Re: [PATCH v2] stash: expose untracked modes in create

From: 重田一聖 <kazumasa.shigeta@kanamei.com>
Date: Oct 5, 2026, 05:55 UTC
Message-ID: <CANUHOw3gynMRGN7A-wOnL3PQtgFbMtsB2gyZxaq+0Z5bHp-H8A@mail.gmail.com>
In-Reply-To: <CANUHOw1eO0HNjU+-PYNDOz9kHhBZYYfhiKJSX4082YSC1NKxww@mail.gmail.com>

Hi Junio,

> Why are we singling out only these two?

After looking more carefully at both the history and the current stash code, I don't think there is a good reason to single out only `-u` and `-a`.

Your question made me realize that I had focused too narrowly on the untracked modes. The larger issue is not simply that `do_create_stash()` has capabilities that `git stash create` does not expose. The existing `git stash create <message>` grammar is a long-standing compatibility contract that has been deliberately preserved.

Making more of those capabilities available through `create` would therefore mean either changing that contract or designing around it. That is a much larger interface decision than I appreciated when I sent the patch.

I moved too quickly here and sent the patch before understanding that constraint well enough. I am sorry about that. Thanks to you, Phillip, Patrick, and everyone else who took the time to review it. I should have investigated this compatibility history first.

Even so, I still think it would be useful to make more of the existing `do_create_stash()` capabilities available through the public command line.

So I no longer think the question is simply which additional options `stash create` should expose. The broader question is how to make those capabilities available through a public interface while dealing appropriately with the existing `git stash create <message>` compatibility contract.

From that perspective, I can see three possible directions.

1. Keep extending `stash create`.

   We could expose more of the existing `do_create_stash()`
   functionality through `stash create`, following the conventions of
   `stash push` for the creation-related options they have in common.

   This seems implementable, but even with
   `PARSE_OPT_STOP_AT_NON_OPTION` it would change the handling of
   messages that begin with an option-like argument. Those would need
   explicit disambiguation, such as `--`.

   There is also the pathspec question. If positional arguments
   continue to be joined to form the message, pathspecs need some other
   way to be distinguished from that message.

2. Add a new stash subcommand for the creation functionality.

   This would leave the existing `stash create <message>` contract
   unchanged. Because the new command would not inherit `create`'s
   positional message grammar, its creation-related options and
   pathspec handling could follow conventions similar to `stash push`.

   This preserves the existing `create` grammar while avoiding the need
   to fit additional creation capabilities into it. The trade-off is
   adding another public stash subcommand and its long-term maintenance
   cost.

3. Add something like `--create-only` to `git stash push`.

   This would reuse the existing `push` option grammar without adding
   another subcommand.

   I also read the 2019 discussion around `git stash push --snapshot`.
   One concern there was that approximately the same end state could
   already be obtained with `git stash push && git stash apply`.

   I do not think that particular concern carries over directly here.
   `git stash create` already stops at object creation, but its public
   interface does not expose more of the creation capabilities already
   available in `do_create_stash()`. There is currently no public stash
   command that exposes those capabilities while retaining that
   create-only boundary.

   That does not mean a similar result cannot be constructed by other
   means. The missing piece is a public interface to the existing stash
   creation machinery at that boundary.

   Even so, there is still the separate question of whether `push` is
   the right place for a creation-only operation in the first place.
   The push-specific work around `do_create_stash()` would also need to
   be separated carefully.

All three seem substantially broader than the original `-u` / `-a` patch.

If this is worth pursuing further, which of these directions seems the most plausible? Also, is this the right thread to continue that design discussion, or would it be better to discuss it separately?

Thanks again for the guidance, Kazumasa Shigeta

On Fri, 2 Oct 2026 05:04:26 -0400, "重田一聖" <kazumasa.shigeta@kanamei.com> wrote:

Show 138 quoted lines

> Hi Junio,
>
> > we would prefer to hear what the user visible implication of
> > "passing 0" is more than what mechanically is happening inside a
> > program.
>
> The user-visible effect is that stash create cannot currently include
> untracked or ignored files in the stash entry. If those are the only
> changes, it creates no entry at all, while stash push and save can
> include them with -u or -a as appropriate. I should have described that
> difference directly instead of starting from the include_untracked
> implementation detail.
>
> > ... was what you wanted to say, but I am not sure.
>
> Yes, exactly. I'll explain the backward-compatibility reason rather
> than the mechanics of parse_options().
>
> > You already said that with "does not update, reset, or clean".
>
> I'll drop that paragraph.
>
> > if you did not make a breaking change to the established convention,
> > is it worth saying?
>
> I don't think it adds anything here. I'll remove the exit-status
> discussion from the commit message as well.
>
> > adding tests for comprehensive coverage is not something to boast
> > about. Is it worth saying?
>
> I'll remove the test details from the commit message.
>
> > Why are we singling out only these two?
>
> I started by looking at the missing -u and -a support in create, and I
> think that led me to focus too narrowly on those two when considering
> the scope. I need to think more about whether this patch should remain
> limited to those two.
>
> Thanks,
> Kazumasa Shigeta
>
> On Thu, 01 Oct 2026 10:03:13 -0700, Junio C Hamano <gitster@pobox.com> wrote:
> > Kazumasa Shigeta <kazumasa.shigeta@kanamei.com> writes:
> >
> > > `git stash create` always passes zero for the include_untracked parameter
> > > of do_create_stash(), even though that helper already supports untracked
> > > and ignored files and stash push/save expose those modes as
> > > -u/--include-untracked and -a/--all.
> >
> > There may be no lies in what the above says, but we would prefer to
> > hear what the user visible implication of "passing 0" is more than
> > what mechanically is happening inside a program. For example:
> >
> > "git stash create", "git stash push", and "git stash save" are
> > commands that create a new stash entry. The latter two are also
> > responsible for storing the resulting stash entry to the reflog
> > of the "refs/stash" ref, but have options to control what is
> > included in the stash entry. Among these options, "create" only
> > supports the equivalent of "-m <message." to record in the stash
> > entry. Most notably, "-u" and "-a" options are missing.
> >
> > > Teach create to accept the same options and pass the existing mode
> > > through. Unlike push/save, create continues to only create objects: it
> > > does not update refs/stash, reset the index, or clean the working tree.
> >
> > Sure. It is a very concise and good description of what we want to
> > do.
> >
> > > Use parse_options() for the new options and stop parsing at the first
> > > non-option message word. This keeps option-like tokens after the message
> > > as message text, while leading option-like arguments now follow Git's
> > > normal option parsing. In particular, unknown or malformed leading
> > > options are rejected instead of silently becoming a message, short
> > > options may be combined, and `--` can be used when a message itself
> > > begins with a dash.
> >
> > Why do we need to go into such a detail in the log message? What is
> > the above paragraph designed to convey to the reader? Again, it may
> > not be telling any lies, but it misses the point by being inconsiderate
> > to your readers. What you need to tell them is _WHY_ you chose to
> > use parse_options() in such a way. What were you trying to achieve?
> >
> > I am guessing that something along this line ...
> >
> > "git stash create" traditionally treated the rest of the command
> > line as a message. For example,
> >
> > $ git stash create adding -u option
> >
> > has always been a request to create a stash entry with the
> > string "adding -u option" as its message. We should not make it
> > trigger the "-u" (include untracked) behavior for backward
> > compatibility, by using parse_options() with stop-at-the-non-option
> > mode to forbid it from reordering the command line arguments.
> >
> > ... was what you wanted to say, but I am not sure.
> >
> > How much of all these verbiage was written by AI by the way? You'd
> > need to spend effort to make it readable to humans.
> >
> > > Keep create's existing no-change behavior: detect the usual no-change
> > > case before do_create_stash() refreshes and writes the index, and return
> > > success without printing an object name. If do_create_stash() still
> > > reports its internal "nothing to create" result, map that to create's
> > > public success status.
> >
> > You already said that with "does not update, reset, or clean".
> >
> > > This follows the stash subcommand exit-status convention established by
> > > 786fc390465f (stash: reserve exit status 1 for conflicts, 2026-09-03):
> > > subcommands return 0 on success, negative values on failure, and status 1
> > > when applying a stash results in conflicts. cmd_stash() maps negative
> > > subcommand failures to 128.
> >
> > Again, there may not be lies in here, but if you did not make a
> > breaking change to the established convention, is it worth saying?
> >
> > > 9ca6326dff29 (stash: refactor stash_create, 2017-02-19) added the
> > > internal include-untracked path while intentionally leaving the user
> > > interface for "git stash create" unchanged. Reuse that machinery and
> > > the existing INCLUDE_ALL_FILES mode rather than adding a separate stash
> > > creation path.
> > >
> > > Add coverage for short and long aliases, combined short options, the
> > > untracked/ignored boundary including an ignored-only worktree, option
> > > parsing and dash-leading messages, no-change behavior, and preservation
> > > of refs/stash, the index state, and the working tree.
> >
> > Again, adding tests for comprehensive coverage is not something to
> > boast about. Is it worth saying?
> >
> > Aren't -p/-S/-k/-q and pathspec support all about the creating half
> > of "git stash push" that are not available to "git stash create",
> > not just "-u" and "-a"? Why are we singling out only these two? It
> > may be more worthwhile to explain the rationale behind such a design
> > decision.