Re: Newbie grief

[Illia Bobyr <ibobyr@blizzard.com>]

On 5/4/2012 9:46 AM, Nathan Gray wrote:
> 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.