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

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 17, 2012, 19:12 UTC
Message-ID: <7vbodsmr1r.fsf@alter.siamese.dyndns.org>
In-Reply-To: <50CEDF0A.7040603@viscovery.net>

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

Show 21 quoted lines

> 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?