Jonathan Nieder wrote: > Proposed clearer text would be welcome, especially if in the form of > a patch to Documentation/git-checkout.txt (see Documentation/SubmittingPatches). Like this, maybe? -- 8< -- Subject: Documentation/checkout: explain behavior wrt local changes The current start of the description to "git checkout" tries to combine an explanation of "git checkout <branch> --" with "git checkout -- <paths>" and ends up with a muddle (as Jeff noticed). In particular, the text does not make it obvious that the "git checkout <branch> --" form does not clobber local changes relative to the HEAD commit in the worktree and index. Reported-by: r.ductor <r.ductor@xxxxxxxxx> Helped-by: Jeff King <peff@xxxxxxxx> Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx> --- I somehow suspect that a mention of --merge would make this clearer but good words for it aren't coming at the moment. Improvements welcome. Documentation/git-checkout.txt | 14 ++++++++------ 1 files changed, 8 insertions(+), 6 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 22d3611..cfb71a8 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -15,16 +15,18 @@ SYNOPSIS DESCRIPTION ----------- -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. +There are two different modes -- one to switch branches and one to +make some paths in the work tree match the index or specified tree. '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. + This form switches branches by changing `HEAD` and updating the + tracked files to the specified branch. 'git checkout' will + stop without doing anything if local changes overlap with + changes to the tracked files. (Any local changes that do not + overlap with changes from `HEAD` to the specified branch will + be preserved.) + If `-b` is given, a new branch is created as if linkgit:git-branch[1] were called and then checked out; in this case you can -- 1.7.4.rc1 -- 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