2020-06-22 04:15:24 +00:00
|
|
|
|
.\" 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
|
|
|
|
|
..
|
2021-08-18 05:45:38 +00:00
|
|
|
|
.TH "SYNCTHING-VERSIONING" "7" "Aug 17, 2021" "v1" "Syncthing"
|
2021-04-28 05:45:43 +00:00
|
|
|
|
.SH NAME
|
|
|
|
|
syncthing-versioning \- Keep automatic backups of deleted files by other nodes
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.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
|
|
|
|
|
.SH TRASH CAN FILE VERSIONING
|
|
|
|
|
.sp
|
|
|
|
|
This versioning strategy emulates the common “trash can” approach. When a file
|
2021-02-17 06:45:43 +00:00
|
|
|
|
is deleted or replaced due to a change on a remote device, it is moved to
|
2020-06-22 04:15:24 +00:00
|
|
|
|
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.
|
|
|
|
|
.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.
|
|
|
|
|
.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.
|
|
|
|
|
.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
|
2021-05-19 05:45:35 +00:00
|
|
|
|
For the first hour, the oldest version in every 30\-seconds interval is
|
|
|
|
|
kept.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.TP
|
|
|
|
|
.B 1 Day
|
2021-05-19 05:45:35 +00:00
|
|
|
|
For the first day, the oldest version in every hour is kept.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.TP
|
|
|
|
|
.B 30 Days
|
2021-05-19 05:45:35 +00:00
|
|
|
|
For the first 30 days, the oldest version in every day is kept.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.TP
|
|
|
|
|
.B Until Maximum Age
|
2021-05-19 05:45:35 +00:00
|
|
|
|
Until maximum age, the oldest version in every week is kept.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.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.
|
|
|
|
|
\fBNote: Set to 0 to keep versions forever.\fP
|
|
|
|
|
.UNINDENT
|
2021-05-19 05:45:35 +00:00
|
|
|
|
.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 \fI\%unit test file\fP <\fBhttps://github.com/syncthing/syncthing/blob/main/lib/versioner/staggered_test.go#L32\fP>
|
|
|
|
|
that shows which versions are deleted for a specific run.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.SH EXTERNAL FILE VERSIONING
|
|
|
|
|
.sp
|
2021-03-10 06:45:45 +00:00
|
|
|
|
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:
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.INDENT 0.0
|
|
|
|
|
.TP
|
|
|
|
|
.B %FOLDER_PATH%
|
|
|
|
|
Path to the folder
|
|
|
|
|
.TP
|
|
|
|
|
.B %FILE_PATH%
|
|
|
|
|
Path to the file within the folder
|
|
|
|
|
.UNINDENT
|
2021-03-10 06:45:45 +00:00
|
|
|
|
.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\&.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.SS Example for Unixes
|
|
|
|
|
.sp
|
2021-03-10 06:45:45 +00:00
|
|
|
|
Let’s say I want to keep the latest version of each file as they are replaced
|
2020-06-22 04:15:24 +00:00
|
|
|
|
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
|
|
|
|
|
.nf
|
|
|
|
|
.ft C
|
|
|
|
|
#!/bin/sh
|
|
|
|
|
set \-eu
|
|
|
|
|
|
|
|
|
|
# Where I want my versions stored
|
|
|
|
|
versionspath=~/.trashcan
|
|
|
|
|
|
|
|
|
|
# The parameters we get from Syncthing
|
|
|
|
|
folderpath="$1"
|
|
|
|
|
filepath="$2"
|
|
|
|
|
|
|
|
|
|
# First ensure the dir where we need to store the file exists
|
2021-03-10 06:45:45 +00:00
|
|
|
|
outpath=$(dirname "$versionspath/$filepath")
|
2020-06-22 04:15:24 +00:00
|
|
|
|
mkdir \-p "$outpath"
|
|
|
|
|
# Then move the file there
|
|
|
|
|
mv \-f "$folderpath/$filepath" "$versionspath/$filepath"
|
|
|
|
|
.ft P
|
|
|
|
|
.fi
|
|
|
|
|
.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
|
2021-03-10 06:45:45 +00:00
|
|
|
|
Let’s assume I have a folder “default” in ~/Sync, and that within that folder
|
2020-06-22 04:15:24 +00:00
|
|
|
|
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
|
|
|
|
|
.nf
|
|
|
|
|
.ft C
|
|
|
|
|
$ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
|
|
|
|
|
.ft P
|
|
|
|
|
.fi
|
|
|
|
|
.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.
|
2021-03-17 06:45:40 +00:00
|
|
|
|
.SS Examples for Windows
|
|
|
|
|
.SS Move to a given folder using the command prompt (CMD)
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.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
|
|
|
|
|
.nf
|
|
|
|
|
.ft C
|
|
|
|
|
@echo off
|
|
|
|
|
|
2021-02-17 06:45:43 +00:00
|
|
|
|
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
|
2020-06-22 04:15:24 +00:00
|
|
|
|
setlocal EnableExtensions
|
|
|
|
|
|
2021-02-17 06:45:43 +00:00
|
|
|
|
rem Where I want my versions stored
|
|
|
|
|
set "VERSIONS_PATH=%USERPROFILE%\e.trashcan"
|
2020-06-22 04:15:24 +00:00
|
|
|
|
|
2021-02-17 06:45:43 +00:00
|
|
|
|
rem The parameters we get from Syncthing, \(aq~\(aq removes quotes if any
|
|
|
|
|
set "FOLDER_PATH=%~1"
|
|
|
|
|
set "FILE_PATH=%~2"
|
2020-06-22 04:15:24 +00:00
|
|
|
|
|
2021-02-17 06:45:43 +00:00
|
|
|
|
rem First ensure the dir where we need to store the file exists
|
|
|
|
|
for %%F in ("%VERSIONS_PATH%\e%FILE_PATH%") do set "OUTPUT_PATH=%%~dpF"
|
|
|
|
|
if not exist "%OUTPUT_PATH%" md "%OUTPUT_PATH%" || exit /B
|
2020-06-22 04:15:24 +00:00
|
|
|
|
|
2021-02-17 06:45:43 +00:00
|
|
|
|
rem Finally move the file, overwrite existing file if any
|
2020-06-22 04:15:24 +00:00
|
|
|
|
move /Y "%FOLDER_PATH%\e%FILE_PATH%" "%VERSIONS_PATH%\e%FILE_PATH%"
|
|
|
|
|
.ft P
|
|
|
|
|
.fi
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.sp
|
2021-03-17 06:45:40 +00:00
|
|
|
|
Finally, I set \fB"C:\eUsers\emfrnd\eScripts\eonlylatest.bat" "%FOLDER_PATH%"
|
|
|
|
|
"%FILE_PATH%"\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
|
|
|
|
|
.nf
|
|
|
|
|
.ft C
|
|
|
|
|
# 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 ("Recycled " + $args + ".")
|
|
|
|
|
}
|
|
|
|
|
.ft P
|
|
|
|
|
.fi
|
|
|
|
|
.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
|
|
|
|
|
.nf
|
|
|
|
|
.ft C
|
|
|
|
|
# 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) + "\e~syncthing~" + (Split\-Path \-Path $args \-Leaf) + ".tmp")) {
|
|
|
|
|
[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,\(aqOnlyErrorDialogs\(aq,\(aqDeletePermanently\(aq)
|
|
|
|
|
if ($?) {
|
|
|
|
|
Write\-Output ("Deleted " + $args + ".")
|
|
|
|
|
}
|
|
|
|
|
} else {
|
|
|
|
|
[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,\(aqOnlyErrorDialogs\(aq,\(aqSendToRecycleBin\(aq)
|
|
|
|
|
if ($?) {
|
|
|
|
|
Write\-Output ("Recycled " + $args + ".")
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
.ft P
|
|
|
|
|
.fi
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.UNINDENT
|
|
|
|
|
.sp
|
|
|
|
|
Finally, we set the command name in Syncthing to \fBpowershell.exe
|
|
|
|
|
\-ExecutionPolicy Bypass \-File "C:\eUsers\eUser\eScripts\eSendToRecycleBin.ps1"
|
|
|
|
|
"%FOLDER_PATH%\e%FILE_PATH%"\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.
|
2020-06-22 04:15:24 +00:00
|
|
|
|
.SH AUTHOR
|
|
|
|
|
The Syncthing Authors
|
|
|
|
|
.SH COPYRIGHT
|
|
|
|
|
2014-2019, The Syncthing Authors
|
|
|
|
|
.\" Generated by docutils manpage writer.
|
|
|
|
|
.
|