Dolt Stash Now Works Anywhere

We build Dolt, the world’s first version controlled database. Much of our syntax and features come from Git. This means you can branch, push or pull, and merge your data. But why not do more? We introduced dolt stash over two years ago, but with restrictions. We implemented it only for Dolt’s command line, meaning you couldn’t use it when a server is running. Stash is now everywhere, so let’s explore how it works.

Why Stash?

git stash is an odd, but handy tool. It allows you to store your current changes in a stack to make the repository clean. You can see stashed changes with git stash list, reapply them with git stash pop, or remove them with git stash drop and git stash clear. You can even stash changes, switch branches, then apply those changes on that new branch.

Stash can be very useful. Say you’re working on a feature branch and an urgent bug report comes in. You don’t want to commit your current in-progress changes, so you stash. Great, now you can safely fix the bug on its own branch, then come back and pop your changes to resume the work. Stash use-cases are often similar, but the command’s help page lists several more if you're interested.

Now the Git purists may scoff at stash, can’t you just commit a temporary branch? It has been argued, many times, but stash is still very convenient. It’s one quick command, and you can immediately work on something else. This is part of the reason we limited stash so much at first, we wanted to preserve its brevity.

Dolt Stash is Hard

At Dolt, we try to make our experience as intuitive as possible. Much of the time, this means mimicking Git’s functionality. This isn’t always possible, however. Dolt supports database features like a running server, multiple connections, and concurrency control via transactions. Meshing these database features with Git commands is sometimes challenging. Stash is one of the cases.

Suppose you have a Django app that makes changes to the main Dolt branch as users interact with a site. If one connection stashes, that’s great. But that stash is now shared, so another person might stash on top, only for those changes to be stolen by the first user. How do we fix this?

Introducing: Named Stashes

So stash needs to differ from Git, but we want to be careful. Its utility is in ease-of-use. After all, you could just create a branch. Of course we also have to make it work in Dolt’s unique environment.

There are several options we thought of:

1. Each user has their own private stash that no one else can use.
2. Each branch has its own stash.
3. Named stashes that the user specifies.

Each has its own advantages and drawbacks, but we eventually decided on the third option. Why?

Private stashes would be great, but Dolt doesn’t store the information that we’d need to consistently have a unique name for the stashes. Any name that could be used by multiple users runs into the issue of tripping over the same stashes.

So why not branch-specific stashes? Popping stashes onto different branches is a key feature, but concurrency is the bigger issue once again. Multiple users on the same branch would be sharing a stash and potentially writing over each other. Not fun.

We think named stashes have the least problems, but how do they work? Whenever you want to interact with a stash, you specify which one. You would call dolt\_stash(‘push’, ‘chevron’) to add, dolt\_stash(‘pop’, ‘walrus’) to pop, and so on. There are tradeoffs, but we believe this to be the nicest solution. You can share stashes with others in case you want to, but it’s also easy to have your own stash. It’s easy to understand and adds only one argument to the command, keeping it relatively convenient.

How does this work in practice? Let’s try out the new stash changes.

Stashing With Dolt

Let’s explore a simple use case. Suppose we’ve modified some values in some table, and we want to pull in some new changes.

CALL DOLT_PULL('origin', 'main');
WARN[0031] error running query                           connectTime="2025-06-13 13:00:23.144441 -0700 PDT m=+2.639885709" connectionDb=db connectionID=1 error="cannot merge with uncommitted changes" queryTime="2025-06-13 13:00:51.824927 -0700 PDT m=+31.320566209"
ERROR 1105 (HY000): cannot merge with uncommitted changes

Dolt isn’t happy pulling to a dirty working set. We don’t want to commit, however, so what do we do? Well, we stash.

CALL DOLT_STASH('push', 'handlebar');
+--------+
| status |
+--------+
|      0 |
+--------+
1 row in set (0.01 sec)

Perfect. We can check that our working set is now clean, and even see our stash by querying the dolt_stashes system table! We can pull with no worries (about our data, at least).

SELECT * FROM dolt_status;
Empty set (0.00 sec)

SELECT * FROM dolt_stashes;
+---------+-----------+--------+----------------------------------+-----------------+
| name    | stash_id  | branch | hash                             | commit_message  |
+---------+-----------+--------+----------------------------------+-----------------+
| myStash | stash@{0} | main   | veied7v6cfrg3bhqa2ap6o8ph8hrdhfb | Created a table |
+---------+-----------+--------+----------------------------------+-----------------+
1 row in set (0.00 sec)

CALL DOLT_PULL('origin','main');
+--------------+-----------+------------------+
| fast_forward | conflicts | message          |
+--------------+-----------+------------------+
|            1 |         0 | merge successful |
+--------------+-----------+------------------+
1 row in set (0.02 sec)

Now we simply get back our stashed changes, and continue working.

CALL DOLT_STASH('pop', 'handlebar');
+--------+
| status |
+--------+
|      0 |
+--------+
1 row in set (0.02 sec)

SELECT * FROM dolt_status;
+------------+--------+----------+
| table_name | staged | status   |
+------------+--------+----------+
| t          |      0 | modified |
+------------+--------+----------+
1 row in set (0.01 sec)

What Now?

Stash now works everywhere. What's next? Git supports many options and subcommands for stash, which Dolt has not yet added. We also don't yet support merge resolution. If you pop conflict-creating changes, you'll get an error message, and your stash will be preserved.

Interested in the stash changes? Why not download Dolt and give it a shot? Tell us what you think! If you want more features for stash, or hate it and really everyone should just use git worktree, come tell us on Discord. We’re always happy to chat.