"man git-stash" explanation of "--include-untracked" and "--all" seems ambiguous

> 
>   from the man page:
> 
> "If the --include-untracked option is used, all untracked files are
> also stashed and then cleaned up with git clean, leaving the working
> directory in a very clean state. If the --all option is used instead
>                                                              ^^^^^^^
> then the ignored files are stashed and cleaned in addition to the
> untracked files."
> 
>   the use of the word "instead" suggests you can use one of those
> options, or the other, but not both at the same time. but it seems you
> can combine them, so that paragraph seems a bit misleading, no?

> rday
> 
> -- 
> 
> ========================================================================
> Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                         http://crashcourse.ca
> 
> Twitter:                                       http://twitter.com/rpjday
> LinkedIn:                               http://ca.linkedin.com/in/rpjday
> ========================================================================
> 

> On 09/29, Robert P. J. Day wrote:
> >
> >   from the man page:
> >
> > "If the --include-untracked option is used, all untracked files
> > are also stashed and then cleaned up with git clean, leaving the
> > working directory in a very clean state. If the --all option is
> > used instead
> >
> > ^^^^^^^ then the ignored files are stashed and cleaned in addition
> > to the untracked files."
> >
> >   the use of the word "instead" suggests you can use one of those
> > options, or the other, but not both at the same time. but it seems
> > you can combine them, so that paragraph seems a bit misleading,
> > no?
>
> Looking at the code, really only one (the last one that's specified
> on the command line) is respected, so I think the man page is
> correct. This happens silently, where I guess your impression that
> it's possible to combine them comes from.
>
> This is fine when --include-untracked is specified first, as --all
> implies --include-untracked, but I guess the behaviour could be a
> bit surprising if --all is specified first and --include-untracked
> later on the command line.
>
> Changing this could possibly break someone that just adds parameters
> to their 'git stash' invocation, but I'm tempted to say allowing
> both at once is a bug, and change it to make git die when both are
> specified.  Do you have any inserest in submitting a patch that
> fixes this? :)

> This is fine when --include-untracked is specified first, as --all
> implies --include-untracked, but I guess the behaviour could be a bit
> surprising if --all is specified first and --include-untracked later
> on the command line.
>
> Changing this could possibly break someone that just adds parameters
> to their 'git stash' invocation, but I'm tempted to say allowing both
> at once is a bug, and change it to make git die when both are
> specified.

> Thomas Gummerer <t.gummerer@gmail.com> writes:
>
> > This is fine when --include-untracked is specified first, as --all
> > implies --include-untracked, but I guess the behaviour could be a
> > bit surprising if --all is specified first and --include-untracked
> > later on the command line.
> >
> > Changing this could possibly break someone that just adds
> > parameters to their 'git stash' invocation, but I'm tempted to say
> > allowing both at once is a bug, and change it to make git die when
> > both are specified.
>
> I am on the fence.
>
> If this were --include=untracked vs --include=all, then I'd say your
> suggestion will violate the usual expectation of "on the command
> line, last one wins", but "--include-untracked" and "--all" are
> spelled very differently, and may not look all that related to a
> casual reader, so the expectation for "the last one wins" might be
> weaker than usual.
>
> But once we start complaining to a command line that has both,
> saying they are mutually exclusive, people will realize that they
> are very much closely related options, even though spelled quite
> differently.  And at that point, they will find it very unreasonable
> that we do not follow the usual "the last one wins" rule but error
> out X-<.
>
> If I really cared deeply about these two options [*1*], I would
> think that the ideal longer term direction would be to introduce
> --include={untracked,all-crufts} to replace and deprecate the
> current two options.  And then we make sure --include=* forms follow
> the usual "last one wins" rule.
>
>
> [Footnote]
>
> *1* I personally don't, but that does not mean I will block efforts
>     by others who do to make this part of the system better.

>> If this were --include=untracked vs --include=all, then I'd say your
>> suggestion will violate the usual expectation of "on the command
>> line, last one wins", but "--include-untracked" and "--all" are
>> spelled very differently, and may not look all that related to a
>> casual reader, so the expectation for "the last one wins" might be
>> weaker than usual.
>>
>> But once we start complaining to a command line that has both,
>> saying they are mutually exclusive, people will realize that they
>> are very much closely related options, even though spelled quite
>> differently.  And at that point, they will find it very unreasonable
>> that we do not follow the usual "the last one wins" rule but error
>> out X-<.
>>
>> If I really cared deeply about these two options [*1*], I would
>> think that the ideal longer term direction would be to introduce
>> --include={untracked,all-crufts} to replace and deprecate the
>> current two options.  And then we make sure --include=* forms follow
>> the usual "last one wins" rule.
>>
>>
>> [Footnote]
>>
>> *1* I personally don't, but that does not mean I will block efforts
>>     by others who do to make this part of the system better.
>
>   since i'm the one who tripped over this pedantic nitpickery, i'm
> willing to take a shot at patching it, as long as there's consensus
> from those *way* higher up the food chain as to what that patch should
> look like.