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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html