Files are divided into a list of blocks. The block size varies from 128KB to 16MB. Each block will be hashed by a a SHA256 hash.
A block list contain the offset, size and hash of all blocks in the file.
To update a file, Syncthing compare the block list between the versions (on local and from remote devices).
- two methods how Syncthing detects changes
- regular full scans
- notifications received from the filesystem
- By default the watcher is enabled and full scans are done once per hour.
- To make sure that not all folders are rescanned at the same time, the actual scan interval is a random time between 3/4 and 5/4 of the given scan interval
- existing files are checked for changes to their modification time, size or permission bits
- The file is “rehashed” if a change is detected based on those attributes, that is a new block list is calculated for the file.
- The watcher does not immediately schedule a scan when a change is detected.
- accumulates changes for 10s (adjustable by
- ) and deleted files are further delayed for 1min
- slight delay between making the change and it appearing on another device
- Changes that were detected and hashed are transmitted to the other devices after each rescan.
- the version that it currently has on disk, called the local version
- the versions announced by all other connected devices, and the “best” (usually the most recent) version of the file. This version is called the global version
- This information is kept in the index database, which is stored in the configuration directory and called
- When new index data is received from other devices Syncthing recalculates which version for each file should be the global version, and compares this to the current local version
- The block lists are compared to build a list of needed blocks, which are then requested from the network or copied locally, as described above.
- Syncthing does recognize conflicts.
- The file with the older modification time will be marked as the conflicting file and thus be renamed
- If the modification times are equal, the file originating from the device which has the larger value of the first 63 bits for its device ID will be marked as the conflicting file.
- If the conflict is between a modification and a deletion of the file, the modified file always wins
Case Sensitivity in File Names
- Syncthing works with case-sensitive paths, meaning that
- denote two independent things.
- Some operating systems
- can never have both names simultaneously.
- if a remote device shares a file which would clash with an existing local file, it cannot be synchronized to such a system and will be reported as a case conflict by Syncthing
- Syncthing never writes directly to a destination file. Instead all changes are made to a temporary copy which is then moved in place over the old version.
- If an error occurs during the copying or syncing, such as a necessary block not being available, the temporary file is kept around for up to a day.
- The temporary file is normally hidden.