Viewing history
Once a repository has a few commits, you will want to ask questions of it. What happened last week? Who changed this file? What did the folder look like before the reorganization? Synck answers each of these with a different command. The examples on this page use the repository from Your first repository.
The commit log
synck log lists commits, newest first:
$ synck log -n 2
4 | 2026-11-04 01:19 +01:00 | Alex | 2 changes | File the notes under meetings
A meetings
MV+RN notes.txt -> meetings/standup.txt
3 | 2026-11-04 01:19 +01:00 | Alex | 1 change | Move the meeting to 11
M notes.txt
Each entry has the commit’s position, its local time, its author, the number of
changes, and its message, followed by the changes themselves. -n limits how
many commits are shown. For a compact overview, use --oneline:
$ synck log --oneline
4 | 2026-11-04 01:19 +01:00 | Alex | File the notes under meetings
3 | 2026-11-04 01:19 +01:00 | Alex | Move the meeting to 11
2 | 2026-11-04 01:19 +01:00 | Alex | Record the meeting time
1 | 2026-11-04 01:19 +01:00 | Alex | Initialize Synck repository
Naming a commit
Commands that take a revision accept four forms:
| Form | Meaning | Example |
|---|---|---|
HEAD |
The latest commit | synck show HEAD |
HEAD~N |
N commits before the latest | synck show HEAD~2 |
| A number | The commit at that position in the log | synck show 2 |
| A full commit ID | The commit with exactly that ID | synck show sha256:c10ad2df… |
Unlike Git, Synck does not accept abbreviated commit IDs, branch names or other
revision expressions. Positions have no gaps: they run 1, 2, 3 and so on, so
HEAD~1 is always the position before the latest.
Looking at one commit
synck show prints a single commit, with its full ID and an exact timestamp
in UTC:
$ synck show 2
2 sha256:c10ad2dfcecedc53f8ff06a52061c509b9099abb3d39167ba8bb4a421253ff88 2026-11-04T00:19:26.206562+00:00 Alex Record the meeting time
A notes.txt
The change rows in log and show are a summary for people. To see exactly
what Synck recorded, add --events:
$ synck log -n 1 --events
4 | 2026-11-04 01:19 +01:00 | Alex | 2 changes | 3 events | File the notes under meetings
0 | FOLDER::CREATE | item 01a1a3ec-c89f-7796-aaa8-91014bd638b4 | item-seq 1
{"create_item":{"item_type":"FOLDER","name":"meetings"},"event_type":"FOLDER::CREATE","item_id":"01a1a3ec-c89f-7796-aaa8-91014bd638b4"}
1 | FILE::SET_PARENT | item 01a1a3ec-c77c-71da-b4aa-47c7536b1e50 | item-seq 3
{"base_seq":2,"event_type":"FILE::SET_PARENT","item_id":"01a1a3ec-c77c-71da-b4aa-47c7536b1e50","set_parent":"01a1a3ec-c89f-7796-aaa8-91014bd638b4"}
2 | FILE::SET_NAME | item 01a1a3ec-c77c-71da-b4aa-47c7536b1e50 | item-seq 4
{"base_seq":2,"event_type":"FILE::SET_NAME","item_id":"01a1a3ec-c77c-71da-b4aa-47c7536b1e50","set_name":"standup.txt"}
The two changes a person sees, “a folder was added” and “a file moved and was renamed”, are three events underneath. One event creates the folder, and two events change the file: one sets its new parent and one sets its new name. Each event names the item it changes and its position in that item’s history. Items, events and commits explains how to read these.
One file’s story
synck log tells the story of the repository. synck history tells the
story of one item, following it through every move and rename:
$ 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 history is oldest first, and each commit is followed by what happened to
this file in it. Notice that you asked about meetings/standup.txt, but the
history begins with the file’s original name.
history takes a path, so it works for items that exist now. To find
something that has been deleted, look in the trash with
synck deleted.
A file’s versions
synck versions lists only the commits that changed a file’s content,
leaving out moves and renames:
$ 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
The columns are the version’s item sequence, the commit, the time, the
content hash and the size in bytes. The item sequence is how you select a
version with synck export --item-seq and synck restore --item-seq. It counts
events on this one file, so it is not the same as the commit position in the
log: the first version here is item sequence 1, recorded in commit 2. In a
busier history the two diverge quickly.
Comparing two points in time
synck diff with two revisions shows the text changes between them:
$ synck diff 2 HEAD
--- a/notes.txt
+++ b/meetings/standup.txt
@@ -1 +1 @@
-Meet at 10.
+Meet at 11.
Because Synck knows notes.txt and meetings/standup.txt are the same file, it
shows the content change between them. A path-based tool would show one file
deleted and another added. diff takes either no revisions (your uncommitted
changes) or exactly two.
synck compare summarizes the structural difference between two revisions,
using the same markers as status:
$ synck compare 2 HEAD
A meetings
M+MV+RN notes.txt -> meetings/standup.txt
Seeing the whole folder at a point in time
To look around a past state rather than compare it, extract it:
$ synck export-tree HEAD~1 ../notes-before-move
exported HEAD~1 to ../notes-before-move
The destination must not exist. You get ordinary files and folders, with no
history. To extract only one folder as it was at that revision, add
--folder PATH. This works even if the folder has since been moved or deleted.
History for scripts
Every command produces JSON when you pass the global --json flag before the
command name, log, show, history, versions, compare and status
included:
$ synck --json log -n 1
{"commits":[{"author":"Alex","changes":[{"content_changed":false,"kind":"ADD","path":"meetings","source_path":null},{"content_changed":false,"kind":"MOVE_RENAME","path":"meetings/standup.txt","source_path":"notes.txt"}],"changes_shown":2,"changes_total":2,"changes_truncated":false,"commit_id":"sha256:372fbb3a6faf011c439fa015908e4309d4b0111476042650ac5b9a122b3f108d","created_at":"2026-11-04T00:19:26.496857+00:00","message":"File the notes under meetings","repo_seq":4}],"schema_version":5}
Parse JSON rather than the human-readable output, which may change between releases. Output, JSON and exit codes describes the documents and their errors.