1SYNCTHING-VERSIONING(7)            Syncthing           SYNCTHING-VERSIONING(7)
2
3
4

NAME

6       syncthing-versioning - Keep automatic backups of deleted files by other
7       nodes
8
9       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
16       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

TRASH CAN FILE VERSIONING

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
29       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

SIMPLE FILE VERSIONING

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

STAGGERED FILE VERSIONING

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
52       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
60       The following intervals are used and they each have a maximum number of
61       files that will be kept for each.
62
63       1 Hour For the first hour, the oldest version in every  30-seconds  in‐
64              terval is kept.
65
66       1 Day  For the first day, the oldest version in every hour is kept.
67
68       30 Days
69              For the first 30 days, the oldest version in every day is kept.
70
71       Until Maximum Age
72              Until maximum age, the oldest version in every week is kept.
73
74       Maximum Age
75              The maximum time to keep a version in days. For example, to keep
76              replaced or deleted files in the “.stversions” folder for an en‐
77              tire year, use 365. If only for 10 days, use 10.  Note: Set to 0
78              to keep versions forever.
79
80       This means that there is only one version in each interval and as files
81       age  they will be deleted unless when the interval they are entering is
82       empty. By keeping the oldest versions this versioning scheme  preserves
83       the file if it is overwritten.
84
85       For  more  info,  check  the  unit  test file <https://github.com/sync
86       thing/syncthing/blob/main/lib/versioner/staggered_test.go#L32>     that
87       shows which versions are deleted for a specific run.
88

EXTERNAL FILE VERSIONING

90       This  versioning  method delegates the decision on what to do to an ex‐
91       ternal command (e.g. a program or a command line script). Just prior to
92       a  file being replaced, the command will be executed. The file needs to
93       be removed from the folder in the process, or otherwise Syncthing  will
94       report an error. The command can use the following templated arguments:
95
96       %FOLDER_PATH%
97              Path to the folder
98
99       %FILE_PATH%
100              Path to the file within the folder
101
102       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
109   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
116          #!/bin/sh
117          set -eu
118
119          # Where I want my versions stored
120          versionspath=~/.trashcan
121
122          # The parameters we get from Syncthing
123          folderpath="$1"
124          filepath="$2"
125
126          # 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
132       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
136       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
141          $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
142
143       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
147   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
153          @echo off
154
155          rem Enable UTF-8 encoding to deal with multilingual folder and file names
156          chcp 65001
157
158          rem We need command extensions for md to create intermediate folders in one go
159          setlocal enableextensions
160
161          rem Where I want my versions stored
162          set "versions_path=%USERPROFILE%\.trashcan"
163
164          rem The parameters we get from Syncthing, '~' removes quotes if any
165          set "folder_path=%~1"
166          set "file_path=%~2"
167
168          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
172          rem Finally move the file, overwrite existing file if any
173          move /y "%folder_path%\%file_path%" "%versions_path%\%file_path%"
174
175       Finally,  I set "C:\Users\mfrnd\Scripts\onlylatest.bat" "%FOLDER_PATH%"
176       "%FILE_PATH%" as the command name in Syncthing.
177
178   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
184          # 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
193       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
197          # 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
201          # 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
217       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
221       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

AUTHOR

227       The Syncthing Authors
228
230       2014-2019, The Syncthing Authors
231
232
233
234
235v1.22.2                          Dec 29, 2022          SYNCTHING-VERSIONING(7)
Impressum