RsyncUI is a macOS application developed using Swift and SwiftUI, designed for macOS Sonoma and subsequent versions. It leverages the command-line tool rsync for file synchronization. Notably, rsync executes the synchronization tasks, while RsyncUI provides a graphical user interface (GUI) on top of rsync.
RsyncUI is a complimentary and open-source application. Kindly review the MIT license before commencing to use RsyncUI. RsyncUI is 100% open-source software and will always remain free.
RsyncUI is digitally signed and notarized by Apple, ensuring its security and preventing malicious code and tampering. However, RsyncUI is not sandboxed, which is a requirement for macOS applications on the Apple App Store. The App Sandbox imposes certain restrictions on the functionality of an application within its environment. A sandboxed app cannot read hidden directories such as .ssh or .rsyncosx from the user’s home directory. Additionally, it cannot use rsync installed by Homebrew. Sandboxing RsyncUI would render it ineffective.
Privacy statement
RsyncUI is a desktop application only, there is no server component. It does not generate any logs that are transmitted from your Mac. Data pertaining to tasks and logs is stored locally on your Mac as files. You can backup all files created by RsyncUI to the Document directory on your Mac from the Settings view. The sole data transferred from your Mac to a server occurs only if you enable tasks with a remote server destination. You bear sole responsibility for securing your own data if synchronized to a remote server.
Changelog and Installation
For the most up-to-date information, please refer to the changelog. RsyncUI is constructed as a Universal macOS Binary, ensuring native execution on Apple Silicon and Intel-based Mac computers.
RsyncUI can be installed via Homebrew or downloaded from GitHub.
brew install --cask rsyncui
If installed via Homebrew, the SHA-256 hash is automatically verified. For downloads from GitHub, please verify the SHA-256 hash manually.
1 - Important
Before commencing the use of RsyncUI, it is imperative to thoroughly comprehend the following key notes. This section specifically highlights the most crucial ones.
The User Interface of RsyncUI may pose challenges for users unfamiliar with the rsync command-line tool. The primary objective is to simplify the usage of rsync, rather than providing a comprehensive introduction to rsync for macOS users. This scope is beyond the intended purpose of the interface.
Not a backup tool for everyone
RsyncUI is a specialized application designed exclusively for backup and secure file management. It operates in conjunction with the command-line tool rsync, which is responsible for the actual synchronization process. If you are seeking a comprehensive backup solution that can create a complete image of your drive for restoration in the event of a catastrophic event, RsyncUI is not the appropriate tool for your needs.
Delete parameter
The –delete parameter, herein referred to as the delete parameter, enables rsync to maintain absolute synchronization between the source and destination directories. When a file is deleted from the source, the delete parameter instructs rsync to delete the corresponding file from the destination. Conversely, if the delete parameter is disabled, the destination directory will contain additional data after deleting files from the source.
Therefore, it is crucial to ascertain whether the delete parameter is enabled or disabled. Enabling the delete parameter ensures complete synchronization between the source and destination directories.
As a safety precaution, the –delete parameter is not set as a default parameter when adding new tasks. To ensure that the source and destination are in complete synchronization, the –delete parameter must be enabled.
How to remove and add the delete parameter
Select Rsync parameters from the primary Sidebar menu. Select the task for which you want to add or remove the --delete parameter. Then toggle Add –delete parameter (ON means added). After toggling, remember to update the task.
if ON, the –delete parameter is included
if OFF, the –delete parameter is removed
Verify all new tasks
Before executing a new task in RsyncUI, please perform an estimation run, a –dry-run, and inspect the result. If you inadvertently set an empty directory as the source and the delete parameter is enabled, rsync will delete all files in the destination.
Setting incorrect parameters for rsync can result in the deletion of data. Furthermore, RsyncUI does not prevent you from performing such actions. RsyncUI is a complimentary and open-source application. For instructions on how to verify a task, new or changed tasks, refer to the Getting started or New tasks section.
Temporary halt tasks
A task can be temporarily halted. Within the primary Synchronize view, select the task and right-click. Halting a task will retain the type of task that was halted when the task is resumed. A halted task displays a red stop sign in the action column.
Two options to save updates to data
This option applies to the data synchronized by RsyncUI. By enabling either of these options, you can save changes to data, such as deletions or updates, prior to a synchronization task.
There are two options to automatically save changes to data when it is changed or deleted.
Option 1:rsync supports a backup flag. Switching this on in the Rsync parameters view adds the required parameters. You may change the backup directory to any location you want.
Option 2: Using snapshots requires that the latest version 3.x of rsync is installed. Please refer to the Snapshots section for information on how to enable and use snapshots.
Remote servers
RsyncUI compels data transfer via SSH if the destination is a remote server. The parameter -e ssh to rsync enables data transfer to be tunneled via SSH. It appears that recent versions of rsync or SSH do not require this parameter, but for safety, RsyncUI appends it if the destination is a remote server.
Through the SSH tunnel, the transfer is encrypted when transmitted over a network connection. Refer to the Passwordless login section for further information on SSH and SSH-keys. This feature cannot be disabled.
2 - Limitations
There are a few limitations or constraints to be aware of when using RsyncUI. None of these limitations can result in data corruption or trouble. However, they may inadvertently halt an ongoing synchronization process.
Long running tasks and sleep
Upon each Mac sleep, RsyncUI synchronization tasks cease. An active rsync process does not prevent the Mac from sleeping. If the Mac sleeps during a synchronization task, rsync likely generates an error, halting the task. The only method to resume synchronization is to restart it via RsyncUI. RsyncUI will resume and synchronize data not yet transferred. Rsync is adept and resumes from its previous state.
If the above occurs, RsyncUI will not generate any logs. RsyncUI logs only upon detecting a termination signal from rsync. If the Mac enters sleep during data synchronization, there will be no termination signal and no logging by RsyncUI.
You may modify your Mac’s sleep settings to control when it sleeps.
The above will also be true if you are using the Calendar function.
The Schedule
A note about the Schedule and scheduling of actions. There are some limitations on how the scheduler works due to how the Timer library is developed. Refer to the Schedule section for more information about this function.
Its primary function is to automate synchronization of selected tasks as long as RsyncUI is running and you are logged in. It may prove useful for users who require scheduled synchronization of data during work. If there are scheduled tasks not executed when the Mac enters sleep mode, they will be explicitly displayed in the Schedule view when the Mac wakes up.
Aborting Tasks
Please be cognizant that this is an external task not under the control of RsyncUI. It executes the command-line tool rsync. RsyncUI monitors the task for progress and termination.
The user has the authority to abort a task at any time. Please allow the abort process to complete and execute any necessary cleanup operations before initiating a new task. This process may take a few seconds. If you don’t wait, RsyncUI may become unresponsive.
3 - Getting started
For new users, kindly refer to the Important section. Additionally, please refer to the Latest version of rsync section for information about installing the latest version.
Concealing Actions
The rationale behind concealing actions is to minimize clutter in menus and enhance user focus.
By utilizing the shortcut ⌘S (for displaying or hiding) or accessing the Task main menu, the Charts, Quick task, view logfile, and several other options will be revealed. These options are concealed by default. To reveal them, simply toggle the show or hide option using the shortcut.
The primary Sidebar menu is also context-sensitive. Refer to the concealing options mentioned at the end of this page for further details.
New Tasks and Verification
RsyncUI supports synchronizing data to:
local attached disk
remote servers on the Internet or local LAN
require passwordless login by ssh-key
Local attached disk
RsyncUI can synchronize your data to a local attached disk. If you only want to synchronize data to a local attached disk, connect the disk, add the source and destination, and you are ready for your first task.
Remote server and passwordless login
If you want to synchronize data to a server, on the Internet, or your local LAN, there is some more setup to do. If you have enabled passwordless login by ssh-key, you only have to add source, destination, login id, and server name and you are ready to synchronize data. If you have not enabled passwordless login, there are some more actions required before your first task.
Verify tasks
Always verify a new task. After adding a new task, changing a task, or adding your own or changed parameters to rsync, select “Verify tasks” from the primary Sidebar menu.
Select the task and press the play button on the toolbar. Executing the play button includes the –dry-run parameter for rsync, which is an estimation run.
Aborting tasks
Please note that this is an external task not controlled by RsyncUI, which executes the command-line tool rsync. RsyncUI monitors the task for progress and termination.
The user can abort a task at any time. However, it is essential to allow the task to complete and perform any necessary cleanup operations before starting a new task. This process may take a few seconds, and if you don’t wait, the application may become unresponsive.
There are errors in tagging data
Sometimes you may get the error:
There are errors in tagging data
for synchronize ID XXXX
Most likely number of rows
> 20 lines and no data to synchronize
The preceding message serves as a cautionary note and a confirmation that all data has been synchronized. RsyncUI provides an indication of whether there is data to be transferred. Typically, the output from rsync is less than 20 rows if no data synchronization is required.
Please refer to the following for further clarification: RsyncUI analyzes the summary output from rsync to identify data that needs to be synchronized or not. Occasionally, RsyncUI may detect that the number of lines from rsync exceeds 20, yet it still tags the data as not needing synchronization. This message serves as a reminder to verify that all data has been successfully synchronized.
To clarify this message, select the task and execute it, or synchronize it, without providing an estimate.
Version 3.x of rsync:
Version openrsync:
Concealing Options
The Sidebar Menu options
There are three Sidebar menu options that are contingent upon the properties of a task. It is sufficient as long as one of the tasks satisfies one of the prerequisites.
Snapshot: this option is exclusively available for snapshot tasks
requires version 3.x of rsync
Restore: this option is only available for synchronize and snapshot tasks where the destination is located on a remote server
available for openrsync as well, but only for synchronize tasks
Verify remote: this option is only available for synchronize tasks where the destination is located on a remote server
requires version 3.x of rsync
The Sidebar menu may be hidden, either click on the Hide Sidebar icon top left or enable Hide the Sidebar on startup within the RsyncUI settings.
The menu bar
Toggle the shortcut ⌘S:
4 - New tasks
A task requires a minimum of a local directory, the source, and a remote directory, the destination.
Always verify the result of a new task before executing. Select the “Verify tasks” from the primary Sidebar menu.
Pressing the Enter key will advance to the next field. Pressing the Enter key will automatically add a new task after the last input. Tasks are saved to permanent storage after each entry.
Delete Tasks
Select the tasks you wish to delete and delete them from the Edit menu or by pressing the backspace button.
Data about Tasks
The following data pertains to tasks:
Action
synchronize - default action for synchronize data from a source to a destination
snapshot - saves changes and deletions prior to a synchronize operation
syncremote - synchronize data from a remote source to a local folder
when adding a syncremote action, add the local folder first and the remote folder as second, RsyncUI will do the flip
Folder Parameters
Source folder - required field
Destination folder - required field
Trailing /
Add - add a trailing slash to both the source and destination
Do not add - do not add a trailing slash, or if added remove it
Do not check - do not check for trailing slash or not on either the source or destination
Synchronize ID
Synchronize ID - informal tag for the task
Remote Parameters
Remote username - username for login to the remote server
Remote server - either server name or IP address for the remote server
Copy and Paste Tasks
Shortcuts for copy and paste are ⌘C and ⌘V, or from the Edit menu. The copy and paste operation creates a copy of the selected tasks and marks them with the “copy” status. The copied tasks retain all parameters.
4.1 - Update tasks
To update a task, select the task. Press the update button to write updates to storage.
Global Changes
Global Changes, choose the Global icon on toolbar, applies to either all or selected tasks. Global changes, either partial or complete string modifications, can be applied to all tasks simultaneously. While updating tasks individually may be feasible, this method is more effective for modifying all tasks in one go.
Directories
Selecting the “Home” icon displays all directories from your “$Home” directory. If a local disk is attached, the mounted volumes are also presented. Select the home directory and the mounted volume. Return to the main Task view, and RsyncUI will suggest some values.
5 - Synchronize data
The Synchronize view enables the execution of either all or selected tasks in a single operation, either by shortcut actions or by functions on the toolbar.
Or, for a single task, a double-click on one task initiates a –dry-run (an estimate run), and the subsequent double-click executes the actual run for that task.
Shortcut actions within the Synchronize view:
estimate - shortcut ⌘E estimates all or selected tasks
synchronize - shortcut ⌘R synchronizes all or selected tasks without estimation
no progress bar during synchronization; a progress bar requires estimation first
abort - shortcut ⌘K aborts and halts any ongoing task
Upon launching RsyncUI, it automatically opens the Synchronize view. Selecting the wand and stars (shortcut ⌘E) from the toolbar initiates estimation of all tasks.
The outcome of an estimate is displayed, with blue numbers indicating data that requires synchronization. To execute the actual synchronization tasks directly from the summarized estimate view, press the left arrow (shortcut ⌘R) on the toolbar.
By selecting a row within the estimate view, you will be presented with detailed information about that task.
After execution, the logs are updated.
6 - RsyncUI settings
There are several settings that can be adjusted. After changing a setting, you have to save the changes to keep it next time you use RsyncUI. Users can access their settings by default using the shortcut ⌘,.
Rsync and path - settings for rsync and path
Monitor and log - settings for monitoring and logging
SSH - settings for SSH
Environment - setting environment variables for SSH, there are several variables that can be set, but RsyncUI only supports one environment variable
The “About" section displays the version of rsync in use and the path for storing and retrieving configurations to the permanent storage location.
6.1 - Rsync and path
After changing a setting, you have to save the changes to keep it next time you use RsyncUI.
Version rsync
It is recommended to install the latest version of rsync. RsyncUI provides direct path support for Homebrew on both Apple Silicon and Intel Macs. RsyncUI will determine the type of Mac you are using. The default path for Homebrew is:
Intel-based Mac: /usr/local/bin
Apple Silicon: /opt/homebrew/bin
Path rsync
The snapshot and syncremote feature requires the latest version of rsync. If an updated or new version of rsync is not installed by Homebrew, set the path to rsync.
If Rsync v3.x is enabled, set the optional path if not installed by Homebrew.
Any version of rsync will work, but only default versions in macOS and the latest release of rsync have been tested and verified.
the test and verification process ensures the accurate parsing of the output generated by rsync
Path for restore
Preset temporary path for restoring single files and directory
Preset temporary path for a full restore
Mark days after
Tasks with an execution date older than the number of days are marked red.
Backup configurations
You can backup the current setup, configurations, and logs, including all profiles, at any time by clicking the wrench button.
The backup executes a copy to your Documents directory and appends a timestamp -month-day-year/hour/minute to the copy.
The backups are located in your Documents directory: $HOME/Documents/RsyncUIcopy-05-06-2024/08/21
6.2 - Monitor and log
After changing a setting, you have to save the changes to keep it next time you use RsyncUI.
Monitor Network:
Monitor network connection during task execution.
If a network connection is dropped during execution, RsyncUI sends an interrupt signal to the task, halting it with an error.
Check for Errors in Output:
If the word “error” is discovered in the output from rsync, it is notified.
Add Summary Log Record:
By default, “on,” a summary of each synchronization is added to the log records. View “Log Listings” from the Sidebar.
No time delay Synchronize URL-actions
If “on”, the estimated tasks, by URL-action, will be Synchronized without any possibility to abort the action.
Hide the Sidebar on startup
the sidebar may be concealed, when on the sidebar will be hidden when RsyncUI start
Observe mounting of external drives
automatic selection of a profile when RsyncUI detects a new mount of a local attached disc
Always present the summarized estimate view
after an estimate, by selecting the Magic Wand on toolbar Synchronize task view, always present the summarized view
Hide Verify remote:
refer to section “Verify remote”, this is a kind of special function, default not enabled
Hide Schedule:
refer to section “Schedule”, hide the Schedule, default not enabled
Confirm Execution:
See below.
The log file is stored at $HOME/.rsyncosx/macserial/rsyncui.txt. The log file can be opened from the main view.
Error Output from rsync:
Sample of an error in output from rsync. If the switch “Check for error in output” is enabled, RsyncUI writes the output to the log file and alerts the user about any errors in rsync.
Confirm Execute
This option is only available if version 3.x of rsync is enabled.
The confirm dialog appears when the number of files to synchronize is comparable to a new task. Occasionally, a remote server or local disk becomes unavailable or is forgotten to be attached. If you initiate a synchronize task without being aware that the destination resource is not available, rsync may mistakenly believe this is a new full synchronize and prompts a dialog to confirm synchronize or abort.
If a remote server is unavailable, rsync will likely complain and generate an error. If the check for error in output option is enabled in the user settings, the rsync error messages written to the log and an Alert will be displayed.
If a local disk is not attached, rsync will attempt to synchronize the data to the /Volumes/ directory on your Mac. This directory is typically where macOS mounts local attached disks.
/dev/disk5s2 on /Volumes/Import bilder (apfs, local, nodev, nosuid, journaled, noowners)/dev/disk6s1 on /Volumes/Backups (apfs, local, nodev, nosuid, journaled, noowners)
Below the local attached volume is not connected, and the estimate may interpret this as a new synchronize task. If you have simply forgotten to attach the disk, you do not want RsyncUI to synchronize data to the /Volume directory.
6.3 - SSH settings
After changing a setting, you have to save the changes to keep it next time you use RsyncUI.
In this perspective, you can utilize RsyncUI to assist in creating an SSH key and setting up a global SSH keypath and identity file. SSH keys are required for passwordless logins to remote servers. You can either use the default values for SSH keys or set your own. For more information on passwordless logins, please refer to the documentation at Passwordless login section.
Local SSH Key Present
If the “on” option is selected in RsyncUI, it has detected a local SSH key.
The default values for RSA-based SSH keys are ~/.ssh/id_rsa and port number 22. These values are not mandatory if you choose to
use the default settings. If you do not specify your own SSH keypath and identityfile, RsyncUI will automatically use the default values.
If a local SSH key is present, you can either leave the settings as they are or manually set your own SSH keypath and identityfile.
In this case, RsyncUI will mark the selected settings as the default.
Set SSH Keypath and Identityfile
The user can specify a selected SSH keypath and identityfile that will apply to all configurations.
SSH Keypath and Identityfile: If the user selects a different keypath or identityfile from the default, it will be used for all configurations.
Port Number: The user can specify the port number through which SSH communicates. The default port number is 22.
If global SSH parameters are set, they will apply to all configurations. It is possible to specify different SSH parameters for each task.
7 - Some advanced features
There are a few more or less advanced features in RsyncUI. If you are new to RsyncUI, new to rsync, it is adviced to learn the basics before utilizing the more advanced features.
Halting tasks
By right-clicking on a task, on column Synchronize ID or Task, it can be halted or released from halted status. A halted task will be marked and not available for estimate or execute. When releasing a task from halted status, it remember which kind of task it was before halted.
7.1 - URL commands
Deep links facilitate direct access to application features via URL links. By utilizing deep links, users can execute an estimate and synchronize actions in a single click. Deep links in RsyncUI enable the grouping of actions that typically require multiple user inputs.
There are three methods of using deep links:
enable RsyncUI widgets
use URL functions direct within RsyncUI
save an URL-link in e.g. Notepad
RsyncUI Widget
One widget is embedded in RsyncUI:
estimating and synchronizing
The widget retrieve a saved URL link from storage. Within the Tasks view, there is a view for URL. Within this view, you can save the required URL. The widgets display whether a validated URL is present. To enable the widgets on macOS, click on the date and time icon located in the upper right corner of your screen. Edit the widgets and select RsyncUI. Then, add the widgets.
After enabling the widget, a single click on the widget will launch RsyncUI and execute the corresponding action. To modify the URL, update and save the new URL.
Execute URL´s from within RsyncUI
Deep links also enable automation of actions within RsyncUI. A single click on the toolbar icon executes the URL action. RsyncUI generates the necessary URL based on the loaded profile and the required action. The two yellow toolbar icons allow execution of URL commands from within RsyncUI, as demonstrated in section above.
URL´s and Notepad
URL´s must start with rsyncuiapp://:
Action
URL
Estimate all tasks, automatically synchronize data
Estimate all tasks and automatically synchronize data
load profile, estimate all tasks and automatically synchronize data
View URL
You may copy the correct URLs and save the URLs in e.g Notepad for easy access to start a synchronize task.
Errors in URL link
If RsyncUI encounters an invalid URL link, it will generate errors. Only well-defined URLs (specifically those supported by RsyncUI) are processed and executed. All URLs are validated as valid, but only defined URLs for RsyncUI are actually executed.
7.2 - Verify remote
The Verify remote function is by default disabled. Please refer to section RsyncUI settings, Monitor and log to enable. This function also necessitates that the destination be located on a remote server.
Prior to utilizing this function, kindly consult its documentation to ensure you make the appropriate decision.
The Verify remote function is a specialized tool designed to assist in synchronizing multiple Mac computers to a single remote repository, excluding Git repositories. Additionally, it updates local data from the same remote repository.
This functionality was developed due to a personal need. The developer utilizes two Macs for photo development and data synchronization to a remote folder. The remote repository is not a Git repository, necessitating a tool to determine whether to push or pull data.
Important: Using the above method requires you to remember from which Mac the latest synchronization was executed. If not, you will most likely lose data. Additionally, you should establish a procedure for using this function. For instance, at home, I always use my Mac Mini M4 to edit photos. When traveling, I always use my MacBook Pro, and it is fully synchronized with my Mac Mini when I leave for travel.
Typically, a synchronize action operates in a one-way direction of data. Local data is synchronized to a backup media, such as an attached disc or a remote server. Restoring data, for instance, involves retrieving data from a backup when local data has become corrupted or inaccessible.
If you are using multiple Macs, as I do, and all Macs synchronize data to the same remote storage, there may be challenges maintaining synchronization
and preventing data loss, particularly if the remote storage is not a Git server, such as GitHub and Gitea. If the remote destinations are stored on a Git server, regular git push and git pull commands will suffice.
Git is a superior tool for version control. However, in certain situations, creating a Git repository may not be feasible, and this function may prove useful. As a reminder, the Verify function is designed for multiple Macs synchronizing data to a single remote server as a backup. It also assists in deciding whether to push or pull changes to keep the local repository updated.
The user is solely responsible for determining the appropriate action. RsyncUI provides only advisory guidance, based on a rudimentary evaluation of a push and pull data comparison. Additionally, the function requires version 3.x of rsync to be installed and enabled.
The Verify process necessitates that one of the Macs be synchronized with the remote. If both Macs have local unique updates, the outcome of the Verify is most likely inaccurate, potentially resulting in data loss.
The function is not intended to be automated. Users must verify their subsequent actions.
Synchronization of Multiple Macs to a Remote Server
I have over 3,000 bird photos (130 GB) from the past four years that are synchronized using RsyncUI to a local remote server at home. New photos are added, old photos are deleted, and updates are made to sidecars of the photos. As long as I was using only one Mac, all updates were made on that Mac. However, with two Macs, I now use both Macs to work on my photos. When I synchronize my changes, I need to transfer those changes to my second Mac.
Arguments for rsync
The following arguments are used in both push and pull.
--itemize-changes - output change-summary for all updates
--dry-run - rsync execute an estimate run
--update - evaluates the timestamp
The result from the pull command is subtracted from the result of the push command. Conversely, the push command is subtracted
from the result of the pull command. After both subtractions, the resulting arrays are compared based on the number of rows.
The outcome is as follows:
If pull has more data than push, it is likely that the destination is more up-to-date than the source
If push has more data than pull, it is likely that the source is more up-to-date than the destination
If the number of rows is equal, it is likely that the source is more up-to-date than the destination
If there are zero rows, most likely, source and destination are in sync.
Itemized output - push or pull
The parameter -i or --itemize-changes produces details about each file. The format of the output is:
YXcstpoguax
|||||||||||`-------------------------- the TYPE OF UPDATE:
|||||||||| <: file is being transferred to the remote host (pushed).
|||||||||| >: file is being transferred to the local host (pulled).
|||||||||| c: local change/creation for the item, such as:
|||||||||| - the creation of a directory
|||||||||| - the changing of a symlink,
|||||||||| - etc.
|||||||||| h: the item is a hard link to another item (requires --hard-links).
||||||||||"+" - the file is newly created
|||||||||| .: the item is not being updated (though it might have attributes that are being modified).
|||||||||| *: means that the rest of the itemized-output area contains a message (e.g. "deleting").
||||||||||`----------------------------- the FILE TYPE:
||||||||| f for a file,
||||||||| d for a directory,
||||||||| L for a symlink,
||||||||| D for a device,
||||||||| S for a special file (e.g. named sockets and fifos).
|||||||||`--------- c: different checksum (for regular files)|||||||| CHANGED VALUE (for symlink, device, and special file)`-------- s: Size is different
`------- t: Modification time is different
`------ p: Permission are different
`----- o: Owner is different
`---- g: Group is different
`--- u: The u slot is reserved for future use.
`-- a: The ACL information changed
7.3 - Passwordless login
To synchronize data to a remote server using RsyncUI, passwordless login via SSH key authentication is required. RsyncUI does not support password-based authentication during data synchronization. SSH key authentication is generally considered more secure than password-based authentication.
If default values for RSA-based SSH key authentication are used, no additional information about the SSH key is required in RsyncUI. However, it is necessary to provide information if a custom SSH keypath, identity file, or port number is used.
The SSH keypath and identity file are specified as follows:
-e "ssh -i ~/.keypath/identityfile -p NN"
where:
-i ~/.keypath/identityfile is the SSH keypath and identity file
-p NN is the port number used for communication (default port 22)
To use custom SSH key and keypath data, add the following information to RsyncUI in the settings:
To configure the SSH keypath and identity file, refer to the user configuration in the SSH settings. When enabling a custom SSH keypath and identity file, please ensure they follow this format:
~/.mynewsshdirectory/mynewkey
For example:
~/.ssh_rsyncosx/rsyncosx
The path must start with ~ followed by /. RsyncUI will verify that the SSH keypath begins with ~ and contains at least two forward slashes (/) before saving the new SSH keypath.
The rsync command to synchronize my Documents directory to my Raspberry Pi server is set by RsyncUI as:
For more information on passwordless login, please refer to the Tools for passwordless login section.
7.4 - Tools for passwordless login
RsyncUI uses the standard SSH tools ssh-keygen and ssh-copy-id to help you establish passwordless login to remote servers via SSH key authentication.
Custom SSH key pairs must follow the format ~/.ssh_keypath/identityfile, and the SSH port must be an integer value. RsyncUI validates these settings before saving.
SSH Key Methods
RsyncUI supports two approaches:
Default SSH keys: Uses the standard RSA key location (~/.ssh/id_rsa)
Custom SSH keys: Uses a user-specified location (e.g., ~/.ssh_rsyncosx/rsyncosx)
When using default keys, RsyncUI doesn’t add extra SSH parameters to rsync commands. Custom keys require additional parameters to tell rsync where to find them.
-f ~/.ssh_rsyncosx/rsyncosx - Specifies where to save the keys
Step 3: Copy Public Key to Server
ssh-copy-id -i ~/.ssh_rsyncosx/rsyncosx.pub -p NN user@server
Replace:
NN with your SSH port number (default is 22)
user with your remote username
server with your server address
Step 4: Set Correct Permissions
chmod 700 ~/.ssh_rsyncosx
Step 5: Configure RsyncUI
Add your custom SSH keypath and identity file in RsyncUI’s user configuration. RsyncUI will automatically apply these settings.
You can also set custom SSH parameters for individual tasks, which will override the global settings.
7.5 - Export and import
Tasks can be exported and imported between profiles and to new Macs. Select the “File” menu and then choose “Export and import.”
7.6 - Snapshots
Utilizing snapshots is an effective method for restoring previous versions of data and deleted files. Snapshots employ hardlinks to save copies of only modified and deleted files as separate files in a snapshot. Files that remain unchanged are hardlinks to the original file.
In every snapshot task, RsyncUI stores the next available snapshot number. The snapshot number is a sequential number incremented by one after each snapshot task execution. The rsync command automatically creates the next snapshot directory by number, and RsyncUI updates the stored snapshot number for the next run. The snapshot number is displayed as part of the log timestamp.
If a file named “file.txt” is saved in the initial snapshot and remains unchanged or is deleted, the “file.txt” in the latest snapshot is a hardlink to the original file in the first snapshot.
If “file.txt” is deleted from the source, the filesystem manages the hardlink appropriately during the delete operation.
In RsyncUI, the first and last snapshots are never deleted, even if all snapshots are marked for deletion.
Snapshots
A snapshot is a saved state or backup of data at a specific point in time. Each snapshot is synchronized with the source at the time of creation.
Remote Server
The rsync parameter for the next snapshot to synchronize to a remote.server is:
n is the number of the next snapshot to be synchronized
n-1 is the latest synchronized snapshot
/Users/thomas/data/ is the source directory, only read by rsync
/Volumes/backup/snapshots/ is the destination directory where snapshots are synchronized
Snapshot Creation
To create a snapshot task, select “snapshot” as the action in the Add tasks section. RsyncUI automatically manages the snapshot number “n” for the task. This number represents the next available snapshot number and is used to calculate the rsync parameter.
Snapshot Administration
Snapshot administration is essential for maintaining an organized and efficient backup system. It involves regularly reviewing and deleting unnecessary or outdated snapshots to prevent clutter and optimize backup space usage.
Deleting Snapshots
Deleting snapshots is a destructive operation that should be performed with caution. It is important to have a plan in place to determine which snapshots to keep and which to delete. RsyncUI provides a simple plan for managing snapshot retention.
The Plan for Keep and Delete
Selecting the “Tag” button evaluates all snapshots based on the date within the log record. Based on the selected plan and date, snapshots are either tagged with “keep” or “delete.” Snapshots tagged with “delete” are also preselected for deletion. To delete the marked snapshots, select the “Delete” button.
Even if all snapshots are tagged for deletion, the first and last snapshots are never deleted. They are automatically removed from the delete list during the internal preparation for deletion.
The plan is based on three time periods, where the plan parameter affects previous months (and years):
The current week
keep all snapshots within the current week
the value of plan has no effect on the current week
The current month (minus the current week)
keep all snapshots for the selected day of week, e.g., all snapshots every Sunday this month
the value of plan has no effect on the current month
Previous months (and years)
keep the snapshot in the last week of the month for the selected day of week, e.g., the last Sunday in the month
if plan == Every, keep snapshots for the selected day of week, e.g., all snapshots every Sunday in previous periods
if plan == Last, keep snapshots for the selected day of week, e.g., all snapshots on the last Sunday of every month in previous periods
Tagging and Deleting Snapshots
It is recommended to optimize the number of snapshots regularly. Select a plan, tag the snapshots, and delete the snapshots marked for deletion.
8 - General information
There are some general information which might be nice to know.
8.1 - Latest version of rsync
The default /usr/bin/rsync differs between macOS versions:
macOS Sonoma: Uses rsync version 2.6.9 (released November 2006)
macOS Sequoia and Tahoe: Use openrsync, a BSD-licensed implementation compatible with rsync protocol 29 and version 2.6.9
I strongly recommend installing the latest version of rsync (version 3.x) to take full advantage of RsyncUI’s features.
Installing rsync via Homebrew
Install the latest version using Homebrew:
brew install rsync
After installation, configure RsyncUI:
Navigate to Settings and select Rsync and path
Enable Rsync ver3.x
RsyncUI will automatically set the correct path
Note: RsyncUI’s snapshot and sync remote features require rsync version 3.x due to limitations in version 2.6.9.
Copyright (c) 2020 - 2025 - Thomas Evensen
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so, subject
to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8.3 - RsyncUI files, JSON
RsyncUI stores all its data locally on your Mac in JSON format. This includes task configurations, log records, and user settings. Understanding the file structure can be helpful for backup or troubleshooting purposes.
File Locations
All RsyncUI files are stored in: $HOME/.rsyncosx/<macserialnumber>, where <macserialnumber> is your Mac’s serial number. RsyncUI retrieves this serial number automatically at startup.
At startup, RsyncUI reads the user settings and default configuration from JSON files. Log records are only loaded when viewing logs or when updating logs after a synchronization task.
The application log file is a text file that can be viewed within RsyncUI:
$HOME/.rsyncosx/<macserialnumber>/rsyncui.txt
8.4 - Signing and notarization
RsyncUI is digitally signed with my Apple Developer Certificate and notarized (https://support.apple.com/en-us/HT202491) by Apple. This verification process ensures that the application is free from malicious code and will seamlessly integrate with Apple’s Gatekeeper technology. Upon opening either a new or updated application for the first time, Apple will issue a notification.
9 - Parameters to rsync
RsyncUI provides default parameters for data synchronization. However, the actual default parameters utilized in tasks are determined by whether the rsync operation is performed over a network connection or to a local attached disk.
Users have the ability to modify default parameters as necessary. Parameters to rsync are stored in tasks, including a local ssh parameter if set. The local ssh parameter overrides a global ssh parameter if set.
Always verify the result of changing parameters to rsync before executing. Select “Verify tasks” from the primary Sidebar menu.
Task-Specific Parameters to rsync
To add a parameter to rsync, enter it in the corresponding field. RsyncUI supports seven user-defined parameters. Users can add parameters using any of the fields. However, users are responsible for verifying the accuracy of the added parameters. If an incorrect parameter is added, rsync will generate an error message.
Parameters to rsync are typically constructed as follows. The following are examples only; rsync supports many parameters.
parameter=value
--exclude-from=/Volumes/home/user/exclude-list.txt - exclude list for rsync
parameters only
--stats - enables the display of statistics during the synchronization process
--dry-run - executes a simulated synchronization without modifying the files
For a comprehensive list of parameters for rsync, please refer to the official rsync documentation.
Task-Specific SSH Parameter
If default ssh-key values are used and no ssh-key information is provided in RsyncUI, the parameter -e ssh is appended to the rsync command to ensure data is tunneled and encrypted using ssh. This applies exclusively to remote servers and data restoration from remote servers.
Task-specific ssh parameters override global ssh parameters configured in the user settings.
ssh-port: specify if ssh uses a port other than the default port 22
ssh-keypath and identity file: typically, these are .ssh/id_rsa; set only if alternative ssh-keypath and identity file are to be used by ssh
The values are marked red until validated OK. Refer to the “Tools passwordless login” section for information about validated values.
Backup Switch
The rsync command allows you to instruct it to save modified and deleted files in a separate backup directory prior to the synchronization process. This feature can be enabled by setting the following parameters:
--backup - Enables the saving of modified files
--backup-dir - Specifies the directory where modified or deleted files should be saved before synchronization
RsyncUI provides a default value for this parameter, but you can customize it as needed. For a synchronized directory named <directory to synchronize>, the default backup directory is ../backup_<directory to synchronize>, which is relative to the synchronized directory.
10 - Schedule
The schedule function is disabled by default. Please refer to the RsyncUI settings, Monitor and log section to enable it.
Schedules are automatically saved to disk. RsyncUI loads the schedule file and reloads scheduled tasks that are due. Tasks that were scheduled to run while the Mac was shut down are not loaded. If the Mac enters sleep mode, RsyncUI will display unexecuted tasks in the Schedule view. There is no automatic execution of scheduled tasks that have not been executed.
The scheduler is implemented using the Timer library. According to Apple: “A timer that fires after a certain time interval has elapsed, sending a specified message to a target object.” The timer has a strong reference to the run loop on the main thread. This means that if the application goes to sleep, so does the run loop. The timer is only active as long as RsyncUI is running.
If scheduled tasks are not executed when the Mac enters sleep mode, they will be displayed in the Schedule view.
Add Schedule
To add a schedule, click on the date, set the time, and schedule the task. When a schedule is active, the user is notified in the sidebar or on the toolbar when the sidebar is hidden. Right-clicking on a date will present schedules by date.
Tasks added to the schedule are validated. The planned next task schedule must either:
be 10 minutes ahead of the first schedule in queue
the first schedule in queue is always ahead of the current time
be within 10 minutes before the first schedule in queue
as above, the planned next schedule must also be later than the current time
The Schedule function is designed to handle Mac sleep mode:
when a scheduled task is not executed because the Mac enters sleep mode, the Schedule function retrieves unexecuted tasks and displays them in a table
the user may move the unexecuted tasks to the schedule table
The Schedule view visually distinguishes invalid times in red font. Only validated task schedules are incorporated into the schedule.
Delete Schedules
Select one or more schedules and press the backspace key.
11 - Profiles
Tasks can be organized in profiles. A profile is a named directory where RsyncUI stores its files.
When you create a profile (for example, newprofile), RsyncUI creates a new directory at:
$HOME/.rsyncosx/<macserialnumber>/newprofile
where <macserialnumber> is your Mac’s serial number. All tasks and log files for that profile are stored within this directory.
The list on the right side of the view displays all tasks that have not been updated within the number of days specified in the Settings under the “Mark days after” option.
12 - QuickTask
The QuickTask function in this release is not functioning as intended due to an oversight on my part. Although it is a minor function and only applicable to remote servers, if you occasionally utilize it, version 2.6.5 is available for download and addresses the issue. If you do not require the QuickTask function, there is no need to download the updated version.
Use QuickTask to quickly copy or transfer files to either source or destination. QuickTask will save the last executed quick task as default values. Default values can be cleared by the toolbar function.
There are two types of quick tasks:
synchronize - synchronize local files to remote, aka push data
syncremote - synchronize remote files to local, aka pull data
Trailing Slash Options
Add - adds a trailing slash to both the source and destination
Do not add - does not add a trailing slash, or if added, removes it
Do not check - does not check for a trailing slash on either the source or destination
After entering data, the default task is a --dry-run task. It is recommended to inspect the result before executing the actual run.
Folder Parameters
Source folder - required field
Destination folder - required field
a ~ is expanded as the home directory with the full path by the remote operating system
the remote directory may also be specified by full path, depending on where the backup directory is located on the remote server
Remote Parameters
Remote username - username for login to the remote server
Remote server - either server name or IP address for the remote server
13 - Restore data
Data restoration from within RsyncUI is only available for remote servers. For data stored on attached volumes, use macOS Finder to restore files. A restore operation must be executed to a temporary restore path to prevent overwriting your original data.
How to Restore Files
Filter files: Use the filter field to search for specific files or directories. The filter retrieves only filenames containing the specified string.
Select files: Choose either a file or a directory to restore.
View the command: Toggle the command switch to see the actual restore command that will be executed.
Preview the restore: Select restore to display a --dry-run preview of the restore operation.
Execute the restore: Turn off the --dry-run toggle to perform the actual restore.
Review results: After the restore completes, RsyncUI displays the output from rsync.
