Shelve command includes large binary files in .hg/shelve bundle causing unexpected size growth

Question

The shelve command stores changes as a bundle in .hg/shelve. When the working directory contains large binary files, those binaries are included unchanged in the bundle, which can cause the shelve directory to grow unexpectedly and affect disk usage in CI pipelines that rely on shelve for temporary storage. The documentation does not specify whether shelve should exclude or compress large binaries, and no official decision has been made about adding a flag such as --exclude-binaries or automatic compression.
Clarifying the intended behavior would help users decide whether to manually clean .hg/shelve or adopt work‑arounds.
Should the shelve command provide an option to exclude binary files from the bundle? Should it automatically compress large binaries when creating the shelve bundle? What is the recommended practice for users who need to shelve changes that include large binary assets without incurring excessive storage growth?

Zoha · Answer

No. Mercurial's shelve should not add a dedicated --exclude-binaries flag or an automatic large-binary compression pass. The command's contract is to preserve the selected working-copy state so unshelve can restore it exactly; silently omitting binary content would break that contract, and an extra compression layer would add CPU cost without reliably shrinking incompressible assets. This reflects the current design and available options, not a claimed upstream roadmap decision.

Likely explanation
The .hg/shelve bundle stores the revisions required to restore your changes. When you shelve added or modified large binaries, those payloads are written into the bundle as full or delta file revisions. Container-level compression already applies, but formats such as images, videos, archives, and compiled artifacts often remain large on disk.

Confirmed behavior
Mercurial's shelve supports include/exclude file patterns and interactive selection. It does not provide a --exclude-binaries flag or a special large-file compression mode. Bundle compression behavior varies by version and configuration, so measured sizes can differ across CI images.

Steps for this case

Determine whether the large binaries are tracked changes that unshelve must restore, or untracked files swept into the selection.
If they are untracked or unnecessary for the temporary state, exclude them by path:
hg shelve -X 'glob:**.zip' -X 'glob:**.mp4'
Or include only the paths you need:
hg shelve -I 'glob:**.py' -I 'glob:**.js'

If the binaries are tracked and must be preserved, do not force them through shelve. Commit them in a controlled changeset, or use your existing large-file/artifact storage strategy.
In CI, treat .hg/shelve as disposable. Once the shelved state is no longer needed, delete the shelf and clean the directory.

Diagnostic detail that changes the advice
Are the large binaries tracked modifications that unshelve must restore, or untracked files included in the shelve selection? If they are untracked, exclude them by path. If they are tracked, commit them separately rather than relying on shelve for temporary storage.

Verification

Run hg shelve --list and inspect .hg/shelve sizes before and after a shelve to confirm which files dominate the bundle.
Reproduce with a pattern such as hg shelve -X 'glob:**.zip' and compare the resulting bundle size to a full shelve.
Check hg help shelve in your installed version for the exact include/exclude, delete, and unshelve options before scripting cleanup.

Shelve command includes large binary files in .hg/shelve bundle causing unexpected size growth

1 answer

Likely explanation

Confirmed behavior

Steps for this case

Diagnostic detail that changes the advice

Verification

Your perspective belongs here.

0 question comments