Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-18 Thread Junio C Hamano
Chris Rorvick writes: > I like Johannes' suggestion of using "" in the --detach case > instead of "" as I think it makes the reason for the > separation more obvious at a glance. Sounds sensible; even though the option does not require its argument to be a branch name, the user does not have a r

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Chris Rorvick
On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano wrote: > Here is a work-in-progress relative to Chris's 83c9989 > (Documentation/git-checkout.txt: document 70c9ac2 behavior, > 2012-12-17). It sounds pretty good to me. > @@ -54,12 +61,17 @@ $ git checkout > that is to say, the branch is not res

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Chris Rorvick
On Mon, Dec 17, 2012 at 2:20 AM, Johannes Sixt wrote: >>> +'git checkout' [--detach] []:: > > The title here is better spelled as two lines: > > 'git checkout' :: > 'git checkout' --detach :: AsciiDoc renders these horizontally separated by a comma when formatted as a man page instead of vertical

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Andrew Ardill
I like these, and I think they are conveying the right amount of information. There is a slight discrepancy between the and versions, where it seems we are assuming that by checking out a commit you are intending to work 'on top of' it. This could be avoided by using the term 'with' in both cases

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Junio C Hamano
Junio C Hamano writes: > I agree with you that sightseeing use case where you do not intend > to make any commit is also important. That is exactly why I said > "further work is done on that branch" not "to that branch" in the > message you are responding to. Here is a work-in-progress relative

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Andrew Ardill
On 18 December 2012 08:59, Junio C Hamano wrote: > Andrew Ardill writes: >> Even if the primary purpose of "git checkout " is to "check >> out the branch so that further work is done on that branch", I don't >> believe that means it has to be stated first. In fact, I would say >> that there are e

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Philip Oakley
From: "Junio C Hamano" Sent: Monday, December 17, 2012 9:13 PM "Philip Oakley" writes: From: "Junio C Hamano" Sent: Monday, December 17, This is to "check out the branch" ;-) ... From a user perspective it's better to refer to the working directory first rather than the internal mechanics

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Junio C Hamano
Andrew Ardill writes: > Even if the primary purpose of "git checkout " is to "check > out the branch so that further work is done on that branch", I don't > believe that means it has to be stated first. In fact, I would say > that there are enough other use cases that the language should be > sli

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Andrew Ardill
On 18 December 2012 08:13, Junio C Hamano wrote: > "Philip Oakley" writes: > >> From: "Junio C Hamano" Sent: Monday, December 17, >>> This is to "check out the branch" ;-) >>> ... >> >> From a user perspective it's better to refer to the working directory >> first rather than the internal mechan

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Junio C Hamano
"Philip Oakley" writes: > From: "Junio C Hamano" Sent: Monday, December 17, >> This is to "check out the branch" ;-) >> ... > > From a user perspective it's better to refer to the working directory > first rather than the internal mechanics. > >Prepare to work on , by updating the files in t

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Philip Oakley
From: "Junio C Hamano" Sent: Monday, December 17, 2012 7:21 AM Chris Rorvick writes: The forms of checkout that do not take a path are lumped together in the DESCRIPTION section, but the description for this group is dominated by explanation of the -b|-B form. Split these apart for more clar

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Junio C Hamano
Johannes Sixt writes: > Am 12/17/2012 9:48, schrieb Junio C Hamano: >> Here is what I tentatively have ... > > Thanks! > >> -'git checkout' [--detach] []:: >> +'git checkout' --detach []:: >> +'git checkout' :: >> >> -Update the index and working tree to reflect the specified >> -commit

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Johannes Sixt
Am 12/17/2012 9:48, schrieb Junio C Hamano: > Here is what I tentatively have ... Thanks! > -'git checkout' [--detach] []:: > +'git checkout' --detach []:: > +'git checkout' :: > > - Update the index and working tree to reflect the specified > - commit and set HEAD to point directly to

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Andrew Ardill
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 thin

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Junio C Hamano
Here is what I tentatively have (so that I do not forget) on 'pu', marked with "(squash???)", as a suggested update on top of Chris's patches. Documentation/git-checkout.txt | 29 + 1 file changed, 21 insertions(+), 8 deletions(-) diff --git c/Documentation/git-checko

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-17 Thread Johannes Sixt
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? >> + >> +Update the index, working tree, and HEAD to reflect the >> +specified bran

Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

2012-12-16 Thread Junio C Hamano
Chris Rorvick writes: > The forms of checkout that do not take a path are lumped together in the > DESCRIPTION section, but the description for this group is dominated by > explanation of the -b|-B form. Split these apart for more clarity. > > Signed-off-by: Chris Rorvick > --- > Documentation