X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d1cce1dd9209f5fde2b58f798bf8eea8cf82f99f..b19fd07c023c3923979ba965e8f485433d7ecf18:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 5360d43b..fce0267c 100644 --- a/rsync.yo +++ b/rsync.yo @@ -290,9 +290,9 @@ verb( -R, --relative use relative path names --no-relative turn off --relative --no-implied-dirs don't send implied dirs with -R - -b, --backup make backups (default ~ suffix) + -b, --backup make backups (see --suffix) --backup-dir make backups into this directory - --suffix=SUFFIX define backup suffix + --suffix=SUFFIX define backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of symlinks @@ -452,9 +452,10 @@ the --no-implied-dirs option would omit both of these implied dirs, which means that if "/path" was a real directory on one machine and a symlink of the other machine, rsync would not try to change this. -dit(bf(-b, --backup)) With this option preexisting destination files are -renamed with a ~ extension as each file is transferred. You can -control the backup suffix using the --suffix option. +dit(bf(-b, --backup)) With this option, preexisting destination files are +renamed as each file is transferred or deleted. You can control where the +backup file goes and what (if any) suffix gets appended using the +--backup-dir and --suffix options. dit(bf(--backup-dir=DIR)) In combination with the --backup option, this tells rsync to store all backups in the specified directory. This is @@ -464,9 +465,8 @@ specify a backup suffix using the --suffix option will keep their original filenames). dit(bf(--suffix=SUFFIX)) This option allows you to override the default -backup suffix used with the -b option. The default is a ~. -If --backup-dir and --suffix are both specified, -the SUFFIX is appended to the filename even in the backup directory. +backup suffix used with the --backup (-b) option. The default suffix is a ~ +if no --backup-dir was specified, otherwise it is an empty string. dit(bf(-u, --update)) This forces rsync to skip any files for which the destination file already exists and has a date later than the source @@ -507,8 +507,13 @@ the source and target are on the local machine. dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the default. -dit(bf(-p, --perms)) This option causes rsync to update the remote -permissions to be the same as the local permissions. +dit(bf(-p, --perms)) This option causes rsync to set the destination +permissions to be the same as the source permissions. + +Without this option, each new file gets its permissions set based on the +source file's permissions and the umask at the receiving end, while all +other files (including updated files) retain their existing permissions +(which is the same behavior as other file-copy utilities, such as cp). dit(bf(-o, --owner)) This option causes rsync to set the owner of the destination file to be the same as the source file. On most systems, @@ -734,6 +739,8 @@ dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but also will create hard links from em(DIR) to the destination directory for unchanged files. Files with changed ownership or permissions will not be linked. +Like bf(--compare-dest) if DIR is a relative path, it is relative +to the destination directory. dit(bf(-z, --compress)) With this option, rsync compresses any data from the files that it sends to the destination machine. This @@ -864,18 +871,19 @@ The exclude and include patterns specified to rsync allow for flexible selection of which files to transfer and which files to skip. rsync builds an ordered list of include/exclude options as specified on -the command line. When a filename is encountered, rsync checks the +the command line. Rsync checks each file and directory name against each exclude/include pattern in turn. The first matching pattern is acted on. If it is an exclude pattern, then that file is skipped. If it is an include pattern then that filename is not skipped. If no matching include/exclude pattern is found then the filename is not skipped. -The filenames matched against the exclude/incldue patterns are -relative to the base directories so patterns should not -include the path elements to those base directories. The -only way in which a pattern will match the absolute path of -a file or directory is if the base path is the root directory. +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. Note that when used with -r (which is implied by -a), every subcomponent of every path is visited from top down, so include/exclude patterns get @@ -893,7 +901,8 @@ itemize( start of the filename, otherwise it is matched against the end of the filename. This is the equivalent of a leading ^ in regular expressions. - Thus "/foo" would match a file called "foo" at the base of the tree. + Thus "/foo" would match a file called "foo" at the top of the + transferred tree. On the other hand, "foo" would match any file called "foo" anywhere in the tree because the algorithm is applied recursively from top down; it behaves as if each path component gets a turn at being the @@ -907,15 +916,15 @@ itemize( *?[ then expression matching is applied using the shell filename matching rules. Otherwise a simple string match is used. - it() if the pattern includes a double asterisk "**" then all wildcards in - the pattern will match slashes, otherwise they will stop at slashes. + it() the double asterisk pattern "**" will match slashes while a + single asterisk pattern "*" will stop at slashes. - it() if the pattern contains a / (not counting a trailing /) then it - is matched against the full filename, including any leading - directory. If the pattern doesn't contain a / then it is matched - only against the final component of the filename. Again, remember - that the algorithm is applied recursively so "full filename" can - actually be any portion of a path. + it() if the pattern contains a / (not counting a trailing /) or a "**" + then it is matched against the full filename, including any leading + directory. If the pattern doesn't contain a / or a "**", then it is + matched only against the final component of the filename. Again, + remember that the algorithm is applied recursively so "full filename" can + actually be any portion of a path below the starting directory. it() if the pattern starts with "+ " (a plus followed by a space) then it is always considered an include pattern, even if specified as @@ -929,8 +938,9 @@ itemize( include/exclude list is reset, removing all previously defined patterns. ) -The +/- rules are most useful in exclude lists, allowing you to have a -single exclude list that contains both include and exclude options. +The +/- rules are most useful in a list that was read from a file, allowing +you to have a single exclude list that contains both include and exclude +options. If you end an exclude list with --exclude '*', note that since the algorithm is applied recursively that unless you explicitly include @@ -943,12 +953,12 @@ Here are some exclude/include examples: itemize( it() --exclude "*.o" would exclude all filenames matching *.o - it() --exclude "/foo" would exclude a file in the base directory called foo + it() --exclude "/foo" would exclude a file called foo in the top directory it() --exclude "foo/" would exclude any directory called foo it() --exclude "/foo/*/bar" would exclude any file called bar two - levels below a base directory called foo + levels below a directory called foo in the top directory it() --exclude "/foo/**/bar" would exclude any file called bar two - or more levels below a base directory called foo + or more levels below a directory called foo in the top directory it() --include "*/" --include "*.c" --exclude "*" would include all directories and C source files it() --include "foo/" --include "foo/bar.c" --exclude "*" would include