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