Re: git checkout branch behaves differently from what specified in man page

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

r. ductor wrote[1]:

>  git checkout [<branch>], git checkout -b <new branch> [<start point>] 
>	This form switches branches by updating the index, working tree,
>	and HEAD to reflect the specified branch. "
>
> The key is the meaning of "to reflect": a normal (?) human being
> like me understands that git  checkout branch will reset the
> contents of working directory, and index exactly equal to that of
> the head of the branch.  As you might know this is not true (see
> example below).
[example with both unregistered and staged local modifications]

Yes, I agree that this could be a lot clearer.  For reference, here's
the current description section:

 Updates files in the working tree to match the version in the index
 or the specified tree. If no paths are given, git checkout will also
 update HEAD to set the specified branch as the current branch.

 git checkout [<branch>], git checkout -b|-B <new_branch> [<start point>]
	This form switches branches by updating the index, working tree,
	and HEAD to reflect the specified branch.

	If -b is given,
[... description of -b and -B ...]

 git checkout [--patch] [<tree-ish>] [--] <pathspec>...
	When <paths> or --patch are given, git checkout does not switch
	branches. It updates the named paths in the working tree from
	the index file or from a named <tree-ish> (most often a commit).
	In this case, the -b and --track options are meaningless and
	giving either of them results in an error. The <tree-ish>
	argument can be used to specify a specific tree-ish (i.e.
	commit, tag or tree) to update the index for the given paths
	before updating the working tree.

	The index may contain unmerged entries because of a previous
	failed merge.
[... more details about the unmerged entries case ...]

Proposed clearer text would be welcome, especially if in the form of
a patch to Documentation/git-checkout.txt (see Documentation/SubmittingPatches).

Currently I think the examples section explains it better.  The
details are something like this:

 - git checkout <branch> --

	tries to change the current branch to <branch>, dragging other
	state kicking and screaming along with it.

	- if a file does _not_ differ between the current commit and
	  <branch>, it does not need to be touched.  Any local changes
	  in that file will be preserved.

	- if a file that _does_ differ between the current commit and
	  <branch> has local changes, git gives up --- the operation is
	  cancelled and all state is preserved.
	  This behavior can be tweaked with the --merge option.

 - git checkout <tree> -- <path specifiers>

	keeping the current branch the same, grabs some files from <tree>
	to replace the current versions in the index and work tree

	- no matter what, the local state of the specified paths is
	  forgotten and both the index and worktree made to match <tree>

	- paths not specified are left alone.

If you just want to reset the worktree and index to match some
branch, then you can use

	git reset --hard <branch>

or

	git checkout <tree> -- .

.  The former even forgets what branch you were on (well, it is
remembered in the reflog).  The latter adopts the content of <tree>
as content registered for the next commit on the current branch.

Hope that helps,
Jonathan

[1] http://bugs.debian.org/609128