[PATCH] Clarify escaping in wildcard patterns documentation

[Erik Auerswald]

Hi,

On Tue, Apr 15, 2014 at 03:01:46PM -0700, Wayne Davison wrote:
> On Thu, Apr 3, 2014 at 1:47 AM, Erik Auerswald
> <auerswal at unix-ag.uni-kl.de>wrote:
> 
> > the attached patch IMHO improves the man page regarding use of the
> > backslash as escape character in wildcard patterns.
> 
> I'm not sure what you mean by your change. If you type something like
> "rsync -aiv foo\bar /tmp" it will copy the file foobar in a typical un*x
> shell.

In your example the \ is removed by the shell.

Assume that proper quoting is used and rsync sees all the escape
(i.e. '\') and wildcard (i.e. '*', '?', '[') characters.

'foo\bar' is a non-wildcard pattern matching 'foo\bar', but not 'foobar'.

'fo[o]\bar' is a wildcard pattern matching 'foobar', but not
'foo\bar'. The backslash is removed by rsync, because it occurs inside
a wildcard pattern.

'fo[o]\\bar' is a wildcard pattern matching 'foo\bar', but not 'foobar'.

> If you notice anything different than that, then it is something
> your shell does, not rsync.

Nope, I know my shell. ;-)

> Is there some other place that you are referring to?

The patch adds a sentence to the 'INCLUDE/EXCLUDE PATTERN RULES' section
of the man page, because I noticed the issue while reading a strange
exclude pattern ('*\.ext') that looked wrong, but worked. The pattern
is equivalent to '*.ext', the backslash is just removed.

I would prefer if rsync did not distinguish between wildcard and
non-wildcard patterns, but that is a change in behavior and might break
existing scripts.

Adding suggested sentence to the man page gives puzzled script
reviewers who consult the docs a quick explanation why the non-sensical
pattern works anyway and how the backslash is treated in wildcard
and non-wildcard patterns. The current wording of '...backslash can
be used to escape...' is a bit vague regarding backslashes preceding
non-wildcard characters in a wildcard pattern. As it is written now it
could be interpreted as if a backslash is retained if it is not preceding
a wildcard character.

Thanks,
Erik
-- 
Trying to understand [the GNU GPL] in terms of the goals and values
of open source is like trying [to] understand a CD drive's retractable
drawer as a cupholder.
                        -- Richard Stallman