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-10-25 20:43 +01:00 | Alex | 2 changes | File the notes under meetings
    A meetings
    MV+RN notes.txt -> meetings/standup.txt

3 | 2026-10-25 20:43 +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-10-25 20:43 +01:00 | Alex | File the notes under meetings
3 | 2026-10-25 20:43 +01:00 | Alex | Move the meeting to 11
2 | 2026-10-25 20:43 +01:00 | Alex | Record the meeting time
1 | 2026-10-25 20:43 +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:750db9d1…`

Unlike Git, Synck does not accept abbreviated commit IDs, branch names or other revision expressions. Positions can have gaps in some repositories, so HEAD~1 is not always the latest position minus one. HEAD~N always counts real commits. Use it when you mean “the commit before”.

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:750db9d14bdb7b2b00e40849345a2cc6ee18be176ad842774219615a009819d0 2026-10-25T19:43:13.091098161+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-10-25 20:43 +01:00 | Alex | 2 changes | 3 events | File the notes under meetings
    0 | FOLDER::CREATE | item 01a17496-aafa-73a0-a1ee-c8f94f98b165 | item-seq 1
        {"create_item":{"item_type":"FOLDER","name":"meetings"},"event_type":"FOLDER::CREATE","item_id":"01a17496-aafa-73a0-a1ee-c8f94f98b165"}
    1 | FILE::SET_PARENT | item 01a17496-a8bb-76e0-8c24-ff89c5d2e99e | item-seq 4
        {"base_seq":3,"event_type":"FILE::SET_PARENT","item_id":"01a17496-a8bb-76e0-8c24-ff89c5d2e99e","set_parent":"01a17496-aafa-73a0-a1ee-c8f94f98b165"}
    2 | FILE::SET_NAME | item 01a17496-a8bb-76e0-8c24-ff89c5d2e99e | item-seq 5
        {"base_seq":3,"event_type":"FILE::SET_NAME","item_id":"01a17496-a8bb-76e0-8c24-ff89c5d2e99e","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: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 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
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

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. 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

log, show, history, versions, compare and status, along with most other inspection commands, produce JSON when you pass the global --json flag before the command name:

$ 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:8d95faaba98e333785a49432297f19641769a0d7f6988e3bf06b36da0a2b2103","created_at":"2026-10-25T19:43:13.662084729+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 lists which commands support it.

Moving, renaming and deleting

Undoing things