[RFC] git stash: add porcelain for sharing stashes through remotes

[RFC] git stash: add porcelain for sharing stashes through remotes

[Hanan Arshad]

Hi,

I'd like to propose adding a small porcelain workflow for sharing
stashes through a Git remote.

git stash export and git stash import already provide a transportable
representation of stashes. I tested the following workflow using
existing commands:

Alice:
  git stash export --print stash@{0}
  git push origin <export-tip>:refs/stashes/alice/wip

Bob:
  git fetch origin refs/stashes/alice/wip:refs/shared-stashes/origin/alice/wip
  git stash import refs/shared-stashes/origin/alice/wip
The imported stash is a normal local stash and retains the original
stash object ID. Removing the remote ref afterward does not affect
Bob's imported stash.

I'd like to add porcelain around this existing mechanism for four operations:

1- publish a selected stash to a remote
2- list available shared stashes
3- get a shared stash as a normal local stash
4- remove a shared stash from the remote

This would not introduce a new stash object format, server-side
service, or synchronization model. It would essentially compose the
existing export/import mechanism with normal push/fetch operations.
Before working on an implementation, I'd appreciate feedback on a few
design points:
1- What remote ref namespace would be appropriate?
2- Should shared stashes use an explicit user-provided name or an
object-derived identifier?
3- Should listing only inspect remote refs, or fetch the export
commits so stash messages can also be displayed?
4- What command naming would fit best with the existing git stash interface?

If the general direction seems reasonable, I can follow up with a more
concrete interface and implementation.

Thanks,
Hanan Arshad

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 2895 bytes --]

On 2026-09-28 at 14:27:23, Hanan Arshad wrote:
> Hi,
> 
> I'd like to propose adding a small porcelain workflow for sharing
> stashes through a Git remote.
> 
> git stash export and git stash import already provide a transportable
> representation of stashes. I tested the following workflow using
> existing commands:
> 
> Alice:
>   git stash export --print stash@{0}
>   git push origin <export-tip>:refs/stashes/alice/wip

You can also use `--to-ref`, which is what I use, and then push that.

> Bob:
>   git fetch origin refs/stashes/alice/wip:refs/shared-stashes/origin/alice/wip
>   git stash import refs/shared-stashes/origin/alice/wip
> The imported stash is a normal local stash and retains the original
> stash object ID. Removing the remote ref afterward does not affect
> Bob's imported stash.
> 
> I'd like to add porcelain around this existing mechanism for four operations:
> 
> 1- publish a selected stash to a remote
> 2- list available shared stashes
> 3- get a shared stash as a normal local stash
> 4- remove a shared stash from the remote

I think that at least 1 is useful here, but you're going to need some
sort of customization.  The name I use for stashes when I am the only
person on the remote is not the same name I use when I'm sharing a
remote with others at my employer.

2 is going to be hard because you don't know whether a ref is a stash
without downloading the data.  3 is also hard because there's no
standard namespacing and it's going to differ based on the context (such
as refs/heads/bk2204/stash or refs/heads/stash).  4 isn't that
difficult.

> This would not introduce a new stash object format, server-side
> service, or synchronization model. It would essentially compose the
> existing export/import mechanism with normal push/fetch operations.
> Before working on an implementation, I'd appreciate feedback on a few
> design points:
> 1- What remote ref namespace would be appropriate?

Again, this is going to depend on the user and environment.

> 2- Should shared stashes use an explicit user-provided name or an
> object-derived identifier?

Names are going to be nicer.  We don't require people to memorize object
IDs and allow them to use branch and tag names.

> 3- Should listing only inspect remote refs, or fetch the export
> commits so stash messages can also be displayed?

Stashes can be large because they (a) can contain untracked files and
(b) contain a reference to history, so inspecting only remote refs is
going to be a lot lighter.

> 4- What command naming would fit best with the existing git stash interface?

Probably `git stash push` or something like that.

I think some nicer tooling would be helpful, so I'm in favour of that,
but I'm not sure that standardization is going to be possible.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 325 bytes --]

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Hanan Arshad]

Hi Brian,

Thanks for the detailed feedback. I reconsidered the design based on your comments, particularly the point that the appropriate remote namespace depends on the user and environment.

I agree that Git should not impose a fixed namespace such as:

refs/stashes/<author>/<name>

Instead, the remote ref should be explicitly chosen by the user. For example:

refs/stashes/hanan/fix-login
refs/stashes/fix-login
refs/heads/hanan/stash
refs/heads/stash

The tooling would provide the stash transport workflow without standardizing where the remote stores it.

The revised interface I have in mind is:

Publish one stash to a user-selected remote ref:

git stash publish <remote> <remote-ref> [<stash>]

For example:

git stash publish origin refs/stashes/hanan/fix-login stash@{0}

If <stash> is omitted, stash@{0} would be used.

Internally this would reuse the existing stash export mechanism and normal push machinery. The original local stash would remain unchanged.

List matching remote refs without downloading their objects:

git stash list --remote <remote> [<ref-pattern>]

For example:

git stash list --remote origin 'refs/stashes/*'

This would list refs only rather than downloading each stash to obtain its description. As you pointed out, stashes may be large, so fetching their contents merely for listing would be unnecessarily expensive.

Retrieve one or more stashes from remote refs:

git stash get <remote> <remote-ref>
git stash get <remote> <ref-pattern>

A single ref retrieves one stash:

git stash get origin refs/stashes/hanan/fix-login

An explicit pattern could retrieve multiple stashes:

git stash get origin 'refs/stashes/hanan/*'

Each matching ref would be fetched and passed through the existing stash import logic, producing normal local stash entries.

Prefix matching would not be implicit. For example:

git stash get origin refs/stashes/hanan

would refer only to that exact ref. The user would need to specify refs/stashes/hanan/* to retrieve refs below that namespace.

No tracking relationship would be established between the imported local stashes and the remote refs.

Remove one or more shared stashes by deleting their remote refs:

git stash remove <remote> <remote-ref>
git stash remove <remote> <ref-pattern>

A single ref:

git stash remove origin refs/stashes/hanan/fix-login

Multiple refs:

git stash remove origin 'refs/stashes/hanan/*'

Again, wildcard matching would need to be explicit rather than treating a ref prefix as a namespace automatically.

This would use the normal remote ref deletion mechanism. Existing local copies would remain unaffected.

publish would always operate on one stash, while get and remove could operate on either a single remote ref or an explicitly specified set of matching refs.

Human-readable ref names would be used rather than requiring users to work with object IDs.

The overall implementation would remain:

local stash
    -> stash export
    -> push to user-selected remote ref
    -> fetch
    -> stash import
    -> normal local stash

So the proposal would add porcelain around the existing mechanisms without imposing a universal remote stash namespace.

Does this direction address your concern about standardization?

Also, do you think it makes sense to pursue all four operations as porcelain, or would you prefer starting with only git stash publish and leaving listing, retrieval, and removal to existing Git commands?

Thanks,
Hanan Arshad

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Johannes Sixt]

Am 05.10.26 um 07:53 schrieb Hanan Arshad:
> The revised interface I have in mind is:
> 
> Publish one stash to a user-selected remote ref:
> 
> git stash publish <remote> <remote-ref> [<stash>]

I am actually not very happy with such an interface. The premise to have
it is that stashes are something that can (and should) be shared with
other people. But this is not the case. Stashes are strictly personal,
short-lived, work-in-progress-not-worth-to-be-committed states. If you
use stashes for longer-lived, worth-to-be-committed, sharable project
states, then you are doing something wrong. You should be using branch
labels instead.

> 
> For example:
> 
> git stash publish origin refs/stashes/hanan/fix-login stash@{0}
> 
> If <stash> is omitted, stash@{0} would be used.
> 
> Internally this would reuse the existing stash export mechanism and
> normal push machinery. The original local stash would remain unchanged.

There you have it. If a stash is worth to be shown, then do take the
long way via `git stash export`, and push the ref. Or just do

  git push origin stash@{0}:refs/stashes/hanan/fix-login

There's no magic support needed (nor, IMHO, desired).

-- Hannes

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Hanan Arshad]

Hi Hannes,

Thanks for the feedback.

I agree that stashes should remain short-lived WIP and that this
should not encourage using them as a replacement for branches or
normal project history.

The use case I have in mind is narrower: temporarily handing off an
unfinished working state to another clone or developer, without first
turning that state into a normal branch workflow.

The motivation is somewhat similar to a Perforce shelf from a UX
perspective: the work is still temporary and unfinished, but another
developer may need to inspect, reproduce, test, or continue that exact
state.

I also agree that Git already has the underlying mechanisms. In fact,
that is the main reason I thought this might make sense as porcelain
rather than as a new feature model.

Today this can already be done through existing refs and stash
transport mechanisms, for example with git stash export, git push, git
fetch, and git stash import, or with the direct push example you
mentioned.

So I am not proposing a new stash representation, server-side storage
model, synchronization mechanism, or ownership model. The intent is
only to make an already possible operation easier to discover and
perform correctly.

The question I am trying to answer is therefore not really "should
stashes become collaborative objects?", but rather:

Is there value in providing a small convenience command around an
already-supported stash transport workflow, so users do not have to
understand and manually compose the lower-level ref/export/import
steps?

I also think your comment suggests that keeping the scope very small
would be preferable. For example, rather than trying to introduce a
larger shared-stash subsystem, an initial version could potentially be
limited to a single publishing convenience and leave listing,
fetching, deletion, etc. to existing Git commands.

Would you still object to such a narrowly scoped porcelain wrapper, or
is your concern mainly about introducing the broader concept of
"shared stashes" into Git?

Thanks,
Hanan

On Mon, 5 Oct 2026 09:47:20 +0200, Johannes Sixt <j6t@kdbg.org> wrote:
> Am 05.10.26 um 07:53 schrieb Hanan Arshad:
> > The revised interface I have in mind is:
> >
> > Publish one stash to a user-selected remote ref:
> >
> > git stash publish <remote> <remote-ref> [<stash>]
>
> I am actually not very happy with such an interface. The premise to have
> it is that stashes are something that can (and should) be shared with
> other people. But this is not the case. Stashes are strictly personal,
> short-lived, work-in-progress-not-worth-to-be-committed states. If you
> use stashes for longer-lived, worth-to-be-committed, sharable project
> states, then you are doing something wrong. You should be using branch
> labels instead.
>
> >
> > For example:
> >
> > git stash publish origin refs/stashes/hanan/fix-login stash@{0}
> >
> > If <stash> is omitted, stash@{0} would be used.
> >
> > Internally this would reuse the existing stash export mechanism and
> > normal push machinery. The original local stash would remain unchanged.
>
> There you have it. If a stash is worth to be shown, then do take the
> long way via `git stash export`, and push the ref. Or just do
>
> git push origin stash@{0}:refs/stashes/hanan/fix-login
>
> There's no magic support needed (nor, IMHO, desired).
>
> -- Hannes

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Johannes Sixt]

Am 05.10.26 um 10:03 schrieb Hanan Arshad:
> The use case I have in mind is narrower: temporarily handing off an
> unfinished working state to another clone or developer, without first
> turning that state into a normal branch workflow.

Understood. But you don't do this ten times a day, so...

> The question I am trying to answer is therefore not really "should
> stashes become collaborative objects?", but rather:
> 
> Is there value in providing a small convenience command around an
> already-supported stash transport workflow, so users do not have to
> understand and manually compose the lower-level ref/export/import
> steps?

... why do you need convenience? A simple export plus a push or even
just a single push command are all that is required today.

So, IMHO, there is zero reason to upgrade stashes so that they can
achieve the exact same thing that we can already do with branches.

(Hence, if indeed you do share your half-finsihed work ten times a day,
then, please, by all means, use the right tool for the task: put your
work on a branch, not in a stash.)

-- Hannes

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Hanan Arshad]

Hi Hannes,

Thanks, I agree with your point after looking more closely at the
existing behavior.

I had overstated what a git stash publish command would add. For a
single stash, Git already handles the essential operation directly:

    git push origin stash@{0}:refs/stashes/hanan/fix-login

So I agree that adding git stash publish would mostly duplicate
functionality that already exists in one command, and I do not plan to
pursue it.

The narrower proposal I am considering now is only around the parts of
the temporary handoff workflow that are less convenient today:

- discovering available remote stash refs,
- fetching one and storing it as a normal local stash entry,
- removing the remote ref when it is no longer needed.

Publishing would remain ordinary git push.

For example, conceptually:

    git stash list --remote <remote> <ref-pattern>
    git stash get <remote> <remote-ref>
    git stash remove <remote> <remote-ref>

These would only be porcelain around existing ls-remote, fetch/stash
store, and remote ref deletion. There would still be no new stash
representation, server-side mechanism, tracking relationship, or
mandatory namespace.

I think this is a more accurate scope for the original shelf-like
workflow I had in mind.

Thanks,
Hanan

On Mon, 5 Oct 2026 10:21:03 +0200, Johannes Sixt <j6t@kdbg.org> wrote:
> Am 05.10.26 um 10:03 schrieb Hanan Arshad:
> > The use case I have in mind is narrower: temporarily handing off an
> > unfinished working state to another clone or developer, without first
> > turning that state into a normal branch workflow.
>
> Understood. But you don't do this ten times a day, so...
>
> > The question I am trying to answer is therefore not really "should
> > stashes become collaborative objects?", but rather:
> >
> > Is there value in providing a small convenience command around an
> > already-supported stash transport workflow, so users do not have to
> > understand and manually compose the lower-level ref/export/import
> > steps?
>
> ... why do you need convenience? A simple export plus a push or even
> just a single push command are all that is required today.
>
> So, IMHO, there is zero reason to upgrade stashes so that they can
> achieve the exact same thing that we can already do with branches.
>
> (Hence, if indeed you do share your half-finsihed work ten times a day,
> then, please, by all means, use the right tool for the task: put your
> work on a branch, not in a stash.)
>
> -- Hannes

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Junio C Hamano]

Hanan Arshad <hananarshad619@gmail.com> writes:

> The narrower proposal I am considering now is only around the parts of
> the temporary handoff workflow that are less convenient today:
>
> - discovering available remote stash refs,
> - fetching one and storing it as a normal local stash entry,
> - removing the remote ref when it is no longer needed.

FWIW, I agree with j6t.  Quoting the part you left at the bottom of
your message (by the way, please do not top-post on this list.  You
quote what others said first, and then you write your response below
that):

>> So, IMHO, there is zero reason to upgrade stashes so that they can
>> achieve the exact same thing that we can already do with branches.
>>
>> (Hence, if indeed you do share your half-finsihed work ten times a day,
>> then, please, by all means, use the right tool for the task: put your
>> work on a branch, not in a stash.)

All of the three you listed (discovery, transfer, clean-up) become
easier to work with if you used branches, branches have always had
good support for these three (and other) operations, and I do not
see a good reason to add a parallel support to do something similar.

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Hanan Arshad]

> All of the three you listed (discovery, transfer, clean-up) become
> easier to work with if you used branches, branches have always had
> good support for these three (and other) operations, and I do not
> see a good reason to add a parallel support to do something similar.

I understand the concern. I think I did not explain the workflow that
originally motivated the RFC clearly enough.

The idea came from a workflow I used with Perforce shelves. One concrete
case is build configuration. The repository contains configuration
templates, while I may have several local configuration variants that
should not become part of the normal project history.

A tester may need to apply the same configuration while testing
different branches or revisions, for example:

    branch A       + configuration X
    branch B       + configuration X
    release branch + configuration X

Using a branch for configuration X makes it another line of history
based on some revision. When the code being tested changes, that
configuration then has to be merged, rebased, cherry-picked, or
otherwise combined with the revision being tested.

What I want instead is an overlay: the tester chooses the code revision
and the temporary configuration independently, applies the
configuration for the test, and then discards it.

Perforce shelves give this kind of temporary handoff a straightforward
user-facing workflow. Git already has the underlying functionality as
well; that became clearer to me during this discussion. A stash can
already be pushed as a ref, so I agree that adding a separate
"publish" command would not be justified.

My motivation for the RFC is therefore not to add another transport or
storage mechanism. It is to see whether the existing stash/ref
functionality could have a more coherent UX for this kind of temporary
handoff, instead of requiring users to compose the generic ref,
push/fetch, and stash operations themselves.

This configuration-overlay workflow is one concrete use case that
motivated the idea. There may be other temporary handoff use cases, but
I do not want to rely on hypothetical cases to justify it.

Thanks,
Hanan

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Johannes Sixt]

Am 07.10.26 um 08:31 schrieb Hanan Arshad:
> A tester may need to apply the same configuration while testing
> different branches or revisions, for example:
> 
>     branch A       + configuration X
>     branch B       + configuration X
>     release branch + configuration X
> 
> Using a branch for configuration X makes it another line of history
> based on some revision. When the code being tested changes, that
> configuration then has to be merged, rebased, cherry-picked, or
> otherwise combined with the revision being tested.
You are overthinking the required workflow.

Nobody claims that you have to keep the configuration X change on an
additional branch for each of the working branches. You would use a
branch only to transfer the configuration X change to other clones. You
don't work on that branch.

In the repository that wants to publish configuration X, you commit the
modifications on ONE branch (doesn't matter which one, say "release"):

	git switch -c configuration-X
	git commit -m"configuration X" -a  # or the config file name
	git push origin +configuration-X
	git checkout release

At this point the state is as if you had run `git stash push` on branch
"release", except the change is on a branch, not in a stash.

Then while on the first branch in a new (or old) clone that needs
configuration X, you run

	git fetch origin
	git show origin/configuration-X | git apply -3

ONCE, which leaves the modifications uncommitted (if there are no
conflicts). From here on, you would use the local stash to transfer the
modifications to other branches, just as you would have done with a
transferred stash.

-- Hannes

[RFC] git stash: add porcelain for sharing stashes through remotes

[Hanan Arshad]

Hi,

I'd like to propose adding a small porcelain workflow for sharing
stashes through a Git remote.

git stash export and git stash import already provide a transportable
representation of stashes. I tested the following workflow using
existing commands:

Alice:
  git stash export --print stash@{0}
  git push origin <export-tip>:refs/stashes/alice/wip

Bob:
  git fetch origin refs/stashes/alice/wip:refs/shared-stashes/origin/alice/wip
  git stash import refs/shared-stashes/origin/alice/wip

The imported stash is a normal local stash and retains the original
stash object ID. Removing the remote ref afterward does not affect
Bob's imported stash.

I'd like to add porcelain around this existing mechanism for four operations:

1. publish a selected stash to a remote
2. list available shared stashes
3. get a shared stash as a normal local stash
4. remove a shared stash from the remote

This would not introduce a new stash object format, server-side
service, or synchronization model. It would essentially compose the
existing export/import mechanism with normal push/fetch operations.
Before working on an implementation, I'd appreciate feedback on a few
design points:
1. What remote ref namespace would be appropriate?
2. Should shared stashes use an explicit user-provided name or an object-derived identifier?
3. Should listing only inspect remote refs, or fetch the export commits so stash messages can also be displayed?
4. What command naming would fit best with the existing git stash interface?

If the general direction seems reasonable, I can follow up with a more
concrete interface and implementation.

Thanks,
Hanan Arshad

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[D. Ben Knoble]

On Thu, Oct 1, 2026 at 5:37 AM Hanan Arshad <hananarshad619@gmail.com> wrote:
>
> Hi,

Hi Hanan, did you mean to send a copy of your prior thread
(https://lore.kernel.org/git/CAKPibBw2XxjGpE_DZrWLZmMHs7kAyvOaP8504kfoh61c4UkGyg@mail.gmail.com/)
?

-- 
D. Ben Knoble

Re: [RFC] git stash: add porcelain for sharing stashes through remotes

[Junio C Hamano]

"D. Ben Knoble" <ben.knoble@gmail.com> writes:

> On Thu, Oct 1, 2026 at 5:37 AM Hanan Arshad <hananarshad619@gmail.com> wrote:
>>
>> Hi,
>
> Hi Hanan, did you mean to send a copy of your prior thread
> (https://lore.kernel.org/git/CAKPibBw2XxjGpE_DZrWLZmMHs7kAyvOaP8504kfoh61c4UkGyg@mail.gmail.com/)
> ?

Perhaps they sent a wrong message after they composed a message to
respond to the excellent idea-review made by Brian?