Your first repository
In this tutorial you will put a folder under version control, record a few changes, rename a file without losing its history, and get an earlier version back. It takes about ten minutes. You need Synck installed and a terminal.
Everything happens in a new, empty folder, so nothing you already have is at risk.
Create a repository
Make a folder and tell Synck to track it:
$ mkdir synck-notes
$ cd synck-notes
$ synck init --author "Alex"
initialized Synck repository 01a1a3ec-c5dc-744d-84ea-895e8e2ef7ae
The long value is the repository’s ID. Every repository gets a new one, so
yours will differ. --author sets the name recorded on your future commits.
It is a label, not an account; you can change it later with
synck config set-author.
Two entries have appeared:
$ ls -A
.synck
.synckignore
.synck is where Synck keeps the repository: the history database and the
stored content. Treat it as Synck’s private property. Never edit, delete or
copy files inside it by hand; Synck has commands for everything you will need
to do with it.
.synckignore lists files Synck should not track. Synck starts you off
with rules for clutter that is never part of the work: operating-system files
such as macOS __MACOSX/ folders and Windows Thumbs.db, Microsoft Office’s
~$ lock files, editor temporary files, and dependency and cache folders such
as node_modules/. Hidden files, the ones whose names start with a dot, are
also left out unless you choose to track them.
.synckignore is an ordinary file that you can edit, and it is already in the
history:
$ synck log
1 | 2026-11-04 01:19 +01:00 | Alex | 1 change | Initialize Synck repository
A .synckignore
Every log entry starts with the same fields: a sequence number, the time, the
author, a count of changes and the message. The indented rows list what
changed. A means added.
Record a file
Create a file:
$ printf 'Meet at 10.\n' > notes.txt
Ask Synck what has changed since the last commit:
$ synck status
A notes.txt
synck status compares the folder with the latest recorded state and lists
every difference. To see the change itself, use synck diff:
$ synck diff
--- /dev/null
+++ b/notes.txt
@@ -0,0 +1 @@
+Meet at 10.
That is a unified diff, the same format many other tools use: - lines were
removed and + lines were added. diff shows text files. For other files, such
as Word documents, PDFs and images, it reports that they changed without
printing their content.
Now record the change:
$ synck commit -m "Record the meeting time"
committed sha256:c10ad2dfcecedc53f8ff06a52061c509b9099abb3d39167ba8bb4a421253ff88
If you have used Git, notice what you did not do: there is no add step.
synck commit records every change in the folder at once. When you want to
commit only some of your changes, name the paths, as in
synck commit -m "..." notes.txt. Recording changes
covers this in more detail.
The sha256:… value is the commit’s ID: a hash of exactly what was recorded.
If anything in that commit were later altered, the hash would no longer match.
Record a change
Edit the file. In real life you would use any editor; here, overwrite it:
$ printf 'Meet at 11.\n' > notes.txt
$ synck status
M notes.txt
$ synck diff
--- a/notes.txt
+++ b/notes.txt
@@ -1 +1 @@
-Meet at 10.
+Meet at 11.
$ synck commit -m "Move the meeting to 11"
committed sha256:009693a7d491a1d9108824055563103bc580b528f532b47d0b2d889b9ba31008
M means modified. The repository now has three commits:
$ synck log
3 | 2026-11-04 01:19 +01:00 | Alex | 1 change | Move the meeting to 11
M notes.txt
2 | 2026-11-04 01:19 +01:00 | Alex | 1 change | Record the meeting time
A notes.txt
1 | 2026-11-04 01:19 +01:00 | Alex | 1 change | Initialize Synck repository
A .synckignore
The newest commit comes first. The number at the start of each entry is the
commit’s position in the repository’s history. You can use it, or HEAD for
the latest commit, to refer to a commit:
$ synck show HEAD
3 sha256:009693a7d491a1d9108824055563103bc580b528f532b47d0b2d889b9ba31008 2026-11-04T00:19:26.346268+00:00 Alex Move the meeting to 11
M notes.txt
Rename without losing history
Now reorganize: create a folder and move the file into it under a new name. Use your ordinary tools. Synck does not need to be told in advance:
$ mkdir meetings
$ mv notes.txt meetings/standup.txt
$ synck status
A meetings
MV+RN notes.txt -> meetings/standup.txt
Synck did not see a deleted notes.txt and an unrelated new
meetings/standup.txt. It recognized the same file, now in a different folder
(MV, moved) and under a different name (RN, renamed). Commit it:
$ synck commit -m "File the notes under meetings"
committed sha256:372fbb3a6faf011c439fa015908e4309d4b0111476042650ac5b9a122b3f108d
Ask for the file’s history under its new name:
$ synck history meetings/standup.txt
2 sha256:c10ad2dfcecedc53f8ff06a52061c509b9099abb3d39167ba8bb4a421253ff88 2026-11-04T00:19:26.206562+00:00 Alex Record the meeting time
A notes.txt
3 sha256:009693a7d491a1d9108824055563103bc580b528f532b47d0b2d889b9ba31008 2026-11-04T00:19:26.346268+00:00 Alex Move the meeting to 11
M notes.txt
4 sha256:372fbb3a6faf011c439fa015908e4309d4b0111476042650ac5b9a122b3f108d 2026-11-04T00:19:26.496857+00:00 Alex File the notes under meetings
MV+RN notes.txt -> meetings/standup.txt
The whole life of the file is there, including the time before it was called
standup.txt. This is what item identity means in practice: history follows
the file, not the path. Moving, renaming and
deleting explains how Synck recognizes moves
and what to do when an application breaks them.
Get an earlier version back
Nothing you have committed is lost. There are two common ways to get it back without disturbing your current work.
The whole folder as it was. synck export-tree writes the files of any
commit into a new folder. HEAD~1 means “one commit before the latest”:
$ synck export-tree HEAD~1 ../notes-before-move
exported HEAD~1 to ../notes-before-move
$ find ../notes-before-move -type f
../notes-before-move/notes.txt
../notes-before-move/.synckignore
The export is a plain folder of files with no .synck directory and no
history, ready to open or send to someone. The destination must not already
exist; Synck never overwrites files when it exports.
One file at one version. synck versions lists every content version of a
file:
$ synck versions meetings/standup.txt
1 sha256:c10ad2dfcecedc53f8ff06a52061c509b9099abb3d39167ba8bb4a421253ff88 2026-11-04T00:19:26.206562+00:00 sha256:0acafc69f8c9239e8d516961088090f2a35903129ec6104fc36d4c5ce41e2790 12
2 sha256:009693a7d491a1d9108824055563103bc580b528f532b47d0b2d889b9ba31008 2026-11-04T00:19:26.346268+00:00 sha256:54b5e89382d5bd75aaad652ca43cc9b844e1b5f8b73a0aac462a9b20a2bb731a 12
Each line describes one version. The first column is the version’s item
sequence: its position in this file’s own history. Next come the commit that
recorded it, the time, the hash of the content and its size in bytes. Pass the
item sequence to synck export to write that version to a new file:
$ synck export meetings/standup.txt ../first-version.txt --item-seq 1
exported meetings/standup.txt to ../first-version.txt
$ cat ../first-version.txt
Meet at 10.
Notice that the first version has item sequence 1 but was recorded in commit 2. The two are different counters. The commit number counts commits across the whole repository. The item sequence counts changes to this one file. Moves and renames count too, although they are not new versions, so the two numbers drift further apart as a file’s life goes on. Commit identity and the three coordinates explains why Synck keeps them apart.
Your working tree, the files in the folder, is untouched by all of this:
$ synck status
nothing to commit, working tree clean
Check the repository
Finally, ask Synck to verify everything it has stored:
$ synck fsck
{"repo_id":"01a1a3ec-c5dc-744d-84ea-895e8e2ef7ae","terminal_repo_seq":4,"commits":4,"items":3,"objects":3,"metadata":5,"missing_objects":[],"missing_metadata":[],"state_digest":"sha256:b762d5594ca527b73c492e9520ced14cf2fd05b967d97a9dd4f27bcb3ea24880"}
fsck (short for file system check) re-reads the whole history, checks its
structure, and recomputes the hash of every stored version. On success it prints
a one-line summary: the repository ID, the latest commit number, and how many
commits, items, stored contents (objects) and metadata records it checked.
Here the 3 items are .synckignore, the meetings folder and standup.txt,
and the 3 objects are .synckignore and the two versions of the notes. The two
missing_ lists name anything the history refers to that is not stored; they
are empty in a complete repository. state_digest is a hash of the
repository’s current state. If anything is wrong,
fsck names the problem and exits with a non-zero status. See Checking
integrity.
What you learned
- A repository is a folder with a
.synckdirectory.synck initcreates one. - Edit files with any tool, inspect with
synck statusandsynck diff, and record withsynck commit. There is no staging step. - History follows items, so moves and renames keep a file’s past.
synck export-treeandsynck exportget earlier states back as new files, without changing your current work.synck fsckverifies that everything stored is intact.
When you are done, you can delete the synck-notes folder and the exports
beside it. They are ordinary folders.
Next, open a repository someone else made in Opening a complete repository, or continue with everyday work in Synck basics.