Using Mercurial Shelve: Quick, Portable Stash for Context Switching

Why Shelve Matters

When you’re in the middle of a feature and need to jump to a hot‑fix, you normally commit or revert the changes. Both options have drawbacks: committing pollutes the history, reverting loses your work. Mercurial’s shelve extension offers a lightweight, reversible stash that keeps your working copy clean without touching the repository’s commit log.

What Shelve Does Under the Hood

The extension writes a patch file (or a set of files for binary changes) into .hg/shelve. Each entry is named, so you can keep multiple stashes. The working directory is then reset to the parent revision of the changeset you shelved, giving you a clean slate. Unshelving restores the patch to the working copy, optionally merging it with the current state.

Key Commands

• hg shelve [NAME] – Store the current uncommitted changes under NAME (default: default).
• hg unshelve [NAME] – Apply the shelved changes back into the working copy.
• hg shelve --list – Show all stored shelves with their revision numbers.
• hg shelve --delete NAME – Remove a named shelf.

These commands run in any Mercurial repository where the shelve extension is active. In modern releases (≥ 5.0) it is enabled by default; older versions require adding shelve = to the [extensions] section of hgrc.

Concrete Workflow Example

1. Make a change:

   echo "Feature A" >> file.txt
   hg status
   # M file.txt
   

2. Shelve the change:

   hg shelve myfeature
   # Output: Shelved 1 file(s) into 'myfeature'
   

   Check that the working copy is clean:

   hg status
   # No output
   

3. Switch context (e.g., update to a hot‑fix branch):

   hg update hotfix-branch
   

4. Apply the shelved change later:

   hg unshelve myfeature
   # If the target revision has diverged, conflicts may appear
   

   Resolve any conflicts, then continue working or commit.

5. Clean up (optional):

   hg shelve --delete myfeature
   

Trade‑offs and Limitations

• No merge support: Unshelving into a branch that has diverged can produce merge conflicts. You must resolve them manually.
• Binary overhead: Large binary files are stored as separate patch files, increasing the size of .hg/shelve and potentially slowing down clone or unshelve operations.
• Not part of the commit history: Shelved changes are local to the repository; they do not propagate with hg push. To share a patch, export the shelf or use hg bundle.
• Requires extension enabled: On very old Mercurial installations you must explicitly enable the extension in hgrc.

Practical Tips

• Use descriptive shelf names (e.g., myfeature, bugfix-123) to avoid confusion.
• Keep shelves small; for large refactors consider creating a temporary branch instead.
• Inspect .hg/shelve to verify that your data is stored correctly: ls .hg/shelve.
• When sharing a patch, export the shelf: hg shelve --export myfeature patches/feature.patch and send the file.

Conclusion

The shelve extension gives Mercurial users a Git‑style stash that is both lightweight and portable across clones. By storing changes in .hg/shelve you can switch contexts without committing, keep history clean, and share patches without pushing. Remember the trade‑offs—especially around merges and binary files—and test the workflow in a sandbox repo before integrating it into your daily routine.