What is the purpose of git stash create and git stash store?

Question

From the documentation at git-scm, there are two git stash commands that mention relevance to scripting, but not general use:

create

Create a stash (which is a regular commit object) and return its object name, without storing it anywhere in the ref namespace. This is intended to be useful for scripts. It is probably not the command you want to use; see "save" above.

store

Store a given stash created via git stash create (which is a dangling merge commit) in the stash ref, updating the stash reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "save" above.

Supposing that we are considering the context of automated scripts, what advantages do git stash create and git stash store give me over the usual git stash save and friends?

Answer 1

You can use git stash create when you're writing scripts that need to stash as an implementation detail and you don't want to disturb the user's stash reflog.

Depending on what happens next, you might (in the case of error, say) decide you do want to disturb the stash reflog after all, at which point you can use git stash store.

Obviously a regular stash can be implemented in terms of create then store, but I can also imagine it being used in a hypothetical update-branch command that does something like this:

git stash create
git fetch
git rebase
git stash apply

Answer 2

Unfortunately the nice example that Andrew showed above does not work in all cases, because:

• If there are local changes then git stash create will create an unreferenced commit, but it won't actually clear the local changes.

• If there are not any local changes, then it won't create a commit at all (as BlackVegetable pointed out). In that case we should not apply at the end.

• (And minor: Andrew forgot to keep and use the commit ID produced by create.)

With that in mind, it appears to me that the usage should be like this:

# Save the local changes, keep a reference to them, and clear them
stashed_commit="$(git stash create)"
git reset --hard

# Do your thing
git fetch
git rebase

# If there were local changes, then restore them
if [ -n "${stashed_commit}" ]
then git stash apply "${stashed_commit}"
fi

Unwieldy to say the least!

Alas. It would be far simpler if I could just git stash save --allow-empty at the top, and git stash pop at the bottom.

I would love to be wrong. Please correct me!