RsyncBack is an addon plugin for Godot 4+, that uses the powerful rsync application that comes installed on Linux/MacOSX and available for Windows, to create fast incremental date-stamped backups versions of your Godot projects with a one click of a button. For more detailed description of rsync click what is rsync?

The main usage for RsyncBack plugin is to be a Godot GUI front end and to make it simple to quickly setup backup your project. Once installed and configured, the plugin can be run with just the click of a button to make date-stamped incremental backups of your project source files. The backups can be to any internal or external drive. Each date-stamped backup is its own folder, having the name [YYYY-MM-DD][HH-MM-SS]. In addition, it saves storage, because the destination will not contain duplicate copies of files that have not been modified, but rather a hardlink to the original. When you check the backup folders, it will look and feel like a complete backup of your source. More on this later.

Note: This plugin, requires the binary rsync min ver. 3.2.4 to be installed on your system. For Linux and MacOSX it should come preinstalled but verify here. Windows click Windows Users. Once verified continue with the steps below.

Install RsyncBack plugin and perform a backup as follows: ( See Uninstall if you wish to remove RsyncBack )

1. Clone directly from Github to the ./addons folder below your project (No git? Click Alternate Download Method):

    cd <your Godot project>
    mkdir addons   # make addons dir if you dont have one
    cd addons
    git clone https://github.com/silocoder/rsyncback.git

2. Open your Godot project and enable the RsyncBack plugin in Godot’s Menu > Project > Project Settings > Plugins. This will display the RsyncBack menu link at the top of the editor.

3. To make a backup, click on the RsyncBack and a configuration screen similar to Fig 1 will open. Here you select the rsync executable path (which may already have been detected), the backup path as well as other options.

Fig 1

4. If rsync is installed (normally part of Linux ad MacOSX) and in the $PATH environment (usually /usr/local/bin/ or /usr/bin/ ), the  label will show the path and version. If not you can manually choose it by clicking on  label see the section below Check if rsync is installed

5. Click on  and pick a folder, to use for backup. At this point you will see your screen changed similar to Fig 2. and the  button enabled.

Fig 2

6. Click on the  and edit any patterns of files you want to exclude from backup. One line per pattern. You can use normal file search patterns.

• Example to exclude .godot, or any .git folders:

    .godot
    .git*

For more info in exclude patterns click here: rsync exclude pattern matching rules

7. To start the backup, click on the Run Rsync button and a popup report will show your project files backed up. The first backup is the longest as the complete project folder is backed up. See example Fig 3.

Fig 3

8. Close the report and click on  label to review your backup and the log file. You should see the backup folders similar to Fig 4

Fig 4

Review the latest backup folder ([YYYY-MM-DD][HH-MM-SS] ) as well as logfiles.

9. Go back to editing your project (e.g. clicking on Script). When ready to backup again click on RsyncBack link to open the plugin screen and then click the  button.  A new report will show only the changed files that were backed up. Clicking on the to review the backups in that folder.

At this point you can repeat step 9 above as many times as you want and new incremental backups will be created. If you need to reset the path configurations, you can click on the label and will allow you to reset to defaults or manually edit the config file in the inspector. If you reset the defaults, you can still reuse the same backup folder and rsync will make a new incremental backup based on any existing backups.

As an example if you were backing up your project /home/user1/godot/tps-demo to a folder /home/user1/godot/godotbackups, then RsyncBack would create a top folder like this: /home/user1/godot/godotbackups/tps-demo-rsync and all backups and logfiles would be found here.

Incremental backup in the case of RsyncBack (which uses rsync), is when the changed files in your project are backed up to a new date-time stamped folder. When rsync runs, it compares the current project to the previous backup. If any files have changed, then a new copy of the files is made to the new backup folder.

In addition hard-links (https://en.wikipedia.org/wiki/Hard_link) are created in that same back up folder to the unchanged files. In essense, your backup folder looks like a complete backup. Every new backup is quick and takes less storage. The backup folders are date-time named stamped. Many backups including RsyncBack work on the basis of using hardlinks to save space and time and make it easy to see your complete backup.

If you look at the latest backup folders they are exact replicas of your project. This means you can just copy the complete folder and open it with Godot.

Rsync is one of the most popular and stable open source backup tools included with Linux and MacOSX (Windows see below Windows Users). It is a terminal run tool with numerous options and arguments for backing up your computer folders incremental/differential, It has been battle tested for years now, is very reliable and has great community support. In its basic form it is a copy/sync tool, in that it copies files from source folder to a destination folder. Rsync backs up files using the native file system of your computer. It does not have its own compressed or proprietary database. You can easily use your File Manager to restore with drag and drop any backup folder or individual files. You can of course view them as regular files using your favorite File Manager. For Linux it could be Dolphin/Nemo/etc and Mac it could be Finder. Or it could be the command line using ls.

Before you begin, check that rsync is installed on your system. You can easily check from the command line by running the following terminal commands:  which rsync to show you the default path or whereis rsync to check if there are more than one installed. RsyncBack requires version 3.2.4 or above. See example below. To choose the desired rsync path, click on the label Rsync Cmd Path

~$ which rsync
/usr/local/bin/rsync

or

~$ whereis rsync
rsync: /usr/bin/rsync /usr/local/bin/rsync /usr/share/rsync /usr/share/man/man1/rsync.1.gz

~$ rsync -V
rsync  version 3.2.7  protocol version 31 Copyright (C) 1996-2022 by Andrew Tridgell, Wayne Davison, and others. .......

Back to installing RsyncBack plugin

The RsyncBack addon is installed as usual with instructions above. However you need to tell it where the rsync.exe command is located. To do that you would need to install MSYS2 which is a list of Linux commands that run native on Windows. An open source consortium called MSYS2 created popular Linux commands that run natively on Windows. There is no need to install Linux to do that!

From their documentation page at https://www.msys2.org/:

• MSYS2 is a collection of tools and libraries providing you with an easy-to-use environment for building, installing and running native Windows software.

Additional docs here: https://www.msys2.org/docs/what-is-msys2/

On your Windows browser, follow this link https://www.msys2.org/#installation: and the instructions to install the msys2 executable.

This will create a native windows folder followed by the path to Linux exe commands. You can then install rsync from the terminal that opens up running the pacman installer as follows:

pacman -S rsync

It then runs natively under Windows with this command:

c:/msys64/usr/bin/rsync.exe

So in this case, you would choose the path above, in the RsyncBack plugin screen, as the path for rsync.

Note: There are a few articles online on how to install MSYS2 and rsync. In fact here is one explaining how to do it if you are using Git. https://tlundberg.com/installing-rsync-on-windows

From the article: If you didn't already know, Git for Windows and its Git Bash environment is built using msys2, but it doesn't include all the binaries from that project.

Back to installing RsyncBack plugin

As we said before, RsyncBack creates an rsync command that incrementally backs up your project to your chosen backup folder. The backup folder will always be called <project name folder>-rsync. Inside this folder the backups are copied with the name [YYYY-MM-DD][HH_MM_SS]. Also the backup folder includes another folder called logfiles, where each backup’s report is kept. See Fig A4 below.

The backup folders are exact ordinary folders of your project. To restore, you can copy or view using your system's File Manager.

Fig A4

Even though it may look to you that in your latest folder the complete project was copied, in fact what you are seeing is an image copy of the previous backup overwritten by the files that are different. This is the power of Linux/Mac file system and it is all done in the background using hardlinks. It allows for efficient disk storage and speed. Rsync does that by comparing your source folder (ie your project folder) with the latest backup then copies the changed files to the destination. The unchanged are hardlinked. The option that does this is --link-dest=”your/last/backup/folder”  See example command below.

In fact every file you create is a hardlink to an inode. If you copy that file to another folder it does not duplicate it. It simply makes a directory entry pointing to what is called an inode. Inodes are beyond the scope of this document, but if you are curious about inodes read this short writeup I found https://albertoalcolea.com/blog/incremental-backups-with-rsync-+-hard-links

A new install of RsyncBack initially reads the choices from a resource file called addons/rsyncback/resource/config.tres ( or if missing, then it makes a copy of default_config.tres). The user then makes the selections and runs the backup. This config.tres can be manually edited in the Inspector. The simplest way to do that is to click on the Config File label link and select Edit In Inspector (Make sure Inspector is showing in the dock). The Godot Inspector will load the config.tres resource file and allow you to make the changes manually and save the config file. Make sure you reload the plugin.

Hover over each of the config.tres properties and read the tooltip for more info. The Rsync Arguments Template is where you would customize further the rsync command options.

It looks similar to this:

{dry_run_argument} -avih --mkpath --stats  \
 --out-format="%M %15'l %5f"  \
 --exclude-from="{exclude_file_path}" \
 --link-dest="{dest_path}/{project_name}/{prev_backup}" \
 --log-file-format="%M %15'l %5f" \
 --log-file="{log_file_path}/{current_datetime}{log_file_suffix}" \
 "{source_path}" \
 "{dest_path}/{project_name}/{current_datetime}"

The curlies {} are properties replaced by RsyncBack when you run the backup. In effect the above becomes this command which is what runs.

/usr/local/bin/rsync  -avih --mkpath --stats  \
 --out-format="%M %15'l %5f"  \
 --exclude-from="/home/user1/godot/tps-demo/addons/rsyncback/exclude.txt" \
 --link-dest="/home/user1/myback/tps-demo-rsync/[2024-10-16][13_22_37]" \
 --log-file-format="%M %15'l %5f" \
 --log-file="/home/user1/myback/tps-demo-rsync/logfiles/[2024-10-18][17_07_35]_log.txt" \
 "/home/user1/godot/tps-demo/" \
 "/home/user1/myback/tps-demo-rsync/[2024-10-18][17_07_35]"

In fact you will see this command in the Rsync Command window. You can click and copy it to the clipboard and run it directly in the command line if you wish!

Notice the rsync command is added from the path you chose. Also {dry_run_argument} is not used in this case since we didn’t check the box. Dry run does not make a backup but simply executes to see if your command is ok. It is always reset back.

You can modify this template anyway you want. E.g. add a remote backup ssh keyfile or add –delete option. Study up on rsync if you plan to customize the template.

(See more https://download.samba.org/pub/rsync/rsync.1#OPTION_SUMMARY):

-avih       # archive-mode, recursive, verbose, human-readable
--mkpath    # create the backup path if it does not exist
--stats     # statistics at the end of the transfer
--out-format=   # Report format 
--link-dest=    # Path to the last backup folder
--log-file-format=  # Log file format, in this case it's same as out-format
--log-file=    # Path to log file
"source code path"  # Your current Godot project path
"backup path"   # The new backup path folder

1. In your browser, navigate to https://github.com/silocoder/rsyncback
2. Making sure master branch is selected, click on the green Code button and select Dowload Zip
3. Save the rsyncback-master.zip file into the ./addons folder of your project.
4. Unzip the zip contents into a folder named ./addons/rsyncback. If you use command line unzip it should look something like:
5. unzip rsyncback-master.zip # unzip master folder
   mv rsyncback-master rsyncback # rename folder to rsyncback
6. Delete the rsyncback-master.zip file

Back to installing RsyncBack plugin

Of course you may want to either disable RsyncBack or completely uninstall it. To disable the plugin click on Godot’s Menu > Project > Project Settings > Plugins and uncheck the RsyncBack box.

To completely remove it, just delete the rsyncback plugin folder inside the addons folder of your project. This will remove the plugin. However any backups are not affected, although you should check that you did not backup anything inside the rsyncback folder you may want to keep.

You may have to restart your project after deleting plugins.

A Godot project typicaly has two folders: res:// for the project, and user:// for runtime data. Only the res:// folder is backed up with this template. You can add the user:// folder to the RsyncBack template if you need to. However you have to hardcode the source path to your user:// folder and then add the project name, something like this below: (ALWAYS TEST ANY CHANGES TO THE TEMPLATE)

{dry_run_argument} -avih --mkpath --stats  \
 --out-format="%M %15'l %5f"  \
 --exclude-from="{exclude_file_path}" \
 --link-dest="{dest_path}/{project_name}/{prev_backup}" \
 --log-file-format="%M %15'l %5f" \
 --log-file="{log_file_path}/{current_datetime}{log_file_suffix}" \
 "{source_path}" "/home/user1/.local/share/godot/app_userdata/Godot Third-Person Shooter Demo" \
 "{dest_path}/{project_name}/{current_datetime}"

Notice the sources line above:

 "{source_path}" "/home/user1/.local/share/godot/app_userdata/Godot Third-Person Shooter Demo" \

the second path is your project's user:// folder. Make sure NOT to ADD a path delimiter (/) at the end so the **user:// ** folder can be create a separate subfolder inside your backup.

TIP: In the same way, you can add a list of other folders to backup. They will all be backed up under the destination path folder.