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

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
01a17498-6fec-7dc2-9fd6-ff8463051d65 FOLDER 9 sha256:e2a5e2d7…1fd21e 2026-10-25T19:45:22.264487990+00:00 proposal
01a17498-6fec-7dc2-9fd6-ff9c4ee852fe FILE 9 sha256:e2a5e2d7…1fd21e 2026-10-25T19:45:22.264487990+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:0de0e0159cd862b6b45832738781c53d5d1277843b11a1acf3fa84ebaf8d84b0
$ 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 01a17498-6fec-… -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 Synck will not accept

Synck keeps one set of naming rules on every operating system, so a repository created on Linux can be read 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 rejected everywhere.

Synck reports the problem and records nothing:

$ synck commit -m "Add files"
synck: portable name collision in .: "Report.txt" and "report.txt"

Rename the file on disk and commit again.

Synck versions regular files and folders only. A symbolic link in the working copy stops status and commit with unsupported filesystem entry. Remove the link, or add it to .synckignore.