Skip to content

Commit 6591f4e

Browse files
acolombacolomb
authored
users/versioning: Document versioning config parameters (#813)
1 parent 1c15939 commit 6591f4e

File tree

1 file changed

+114
-40
lines changed

1 file changed

+114
-40
lines changed

‎users/versioning.rst

Lines changed: 114 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. default-domain:: stconf
2+
13
File Versioning
24
===============
35

@@ -14,14 +16,12 @@ defaults to "no file versioning", i.e. no old copies of files are kept.
1416
Bob. If Alice changes a file locally on her own computer Syncthing will
1517
not and can not archive the old version.
1618

17-
.. .. stconf:option:: folder.versioning
18-
19-
.. todo:: Describe element attributes!
20-
.. string type = 1[(ext.xml) = "type,attr"];
21-
.. map<string, string> parameters = 2 [(ext.goname) = "Params", (ext.json) = "params"];
22-
.. int32 cleanup_interval_s = 3 [(ext.default) = "3600"];
23-
.. string fs_path = 4 [(ext.goname) = "FSPath"];
24-
.. fs.FilesystemType fs_type = 5 [(ext.goname) = "FSType"];
19+
The applicable configuration options for each versioning strategy are described
20+
below. For most of them it's possible to specify where the versions are stored,
21+
with the default being the ``.stversions`` folder inside the shared folder path.
22+
If you set a custom version path, please ensure that it's on the same partition
23+
or filesystem as the regular folder path, as moving files there may otherwise
24+
fail.
2525

2626
Trash Can File Versioning
2727
-------------------------
@@ -31,38 +31,32 @@ is deleted or replaced due to a change on a remote device, it is moved to
3131
the trash can in the ``.stversions`` folder. If a file with the same name was
3232
already in the trash can it is replaced.
3333

34-
A configuration option is available to clean the trash can from files older
35-
than a specified number of days. If this is set to a positive number of days,
36-
files will be removed when they have been in the trash can that long. Setting
37-
this to zero prevents any files from being removed from the trash can
38-
automatically.
34+
A :opt:`configuration option <folder.versioning.params.cleanoutDays>` is
35+
available to clean the trash can from files older than a specified number of
36+
days. If this is set to a positive number of days, files will be removed when
37+
they have been in the trash can that long. Setting this to zero prevents any
38+
files from being removed from the trash can automatically.
3939

4040
Simple File Versioning
4141
----------------------
4242

43-
With "Simple File Versioning" files are moved to the ``.stversions`` folder
44-
(inside your shared folder) when replaced or deleted on a remote device. This
45-
option also takes a value in an input titled "Keep Versions" which tells
46-
Syncthing how many old versions of the file it should keep. For example, if
47-
you set this value to 5, if a file is replaced 5 times on a remote device, you
48-
will see 5 time-stamped versions on that file in the ".stversions" folder on
49-
the other devices sharing the same folder.
43+
With "Simple File Versioning" files are moved to the ``.stversions`` folder when
44+
replaced or deleted on a remote device. In addition to the
45+
:opt:`~folder.versioning.params.cleanoutDays` option, this strategy also takes a
46+
value in an input titled "Keep Versions" which tells Syncthing how many old
47+
versions of the file it should :opt:`~folder.versioning.params.keep`. For
48+
example, if you set this value to 5, if a file is replaced 5 times on a remote
49+
device, you will see 5 time-stamped versions on that file in the ``.stversions``
50+
folder on the other devices sharing the same folder.
51+
5052

5153
Staggered File Versioning
5254
-------------------------
5355

54-
With "Staggered File Versioning" files are also moved to a different folder
55-
when replaced or deleted on a remote device (just like "Simple File
56-
Versioning"), however, versions are automatically deleted if they are older
57-
than the maximum age or exceed the number of files allowed in an interval.
58-
59-
With this versioning method it's possible to specify where the versions are
60-
stored, with the default being the ``.stversions`` folder inside the normal
61-
folder path. If you set a custom version path, please ensure that it's on the
62-
same partition or filesystem as the regular folder path, as moving files there
63-
may otherwise fail. You can use an absolute path (this is recommended) or a
64-
relative path. Relative paths are interpreted relative to Syncthing's current
65-
or startup directory.
56+
With "Staggered File Versioning" files are also moved to the ``.stversions``
57+
folder when replaced or deleted on a remote device (just like "Simple File
58+
Versioning"), however, versions are automatically deleted if they are older than
59+
the maximum age or exceed the number of files allowed in an interval.
6660

6761
The following intervals are used and they each have a maximum number of files
6862
that will be kept for each.
@@ -78,8 +72,9 @@ Until Maximum Age
7872
Until maximum age, the oldest version in every week is kept.
7973
Maximum Age
8074
The maximum time to keep a version in days. For example, to keep replaced or
81-
deleted files in the ".stversions" folder for an entire year, use 365. If
82-
only for 10 days, use 10.
75+
deleted files in the ``.stversions`` folder for an entire year, use 365. If
76+
only for 10 days, use 10. Corresponds to the
77+
:opt:`~folder.versioning.params.maxAge` option.
8378
**Note: Set to 0 to keep versions forever.**
8479

8580
This means that there is only one version in each interval and as files age they
@@ -94,12 +89,12 @@ that shows which versions are deleted for a specific run.
9489
External File Versioning
9590
------------------------
9691

97-
This versioning method delegates the decision on what to do to an
98-
external command (e.g. a program or a command line script). Just prior
99-
to a file being replaced, the command will be executed. The file needs
100-
to be removed from the folder in the process, or otherwise Syncthing
101-
will report an error. The command can use the following templated
102-
arguments:
92+
This versioning strategy delegates the decision on what to do to an
93+
:opt:`external command <folder.versioning.params.command>` (e.g. a program or a
94+
command line script). Just prior to a file being replaced, the command will be
95+
executed. The file needs to be removed from the folder in the process, or
96+
otherwise Syncthing will report an error. The command can use the following
97+
templated arguments:
10398

10499
..
105100
This to be added when actually relevant.
@@ -249,3 +244,82 @@ The only caveat that you should be aware of is that if your Syncthing
249244
folder is located on a portable storage, such as a USB stick, or if you
250245
have the Recycle Bin disabled, then the script will end up deleting all
251246
files permanently.
247+
248+
Configuration Parameter Reference
249+
---------------------------------
250+
251+
The versioning settings are grouped into their own section of each folder in the
252+
:opt:`configuration file <folder.versioning>`. The following shows an
253+
example of such a section in the XML:
254+
255+
.. code-block:: xml
256+
257+
<folder id="...">
258+
<versioning type="simple">
259+
<cleanupIntervalS>3600</cleanupIntervalS>
260+
<fsPath></fsPath>
261+
<fsType>basic</fsType>
262+
<param key="cleanoutDays" val="0"></param>
263+
<param key="keep" val="5"></param>
264+
</versioning>
265+
</folder>
266+
267+
.. option:: folder.versioning.type
268+
269+
Selects one of the versioning strategies: ``trashcan``, ``simple``,
270+
``staggered``, ``external`` or leave empty to disable versioning completely.
271+
272+
.. option:: folder.versioning.fsPath
273+
274+
Overrides the path where old versions of files are stored and defaults to
275+
``.stversions`` if left empty. An absolute or relative path can be
276+
specified. The latter is interpreted relative to the shared folder path, if
277+
the :opt:`~folder.versioning.fsType` is configured as ``basic``. Ignored
278+
for the ``external`` versioning strategy.
279+
280+
This option used to be stored under the keys ``fsPath`` or ``versionsPath``
281+
in the :opt:`~folder.versioning.params` element.
282+
283+
.. option:: folder.versioning.fsType
284+
285+
The internal file system implementation used to access this versions folder.
286+
Only applies if :opt:`~folder.versioning.fsPath` is also set non-empty,
287+
otherwise the :opt:`~folder.filesystemType` from the folder element is used
288+
instead. Refer to that option description for possible values. Ignored for
289+
the ``external`` versioning strategy.
290+
291+
This option used to be stored under the key ``fsType`` in the
292+
:opt:`~folder.versioning.params` element.
293+
294+
.. option:: folder.versioning.cleanupIntervalS
295+
296+
The interval, in seconds, for running cleanup in the versions folder. Zero
297+
to disable periodic cleaning. Limited to one year (31536000 seconds).
298+
Ignored for the ``external`` versioning strategy.
299+
300+
This option used to be stored under the key ``cleanInterval`` in the
301+
:opt:`~folder.versioning.params` element.
302+
303+
.. option:: folder.versioning.params
304+
305+
Each versioning strategy can have configuration parameters specific to its
306+
implementation under this element.
307+
308+
.. option:: folder.versioning.params.cleanoutDays
309+
310+
The number of days to keep files in the versions folder. Zero means to keep
311+
forever. Older elements encountered during cleanup are removed.
312+
313+
.. option:: folder.versioning.params.keep
314+
315+
The number of old versions to keep, per file.
316+
317+
.. option:: folder.versioning.params.maxAge
318+
319+
The maximum time to keep a version, in seconds. Zero means to keep forever.
320+
321+
.. option:: folder.versioning.params.command
322+
323+
External command to execute for storing a file version about to be replaced
324+
or deleted. If the path to the application contains spaces, it should be
325+
quoted.

0 commit comments

Comments
 (0)