On Fri, Jan 29, 2010 at 10:11 PM, Nicolas Pitre <nico@xxxxxxxxxxx> wrote:
> On Fri, 29 Jan 2010, Mark Lodato wrote:
>> On Fri, Jan 29, 2010 at 8:22 PM, Nicolas Pitre <nico@xxxxxxxxxxx> wrote:
>> > On Fri, 29 Jan 2010, Mark Lodato wrote:
>> >
>> >> Still, I find it slightly confusing and unfriendly. How about the following?
>> >
>> >> Checking out commit 'master^0'.
>> >>
>> >> Since this is not a local branch head, any commits you make will be lost
>> >> when you check out another branch or commit. (In git terminology, HEAD
>> >> is detached.) If you just wish to look at files without committing,
>> >> this is fine. If you wish to make commits and retain them, you may
>> >> create a new branch by running:
>> >>
>> >> git checkout -b <new_branch_name>
>> >
>> > This gives the impression that any commit you make on a detached HEAD
>> > are going to be lost, unless you create a new branch first.
>>
>> What about "...you may want to create..."? This does not imply that
>> creating a new branch now is the *only* way, just the most likely. If
>> a user knows another way, that user probably does not need this
>> warning in the first place.
>
> Still, you don't know what way the unsuspected user will take to get
> there.
Sorry, I don't understand. What do you mean by "take to get there"?
Are you referring to how the user arrived in this detached HEAD state,
or what the user wishes to do next? Either way, I still am not sure
why this wording is no good. Could please elaborate?
> Do you still have a problem with the latest version of the text from
> Junio? Looks like you based your modification on an earlier version.
Yes, I do. I thought his earlier version was more clear. Particularly:
Note: 'master^0' isn't a local branch head;
This isn't very friendly. It sounds like an admonition. Rather, I
suggest that the first sentence be similar to, but distinct from,
"Switched to branch foo," to inform the user that they did something
different, which may or may not be intentional.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by checking out another branch.
First, we shouldn't start off with the term "detached HEAD". I used a
parenthetical comment to mention it, in case the user wants to look it
up or refer to this state. Otherwise, the term conveys no meaning,
unless one understand enough about git to not need this advice.
Second, this advice should be a warning that commits may be lost
unless one knows what one is doing. Saying "you can discard commits"
makes it sound like a feature! Sure, that may be so for advanced
users, but for beginners (for whom this advice is intended), this is a
common trap. I tried to word the advice so that the users will know
that they should not commit without first creating a branch (or
knowing what they're doing), but that if they don't commit, there's no
problem. The wording quoted above does not convey this meaning to me.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b <new_branch_name>
I basically retained this, with rewording.
This discussion brings up another good point: The main worry about a
detached head is losing commits. Back in 2008, it was suggested to
have a warning when committing on a detached HEAD:
http://kerneltrap.org/mailarchive/git/2008/9/2/3169744
This was before the advice system, so folks complained about it
getting in the way, and it was never implemented. Since we now have a
way to easily turn off the warning, perhaps we should bring this topic
up again (probably as a separate thread.)
--
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