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

[Junio C Hamano <gitster@pobox.com>]

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

> Signed-off-by: Mehul Jain <mehul.jain2029@gmail.com>
> ---
>  Documentation/git-pull.txt | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
>
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index a62a2a6..a593972 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -128,6 +128,21 @@ unless you have read linkgit:git-rebase[1] carefully.
>  --no-rebase::
>  	Override earlier --rebase.
>  
> +--autostash::
> +--no-autostash::
> +	Automatically create a temporary stash before the operation
> +	begins, and apply it after the operation ends. This means
> +	that you can run rebase on a dirty worktree.
> ++
> +This option is only valid when '--rebase' option is used.
> ++
> +The default is --no-autostash, unless rebase.autoStash configuration 
> +is set.
> ++
> +[NOTE]
> +Use with care: the final stash application after a successful
> +rebase might result in non-trivial conflicts.
> +

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).
        +
        '--no-autostash' is useful to override the 'rebase.autoStash'
        configuration variable (see linkgit:git-config[1]).

By the way, some other patches in this series say --noautostash
without a dash after --no, which you would want to correct.

Thanks.