[PATCH/RFC] Documentation/checkout: explain behavior wrt local changes
- From
Jonathan Nieder <jrnieder@gmail.com>
- Date
- Jan 6, 2011, 22:52 UTC
- 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 <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@gmail.com> Helped-by: Jeff King <peff@peff.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- 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