exclude confusion: what does it match against?

John Van Essen vanes002 at umn.edu
Sat Mar 27 02:55:48 GMT 2004

On Fri, 26 Mar 2004, Wayne Davison <wayned at samba.org> wrote:
> 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).

This is another opportunity to (try to) make more clear the
effects of using a trailing slash on the source and using the
--relative option.  They not only affect the absolute-path
pattern but also where the source file ends up on the target.

I'd like to see something like this included in the explanation.
(And I'm not even 100% sure these details are correct...)


The following examples demonstrate the effect that various
invocations of rsync have on the Include and Exclude pattern
needed to match a source filename of "/home/me/foo/bar", and
also show the resulting file path on the target:

Example cmd: rsync -a /home/me /dest
Source root: /home                 (NOT /home/me)
Target root: /dest
I/E pattern: /me/foo/bar
Source file: /home/me/foo/bar
Target file: /dest/me/foo/bar

Example cmd: rsync -a /home/me/ /dest
Source root: /home/me              (due to trailing /)
Target root: /dest
I/E pattern: /foo/bar              (note missing 'me')
Source file: /home/me/foo/bar
Target file: /dest/foo/bar         (note missing 'me')

Example cmd: rsync -a --relative /home/me /dest
Source root: /home
Target root: /dest
I/E pattern: /home/me/foo/bar      (note full path)
Source file: /home/me/foo/bar
Target file: /dest/home/me/foo/bar (note full path)

        John Van Essen  Univ of MN Alumnus  <vanes002 at umn.edu>

More information about the rsync mailing list