From: Jonathan Nieder Date: Thu, 06 Jan 2011 22:52:22 GMT Subject: [PATCH/RFC] Documentation/checkout: explain behavior wrt local changes Message-ID: <20110106225222.GA15900@burratino> In-Reply-To: <20110106173522.GB11346@burratino> 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 --" with "git checkout -- " and ends up with a muddle (as Jeff noticed). In particular, the text does not make it obvious that the "git checkout --" form does not clobber local changes relative to the HEAD commit in the worktree and index. Reported-by: r.ductor Helped-by: Jeff King Signed-off-by: Jonathan Nieder --- 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' []:: 'git checkout' -b|-B []:: - 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