Moving, renaming and deleting

Reorganizing is a constant part of knowledge work. Drafts become finals, folders get restructured, and files get clearer names. Synck is designed so that none of this costs you history. This page explains how it does that, and the few situations where you need to help it.

Moves and renames keep identity

Every tracked file and folder is an item with a permanent ID. When you move or rename it, Synck records that the same item now has a different name or parent. It does not record a deletion and an unrelated addition:

$ mkdir meetings
$ mv notes.txt meetings/standup.txt
$ synck status
A meetings
MV+RN notes.txt -> meetings/standup.txt
$ synck commit -m "File the notes under meetings"

After the commit, synck history meetings/standup.txt shows the file’s entire past, including the time it was called notes.txt. Moving a folder moves all of its contents, and each of them keeps its own identity and history.

The markers tell you exactly what Synck understood: RN for a rename in the same folder, MV for a move to another folder, and MV+RN for both. If the content also changed, the marker starts with M+, as in M+RN.

How Synck recognizes a moved file

Synck does not compare file contents or guess from similar names. It asks the operating system. Every file on disk has a hidden identity, its file ID (the inode number on macOS and Linux, the file index on Windows), plus a creation time. Synck remembers that pair for every tracked file. When a file disappears from one path and a file with the same identity appears at another, it is the same item.

This approach is exact. A new file that happens to have the same content as a deleted one is never mistaken for it. In return, Synck can only recognize moves that the operating system reports as moves. Most of the time that is every move you make: dragging in Finder or Explorer, renaming a file in place, or mv in a terminal. A few things look different to the operating system:

What you did What Synck sees Identity
Moved or renamed the file MV, RN or MV+RN Kept
Edited and saved, even if the editor saves by writing a temporary file and renaming it over the original M Kept
Copied the file to a new place, then deleted the original A new path, D old path Lost
Downloaded or extracted a fresh copy and deleted the old one A and D Lost
Replaced a file with a folder of the same name, or the other way round D and A at the same path New item, by design

Some file systems, including certain network drives, do not record creation times. On those, Synck cannot match moves safely and reports every move as a deletion plus an addition. Use synck mv there.

If a move shows up as delete and add

Check synck status before you commit. If you see an A and a D where you expected a move, undo the move on disk and let Synck perform it. synck restore-tree puts the working tree back the way it was at the last commit. It discards all uncommitted changes, so commit any other work first:

$ synck status
A copy.txt
D report.txt
$ synck restore-tree
restored working tree
$ synck mv report.txt copy.txt -m "Rename the report"

Moving with synck mv

synck mv moves or renames a tracked item and commits the move in a single step:

$ synck mv todo.txt tasks.txt -m "Rename the to-do list"
committed sha256:4f107ff3ed0851a83dd5e22ab159381e0de28b41e3cc81270d68841cd0ef07f7

It needs a clean working tree, so that the commit contains only the move:

$ synck mv todo.txt tasks.txt -m "Rename"
synck: synck mv requires a clean working tree

Use synck mv when you want a move recorded as its own commit, on file systems that cannot track moves, or in scripts. For everyday reorganizing, your file manager plus synck commit works just as well.

Deleting files

Delete a file or folder with any tool, and Synck sees the deletion:

$ rm -rf proposal
$ synck status
D proposal
D proposal/draft.txt
$ synck commit -m "Drop the proposal folder"

Committing a deletion does not erase anything. The items move to the repository’s trash, and their history and every stored version stay in the repository. synck deleted lists what is in the trash:

$ synck deleted
01a1a3f0-2f52-7348-936a-ecc3fa60b252 FOLDER 12 sha256:6f6aaa8e…9acb7f 2026-11-04T00:23:44.948380+00:00 proposal
01a1a3f0-2f52-7348-936a-ecc40a3616d1 FILE 12 sha256:6f6aaa8e…9acb7f 2026-11-04T00:23:44.948380+00:00 proposal/draft.txt

Each line shows the item’s ID, its type, the commit that deleted it (by position and ID, shortened here), when, and the path it had.

Recovering deleted items

synck recover brings an item back from the trash under its original ID, so its history continues as if it had never left. Name it by the path it had when it was deleted:

$ synck recover proposal -m "Bring the proposal back"
committed sha256:392cdf8f271258873378b77755e11525bca81f3e32f11c4d18f4ceffd58359e1
$ ls proposal
draft.txt

If several deleted items once had the same path, Synck asks you to use the item ID from synck deleted instead, as in synck recover 01a1a3f0-2f52-… -m "...". Recovering a folder also recovers the contents that were deleted with it. Recovery is a commit like any other, so it appears in synck log.

Compare this with creating a new file at the old path. That makes a new item with an empty history, which is what you want for a genuinely new file. When you want the old file back, use recover.

Names that do not travel

Synck keeps one set of naming rules on every operating system, so a repository created on Linux can be checked out on Windows and macOS. In practice:

  • Two items in the same folder cannot have names that differ only in letter case, such as Report.txt and report.txt. Names are also compared after Unicode normalization, so visually identical names count as the same.
  • Characters that some operating systems forbid in file names, such as :, are not allowed anywhere, and neither is a name that ends in a space or a dot.

synck status points out a name that breaks these rules, together with the name Synck would give it:

$ synck status
synck: 1 non-portable name(s):
  "Q3: plan.txt" -> "Q3_ plan.txt": name contains forbidden character ':'

synck commit and synck init fix such names for you. They rename the file or folder on disk to its portable spelling, report each rename, and then go on as usual:

$ synck commit -m "Add files"
renamed "Q3: plan.txt" -> "Q3_ plan.txt"
committed sha256:0fac40a9f4d2b7189eb56b3a3f8aaa5f36d20f5c14ce4082b46a31ad1cf4309d

When two names in a folder differ only in case, the first in alphabetical order keeps its name and the other gets a number, as in report (2).txt. If you prefer another name, rename the file yourself before you commit. Ignored files are never renamed.

Synck versions regular files and folders only. A symbolic link, or anything else that is neither, is left out and listed:

$ synck status
nothing to commit, working tree clean
skipped, not a file or folder: shortcut.txt

A path that Synck already tracks as a file or folder, and that later becomes a link, stops status and commit with an error instead, so that it never looks like a deletion. Finder aliases and Windows shortcuts are ordinary files, and Synck tracks them like any other.