Search code examples
gitgit-bisect

What does `git bisect start` really do?


Please understand, I'm not asking how to use git bisect start. There is plenty documentation telling me to start a bisect session with a git bisect start command. What seems to be missing is any explanation of what doing this actually does.

To be clear, I know git bisect start has options that can be passed to it that do things. I'm only asking about what it does when you follow examples that pass nothing else.

My overriding question is about what state or mode git bisect start puts us in. Here are some other questions meant only to illustrate the nature of this one question:

  • What state actually changes because of the git bisect start command? Is there some query I could run that would tell me if we're in that state?
  • Why is this state necessary? Is it even needed?
  • What commands are not available while in this state? Which commands are only available when in it?
  • The git bisect ceremony seems to end with git bisect reset. Does that take us out of this state?
  • This tells me that rm -v .git/BISECT_* cleans up the files bisect creates. Are those files the only thing putting git in this bisect state?

All the documentation I'm finding just tells me to start bisect with git bisect start without telling me why.


Solution

  • git bisect start puts Git into bisect mode. It keeps track of this internally by creating the files

    .git/BISECT_LOG
    .git/BISECT_NAMES
    .git/BISECT_START
    

    During the course of bisecting, further scratch files can be created:

    .git/BISECT_TERMS
    .git/BISECT_ANCESTORS_OK
    

    The presence of these files tells Git, or you, or git status, or an external tool, such as your terminal prompt, that you are in bisect mode, and gives meaning to any further git bisect commands you may care to give.

    Indeed, you can in theory exit bisect mode, kaboom, with no other changes, just by deleting all those files. But it is more usual, and a much better idea, to have Git do that for you, by saying git bisect reset, which also by default returns you to the commit you were on when you started.