Committing large folders

An ordinary commit is a single atomic change, and that has limits. A single commit can hold up to 10,000 events, and a new file takes two or three. When you bring years of documents into a repository at once, or a tool rewrites thousands of files, the change no longer fits in one commit. synck commit --batch records it as a short series of commits instead.

Before you commit a large folder

Two minutes of preparation saves a lot of cleanup. Everything you commit becomes permanent history.

1. Check .synckignore and commit any change to it. Exclude caches, build output, exports and anything else you do not want to keep forever. See Telling Synck what to ignore.
2. Decide about hidden files. They are ignored by default. Change the setting with synck config set-hidden-files track before you commit if you want them.
3. Check for things you should not commit, such as passwords, keys and personal data. Once committed, they cannot be removed from history.
4. Look at synck status. It lists everything the commit will record, so you can spot a folder that should have been ignored.

Commit in batches

Copy or move the folder into the repository’s folder. An ordinary commit tells you when a change is too large:

$ synck commit -m "Import the archive"
synck: atomic commit exceeds the FILE/FOLDER profile limit (TOO_MANY_INTENTS: proposal exceeds the intent limit); use `synck commit --batch`

Nothing was recorded. Run the same commit with --batch:

$ synck commit --batch -m "Import the archive"
committed sha256:9dda8c8ad85127dcf1376c94daf5822620267f29a1aa3a4943a38f52f9e81727
committed sha256:21169957e17115967d955e43a4fc8f488ae9268de59ac8094800cecd3736abbc
committed sha256:93e0c8a003823ca483644a2ea750a517ad1ee6beea4cda0d33154f26e91b5585
committed 5006 items in 3 commits
$ synck log --oneline
4 | 2026-10-26 18:51 +01:00 | Alex | Import the archive
3 | 2026-10-26 18:51 +01:00 | Alex | Import the archive
2 | 2026-10-26 18:51 +01:00 | Alex | Import the archive
1 | 2026-10-26 18:51 +01:00 | Alex | Initialize Synck repository

Each commit holds up to 2,000 changes and is atomic on its own. Folders are recorded before the files inside them, so every commit leaves the history in a consistent state. You can name paths, as with an ordinary commit, to record only part of the working tree.

--batch accepts additions, content changes and individual file deletions. It refuses moves, renames and folder deletions, because splitting those across commits could leave the tree in an inconsistent intermediate state. Commit those with an ordinary synck commit first, then use --batch for the rest.

Use --batch only when an ordinary commit tells you to. Every commit it creates is a separate entry in the history.

If a batch is interrupted

A batch is not one atomic commit. Before it starts, Synck writes down exactly which changes it will record. If the computer crashes or you stop the command, the commits that were already accepted stay accepted, and the next Synck command in that folder continues the remaining batches from where they stopped. If the files changed in the meantime in a way that conflicts with the plan, Synck stops and reports which commits it accepted. Check synck log and synck status before you try again; do not assume that nothing happened.

Undoing a large commit

To take back a folder you committed in batches, delete it and commit. Deleting a folder is a single change, however many files it holds, so an ordinary commit is enough:

$ rm -rf archive
$ synck commit -m "Remove the archive"
committed sha256:8dcd482f9a5516d72602d46e14d3e977a2fed04530022c86d7c337f139ab59d2

The folder and everything in it move to the trash, and the batch commits stay in the history. If you change your mind, synck recover archive -m "..." brings the whole folder back with its identity and history. See Recover a deleted item.