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:
- Make some changes.
- Look at them with
synck statusandsynck diff. - 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, usesynck 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(BUSYin JSON). Nothing has happened in that case, and you can run the same command again. - If a command is interrupted, leave
.synckalone 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.