The output of --list-only isn't as I expected as regards symlinks. Here are my test files:
$ ls ./src
-rw------- 1 michael michael 0 2018-09-05 09:18:15 file
lrwxrwxrwx 1 michael michael 4 2018-09-05 09:18:28 near_symlink -> file
-rw------- 1 michael michael 0 2018-09-13 12:39:41 exclude
lrwxrwxrwx 1 michael michael 4 2018-09-13 12:40:47 far_symlink -> /etc
I want to know which files are candidates to transfer. I don't want symlinks to transfer. I run it with --list-only :
$ rsync -r --no-links --list-only --exclude="/excl*" ./src/
drwx------ 4,096 2018/09/13 12:40:47 .
lrwxrwxrwx 4 2018/09/13 12:40:47 far_symlink
-rw------- 0 2018/09/05 09:18:15 file
lrwxrwxrwx 4 2018/09/05 09:18:28 near_symlink
This seems to indicate the symlinks are expected to transfer. Note that --list-only correctly handles exclusions.
But when I actually run the transfer, the symlinks are not transferred:
$ rsync -r --no-links --exclude="/excl*" ./src/ ./dest
skipping non-regular file "far_symlink"
skipping non-regular file "near_symlink"
$ ls ./dest
-rw------- 1 michael michael 0 2018-09-13 12:49:06 file
So it seems like --list-only is not being truthful as regards symlinks. Or else I misunderstand the purpose of --list-only.
So I am submitting a request to either:
a) correct the output of --list-only, or
b) have the purpose and intended use case of --list-only be better explained in the docs.
The --list-only option just tells rsync to do some remote file listings. You should use --dry-run if you want to know what a transfer is going to do.
I'm sorry, I don't understand. The first line in the docs says:
"This option will cause the source files to be listed instead of transferred."
It doesn't say anything about "remote". It would seem to be a viable way to list the files that rsync will consider as candidates to transfer.
It obeys the exclusions and such, why does it not obey such for its treatment of symlinks?
Using --dry-run isn't really a substitute as it requires a connection to the remote server (destination) in the case of an ssh transfer. So it cannot be used if that remote server is not accessible.
Is there any way to get a "correct" list of the files rsync will consider as candidates to transfer, but without making an unnecessary connection to the remote end?
I believe I talked to you in IRC about which is why I didn't respond when this was first posted but I think I can help explain this better...
The --list-only option is to turn rsync into a network capable ls. It allows you to look around a remote filesystem that you can only access via rsync over ssh or rsyncd. It kinda implements some rsync options to kinda do more of what ls can do but it is still a bit of a kludge to allow you to look around. For local stuff using ls is a much better idea.
That being said, if you want rsync output even if your target is unavailable you can always talk to localhost. You can do something like:
rsync --verbose --archive --itemize-changes --dry-run --ignore-times ./ localhost:`pwd`/
The --ignore-times is there so rsync will think all files need to be copied and therefore they will always all be listed. Otherwise ./ and localhost:`pwd`/ will always be identical and nothing would be listed.
(In reply to Kevin Korb from comment #3)
Thanks for the explanation. I would encourage someone to consider updating the documentation to be more like what you wrote - as what I get from reading the man page is nothing at all like that.
> rsync --verbose --archive --itemize-changes --dry-run --ignore-times ./ localhost:`pwd`/
Thanks for this. I will give it a try when I get back on that project.