Re: Newbie grief
- From
- Illia Bobyr <ibobyr@blizzard.com>
- Date
- May 4, 2012, 17:17 UTC
- Message-ID
- <4FA40F2A.7070109@blizzard.com>
- In-Reply-To
- <CA+7g9Jx20q6C8JqrcrmbWhYNH1K35Gwp_BAckjM=8qg1kMwU4Q@mail.gmail.com>
On 5/4/2012 9:46 AM, Nathan Gray wrote:
Show 51 quoted lines
> On Fri, May 4, 2012 at 3:09 AM, Carlos Martín Nieto<cmn@elego.de> wrote: >> On Thu, 2012-05-03 at 22:25 -0700, Junio C Hamano wrote: >>> Michael Witten<mfwitten@gmail.com> writes: >>> >>>> As for a seemingly conservative suggestion, how about using a little >>>> more structural white space: >>>> >>>> To $uri_for_central_repo >>>> ! [rejected] HEAD -> feature_0 (non-fast-forward) >>>> >>>> error: failed to push some refs to '$uri_for_central_repo' >>>> >>>> To prevent you from losing history, non-fast-forward updates were rejected >>>> Merge the remote changes (e.g. 'git pull') before pushing again. See the >>>> 'Note about fast-forwards' section of 'git push --help' for details. >>>> >> Most of the first sentence repeats what we can see above. Restating that >> non-ff updates were rejected doesn't add information and doesn't help >> people who don't already know what a non-ff update is, so it's either >> redundant or not helpful[0]. So lets see if we can come up with a >> friendlier way of saying it. Maybe something like: >> >> To $uri_for_central_repo >> ! [rejected] HEAD -> feature_0 (non-fast-forward) >> >> error: failed to push some refs to '$uri_for_central_repo' >> >> Some updates which might rewrite history and lose someone else's >> changes were rejected. Merge those changes (e.g. 'git pull') to >> incorporate that history. See the 'Note about fast-forwards' section >> of 'git push --help' for details. >> >> It may be a bit longer, but if you don't know what a non-ff is or why >> it's a problem, this text should help you a lot more than the previous >> one did. Not reading the documentation (specially when the error message >> points you to a specific section for a longer explanation) is still no >> excuse for not known what's going on, but if you've been working on your >> own for a while, you might have forgotten what this is all about.[1] > The whitespace that Michael introduced is a big help, for starters, > and this rewording is also a nice step forward. I'm still not > thrilled about the "rewriting history" verbiage -- that makes it sound > like the user did something super risky and was rescued by the system. > Here's my suggestion for replacing the last paragraph: > > Some of your branches are out of date. Merge the remote changes > (e.g. 'git pull') then try again. > > It's short and easy to scan. It has no git-specific jargon that new > users would be unfamiliar with. There's no reference to fast-forward > updates so no need to refer the user to that help section. What do > you think?
Not everybody is a new user :) Throwing away a precise explanation for the purpose of avoiding a possible confusion for someone who either just started (and will have to learn the terms anyway) or for someone who does not really care to learn is a decision that I would weight very carefully.
Just as I side note, I lead a team of an ordinary developers through a transition from CVS to Git and there were pretty much fine with the fact that there are pieces in such a complex system as Git that they do not understand immediately. Over a couple of month everyone who cared or required this knowledge knew what a fast-forward is. And people who did not care just learn to do git pull as the message suggests.
I think that a reference to the documentation is very nice. I remember that this kind of references allowed me to learn Git gradually as I was facing different usage scenarios instead of reading the whole documentation for all the tools.