From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Wed, 15 Sep 2010 20:47:27 GMT
Subject: Re: [PATCH 6/6] git-reset.txt: make modes description more consistent
Message-ID: <4C9130DF.70303@drmicha.warpmail.net>
In-Reply-To: <7vd3sh9n7l.fsf@alter.siamese.dyndns.org>

Thanks for all your hints and thoughts. I'll be sending a v2 in a
minute. There's just one point where I chose not to follow completely
for now:

Junio C Hamano venit, vidit, dixit 14.09.2010 02:35:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
[snip]
>> @@ -57,22 +58,30 @@ linkgit:git-add[1]).
>>  	been updated. This is the default action.
>>  
>>  --hard::
>> -	Matches the working tree and index to that of the tree being
>> -	switched to. Any changes to tracked files in the working tree
>> -	since <commit> are lost.
>> +	Resets the index and working tree. Any changes to tracked files in the
>> +	working tree since <commit> are lost.
> 
> Explaining what "reset" does using the undefined word "reset" smells
> somewhat wrong.  Not that "matches" is any better, but at least the
> original says "to that of the tree", which you seem to have lost, so there
> is no indication what they are reset _to_.  I don't think the above is a
> good change for this reason.

The idea was to define "reset" once (in the paragraph right before the
list of modes) and then use it without repeating that. I tried to make
this a bit clearer now by emphasising the term "reset" more in the
leading paragraph.

[snip]
> It may be just me, but "unstaged" sounds as if you once have staged and
> then changed your mind and took it back.  "... which have changes that
> haven't been added" might be clearer.

We use "unstaged" in the meaning of "not staged/added yet" in other
places, as well - but in surprisingly few I have to admit! I went with
your version here.

Michael