123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381 |
- .\" Man page generated from reStructuredText.
- .
- .
- .nr rst2man-indent-level 0
- .
- .de1 rstReportMargin
- \\$1 \\n[an-margin]
- level \\n[rst2man-indent-level]
- level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
- -
- \\n[rst2man-indent0]
- \\n[rst2man-indent1]
- \\n[rst2man-indent2]
- ..
- .de1 INDENT
- .\" .rstReportMargin pre:
- . RS \\$1
- . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
- . nr rst2man-indent-level +1
- .\" .rstReportMargin post:
- ..
- .de UNINDENT
- . RE
- .\" indent \\n[an-margin]
- .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
- .nr rst2man-indent-level -1
- .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
- .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
- ..
- .TH "SYNCTHING-VERSIONING" "7" "Sep 04, 2024" "v1.27.11" "Syncthing"
- .SH NAME
- syncthing-versioning \- Keep automatic backups of deleted files by other nodes
- .sp
- Syncthing supports archiving the old version of a file when it is deleted or
- replaced with a newer version from the cluster. This is called “file
- versioning” and uses one of the available \fIversioning strategies\fP described
- below. File versioning is configured per folder, on a per\-device basis, and
- defaults to “no file versioning”, i.e. no old copies of files are kept.
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Versioning applies to changes received \fIfrom other devices\fP\&. That is, if
- Alice has versioning turned on and Bob changes a file, the old version
- will be archived on Alice’s computer when that change is synced from
- 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
- 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 \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 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 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.
- .INDENT 0.0
- .TP
- .B 1 Hour
- For the first hour, the oldest version in every 30\-seconds interval is
- kept.
- .TP
- .B 1 Day
- For the first day, the oldest version in every hour is kept.
- .TP
- .B 30 Days
- For the first 30 days, the oldest version in every day is kept.
- .TP
- .B Until Maximum Age
- 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 \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
- This means that there is only one version in each interval and as files age they
- will be deleted unless when the interval they are entering is empty. By keeping
- the oldest versions this versioning scheme preserves the file if it is
- overwritten.
- .sp
- For more info, check the \X'tty: link https://github.com/syncthing/syncthing/blob/main/lib/versioner/staggered_test.go#L32'\fI\%unit test file\fP <\fBhttps://github.com/syncthing/syncthing/blob/main/lib/versioner/staggered_test.go#L32\fP>\X'tty: link'
- that shows which versions are deleted for a specific run.
- .SH EXTERNAL FILE VERSIONING
- .sp
- 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%
- Path to the folder
- .TP
- .B %FILE_PATH%
- Path to the file within the folder
- .UNINDENT
- .sp
- Note that the former expands to the path of the actual Syncthing folder,
- and the latter to the path inside that folder. For instance, if you use
- the default \fBSync\fP folder in Windows, and the full path to the file is
- \fBC:\eUsers\eUser\eSync\eFamily photos\eIMG_2021\-03\-01.jpg\fP, then the
- \fB%FOLDER_PATH%\fP will be \fBC:\eUsers\eUser\eSync\fP, and the
- \fB%FILE_PATH%\fP will be \fBFamily photos\eIMG_2021\-03\-01.jpg\fP\&.
- .SS Example for Unixes
- .sp
- Let’s say I want to keep the latest version of each file as they are replaced
- or removed; essentially I want a “trash can”\-like behavior. For this, I create
- the following script and store it as \fB/Users/jb/bin/onlylatest.sh\fP (i.e. the
- \fBbin\fP directory in my home directory):
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- #!/bin/sh
- set \-eu
- # Where I want my versions stored
- versionspath=~/.trashcan
- # The parameters we get from Syncthing
- folderpath=\(dq$1\(dq
- filepath=\(dq$2\(dq
- # First ensure the dir where we need to store the file exists
- outpath=$(dirname \(dq$versionspath/$filepath\(dq)
- mkdir \-p \(dq$outpath\(dq
- # Then move the file there
- mv \-f \(dq$folderpath/$filepath\(dq \(dq$versionspath/$filepath\(dq
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- I must ensure that the script has execute permissions (\fBchmod 755
- onlylatest.sh\fP), then configure Syncthing with command \fB/Users/jb/bin/onlylatest.sh %FOLDER_PATH% %FILE_PATH%\fP
- .sp
- Let’s assume I have a folder “default” in ~/Sync, and that within that folder
- there is a file \fBdocs/letter.txt\fP that is being replaced or deleted. The
- script will be called as if I ran this from the command line:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- The script will then move the file in question to
- \fB~/.trashcan/docs/letter.txt\fP, replacing any previous version of that letter
- that may already have been there.
- .SS Examples for Windows
- .SS Move to a given folder using the command prompt (CMD)
- .sp
- On Windows we can use a batch script to perform the same “trash can”\-like
- behavior as mentioned above. I created the following script and saved it as
- \fBC:\eUsers\emfrnd\eScripts\eonlylatest.bat\fP\&.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- @echo off
- rem Enable UTF\-8 encoding to deal with multilingual folder and file names
- chcp 65001
- rem We need command extensions for md to create intermediate folders in one go
- setlocal enableextensions
- rem Where I want my versions stored
- set \(dqversions_path=%USERPROFILE%\e.trashcan\(dq
- rem The parameters we get from Syncthing, \(aq~\(aq removes quotes if any
- set \(dqfolder_path=%~1\(dq
- set \(dqfile_path=%~2\(dq
- rem First ensure the dir where we need to store the file exists
- for %%f in (\(dq%versions_path%\e%file_path%\(dq) do set \(dqoutput_path=%%~dpf\(dq
- if not exist \(dq%output_path%\(dq md \(dq%output_path%\(dq || exit /b
- rem Finally move the file, overwrite existing file if any
- move /y \(dq%folder_path%\e%file_path%\(dq \(dq%versions_path%\e%file_path%\(dq
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Finally, I set \fB\(dqC:\eUsers\emfrnd\eScripts\eonlylatest.bat\(dq \(dq%FOLDER_PATH%\(dq
- \(dq%FILE_PATH%\(dq\fP as the command name in Syncthing.
- .SS Move to the Recycle Bin using PowerShell
- .sp
- We can use PowerShell to send files directly to the Recycle Bin, which
- mimics the behaviour of deleting them using the Windows Explorer.
- Firstly, create the following script and save it in your preferred
- location, e.g. \fBC:\eUsers\eUser\eScripts\eSendToRecycleBin.ps1\fP\&.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- # PowerShell has no native method to recycle files, so we use Visual
- # Basic to perform the operation. If succeeded, we also include the
- # recycled file in the Syncthing\(aqs DEBUG output.
- Add\-Type \-AssemblyName Microsoft.VisualBasic
- [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,\(aqOnlyErrorDialogs\(aq,\(aqSendToRecycleBin\(aq)
- if ($?) {
- Write\-Output (\(dqRecycled \(dq + $args + \(dq.\(dq)
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Alternatively, the script can be expanded to send only deleted files to
- the Recycle Bin, and permanently delete modified ones, which makes it
- more consistent with how the Explorer works.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- # PowerShell has no native method to recycle files, so we use Visual
- # Basic to perform the operation.
- Add\-Type \-AssemblyName Microsoft.VisualBasic
- # We need to test if a Syncthing .tmp file exists. If it does, we assume
- # a modification and delete the existing file. If if does not, we assume
- # a deletion and recycle the current file. If succeeded, we also include
- # the deleted/recycled file in the Syncthing\(aqs DEBUG output.
- if (Test\-Path \-LiteralPath ((Split\-Path \-Path $args) + \(dq\e~syncthing~\(dq + (Split\-Path \-Path $args \-Leaf) + \(dq.tmp\(dq)) {
- [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,\(aqOnlyErrorDialogs\(aq,\(aqDeletePermanently\(aq)
- if ($?) {
- Write\-Output (\(dqDeleted \(dq + $args + \(dq.\(dq)
- }
- } else {
- [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,\(aqOnlyErrorDialogs\(aq,\(aqSendToRecycleBin\(aq)
- if ($?) {
- Write\-Output (\(dqRecycled \(dq + $args + \(dq.\(dq)
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Finally, we set the command name in Syncthing to \fBpowershell.exe
- \-ExecutionPolicy Bypass \-File \(dqC:\eUsers\eUser\eScripts\eSendToRecycleBin.ps1\(dq
- \(dq%FOLDER_PATH%\e%FILE_PATH%\(dq\fP\&.
- .sp
- 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
- \fI\%configuration file\fP\&. The following shows an
- example of such a section in the XML:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- <folder id=\(dq...\(dq>
- <versioning type=\(dqsimple\(dq>
- <cleanupIntervalS>3600</cleanupIntervalS>
- <fsPath></fsPath>
- <fsType>basic</fsType>
- <param key=\(dqcleanoutDays\(dq val=\(dq0\(dq></param>
- <param key=\(dqkeep\(dq val=\(dq5\(dq></param>
- </versioning>
- </folder>
- .EE
- .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 \fI\%filesystemType\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
- 2014-2019, The Syncthing Authors
- .\" Generated by docutils manpage writer.
- .
|