From 8042bd1a54eeba2fd86516381b6422c3fb7ef727 Mon Sep 17 00:00:00 2001 From: Syncthing Release Automation Date: Mon, 14 Aug 2023 03:45:48 +0000 Subject: [PATCH] gui, man, authors: Update docs, translations, and contributors --- gui/default/assets/lang/lang-de.json | 2 +- man/stdiscosrv.1 | 2 +- man/strelaysrv.1 | 2 +- man/syncthing-bep.7 | 2 +- man/syncthing-config.5 | 2 +- man/syncthing-device-ids.7 | 2 +- man/syncthing-event-api.7 | 2 +- man/syncthing-faq.7 | 2 +- man/syncthing-globaldisco.7 | 2 +- man/syncthing-localdisco.7 | 2 +- man/syncthing-networking.7 | 2 +- man/syncthing-relay.7 | 2 +- man/syncthing-rest-api.7 | 2 +- man/syncthing-security.7 | 2 +- man/syncthing-stignore.5 | 2 +- man/syncthing-versioning.7 | 159 +++++++++++++++++++++------ man/syncthing.1 | 2 +- 17 files changed, 142 insertions(+), 49 deletions(-) diff --git a/gui/default/assets/lang/lang-de.json b/gui/default/assets/lang/lang-de.json index ff7028165..7c32229fe 100644 --- a/gui/default/assets/lang/lang-de.json +++ b/gui/default/assets/lang/lang-de.json @@ -422,7 +422,7 @@ "The interval, in seconds, for running cleanup in the versions directory. Zero to disable periodic cleaning.": "Das Intervall, in Sekunden, zwischen den Bereinigungen im Versionsverzeichnis. Null um das regelmäßige Bereinigen zu deaktivieren.", "The maximum age must be a number and cannot be blank.": "Das Höchstalter muss angegeben werden und eine Zahl sein.", "The maximum time to keep a version (in days, set to 0 to keep versions forever).": "Die längste Zeit, die alte Versionen vorgehalten werden (in Tagen) (0 um alte Versionen für immer zu behalten).", - "The number of days must be a number and cannot be blank.": "Die Anzahl von Versionen muss eine Ganzzahl und darf nicht leer sein.", + "The number of days must be a number and cannot be blank.": "Die Anzahl der Tage muss eine Ganzzahl sein und darf nicht leer sein.", "The number of days to keep files in the trash can. Zero means forever.": "Dauer in Tagen für welche die Dateien aufgehoben werden sollen. 0 bedeutet für immer.", "The number of old versions to keep, per file.": "Anzahl der alten Versionen, die von jeder Datei behalten werden sollen.", "The number of versions must be a number and cannot be blank.": "Die Anzahl von Versionen muss eine Ganzzahl und darf nicht leer sein.", diff --git a/man/stdiscosrv.1 b/man/stdiscosrv.1 index 1078e1122..5e45605c8 100644 --- a/man/stdiscosrv.1 +++ b/man/stdiscosrv.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "STDISCOSRV" "1" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "STDISCOSRV" "1" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME stdiscosrv \- Syncthing Discovery Server .SH SYNOPSIS diff --git a/man/strelaysrv.1 b/man/strelaysrv.1 index 4ef45d89b..2f6f58626 100644 --- a/man/strelaysrv.1 +++ b/man/strelaysrv.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "STRELAYSRV" "1" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "STRELAYSRV" "1" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME strelaysrv \- Syncthing Relay Server .SH SYNOPSIS diff --git a/man/syncthing-bep.7 b/man/syncthing-bep.7 index b23ca7186..635215c98 100644 --- a/man/syncthing-bep.7 +++ b/man/syncthing-bep.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-BEP" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-BEP" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-bep \- Block Exchange Protocol v1 .SH INTRODUCTION AND DEFINITIONS diff --git a/man/syncthing-config.5 b/man/syncthing-config.5 index afff62816..d6519b6ab 100644 --- a/man/syncthing-config.5 +++ b/man/syncthing-config.5 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-CONFIG" "5" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-CONFIG" "5" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-config \- Syncthing Configuration .SH SYNOPSIS diff --git a/man/syncthing-device-ids.7 b/man/syncthing-device-ids.7 index a492575a9..ef2534561 100644 --- a/man/syncthing-device-ids.7 +++ b/man/syncthing-device-ids.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-DEVICE-IDS" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-DEVICE-IDS" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-device-ids \- Understanding Device IDs .sp diff --git a/man/syncthing-event-api.7 b/man/syncthing-event-api.7 index 9fdc8ae53..6230f1e4a 100644 --- a/man/syncthing-event-api.7 +++ b/man/syncthing-event-api.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-EVENT-API" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-EVENT-API" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-event-api \- Event API .SH DESCRIPTION diff --git a/man/syncthing-faq.7 b/man/syncthing-faq.7 index 0c9bdb662..a5ab7dc77 100644 --- a/man/syncthing-faq.7 +++ b/man/syncthing-faq.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-FAQ" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-FAQ" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-faq \- Frequently Asked Questions .INDENT 0.0 diff --git a/man/syncthing-globaldisco.7 b/man/syncthing-globaldisco.7 index f21b3d227..1150ecc0e 100644 --- a/man/syncthing-globaldisco.7 +++ b/man/syncthing-globaldisco.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-GLOBALDISCO" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-GLOBALDISCO" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-globaldisco \- Global Discovery Protocol v3 .SH ANNOUNCEMENTS diff --git a/man/syncthing-localdisco.7 b/man/syncthing-localdisco.7 index d50ad0997..aa6ac12a9 100644 --- a/man/syncthing-localdisco.7 +++ b/man/syncthing-localdisco.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-LOCALDISCO" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-LOCALDISCO" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-localdisco \- Local Discovery Protocol v4 .SH MODE OF OPERATION diff --git a/man/syncthing-networking.7 b/man/syncthing-networking.7 index aeea4668d..1cd24a467 100644 --- a/man/syncthing-networking.7 +++ b/man/syncthing-networking.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-NETWORKING" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-NETWORKING" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-networking \- Firewall Setup .SH ROUTER SETUP diff --git a/man/syncthing-relay.7 b/man/syncthing-relay.7 index c448cd789..2b9c5f696 100644 --- a/man/syncthing-relay.7 +++ b/man/syncthing-relay.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-RELAY" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-RELAY" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-relay \- Relay Protocol v1 .SH WHAT IS A RELAY? diff --git a/man/syncthing-rest-api.7 b/man/syncthing-rest-api.7 index e1920b132..09cb2890f 100644 --- a/man/syncthing-rest-api.7 +++ b/man/syncthing-rest-api.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-REST-API" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-REST-API" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-rest-api \- REST API .sp diff --git a/man/syncthing-security.7 b/man/syncthing-security.7 index dec0efc18..bf9035666 100644 --- a/man/syncthing-security.7 +++ b/man/syncthing-security.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-SECURITY" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-SECURITY" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-security \- Security Principles .sp diff --git a/man/syncthing-stignore.5 b/man/syncthing-stignore.5 index 901e65c32..da7369af4 100644 --- a/man/syncthing-stignore.5 +++ b/man/syncthing-stignore.5 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-STIGNORE" "5" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-STIGNORE" "5" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-stignore \- Prevent files from being synchronized to other nodes .SH SYNOPSIS diff --git a/man/syncthing-versioning.7 b/man/syncthing-versioning.7 index 02858ece5..bf893ceba 100644 --- a/man/syncthing-versioning.7 +++ b/man/syncthing-versioning.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING-VERSIONING" "7" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING-VERSIONING" "7" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing-versioning \- Keep automatic backups of deleted files by other nodes .sp @@ -47,6 +47,13 @@ Bob. If Alice changes a file locally on her own computer Syncthing will not and can not archive the old version. .UNINDENT .UNINDENT +.sp +The applicable configuration options for each versioning strategy are described +below. For most of them it’s possible to specify where the versions are stored, +with the default being the \fB\&.stversions\fP folder inside the shared folder path. +If you set a custom version path, please ensure that it’s on the same partition +or filesystem as the regular folder path, as moving files there may otherwise +fail. .SH TRASH CAN FILE VERSIONING .sp This versioning strategy emulates the common “trash can” approach. When a file @@ -54,34 +61,27 @@ is deleted or replaced due to a change on a remote device, it is moved to the trash can in the \fB\&.stversions\fP folder. If a file with the same name was already in the trash can it is replaced. .sp -A configuration option is available to clean the trash can from files older -than a specified number of days. If this is set to a positive number of days, -files will be removed when they have been in the trash can that long. Setting -this to zero prevents any files from being removed from the trash can -automatically. +A \fI\%configuration option\fP is +available to clean the trash can from files older than a specified number of +days. If this is set to a positive number of days, files will be removed when +they have been in the trash can that long. Setting this to zero prevents any +files from being removed from the trash can automatically. .SH SIMPLE FILE VERSIONING .sp -With “Simple File Versioning” files are moved to the \fB\&.stversions\fP folder -(inside your shared folder) when replaced or deleted on a remote device. This -option also takes a value in an input titled “Keep Versions” which tells -Syncthing how many old versions of the file it should keep. For example, if -you set this value to 5, if a file is replaced 5 times on a remote device, you -will see 5 time\-stamped versions on that file in the “.stversions” folder on -the other devices sharing the same folder. +With “Simple File Versioning” files are moved to the \fB\&.stversions\fP folder when +replaced or deleted on a remote device. In addition to the +\fI\%cleanoutDays\fP option, this strategy also takes a +value in an input titled “Keep Versions” which tells Syncthing how many old +versions of the file it should \fI\%keep\fP\&. For +example, if you set this value to 5, if a file is replaced 5 times on a remote +device, you will see 5 time\-stamped versions on that file in the \fB\&.stversions\fP +folder on the other devices sharing the same folder. .SH STAGGERED FILE VERSIONING .sp -With “Staggered File Versioning” files are also moved to a different folder -when replaced or deleted on a remote device (just like “Simple File -Versioning”), however, versions are automatically deleted if they are older -than the maximum age or exceed the number of files allowed in an interval. -.sp -With this versioning method it’s possible to specify where the versions are -stored, with the default being the \fB\&.stversions\fP folder inside the normal -folder path. If you set a custom version path, please ensure that it’s on the -same partition or filesystem as the regular folder path, as moving files there -may otherwise fail. You can use an absolute path (this is recommended) or a -relative path. Relative paths are interpreted relative to Syncthing’s current -or startup directory. +With “Staggered File Versioning” files are also moved to the \fB\&.stversions\fP +folder when replaced or deleted on a remote device (just like “Simple File +Versioning”), however, versions are automatically deleted if they are older than +the maximum age or exceed the number of files allowed in an interval. .sp The following intervals are used and they each have a maximum number of files that will be kept for each. @@ -102,8 +102,9 @@ Until maximum age, the oldest version in every week is kept. .TP .B Maximum Age The maximum time to keep a version in days. For example, to keep replaced or -deleted files in the “.stversions” folder for an entire year, use 365. If -only for 10 days, use 10. +deleted files in the \fB\&.stversions\fP folder for an entire year, use 365. If +only for 10 days, use 10. Corresponds to the +\fI\%maxAge\fP option. \fBNote: Set to 0 to keep versions forever.\fP .UNINDENT .sp @@ -116,12 +117,12 @@ For more info, check the \fI\%unit test file\fP <\fBhttps://github.com/syncthing that shows which versions are deleted for a specific run. .SH EXTERNAL FILE VERSIONING .sp -This versioning method delegates the decision on what to do to an -external command (e.g. a program or a command line script). Just prior -to a file being replaced, the command will be executed. The file needs -to be removed from the folder in the process, or otherwise Syncthing -will report an error. The command can use the following templated -arguments: +This versioning strategy delegates the decision on what to do to an +\fI\%external command\fP (e.g. a program or a +command line script). Just prior to a file being replaced, the command will be +executed. The file needs to be removed from the folder in the process, or +otherwise Syncthing will report an error. The command can use the following +templated arguments: .INDENT 0.0 .TP .B %FOLDER_PATH% @@ -291,6 +292,98 @@ The only caveat that you should be aware of is that if your Syncthing folder is located on a portable storage, such as a USB stick, or if you have the Recycle Bin disabled, then the script will end up deleting all files permanently. +.SH CONFIGURATION PARAMETER REFERENCE +.sp +The versioning settings are grouped into their own section of each folder in the +\fBconfiguration file\fP\&. The following shows an +example of such a section in the XML: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + + 3600 + + basic + + + + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.type +Selects one of the versioning strategies: \fBtrashcan\fP, \fBsimple\fP, +\fBstaggered\fP, \fBexternal\fP or leave empty to disable versioning completely. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.fsPath +Overrides the path where old versions of files are stored and defaults to +\fB\&.stversions\fP if left empty. An absolute or relative path can be +specified. The latter is interpreted relative to the shared folder path, if +the \fI\%fsType\fP is configured as \fBbasic\fP\&. Ignored +for the \fBexternal\fP versioning strategy. +.sp +This option used to be stored under the keys \fBfsPath\fP or \fBversionsPath\fP +in the \fI\%params\fP element. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.fsType +The internal file system implementation used to access this versions folder. +Only applies if \fI\%fsPath\fP is also set non\-empty, +otherwise the \fBfilesystemType\fP from the folder element is used +instead. Refer to that option description for possible values. Ignored for +the \fBexternal\fP versioning strategy. +.sp +This option used to be stored under the key \fBfsType\fP in the +\fI\%params\fP element. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.cleanupIntervalS +The interval, in seconds, for running cleanup in the versions folder. Zero +to disable periodic cleaning. Limited to one year (31536000 seconds). +Ignored for the \fBexternal\fP versioning strategy. +.sp +This option used to be stored under the key \fBcleanInterval\fP in the +\fI\%params\fP element. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.params +Each versioning strategy can have configuration parameters specific to its +implementation under this element. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.params.cleanoutDays +The number of days to keep files in the versions folder. Zero means to keep +forever. Older elements encountered during cleanup are removed. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.params.keep +The number of old versions to keep, per file. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.params.maxAge +The maximum time to keep a version, in seconds. Zero means to keep forever. +.UNINDENT +.INDENT 0.0 +.TP +.B versioning.params.command +External command to execute for storing a file version about to be replaced +or deleted. If the path to the application contains spaces, it should be +quoted. +.UNINDENT .SH AUTHOR The Syncthing Authors .SH COPYRIGHT diff --git a/man/syncthing.1 b/man/syncthing.1 index 9c1071b19..d84c524c3 100644 --- a/man/syncthing.1 +++ b/man/syncthing.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SYNCTHING" "1" "Aug 03, 2023" "v1.23.6" "Syncthing" +.TH "SYNCTHING" "1" "Aug 09, 2023" "v1.23.6" "Syncthing" .SH NAME syncthing \- Syncthing .SH SYNOPSIS