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

[Junio C Hamano <gitster@pobox.com>]

Johannes Sixt <j.sixt@viscovery.net> writes:

> Am 12/17/2012 9:48, schrieb Junio C Hamano:
>> Here is what I tentatively have ...
>
> Thanks!
>
>> -'git checkout' [--detach] [<commit>]::
>> +'git checkout' --detach [<commit>]::
>> +'git checkout' <commit>::
>>  
>> -	Update the index and working tree to reflect the specified
>> -	commit and set HEAD to point directly to <commit> (see
>> -	"DETACHED HEAD" section.)  Passing `--detach` forces this
>> -	behavior even if <commit> is a branch.
>> +	Prepare to work on building new history on top of <commit>,
>> +	by detaching HEAD at the commit (see "DETACHED HEAD"
>> +	section), and updating the index and the files in the
>> +	working tree.  Local modifications to the files in the
>> +	working tree are kept, so that they can be committed on the
>> +	<branch>.
>
> The last half-sentence should better be removed.

True; we do not have a particular "on the <branch>" in this state.
At least, "on the <branch>" needs to be removed.  But I think we may
want a more different wording here, including the earlier "work on
building new history on top of" part.

The detached HEAD state primarily is a sightseeing mode, where the
user is expected to view but not touch.  Even for experienced users,
commits on a detached HEAD are for keeping snapshots of interim
states during a throw-away experiment, so the purpose of detaching
is not exactly "to work on *building* new history" in the first
place.

Carefree experimentation is encouraged by not forbidding commmits
from this state, with the expectation that:

 (1) if it does not lead to interesting result, another "git
     checkout <branch>" will wipe the throw-away experiment without
     affecting any of your more important branches; and

 (2) an experiment that yielded something useful can be further
     polished on a concrete branch by "git checkout -b <newbranch>".

I think the above discussion on detached HEAD can be added to its
own section.

	Prepare to work on top of <commit>, by detaching HEAD at it
	(see "DETACHED HEAD" section), and updating te index and the
	files in the working tree.  Local modifications to the files
	in the working tree are kept, so that the resulting working
	tree will be the state recorded in the commit plus the local
	modifications.

Or something, perhaps?