rsync: Why doesn't --archive imply --recursive when --files-from=FILE is used?

Question

Using -r or --recursive causes rsync to recurse into directories. -a or --archive equals -rlptgoD, so -a implies -r.

If I have directories source/ and dest/ and I run:

rsync source dest

then rsync skips source/ and does not copy anything. If I run:

rsync -a source dest

then -a implies -r and rsync copies source/ and all of its contents to dest/.

But if I have a file list.txt that contains the line source, and the full path of my directory source/ is /home/user/source/, and I run:

rsync -a --files-from=list.txt /home/user/ dest

then rsync only copies source/ to dest/ but does not copy its contents. The same happens if I run the command without the -a option.

But if I run the same command with -r:

rsync -r --files-from=list.txt /home/user/ dest

then rsync copies source/ and all of its contents to dest/.

My questions are:

• Why doesn't -a imply -r when the --files-from=FILE option is used? Is this expected behavior?
• Given that the command rsync source dest skips source/ and copies nothing because source/ is a directory and neither -a nor -r is used, why does the command rsync --files-from=list.txt /home/user/ dest still copy source/ to dest/?
• Do the other options implied by -a still work when the --files-from=FILE option is used? Is -r the only option that is left out?

Edit: Looks like I should have read the man page more thoroughly. Under the description of the --files-from=FILE option it says:

The --archive (-a) option’s behavior does not imply --recursive (-r), so specify it explicitly, if you want it.

(Answers my first question.)

The --dirs (-d) option is implied, which will create directories specified in the list on the destination rather than noisily skipping them (use --no-dirs or --no-d if you want to turn that off).

(Answers my second question.)

Answer 1

-a, --archive

This is equivalent to -rlptgoD. It is a quick way of saying you want recursion and want to preserve almost everything (with -H being a notable omission). The only exception to the above equivalence is when --files-from is specified, in which case -r is not implied.

When you use --files-from, the recursion is disabled (this is the only option left out). It is assumed that the user knows exactly what specific files to transfer and that they have specified these in the file list that they use with --files-from.

If a directory is specified in the file list, its ownership, timestamp etc. will be synchronised, but not its content.

You may add the -r flag explicitly though:

rsync -av --files-from=file.list -r src/ dst/

This will have the effect that you are looking for.