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
17 This versioning strategy emulates the common “trash can” approach. When
18 a file is deleted or replaced due to a change on a remote device, it is
19 a moved to the trash can in the .stversions folder. If a file with the
20 same name was already in the trash can it is replaced.
21 A configuration option is available to clean the trash can from files
23 older than a specified number of days. If this is set to a positive
24 number of days, files will be removed when they have been in the trash
25 can that long. Setting this to zero prevents any files from being
26 removed from the trash can automatically.
27
29 With “Simple File Versioning” files are moved to the .stversions folder
30 (inside your shared folder) when replaced or deleted on a remote
31 device. This option also takes a value in an input titled “Keep Ver‐
32 sions” which tells Syncthing how many old versions of the file it
33 should keep. For example, if you set this value to 5, if a file is
34 replaced 5 times on a remote device, you will see 5 time-stamped ver‐
35 sions on that file in the “.stversions” folder on the other devices
36 sharing the same folder.
37
39 With “Staggered File Versioning” files are also moved to a different
40 folder when replaced or deleted on a remote device (just like “Simple
41 File Versioning”), however, versions are automatically deleted if they
42 are older than the maximum age or exceed the number of files allowed in
43 an interval.
44 With this versioning method it’s possible to specify where the versions
46 are stored, with the default being the .stversions folder inside the
47 normal folder path. If you set a custom version path, please ensure
48 that it’s on the same partition or filesystem as the regular folder
49 path, as moving files there may otherwise fail. You can use an absolute
50 path (this is recommended) or a relative path. Relative paths are
51 interpreted relative to Syncthing’s current or startup directory.
52 The following intervals are used and they each have a maximum number of
54 files that will be kept for each.
55 1 Hour For the first hour, the most recent version is kept every 30
57 seconds.
58 1 Day For the first day, the most recent version is kept every hour.
60 30 Days
62 For the first 30 days, the most recent version is kept every
63 day.
64 Until Maximum Age
66 Until maximum age, the most recent version is kept every week.
67 Maximum Age
69 The maximum time to keep a version in days. For example, to keep
70 replaced or deleted files in the “.stversions” folder for an
71 entire year, use 365. If only for 10 days, use 10. Note: Set to
72 0 to keep versions forever.
73
75 This versioning method delegates the decision on what to do to an
76 external command (program or script). Just prior to a file being
77 replaced, the command will be run. The command should be specified as
78 an absolute path, and can use the following templated arguments:
79 %FOLDER_PATH%
81 Path to the folder
82 %FILE_PATH%
84 Path to the file within the folder
85 Example for Unixes
87 Lets say I want to keep the latest version of each file as they are
88 replaced or removed; essentially I want a “trash can”-like behavior.
89 For this, I create the following script and store it as
90 /Users/jb/bin/onlylatest.sh (i.e. the bin directory in my home direc‐
91 tory):
92 #!/bin/sh
94 set -eu
95 # Where I want my versions stored
97 versionspath=~/.trashcan
98 # The parameters we get from Syncthing
100 folderpath="$1"
101 filepath="$2"
102 # First ensure the dir where we need to store the file exists
104 outpath=`dirname "$versionspath/$filepath"`
105 mkdir -p "$outpath"
106 # Then move the file there
107 mv -f "$folderpath/$filepath" "$versionspath/$filepath"
108 I must ensure that the script has execute permissions (chmod 755 only‐
110 latest.sh), then configure Syncthing with command /Users/jb/bin/only‐
111 latest.sh %FOLDER_PATH% %FILE_PATH%
112 Lets assume I have a folder “default” in ~/Sync, and that within that
114 folder there is a file docs/letter.txt that is being replaced or
115 deleted. The script will be called as if I ran this from the command
116 line:
117 $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
119 The script will then move the file in question to ~/.trashcan/docs/let‐
121 ter.txt, replacing any previous version of that letter that may already
122 have been there.
123 Example for Windows
125 On Windows we can use a batch script to perform the same “trash
126 can”-like behavior as mentioned above. I created the following script
127 and saved it as C:\Users\mfrnd\Scripts\onlylatest.bat.
128 @echo off
130 :: We need command extensions for mkdir to create intermediate folders in one go
132 setlocal EnableExtensions
133 :: Where I want my versions stored
135 set VERSIONS_PATH=%USERPROFILE%\.trashcan
136 :: The parameters we get from Syncthing, '~' removes quotes if any
138 set FOLDER_PATH=%~1
139 set FILE_PATH=%~2
140 :: First ensure the dir where we need to store the file exists
142 for %%F in ("%VERSIONS_PATH%\%FILE_PATH%") do set OUTPUT_PATH=%%~dpF
143 if not exist "%OUTPUT_PATH%" mkdir "%OUTPUT_PATH%" || exit /B
144 :: Finally move the file, overwrite existing file if any
146 move /Y "%FOLDER_PATH%\%FILE_PATH%" "%VERSIONS_PATH%\%FILE_PATH%"
147 Finally, I set C:\Users\mfrnd\Scripts\onlylatest.bat %FOLDER_PATH%
149 %FILE_PATH% as command name in Syncthing.
150
152 The Syncthing Authors
153
155 2014-2019, The Syncthing Authors
156v1 Jun 11, 2019 SYNCTHING-VERSIONING(7)