Include Exclude .. a canonical way

[Matt McCutchen]

On Sat, 2006-02-25 at 10:27 -0600, Harry Putnam wrote:
> Matt McCutchen <hashproduct at verizon.net> writes:
> > 	rsync --exclude=/.kde* --relative ~/./ \
> >             ~/./.kde3.5/share/apps/konqueror/bookmarks.xml dest/
> 
> Nice, but what else might the --relative inclusion do? I remember some
> time in the past having that set in rsnaphshot config and ending up
> with a really confusing directory structure under the backup dest.

All --relative does is cause rsync to duplicate the source path (minus
any leading /) inside the destination.  For example, the command
	cd / && rsync usr/ home/matt/ /backup/
mixes my personal files with bin, lib, share, src, and so forth
immediately inside the backup folder.  But
	cd / && rsync --relative usr/ home/matt/ /backup/
creates /backup/usr and /backup/home/matt .

--relative is useful when you are copying multiple sources and want them
to wind up in the same locations relative to each other in the
destination, whether you copy all the sources in one rsync command or
each source in its own command.  Rsnapshot passes --relative by default
and runs a separate rsync command for each "backup" entry in the
configuration file.  Given this configuration file:
	snapshot_root	/snapshots/
	backup  /home/          localhost/
	backup  /etc/           localhost/
	backup  /usr/local/     localhost/
rsnapshot runs:
	rsync <other-options> --relative /home/ /snapshots/localhost/
	rsync <other-options> --relative /etc/ /snapshots/localhost/
	rsync <other-options> --relative /usr/local/ /snapshots/localhost/
and the following directories are created:
	/snapshots/localhost/home
	/snapshots/localhost/etc
	/snapshots/localhost/usr/local

A configuration file like this...
	snapshot_root	/snapshots/
	backup  /home/          localhost/home/
	backup  /etc/           localhost/etc/
	backup  /usr/local/     localhost/usr/local/
will create the following "really confusing directory structure" unless
you turn --relative off by setting rsync_long_args:
	/snapshots/localhost/home/home
	/snapshots/localhost/etc/etc
	/snapshots/localhost/usr/local/usr/local

So --relative is useful if you set the destination path appropriately.
However, in some cases you may only want to duplicate a suffix of the
source path inside the destination; to do that, put a ./ in front of
that suffix.  The command
	rsync --exclude=/.kde* --relative ~/ \
		~/.kde3.5/share/apps/konqueror/bookmarks.xml /dest/
would create /dest/home/harry/ and /dest/home/harry/.kde3.5/share/
apps/konqueror/bookmarks.xml , but your original command matched your
home directory with /dest/ itself.  Using ./ gives the desired behavior:
	rsync --exclude=/.kde* --relative ~/./ \
		~/./.kde3.5/share/apps/konqueror/bookmarks.xml /dest/
Now you get /dest/.kde3.5/share/apps/konqueror/bookmarks.xml because the
part of the source path after the ./ is duplicated inside the
destination.
-- 
Matt McCutchen
hashproduct at verizon.net
http://hashproduct.metaesthetics.net/