Re: [PATCH v3 3/3] Documentation/git-pull: document --[no-]autostash option

[Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>]

Mehul Jain <mehul.jain2029@gmail.com> writes:

> On Thu, Mar 3, 2016 at 10:44 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Should this entry this verbose?
>>
>>  - Is there a non-temporary stash?
>>
>>  - I think "This means that ..." is totally unnecessary.
>>
>>  - It probably makes sense to have "This option is only valid..." as
>>    a separate second paragraph as you did.
>>
>>  - "The default is..." is misleading.  Even if rebase.autostash is
>>    set to false, we won't autostash, but that is different from the
>>    default being "--no-autostash".
>>
>>    Think of "--[no-]autostash" option as *ONE* way to affect the
>>    auto-stashing behaviour, and treat "options" and "behaviours" two
>>    different things.
>>
>> There is no default "option" for this.  It is that "autostash"
>> behaviour defaults to what is given to rebase.autostash if
>> exists, and can be explicitly set by --[no-]autostash if given.
>>
>> But that is the norm for any configuration and option that overrides
>> the configuration, so it probably is a better use of the ink to say
>> something like this perhaps?
>>
>>         --autostash::
>>         --no-autostash::
>>                 Before starting "pull --rebase", create a stash to save
>>                 local modifications, and apply the stash when done (this
>>                 option is only valid when "--rebase" is used).
>
> OK, but according to the definition of --[no-]autostash given in
> git-rebase documentation (https://git-scm.com/docs/git-rebase),
> temporary stash is created.

You shouldn't justify your change by copy-paste from another place. If
the other place is wrong, then replicating it is the worse thing to do
because this would mean we end up with two suboptimal pieces of
documentation instead of one (keep in mind: maintaining stuff is usually
harder than writing it in the first place).

I agree with Junio that "temporary stash" is pleonasm. OTOH, for someone
not familiar with "git stash", the explanation makes no sense anyway.
So, I'd drop the "temporary", and instead add a link to the doc of git
stash. Also, this is not really before starting "pull --rebase" but
after the user calls "pull" and before the actual rebase starst. I'd
write something like this:

	Before starting rebase, stash local modifications away (see
	linkgit:git-stash.txt[1]) if needed, and apply the stash when
	done

(I added "if needed" which makes sense technically since we don't create
an empty stash if not needed)

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/