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       a  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
33       removed 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
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

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
58       interpreted 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 most recent version  is  kept  every  30
64              seconds.
65
66       1 Day  For the first day, the most recent version is kept every hour.
67
68       30 Days
69              For  the  first  30  days, the most recent version is kept every
70              day.
71
72       Until Maximum Age
73              Until maximum age, the most recent version is kept every week.
74
75       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

EXTERNAL FILE VERSIONING

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
87       %FOLDER_PATH%
88              Path to the folder
89
90       %FILE_PATH%
91              Path to the file within the folder
92
93   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
100          #!/bin/sh
101          set -eu
102
103          # Where I want my versions stored
104          versionspath=~/.trashcan
105
106          # The parameters we get from Syncthing
107          folderpath="$1"
108          filepath="$2"
109
110          # 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
116       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
120       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
125          $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
126
127       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
131   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
136          @echo off
137
138          :: We need command extensions for mkdir to create intermediate folders in one go
139          setlocal EnableExtensions
140
141          :: Where I want my versions stored
142          set VERSIONS_PATH=%USERPROFILE%\.trashcan
143
144          :: The parameters we get from Syncthing, '~' removes quotes if any
145          set FOLDER_PATH=%~1
146          set FILE_PATH=%~2
147
148          :: First ensure the dir where we need to store the file exists
149          for %%F in ("%VERSIONS_PATH%\%FILE_PATH%") do set OUTPUT_PATH=%%~dpF
150          if not exist "%OUTPUT_PATH%" mkdir "%OUTPUT_PATH%" || exit /B
151
152          :: Finally move the file, overwrite existing file if any
153          move /Y "%FOLDER_PATH%\%FILE_PATH%" "%VERSIONS_PATH%\%FILE_PATH%"
154
155       Finally,   I  set  C:\Users\mfrnd\Scripts\onlylatest.bat  %FOLDER_PATH%
156       %FILE_PATH% as command name in Syncthing.
157

AUTHOR

159       The Syncthing Authors
160
162       2014-2019, The Syncthing Authors
163
164
165
166
167v1                               Mar 17, 2020          SYNCTHING-VERSIONING(7)
Impressum