How to use multiple link-dest directories?

[Maynard Handley]

Hi guys,
I hope this is not considered a stupid question, but it really seems  
to be something that needs to be covered with a decent example in the  
man page. I have looked in every piece of documentation I can think  
of and have found no answer.

So I want to use the multiple link-dest directories feature as of  
2.6.4. (I am using 2.6.6)
My understanding of how this should work is that I can have say
* directory BASE_OS/1 which is the most recent version of stuff I  
believe to be common to all my backups and
* directory SOME_MACHINE/1 which is the most recent version of a  
machine specific backup and
* I can have rsync, when told to backup SOME_MACHINE to SOME_MACHINE/ 
0, for each file
++ first look in SOME_MACHINE/0 for a match (won't exist in the usual  
case that SOME_MACHINE/0 is created from scratch)
++ then look in BASE_OS/1 for a match, to which a hard link will be  
constructed in SOME_MACHINE/0
++ then, if that doesn't work, look in SOME_MACHINE/1 for a match, to  
which a hard link will be consructed in SOME_MACHINE/0
++ then finally if that fails, copy the file over and create it in  
SOME_MACHINE/0

OK, so assuming my understanding the nature of the feature is correct  
(ie that it's the obvious extension to link-dest that we've all been  
using on single directories for a long time; and that it's not subtly  
different in some weird way) we are faced with the following  
apparently trivial problem:
How the fsck do I specify to rsync what I want the two directories to  
be?

Attempt one was the simple-minded
	$RSYNC_LOCAL -axHEz  --delete --delete-excluded --delete-after				\
	  --exclude-from=/Users/handleym/bin/backup_excludes.txt 					\
	  --ea-checksum																\
	  --link-dest=$BASE_SRC/1/ $DST_DIR/1/ 				\
	  --rsync-path=$RSYNC_REMOTE												\
	  --stats 																	\
	  $SRC_DIR		$DST_DIR/0/ 												\
	2>&1 >> $LOG_FILE
This fails to parse. rsync apparently treats "--link-dest=$BASE_SRC/ 
1/" as a single unit, treats the next "$DST_DIR/1/" as the src  
directory specifier, and goes off the rails.

OK, next we try
	$RSYNC_LOCAL -axHEz  --delete --delete-excluded --delete-after				\
	  --exclude-from=/Users/handleym/bin/backup_excludes.txt 					\
	  --ea-checksum																\
	  --link-dest="$BASE_SRC/1/  $DST_DIR/1/" 				\
	  --rsync-path=$RSYNC_REMOTE												\
	  --stats 																	\
	  $SRC_DIR		$DST_DIR/0/ 												\
	2>&1 >> $LOG_FILE

with " quotation marks around the two directories. (I think I came up  
with this based on a web search which showed that this was how other  
apps handled this sort of thing.)

This parses just fine, only problem is it doesn't work. Worse than it  
doesn't work --- apparently no link-dest action at all occurs now ---  
the backup is the size of the source and a look-see shows that  
everything's link count is one. Looking at what happens in hyper- 
verbosity mode shows none of the traffic ("filename matched" sort of  
stuff) that one would expect to see when link-dest is on, just the  
sort of behavior one gets with no link-dest specified.
So what's going on? Best I can do is to run my backup script using  
bash -x so
sudo bash -x bak12
which outputs that the command line being used is
/Users/handleym/bin/rsync ... '--link-dest=$BASE_SRC/1/  $DST_DIR/ 
1/' ...
with the significant point being that the link-dest stuff is  
completely in single 's, while nothing else is.
This looks legit, but what do I know?

So we return to the original problem. It would be really nice if the  
man page (and perhaps also the "What's new" file) not only told us  
about this shiny new feature but also told us how to use it. (Use it  
both in a direct command-line and in a bash script if there is some  
quoting weirdness that differs between these two cases.)

I guess the other alternative is that my syntax is fine and there is  
simply a bug in the feature, but that seems awfully unlikely --- I'd  
imagine when this was added in 2.6.4 it got at least some testing.

Thanks,
Maynard Handley