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 01a17496-a728-7222-a2a9-3b1d4701a4e0

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-10-25 20:43 +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:750db9d14bdb7b2b00e40849345a2cc6ee18be176ad842774219615a009819d0

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:daf44e21d62de84d20e3f29cded10b538eeef6c32f793fd70f4f766c1766fb2f

M means modified. The repository now has three commits:

$ synck log
3 | 2026-10-25 20:43 +01:00 | Alex | 1 change | Move the meeting to 11
    M notes.txt

2 | 2026-10-25 20:43 +01:00 | Alex | 1 change | Record the meeting time
    A notes.txt

1 | 2026-10-25 20:43 +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:daf44e21d62de84d20e3f29cded10b538eeef6c32f793fd70f4f766c1766fb2f 2026-10-25T19:43:13.345511486+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:8d95faaba98e333785a49432297f19641769a0d7f6988e3bf06b36da0a2b2103

Ask for the file’s history under its new name:

$ synck history meetings/standup.txt
2 sha256:750db9d14bdb7b2b00e40849345a2cc6ee18be176ad842774219615a009819d0 2026-10-25T19:43:13.091098161+00:00 Alex Record the meeting time
A notes.txt
3 sha256:daf44e21d62de84d20e3f29cded10b538eeef6c32f793fd70f4f766c1766fb2f 2026-10-25T19:43:13.345511486+00:00 Alex Move the meeting to 11
M notes.txt
4 sha256:8d95faaba98e333785a49432297f19641769a0d7f6988e3bf06b36da0a2b2103 2026-10-25T19:43:13.662084729+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/.synckignore
../notes-before-move/notes.txt

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
2 sha256:750db9d14bdb7b2b00e40849345a2cc6ee18be176ad842774219615a009819d0 2026-10-25T19:43:13.091098161+00:00 sha256:0acafc69f8c9239e8d516961088090f2a35903129ec6104fc36d4c5ce41e2790 12
3 sha256:daf44e21d62de84d20e3f29cded10b538eeef6c32f793fd70f4f766c1766fb2f 2026-10-25T19:43:13.345511486+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 2
exported meetings/standup.txt to ../first-version.txt
$ cat ../first-version.txt
Meet at 10.

The first column of versions happens to match the commit number here, but the two are different counters. The commit number counts commits across the whole repository. The item sequence counts changes to this one file. 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":"01a17955-e227-774e-bc2c-4e127ae64aea","terminal_repo_seq":4,"commits":4,"items":3,"blobs":3,"bodies":0}

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 and stored contents it checked. Here the 3 items are .synckignore, the meetings folder and standup.txt. 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 .synck directory. synck init creates one.
• Edit files with any tool, inspect with synck status and synck diff, and record with synck commit. There is no staging step.
• History follows items, so moves and renames keep a file’s past.
• synck export-tree and synck export get earlier states back as new files, without changing your current work.
• synck fsck verifies 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.