SYNCTHING-VERSIONING(7)            Syncthing           SYNCTHING-VERSIONING(7)



NNAAMMEE
       syncthing-versioning - Keep automatic backups of deleted files by other
       nodes

       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  _v_e_r_s_i_o_n_i_n_g
       _s_t_r_a_t_e_g_i_e_s  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.

       NNOOTTEE::
          Versioning  applies to changes received _f_r_o_m _o_t_h_e_r _d_e_v_i_c_e_s. 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.

TTRRAASSHH CCAANN FFIILLEE VVEERRSSIIOONNIINNGG
       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 ..ssttvveerrssiioonnss folder. If a file with the
       same name was already in the trash can it is replaced.

       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.

SSIIMMPPLLEE FFIILLEE VVEERRSSIIOONNIINNGG
       With âSimple File Versioningâ files are moved to the ..ssttvveerrssiioonnss folder
       (inside  your  shared  folder)  when  replaced  or  deleted on a remote
       device. This option also takes a value in an input  titled  âKeep  Ver‐
       sionsâ  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 ver‐
       sions on that file in the â.stversionsâ folder  on  the  other  devices
       sharing the same folder.

SSTTAAGGGGEERREEDD FFIILLEE VVEERRSSIIOONNIINNGG
       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.

       With this versioning method itâs possible to specify where the versions
       are stored, with the default being the ..ssttvveerrssiioonnss  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.

       The following intervals are used and they each have a maximum number of
       files that will be kept for each.

       11 HHoouurr For the first hour,  the  oldest  version  in  every  30-seconds
              interval is kept.

       11 DDaayy  For the first day, the oldest version in every hour is kept.

       3300 DDaayyss
              For the first 30 days, the oldest version in every day is kept.

       UUnnttiill MMaaxxiimmuumm AAggee
              Until maximum age, the oldest version in every week is kept.

       MMaaxxiimmuumm AAggee
              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.  NNoottee:: SSeett ttoo
              00 ttoo kkeeeepp vveerrssiioonnss ffoorreevveerr..

       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.

       For  more  info,  check  the  _u_n_i_t  _t_e_s_t _f_i_l_e <hhttttppss::////ggiitthhuubb..ccoomm//ssyynncc‐‐
       tthhiinngg//ssyynncctthhiinngg//bblloobb//mmaaiinn//lliibb//vveerrssiioonneerr//ssttaaggggeerreedd__tteesstt..ggoo##LL3322>     that
       shows which versions are deleted for a specific run.

EEXXTTEERRNNAALL FFIILLEE VVEERRSSIIOONNIINNGG
       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 argu‐
       ments:

       %%FFOOLLDDEERR__PPAATTHH%%
              Path to the folder

       %%FFIILLEE__PPAATTHH%%
              Path to the file within the folder

       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 SSyynncc folder in Windows, and the full  path  to  the
       file  is  CC::\\UUsseerrss\\UUsseerr\\SSyynncc\\FFaammiillyy pphhoottooss\\IIMMGG__22002211--0033--0011..jjppgg, then the
       %%FFOOLLDDEERR__PPAATTHH%% will be CC::\\UUsseerrss\\UUsseerr\\SSyynncc, and the %%FFIILLEE__PPAATTHH%%  will  be
       FFaammiillyy pphhoottooss\\IIMMGG__22002211--0033--0011..jjppgg.

   EExxaammppllee ffoorr UUnniixxeess
       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
       //UUsseerrss//jjbb//bbiinn//oonnllyyllaatteesstt..sshh (i.e. the bbiinn directory in my  home  direc‐
       tory):

          #!/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
          outpath=$(dirname "$versionspath/$filepath")
          mkdir -p "$outpath"
          # Then move the file there
          mv -f "$folderpath/$filepath" "$versionspath/$filepath"

       I  must ensure that the script has execute permissions (cchhmmoodd 775555 oonnllyy‐‐
       llaatteesstt..sshh), then configure Syncthing with  command  //UUsseerrss//jjbb//bbiinn//oonnllyy‐‐
       llaatteesstt..sshh %%FFOOLLDDEERR__PPAATTHH%% %%FFIILLEE__PPAATTHH%%

       Letâs  assume I have a folder âdefaultâ in ~/Sync, and that within that
       folder there is a  file  ddooccss//lleetttteerr..ttxxtt  that  is  being  replaced  or
       deleted.  The  script  will be called as if I ran this from the command
       line:

          $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt

       The script will then move the file in question to ~~//..ttrraasshhccaann//ddooccss//lleett‐‐
       tteerr..ttxxtt, replacing any previous version of that letter that may already
       have been there.

   EExxaammpplleess ffoorr WWiinnddoowwss
   MMoovvee ttoo aa ggiivveenn ffoollddeerr uussiinngg tthhee ccoommmmaanndd pprroommpptt ((CCMMDD))
       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 CC::\\UUsseerrss\\mmffrrnndd\\SSccrriippttss\\oonnllyyllaatteesstt..bbaatt.

          @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 "versions_path=%USERPROFILE%\.trashcan"

          rem The parameters we get from Syncthing, '~' removes quotes if any
          set "folder_path=%~1"
          set "file_path=%~2"

          rem First ensure the dir where we need to store the file exists
          for %%f in ("%versions_path%\%file_path%") do set "output_path=%%~dpf"
          if not exist "%output_path%" md "%output_path%" || exit /b

          rem Finally move the file, overwrite existing file if any
          move /y "%folder_path%\%file_path%" "%versions_path%\%file_path%"

       Finally, I set ""CC::\\UUsseerrss\\mmffrrnndd\\SSccrriippttss\\oonnllyyllaatteesstt..bbaatt""  ""%%FFOOLLDDEERR__PPAATTHH%%""
       ""%%FFIILLEE__PPAATTHH%%"" as the command name in Syncthing.

   MMoovvee ttoo tthhee RReeccyyccllee BBiinn uussiinngg PPoowweerrSShheellll
       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. CC::\\UUsseerrss\\UUsseerr\\SSccrriippttss\\SSeennddTTooRReeccyycclleeBBiinn..ppss11.

          # 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's DEBUG output.
          Add-Type -AssemblyName Microsoft.VisualBasic
          [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','SendToRecycleBin')
          if ($?) {
            Write-Output ("Recycled " + $args + ".")
          }

       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.

          # 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's DEBUG output.
          if (Test-Path -LiteralPath ((Split-Path -Path $args) + "\~syncthing~" + (Split-Path -Path $args -Leaf) + ".tmp")) {
            [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','DeletePermanently')
            if ($?) {
              Write-Output ("Deleted " + $args + ".")
            }
          } else {
            [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($args,'OnlyErrorDialogs','SendToRecycleBin')
            if ($?) {
              Write-Output ("Recycled " + $args + ".")
            }
          }

       Finally, we set the command name in Syncthing to ppoowweerrsshheellll..eexxee --EExxeeccuu‐‐
       ttiioonnPPoolliiccyy  BByyppaassss  --FFiillee  ""CC::\\UUsseerrss\\UUsseerr\\SSccrriippttss\\SSeennddTTooRReeccyycclleeBBiinn..ppss11""
       ""%%FFOOLLDDEERR__PPAATTHH%%\\%%FFIILLEE__PPAATTHH%%"".

       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.

AAUUTTHHOORR
       The Syncthing Authors

CCOOPPYYRRIIGGHHTT
       2014-2019, The Syncthing Authors



v1.19.2                          Apr 05, 2022          SYNCTHING-VERSIONING(7)
