Using Mercurial’s Shelve Extension to Keep Your Work Safe While Switching Contexts

Problem: You’re halfway through a feature and a critical bug lands in the main branch

In Mercurial, you often find yourself in the middle of a change that isn’t ready for commit. Suddenly a client reports a regression in the production branch. You need to pull the latest changes, run tests, and maybe even fix a bug—all without losing the work you’re doing.

Thesis: The shelve extension gives you a lightweight, non‑historical stash that lets you temporarily set aside uncommitted changes, pull updates, and then bring your work back.

What the Shelve Extension Does

• Creates a patch file that captures the differences between your working directory and the current revision.
• Stores that patch in .hg/shelve, outside the normal revision history.
• Allows you to unshelve the patch later, applying it on top of the latest changes.
• Does not require a commit, so the shelf lives only on your machine.

Because the shelf is a simple patch, it works even in a repository that has never had a commit. That’s handy for very small projects or when you’re experimenting locally.

Typical Workflow Example

1. Enable the extension (once per user or per repo)

   # ~/.hgrc or .hg/hgrc
   [extensions]
   shelve=
   

2. Create a test repository

   hg init testrepo
   cd testrepo
   echo "Hello" > file.txt
   hg add file.txt
   hg commit -m "Initial file"
   

3. Make experimental changes

   echo "World" >> file.txt
   

4. Shelve the changes

   hg shelve -n my-experiment
   # The patch is now stored in .hg/shelve/my-experiment.patch
   

   Check that the working directory is clean: hg status should show no modifications.

5. Pull updates from upstream

   hg pull -u https://example.com/repo
   

   Because the working directory is clean, the update will succeed without conflicts.

6. Unshelve and resolve conflicts

   hg unshelve -n my-experiment
   

   If the same line was changed in the new revision, Mercurial will ask you to resolve the conflict. After editing the file, run hg resolve --mark file.txt and then hg commit -m "Reapply experiment on top of updated code".

7. Clean up the shelf

   hg shelve --delete my-experiment
   

   This removes the patch file from .hg/shelve and frees up space.

Trade‑offs & Limitations

• Local‑only: Shelved patches live on your machine and are not pushed or cloned. If you need to share the experiment, you must commit it or export the patch manually.
• Untracked files: Unshelving will fail if the working directory contains untracked files that would be overwritten by the patch. Keep the directory tidy or use hg purge before unshelving.
• Performance on large trees: Creating a patch for a huge repository can be slow because the extension must diff every file. For very large codebases, consider using a lightweight commit instead.
• Manual cleanup: Shelves are not removed automatically. Use hg shelve --list to see what’s pending and hg shelve --delete to clear them.

Actionable Takeaway

If you frequently need to jump between unfinished work and urgent updates, enable the shelve extension and treat it as your “in‑progress stash.” It’s faster than committing and pushing, and it keeps your history clean. Just remember:

• Add shelve to your ~/.hgrc or use --config extensions.shelve= for one‑off runs.
• After shelving, always run hg status to confirm the working directory is clean.
• Before unshelving, check for untracked files that might block the patch. Clean them with hg purge if necessary.
• Delete old shelves to avoid clutter—hg shelve --delete <shelf>.

Give it a try next time you need to pull a hotfix without committing your half‑finished feature. Your workflow will feel smoother, and your repo history stays tidy.