Overlays with rsync

I’ve been using rsync to build my site as a combination of a base layer held in git plus an overlay generated using Nanoc. Here’s how.

Each time the new site overlay is generated, rsync gets called as follows:

$ rsync -avr --no-times --delete --checksum --files-from=deploy/files \
    output/ $DESTINATION

This takes an overlay from output/ and writes it onto the $DESTINATION. The overlay is specified by deploy/files, which contains a list of the files and directories forming the overlay, including:

/.htaccess
/404.html
/assets
/blog
/photography
/there

The rsync options are of course the real meat of this:

• -a means “archive mode”; this means that things like file modes are copied across.
• -v means “verbose”.
• -r means “recursive”. That would normally be implied by -a, but it is suppressed by default when using --files-from.
• --no-times stops the copying across of the modification time for files that have not themselves been modified. Creation and modification times have no meaning when we’re regenerating the entire overlay so frequently.
• --delete forces deletion of files in the destination that are no longer part of the overlay.
• --checksum means that we don’t look at things like file creation and modification times to determine whether a file has changed. This means that rsync behaves more sensibly in an environment where all the files are being regenerated every time; only the ones whose contents have been changed will be copied across again.

I’m not far from the point where I will want to reverse this arrangement. At that point, I will be copying across the entire contents of output/ and protecting only selected files in the destination. It looks like the --filter option and protect rules will be the way to go for that. Fortunately rsync has a --dry-run option to allow for experiments.