It’s not uncommon to accidentally add a lot of file data to a repo. You might mistakenly unpack
a tarball or zip file in a repo and discover that you’ve got thousands of new files not covered
by an existing .gitignore entry.
With jj’s automatic snapshots, this can be kind of annoying: running a command like jj status
will cause you to unexpectedly snapshot all of those files. Because you don’t normally look at
jj snapshots (I have never done so even once), this is an invisible tax. Deleting the files
creates a new snapshot that records their removal. If your tarball accident was large, the add
and remove snapshots could each be big.
By default, if jj-musubi sees more than 1,000 new file paths or 64 MiB of data in a snapshot that hasn’t been committed, it will put the sync of that snapshot on hold. The design assumption is that these kinds of additions, without a commit, are usually accidental. The hold prevents these presumed mistaken snapshots from spamming the op logs of your other repos in the hive.
If a snapshot gets used by a subsequent jj commit or other command that creates or modifies
changes, jj-musubi will automatically treat the snapshot as intentional, and lift the hold. A
commit of some snapshotted files will not cause leftover files from the snapshot to be
automatically approved.
Inspecting and dropping unwanted files
Suppose we accidentally unpacked an archive into scratch/data/, and jj snapshotted 1,200 small
files before we noticed. Inspect the snapshots that retain them before choosing what to prune.
This reads recorded history without taking a new snapshot or contacting the hub (output trimmed
here):
$ musubi sync --outgoing
Sending held: snapshots retain 1200 files, 1228800 bytes beyond intentional history.
...
Retaining operations (their byte counts overlap):
a12b34c56d78 1200 files, 1228800 bytes snapshot working copy
Deleting the files leaves their older versions in history. Pruning records your current edits and deletions, then removes the selected operations while keeping the resulting commits and their ids, bookmarks and workspace positions. It can discard older uncommitted versions of files; if you want one, save it first.
Delete the accidental files, then use the ids from your report to prune their snapshots:
$ rm -r scratch/data/
$ musubi sync --prune a12b34c56d78
Discarded 1 unpublished operation; current work is unchanged.
Pruning runs jj util snapshot in the invoking workspace before cleanup, so recent edits and
deletions are included. This follows jj’s normal snapshot behavior, including importing changes
from colocated Git refs, which can rebase commits and update checkout files. Automatic stale
working-copy recovery is disabled for this step, even when snapshot.auto-update-stale is
enabled; follow jj’s recovery hint if the workspace is already stale.
Every local workspace must have a current recorded basis, including secondary workspaces. If
cleanup names a workspace that needs updating, run jj status there and follow its recovery
hint, then retry. For inaccessible or missing workspace metadata, follow the
recovery advice.
Now check that the hold is lifted:
$ musubi sync --outgoing
Within publication budget: snapshots retain 0 files, 0 bytes beyond intentional history.
$ musubi sync
If sending is still held, the report will list the remaining snapshots; prune the unwanted ones too. To pick up your work elsewhere, follow Pick up on another machine.
To keep the extracted files on disk, move them outside the repo instead of deleting them.
Or add scratch/data/ to .gitignore, then run jj file untrack scratch/data/.
Ignoring a file that’s already tracked doesn’t stop jj from snapshotting it.
You can add --dry-run to preview cleanup of the last recorded state without snapshotting or
removing anything. Pending edits and deletions are included when you run the command without
--dry-run, so they can change the result. Pruning removes whole operations, so it can’t remove
individual files from a snapshot. It doesn’t immediately free disk space or erase secrets;
jj’s garbage collection reclaims unused objects later.
Pruning is limited to operations this copy has never tried to send to the hub. If musubi
refuses a selection, it discards no operations; follow the
recovery advice. For history already
sent, see
Abandoning operations.
Approve the history or change limits
You might have unpacked a large set of test data on purpose and want it on another machine.
To send it without committing it or cleaning up snapshots, copy the approval command printed by
musubi sync --outgoing. This approves all the outgoing history in the report, including any
accidental files:
musubi sync --approve <approval-token>
The token approves the outgoing history you inspected, with the limits in effect at that time.
New snapshots or incoming changes can invalidate it. If musubi asks you to inspect again, run
musubi sync --outgoing and use the new token.
If the sync fails or the hub is offline, the approval still holds: the daemon can retry sending the same history. The outgoing report will say “Approved for sending”.
If you often work with larger snapshots, you can raise the limits for this repo:
jj config set --repo musubi.publication.max-files 2000
jj config set --repo musubi.publication.max-bytes '128 MiB'
Use --user instead of --repo to set your defaults. Zero disables a limit; setting both to
zero disables the hold. See the
configuration reference for details.
You can also set snapshot.auto-track = 'none()' to stop jj from automatically adding new
files. This changes your jj workflow; you don’t need to do it to use jj-musubi’s snapshot limits.
Inspecting older edits before pruning
If you want an older uncommitted version of a file, inspect the snapshot that contains it:
jj --ignore-working-copy op show --patch a12b34c56d78
Take the file’s commit id from that output and use it as <commit> to save a copy outside the
repo:
jj --at-op a12b34c56d78 file show -r <commit> AGENTS.md > ../AGENTS-before-cleanup.md
These commands read history without snapshotting your current files.