How to bisect to find what broke a game

Git bisection, building each time

When something breaks, it makes things a lot easier to debug to find the exact commit that broke it. It can be fixed significantly faster knowing this.

This can also be used to find which commit fixed an issue, by pretending it working is "broken" and it not working is "fixed."

Bisecting uses the famous "hot/cold" method of guessing to find it in the least steps possible. It's only possible to use this if you actually have the game and a compiler. If you don't have a compiler, you'll need to test revisions manually (which is less accurate and will likely take more steps.)

It's pretty easy. Just start out in the directory with PPSSPP, and type:

git bisect start

Now compile, and test to see if it works. Assuming it doesn't work, you'll type:

git bisect bad

Now you need a new reference point. If you know the last revision that worked, use git checkout <version>. For example, git checkout v0.9.1-134-g554ca84. If you don't know the version, you can [browse recent commits] (https://github.com/hrydgard/ppsspp/commits/master) and try one a few back, or just go 100 commits back using git checkout HEAD~100.

Remember, after git checkout, you also want to run git submodule update. This will update native to match your checked out version.

For large jumps, you may want to close Visual Studio before the git checkout ... and git submodule update commands, and reopen it afterward. Visual Studio reloads projects very slowly when they change, and restarting it is actually faster.

Now again, compile and test. It should work this time so you'll say:

git bisect good

If it doesn't work, you'll have to go back to the previous step, first tell git:

git bisect bad

And then go back to the previous step and checkout / submodule update an older version until you find the working one. You can try going back farther, like 500 commits or 1000. Bisecting 1000 commits is still not a ton of steps, don't worry.

From here on it automatically picks a new revision (using the most optimal choices it can) to test next. Just keep answering it by compiling, and then using git bisect good, or git bisect bad. Don't forget to git submodule update before compiling each time.

If you run into a revision that can't be compiled, you can just skip it:

git bisect skip

In the worst case, if you have to skip a lot, git will give you a range of commits that could have been the cause. If you don't have to skip much, it should pinpoint the exact one.

Then just update the issue or forum post with what git tells you.

To return to the current version, you can exit bisect with the command

git bisect reset

APK bisection

If you've downloaded a bunch of APK from https://buildbot.orphis.net/ppsspp/ and want to bisect, it's a pain manually installing them one by one. Instead, do it from the command line:

adb uninstall org.ppsspp.ppsspp
adb install ppsspp-v1.7.5-494-g50de04a29-android
adb shell am start -a android.intent.action.MAIN -n org.ppsspp.ppsspp/.PpssppActivity

Rinse and repeat, manually keeping track of where you are in the bisection. Taking notes is useful.