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

TRASH CAN FILE VERSIONING

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

SIMPLE FILE VERSIONING

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

STAGGERED FILE VERSIONING

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
45       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
53       The following intervals are used and they each have a maximum number of
54       files that will be kept for each.
55
56       1 Hour For the first hour, the most recent version  is  kept  every  30
57              seconds.
58
59       1 Day  For the first day, the most recent version is kept every hour.
60
61       30 Days
62              For  the  first  30  days, the most recent version is kept every
63              day.
64
65       Until Maximum Age
66              Until maximum age, the most recent version is kept every week.
67
68       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

EXTERNAL FILE VERSIONING

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
80       %FOLDER_PATH%
81              Path to the folder
82
83       %FILE_PATH%
84              Path to the file within the folder
85
86   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
93          #!/bin/sh
94          set -eu
95
96          # Where I want my versions stored
97          versionspath=~/.trashcan
98
99          # The parameters we get from Syncthing
100          folderpath="$1"
101          filepath="$2"
102
103          # 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
109       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
113       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
118          $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
119
120       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
124   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
129          @echo off
130
131          :: We need command extensions for mkdir to create intermediate folders in one go
132          setlocal EnableExtensions
133
134          :: Where I want my versions stored
135          set VERSIONS_PATH=%USERPROFILE%\.trashcan
136
137          :: The parameters we get from Syncthing, '~' removes quotes if any
138          set FOLDER_PATH=%~1
139          set FILE_PATH=%~2
140
141          :: 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
145          :: Finally move the file, overwrite existing file if any
146          move /Y "%FOLDER_PATH%\%FILE_PATH%" "%VERSIONS_PATH%\%FILE_PATH%"
147
148       Finally,   I  set  C:\Users\mfrnd\Scripts\onlylatest.bat  %FOLDER_PATH%
149       %FILE_PATH% as command name in Syncthing.
150

AUTHOR

152       The Syncthing Authors
153
155       2014-2019, The Syncthing Authors
156
157
158
159
160v1                               Apr 13, 2019          SYNCTHING-VERSIONING(7)
Impressum