Unison

This document describes how to set up bidirectional synchronisation of wallpaper images between a macOS computer and a Raspberry Pi using Unison.

Prerequisites

macOS computer with Homebrew installed
Raspberry Pi running Raspbian
SSH access to your Raspberry Pi
Basic knowledge of terminal commands

Directory Paths

macOS: $HOME/Pictures/wallpaper
Raspberry Pi: $HOME/runtipi/media/data/images/wallpaper

Installation

On macOS

brew install unison

On Raspberry Pi

sudo apt-get update
sudo apt-get install unison

Basic Usage

Bidirectional Synchronisation

This command synchronises files in both directions, maintaining consistency between both folders:

unison ~/Pictures/wallpaper ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper -batch -auto

Replace raspberry-pi-hostname with your Pi’s actual hostname or IP address.

One-way Synchronisation (Pull from Pi)

This command pulls all files from the Pi to your Mac, overwriting local changes:

unison ~/Pictures/wallpaper ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper -batch -prefer ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper

One-way Synchronisation (Push to Pi)

This command pushes all files from your Mac to the Pi, overwriting changes on the Pi:

unison ~/Pictures/wallpaper ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper -batch -prefer ~/Pictures/wallpaper

Setting Up Profiles

Unison profiles make it easier to run commands with preset options.

Create Profiles Directory

mkdir -p ~/.unison

Bidirectional Sync Profile

Create a file at ~/.unison/wallpaper.prf with the following content:

# Roots of the synchronisation
root = /Users/yourusername/Pictures/wallpaper
root = ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper

# General options
auto = true
batch = true
confirmbigdel = true
fastcheck = true
times = true

# Log output to a file
log = true
logfile = /Users/yourusername/.unison/wallpaper-sync.log

# File patterns to ignore
ignore = Name .DS_Store
ignore = Name ._.DS_Store
ignore = Name Thumbs.db

Replace yourusername and raspberry-pi-hostname with your actual values.

Pull-only Profile

Create a file at ~/.unison/wallpaper-pull.prf with the following content:

# Roots of the synchronisation
root = /Users/yourusername/Pictures/wallpaper
root = ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper

# General options
auto = true
batch = true
fastcheck = true
times = true

# Always prefer the Pi's version
prefer = ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper

# Log output to a file
log = true
logfile = /Users/yourusername/.unison/wallpaper-pull.log

# File patterns to ignore
ignore = Name .DS_Store
ignore = Name ._.DS_Store
ignore = Name Thumbs.db

Push-only Profile

Create a file at ~/.unison/wallpaper-push.prf with the following content:

# Roots of the synchronisation
root = /Users/yourusername/Pictures/wallpaper
root = ssh://pi@raspberry-pi-hostname//home/pi/runtipi/media/data/images/wallpaper

# General options
auto = true
batch = true
fastcheck = true
times = true

# Always prefer the Mac's version
prefer = /Users/yourusername/Pictures/wallpaper

# Log output to a file
log = true
logfile = /Users/yourusername/.unison/wallpaper-push.log

# File patterns to ignore
ignore = Name .DS_Store
ignore = Name ._.DS_Store
ignore = Name Thumbs.db

Running with Profiles

Once your profiles are set up, you can run Unison with simple commands:

Bidirectional sync: unison wallpaper
Pull from Pi: unison wallpaper-pull
Push to Pi: unison wallpaper-push

Automating with Cron

You can schedule regular syncs using cron:

crontab -e

Add one of the following lines depending on your preference:

# Bidirectional sync every hour
0 * * * * /usr/local/bin/unison wallpaper

# Pull from Pi daily at 9am
0 9 * * * /usr/local/bin/unison wallpaper-pull

# Push to Pi daily at 6pm
0 18 * * * /usr/local/bin/unison wallpaper-push

Troubleshooting

SSH Authentication Issues

If you encounter SSH authentication problems, set up passwordless SSH:

Generate SSH key (if you don’t already have one):
Terminal window
```
ssh-keygen -t ed25519
```
Copy your key to the Raspberry Pi:
Terminal window
```
ssh-copy-id pi@raspberry-pi-hostname
```

Version Mismatch

Unison requires the same version on both systems. If you encounter version errors:

Check versions:

unison -version   # On Mac
ssh pi@raspberry-pi-hostname 'unison -version'  # On Pi

If they don’t match, you may need to compile from source on one system to match the other.

Large File Transfer Issues

For very large collections, initial sync might time out. Try:

unison wallpaper -batch -auto -maxthreads 1 -confirmbigdel=false

Notes

First sync will be slower as Unison builds its database
Default conflict resolution in batch mode is to skip the file
The log files contain details of each sync operation
Consider using rsync for one-time bulk transfers of large collections