Johannes Sixt <j.sixt@xxxxxxxxxxxxx> 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?
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html