Recording changes

You work in a Synck repository’s folder the way you work in any folder: open, edit, create and delete files with whatever applications you like. Synck does not watch over your shoulder or record anything automatically. A change becomes part of the history only when you commit it.

The cycle is always the same:

1. Make some changes.
2. Look at them with synck status and synck diff.
3. Record them with synck commit -m "why".

Checking the status of your files

synck status compares every file in the folder with the latest commit and lists every difference, one per line:

$ synck status
A assets
A assets/logo.txt
A proposal
A proposal/draft.txt
A todo.txt

When nothing has changed, it says so:

$ synck status
nothing to commit, working tree clean

Each line starts with a marker:

Marker	Meaning
A	Added: a new file or folder
M	Modified: the file’s content changed
D	Deleted
RN	Renamed in the same folder
MV	Moved to another folder
MV+RN	Moved and renamed
M+RN, M+MV, M+MV+RN	Moved or renamed, and its content changed too

Folders appear as items in their own right. Adding proposal/draft.txt also adds the proposal folder.

For scripts, synck --json status prints the same information as JSON. See Output, JSON and exit codes.

Seeing what changed inside files

synck diff shows the line-by-line changes in text files:

$ synck diff
--- a/notes.txt
+++ b/notes.txt
@@ -1 +1 @@
-Meet at 10.
+Meet at 11.

Synck shows a text diff when both versions are valid UTF-8 without NUL characters and no larger than 8 MiB. For anything else, it just says the file changed:

$ synck diff
Binary files image.bin and image.bin differ

diff does not understand document formats. A Word document, a spreadsheet or a PDF is a binary file to it, even though it may contain text. Open the versions side by side in their applications instead, using synck export to get the old one.

Committing

synck commit records every change that status shows as one commit:

$ synck commit -m "Record the meeting time"
committed sha256:750db9d14bdb7b2b00e40849345a2cc6ee18be176ad842774219615a009819d0

A commit is atomic. Either everything in it is recorded or nothing is. Synck reads each changed file, hashes it and checks that the file did not change while it was being read. If an application is still writing a file, the whole commit is abandoned, your history is unchanged, and you can try again once the file is saved.

If there is nothing to commit, Synck says so and records nothing:

$ synck commit -m "Anything?"
nothing to commit

Committing only some changes

Often your folder contains several unrelated changes. Name the paths you want, and only those are committed:

$ synck commit -m "Draft the proposal" proposal
committed sha256:b76bfdedcfb578758c525f71c9d342326a733047d91d794f199bdb9eee60e631
$ synck status
A assets
A assets/logo.txt
A todo.txt

Naming a folder includes everything inside it. The selection applies to this one commit only. There is no staging area that remembers it, and the remaining changes simply stay in your folder until you commit them.

Writing good commit messages

The message is what people (including you, next year) will read in synck log. Synck lets you omit it, but you should not. A good message says what changed and why, in a line:

Move the launch to 1 March after the landlord's delay

A useful rule of thumb is to commit when a piece of work is complete and makes sense on its own: a section is drafted, figures are reconciled, a folder is reorganized. Do not commit every save, and do not bundle unrelated changes together. One coherent change per commit makes history easy to read and undo.

Who is the author?

Each commit records the author you chose with synck init --author. You can check or change it for future commits:

$ synck config author
author Alex
$ synck config set-author "Alex Morgan"
author Alex Morgan

Changing it never alters commits already made. The author is a label for attribution and is not checked against any account. That is fine on your own computer, but remember it when you read a repository that came from elsewhere.

Telling Synck what to ignore

Some files should never be recorded: temporary files, build output, exports, caches. List them in .synckignore at the root of the repository’s folder. It uses the same pattern syntax as Git’s .gitignore:

# Build output and temporary files
build/
*.tmp

.synckignore is an ordinary tracked file, so a change to it is itself a change you commit:

$ printf 'build/\n*.tmp\n' >> .synckignore
$ synck status
M .synckignore
$ synck commit -m "Ignore build output" .synckignore

Two rules are worth knowing:

• Ignore rules only affect untracked files. If a file is already tracked, adding a matching rule does not hide its changes. Delete the file and commit that deletion first if you want Synck to stop tracking it.
• Set up ignore rules before you bring in a large folder. It is much easier than cleaning up afterwards. See Committing large folders.

Hidden files

Files and folders whose names start with a dot, along with files your operating system marks as hidden, are not tracked by default. That keeps things like .DS_Store and editor settings out of your history. The setting belongs to the repository:

$ synck config hidden-files
hidden-files ignore
$ synck config set-hidden-files track
hidden-files track

With track, untracked hidden files show up in status like any other file, and .synckignore still applies to them. The .synck directory itself is never tracked, whatever the setting.

Inspecting the repository itself

Two commands summarize a repository at a glance. synck info shows its identity:

$ synck info
root /tmp/b2
format_version 6
repo_id 01a17498-6f04-7d82-8d5b-d91939706deb
author Alex
head_repo_seq 3
head_commit_id sha256:b2946d15f95e2e04ac7b0df8f6b0edad8d0e335a8e3ec6593e4cef8c420ff12e

synck context adds the current changes and the most recent commits, which makes it a good first command when you come back to a folder after a while:

$ synck context
root /tmp/b2
format_version 6
...
working_tree dirty
A assets
A assets/logo.txt
A todo.txt
changes_total 3
changes_shown 3
changes_truncated false

recent_commits 3
3 | 2026-10-25 20:45 +01:00 | Alex | Ignore build output
2 | 2026-10-25 20:45 +01:00 | Alex | Draft the proposal
1 | 2026-10-25 20:45 +01:00 | Alex | Initialize Synck repository

Rules of the road

A few habits keep a repository healthy:

• Never touch .synck. Don’t edit it, copy pieces of it, or put it in a cloud-synced folder that might change it behind Synck’s back. To back up, use synck archive.
• Run one Synck command at a time per repository. Synck takes a lock for each operation. A second command that starts while the first is running fails immediately with repository busy instead of waiting.
• If a command is interrupted, leave .synck alone and run the next one. Synck records its intent before it changes anything. The next command completes the interrupted operation first, or stops and reports exactly what is inconsistent. See When an operation is interrupted.