The exact filename tested against include/exclude patterns is not always
obvious, and the documentation is somewhat ambiguous about it. This
bites particularly when using patterns starting with '/'. I just spent
an hour being confused by this. Here are some suggested edits to the
documentation.
Current:
The filenames matched against the exclude/include patterns are
relative to the destination directory, or "top directory", so
patterns should not include the path elements of the source or
destination directories. The only way in which a pattern will match
the absolute path of a file or directory is if the source path is
the root directory.
The first sentence up to the comma is (AFAICT) exactly accurate. The
term "top directory" is vague and superfluous; stick with destination
directory. The warning against including the source directory is
totally wrong when using --relative, and is even partly wrong for source
files that don't end with '/' (because then the last component of
the
source is in the destination tree). The last sentence is wrong with
--relative.
Suggested:
The filenames matched against the exclude/include patterns are
relative to the destination directory. Note that different amounts
of the source filename may be included, depending on how rsync is
invoked. For example, if you have a file /home/me/foo/bar, then for
the rsync commands
rsync -a /home/me /dest
rsync -a /home/me/ /dest
rsync -a --relative /home/me /dest
this file is matched against as
/me/foo/bar
/foo/bar
/home/me/foo/bar
respectively. The difference is particularly important when you use
patterns starting with / (see below).
In the rest of the section, there is a reference to the "transferred
tree" (which is wrong) and three references to the "top
directory"
(which, as above, is vague). I think it would be better to say
"destination tree" and "destination directory".
Andrew
On Thu, Mar 25, 2004 at 11:03:31PM -0500, Andrew Pimlott wrote:> The exact filename tested against include/exclude patterns is not > always obvious, and the documentation is somewhat ambiguous about it. > This bites particularly when using patterns starting with '/'.Yes, this could certainly use some improvement to make things clearer. I've never liked the description of the patterns being relative to the destination directory, though, since the patterns also affect files on the source side. I prefer the phrase "root of the transfer", which would have to be defined in the documentation. What about something like this? The filenames matched against the exclude/include patterns are relative to the "root of the transfer". If you think of the transfer as a subtree of names that are being sent from sender to receiver, the root is where the tree starts to be duplicated in the destination directory. This root governs where patterns that start with a / match (see below). Because the matching is relative to the transfer root, changing the trailing slash on the source path or changing your use of the --relative option affects the names you need to use in your matching. For example, using these rsync commands: rsync -a /home/me /dest rsync -a /home/me/ /dest rsync -a --relative /home/me /dest the file /home/me/foo/bar would be matched using, respectively: /me/foo/bar /foo/bar /home/me/foo/bar The easiest way to see what name you should include/exclude is to just look at the output when using --verbose and put a / in front of the name (use the --dry-run option if you're not yet ready to copy any files). ..wayne..