This tool's purpose is to help you determine which revision of a subversion repository contains a change. It does this by employing a binary search. It will manage the current revision of your checkout directory, and narrow in on the target revision, as you give it clues about the current revision such as "before" (this revision is before the one you want) or "after" (this revision is after the one you want).

Start a bisect session with the "start" command. Then, walk the binary tree by using the "before" and "after" commands. When you are done, the tool will tell you the target revision.

The most common usage scenario is finding out which rev a bug was introduced in. For this purpose, some command aliases have been added: if the current revision contains the bug, you can use the "bad" command (meaning, this revision is "after" the change you want to find), otherwise use the "good" command (meaning, this revision is "before" the change you want to find).

All commands should be run from within a subversion checkout directory. After a "svn-bisect start", all subsequent svn-bisect commands need to be run from that same directory.

Inform svn-bisect that the specified revision is *after* the change we're looking for. If you don't specify a revision number, the current revision of the working tree is used. If you are looking for the rev which introduced a bug (which is the common case), the alias "bad" might be easier to remember.

Inform svn-bisect that the specified revision is *before* the change we're looking for. If you don't specify a revision number, the current revision of the working tree is used. If you are looking for the rev which introduced a bug (which is the common case), the alias "good" might be easier to remember.

Tell svn-bisect to skip the specified revision. If no revision is specified, the current version of the working tree is used. Do this if you can't determine whether the current revision is bad or good, if, for instance, some other issue prevents it from compiling successfully.

We run the command and arguments until a conclusion is reached. The command (usually a shell script) tells us about the current revision by way of its return code. The following return codes are handled:

0: This revision is before the change we're looking for
1-124, 126-127: This revision includes the change we're looking for
125: This revision is untestable and should be skipped
any other value: The command failed to run, abort bisection.

In other words, "run" will automatically find the last revision for which the given command returns success. (Keep in mind that in the shell, "0" means "success".)

The normal caveats apply. In particular, if your script makes any changes, don't forget to clean up afterwards.

...Because, you know, no software documentation is complete without a flashy screenshot, these days.

So, lets say you were wondering when the subversion project added the "Last Changed Rev:" line to the output of "svn info". Determining the existence of this change is a straightforward matter of searching for the text string... if a result was found, the current revision is "after", otherwise it was "before". So a bisect looks like this: