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

Mehul Jain [off-list ref] writes:

On Thu, Mar 3, 2016 at 10:44 PM, Junio C Hamano [off-list ref] wrote:

quoted

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/