Using Mercurial Shelve to Temporarily Set Aside Uncommitted Changes

Desired outcome

You have uncommitted modifications in your working directory and need to switch to another branch or task without committing incomplete work. The goal is to store those changes temporarily, return to a clean state, perform the alternate work, and then restore the original edits exactly as they were.

Prerequisites

• Mercurial version 2.0 or later (the shelve command was introduced in 2.0).
• A repository that contains at least one modified, added, or removed file.
• No active merge, rebase, or bisect operation that would interfere with shelving.
• Read/write access to the repository directory.

Procedure

1. Shelve the current changes

   From the root of the repository run:

   hg shelve

   This creates a shelf entry containing all pending modifications, additions, and deletions. The command will prompt for a shelf name if you have multiple shelves; accepting the default creates a name like default.

2. Verify a clean working directory

   Check that no changes remain:

   hg status

   The output should be empty, indicating a clean state.

   You can also list shelves to confirm the new entry:

   hg shelve --list

   Expect to see exactly one shelf, e.g., default.

3. Perform the alternate work

   Switch branches, apply a patch, or make any other changes needed. Because the working directory is clean, these actions will not interfere with the shelved edits.

4. Restore the shelved changes

   When you are ready to continue with the original work, run:

   hg unshelve

   If you used a non‑default shelf name, specify it: hg unshelve shelf-name.

   This reapplies the stored modifications to the working directory.

5. Optional: Delete the shelf

   After confirming the unshelve succeeded, remove the shelf to free space:

   hg shelve --delete shelf-name

   You can list shelves again to verify deletion.

Expected checks

• After hg shelve, hg status shows no modified, added, or removed files.
• After hg unshelve, running hg diff produces the same output as the diff taken before shelving.
• The status after unshelving matches the original state (same set of modified/added/removed files).
• No new commit is created during the shelve/unshelve cycle; you can confirm with hg log -r . showing the same revision identifier before and after.

Recovery options

• Unshelve conflicts: If applying the shelf fails because the working directory has diverged, Mercurial will leave conflict markers in the affected files. Resolve the markers manually, then continue. You can abort the operation with hg unshelve --abort and retry later.
• Discard a problematic shelf: If the shelf is corrupted or you no longer need it, delete it with hg shelve --delete shelf-name and start over.
• Accidental unshelve of wrong shelf: List shelves (hg shelve --list) to ensure you target the correct name before unshelving.

Limitations and notes

• Shelves are stored only in the local repository clone; they are not transferred by hg push or hg pull. To share work-in-progress, commit changes or use patches.
• Avoid shelving while an active merge or rebase is in progress; the resulting shelf may be unclear and cause merge conflicts upon unshelve.
• The shelf mechanism does not version the shelved changes themselves; if you need a history of temporary states, consider committing to a temporary branch instead.

Concrete example

Suppose you are working on a feature branch and have edited src/main.c and added src/new_util.c. You discover a critical typo in the release branch that must be fixed immediately.

1. Run hg shelve; the shelf named default now holds your two changes.
2. Confirm with hg status (no output) and hg shelve --list (shows default).
3. Switch to the release branch: hg update release.
4. Fix the typo, commit, and push.
5. Return to your feature branch: hg update feature.
6. Restore your work: hg unshelve. Verify with hg diff that the edits to src/main.c and the addition of src/new_util.c are exactly as before.
7. Optionally delete the shelf: hg shelve --delete default.

Following these steps lets you pause work, handle urgent tasks, and resume without losing or duplicating changes.