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



NNAAMMEE
       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.

       NNOOTTEE::
          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.

TTRRAASSHH CCAANN FFIILLEE VVEERRSSIIOONNIINNGG
       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 ..ssttvveerrssiioonnss 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.

SSIIMMPPLLEE FFIILLEE VVEERRSSIIOONNIINNGG
       With âSimple File Versioningâ files are moved to the ..ssttvveerrssiioonnss 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.

SSTTAAGGGGEERREEDD FFIILLEE VVEERRSSIIOONNIINNGG
       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 ..ssttvveerrssiioonnss  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.

       11 HHoouurr For the first hour,  the  oldest  version  in  every  30-seconds
              interval is kept.

       11 DDaayy  For the first day, the oldest version in every hour is kept.

       3300 DDaayyss
              For the first 30 days, the oldest version in every day is kept.

       UUnnttiill MMaaxxiimmuumm AAggee
              Until maximum age, the oldest version in every week is kept.

       MMaaxxiimmuumm AAggee
              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.  NNoottee:: SSeett ttoo
              00 ttoo kkeeeepp vveerrssiioonnss ffoorreevveerr..

       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 <hhttttppss::////ggiitthhuubb..ccoomm//ssyynncc‐‐
       tthhiinngg//ssyynncctthhiinngg//bblloobb//mmaaiinn//lliibb//vveerrssiioonneerr//ssttaaggggeerreedd__tteesstt..ggoo##LL3322>     that
       shows which versions are deleted for a specific run.

EEXXTTEERRNNAALL FFIILLEE VVEERRSSIIOONNIINNGG
       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:

       %%FFOOLLDDEERR__PPAATTHH%%
              Path to the folder

       %%FFIILLEE__PPAATTHH%%
              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 SSyynncc folder in Windows, and the full  path  to  the
       file  is  CC::\\UUsseerrss\\UUsseerr\\SSyynncc\\FFaammiillyy pphhoottooss\\IIMMGG__22002211--0033--0011..jjppgg, then the
       %%FFOOLLDDEERR__PPAATTHH%% will be CC::\\UUsseerrss\\UUsseerr\\SSyynncc, and the %%FFIILLEE__PPAATTHH%%  will  be
       FFaammiillyy pphhoottooss\\IIMMGG__22002211--0033--0011..jjppgg.

   EExxaammppllee ffoorr UUnniixxeess
       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
       //UUsseerrss//jjbb//bbiinn//oonnllyyllaatteesstt..sshh (i.e. the bbiinn 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 (cchhmmoodd 775555 oonnllyy‐‐
       llaatteesstt..sshh), then configure Syncthing with  command  //UUsseerrss//jjbb//bbiinn//oonnllyy‐‐
       llaatteesstt..sshh %%FFOOLLDDEERR__PPAATTHH%% %%FFIILLEE__PPAATTHH%%

       Letâs  assume I have a folder âdefaultâ in ~/Sync, and that within that
       folder there is a  file  ddooccss//lleetttteerr..ttxxtt  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 ~~//..ttrraasshhccaann//ddooccss//lleett‐‐
       tteerr..ttxxtt, replacing any previous version of that letter that may already
       have been there.

   EExxaammpplleess ffoorr WWiinnddoowwss
   MMoovvee ttoo aa ggiivveenn ffoollddeerr uussiinngg tthhee ccoommmmaanndd pprroommpptt ((CCMMDD))
       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 CC::\\UUsseerrss\\mmffrrnndd\\SSccrriippttss\\oonnllyyllaatteesstt..bbaatt.

          @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 ""CC::\\UUsseerrss\\mmffrrnndd\\SSccrriippttss\\oonnllyyllaatteesstt..bbaatt""  ""%%FFOOLLDDEERR__PPAATTHH%%""
       ""%%FFIILLEE__PPAATTHH%%"" as the command name in Syncthing.

   MMoovvee ttoo tthhee RReeccyyccllee BBiinn uussiinngg PPoowweerrSShheellll
       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. CC::\\UUsseerrss\\UUsseerr\\SSccrriippttss\\SSeennddTTooRReeccyycclleeBBiinn..ppss11.

          # 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 ppoowweerrsshheellll..eexxee --EExxeeccuu‐‐
       ttiioonnPPoolliiccyy  BByyppaassss  --FFiillee  ""CC::\\UUsseerrss\\UUsseerr\\SSccrriippttss\\SSeennddTTooRReeccyycclleeBBiinn..ppss11""
       ""%%FFOOLLDDEERR__PPAATTHH%%\\%%FFIILLEE__PPAATTHH%%"".

       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.

AAUUTTHHOORR
       The Syncthing Authors

CCOOPPYYRRIIGGHHTT
       2014-2019, The Syncthing Authors



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