On Fri, 29 Jan 2010, Mark Lodato wrote: > 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, Yes. > or what the user wishes to do next? Either way, I still am not sure > why this wording is no good. Could please elaborate? First, I'm afraid that "Checking out commit 'foobar'" might be confusing as this may happen through either a remote branch, a tag, or any random commit. It seems to me that "Checking out 'v2.5'" is less confusing than "Checking out commit 'v2.5'". But that's a minor detail and probably a personal preference. > 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. I consider that starting the explanation paragraph with " any commits you make will be lost" is even more unfriendly, and misleading. That is sure to scare people needlessly. > 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. To the contrary: this "detached HEAD" is exactly what you need if you want to relate to any documentation or perform a search for more information. Like it or not, this detached HEAD term is exactly what this Git concept is all about and how it is designated everywhere. The sooner Git users see and learn about it the better. > 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. I think your wording is just too far on the negative side, and makes Git look like an even more difficult tool than it actually is. And you help no one by stating things that are not exactly true even if the truth implies that you need to know what you're doing. The _whole_ and only point of a detached HEAD is actually to be able to make commits even without having to create a new branch first. > 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.) Possibly. I don't like the message proposed in that patch though. Since the warning when actually detaching HEAD is about to become way more prominent, the per-commit warning doesn't have to be that noisy anymore. Nicolas