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 The applicable configuration options for each versioning strategy are
24 described below. For most of them it’s possible to specify where the
25 versions are stored, with the default being the .stversions folder in‐
26 side the shared folder path. If you set a custom version path, please
27 ensure that it’s on the same partition or filesystem as the regular
28 folder path, as moving files there may otherwise fail.
29
31 This versioning strategy emulates the common “trash can” approach. When
32 a file is deleted or replaced due to a change on a remote device, it is
33 moved to the trash can in the .stversions folder. If a file with the
34 same name was already in the trash can it is replaced.
35 A configuration option is available to clean the trash can from files
37 older than a specified number of days. If this is set to a positive
38 number of days, files will be removed when they have been in the trash
39 can that long. Setting this to zero prevents any files from being re‐
40 moved from the trash can automatically.
41
43 With “Simple File Versioning” files are moved to the .stversions folder
44 when replaced or deleted on a remote device. In addition to the
45 cleanoutDays option, this strategy also takes a value in an input ti‐
46 tled “Keep Versions” which tells Syncthing how many old versions of the
47 file it should keep. For example, if you set this value to 5, if a
48 file is replaced 5 times on a remote device, you will see 5
49 time-stamped versions on that file in the .stversions folder on the
50 other devices sharing the same folder.
51
53 With “Staggered File Versioning” files are also moved to the .stver‐
54 sions folder when replaced or deleted on a remote device (just like
55 “Simple File Versioning”), however, versions are automatically deleted
56 if they are older than the maximum age or exceed the number of files
57 allowed in an interval.
58 The following intervals are used and they each have a maximum number of
60 files that will be kept for each.
61 1 Hour For the first hour, the oldest version in every 30-seconds in‐
63 terval is kept.
64 1 Day For the first day, the oldest version in every hour is kept.
66 30 Days
68 For the first 30 days, the oldest version in every day is kept.
69 Until Maximum Age
71 Until maximum age, the oldest version in every week is kept.
72 Maximum Age
74 The maximum time to keep a version in days. For example, to keep
75 replaced or deleted files in the .stversions folder for an en‐
76 tire year, use 365. If only for 10 days, use 10. Corresponds to
77 the maxAge option. Note: Set to 0 to keep versions forever.
78 This means that there is only one version in each interval and as files
80 age they will be deleted unless when the interval they are entering is
81 empty. By keeping the oldest versions this versioning scheme preserves
82 the file if it is overwritten.
83 For more info, check the unit test file <https://github.com/sync‐
85 thing/syncthing/blob/main/lib/versioner/staggered_test.go#L32> that
86 shows which versions are deleted for a specific run.
87
89 This versioning strategy delegates the decision on what to do to an
90 external command (e.g. a program or a command line script). Just prior
91 to a file being replaced, the command will be executed. The file needs
92 to be removed from the folder in the process, or otherwise Syncthing
93 will report an error. The command can use the following templated ar‐
94 guments:
95 %FOLDER_PATH%
97 Path to the folder
98 %FILE_PATH%
100 Path to the file within the folder
101 Note that the former expands to the path of the actual Syncthing
103 folder, and the latter to the path inside that folder. For instance, if
104 you use the default Sync folder in Windows, and the full path to the
105 file is C:\Users\User\Sync\Family photos\IMG_2021-03-01.jpg, then the
106 %FOLDER_PATH% will be C:\Users\User\Sync, and the %FILE_PATH% will be
107 Family photos\IMG_2021-03-01.jpg.
108 Example for Unixes
110 Let’s say I want to keep the latest version of each file as they are
111 replaced or removed; essentially I want a “trash can”-like behavior.
112 For this, I create the following script and store it as
113 /Users/jb/bin/onlylatest.sh (i.e. the bin directory in my home direc‐
114 tory):
115 #!/bin/sh
117 set -eu
118 # Where I want my versions stored
120 versionspath=~/.trashcan
121 # The parameters we get from Syncthing
123 folderpath="$1"
124 filepath="$2"
125 # First ensure the dir where we need to store the file exists
127 outpath=$(dirname "$versionspath/$filepath")
128 mkdir -p "$outpath"
129 # Then move the file there
130 mv -f "$folderpath/$filepath" "$versionspath/$filepath"
131 I must ensure that the script has execute permissions (chmod 755 only‐
133 latest.sh), then configure Syncthing with command /Users/jb/bin/only‐
134 latest.sh %FOLDER_PATH% %FILE_PATH%
135 Let’s assume I have a folder “default” in ~/Sync, and that within that
137 folder there is a file docs/letter.txt that is being replaced or
138 deleted. The script will be called as if I ran this from the command
139 line:
140 $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
142 The script will then move the file in question to ~/.trashcan/docs/let‐
144 ter.txt, replacing any previous version of that letter that may already
145 have been there.
146 Examples for Windows
148 Move to a given folder using the command prompt (CMD)
149 On Windows we can use a batch script to perform the same “trash
150 can”-like behavior as mentioned above. I created the following script
151 and saved it as C:\Users\mfrnd\Scripts\onlylatest.bat.
152 @echo off
154 rem Enable UTF-8 encoding to deal with multilingual folder and file names
156 chcp 65001
157 rem We need command extensions for md to create intermediate folders in one go
159 setlocal enableextensions
160 rem Where I want my versions stored
162 set "versions_path=%USERPROFILE%\.trashcan"
163 rem The parameters we get from Syncthing, '~' removes quotes if any
165 set "folder_path=%~1"
166 set "file_path=%~2"
167 rem First ensure the dir where we need to store the file exists
169 for %%f in ("%versions_path%\%file_path%") do set "output_path=%%~dpf"
170 if not exist "%output_path%" md "%output_path%" || exit /b
171 rem Finally move the file, overwrite existing file if any
173 move /y "%folder_path%\%file_path%" "%versions_path%\%file_path%"
174 Finally, I set "C:\Users\mfrnd\Scripts\onlylatest.bat" "%FOLDER_PATH%"
176 "%FILE_PATH%" as the command name in Syncthing.
177 Move to the Recycle Bin using PowerShell
179 We can use PowerShell to send files directly to the Recycle Bin, which
180 mimics the behaviour of deleting them using the Windows Explorer.
181 Firstly, create the following script and save it in your preferred lo‐
182 cation, e.g. C:\Users\User\Scripts\SendToRecycleBin.ps1.
183 # PowerShell has no native method to recycle files, so we use Visual
185 # Basic to perform the operation. If succeeded, we also include the
186 # recycled file in the Syncthing's DEBUG output.
187 Add-Type -AssemblyName Microsoft.VisualBasic
188 [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','SendToRecycleBin')
189 if ($?) {
190 Write-Output ("Recycled " + $args + ".")
191 }
192 Alternatively, the script can be expanded to send only deleted files to
194 the Recycle Bin, and permanently delete modified ones, which makes it
195 more consistent with how the Explorer works.
196 # PowerShell has no native method to recycle files, so we use Visual
198 # Basic to perform the operation.
199 Add-Type -AssemblyName Microsoft.VisualBasic
200 # We need to test if a Syncthing .tmp file exists. If it does, we assume
202 # a modification and delete the existing file. If if does not, we assume
203 # a deletion and recycle the current file. If succeeded, we also include
204 # the deleted/recycled file in the Syncthing's DEBUG output.
205 if (Test-Path -LiteralPath ((Split-Path -Path $args) + "\~syncthing~" + (Split-Path -Path $args -Leaf) + ".tmp")) {
206 [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','DeletePermanently')
207 if ($?) {
208 Write-Output ("Deleted " + $args + ".")
209 }
210 } else {
211 [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','SendToRecycleBin')
212 if ($?) {
213 Write-Output ("Recycled " + $args + ".")
214 }
215 }
216 Finally, we set the command name in Syncthing to powershell.exe -Execu‐
218 tionPolicy Bypass -File "C:\Users\User\Scripts\SendToRecycleBin.ps1"
219 "%FOLDER_PATH%\%FILE_PATH%".
220 The only caveat that you should be aware of is that if your Syncthing
222 folder is located on a portable storage, such as a USB stick, or if you
223 have the Recycle Bin disabled, then the script will end up deleting all
224 files permanently.
225
227 The versioning settings are grouped into their own section of each
228 folder in the configuration file. The following shows an example of
229 such a section in the XML:
230 <folder id="...">
232 <versioning type="simple">
233 <cleanupIntervalS>3600</cleanupIntervalS>
234 <fsPath></fsPath>
235 <fsType>basic</fsType>
236 <param key="cleanoutDays" val="0"></param>
237 <param key="keep" val="5"></param>
238 </versioning>
239 </folder>
240 versioning.type
242 Selects one of the versioning strategies: trashcan, simple,
243 staggered, external or leave empty to disable versioning com‐
244 pletely.
245 versioning.fsPath
247 Overrides the path where old versions of files are stored and
248 defaults to .stversions if left empty. An absolute or relative
249 path can be specified. The latter is interpreted relative to
250 the shared folder path, if the fsType is configured as basic.
251 Ignored for the external versioning strategy.
252 This option used to be stored under the keys fsPath or version‐
254 sPath in the params element.
255 versioning.fsType
257 The internal file system implementation used to access this ver‐
258 sions folder. Only applies if fsPath is also set non-empty,
259 otherwise the filesystemType from the folder element is used in‐
260 stead. Refer to that option description for possible values.
261 Ignored for the external versioning strategy.
262 This option used to be stored under the key fsType in the params
264 element.
265 versioning.cleanupIntervalS
267 The interval, in seconds, for running cleanup in the versions
268 folder. Zero to disable periodic cleaning. Limited to one year
269 (31536000 seconds). Ignored for the external versioning strat‐
270 egy.
271 This option used to be stored under the key cleanInterval in the
273 params element.
274 versioning.params
276 Each versioning strategy can have configuration parameters spe‐
277 cific to its implementation under this element.
278 versioning.params.cleanoutDays
280 The number of days to keep files in the versions folder. Zero
281 means to keep forever. Older elements encountered during
282 cleanup are removed.
283 versioning.params.keep
285 The number of old versions to keep, per file.
286 versioning.params.maxAge
288 The maximum time to keep a version, in seconds. Zero means to
289 keep forever.
290 versioning.params.command
292 External command to execute for storing a file version about to
293 be replaced or deleted. If the path to the application contains
294 spaces, it should be quoted.
295
297 The Syncthing Authors
298
300 2014-2019, The Syncthing Authors
301v1.25.0 Oct 05, 2023 SYNCTHING-VERSIONING(7)