1SYNCTHING-VERSIONING(7) Syncthing SYNCTHING-VERSIONING(7)
2
6 syncthing-versioning - Keep automatic backups of deleted files by other
7 nodes
8 Syncthing supports archiving the old version of a file when it is
10 deleted or replaced with a newer version from the cluster. This is
11 called “file versioning” and uses one of the available versioning
12 strategies described below. File versioning is configured per folder,
13 on a per-device basis, and defaults to “no file versioning”, i.e. no
14 old copies of files are kept.
15 NOTE:
17 Versioning applies to changes received from other devices. That is,
18 if Alice has versioning turned on and Bob changes a file, the old
19 version will be archived on Alice’s computer when that change is
20 synced from Bob. If Alice changes a file locally on her own computer
21 Syncthing will not and can not archive the old version.
22
24 This versioning strategy emulates the common “trash can” approach. When
25 a file is deleted or replaced due to a change on a remote device, it is
26 moved to the trash can in the .stversions folder. If a file with the
27 same name was already in the trash can it is replaced.
28 A configuration option is available to clean the trash can from files
30 older than a specified number of days. If this is set to a positive
31 number of days, files will be removed when they have been in the trash
32 can that long. Setting this to zero prevents any files from being
33 removed from the trash can automatically.
34
36 With “Simple File Versioning” files are moved to the .stversions folder
37 (inside your shared folder) when replaced or deleted on a remote
38 device. This option also takes a value in an input titled “Keep Ver‐
39 sions” which tells Syncthing how many old versions of the file it
40 should keep. For example, if you set this value to 5, if a file is
41 replaced 5 times on a remote device, you will see 5 time-stamped ver‐
42 sions on that file in the “.stversions” folder on the other devices
43 sharing the same folder.
44
46 With “Staggered File Versioning” files are also moved to a different
47 folder when replaced or deleted on a remote device (just like “Simple
48 File Versioning”), however, versions are automatically deleted if they
49 are older than the maximum age or exceed the number of files allowed in
50 an interval.
51 With this versioning method it’s possible to specify where the versions
53 are stored, with the default being the .stversions folder inside the
54 normal folder path. If you set a custom version path, please ensure
55 that it’s on the same partition or filesystem as the regular folder
56 path, as moving files there may otherwise fail. You can use an absolute
57 path (this is recommended) or a relative path. Relative paths are
58 interpreted relative to Syncthing’s current or startup directory.
59 The following intervals are used and they each have a maximum number of
61 files that will be kept for each.
62 1 Hour For the first hour, the most recent version is kept every 30
64 seconds.
65 1 Day For the first day, the most recent version is kept every hour.
67 30 Days
69 For the first 30 days, the most recent version is kept every
70 day.
71 Until Maximum Age
73 Until maximum age, the most recent version is kept every week.
74 Maximum Age
76 The maximum time to keep a version in days. For example, to keep
77 replaced or deleted files in the “.stversions” folder for an
78 entire year, use 365. If only for 10 days, use 10. Note: Set to
79 0 to keep versions forever.
80
82 This versioning method delegates the decision on what to do to an
83 external command (program or script). Just prior to a file being
84 replaced, the command will be run. The command should be specified as
85 an absolute path, and can use the following templated arguments:
86 %FOLDER_PATH%
88 Path to the folder
89 %FILE_PATH%
91 Path to the file within the folder
92 Example for Unixes
94 Lets say I want to keep the latest version of each file as they are
95 replaced or removed; essentially I want a “trash can”-like behavior.
96 For this, I create the following script and store it as
97 /Users/jb/bin/onlylatest.sh (i.e. the bin directory in my home direc‐
98 tory):
99 #!/bin/sh
101 set -eu
102 # Where I want my versions stored
104 versionspath=~/.trashcan
105 # The parameters we get from Syncthing
107 folderpath="$1"
108 filepath="$2"
109 # First ensure the dir where we need to store the file exists
111 outpath=`dirname "$versionspath/$filepath"`
112 mkdir -p "$outpath"
113 # Then move the file there
114 mv -f "$folderpath/$filepath" "$versionspath/$filepath"
115 I must ensure that the script has execute permissions (chmod 755 only‐
117 latest.sh), then configure Syncthing with command /Users/jb/bin/only‐
118 latest.sh %FOLDER_PATH% %FILE_PATH%
119 Lets assume I have a folder “default” in ~/Sync, and that within that
121 folder there is a file docs/letter.txt that is being replaced or
122 deleted. The script will be called as if I ran this from the command
123 line:
124 $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
126 The script will then move the file in question to ~/.trashcan/docs/let‐
128 ter.txt, replacing any previous version of that letter that may already
129 have been there.
130 Example for Windows
132 On Windows we can use a batch script to perform the same “trash
133 can”-like behavior as mentioned above. I created the following script
134 and saved it as C:\Users\mfrnd\Scripts\onlylatest.bat.
135 @echo off
137 rem Enable UTF-8 encoding to deal with multilingual folder and file names
139 chcp 65001
140 rem We need command extensions for md to create intermediate folders in one go
142 setlocal EnableExtensions
143 rem Where I want my versions stored
145 set "VERSIONS_PATH=%USERPROFILE%\.trashcan"
146 rem The parameters we get from Syncthing, '~' removes quotes if any
148 set "FOLDER_PATH=%~1"
149 set "FILE_PATH=%~2"
150 rem First ensure the dir where we need to store the file exists
152 for %%F in ("%VERSIONS_PATH%\%FILE_PATH%") do set "OUTPUT_PATH=%%~dpF"
153 if not exist "%OUTPUT_PATH%" md "%OUTPUT_PATH%" || exit /B
154 rem Finally move the file, overwrite existing file if any
156 move /Y "%FOLDER_PATH%\%FILE_PATH%" "%VERSIONS_PATH%\%FILE_PATH%"
157 Finally, I set C:\Users\mfrnd\Scripts\onlylatest.bat %FOLDER_PATH%
159 %FILE_PATH% as command name in Syncthing.
160
162 The Syncthing Authors
163
165 2014-2019, The Syncthing Authors
166v1 Feb 17, 2021 SYNCTHING-VERSIONING(7)