[PATCH v2 0/5] stash completion miscellany

Hi all,

This short patch series takes care of a few paper cuts in stash completion. The first patch is a small code cleanup I noticed a while back while working on bfc1b34859 (completion: add stash import, export, 2026-02-07), I think. The next 2 take care of a problem I've been having with Zsh's completion of stashes (cf. Unix & Linux SE [1]).

[1]: https://unix.stackexchange.com/q/807580/301073

Changes in v2:
• Reworded a few commit messages thanks to Patrick
• Clarify the behavior of the final patches with completion for "git
  stash save" (also thanks to Patrick)

The final 2 are not only about completion; I noticed we were special-casing save completion, did some digging, and was a bit confused by the status of "git stash save". So, I figured while I was here I would start a conversation about (a) restoring the git-stash(1) manual to it's "no save" version and (b) ripping out the special case.

These last 2 may be controversial, and I'm not particularly attached to them, so if they need to be dropped I won't really complain. OTOH, what's the point of a deprecated subcommand we still advertise? ;)

Generated-with: git format-patch @{u}.. -o p -v2 --range-diff=@{u}..d1d0bf2d9a7d380d10771b5d1bceb8db91c5f05e --in-reply-to=cover.1791827304.git.ben.knoble@gmail.com --cc='Patrick Steinhardt <ps@pks.im>'

I accidentally left the above line in v1, but I'm considering leaving it in from now on? It's the exact command I run to generate patches; I store it as a "trailer" in the branch description, then run "git generated-with"† which (effectively) does

    eval "$(git bdesc | git interpret-trailers --parse | grep ^Generated-with | cut -d: -f 2-)"

where "bdesc" is an alias for

    git -c core.editor=cat branch --edit-description | git stripspace -s

Anyway, I've been hand-editing them out of cover letters for the last few series, but if it doesn't bother anyone I'll just leave it around. Might be helpful for new folks learning how to format patches?

†: https://github.com/benknoble/Dotfiles/blob/master/links/bin/git-generated-with

[1/5] completion: simplify stash subcommand completion [2/5] Completion: extract common stash listing code [3/5] completion: fix Zsh handling of stash names [4/5] doc: drop usage mentions of "git stash save" [5/5] completion: drop "stash save" completion altogether

 Documentation/git-stash.adoc           |  2 --
 builtin/stash.c                        |  1 -
 contrib/completion/git-completion.bash | 22 +++++++++++++---------
 contrib/completion/git-completion.zsh  |  5 +++++
 4 files changed, 18 insertions(+), 12 deletions(-)

Diff-intervalle contre v1 :
1:  d0e461a14a ! 1:  90d36b6445 completion: simplify stash subcommand completion
    @@ Commit message
         The stash completion helper contains a hard-coded list of commands, but
         git-stash provides a mechanism to list such commands
         (--git-completion-helper). The pattern for using it is wrapped by
    -    __git_resolve_builtins, so use it, bring _git_stash closer in line with
    -    other completion helpers.
    +    __git_resolve_builtins, so use it, bringing _git_stash closer in line
    +    with other completion helpers. As a nice side-benefit, this also adds
    +    "store" subcommand completion, which is missing from the explicit list
    +    of subcommands.
     
    -    Note that we maintain the "save" special case, since it was removed from
    +    Note that we maintain the "save" special case†, since it was removed from
         default completion in 0eb5a4f911 (completion: stop showing 'save' for
    -    stash by default, 2018-04-20). We don't have to do anything special with
    -    the exclude (3rd) argument to __git_resolve_builtins, though, because
    -    save is already marked PARSE_OPT_NOCOMPLETE.
    +    stash by default, 2018-04-20). One might think we need to give "save" to
    +    __git_resolve_builtins' 3rd exclude argument to prevent it from
    +    showing up, but we don't: "save" is already marked PARSE_OPT_NOCOMPLETE.
    +
    +    †We don't complete the "save" subcommand unless at least "sa" has been
    +    typed, but we do complete its options if explicitly typed. With this
    +    change, we will complete "save" if GIT_COMPLETION_SHOW_ALL=1.
     
      ## contrib/completion/git-completion.bash ##
     @@ contrib/completion/git-completion.bash: _git_sparse_checkout ()
2:  6c24a833fc = 2:  abf8efb792 Completion: extract common stash listing code
3:  22283a1d5f ! 3:  f4f6b89ff6 completion: fix Zsh handling of stash names
    @@ Commit message
     
         From here, the list-choices widget (on Ctrl-D by default) will show
         stash@{0} and stash@{1}, but the complete-word widget (Tab) will just
    -    add another brace. Zsh things we're trying to do a brace expansion, I
    +    add another brace. Zsh thinks we're trying to do a brace expansion, I
         think! Interestingly, using menu-complete (Ctrl-N) does cycle through
         matches, since it's taking a slightly different completion path in Zsh.
     
         We might try to fix this by passing surrounding single quotes (using the
    -    -S/-p arguments of compadd, which we can do via __gitcomp_nl's other
    -    parameters), and indeed Zsh will generate
    +    -S/-p arguments of compadd, which we can do from Bash in our code via
    +    __gitcomp_nl's other parameters), and indeed Zsh will generate
     
             git stash show 'stash@{
                             cursor ^
4:  985a14f18e = 4:  3762f9d5bb doc: drop usage mentions of "git stash save"
5:  d1d0bf2d9a ! 5:  0266646fb4 completion: drop "stash save" completion altogether
    @@ Commit message
         further documentation suggesting to use it.
     
         Since we recommend push instead, stop completing for "save" and remove a
    -    special case in completion code.
    +    special case in completion code. It still appears for "git stash <tab>"
    +    when GIT_COMPLETION_SHOW_ALL=1, and when typed explicitly we still
    +    complete options for
    +
    +        git stash save --<tab>
    +
    +    which is helpful for folks with finger-memory for save.
     
      ## contrib/completion/git-completion.bash ##
     @@ contrib/completion/git-completion.bash: _git_stash ()

base-commit: 6de20f6092dcf9bdb1c8efe03db4b70c82b423dd