Cut Disk Footprint with Mercurial `hg share`: A Practical Guide

Problem: Full Clones Eat Space

When a team needs several local workspaces—say, for feature branches, experimental builds, or CI agents—creating a full clone of the repository for each copy duplicates the entire history. In a large codebase, that can quickly consume gigabytes of disk and slow down file‑system operations.

Thesis: Reuse the Store, Keep the Workspaces Separate

Mercurial’s hg share solves this by creating a lightweight clone that points to the same .hg/store directory as the original repository. Only the working directory is duplicated, so the disk footprint stays minimal while each clone behaves like a regular repository.

1. What Does hg share Do?

• Creates a new working directory (e.g., shared) that contains its own .hg metadata.
• All .hg/store files are symlinked or hard‑linked to the original store, so the actual data is shared.
• Each clone has its own .hg/branch and working copy, allowing independent edits.
• Only works on local filesystems; the shared store is not designed for networked or remote repositories.

2. Setting Up a Shared Clone – Step‑by‑Step

1. Initialize a base repository (if you don’t already have one):

   hg init repo
   cd repo
   
   echo "Hello" > file
   hg commit -Am "init"
   

2. Create a shared clone in a sibling directory:

   hg share repo shared
   

   After this, shared/.hg/store is a link to repo/.hg/store. You can verify by inspecting the link target.

3. Check disk usage to see the savings:

   du -sh repo
   du -sh shared
   

   The shared clone should show only the size of the working directory plus minimal metadata.

4. Confirm identical history:

   hg log -r . -T "{rev}:{node|short} {desc}\n" --cwd repo
   hg log -r . -T "{rev}:{node|short} {desc}\n" --cwd shared
   

   The outputs should match.

3. Using the Shared Clone

Because the shared clone shares the store, any changes you commit there are reflected in the base repository’s history. However, you should not push directly from a shared clone to a remote; instead, push from the base or another non‑shared clone.

# In the shared clone
hg update default
# Make a change
hg commit -m "Feature in shared clone"
# Push from the base repo
hg push

After pushing, the base repository will contain the new changes, and any other shared clones will see them on the next update.

4. Trade‑offs & Limitations

• Remote Pushes: hg share is local only. If you need to push to a remote, use a separate non‑shared clone.
• Extension Compatibility: Some extensions that modify the store (e.g., hg convert, hg bundle) may not work reliably with a shared clone.
• File System Constraints: On systems that do not support hard links (e.g., some networked drives), hg share may fall back to copying, negating the disk‑saving benefit.
• Security Considerations: Since multiple working directories share the same underlying data, accidental deletion of the base store will affect all shared clones.

Actionable Checklist

1. Verify your Mercurial version: hg --version (must be ≥ 1.5).
2. Ensure you’re on a local filesystem that supports hard links.
3. Run hg share as shown above.
4. Use the base or a dedicated non‑shared clone for pushes.
5. Periodically run du -sh to confirm storage savings.

With these steps, you can keep multiple local workspaces lightweight, saving disk space and speeding up operations without sacrificing the full power of Mercurial’s distributed model.