RSync-Studio/Rsync Studio/Resources/Rsync Studio Help.md

Rsync Studio Help

Rsync Studio is a macOS front end for rsync. It can run local copies, SSH-based remote synchronisation, dry runs, scheduled jobs, and file/folder watch jobs. Every run is recorded in History with the command, result and transfer statistics.

1. Before You Start

Rsync Studio looks for rsync in this order:

1. /opt/homebrew/bin/rsync
2. /usr/local/bin/rsync
3. /usr/bin/rsync

For the best compatibility with modern Linux servers, install a current rsync using Homebrew. The macOS supplied /usr/bin/rsync is older and behaves differently for some extended-attribute options.

SSH jobs also require the normal macOS ssh client and network access to the remote computer.

2. Create a Local Sync Job

1. Select New Sync Job.
2. Give the job a descriptive name, for example Documents Backup.
3. Choose Local as the destination type.
4. Select the source folder.
5. Select the destination folder.
6. Choose the required rsync options.
7. Save the job.
8. Run Dry Run first, then use Run Now when the result looks correct.

Example

Source:

/Users/mag/Documents/

Destination:

/Volumes/Backup/Documents/

A typical job using Archive mode is equivalent to:

rsync -a --human-readable --stats /Users/mag/Documents/ /Volumes/Backup/Documents/

Trailing slash behaviour

Rsync treats these differently:

/Users/mag/Documents/

copies the contents of Documents into the destination.

/Users/mag/Documents

copies the Documents directory itself into the destination.

Check the source carefully before enabling Delete mode.

3. Create an SSH Remote Job

1. Create or edit a job.
2. Select SSH Remote.
3. Enter the remote host, for example 192.168.1.2 or pegasus.local.
4. Enter the SSH username, for example mag.
5. Set the SSH port, normally 22.
6. Select a private SSH key if required.
7. Enter a remote destination path such as /home/mag/backups/Documents.
8. Save and run a Dry Run.

Correct remote example

Host: pegasus.local

Username: mag

Destination: /home/mag/backups/photos

The resulting destination is similar to:

mag@pegasus.local:/home/mag/backups/photos

Incorrect remote destination

Do not put the host address in the Destination field. These are wrong:

192.168.1.2

mag@192.168.1.2

The Destination field must contain a path on the remote machine.

4. SSH Keys

Use the private key, not the .pub file.

Correct examples:

~/.ssh/id_ed25519

~/.ssh/id_rsa

Incorrect:

~/.ssh/id_ed25519.pub

If you accidentally select a .pub key and the matching private key exists beside it, Rsync Studio attempts to use the private key. If only the public key exists, the run is rejected.

Test SSH outside the app

Before troubleshooting rsync, verify SSH itself works:

ssh -p 22 -i ~/.ssh/id_ed25519 mag@pegasus.local

If that command cannot connect, fix SSH/network/authentication first.

5. Default Connection Settings

Open Rsync Studio > Settings > Connections to configure defaults for new SSH jobs:

• Default username
• Default host
• Default SSH port
• Default private key
• Default password storage

Passwords are stored in macOS Keychain, not SwiftData or UserDefaults. Current rsync execution is designed primarily around SSH keys or an SSH agent; a stored password is not placed on the command line.

6. Rsync Options

Archive

Archive mode (-a) is the normal choice for directory backup/synchronisation. It recursively copies files and preserves common metadata.

Compress

Compress (-z) can help on slower network links. It is often unnecessary for local copies or already-compressed files such as JPEG, ZIP and video.

Delete Extraneous Files

Delete mode (--delete) removes destination files that no longer exist at the source.

Use Dry Run before enabling a destructive sync. A mistaken source or destination combined with Delete can remove destination data.

Preserve Permissions

Preserves permissions when Archive mode is not being used.

Extended Attributes

On modern rsync, Rsync Studio uses -X. With Apple /usr/bin/rsync, local jobs use the Apple-compatible -E form. For SSH to modern Linux rsync, the Apple-only extended attribute flag is omitted to avoid an incompatible remote option.

Exclusions

Add patterns for files or directories you do not want transferred.

Examples:

.DS_Store

*.tmp

node_modules/

.git/

Additional arguments

Advanced rsync options can be entered as additional arguments. Use this only when you understand the rsync option and its effect.

Example:

--max-size=2G

7. Dry Run

Dry Run adds --dry-run. Rsync reports what it would change without transferring or deleting files.

Use Dry Run when:

• Creating a new job
• Changing source or destination paths
• Enabling Delete
• Changing exclusions
• Changing SSH destinations
• Testing a large sync

The summary window shows files checked, files that would transfer, data size and transfer statistics.

8. Run Now

Select a job and choose Run Now. Manual runs display a progress/result sheet. The complete stdout/stderr output is retained in History.

Only one rsync process is run by the current runner at a time. If another run is already active, a second job waits for the automation manager or is rejected for a direct manual launch depending on how it was triggered.

9. Scheduling Jobs

Edit a job and enable Schedule.

Available schedule types include:

• Once
• Hourly
• Daily
• Weekly
• Monthly
• Custom interval

Scheduled runs execute without displaying the manual progress sheet. Results still appear in History.

Daily example

Job: Nightly Documents

Schedule: Daily

Start time: 23:30

Result: the job runs each day at approximately the configured application schedule time while Rsync Studio is running.

Weekly example

Job: Weekly Photos

Schedule: Weekly

Choose the desired start date/time. The application calculates and displays the next run.

Custom interval example

Set a custom interval of 30 minutes to request a run every 30 minutes.

Avoid extremely short intervals for large jobs. A new run should not repeatedly start before the previous transfer has finished.

10. Calendar

Select Calendar at the top of the main window.

The calendar shows scheduled jobs by date and allows you to review upcoming automated work. Use it to confirm that a newly edited schedule produces the next run you expected.

If a job does not appear:

1. Confirm the job is enabled.
2. Confirm Schedule is enabled for that job.
3. Confirm the start date is valid.
4. Return to the job and check the displayed Next scheduled run value.

11. Watch for File or Folder Changes

Edit a job and enable File Watching.

Rsync Studio uses macOS FSEvents rather than repeatedly scanning the whole directory tree.

Watch the job source directory

Leave the custom watch path empty. The job source is watched automatically.

Example source:

/Users/mag/Developer/MyProject/

When changes occur beneath that directory, the watch service debounces the events and triggers the configured sync.

Watch one specific file

Set the watch path to a specific file, for example:

/Users/mag/Documents/config.json

The service watches the containing directory and filters events so only changes affecting that file trigger the job.

Debounce

Applications often save a file several times in quick succession. The debounce period groups those events into one rsync run.

Example:

Debounce: 5 seconds

Saving 10 files over a three-second period results in a single sync after activity settles, rather than 10 separate rsync processes.

Good watch-job examples

• Sync a development project to a test server after edits.
• Mirror a document directory to a local backup disk.
• Upload generated reports when files change.
• Synchronise a configuration directory to another Mac or Linux machine.

Avoid watch loops

Do not configure the destination inside the watched source tree. Otherwise rsync's own writes can generate more filesystem events and repeatedly trigger the job.

Bad example:

Source: /Users/mag/Data/

Destination: /Users/mag/Data/Backup/

Prefer a destination outside the watched source hierarchy.

12. Background Operation

Scheduled and file-watch jobs run without opening the manual progress sheet. The application must still be running for its scheduler and FSEvents watchers to operate.

Enable Launch at Login in Settings if you want Rsync Studio to start automatically after you sign in to macOS. You can then close or minimise the main window while the app continues running.

Quitting Rsync Studio stops in-process schedules and file watching until the application starts again.

13. Jobs Screen

The Jobs screen is the main status dashboard. Each job shows its key automation and run state.

Use the filters to review:

• All jobs
• Scheduled jobs
• Watching jobs
• Jobs with issues

Select a job to open its full detail view. The Edit Job button remains fixed at the top of the detail pane so it is available even after scrolling or on narrower windows.

14. History

Select History to review completed runs.

History records whether the run was started by:

• Manual action
• Schedule
• File change

Select a run to inspect:

• Start/end time
• Exit status
• rsync command
• Transfer summary
• stdout
• stderr
• Dry-run state

Use Export Log from the run result/detail view when you need a text copy for troubleshooting or auditing.

15. Common Rsync Exit Codes

0 — Success.

1 — Syntax or usage error.

2 — Protocol incompatibility.

3 — File selection/input-output errors.

10 — Socket I/O error.

11 — File I/O error.

12 — Error in rsync protocol data stream.

23 — Partial transfer due to error.

24 — Partial transfer because source files vanished during the run.

30 — Timeout in data send/receive.

Always inspect stderr in History for the actual diagnostic message.

16. Troubleshooting

Permission denied

Check that the macOS user running Rsync Studio can read the source and write to the destination. For remote jobs, check permissions for the remote SSH user.

Host key verification failed

Connect once using Terminal:

ssh mag@pegasus.local

Verify the host fingerprint and allow SSH to update ~/.ssh/known_hosts.

Do not disable host-key verification simply to hide this warning.

Public key authentication failed

Check:

• The private key path is correct.
• The remote user's ~/.ssh/authorized_keys contains the matching public key.
• File permissions on the remote .ssh directory/key files are valid.
• The SSH username is correct.

Remote rsync option error

If you are using /usr/bin/rsync on macOS against modern Linux, avoid manually adding Apple-specific rsync options. Installing Homebrew rsync provides better modern compatibility.

Nothing transfers

Run a Dry Run and inspect the command and output. Check exclusions, trailing slash behaviour and whether source/destination already contain identical data.

Watch job does not trigger

Check that:

• The job is enabled.
• Global file watching is enabled in Settings.
• File Watching is enabled on the job.
• The watch path exists.
• Rsync Studio is still running.
• The change occurred beneath the watched path, or matches the selected single file.

Schedule does not run

Check that:

• Global scheduling is enabled in Settings.
• The job itself is enabled.
• Schedule is enabled for the job.
• The displayed next-run time is correct.
• Rsync Studio is running at the scheduled time.

17. Recommended Backup Workflow

For an important backup job:

1. Create the job without Delete enabled.
2. Run a Dry Run.
3. Review the source and destination in the generated command.
4. Run the job manually.
5. Check History for exit code 0.
6. Verify several files at the destination.
7. Only then enable a schedule.
8. Enable Delete only when you specifically require a mirror and understand the deletion behaviour.

Rsync synchronisation is not automatically a versioned backup. If the destination mirrors source deletions, it does not replace a separate versioned/offline backup strategy.

18. Example Configurations

Local external-drive backup

Name: Documents to USB

Source: /Users/mag/Documents/

Destination: /Volumes/Backup/Documents/

Archive: On

Delete: Off initially

Schedule: Daily at 22:00

Mac to Linux server

Name: Projects to Pegasus

Source: /Users/mag/Developer/

Host: pegasus.local

User: mag

Port: 22

Private key: /Users/mag/.ssh/id_ed25519

Remote destination: /home/mag/backups/Developer/

Archive: On

Compress: On

Schedule: Daily

Live project watcher

Name: Website Live Sync

Source: /Users/mag/Sites/MySite/

Remote destination: /var/www/mysite/

Watch: On

Watch path: leave empty to watch the source

Debounce: 5 seconds

Exclusions: .git/, node_modules/, .DS_Store

Use this style only when automatic deployment to that destination is intentional.

19. Safety Checklist

Before running a new job, confirm:

• Source is correct.
• Destination is correct.
• Remote host/user are correct.
• The selected SSH key is private, not .pub.
• Delete mode is intentional.
• Exclusions are correct.
• Dry Run output looks correct.
• The destination has enough free space.
• A watch destination is not inside its watched source.

20. Getting Help Information from the App

Select the Help button in the main Rsync Studio header. The bundled guide you are reading opens inside the application and is available without an Internet connection.

For an rsync-specific option not documented here, run man rsync in Terminal for the version of rsync installed on your Mac. Behaviour can differ between the Apple-supplied rsync and current Homebrew rsync.

Sync All

Use Sync All in the Jobs sidebar to run every enabled job in sequence. Rsync Studio queues the jobs rather than starting several rsync processes at once. Each job creates its own History entry, and the header shows the current batch progress. Disabled jobs are skipped.

Security and unattended operation

Rsync Studio is designed for direct Developer ID distribution. It uses the macOS Hardened Runtime and intentionally does not use the App Sandbox because the utility must launch rsync/ssh and work with arbitrary user-selected paths.

SSH security

SSH authentication uses a private key or your normal macOS SSH agent. Rsync Studio does not store SSH passwords and does not place passwords on a process command line. Automated SSH uses BatchMode=yes, a connection timeout, keepalive intervals and a finite keepalive failure count. Host-key verification is never disabled; connect to a new host once in Terminal first if SSH needs you to approve its host key.

Example:

ssh -p 22 -i ~/.ssh/id_ed25519 mag@pegasus.local

Protected advanced arguments

The Advanced field is for ordinary rsync tuning only. Rsync Studio rejects arguments that can replace the SSH transport, run a different remote command, read options/file lists from other files, write logs/batches to arbitrary paths, load a password file, enter daemon mode, remove source files or bypass the app's controlled delete switch. Examples that are rejected include -e, -M, --rsh, --rsync-path, --password-file, --files-from, --log-file, --write-batch, --remove-source-files and --delete*. Unmatched quotes and trailing escape characters are also rejected.

Delete protection

Manual --delete runs always show a destructive-operation warning. If a scheduled or file-watch job uses Delete, you must also explicitly enable Allow unattended delete in the job editor. This prevents a job from becoming destructively automated merely because Schedule or File Watch was enabled later.

Run a Dry Run and review the destination before authorising unattended delete.

Path overlap protection

For local jobs, source and destination must be separate directory trees. Rsync Studio rejects configurations where the destination is inside the source or the source is inside the destination. This prevents recursive backup trees and common file-watch loops.

History and privacy

Rsync Studio does not include analytics or tracking. Run output is sanitised before persistence, terminal control sequences are removed, likely credential-shaped values are redacted, and each stdout/stderr log is capped at approximately 2 MB. History retention is configurable in Settings > Automation > History & Privacy and defaults to 90 days.

The bundled privacy manifest declares no tracking and no collected data.

Release verification

The project contains Docs/RELEASE.md and Scripts/security-check.sh with Developer ID, notarisation, signature and Gatekeeper verification steps for production builds.

Production Reliability

Test Job / Preflight

Use Test Job before relying on unattended automation. Local jobs verify configuration, rsync availability, source reachability, destination volume identity, and configured free-space reserve. SSH jobs verify batch authentication, remote rsync availability, and remote destination access.

External volume protection

For removable drives, enable Require this exact destination volume and capture the mounted destination. If that volume is absent, Rsync Studio refuses to sync to another filesystem that happens to appear at the same path.

Retries and notifications

Scheduled and watched jobs can retry automatically with increasing delays. Per-job notifications can report failures and, optionally, successful completion. Remote queued jobs wait while the Mac is offline and resume when network connectivity returns.

Sync All

Sync All runs enabled jobs sequentially, displays succeeded/failed/skipped totals, and can be cancelled from the Jobs dashboard.

Configuration backup

Use the Jobs menu to export or import a versioned JSON job configuration. Private SSH-key paths are intentionally omitted. Imported remote jobs are disabled until authentication is confirmed on that Mac.

Diagnostics

Settings → General → Export Diagnostics… creates a redacted support report containing application, macOS and rsync versions, job status and recent failures without exporting SSH private-key paths or credentials.

Updates

The built-in update checker accepts only an HTTPS manifest signed with the Ed25519 public key embedded in the signed app. Until a production feed and key are configured, update checking remains safely disabled.