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 re‐
33 moved 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 de‐
38 vice. This option also takes a value in an input titled “Keep Versions”
39 which tells Syncthing how many old versions of the file it should keep.
40 For example, if you set this value to 5, if a file is replaced 5 times
41 on a remote device, you will see 5 time-stamped versions on that file
42 in the “.stversions” folder on the other devices sharing the same
43 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 in‐
58 terpreted 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 en‐
78 tire year, use 365. If only for 10 days, use 10. Note: Set to 0
79 to keep versions forever.
80
82 This versioning method delegates the decision on what to do to an ex‐
83 ternal command (e.g. a program or a command line script). Just prior to
84 a file being replaced, the command will be executed. The file needs to
85 be removed from the folder in the process, or otherwise Syncthing will
86 report an error. The command can use the following templated arguments:
87 %FOLDER_PATH%
89 Path to the folder
90 %FILE_PATH%
92 Path to the file within the folder
93 Note that the former expands to the path of the actual Syncthing
95 folder, and the latter to the path inside that folder. For instance, if
96 you use the default Sync folder in Windows, and the full path to the
97 file is C:\Users\User\Sync\Family photos\IMG_2021-03-01.jpg, then the
98 %FOLDER_PATH% will be C:\Users\User\Sync, and the %FILE_PATH% will be
99 Family photos\IMG_2021-03-01.jpg.
100 Example for Unixes
102 Let’s say I want to keep the latest version of each file as they are
103 replaced or removed; essentially I want a “trash can”-like behavior.
104 For this, I create the following script and store it as
105 /Users/jb/bin/onlylatest.sh (i.e. the bin directory in my home direc‐
106 tory):
107 #!/bin/sh
109 set -eu
110 # Where I want my versions stored
112 versionspath=~/.trashcan
113 # The parameters we get from Syncthing
115 folderpath="$1"
116 filepath="$2"
117 # First ensure the dir where we need to store the file exists
119 outpath=$(dirname "$versionspath/$filepath")
120 mkdir -p "$outpath"
121 # Then move the file there
122 mv -f "$folderpath/$filepath" "$versionspath/$filepath"
123 I must ensure that the script has execute permissions (chmod 755 only‐
125 latest.sh), then configure Syncthing with command /Users/jb/bin/only‐
126 latest.sh %FOLDER_PATH% %FILE_PATH%
127 Let’s assume I have a folder “default” in ~/Sync, and that within that
129 folder there is a file docs/letter.txt that is being replaced or
130 deleted. The script will be called as if I ran this from the command
131 line:
132 $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
134 The script will then move the file in question to ~/.trashcan/docs/let‐
136 ter.txt, replacing any previous version of that letter that may already
137 have been there.
138 Examples for Windows
140 Move to a given folder using the command prompt (CMD)
141 On Windows we can use a batch script to perform the same “trash
142 can”-like behavior as mentioned above. I created the following script
143 and saved it as C:\Users\mfrnd\Scripts\onlylatest.bat.
144 @echo off
146 rem Enable UTF-8 encoding to deal with multilingual folder and file names
148 chcp 65001
149 rem We need command extensions for md to create intermediate folders in one go
151 setlocal EnableExtensions
152 rem Where I want my versions stored
154 set "VERSIONS_PATH=%USERPROFILE%\.trashcan"
155 rem The parameters we get from Syncthing, '~' removes quotes if any
157 set "FOLDER_PATH=%~1"
158 set "FILE_PATH=%~2"
159 rem First ensure the dir where we need to store the file exists
161 for %%F in ("%VERSIONS_PATH%\%FILE_PATH%") do set "OUTPUT_PATH=%%~dpF"
162 if not exist "%OUTPUT_PATH%" md "%OUTPUT_PATH%" || exit /B
163 rem Finally move the file, overwrite existing file if any
165 move /Y "%FOLDER_PATH%\%FILE_PATH%" "%VERSIONS_PATH%\%FILE_PATH%"
166 Finally, I set "C:\Users\mfrnd\Scripts\onlylatest.bat" "%FOLDER_PATH%"
168 "%FILE_PATH%" as the command name in Syncthing.
169 Move to the Recycle Bin using PowerShell
171 We can use PowerShell to send files directly to the Recycle Bin, which
172 mimics the behaviour of deleting them using the Windows Explorer.
173 Firstly, create the following script and save it in your preferred lo‐
174 cation, e.g. C:\Users\User\Scripts\SendToRecycleBin.ps1.
175 # PowerShell has no native method to recycle files, so we use Visual
177 # Basic to perform the operation. If succeeded, we also include the
178 # recycled file in the Syncthing's DEBUG output.
179 Add-Type -AssemblyName Microsoft.VisualBasic
180 [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','SendToRecycleBin')
181 if ($?) {
182 Write-Output ("Recycled " + $args + ".")
183 }
184 Alternatively, the script can be expanded to send only deleted files to
186 the Recycle Bin, and permanently delete modified ones, which makes it
187 more consistent with how the Explorer works.
188 # PowerShell has no native method to recycle files, so we use Visual
190 # Basic to perform the operation.
191 Add-Type -AssemblyName Microsoft.VisualBasic
192 # We need to test if a Syncthing .tmp file exists. If it does, we assume
194 # a modification and delete the existing file. If if does not, we assume
195 # a deletion and recycle the current file. If succeeded, we also include
196 # the deleted/recycled file in the Syncthing's DEBUG output.
197 if (Test-Path -LiteralPath ((Split-Path -Path $args) + "\~syncthing~" + (Split-Path -Path $args -Leaf) + ".tmp")) {
198 [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','DeletePermanently')
199 if ($?) {
200 Write-Output ("Deleted " + $args + ".")
201 }
202 } else {
203 [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','SendToRecycleBin')
204 if ($?) {
205 Write-Output ("Recycled " + $args + ".")
206 }
207 }
208 Finally, we set the command name in Syncthing to powershell.exe -Execu‐
210 tionPolicy Bypass -File "C:\Users\User\Scripts\SendToRecycleBin.ps1"
211 "%FOLDER_PATH%\%FILE_PATH%".
212 The only caveat that you should be aware of is that if your Syncthing
214 folder is located on a portable storage, such as a USB stick, or if you
215 have the Recycle Bin disabled, then the script will end up deleting all
216 files permanently.
217
219 The Syncthing Authors
220
222 2014-2019, The Syncthing Authors
223v1 Apr 15, 2021 SYNCTHING-VERSIONING(7)