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. Word, Excel and PowerPoint files (.docx, .xlsx and .pptx) are compared by their text: a document’s paragraphs, each slide’s text, and each sheet’s cells with their formulas. For anything else, it just says the file changed:

$ synck diff
--- a/contract.docx
+++ b/contract.docx
@@ -1,2 +1,2 @@
-Term: 12 months.
+Term: 24 months.
 Rent: 4,000 EUR per month.
Binary files image.bin and image.bin differ

A document’s diff describes its text, so it says nothing about formatting, images or comments, and a change to those alone shows as a binary difference. PDFs and other formats are always binary to diff. 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:c10ad2dfcecedc53f8ff06a52061c509b9099abb3d39167ba8bb4a421253ff88

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:e73064e0fd783858424a6b1da5388e8f6a5f84b0fc8f51f0f1d8ad71dadf4a49
$ 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
A assets
A assets/logo.txt
A todo.txt
$ synck commit -m "Ignore build output" .synckignore
committed sha256:2508c93a916368ec56bcd10a5bb384a77afc5d4d39bbd0a64a6a3b9fadcdf8e9

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 .../b2
format_version 7
repo_id 01a1a3f0-2e12-7172-b625-bef8057b9978
author Alex Morgan
head_repo_seq 3
head_commit_id sha256:2508c93a916368ec56bcd10a5bb384a77afc5d4d39bbd0a64a6a3b9fadcdf8e9

(root is the folder’s full path, shortened here.) 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 .../b2
format_version 7
...
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-11-04 01:23 +01:00 | Alex Morgan | Ignore build output
2 | 2026-11-04 01:23 +01:00 | Alex | Draft the proposal
1 | 2026-11-04 01:23 +01:00 | Alex | Initialize Synck repository

The newest commit carries the new author name. The older ones keep the name they were made with.

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.
  • Let Synck commands take turns. Synck takes a lock for each operation. A command that starts while another is running in the same repository waits for it, for up to 30 seconds, and then fails with repository busy (BUSY in JSON). Nothing has happened in that case, and you can run the same command again.
  • 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.