From: Andrew Ardill Date: Mon, 17 Dec 2012 08:53:19 GMT Subject: Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage Message-ID: In-Reply-To: <50CED5D4.5040705@viscovery.net> Regards, Andrew Ardill On 17 December 2012 19:20, Johannes Sixt wrote: > Am 12/17/2012 8:21, schrieb Junio C Hamano: >> Chris Rorvick writes: >>> 'git checkout' []:: > > Is really optional in this form? > > BTW, what does plain 'git checkout' do? Just report ahead/behind information? I think it defaults to either HEAD or the current branch, which shows uncommitted changes and relationship to upstream. >>> + >>> + Update the index, working tree, and HEAD to reflect the >>> + specified branch. > ... >>> +'git checkout' [--detach] []:: > > The title here is better spelled as two lines: > > 'git checkout' :: > 'git checkout' --detach :: > > I don't think that or should be indicated as optional here. doing 'git checkout --detach' will detach from the current branch if you have one, but maybe listing as optional would work in that case? Here is my suggestion, differing from what Junio put forward primarily by first indicating that a checkout is a 'switch' to a different branch or commit. This makes sense to me, and is used elsewhere in the documentation, so I thought it might make sense here too. -->8-- From: Andrew Ardill Date: Mon, 17 Dec 2012 18:53:41 +1100 Subject: [PATCH] Documentation/git-checkout.txt: Use consistent terminology git checkout is described as 'switching' branches in places. Use this terminology more consistently. Expand on the purpose of switching to a branch or commit, which is typically to prepare to build history on top of that branch or commit. Signed-off-by: Andrew Ardill --- Documentation/git-checkout.txt | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index db89cf7..e6db14f 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -23,8 +23,11 @@ branch. 'git checkout' []:: - Update the index, working tree, and HEAD to reflect the - specified branch. + Switch to the specified . Prepares for building new + history on , by updating the index and the files in the + working tree, and by pointing HEAD at the branch. Local + modifications to the files in the working tree are kept, so that + they can be committed on the . + If is not found but there does exist a tracking branch in exactly one remote (call it ) with a matching name, treat as @@ -56,10 +59,13 @@ successful. 'git checkout' [--detach] []:: - Update the index and working tree to reflect the specified - commit and set HEAD to point directly to (see - "DETACHED HEAD" section.) Passing `--detach` forces this - behavior even if is a branch. + Switch to the specified . Prepares for building new + history on top of , by updating the index and the files + in the working tree, and by pointing HEAD at . Local + modifications to the files in the working tree are kept, so that + they can be committed on top of . Passing `--detach` + forces HEAD to point directly at even if is a + branch (see "DETACHED HEAD" section.) 'git checkout' [-p|--patch] [] [--] ...:: --