# HG changeset patch # User George Asaad # Date 1307739718 25200 # Node ID 464763778976bb68b1b7ed4df0fa531c93b57ac2 # Parent ae0cd5b7bed2458dda49fab36015d05f2543cde2 7034286 Problem with utility/rsync diff -r ae0cd5b7bed2 -r 464763778976 components/rsync/Makefile --- a/components/rsync/Makefile Thu Jun 09 17:28:09 2011 -0700 +++ b/components/rsync/Makefile Fri Jun 10 14:01:58 2011 -0700 @@ -26,11 +26,11 @@ include ../../make-rules/shared-macros.mk COMPONENT_NAME= rsync -COMPONENT_VERSION= 3.0.6 +COMPONENT_VERSION= 3.0.8 COMPONENT_SRC= $(COMPONENT_NAME)-$(COMPONENT_VERSION) COMPONENT_PROJECT_URL= http://rsync.samba.org COMPONENT_ARCHIVE= $(COMPONENT_SRC).tar.gz -COMPONENT_ARCHIVE_HASH= sha1:8853dfd291b3850aafa60169d2eea8601498f713 +COMPONENT_ARCHIVE_HASH= sha1:10e80173c7e9ed8b8a4dc9e8fdab08402da5f08d COMPONENT_ARCHIVE_URL= http://rsync.samba.org/ftp/rsync/src/$(COMPONENT_ARCHIVE) COPYRIGHT_FILE= rsync.copyright @@ -50,12 +50,6 @@ test: $(NO_TESTS) -# -# The install target in the automatically generated Makefile only check the man pages -# file under $(BUILD_DIR_32). So copy the files there to make "gmake install" work -# correctly. -# - BUILD_PKG_DEPENDENCIES = $(BUILD_TOOLS) include ../../make-rules/depend.mk diff -r ae0cd5b7bed2 -r 464763778976 components/rsync/patches/rsync.1.patch --- a/components/rsync/patches/rsync.1.patch Thu Jun 09 17:28:09 2011 -0700 +++ b/components/rsync/patches/rsync.1.patch Fri Jun 10 14:01:58 2011 -0700 @@ -1,22 +1,5562 @@ ---- rsync-3.0.6.ori/rsync.1 Wed May 4 09:58:49 2011 -+++ rsync-3.0.6/rsync.1 Thu May 5 10:23:18 2011 -@@ -1213,9 +1213,8 @@ - up less space on the destination. Conflicts with \fB\-\-inplace\fP because it's - not possible to overwrite data in a sparse fashion. - .IP --NOTE: Don't use this option when the destination is a Solaris \(lqtmpfs\(rq --filesystem. It doesn't seem to handle seeks over null regions --correctly and ends up corrupting the files. -+NOTE: This option has no effect if the destination is a Solaris "tmpfs" -+filesystem. The files won't be sparse\&. - .IP - .IP "\fB\-n, \-\-dry\-run\fP" - This makes rsync perform a trial run that doesn't -@@ -3472,3 +3471,7 @@ - .PP - Mailing lists for support and development are available at - http://lists.samba.org -+.SH "NOTES" -+WARNING: Daemon mode does not participate in the core -+Solaris security policies, including Authentication, limit -+of privileges, Audit and Audit of any subprocessing. +*** rsync-3.0.6/rsync.1 Fri May 8 10:42:39 2009 +--- rsync-3.0.8/rsync.1 Sat Mar 26 14:37:52 2011 +*************** +*** 1,6 **** +! .TH "rsync" "1" "8 May 2009" "" "" + .SH "NAME" +! rsync \(em a fast, versatile, remote (and local) file-copying tool + .SH "SYNOPSIS" + + .PP +--- 1,6 ---- +! .TH "rsync" "1" "26 Mar 2011" "" "" + .SH "NAME" +! rsync \(em a fast, versatile, remote (and local) file\-copying tool + .SH "SYNOPSIS" + + .PP +*************** +*** 29,45 **** + copy locally, to/from another host over any remote shell, or to/from a + remote rsync daemon. It offers a large number of options that control + every aspect of its behavior and permit very flexible specification of the +! set of files to be copied. It is famous for its delta-transfer algorithm, + which reduces the amount of data sent over the network by sending only the + differences between the source files and the existing files in the + destination. Rsync is widely used for backups and mirroring and as an + improved copy command for everyday use. + .PP +! Rsync finds files that need to be transferred using a \(lqquick check\(rq + algorithm (by default) that looks for files that have changed in size or +! in last-modified time. Any changes in the other preserved attributes (as + requested by options) are made on the destination file directly when the +! quick check indicates that the file's data does not need to be updated. + .PP + Some of the additional features of rsync are: + .PP +--- 29,45 ---- + copy locally, to/from another host over any remote shell, or to/from a + remote rsync daemon. It offers a large number of options that control + every aspect of its behavior and permit very flexible specification of the +! set of files to be copied. It is famous for its delta\-transfer algorithm, + which reduces the amount of data sent over the network by sending only the + differences between the source files and the existing files in the + destination. Rsync is widely used for backups and mirroring and as an + improved copy command for everyday use. + .PP +! Rsync finds files that need to be transferred using a \(dq\&quick check\(dq\& + algorithm (by default) that looks for files that have changed in size or +! in last\-modified time. Any changes in the other preserved attributes (as + requested by options) are made on the destination file directly when the +! quick check indicates that the file\(cq\&s data does not need to be updated. + .PP + Some of the additional features of rsync are: + .PP +*************** +*** 46,58 **** + .IP o + support for copying links, devices, owners, groups, and permissions + .IP o +! exclude and exclude-from options similar to GNU tar + .IP o + a CVS exclude mode for ignoring the same files that CVS would ignore + .IP o + can use any transparent remote shell, including ssh or rsh + .IP o +! does not require super-user privileges + .IP o + pipelining of file transfers to minimize latency costs + .IP o +--- 46,58 ---- + .IP o + support for copying links, devices, owners, groups, and permissions + .IP o +! exclude and exclude\-from options similar to GNU tar + .IP o + a CVS exclude mode for ignoring the same files that CVS would ignore + .IP o + can use any transparent remote shell, including ssh or rsh + .IP o +! does not require super\-user privileges + .IP o + pipelining of file transfers to minimize latency costs + .IP o +*************** +*** 67,90 **** + current host (it does not support copying files between two remote hosts). + .PP + There are two different ways for rsync to contact a remote system: using a +! remote-shell program as the transport (such as ssh or rsh) or contacting an +! rsync daemon directly via TCP. The remote-shell transport is used whenever + the source or destination path contains a single colon (:) separator after + a host specification. Contacting an rsync daemon directly happens when the + source or destination path contains a double colon (::) separator after a + host specification, OR when an rsync:// URL is specified (see also the +! \(lqUSING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION\(rq section for + an exception to this latter rule). + .PP + As a special case, if a single source arg is specified without a +! destination, the files are listed in an output format similar to \(lqls \-l\(rq. + .PP + As expected, if neither the source or destination path specify a remote + host, the copy occurs locally (see also the \fB\-\-list\-only\fP option). + .PP +! Rsync refers to the local side as the \(lqclient\(rq and the remote side as the +! \(lqserver\(rq. Don't confuse \(lqserver\(rq with an rsync daemon \(em a daemon is always a +! server, but a server can be either a daemon or a remote-shell spawned process. + .PP + .SH "SETUP" + +--- 67,90 ---- + current host (it does not support copying files between two remote hosts). + .PP + There are two different ways for rsync to contact a remote system: using a +! remote\-shell program as the transport (such as ssh or rsh) or contacting an +! rsync daemon directly via TCP. The remote\-shell transport is used whenever + the source or destination path contains a single colon (:) separator after + a host specification. Contacting an rsync daemon directly happens when the + source or destination path contains a double colon (::) separator after a + host specification, OR when an rsync:// URL is specified (see also the +! \(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION\(dq\& section for + an exception to this latter rule). + .PP + As a special case, if a single source arg is specified without a +! destination, the files are listed in an output format similar to \(dq\&ls \-l\(dq\&. + .PP + As expected, if neither the source or destination path specify a remote + host, the copy occurs locally (see also the \fB\-\-list\-only\fP option). + .PP +! Rsync refers to the local side as the \(dq\&client\(dq\& and the remote side as the +! \(dq\&server\(dq\&. Don\(cq\&t confuse \(dq\&server\(dq\& with an rsync daemon \-\- a daemon is always a +! server, but a server can be either a daemon or a remote\-shell spawned process. + .PP + .SH "SETUP" + +*************** +*** 93,99 **** + .PP + Once installed, you can use rsync to any machine that you can access via + a remote shell (as well as some that you can access using the rsync +! daemon-mode protocol). For remote transfers, a modern rsync uses ssh + for its communications, but it may have been configured to use a + different remote shell by default, such as rsh or remsh. + .PP +--- 93,99 ---- + .PP + Once installed, you can use rsync to any machine that you can access via + a remote shell (as well as some that you can access using the rsync +! daemon\-mode protocol). For remote transfers, a modern rsync uses ssh + for its communications, but it may have been configured to use a + different remote shell by default, such as rsh or remsh. + .PP +*************** +*** 119,125 **** + This would transfer all files matching the pattern *.c from the + current directory to the directory src on the machine foo. If any of + the files already exist on the remote system then the rsync +! remote-update protocol is used to update the file by sending only the + differences. See the tech report for details. + .PP + .RS +--- 119,125 ---- + This would transfer all files matching the pattern *.c from the + current directory to the directory src on the machine foo. If any of + the files already exist on the remote system then the rsync +! remote\-update protocol is used to update the file by sending only the + differences. See the tech report for details. + .PP + .RS +*************** +*** 129,135 **** + .PP + This would recursively transfer all files from the directory src/bar on the + machine foo into the /data/tmp/bar directory on the local machine. The +! files are transferred in \(lqarchive\(rq mode, which ensures that symbolic + links, devices, attributes, permissions, ownerships, etc. are preserved + in the transfer. Additionally, compression will be used to reduce the + size of data portions of the transfer. +--- 129,135 ---- + .PP + This would recursively transfer all files from the directory src/bar on the + machine foo into the /data/tmp/bar directory on the local machine. The +! files are transferred in \(dq\&archive\(dq\& mode, which ensures that symbolic + links, devices, attributes, permissions, ownerships, etc. are preserved + in the transfer. Additionally, compression will be used to reduce the + size of data portions of the transfer. +*************** +*** 141,148 **** + .PP + A trailing slash on the source changes this behavior to avoid creating an + additional directory level at the destination. You can think of a trailing +! / on a source as meaning \(lqcopy the contents of this directory\(rq as opposed +! to \(lqcopy the directory by name\(rq, but in both cases the attributes of the + containing directory are transferred to the containing directory on the + destination. In other words, each of the following commands copies the + files in the same way, including their setting of the attributes of +--- 141,148 ---- + .PP + A trailing slash on the source changes this behavior to avoid creating an + additional directory level at the destination. You can think of a trailing +! / on a source as meaning \(dq\© the contents of this directory\(dq\& as opposed +! to \(dq\© the directory by name\(dq\&, but in both cases the attributes of the + containing directory are transferred to the containing directory on the + destination. In other words, each of the following commands copies the + files in the same way, including their setting of the attributes of +*************** +*** 156,164 **** + .RE + + .PP +! Note also that host and module references don't require a trailing slash to + copy the contents of the default directory. For example, both of these +! copy the remote directory's contents into \(lq/dest\(rq: + .PP + .RS + \f(CWrsync \-av host: /dest\fP +--- 156,164 ---- + .RE + + .PP +! Note also that host and module references don\(cq\&t require a trailing slash to + copy the contents of the default directory. For example, both of these +! copy the remote directory\(cq\&s contents into \(dq\&/dest\(dq\&: + .PP + .RS + \f(CWrsync \-av host: /dest\fP +*************** +*** 168,175 **** + .RE + + .PP +! You can also use rsync in local-only mode, where both the source and +! destination don't have a \(oq:\(cq in the name. In this case it behaves like + an improved copy command. + .PP + Finally, you can list all the (listable) modules available from a +--- 168,175 ---- + .RE + + .PP +! You can also use rsync in local\-only mode, where both the source and +! destination don\(cq\&t have a \(cq\&:\(cq\& in the name. In this case it behaves like + an improved copy command. + .PP + Finally, you can list all the (listable) modules available from a +*************** +*** 186,192 **** + + .PP + The syntax for requesting multiple files from a remote host is done by +! specifying additional remote-host args in the same style as the first, + or with the hostname omitted. For instance, all these work: + .PP + .RS +--- 186,192 ---- + + .PP + The syntax for requesting multiple files from a remote host is done by +! specifying additional remote\-host args in the same style as the first, + or with the hostname omitted. For instance, all these work: + .PP + .RS +*************** +*** 202,223 **** + examples: + .PP + .RS +! \f(CWrsync \-av host:'dir1/file1 dir2/file2' /dest\fP + .br +! \f(CWrsync host::'modname/dir1/file1 modname/dir2/file2' /dest\fP + .RE + + .PP +! This word-splitting still works (by default) in the latest rsync, but is + not as easy to use as the first method. + .PP + If you need to transfer a filename that contains whitespace, you can either +! specify the \fB\-\-protect\-args\fP (\fB\-s\fP) option, or you'll need to escape + the whitespace in a way that the remote shell will understand. For + instance: + .PP + .RS +! \f(CWrsync \-av host:'file\e name\e with\e spaces' /dest\fP + .RE + + .PP +--- 202,223 ---- + examples: + .PP + .RS +! \f(CWrsync \-av host:'\&dir1/file1 dir2/file2'\& /dest\fP + .br +! \f(CWrsync host::'\&modname/dir1/file1 modname/dir2/file2'\& /dest\fP + .RE + + .PP +! This word\-splitting still works (by default) in the latest rsync, but is + not as easy to use as the first method. + .PP + If you need to transfer a filename that contains whitespace, you can either +! specify the \fB\-\-protect\-args\fP (\fB\-s\fP) option, or you\(cq\&ll need to escape + the whitespace in a way that the remote shell will understand. For + instance: + .PP + .RS +! \f(CWrsync \-av host:'\&file\e name\e with\e spaces'\& /dest\fP + .RE + + .PP +*************** +*** 237,243 **** + you either use a double colon :: instead of a single colon to + separate the hostname from the path, or you use an rsync:// URL. + .IP o +! the first word of the \(lqpath\(rq is actually a module name. + .IP o + the remote daemon may print a message of the day when you + connect. +--- 237,243 ---- + you either use a double colon :: instead of a single colon to + separate the hostname from the path, or you use an rsync:// URL. + .IP o +! the first word of the \(dq\&path\(dq\& is actually a module name. + .IP o + the remote daemon may print a message of the day when you + connect. +*************** +*** 251,257 **** + you must not specify the \fB\-\-rsh\fP (\fB\-e\fP) option. + + .PP +! An example that copies all the files in a remote module named \(lqsrc\(rq: + .PP + .nf + rsync \-av host::src /dest +--- 251,257 ---- + you must not specify the \fB\-\-rsh\fP (\fB\-e\fP) option. + + .PP +! An example that copies all the files in a remote module named \(dq\&src\(dq\&: + .PP + .nf + rsync \-av host::src /dest +*************** +*** 269,286 **** + .PP + You may establish the connection via a web proxy by setting the + environment variable RSYNC_PROXY to a hostname:port pair pointing to +! your web proxy. Note that your web proxy's configuration must support + proxy connections to port 873. + .PP + You may also establish a daemon connection using a program as a proxy by + setting the environment variable RSYNC_CONNECT_PROG to the commands you + wish to run in place of making a direct socket connection. The string may +! contain the escape \(lq%H\(rq to represent the hostname specified in the rsync +! command (so use \(lq%%\(rq if you need a single \(lq%\(rq in your string). For + example: + .PP + .nf +! export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873' + rsync \-av targethost1::module/src/ /dest/ + rsync \-av rsync:://targethost2/module/src/ /dest/ + .fi +--- 269,286 ---- + .PP + You may establish the connection via a web proxy by setting the + environment variable RSYNC_PROXY to a hostname:port pair pointing to +! your web proxy. Note that your web proxy\(cq\&s configuration must support + proxy connections to port 873. + .PP + You may also establish a daemon connection using a program as a proxy by + setting the environment variable RSYNC_CONNECT_PROG to the commands you + wish to run in place of making a direct socket connection. The string may +! contain the escape \(dq\&%H\(dq\& to represent the hostname specified in the rsync +! command (so use \(dq\&%%\(dq\& if you need a single \(dq\&%\(dq\& in your string). For + example: + .PP + .nf +! export RSYNC_CONNECT_PROG='\&ssh proxyhost nc %H 873'\& + rsync \-av targethost1::module/src/ /dest/ + rsync \-av rsync:://targethost2/module/src/ /dest/ + .fi +*************** +*** 290,315 **** + which forwards all data to port 873 (the rsync daemon) on the targethost + (%H). + .PP +! .SH "USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" + + .PP + It is sometimes useful to use various features of an rsync daemon (such as + named modules) without actually allowing any new socket connections into a +! system (other than what is already required to allow remote-shell access). + Rsync supports connecting to a host using a remote shell and then spawning +! a single-use \(lqdaemon\(rq server that expects to read its config file in the + home dir of the remote user. This can be useful if you want to encrypt a +! daemon-style transfer's data, but since the daemon is started up fresh by + the remote user, you may not be able to use features such as chroot or + change the uid used by the daemon. (For another way to encrypt a daemon + transfer, consider using ssh to tunnel a local port to a remote machine and + configure a normal rsync daemon on that remote host to only allow +! connections from \(lqlocalhost\(rq.) + .PP +! From the user's perspective, a daemon transfer via a remote-shell +! connection uses nearly the same command-line syntax as a normal +! rsync-daemon transfer, with the only exception being that you must +! explicitly set the remote shell program on the command-line with the + \fB\-\-rsh=COMMAND\fP option. (Setting the RSYNC_RSH in the environment + will not turn on this functionality.) For example: + .PP +--- 290,315 ---- + which forwards all data to port 873 (the rsync daemon) on the targethost + (%H). + .PP +! .SH "USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION" + + .PP + It is sometimes useful to use various features of an rsync daemon (such as + named modules) without actually allowing any new socket connections into a +! system (other than what is already required to allow remote\-shell access). + Rsync supports connecting to a host using a remote shell and then spawning +! a single\-use \(dq\&daemon\(dq\& server that expects to read its config file in the + home dir of the remote user. This can be useful if you want to encrypt a +! daemon\-style transfer\(cq\&s data, but since the daemon is started up fresh by + the remote user, you may not be able to use features such as chroot or + change the uid used by the daemon. (For another way to encrypt a daemon + transfer, consider using ssh to tunnel a local port to a remote machine and + configure a normal rsync daemon on that remote host to only allow +! connections from \(dq\&localhost\(dq\&.) + .PP +! From the user\(cq\&s perspective, a daemon transfer via a remote\-shell +! connection uses nearly the same command\-line syntax as a normal +! rsync\-daemon transfer, with the only exception being that you must +! explicitly set the remote shell program on the command\-line with the + \fB\-\-rsh=COMMAND\fP option. (Setting the RSYNC_RSH in the environment + will not turn on this functionality.) For example: + .PP +*************** +*** 318,336 **** + .fi + + .PP +! If you need to specify a different remote-shell user, keep in mind that the +! user@ prefix in front of the host is specifying the rsync-user value (for a +! module that requires user-based authentication). This means that you must +! give the '\-l user' option to ssh when specifying the remote-shell, as in + this example that uses the short version of the \fB\-\-rsh\fP option: + .PP + .nf +! rsync \-av \-e "ssh \-l ssh-user" rsync-user@host::module /dest + .fi + + .PP +! The \(lqssh-user\(rq will be used at the ssh level; the \(lqrsync-user\(rq will be +! used to log-in to the \(lqmodule\(rq. + .PP + .SH "STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS" + +--- 318,336 ---- + .fi + + .PP +! If you need to specify a different remote\-shell user, keep in mind that the +! user@ prefix in front of the host is specifying the rsync\-user value (for a +! module that requires user\-based authentication). This means that you must +! give the \(cq\&\-l user\(cq\& option to ssh when specifying the remote\-shell, as in + this example that uses the short version of the \fB\-\-rsh\fP option: + .PP + .nf +! rsync \-av \-e \(dq\&ssh \-l ssh\-user\(dq\& rsync\-user@host::module /dest + .fi + + .PP +! The \(dq\&ssh\-user\(dq\& will be used at the ssh level; the \(dq\&rsync\-user\(dq\& will be +! used to log\-in to the \(dq\&module\(dq\&. + .PP + .SH "STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS" + +*************** +*** 339,349 **** + daemon already running (or it needs to have configured something like inetd + to spawn an rsync daemon for incoming connections on a particular port). + For full information on how to start a daemon that will handling incoming +! socket connections, see the \fBrsyncd.conf\fP(5) man page \(em that is the config + file for the daemon, and it contains the full details for how to run the +! daemon (including stand-alone and inetd configurations). + .PP +! If you're using one of the remote-shell transports for the transfer, there is + no need to manually start an rsync daemon. + .PP + .SH "EXAMPLES" +--- 339,349 ---- + daemon already running (or it needs to have configured something like inetd + to spawn an rsync daemon for incoming connections on a particular port). + For full information on how to start a daemon that will handling incoming +! socket connections, see the \fBrsyncd.conf\fP(5) man page \-\- that is the config + file for the daemon, and it contains the full details for how to run the +! daemon (including stand\-alone and inetd configurations). + .PP +! If you\(cq\&re using one of the remote\-shell transports for the transfer, there is + no need to manually start an rsync daemon. + .PP + .SH "EXAMPLES" +*************** +*** 351,357 **** + .PP + Here are some examples of how I use rsync. + .PP +! To backup my wife's home directory, which consists of large MS Word + files and mail folders, I use a cron job that runs + .PP + .RS +--- 351,357 ---- + .PP + Here are some examples of how I use rsync. + .PP +! To backup my wife\(cq\&s home directory, which consists of large MS Word + files and mail folders, I use a cron job that runs + .PP + .RS +*************** +*** 360,366 **** + + .PP + each night over a PPP connection to a duplicate directory on my machine +! \(lqarvidsjaur\(rq. + .PP + To synchronize my samba source trees I use the following Makefile + targets: +--- 360,366 ---- + + .PP + each night over a PPP connection to a duplicate directory on my machine +! \(dq\&arvidsjaur\(dq\&. + .PP + To synchronize my samba source trees I use the following Makefile + targets: +*************** +*** 367,373 **** + .PP + .nf + get: +! rsync \-avuzb \-\-exclude '*~' samba:samba/ . + put: + rsync \-Cavuzb . samba:samba/ + sync: get put +--- 367,373 ---- + .PP + .nf + get: +! rsync \-avuzb \-\-exclude '\&*~'\& samba:samba/ . + put: + rsync \-Cavuzb . samba:samba/ + sync: get put +*************** +*** 376,387 **** + .PP + this allows me to sync with a CVS directory at the other end of the + connection. I then do CVS operations on the remote machine, which saves a +! lot of time as the remote CVS protocol isn't very efficient. + .PP +! I mirror a directory between my \(lqold\(rq and \(lqnew\(rq ftp sites with the + command: + .PP +! \f(CWrsync \-az \-e ssh \-\-delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge"\fP + .PP + This is launched from cron every few hours. + .PP +--- 376,387 ---- + .PP + this allows me to sync with a CVS directory at the other end of the + connection. I then do CVS operations on the remote machine, which saves a +! lot of time as the remote CVS protocol isn\(cq\&t very efficient. + .PP +! I mirror a directory between my \(dq\&old\(dq\& and \(dq\&new\(dq\& ftp sites with the + command: + .PP +! \f(CWrsync \-az \-e ssh \-\-delete ~ftp/pub/samba nimbus:\(dq\&~ftp/pub/tridge\(dq\&\fP + .PP + This is launched from cron every few hours. + .PP +*************** +*** 393,417 **** + .nf + + \-v, \-\-verbose increase verbosity +! \-q, \-\-quiet suppress non-error messages +! \-\-no\-motd suppress daemon-mode MOTD (see caveat) +! \-c, \-\-checksum skip based on checksum, not mod-time & size + \-a, \-\-archive archive mode; equals \-rlptgoD (no \-H,\-A,\-X) + \-\-no\-OPTION turn off an implied OPTION (e.g. \-\-no\-D) + \-r, \-\-recursive recurse into directories + \-R, \-\-relative use relative path names +! \-\-no\-implied\-dirs don't send implied dirs with \-\-relative + \-b, \-\-backup make backups (see \-\-suffix & \-\-backup\-dir) + \-\-backup\-dir=DIR make backups into hierarchy based in DIR + \-\-suffix=SUFFIX backup suffix (default ~ w/o \-\-backup\-dir) + \-u, \-\-update skip files that are newer on the receiver +! \-\-inplace update destination files in-place + \-\-append append data onto shorter files + \-\-append\-verify \-\-append w/old data in file checksum + \-d, \-\-dirs transfer directories without recursing + \-l, \-\-links copy symlinks as symlinks + \-L, \-\-copy\-links transform symlink into referent file/dir +! \-\-copy\-unsafe\-links only "unsafe" symlinks are transformed + \-\-safe\-links ignore symlinks that point outside the tree + \-k, \-\-copy\-dirlinks transform symlink to dir into referent dir + \-K, \-\-keep\-dirlinks treat symlinked dir on receiver as dir +--- 393,417 ---- + .nf + + \-v, \-\-verbose increase verbosity +! \-q, \-\-quiet suppress non\-error messages +! \-\-no\-motd suppress daemon\-mode MOTD (see caveat) +! \-c, \-\-checksum skip based on checksum, not mod\-time & size + \-a, \-\-archive archive mode; equals \-rlptgoD (no \-H,\-A,\-X) + \-\-no\-OPTION turn off an implied OPTION (e.g. \-\-no\-D) + \-r, \-\-recursive recurse into directories + \-R, \-\-relative use relative path names +! \-\-no\-implied\-dirs don'\&t send implied dirs with \-\-relative + \-b, \-\-backup make backups (see \-\-suffix & \-\-backup\-dir) + \-\-backup\-dir=DIR make backups into hierarchy based in DIR + \-\-suffix=SUFFIX backup suffix (default ~ w/o \-\-backup\-dir) + \-u, \-\-update skip files that are newer on the receiver +! \-\-inplace update destination files in\-place + \-\-append append data onto shorter files + \-\-append\-verify \-\-append w/old data in file checksum + \-d, \-\-dirs transfer directories without recursing + \-l, \-\-links copy symlinks as symlinks + \-L, \-\-copy\-links transform symlink into referent file/dir +! \-\-copy\-unsafe\-links only \(dq\&unsafe\(dq\& symlinks are transformed + \-\-safe\-links ignore symlinks that point outside the tree + \-k, \-\-copy\-dirlinks transform symlink to dir into referent dir + \-K, \-\-keep\-dirlinks treat symlinked dir on receiver as dir +*************** +*** 421,445 **** + \-\-chmod=CHMOD affect file and/or directory permissions + \-A, \-\-acls preserve ACLs (implies \-p) + \-X, \-\-xattrs preserve extended attributes +! \-o, \-\-owner preserve owner (super-user only) + \-g, \-\-group preserve group +! \-\-devices preserve device files (super-user only) + \-\-specials preserve special files + \-D same as \-\-devices \-\-specials + \-t, \-\-times preserve modification times + \-O, \-\-omit\-dir\-times omit directories from \-\-times +! \-\-super receiver attempts super-user activities + \-\-fake\-super store/recover privileged attrs using xattrs + \-S, \-\-sparse handle sparse files efficiently + \-n, \-\-dry\-run perform a trial run with no changes made +! \-W, \-\-whole\-file copy files whole (w/o delta-xfer algorithm) +! \-x, \-\-one\-file\-system don't cross filesystem boundaries +! \-B, \-\-block\-size=SIZE force a fixed checksum block-size + \-e, \-\-rsh=COMMAND specify the remote shell to use + \-\-rsync\-path=PROGRAM specify the rsync to run on remote machine + \-\-existing skip creating new files on receiver + \-\-ignore\-existing skip updating files that exist on receiver +! \-\-remove\-source\-files sender removes synchronized files (non-dir) + \-\-del an alias for \-\-delete\-during + \-\-delete delete extraneous files from dest dirs + \-\-delete\-before receiver deletes before transfer (default) +--- 421,445 ---- + \-\-chmod=CHMOD affect file and/or directory permissions + \-A, \-\-acls preserve ACLs (implies \-p) + \-X, \-\-xattrs preserve extended attributes +! \-o, \-\-owner preserve owner (super\-user only) + \-g, \-\-group preserve group +! \-\-devices preserve device files (super\-user only) + \-\-specials preserve special files + \-D same as \-\-devices \-\-specials + \-t, \-\-times preserve modification times + \-O, \-\-omit\-dir\-times omit directories from \-\-times +! \-\-super receiver attempts super\-user activities + \-\-fake\-super store/recover privileged attrs using xattrs + \-S, \-\-sparse handle sparse files efficiently + \-n, \-\-dry\-run perform a trial run with no changes made +! \-W, \-\-whole\-file copy files whole (w/o delta\-xfer algorithm) +! \-x, \-\-one\-file\-system don'\&t cross filesystem boundaries +! \-B, \-\-block\-size=SIZE force a fixed checksum block\-size + \-e, \-\-rsh=COMMAND specify the remote shell to use + \-\-rsync\-path=PROGRAM specify the rsync to run on remote machine + \-\-existing skip creating new files on receiver + \-\-ignore\-existing skip updating files that exist on receiver +! \-\-remove\-source\-files sender removes synchronized files (non\-dir) + \-\-del an alias for \-\-delete\-during + \-\-delete delete extraneous files from dest dirs + \-\-delete\-before receiver deletes before transfer (default) +*************** +*** 449,467 **** + \-\-delete\-excluded also delete excluded files from dest dirs + \-\-ignore\-errors delete even if there are I/O errors + \-\-force force deletion of dirs even if not empty +! \-\-max\-delete=NUM don't delete more than NUM files +! \-\-max\-size=SIZE don't transfer any file larger than SIZE +! \-\-min\-size=SIZE don't transfer any file smaller than SIZE + \-\-partial keep partially transferred files + \-\-partial\-dir=DIR put a partially transferred file into DIR + \-\-delay\-updates put all updated files into place at end +! \-m, \-\-prune\-empty\-dirs prune empty directory chains from file-list +! \-\-numeric\-ids don't map uid/gid values by user/group name + \-\-timeout=SECONDS set I/O timeout in seconds + \-\-contimeout=SECONDS set daemon connection timeout in seconds +! \-I, \-\-ignore\-times don't skip files that match size and time + \-\-size\-only skip files that match in size +! \-\-modify\-window=NUM compare mod-times with reduced accuracy + \-T, \-\-temp\-dir=DIR create temporary files in directory DIR + \-y, \-\-fuzzy find similar file for basis if no dest file + \-\-compare\-dest=DIR also compare received files relative to DIR +--- 449,467 ---- + \-\-delete\-excluded also delete excluded files from dest dirs + \-\-ignore\-errors delete even if there are I/O errors + \-\-force force deletion of dirs even if not empty +! \-\-max\-delete=NUM don'\&t delete more than NUM files +! \-\-max\-size=SIZE don'\&t transfer any file larger than SIZE +! \-\-min\-size=SIZE don'\&t transfer any file smaller than SIZE + \-\-partial keep partially transferred files + \-\-partial\-dir=DIR put a partially transferred file into DIR + \-\-delay\-updates put all updated files into place at end +! \-m, \-\-prune\-empty\-dirs prune empty directory chains from file\-list +! \-\-numeric\-ids don'\&t map uid/gid values by user/group name + \-\-timeout=SECONDS set I/O timeout in seconds + \-\-contimeout=SECONDS set daemon connection timeout in seconds +! \-I, \-\-ignore\-times don'\&t skip files that match size and time + \-\-size\-only skip files that match in size +! \-\-modify\-window=NUM compare mod\-times with reduced accuracy + \-T, \-\-temp\-dir=DIR create temporary files in directory DIR + \-y, \-\-fuzzy find similar file for basis if no dest file + \-\-compare\-dest=DIR also compare received files relative to DIR +*************** +*** 470,500 **** + \-z, \-\-compress compress file data during the transfer + \-\-compress\-level=NUM explicitly set compression level + \-\-skip\-compress=LIST skip compressing files with suffix in LIST +! \-C, \-\-cvs\-exclude auto-ignore files in the same way CVS does +! \-f, \-\-filter=RULE add a file-filtering RULE +! \-F same as \-\-filter='dir-merge /.rsync\-filter' +! repeated: \-\-filter='\- .rsync\-filter' + \-\-exclude=PATTERN exclude files matching PATTERN + \-\-exclude\-from=FILE read exclude patterns from FILE +! \-\-include=PATTERN don't exclude files matching PATTERN + \-\-include\-from=FILE read include patterns from FILE +! \-\-files\-from=FILE read list of source-file names from FILE + \-0, \-\-from0 all *from/filter files are delimited by 0s +! \-s, \-\-protect\-args no space-splitting; wildcard chars only + \-\-address=ADDRESS bind address for outgoing socket to daemon +! \-\-port=PORT specify double-colon alternate port number + \-\-sockopts=OPTIONS specify custom TCP options + \-\-blocking\-io use blocking I/O for the remote shell +! \-\-stats give some file-transfer stats +! \-8, \-\-8\-bit\-output leave high-bit chars unescaped in output +! \-h, \-\-human\-readable output numbers in a human-readable format + \-\-progress show progress during transfer + \-P same as \-\-partial \-\-progress +! \-i, \-\-itemize\-changes output a change-summary for all updates + \-\-out\-format=FORMAT output updates using the specified FORMAT +! \-\-log\-file=FILE log what we're doing to the specified FILE + \-\-log\-file\-format=FMT log updates using the specified FMT +! \-\-password\-file=FILE read daemon-access password from FILE + \-\-list\-only list the files instead of copying them + \-\-bwlimit=KBPS limit I/O bandwidth; KBytes per second + \-\-write\-batch=FILE write a batched update to FILE +--- 470,500 ---- + \-z, \-\-compress compress file data during the transfer + \-\-compress\-level=NUM explicitly set compression level + \-\-skip\-compress=LIST skip compressing files with suffix in LIST +! \-C, \-\-cvs\-exclude auto\-ignore files in the same way CVS does +! \-f, \-\-filter=RULE add a file\-filtering RULE +! \-F same as \-\-filter='\&dir\-merge /.rsync\-filter'\& +! repeated: \-\-filter='\&\- .rsync\-filter'\& + \-\-exclude=PATTERN exclude files matching PATTERN + \-\-exclude\-from=FILE read exclude patterns from FILE +! \-\-include=PATTERN don'\&t exclude files matching PATTERN + \-\-include\-from=FILE read include patterns from FILE +! \-\-files\-from=FILE read list of source\-file names from FILE + \-0, \-\-from0 all *from/filter files are delimited by 0s +! \-s, \-\-protect\-args no space\-splitting; wildcard chars only + \-\-address=ADDRESS bind address for outgoing socket to daemon +! \-\-port=PORT specify double\-colon alternate port number + \-\-sockopts=OPTIONS specify custom TCP options + \-\-blocking\-io use blocking I/O for the remote shell +! \-\-stats give some file\-transfer stats +! \-8, \-\-8\-bit\-output leave high\-bit chars unescaped in output +! \-h, \-\-human\-readable output numbers in a human\-readable format + \-\-progress show progress during transfer + \-P same as \-\-partial \-\-progress +! \-i, \-\-itemize\-changes output a change\-summary for all updates + \-\-out\-format=FORMAT output updates using the specified FORMAT +! \-\-log\-file=FILE log what we'\&re doing to the specified FILE + \-\-log\-file\-format=FMT log updates using the specified FMT +! \-\-password\-file=FILE read daemon\-access password from FILE + \-\-list\-only list the files instead of copying them + \-\-bwlimit=KBPS limit I/O bandwidth; KBytes per second + \-\-write\-batch=FILE write a batched update to FILE +*************** +*** 520,527 **** + \-\-config=FILE specify alternate rsyncd.conf file + \-\-no\-detach do not detach from the parent + \-\-port=PORT listen on alternate port number +! \-\-log\-file=FILE override the "log file" setting +! \-\-log\-file\-format=FMT override the "log format" setting + \-\-sockopts=OPTIONS specify custom TCP options + \-v, \-\-verbose increase verbosity + \-4, \-\-ipv4 prefer IPv4 +--- 520,527 ---- + \-\-config=FILE specify alternate rsyncd.conf file + \-\-no\-detach do not detach from the parent + \-\-port=PORT listen on alternate port number +! \-\-log\-file=FILE override the \(dq\&log file\(dq\& setting +! \-\-log\-file\-format=FMT override the \(dq\&log format\(dq\& setting + \-\-sockopts=OPTIONS specify custom TCP options + \-v, \-\-verbose increase verbosity + \-4, \-\-ipv4 prefer IPv4 +*************** +*** 536,547 **** + rsync uses the GNU long options package. Many of the command line + options have two variants, one short and one long. These are shown + below, separated by commas. Some options only have a long variant. +! The \(oq=\(cq for options that take a parameter is optional; whitespace + can be used instead. + .PP + .IP "\fB\-\-help\fP" + Print a short help page describing the options +! available in rsync and exit. For backward-compatibility with older + versions of rsync, the help will also be output if you use the \fB\-h\fP + option without any other args. + .IP +--- 536,547 ---- + rsync uses the GNU long options package. Many of the command line + options have two variants, one short and one long. These are shown + below, separated by commas. Some options only have a long variant. +! The \(cq\&=\(cq\& for options that take a parameter is optional; whitespace + can be used instead. + .PP + .IP "\fB\-\-help\fP" + Print a short help page describing the options +! available in rsync and exit. For backward\-compatibility with older + versions of rsync, the help will also be output if you use the \fB\-h\fP + option without any other args. + .IP +*************** +*** 558,568 **** + you are debugging rsync. + .IP + Note that the names of the transferred files that are output are done using +! a default \fB\-\-out\-format\fP of \(lq%n%L\(rq, which tells you just the name of the + file and, if the item is a link, where it points. At the single \fB\-v\fP + level of verbosity, this does not mention when a file gets its attributes + changed. If you ask for an itemized list of changed attributes (either +! \fB\-\-itemize\-changes\fP or adding \(lq%i\(rq to the \fB\-\-out\-format\fP setting), the + output (on the client) increases to mention all items that are changed in + any way. See the \fB\-\-out\-format\fP option for more details. + .IP +--- 558,568 ---- + you are debugging rsync. + .IP + Note that the names of the transferred files that are output are done using +! a default \fB\-\-out\-format\fP of \(dq\&%n%L\(dq\&, which tells you just the name of the + file and, if the item is a link, where it points. At the single \fB\-v\fP + level of verbosity, this does not mention when a file gets its attributes + changed. If you ask for an itemized list of changed attributes (either +! \fB\-\-itemize\-changes\fP or adding \(dq\&%i\(dq\& to the \fB\-\-out\-format\fP setting), the + output (on the client) increases to mention all items that are changed in + any way. See the \fB\-\-out\-format\fP option for more details. + .IP +*************** +*** 575,582 **** + .IP "\fB\-\-no\-motd\fP" + This option affects the information that is output + by the client at the start of a daemon transfer. This suppresses the +! message-of-the-day (MOTD) text, but it also affects the list of modules +! that the daemon sends in response to the \(lqrsync host::\(rq request (due to + a limitation in the rsync protocol), so omit this option if you want to + request the list of modules from the daemon. + .IP +--- 575,582 ---- + .IP "\fB\-\-no\-motd\fP" + This option affects the information that is output + by the client at the start of a daemon transfer. This suppresses the +! message\-of\-the\-day (MOTD) text, but it also affects the list of modules +! that the daemon sends in response to the \(dq\&rsync host::\(dq\& request (due to + a limitation in the rsync protocol), so omit this option if you want to + request the list of modules from the daemon. + .IP +*************** +*** 583,595 **** + .IP "\fB\-I, \-\-ignore\-times\fP" + Normally rsync will skip any files that are + already the same size and have the same modification timestamp. +! This option turns off this \(lqquick check\(rq behavior, causing all files to + be updated. + .IP + .IP "\fB\-\-size\-only\fP" +! This modifies rsync's \(lqquick check\(rq algorithm for + finding files that need to be transferred, changing it from the default of +! transferring files with either a changed size or a changed last-modified + time to just looking for files that have changed in size. This is useful + when starting to use rsync after using another mirroring system which may + not preserve timestamps exactly. +--- 583,595 ---- + .IP "\fB\-I, \-\-ignore\-times\fP" + Normally rsync will skip any files that are + already the same size and have the same modification timestamp. +! This option turns off this \(dq\&quick check\(dq\& behavior, causing all files to + be updated. + .IP + .IP "\fB\-\-size\-only\fP" +! This modifies rsync\(cq\&s \(dq\&quick check\(dq\& algorithm for + finding files that need to be transferred, changing it from the default of +! transferring files with either a changed size or a changed last\-modified + time to just looking for files that have changed in size. This is useful + when starting to use rsync after using another mirroring system which may + not preserve timestamps exactly. +*************** +*** 596,630 **** + .IP + .IP "\fB\-\-modify\-window\fP" + When comparing two timestamps, rsync treats the +! timestamps as being equal if they differ by no more than the modify-window + value. This is normally 0 (for an exact match), but you may find it useful + to set this to a larger value in some situations. In particular, when + transferring to or from an MS Windows FAT filesystem (which represents +! times with a 2-second resolution), \fB\-\-modify\-window=1\fP is useful + (allowing times to differ by up to 1 second). + .IP + .IP "\fB\-c, \-\-checksum\fP" + This changes the way rsync checks if the files have + been changed and are in need of a transfer. Without this option, rsync +! uses a \(lqquick check\(rq that (by default) checks if each file's size and time + of last modification match between the sender and receiver. This option +! changes this to compare a 128-bit checksum for each file that has a + matching size. Generating the checksums means that both sides will expend + a lot of disk I/O reading all the data in the files in the transfer (and + this is prior to any reading that will be done to transfer changed files), + so this can slow things down significantly. + .IP +! The sending side generates its checksums while it is doing the file-system + scan that builds the list of the available files. The receiver generates + its checksums when it is scanning for changed files, and will checksum any +! file that has the same size as the corresponding sender's file: files with + either a changed size or a changed checksum are selected for transfer. + .IP + Note that rsync always verifies that each \fItransferred\fP file was +! correctly reconstructed on the receiving side by checking a whole-file + checksum that is generated as the file is transferred, but that +! automatic after-the-transfer verification has nothing to do with this +! option's before-the-transfer \(lqDoes this file need to be updated?\(rq check. + .IP + For protocol 30 and beyond (first supported in 3.0.0), the checksum used is + MD5. For older protocols, the checksum used is MD4. +--- 596,630 ---- + .IP + .IP "\fB\-\-modify\-window\fP" + When comparing two timestamps, rsync treats the +! timestamps as being equal if they differ by no more than the modify\-window + value. This is normally 0 (for an exact match), but you may find it useful + to set this to a larger value in some situations. In particular, when + transferring to or from an MS Windows FAT filesystem (which represents +! times with a 2\-second resolution), \fB\-\-modify\-window=1\fP is useful + (allowing times to differ by up to 1 second). + .IP + .IP "\fB\-c, \-\-checksum\fP" + This changes the way rsync checks if the files have + been changed and are in need of a transfer. Without this option, rsync +! uses a \(dq\&quick check\(dq\& that (by default) checks if each file\(cq\&s size and time + of last modification match between the sender and receiver. This option +! changes this to compare a 128\-bit checksum for each file that has a + matching size. Generating the checksums means that both sides will expend + a lot of disk I/O reading all the data in the files in the transfer (and + this is prior to any reading that will be done to transfer changed files), + so this can slow things down significantly. + .IP +! The sending side generates its checksums while it is doing the file\-system + scan that builds the list of the available files. The receiver generates + its checksums when it is scanning for changed files, and will checksum any +! file that has the same size as the corresponding sender\(cq\&s file: files with + either a changed size or a changed checksum are selected for transfer. + .IP + Note that rsync always verifies that each \fItransferred\fP file was +! correctly reconstructed on the receiving side by checking a whole\-file + checksum that is generated as the file is transferred, but that +! automatic after\-the\-transfer verification has nothing to do with this +! option\(cq\&s before\-the\-transfer \(dq\&Does this file need to be updated?\(dq\& check. + .IP + For protocol 30 and beyond (first supported in 3.0.0), the checksum used is + MD5. For older protocols, the checksum used is MD4. +*************** +*** 637,661 **** + specified, in which case \fB\-r\fP is not implied. + .IP + Note that \fB\-a\fP \fBdoes not preserve hardlinks\fP, because +! finding multiply-linked files is expensive. You must separately + specify \fB\-H\fP. + .IP + .IP "\-\-no\-OPTION" + You may turn off one or more implied options by prefixing +! the option name with \(lqno\-\(rq. Not all options may be prefixed with a \(lqno\-\(rq: + only options that are implied by other options (e.g. \fB\-\-no\-D\fP, + \fB\-\-no\-perms\fP) or have different defaults in various circumstances + (e.g. \fB\-\-no\-whole\-file\fP, \fB\-\-no\-blocking\-io\fP, \fB\-\-no\-dirs\fP). You may +! specify either the short or the long option name after the \(lqno\-\(rq prefix + (e.g. \fB\-\-no\-R\fP is the same as \fB\-\-no\-relative\fP). + .IP +! For example: if you want to use \fB\-a\fP (\fB\-\-archive\fP) but don't want + \fB\-o\fP (\fB\-\-owner\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you + could specify \fB\-a \-\-no\-o\fP (or \fB\-a \-\-no\-owner\fP). + .IP + The order of the options is important: if you specify \fB\-\-no\-r \-a\fP, the + \fB\-r\fP option would end up being turned on, the opposite of \fB\-a \-\-no\-r\fP. +! Note also that the side-effects of the \fB\-\-files\-from\fP option are NOT + positional, as it affects the default state of several options and slightly + changes the meaning of \fB\-a\fP (see the \fB\-\-files\-from\fP option for more + details). +--- 637,661 ---- + specified, in which case \fB\-r\fP is not implied. + .IP + Note that \fB\-a\fP \fBdoes not preserve hardlinks\fP, because +! finding multiply\-linked files is expensive. You must separately + specify \fB\-H\fP. + .IP + .IP "\-\-no\-OPTION" + You may turn off one or more implied options by prefixing +! the option name with \(dq\&no\-\(dq\&. Not all options may be prefixed with a \(dq\&no\-\(dq\&: + only options that are implied by other options (e.g. \fB\-\-no\-D\fP, + \fB\-\-no\-perms\fP) or have different defaults in various circumstances + (e.g. \fB\-\-no\-whole\-file\fP, \fB\-\-no\-blocking\-io\fP, \fB\-\-no\-dirs\fP). You may +! specify either the short or the long option name after the \(dq\&no\-\(dq\& prefix + (e.g. \fB\-\-no\-R\fP is the same as \fB\-\-no\-relative\fP). + .IP +! For example: if you want to use \fB\-a\fP (\fB\-\-archive\fP) but don\(cq\&t want + \fB\-o\fP (\fB\-\-owner\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you + could specify \fB\-a \-\-no\-o\fP (or \fB\-a \-\-no\-owner\fP). + .IP + The order of the options is important: if you specify \fB\-\-no\-r \-a\fP, the + \fB\-r\fP option would end up being turned on, the opposite of \fB\-a \-\-no\-r\fP. +! Note also that the side\-effects of the \fB\-\-files\-from\fP option are NOT + positional, as it affects the default state of several options and slightly + changes the meaning of \fB\-a\fP (see the \fB\-\-files\-from\fP option for more + details). +*************** +*** 668,674 **** + incremental scan that uses much less memory than before and begins the + transfer after the scanning of the first few directories have been + completed. This incremental scan only affects our recursion algorithm, and +! does not change a non-recursive transfer. It is also only possible when + both ends of the transfer are at least version 3.0.0. + .IP + Some options require rsync to know the full file list, so these options +--- 668,674 ---- + incremental scan that uses much less memory than before and begins the + transfer after the scanning of the first few directories have been + completed. This incremental scan only affects our recursion algorithm, and +! does not change a non\-recursive transfer. It is also only possible when + both ends of the transfer are at least version 3.0.0. + .IP + Some options require rsync to know the full file list, so these options +*************** +*** 705,720 **** + .IP + then a file named /tmp/foo/bar/baz.c would be created on the remote + machine, preserving its full path. These extra path elements are called +! \(lqimplied directories\(rq (i.e. the \(lqfoo\(rq and the \(lqfoo/bar\(rq directories in the + above example). + .IP + Beginning with rsync 3.0.0, rsync always sends these implied directories as + real directories in the file list, even if a path element is really a + symlink on the sending side. This prevents some really unexpected +! behaviors when copying the full path of a file that you didn't realize had +! a symlink in its path. If you want to duplicate a server-side symlink, + include both the symlink via its path, and referent directory via its real +! path. If you're dealing with an older rsync on the sending side, you may + need to use the \fB\-\-no\-implied\-dirs\fP option. + .IP + It is also possible to limit the amount of path information that is sent as +--- 705,720 ---- + .IP + then a file named /tmp/foo/bar/baz.c would be created on the remote + machine, preserving its full path. These extra path elements are called +! \(dq\&implied directories\(dq\& (i.e. the \(dq\&foo\(dq\& and the \(dq\&foo/bar\(dq\& directories in the + above example). + .IP + Beginning with rsync 3.0.0, rsync always sends these implied directories as + real directories in the file list, even if a path element is really a + symlink on the sending side. This prevents some really unexpected +! behaviors when copying the full path of a file that you didn\(cq\&t realize had +! a symlink in its path. If you want to duplicate a server\-side symlink, + include both the symlink via its path, and referent directory via its real +! path. If you\(cq\&re dealing with an older rsync on the sending side, you may + need to use the \fB\-\-no\-implied\-dirs\fP option. + .IP + It is also possible to limit the amount of path information that is sent as +*************** +*** 728,735 **** + + .IP + That would create /tmp/bar/baz.c on the remote machine. (Note that the +! dot must be followed by a slash, so \(lq/foo/.\(rq would not be abbreviated.) +! (2) For older rsync versions, you would need to use a chdir to limit the + source path. For example, when pushing files: + .IP + .RS +--- 728,735 ---- + + .IP + That would create /tmp/bar/baz.c on the remote machine. (Note that the +! dot must be followed by a slash, so \(dq\&/foo/.\(dq\& would not be abbreviated.) +! For older rsync versions, you would need to use a chdir to limit the + source path. For example, when pushing files: + .IP + .RS +*************** +*** 737,749 **** + .RE + + .IP +! (Note that the parens put the two commands into a sub-shell, so that the +! \(lqcd\(rq command doesn't remain in effect for future commands.) +! If you're pulling files from an older rsync, use this idiom (but only +! for a non-daemon transfer): + .IP + .RS +! \f(CW rsync \-avR \-\-rsync\-path="cd /foo; rsync" \e \fP + .br + \f(CW remote:bar/baz.c /tmp/\fP + .RE +--- 737,749 ---- + .RE + + .IP +! (Note that the parens put the two commands into a sub\-shell, so that the +! \(dq\&cd\(dq\& command doesn\(cq\&t remain in effect for future commands.) +! If you\(cq\&re pulling files from an older rsync, use this idiom (but only +! for a non\-daemon transfer): + .IP + .RS +! \f(CW rsync \-avR \-\-rsync\-path=\(dq\&cd /foo; rsync\(dq\& \e \fP + .br + \f(CW remote:bar/baz.c /tmp/\fP + .RE +*************** +*** 759,772 **** + elements to have big differences, such as being a symlink to a directory on + the receiving side. + .IP +! For instance, if a command-line arg or a files-from entry told rsync to +! transfer the file \(lqpath/foo/file\(rq, the directories \(lqpath\(rq and \(lqpath/foo\(rq +! are implied when \fB\-\-relative\fP is used. If \(lqpath/foo\(rq is a symlink to +! \(lqbar\(rq on the destination system, the receiving rsync would ordinarily +! delete \(lqpath/foo\(rq, recreate it as a directory, and receive the file into + the new directory. With \fB\-\-no\-implied\-dirs\fP, the receiving rsync updates +! \(lqpath/foo/file\(rq using the existing path elements, which means that the file +! ends up being created in \(lqpath/bar\(rq. Another way to accomplish this link + preservation is to use the \fB\-\-keep\-dirlinks\fP option (which will also + affect symlinks to directories in the rest of the transfer). + .IP +--- 759,772 ---- + elements to have big differences, such as being a symlink to a directory on + the receiving side. + .IP +! For instance, if a command\-line arg or a files\-from entry told rsync to +! transfer the file \(dq\&path/foo/file\(dq\&, the directories \(dq\&path\(dq\& and \(dq\&path/foo\(dq\& +! are implied when \fB\-\-relative\fP is used. If \(dq\&path/foo\(dq\& is a symlink to +! \(dq\&bar\(dq\& on the destination system, the receiving rsync would ordinarily +! delete \(dq\&path/foo\(dq\&, recreate it as a directory, and receive the file into + the new directory. With \fB\-\-no\-implied\-dirs\fP, the receiving rsync updates +! \(dq\&path/foo/file\(dq\& using the existing path elements, which means that the file +! ends up being created in \(dq\&path/bar\(dq\&. Another way to accomplish this link + preservation is to use the \fB\-\-keep\-dirlinks\fP option (which will also + affect symlinks to directories in the rest of the transfer). + .IP +*************** +*** 780,794 **** + backup file goes and what (if any) suffix gets appended using the + \fB\-\-backup\-dir\fP and \fB\-\-suffix\fP options. + .IP +! Note that if you don't specify \fB\-\-backup\-dir\fP, (1) the + \fB\-\-omit\-dir\-times\fP option will be implied, and (2) if \fB\-\-delete\fP is +! also in effect (without \fB\-\-delete\-excluded\fP), rsync will add a \(lqprotect\(rq +! filter-rule for the backup suffix to the end of all your existing excludes +! (e.g. \fB\-f "P *~"\fP). This will prevent previously backed-up files from being + deleted. Note that if you are supplying your own filter rules, you may + need to manually insert your own exclude/protect rule somewhere higher up + in the list so that it has a high enough priority to be effective (e.g., if +! your rules specify a trailing inclusion/exclusion of \(oq*\(cq, the auto-added + rule would never be reached). + .IP + .IP "\fB\-\-backup\-dir=DIR\fP" +--- 780,794 ---- + backup file goes and what (if any) suffix gets appended using the + \fB\-\-backup\-dir\fP and \fB\-\-suffix\fP options. + .IP +! Note that if you don\(cq\&t specify \fB\-\-backup\-dir\fP, (1) the + \fB\-\-omit\-dir\-times\fP option will be implied, and (2) if \fB\-\-delete\fP is +! also in effect (without \fB\-\-delete\-excluded\fP), rsync will add a \(dq\&protect\(dq\& +! filter\-rule for the backup suffix to the end of all your existing excludes +! (e.g. \fB\-f \(dq\&P *~\(dq\&\fP). This will prevent previously backed\-up files from being + deleted. Note that if you are supplying your own filter rules, you may + need to manually insert your own exclude/protect rule somewhere higher up + in the list so that it has a high enough priority to be effective (e.g., if +! your rules specify a trailing inclusion/exclusion of \(cq\&*\(cq\&, the auto\-added + rule would never be reached). + .IP + .IP "\fB\-\-backup\-dir=DIR\fP" +*************** +*** 799,814 **** + (otherwise the files backed up in the specified directory + will keep their original filenames). + .IP + .IP "\fB\-\-suffix=SUFFIX\fP" + This option allows you to override the default + backup suffix used with the \fB\-\-backup\fP (\fB\-b\fP) option. The default suffix is a ~ +! if no \-\fB\-backup-dir\fP was specified, otherwise it is an empty string. + .IP + .IP "\fB\-u, \-\-update\fP" + This forces rsync to skip any files which exist on + the destination and have a modified time that is newer than the source + file. (If an existing destination file has a modification time equal to the +! source file's, it will be updated if the sizes are different.) + .IP + Note that this does not affect the copying of symlinks or other special + files. Also, a difference of file format between the sender and receiver +--- 799,820 ---- + (otherwise the files backed up in the specified directory + will keep their original filenames). + .IP ++ Note that if you specify a relative path, the backup directory will be ++ relative to the destination directory, so you probably want to specify ++ either an absolute path or a path that starts with \(dq\&../\(dq\&. If an rsync ++ daemon is the receiver, the backup dir cannot go outside the module\(cq\&s path ++ hierarchy, so take extra care not to delete it or copy into it. ++ .IP + .IP "\fB\-\-suffix=SUFFIX\fP" + This option allows you to override the default + backup suffix used with the \fB\-\-backup\fP (\fB\-b\fP) option. The default suffix is a ~ +! if no \-\fB\-backup\-dir\fP was specified, otherwise it is an empty string. + .IP + .IP "\fB\-u, \-\-update\fP" + This forces rsync to skip any files which exist on + the destination and have a modified time that is newer than the source + file. (If an existing destination file has a modification time equal to the +! source file\(cq\&s, it will be updated if the sizes are different.) + .IP + Note that this does not affect the copying of symlinks or other special + files. Also, a difference of file format between the sender and receiver +*************** +*** 817,850 **** + where the destination has a file, the transfer would occur regardless of + the timestamps. + .IP +! This option is a transfer rule, not an exclude, so it doesn't affect the +! data that goes into the file-lists, and thus it doesn't affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP + .IP "\fB\-\-inplace\fP" +! This option changes how rsync transfers a file when the +! file's data needs to be updated: instead of the default method of creating + a new copy of the file and moving it into place when it is complete, rsync + instead writes the updated data directly to the destination file. + .IP +! This has several effects: (1) in-use binaries cannot be updated (either the +! OS will prevent this from happening, or binaries that attempt to swap-in +! their data will misbehave or crash), (2) the file's data will be in an +! inconsistent state during the transfer, (3) a file's data may be left in an +! inconsistent state after the transfer if the transfer is interrupted or if +! an update fails, (4) a file that does not have write permissions can not be +! updated, and (5) the efficiency of rsync's delta-transfer algorithm may be +! reduced if some data in the destination file is overwritten before it can +! be copied to a position later in the file (one exception to this is if you +! combine this option with \fB\-\-backup\fP, since rsync is smart enough to use +! the backup file as the basis file for the transfer). + .IP + WARNING: you should not use this option to update files that are being + accessed by others, so be careful when choosing to use this for a copy. + .IP +! This option is useful for transfer of large files with block-based changes + or appended data, and also on systems that are disk bound, not network +! bound. + .IP + The option implies \fB\-\-partial\fP (since an interrupted transfer does not delete + the file), but conflicts with \fB\-\-partial\-dir\fP and \fB\-\-delay\-updates\fP. +--- 823,874 ---- + where the destination has a file, the transfer would occur regardless of + the timestamps. + .IP +! This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the +! data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP + .IP "\fB\-\-inplace\fP" +! This option changes how rsync transfers a file when +! its data needs to be updated: instead of the default method of creating + a new copy of the file and moving it into place when it is complete, rsync + instead writes the updated data directly to the destination file. + .IP +! This has several effects: + .IP ++ .RS ++ .IP o ++ Hard links are not broken. This means the new data will be visible ++ through other hard links to the destination file. Moreover, attempts to ++ copy differing source files onto a multiply\-linked destination file will ++ result in a \(dq\&tug of war\(dq\& with the destination data changing back and forth. ++ .IP o ++ In\-use binaries cannot be updated (either the OS will prevent this from ++ happening, or binaries that attempt to swap\-in their data will misbehave or ++ crash). ++ .IP o ++ The file\(cq\&s data will be in an inconsistent state during the transfer ++ and will be left that way if the transfer is interrupted or if an update ++ fails. ++ .IP o ++ A file that rsync cannot write to cannot be updated. While a super user ++ can update any file, a normal user needs to be granted write permission for ++ the open of the file for writing to be successful. ++ .IP o ++ The efficiency of rsync\(cq\&s delta\-transfer algorithm may be reduced if ++ some data in the destination file is overwritten before it can be copied to ++ a position later in the file. This does not apply if you use \fB\-\-backup\fP, ++ since rsync is smart enough to use the backup file as the basis file for the ++ transfer. ++ .RE ++ ++ .IP + WARNING: you should not use this option to update files that are being + accessed by others, so be careful when choosing to use this for a copy. + .IP +! This option is useful for transferring large files with block\-based changes + or appended data, and also on systems that are disk bound, not network +! bound. It can also help keep a copy\-on\-write filesystem snapshot from +! diverging the entire contents of a file that only has minor changes. + .IP + The option implies \fB\-\-partial\fP (since an interrupted transfer does not delete + the file), but conflicts with \fB\-\-partial\-dir\fP and \fB\-\-delay\-updates\fP. +*************** +*** 857,874 **** + the receiving side is identical with the start of the file on the sending + side. If a file needs to be transferred and its size on the receiver is + the same or longer than the size on the sender, the file is skipped. This +! does not interfere with the updating of a file's non-content attributes + (e.g. permissions, ownership, etc.) when the file does not need to be +! transferred, nor does it affect the updating of any non-regular files. + Implies \fB\-\-inplace\fP, + but does not conflict with \fB\-\-sparse\fP (since it is always extending a +! file's length). + .IP + .IP "\fB\-\-append\-verify\fP" + This works just like the \fB\-\-append\fP option, but +! the existing data on the receiving side is included in the full-file + checksum verification step, which will cause a file to be resent if the +! final verification step fails (rsync uses a normal, non-appending + \fB\-\-inplace\fP transfer for the resend). + .IP + Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like +--- 881,898 ---- + the receiving side is identical with the start of the file on the sending + side. If a file needs to be transferred and its size on the receiver is + the same or longer than the size on the sender, the file is skipped. This +! does not interfere with the updating of a file\(cq\&s non\-content attributes + (e.g. permissions, ownership, etc.) when the file does not need to be +! transferred, nor does it affect the updating of any non\-regular files. + Implies \fB\-\-inplace\fP, + but does not conflict with \fB\-\-sparse\fP (since it is always extending a +! file\(cq\&s length). + .IP + .IP "\fB\-\-append\-verify\fP" + This works just like the \fB\-\-append\fP option, but +! the existing data on the receiving side is included in the full\-file + checksum verification step, which will cause a file to be resent if the +! final verification step fails (rsync uses a normal, non\-appending + \fB\-\-inplace\fP transfer for the resend). + .IP + Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like +*************** +*** 878,886 **** + .IP + .IP "\fB\-d, \-\-dirs\fP" + Tell the sending side to include any directories that +! are encountered. Unlike \fB\-\-recursive\fP, a directory's contents are not copied +! unless the directory name specified is \(lq.\(rq or ends with a trailing slash +! (e.g. \(lq.\(rq, \(lqdir/.\(rq, \(lqdir/\(rq, etc.). Without this option or the + \fB\-\-recursive\fP option, rsync will skip all directories it encounters (and + output a message to that effect for each one). If you specify both + \fB\-\-dirs\fP and \fB\-\-recursive\fP, \fB\-\-recursive\fP takes precedence. +--- 902,910 ---- + .IP + .IP "\fB\-d, \-\-dirs\fP" + Tell the sending side to include any directories that +! are encountered. Unlike \fB\-\-recursive\fP, a directory\(cq\&s contents are not copied +! unless the directory name specified is \(dq\&.\(dq\& or ends with a trailing slash +! (e.g. \(dq\&.\(dq\&, \(dq\&dir/.\(dq\&, \(dq\&dir/\(dq\&, etc.). Without this option or the + \fB\-\-recursive\fP option, rsync will skip all directories it encounters (and + output a message to that effect for each one). If you specify both + \fB\-\-dirs\fP and \fB\-\-recursive\fP, \fB\-\-recursive\fP takes precedence. +*************** +*** 887,898 **** + .IP + The \fB\-\-dirs\fP option is implied by the \fB\-\-files\-from\fP option + or the \fB\-\-list\-only\fP option (including an implied +! \fB\-\-list\-only\fP usage) if \fB\-\-recursive\fP wasn't specified (so that + directories are seen in the listing). Specify \fB\-\-no\-dirs\fP (or \fB\-\-no\-d\fP) + if you want to turn this off. + .IP +! There is also a backward-compatibility helper option, \fB\-\-old\-dirs\fP (or +! \fB\-\-old\-d\fP) that tells rsync to use a hack of \(lq\-r \-\-exclude='/*/*'\(rq to get + an older rsync to list a single directory without recursing. + .IP + .IP "\fB\-l, \-\-links\fP" +--- 911,922 ---- + .IP + The \fB\-\-dirs\fP option is implied by the \fB\-\-files\-from\fP option + or the \fB\-\-list\-only\fP option (including an implied +! \fB\-\-list\-only\fP usage) if \fB\-\-recursive\fP wasn\(cq\&t specified (so that + directories are seen in the listing). Specify \fB\-\-no\-dirs\fP (or \fB\-\-no\-d\fP) + if you want to turn this off. + .IP +! There is also a backward\-compatibility helper option, \fB\-\-old\-dirs\fP (or +! \fB\-\-old\-d\fP) that tells rsync to use a hack of \(dq\&\-r \-\-exclude=\(cq\&/*/*\(cq\&\(dq\& to get + an older rsync to list a single directory without recursing. + .IP + .IP "\fB\-l, \-\-links\fP" +*************** +*** 902,913 **** + .IP "\fB\-L, \-\-copy\-links\fP" + When symlinks are encountered, the item that + they point to (the referent) is copied, rather than the symlink. In older +! versions of rsync, this option also had the side-effect of telling the + receiving side to follow symlinks, such as symlinks to directories. In a +! modern rsync such as this one, you'll need to specify \fB\-\-keep\-dirlinks\fP (\fB\-K\fP) + to get this extra behavior. The only exception is when sending files to +! an rsync that is too old to understand \fB\-K\fP \(em in that case, the \fB\-L\fP option +! will still have the side-effect of \fB\-K\fP on that older receiving rsync. + .IP + .IP "\fB\-\-copy\-unsafe\-links\fP" + This tells rsync to copy the referent of +--- 926,937 ---- + .IP "\fB\-L, \-\-copy\-links\fP" + When symlinks are encountered, the item that + they point to (the referent) is copied, rather than the symlink. In older +! versions of rsync, this option also had the side\-effect of telling the + receiving side to follow symlinks, such as symlinks to directories. In a +! modern rsync such as this one, you\(cq\&ll need to specify \fB\-\-keep\-dirlinks\fP (\fB\-K\fP) + to get this extra behavior. The only exception is when sending files to +! an rsync that is too old to understand \fB\-K\fP \-\- in that case, the \fB\-L\fP option +! will still have the side\-effect of \fB\-K\fP on that older receiving rsync. + .IP + .IP "\fB\-\-copy\-unsafe\-links\fP" + This tells rsync to copy the referent of +*************** +*** 925,931 **** + .IP "\fB\-k, \-\-copy\-dirlinks\fP" + This option causes the sending side to treat + a symlink to a directory as though it were a real directory. This is +! useful if you don't want symlinks to non-directories to be affected, as + they would be using \fB\-\-copy\-links\fP. + .IP + Without this option, if the sending side has replaced a directory with a +--- 949,955 ---- + .IP "\fB\-k, \-\-copy\-dirlinks\fP" + This option causes the sending side to treat + a symlink to a directory as though it were a real directory. This is +! useful if you don\(cq\&t want symlinks to non\-directories to be affected, as + they would be using \fB\-\-copy\-links\fP. + .IP + Without this option, if the sending side has replaced a directory with a +*************** +*** 936,953 **** + See also \fB\-\-keep\-dirlinks\fP for an analogous option for the receiving + side. + .IP + .IP "\fB\-K, \-\-keep\-dirlinks\fP" + This option causes the receiving side to treat + a symlink to a directory as though it were a real directory, but only if it + matches a real directory from the sender. Without this option, the +! receiver's symlink would be deleted and replaced with a real directory. + .IP +! For example, suppose you transfer a directory \(lqfoo\(rq that contains a file +! \(lqfile\(rq, but \(lqfoo\(rq is a symlink to directory \(lqbar\(rq on the receiver. Without +! \fB\-\-keep\-dirlinks\fP, the receiver deletes symlink \(lqfoo\(rq, recreates it as a + directory, and receives the file into the new directory. With +! \fB\-\-keep\-dirlinks\fP, the receiver keeps the symlink and \(lqfile\(rq ends up in +! \(lqbar\(rq. + .IP + One note of caution: if you use \fB\-\-keep\-dirlinks\fP, you must trust all + the symlinks in the copy! If it is possible for an untrusted user to +--- 960,991 ---- + See also \fB\-\-keep\-dirlinks\fP for an analogous option for the receiving + side. + .IP ++ \fB\-\-copy\-dirlinks\fP applies to all symlinks to directories in the source. If ++ you want to follow only a few specified symlinks, a trick you can use is to ++ pass them as additional source args with a trailing slash, using \fB\-\-relative\fP ++ to make the paths match up right. For example: ++ .IP ++ .RS ++ \f(CWrsync \-r \-\-relative src/./ src/./follow\-me/ dest/\fP ++ .RE ++ ++ .IP ++ This works because rsync calls \fBlstat\fP(2) on the source arg as given, and the ++ trailing slash makes \fBlstat\fP(2) follow the symlink, giving rise to a directory ++ in the file\-list which overrides the symlink found during the scan of \(dq\&src/./\(dq\&. ++ .IP + .IP "\fB\-K, \-\-keep\-dirlinks\fP" + This option causes the receiving side to treat + a symlink to a directory as though it were a real directory, but only if it + matches a real directory from the sender. Without this option, the +! receiver\(cq\&s symlink would be deleted and replaced with a real directory. + .IP +! For example, suppose you transfer a directory \(dq\&foo\(dq\& that contains a file +! \(dq\&file\(dq\&, but \(dq\&foo\(dq\& is a symlink to directory \(dq\&bar\(dq\& on the receiver. Without +! \fB\-\-keep\-dirlinks\fP, the receiver deletes symlink \(dq\&foo\(dq\&, recreates it as a + directory, and receives the file into the new directory. With +! \fB\-\-keep\-dirlinks\fP, the receiver keeps the symlink and \(dq\&file\(dq\& ends up in +! \(dq\&bar\(dq\&. + .IP + One note of caution: if you use \fB\-\-keep\-dirlinks\fP, you must trust all + the symlinks in the copy! If it is possible for an untrusted user to +*************** +*** 960,980 **** + See also \fB\-\-copy\-dirlinks\fP for an analogous option for the sending side. + .IP + .IP "\fB\-H, \-\-hard\-links\fP" +! This tells rsync to look for hard-linked files in +! the transfer and link together the corresponding files on the receiving +! side. Without this option, hard-linked files in the transfer are treated + as though they were separate files. + .IP +! When you are updating a non-empty destination, this option only ensures +! that files that are hard-linked together on the source are hard-linked +! together on the destination. It does NOT currently endeavor to break +! already existing hard links on the destination that do not exist between +! the source files. Note, however, that if one or more extra-linked files +! have content changes, they will become unlinked when updated (assuming you +! are not using the \fB\-\-inplace\fP option). + .IP + Note that rsync can only detect hard links between files that are inside +! the transfer set. If rsync updates a file that has extra hard-link + connections to files outside the transfer, that linkage will be broken. If + you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be + very careful that you know how your files are being updated so that you are +--- 998,1029 ---- + See also \fB\-\-copy\-dirlinks\fP for an analogous option for the sending side. + .IP + .IP "\fB\-H, \-\-hard\-links\fP" +! This tells rsync to look for hard\-linked files in +! the source and link together the corresponding files on the destination. +! Without this option, hard\-linked files in the source are treated + as though they were separate files. + .IP +! This option does NOT necessarily ensure that the pattern of hard links on the +! destination exactly matches that on the source. Cases in which the +! destination may end up with extra hard links include the following: + .IP ++ .RS ++ .IP o ++ If the destination contains extraneous hard\-links (more linking than ++ what is present in the source file list), the copying algorithm will not ++ break them explicitly. However, if one or more of the paths have content ++ differences, the normal file\-update process will break those extra links ++ (unless you are using the \fB\-\-inplace\fP option). ++ .IP o ++ If you specify a \fB\-\-link\-dest\fP directory that contains hard links, ++ the linking of the destination files against the \fB\-\-link\-dest\fP files can ++ cause some paths in the destination to become linked together due to the ++ \fB\-\-link\-dest\fP associations. ++ .RE ++ ++ .IP + Note that rsync can only detect hard links between files that are inside +! the transfer set. If rsync updates a file that has extra hard\-link + connections to files outside the transfer, that linkage will be broken. If + you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be + very careful that you know how your files are being updated so that you are +*************** +*** 982,990 **** + see the \fB\-\-inplace\fP option for more caveats). + .IP + If incremental recursion is active (see \fB\-\-recursive\fP), rsync may transfer +! a missing hard-linked file before it finds that another link for that contents + exists elsewhere in the hierarchy. This does not affect the accuracy of +! the transfer, just its efficiency. One way to avoid this is to disable + incremental recursion using the \fB\-\-no\-inc\-recursive\fP option. + .IP + .IP "\fB\-p, \-\-perms\fP" +--- 1031,1042 ---- + see the \fB\-\-inplace\fP option for more caveats). + .IP + If incremental recursion is active (see \fB\-\-recursive\fP), rsync may transfer +! a missing hard\-linked file before it finds that another link for that contents + exists elsewhere in the hierarchy. This does not affect the accuracy of +! the transfer (i.e. which files are hard\-linked together), just its efficiency +! (i.e. copying the data for a new, early copy of a hard\-linked file that could +! have been found later in the transfer in another member of the hard\-linked +! set of files). One way to avoid this inefficiency is to disable + incremental recursion using the \fB\-\-no\-inc\-recursive\fP option. + .IP + .IP "\fB\-p, \-\-perms\fP" +*************** +*** 1001,1010 **** + permissions, though the \fB\-\-executability\fP option might change just + the execute permission for the file. + .IP o +! New files get their \(lqnormal\(rq permission bits set to the source +! file's permissions masked with the receiving directory's default +! permissions (either the receiving process's umask, or the permissions +! specified via the destination directory's default ACL), and + their special permission bits disabled except in the case where a new + directory inherits a setgid bit from its parent directory. + .RE +--- 1053,1062 ---- + permissions, though the \fB\-\-executability\fP option might change just + the execute permission for the file. + .IP o +! New files get their \(dq\&normal\(dq\& permission bits set to the source +! file\(cq\&s permissions masked with the receiving directory\(cq\&s default +! permissions (either the receiving process\(cq\&s umask, or the permissions +! specified via the destination directory\(cq\&s default ACL), and + their special permission bits disabled except in the case where a new + directory inherits a setgid bit from its parent directory. + .RE +*************** +*** 1011,1024 **** + + .IP + Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled, +! rsync's behavior is the same as that of other file-copy utilities, + such as \fBcp\fP(1) and \fBtar\fP(1). + .IP + In summary: to give destination files (both old and new) the source +! permissions, use \fB\-\-perms\fP. To give new files the destination-default + permissions (while leaving existing files unchanged), make sure that the + \fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures that +! all non-masked bits get enabled). If you'd care to make this latter + behavior easier to type, you could define a popt alias for it, such as + putting this line in the file ~/.popt (the following defines the \fB\-Z\fP option, + and includes \-\-no\-g to use the default group of the destination dir): +--- 1063,1076 ---- + + .IP + Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled, +! rsync\(cq\&s behavior is the same as that of other file\-copy utilities, + such as \fBcp\fP(1) and \fBtar\fP(1). + .IP + In summary: to give destination files (both old and new) the source +! permissions, use \fB\-\-perms\fP. To give new files the destination\-default + permissions (while leaving existing files unchanged), make sure that the + \fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures that +! all non\-masked bits get enabled). If you\(cq\&d care to make this latter + behavior easier to type, you could define a popt alias for it, such as + putting this line in the file ~/.popt (the following defines the \fB\-Z\fP option, + and includes \-\-no\-g to use the default group of the destination dir): +*************** +*** 1035,1068 **** + .RE + + .IP +! (Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re-enable +! the two \(lq\-\-no\-*\(rq options mentioned above.) + .IP +! The preservation of the destination's setgid bit on newly-created + directories when \fB\-\-perms\fP is off was added in rsync 2.6.7. Older rsync + versions erroneously preserved the three special permission bits for +! newly-created files when \fB\-\-perms\fP was off, while overriding the +! destination's setgid bit setting on a newly-created directory. Default ACL + observance was added to the ACL patch for rsync 2.6.7, so older (or +! non-ACL-enabled) rsyncs use the umask even if default ACLs are present. + (Keep in mind that it is the version of the receiving rsync that affects + these behaviors.) + .IP + .IP "\fB\-E, \-\-executability\fP" + This option causes rsync to preserve the +! executability (or non-executability) of regular files when \fB\-\-perms\fP is + not enabled. A regular file is considered to be executable if at least one +! \(oqx\(cq is turned on in its permissions. When an existing destination file's + executability differs from that of the corresponding source file, rsync +! modifies the destination file's permissions as follows: + .IP + .RS + .IP o +! To make a file non-executable, rsync turns off all its \(oqx\(cq + permissions. + .IP o +! To make a file executable, rsync turns on each \(oqx\(cq permission that +! has a corresponding \(oqr\(cq permission enabled. + .RE + + .IP +--- 1087,1120 ---- + .RE + + .IP +! (Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re\-enable +! the two \(dq\&\-\-no\-*\(dq\& options mentioned above.) + .IP +! The preservation of the destination\(cq\&s setgid bit on newly\-created + directories when \fB\-\-perms\fP is off was added in rsync 2.6.7. Older rsync + versions erroneously preserved the three special permission bits for +! newly\-created files when \fB\-\-perms\fP was off, while overriding the +! destination\(cq\&s setgid bit setting on a newly\-created directory. Default ACL + observance was added to the ACL patch for rsync 2.6.7, so older (or +! non\-ACL\-enabled) rsyncs use the umask even if default ACLs are present. + (Keep in mind that it is the version of the receiving rsync that affects + these behaviors.) + .IP + .IP "\fB\-E, \-\-executability\fP" + This option causes rsync to preserve the +! executability (or non\-executability) of regular files when \fB\-\-perms\fP is + not enabled. A regular file is considered to be executable if at least one +! \(cq\&x\(cq\& is turned on in its permissions. When an existing destination file\(cq\&s + executability differs from that of the corresponding source file, rsync +! modifies the destination file\(cq\&s permissions as follows: + .IP + .RS + .IP o +! To make a file non\-executable, rsync turns off all its \(cq\&x\(cq\& + permissions. + .IP o +! To make a file executable, rsync turns on each \(cq\&x\(cq\& permission that +! has a corresponding \(cq\&r\(cq\& permission enabled. + .RE + + .IP +*************** +*** 1078,1105 **** + and restore ACLs that are not compatible. + .IP + .IP "\fB\-X, \-\-xattrs\fP" +! This option causes rsync to update the remote +! extended attributes to be the same as the local ones. + .IP +! For systems that support extended-attribute namespaces, a copy being done by a +! super-user copies all namespaces except system.*. A normal user only copies +! the user.* namespace. To be able to backup and restore non-user namespaces as + a normal user, see the \fB\-\-fake\-super\fP option. + .IP + .IP "\fB\-\-chmod\fP" + This option tells rsync to apply one or more +! comma-separated \(lqchmod\(rq strings to the permission of the files in the +! transfer. The resulting value is treated as though it was the permissions + that the sending side supplied for the file, which means that this option + can seem to have no effect on existing files if \fB\-\-perms\fP is not enabled. + .IP + In addition to the normal parsing rules specified in the \fBchmod\fP(1) + manpage, you can specify an item that should only apply to a directory by +! prefixing it with a \(oqD\(cq, or specify an item that should only apply to a +! file by prefixing it with a \(oqF\(cq. For example: + .IP + .RS +! \-\-chmod=Dg+s,ug+w,Fo-w,+X + .RE + + .IP +--- 1130,1164 ---- + and restore ACLs that are not compatible. + .IP + .IP "\fB\-X, \-\-xattrs\fP" +! This option causes rsync to update the destination +! extended attributes to be the same as the source ones. + .IP +! For systems that support extended\-attribute namespaces, a copy being done by a +! super\-user copies all namespaces except system.*. A normal user only copies +! the user.* namespace. To be able to backup and restore non\-user namespaces as + a normal user, see the \fB\-\-fake\-super\fP option. + .IP ++ Note that this option does not copy rsyncs special xattr values (e.g. those ++ used by \fB\-\-fake\-super\fP) unless you repeat the option (e.g. \-XX). This ++ \(dq\© all xattrs\(dq\& mode cannot be used with \fB\-\-fake\-super\fP. ++ .IP + .IP "\fB\-\-chmod\fP" + This option tells rsync to apply one or more +! comma\-separated \(dq\&chmod\(dq\& strings to the permission of the files in the +! transfer. The resulting value is treated as though it were the permissions + that the sending side supplied for the file, which means that this option + can seem to have no effect on existing files if \fB\-\-perms\fP is not enabled. + .IP + In addition to the normal parsing rules specified in the \fBchmod\fP(1) + manpage, you can specify an item that should only apply to a directory by +! prefixing it with a \(cq\&D\(cq\&, or specify an item that should only apply to a +! file by prefixing it with a \(cq\&F\(cq\&. For example, the following will ensure +! that all directories get marked set\-gid, that no files are other\-writable, +! that both are user\-writable and group\-writable, and that both have +! consistent executability across all bits: + .IP + .RS +! \-\-chmod=Dg+s,ug+w,Fo\-w,+X + .RE + + .IP +*************** +*** 1112,1118 **** + .IP "\fB\-o, \-\-owner\fP" + This option causes rsync to set the owner of the + destination file to be the same as the source file, but only if the +! receiving rsync is being run as the super-user (see also the \fB\-\-super\fP + and \fB\-\-fake\-super\fP options). + Without this option, the owner of new and/or transferred files are set to + the invoking user on the receiving side. +--- 1171,1177 ---- + .IP "\fB\-o, \-\-owner\fP" + This option causes rsync to set the owner of the + destination file to be the same as the source file, but only if the +! receiving rsync is being run as the super\-user (see also the \fB\-\-super\fP + and \fB\-\-fake\-super\fP options). + Without this option, the owner of new and/or transferred files are set to + the invoking user on the receiving side. +*************** +*** 1124,1130 **** + .IP "\fB\-g, \-\-group\fP" + This option causes rsync to set the group of the + destination file to be the same as the source file. If the receiving +! program is not running as the super-user (or if \fB\-\-no\-super\fP was + specified), only groups that the invoking user on the receiving side + is a member of will be preserved. + Without this option, the group is set to the default group of the invoking +--- 1183,1189 ---- + .IP "\fB\-g, \-\-group\fP" + This option causes rsync to set the group of the + destination file to be the same as the source file. If the receiving +! program is not running as the super\-user (or if \fB\-\-no\-super\fP was + specified), only groups that the invoking user on the receiving side + is a member of will be preserved. + Without this option, the group is set to the default group of the invoking +*************** +*** 1138,1144 **** + This option causes rsync to transfer character and + block device files to the remote system to recreate these devices. + This option has no effect if the receiving rsync is not run as the +! super-user (see also the \fB\-\-super\fP and \fB\-\-fake\-super\fP options). + .IP + .IP "\fB\-\-specials\fP" + This option causes rsync to transfer special files +--- 1197,1203 ---- + This option causes rsync to transfer character and + block device files to the remote system to recreate these devices. + This option has no effect if the receiving rsync is not run as the +! super\-user (see also the \fB\-\-super\fP and \fB\-\-fake\-super\fP options). + .IP + .IP "\fB\-\-specials\fP" + This option causes rsync to transfer special files +*************** +*** 1153,1160 **** + option is not used, the optimization that excludes files that have not been + modified cannot be effective; in other words, a missing \fB\-t\fP or \fB\-a\fP will + cause the next transfer to behave as if it used \fB\-I\fP, causing all files to be +! updated (though rsync's delta-transfer algorithm will make the update fairly efficient +! if the files haven't actually changed, you're much better off using \fB\-t\fP). + .IP + .IP "\fB\-O, \-\-omit\-dir\-times\fP" + This tells rsync to omit directories when +--- 1212,1219 ---- + option is not used, the optimization that excludes files that have not been + modified cannot be effective; in other words, a missing \fB\-t\fP or \fB\-a\fP will + cause the next transfer to behave as if it used \fB\-I\fP, causing all files to be +! updated (though rsync\(cq\&s delta\-transfer algorithm will make the update fairly efficient +! if the files haven\(cq\&t actually changed, you\(cq\&re much better off using \fB\-t\fP). + .IP + .IP "\fB\-O, \-\-omit\-dir\-times\fP" + This tells rsync to omit directories when +*************** +*** 1163,1224 **** + This option is inferred if you use \fB\-\-backup\fP without \fB\-\-backup\-dir\fP. + .IP + .IP "\fB\-\-super\fP" +! This tells the receiving side to attempt super-user +! activities even if the receiving rsync wasn't run by the super-user. These + activities include: preserving users via the \fB\-\-owner\fP option, preserving +! all groups (not just the current user's groups) via the \fB\-\-groups\fP + option, and copying devices via the \fB\-\-devices\fP option. This is useful +! for systems that allow such activities without being the super-user, and +! also for ensuring that you will get errors if the receiving side isn't +! being run as the super-user. To turn off super-user activities, the +! super-user can use \fB\-\-no\-super\fP. + .IP + .IP "\fB\-\-fake\-super\fP" + When this option is enabled, rsync simulates +! super-user activities by saving/restoring the privileged attributes via + special extended attributes that are attached to each file (as needed). This +! includes the file's owner and group (if it is not the default), the file's + device info (device & special files are created as empty text files), and +! any permission bits that we won't allow to be set on the real file (e.g. +! the real file gets u-s,g-s,o-t for safety) or that would limit the owner's +! access (since the real super-user can always access/change a file, the + files we create can always be accessed/changed by the creating user). +! This option also handles ACLs (if \fB\-\-acls\fP was specified) and non-user + extended attributes (if \fB\-\-xattrs\fP was specified). + .IP +! This is a good way to backup data without using a super-user, and to store + ACLs from incompatible systems. + .IP + The \fB\-\-fake\-super\fP option only affects the side where the option is used. +! To affect the remote side of a remote-shell connection, specify an rsync + path: + .IP + .RS +! \f(CW rsync \-av \-\-rsync\-path="rsync \-\-fake\-super" /src/ host:/dest/\fP + .RE + + .IP +! Since there is only one \(lqside\(rq in a local copy, this option affects both +! the sending and receiving of files. You'll need to specify a copy using +! \(lqlocalhost\(rq if you need to avoid this, possibly using the \(lqlsh\(rq shell + script (from the support directory) as a substitute for an actual remote + shell (see \fB\-\-rsh\fP). + .IP + This option is overridden by both \fB\-\-super\fP and \fB\-\-no\-super\fP. + .IP +! See also the \(lqfake super\(rq setting in the daemon's rsyncd.conf file. + .IP + .IP "\fB\-S, \-\-sparse\fP" + Try to handle sparse files efficiently so they take +! up less space on the destination. Conflicts with \fB\-\-inplace\fP because it's + not possible to overwrite data in a sparse fashion. + .IP +- NOTE: Don't use this option when the destination is a Solaris \(lqtmpfs\(rq +- filesystem. It doesn't seem to handle seeks over null regions +- correctly and ends up corrupting the files. +- .IP + .IP "\fB\-n, \-\-dry\-run\fP" +! This makes rsync perform a trial run that doesn't + make any changes (and produces mostly the same output as a real run). It + is most commonly used in combination with the \fB\-v, \-\-verbose\fP and/or + \fB\-i, \-\-itemize\-changes\fP options to see what an rsync command is going +--- 1222,1279 ---- + This option is inferred if you use \fB\-\-backup\fP without \fB\-\-backup\-dir\fP. + .IP + .IP "\fB\-\-super\fP" +! This tells the receiving side to attempt super\-user +! activities even if the receiving rsync wasn\(cq\&t run by the super\-user. These + activities include: preserving users via the \fB\-\-owner\fP option, preserving +! all groups (not just the current user\(cq\&s groups) via the \fB\-\-groups\fP + option, and copying devices via the \fB\-\-devices\fP option. This is useful +! for systems that allow such activities without being the super\-user, and +! also for ensuring that you will get errors if the receiving side isn\(cq\&t +! being run as the super\-user. To turn off super\-user activities, the +! super\-user can use \fB\-\-no\-super\fP. + .IP + .IP "\fB\-\-fake\-super\fP" + When this option is enabled, rsync simulates +! super\-user activities by saving/restoring the privileged attributes via + special extended attributes that are attached to each file (as needed). This +! includes the file\(cq\&s owner and group (if it is not the default), the file\(cq\&s + device info (device & special files are created as empty text files), and +! any permission bits that we won\(cq\&t allow to be set on the real file (e.g. +! the real file gets u\-s,g\-s,o\-t for safety) or that would limit the owner\(cq\&s +! access (since the real super\-user can always access/change a file, the + files we create can always be accessed/changed by the creating user). +! This option also handles ACLs (if \fB\-\-acls\fP was specified) and non\-user + extended attributes (if \fB\-\-xattrs\fP was specified). + .IP +! This is a good way to backup data without using a super\-user, and to store + ACLs from incompatible systems. + .IP + The \fB\-\-fake\-super\fP option only affects the side where the option is used. +! To affect the remote side of a remote\-shell connection, specify an rsync + path: + .IP + .RS +! \f(CW rsync \-av \-\-rsync\-path=\(dq\&rsync \-\-fake\-super\(dq\& /src/ host:/dest/\fP + .RE + + .IP +! Since there is only one \(dq\&side\(dq\& in a local copy, this option affects both +! the sending and receiving of files. You\(cq\&ll need to specify a copy using +! \(dq\&localhost\(dq\& if you need to avoid this, possibly using the \(dq\&lsh\(dq\& shell + script (from the support directory) as a substitute for an actual remote + shell (see \fB\-\-rsh\fP). + .IP + This option is overridden by both \fB\-\-super\fP and \fB\-\-no\-super\fP. + .IP +! See also the \(dq\&fake super\(dq\& setting in the daemon\(cq\&s rsyncd.conf file. + .IP + .IP "\fB\-S, \-\-sparse\fP" + Try to handle sparse files efficiently so they take +! up less space on the destination. Conflicts with \fB\-\-inplace\fP because it\(cq\&s + not possible to overwrite data in a sparse fashion. + .IP + .IP "\fB\-n, \-\-dry\-run\fP" +! This makes rsync perform a trial run that doesn\(cq\&t + make any changes (and produces mostly the same output as a real run). It + is most commonly used in combination with the \fB\-v, \-\-verbose\fP and/or + \fB\-i, \-\-itemize\-changes\fP options to see what an rsync command is going +*************** +*** 1226,1263 **** + .IP + The output of \fB\-\-itemize\-changes\fP is supposed to be exactly the same on a + dry run and a subsequent real run (barring intentional trickery and system +! call failures); if it isn't, that's a bug. Other output is the same to the +! extent practical, but may differ in some areas. Notably, a dry run does not + send the actual data for file transfers, so \fB\-\-progress\fP has no effect, +! the \(lqbytes sent\(rq, \(lqbytes received\(rq, \(lqliteral data\(rq, and \(lqmatched data\(rq +! statistics are too small, and the \(lqspeedup\(rq value is equivalent to a run +! where no file transfers are needed. + .IP + .IP "\fB\-W, \-\-whole\-file\fP" +! With this option rsync's delta-transfer algorithm +! is not used and the whole file is sent as-is instead. The transfer may be + faster if this option is used when the bandwidth between the source and + destination machines is higher than the bandwidth to disk (especially when the +! \(lqdisk\(rq is actually a networked filesystem). This is the default when both +! the source and destination are specified as local paths. + .IP + .IP "\fB\-x, \-\-one\-file\-system\fP" + This tells rsync to avoid crossing a +! filesystem boundary when recursing. This does not limit the user's ability +! to specify items to copy from multiple filesystems, just rsync's recursion + through the hierarchy of each directory that the user specified, and also + the analogous recursion on the receiving side during deletion. Also keep +! in mind that rsync treats a \(lqbind\(rq mount to the same device as being on the + same filesystem. + .IP +! If this option is repeated, rsync omits all mount-point directories from +! the copy. Otherwise, it includes an empty directory at each mount-point it + encounters (using the attributes of the mounted directory because those of +! the underlying mount-point directory are inaccessible). + .IP + If rsync has been told to collapse symlinks (via \fB\-\-copy\-links\fP or + \fB\-\-copy\-unsafe\-links\fP), a symlink to a directory on another device is +! treated like a mount-point. Symlinks to non-directories are unaffected + by this option. + .IP + .IP "\fB\-\-existing, \-\-ignore\-non\-existing\fP" +--- 1281,1319 ---- + .IP + The output of \fB\-\-itemize\-changes\fP is supposed to be exactly the same on a + dry run and a subsequent real run (barring intentional trickery and system +! call failures); if it isn\(cq\&t, that\(cq\&s a bug. Other output should be mostly +! unchanged, but may differ in some areas. Notably, a dry run does not + send the actual data for file transfers, so \fB\-\-progress\fP has no effect, +! the \(dq\&bytes sent\(dq\&, \(dq\&bytes received\(dq\&, \(dq\&literal data\(dq\&, and \(dq\&matched data\(dq\& +! statistics are too small, and the \(dq\&speedup\(dq\& value is equivalent to a run +! where no file transfers were needed. + .IP + .IP "\fB\-W, \-\-whole\-file\fP" +! With this option rsync\(cq\&s delta\-transfer algorithm +! is not used and the whole file is sent as\-is instead. The transfer may be + faster if this option is used when the bandwidth between the source and + destination machines is higher than the bandwidth to disk (especially when the +! \(dq\&disk\(dq\& is actually a networked filesystem). This is the default when both +! the source and destination are specified as local paths, but only if no +! batch\-writing option is in effect. + .IP + .IP "\fB\-x, \-\-one\-file\-system\fP" + This tells rsync to avoid crossing a +! filesystem boundary when recursing. This does not limit the user\(cq\&s ability +! to specify items to copy from multiple filesystems, just rsync\(cq\&s recursion + through the hierarchy of each directory that the user specified, and also + the analogous recursion on the receiving side during deletion. Also keep +! in mind that rsync treats a \(dq\&bind\(dq\& mount to the same device as being on the + same filesystem. + .IP +! If this option is repeated, rsync omits all mount\-point directories from +! the copy. Otherwise, it includes an empty directory at each mount\-point it + encounters (using the attributes of the mounted directory because those of +! the underlying mount\-point directory are inaccessible). + .IP + If rsync has been told to collapse symlinks (via \fB\-\-copy\-links\fP or + \fB\-\-copy\-unsafe\-links\fP), a symlink to a directory on another device is +! treated like a mount\-point. Symlinks to non\-directories are unaffected + by this option. + .IP + .IP "\fB\-\-existing, \-\-ignore\-non\-existing\fP" +*************** +*** 1267,1274 **** + combined with the \fB\-\-ignore\-existing\fP option, no files will be updated + (which can be useful if all you want to do is delete extraneous files). + .IP +! This option is a transfer rule, not an exclude, so it doesn't affect the +! data that goes into the file-lists, and thus it doesn't affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP + .IP "\fB\-\-ignore\-existing\fP" +--- 1323,1330 ---- + combined with the \fB\-\-ignore\-existing\fP option, no files will be updated + (which can be useful if all you want to do is delete extraneous files). + .IP +! This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the +! data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP + .IP "\fB\-\-ignore\-existing\fP" +*************** +*** 1276,1283 **** + already exist on the destination (this does \fInot\fP ignore existing + directories, or nothing would get done). See also \fB\-\-existing\fP. + .IP +! This option is a transfer rule, not an exclude, so it doesn't affect the +! data that goes into the file-lists, and thus it doesn't affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP + This option can be useful for those doing backups using the \fB\-\-link\-dest\fP +--- 1332,1339 ---- + already exist on the destination (this does \fInot\fP ignore existing + directories, or nothing would get done). See also \fB\-\-existing\fP. + .IP +! This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the +! data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP + This option can be useful for those doing backups using the \fB\-\-link\-dest\fP +*************** +*** 1284,1306 **** + option when they need to continue a backup run that got interrupted. Since + a \fB\-\-link\-dest\fP run is copied into a new directory hierarchy (when it is + used properly), using \fB\-\-ignore existing\fP will ensure that the +! already-handled files don't get tweaked (which avoids a change in +! permissions on the hard-linked files). This does mean that this option + is only looking at the existing files in the destination hierarchy itself. + .IP + .IP "\fB\-\-remove\-source\-files\fP" + This tells rsync to remove from the sending +! side the files (meaning non-directories) that are a part of the transfer + and have been successfully duplicated on the receiving side. + .IP + .IP "\fB\-\-delete\fP" + This tells rsync to delete extraneous files from the +! receiving side (ones that aren't on the sending side), but only for the + directories that are being synchronized. You must have asked rsync to +! send the whole directory (e.g. \(lqdir\(rq or \(lqdir/\(rq) without using a wildcard +! for the directory's contents (e.g. \(lqdir/*\(rq) since the wildcard is expanded + by the shell and rsync thus gets a request to transfer individual files, not +! the files' parent directory. Files that are excluded from the transfer are + also excluded from being deleted unless you use the \fB\-\-delete\-excluded\fP + option or mark the rules as only matching on the sending side (see the + include/exclude modifiers in the FILTER RULES section). +--- 1340,1362 ---- + option when they need to continue a backup run that got interrupted. Since + a \fB\-\-link\-dest\fP run is copied into a new directory hierarchy (when it is + used properly), using \fB\-\-ignore existing\fP will ensure that the +! already\-handled files don\(cq\&t get tweaked (which avoids a change in +! permissions on the hard\-linked files). This does mean that this option + is only looking at the existing files in the destination hierarchy itself. + .IP + .IP "\fB\-\-remove\-source\-files\fP" + This tells rsync to remove from the sending +! side the files (meaning non\-directories) that are a part of the transfer + and have been successfully duplicated on the receiving side. + .IP + .IP "\fB\-\-delete\fP" + This tells rsync to delete extraneous files from the +! receiving side (ones that aren\(cq\&t on the sending side), but only for the + directories that are being synchronized. You must have asked rsync to +! send the whole directory (e.g. \(dq\&dir\(dq\& or \(dq\&dir/\(dq\&) without using a wildcard +! for the directory\(cq\&s contents (e.g. \(dq\&dir/*\(dq\&) since the wildcard is expanded + by the shell and rsync thus gets a request to transfer individual files, not +! the files\(cq\& parent directory. Files that are excluded from the transfer are + also excluded from being deleted unless you use the \fB\-\-delete\-excluded\fP + option or mark the rules as only matching on the sending side (see the + include/exclude modifiers in the FILTER RULES section). +*************** +*** 1316,1322 **** + If the sending side detects any I/O errors, then the deletion of any + files at the destination will be automatically disabled. This is to + prevent temporary filesystem failures (such as NFS errors) on the +! sending side causing a massive deletion of files on the + destination. You can override this with the \fB\-\-ignore\-errors\fP option. + .IP + The \fB\-\-delete\fP option may be combined with one of the \-\-delete\-WHEN options +--- 1372,1378 ---- + If the sending side detects any I/O errors, then the deletion of any + files at the destination will be automatically disabled. This is to + prevent temporary filesystem failures (such as NFS errors) on the +! sending side from causing a massive deletion of files on the + destination. You can override this with the \fB\-\-ignore\-errors\fP option. + .IP + The \fB\-\-delete\fP option may be combined with one of the \-\-delete\-WHEN options +*************** +*** 1327,1355 **** + \fB\-\-delete\-delay\fP and \fB\-\-delete\-after\fP. + .IP + .IP "\fB\-\-delete\-before\fP" +! Request that the file-deletions on the receiving + side be done before the transfer starts. +! See \fB\-\-delete\fP (which is implied) for more details on file-deletion. + .IP + Deleting before the transfer is helpful if the filesystem is tight for space + and removing extraneous files would help to make the transfer possible. + However, it does introduce a delay before the start of the transfer, + and this delay might cause the transfer to timeout (if \fB\-\-timeout\fP was +! specified). It also forces rsync to use the old, non-incremental recursion + algorithm that requires rsync to scan all the files in the transfer into + memory at once (see \fB\-\-recursive\fP). + .IP + .IP "\fB\-\-delete\-during, \-\-del\fP" +! Request that the file-deletions on the + receiving side be done incrementally as the transfer happens. The +! per-directory delete scan is done right before each directory is checked + for updates, so it behaves like a more efficient \fB\-\-delete\-before\fP, +! including doing the deletions prior to any per-directory filter files + being updated. This option was first added in rsync version 2.6.4. +! See \fB\-\-delete\fP (which is implied) for more details on file-deletion. + .IP + .IP "\fB\-\-delete\-delay\fP" +! Request that the file-deletions on the receiving + side be computed during the transfer (like \fB\-\-delete\-during\fP), and then + removed after the transfer completes. This is useful when combined with + \fB\-\-delay\-updates\fP and/or \fB\-\-fuzzy\fP, and is more efficient than using +--- 1383,1411 ---- + \fB\-\-delete\-delay\fP and \fB\-\-delete\-after\fP. + .IP + .IP "\fB\-\-delete\-before\fP" +! Request that the file\-deletions on the receiving + side be done before the transfer starts. +! See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. + .IP + Deleting before the transfer is helpful if the filesystem is tight for space + and removing extraneous files would help to make the transfer possible. + However, it does introduce a delay before the start of the transfer, + and this delay might cause the transfer to timeout (if \fB\-\-timeout\fP was +! specified). It also forces rsync to use the old, non\-incremental recursion + algorithm that requires rsync to scan all the files in the transfer into + memory at once (see \fB\-\-recursive\fP). + .IP + .IP "\fB\-\-delete\-during, \-\-del\fP" +! Request that the file\-deletions on the + receiving side be done incrementally as the transfer happens. The +! per\-directory delete scan is done right before each directory is checked + for updates, so it behaves like a more efficient \fB\-\-delete\-before\fP, +! including doing the deletions prior to any per\-directory filter files + being updated. This option was first added in rsync version 2.6.4. +! See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. + .IP + .IP "\fB\-\-delete\-delay\fP" +! Request that the file\-deletions on the receiving + side be computed during the transfer (like \fB\-\-delete\-during\fP), and then + removed after the transfer completes. This is useful when combined with + \fB\-\-delay\-updates\fP and/or \fB\-\-fuzzy\fP, and is more efficient than using +*************** +*** 1357,1377 **** + computes the deletions in a separate pass after all updates are done). + If the number of removed files overflows an internal buffer, a + temporary file will be created on the receiving side to hold the names (it +! is removed while open, so you shouldn't see it during the transfer). If + the creation of the temporary file fails, rsync will try to fall back to + using \fB\-\-delete\-after\fP (which it cannot do if \fB\-\-recursive\fP is doing an + incremental scan). +! See \fB\-\-delete\fP (which is implied) for more details on file-deletion. + .IP + .IP "\fB\-\-delete\-after\fP" +! Request that the file-deletions on the receiving + side be done after the transfer has completed. This is useful if you +! are sending new per-directory merge files as a part of the transfer and + you want their exclusions to take effect for the delete phase of the +! current transfer. It also forces rsync to use the old, non-incremental + recursion algorithm that requires rsync to scan all the files in the + transfer into memory at once (see \fB\-\-recursive\fP). +! See \fB\-\-delete\fP (which is implied) for more details on file-deletion. + .IP + .IP "\fB\-\-delete\-excluded\fP" + In addition to deleting the files on the +--- 1413,1433 ---- + computes the deletions in a separate pass after all updates are done). + If the number of removed files overflows an internal buffer, a + temporary file will be created on the receiving side to hold the names (it +! is removed while open, so you shouldn\(cq\&t see it during the transfer). If + the creation of the temporary file fails, rsync will try to fall back to + using \fB\-\-delete\-after\fP (which it cannot do if \fB\-\-recursive\fP is doing an + incremental scan). +! See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. + .IP + .IP "\fB\-\-delete\-after\fP" +! Request that the file\-deletions on the receiving + side be done after the transfer has completed. This is useful if you +! are sending new per\-directory merge files as a part of the transfer and + you want their exclusions to take effect for the delete phase of the +! current transfer. It also forces rsync to use the old, non\-incremental + recursion algorithm that requires rsync to scan all the files in the + transfer into memory at once (see \fB\-\-recursive\fP). +! See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. + .IP + .IP "\fB\-\-delete\-excluded\fP" + In addition to deleting the files on the +*************** +*** 1380,1386 **** + See the FILTER RULES section for a way to make individual exclusions behave + this way on the receiver, and for a way to protect files from + \fB\-\-delete\-excluded\fP. +! See \fB\-\-delete\fP (which is implied) for more details on file-deletion. + .IP + .IP "\fB\-\-ignore\-errors\fP" + Tells \fB\-\-delete\fP to go ahead and delete files +--- 1436,1442 ---- + See the FILTER RULES section for a way to make individual exclusions behave + this way on the receiver, and for a way to protect files from + \fB\-\-delete\-excluded\fP. +! See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. + .IP + .IP "\fB\-\-ignore\-errors\fP" + Tells \fB\-\-delete\fP to go ahead and delete files +*************** +*** 1387,1398 **** + even when there are I/O errors. + .IP + .IP "\fB\-\-force\fP" +! This option tells rsync to delete a non-empty directory +! when it is to be replaced by a non-directory. This is only relevant if + deletions are not active (see \fB\-\-delete\fP for details). + .IP + Note for older rsync versions: \fB\-\-force\fP used to still be required when +! using \fB\-\-delete\-after\fP, and it used to be non-functional unless the + \fB\-\-recursive\fP option was also enabled. + .IP + .IP "\fB\-\-max\-delete=NUM\fP" +--- 1443,1454 ---- + even when there are I/O errors. + .IP + .IP "\fB\-\-force\fP" +! This option tells rsync to delete a non\-empty directory +! when it is to be replaced by a non\-directory. This is only relevant if + deletions are not active (see \fB\-\-delete\fP for details). + .IP + Note for older rsync versions: \fB\-\-force\fP used to still be required when +! using \fB\-\-delete\-after\fP, and it used to be non\-functional unless the + \fB\-\-recursive\fP option was also enabled. + .IP + .IP "\fB\-\-max\-delete=NUM\fP" +*************** +*** 1402,1428 **** + .IP + Also new for version 3.0.0, you may specify \fB\-\-max\-delete=0\fP to be warned + about any extraneous files in the destination without removing any of them. +! Older clients interpreted this as \(lqunlimited\(rq, so if you don't know what + version the client is, you can use the less obvious \fB\-\-max\-delete=\-1\fP as +! a backward-compatible way to specify that no deletions be allowed (though +! older versions didn't warn when the limit was exceeded). + .IP + .IP "\fB\-\-max\-size=SIZE\fP" + This tells rsync to avoid transferring any + file that is larger than the specified SIZE. The SIZE value can be + suffixed with a string to indicate a size multiplier, and +! may be a fractional value (e.g. \(lq\fB\-\-max\-size=1.5m\fP\(rq). + .IP +! This option is a transfer rule, not an exclude, so it doesn't affect the +! data that goes into the file-lists, and thus it doesn't affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP +! The suffixes are as follows: \(lqK\(rq (or \(lqKiB\(rq) is a kibibyte (1024), +! \(lqM\(rq (or \(lqMiB\(rq) is a mebibyte (1024*1024), and \(lqG\(rq (or \(lqGiB\(rq) is a + gibibyte (1024*1024*1024). +! If you want the multiplier to be 1000 instead of 1024, use \(lqKB\(rq, +! \(lqMB\(rq, or \(lqGB\(rq. (Note: lower-case is also accepted for all values.) +! Finally, if the suffix ends in either \(lq+1\(rq or \(lq\-1\(rq, the value will + be offset by one byte in the indicated direction. + .IP + Examples: \-\-max\-size=1.5mb\-1 is 1499999 bytes, and \-\-max\-size=2g+1 is +--- 1458,1484 ---- + .IP + Also new for version 3.0.0, you may specify \fB\-\-max\-delete=0\fP to be warned + about any extraneous files in the destination without removing any of them. +! Older clients interpreted this as \(dq\&unlimited\(dq\&, so if you don\(cq\&t know what + version the client is, you can use the less obvious \fB\-\-max\-delete=\-1\fP as +! a backward\-compatible way to specify that no deletions be allowed (though +! older versions didn\(cq\&t warn when the limit was exceeded). + .IP + .IP "\fB\-\-max\-size=SIZE\fP" + This tells rsync to avoid transferring any + file that is larger than the specified SIZE. The SIZE value can be + suffixed with a string to indicate a size multiplier, and +! may be a fractional value (e.g. \(dq\&\fB\-\-max\-size=1.5m\fP\(dq\&). + .IP +! This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the +! data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. + It just limits the files that the receiver requests to be transferred. + .IP +! The suffixes are as follows: \(dq\&K\(dq\& (or \(dq\&KiB\(dq\&) is a kibibyte (1024), +! \(dq\&M\(dq\& (or \(dq\&MiB\(dq\&) is a mebibyte (1024*1024), and \(dq\&G\(dq\& (or \(dq\&GiB\(dq\&) is a + gibibyte (1024*1024*1024). +! If you want the multiplier to be 1000 instead of 1024, use \(dq\&KB\(dq\&, +! \(dq\&MB\(dq\&, or \(dq\&GB\(dq\&. (Note: lower\-case is also accepted for all values.) +! Finally, if the suffix ends in either \(dq\&+1\(dq\& or \(dq\&\-1\(dq\&, the value will + be offset by one byte in the indicated direction. + .IP + Examples: \-\-max\-size=1.5mb\-1 is 1499999 bytes, and \-\-max\-size=2g+1 is +*************** +*** 1436,1442 **** + .IP + .IP "\fB\-B, \-\-block\-size=BLOCKSIZE\fP" + This forces the block size used in +! rsync's delta-transfer algorithm to a fixed value. It is normally selected based on + the size of each file being updated. See the technical report for details. + .IP + .IP "\fB\-e, \-\-rsh=COMMAND\fP" +--- 1492,1498 ---- + .IP + .IP "\fB\-B, \-\-block\-size=BLOCKSIZE\fP" + This forces the block size used in +! rsync\(cq\&s delta\-transfer algorithm to a fixed value. It is normally selected based on + the size of each file being updated. See the technical report for details. + .IP + .IP "\fB\-e, \-\-rsh=COMMAND\fP" +*************** +*** 1449,1475 **** + remote shell \fICOMMAND\fP will be used to run an rsync daemon on the + remote host, and all data will be transmitted through that remote + shell connection, rather than through a direct socket connection to a +! running rsync daemon on the remote host. See the section \(lqUSING +! RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION\(rq above. + .IP +! Command-line arguments are permitted in COMMAND provided that COMMAND is + presented to rsync as a single argument. You must use spaces (not tabs + or other whitespace) to separate the command and args from each other, +! and you can use single- and/or double-quotes to preserve spaces in an +! argument (but not backslashes). Note that doubling a single-quote +! inside a single-quoted string gives you a single-quote; likewise for +! double-quotes (though you need to pay attention to which quotes your + shell is parsing and which quotes rsync is parsing). Some examples: + .IP + .RS +! \f(CW \-e 'ssh \-p 2234'\fP + .br +! \f(CW \-e 'ssh \-o "ProxyCommand nohup ssh firewall nc \-w1 %h %p"'\fP + .br + .RE + + .IP +! (Note that ssh users can alternately customize site-specific connect + options in their .ssh/config file.) + .IP + You can also choose the remote shell program using the RSYNC_RSH +--- 1505,1531 ---- + remote shell \fICOMMAND\fP will be used to run an rsync daemon on the + remote host, and all data will be transmitted through that remote + shell connection, rather than through a direct socket connection to a +! running rsync daemon on the remote host. See the section \(dq\&USING +! RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION\(dq\& above. + .IP +! Command\-line arguments are permitted in COMMAND provided that COMMAND is + presented to rsync as a single argument. You must use spaces (not tabs + or other whitespace) to separate the command and args from each other, +! and you can use single\- and/or double\-quotes to preserve spaces in an +! argument (but not backslashes). Note that doubling a single\-quote +! inside a single\-quoted string gives you a single\-quote; likewise for +! double\-quotes (though you need to pay attention to which quotes your + shell is parsing and which quotes rsync is parsing). Some examples: + .IP + .RS +! \f(CW \-e '\&ssh \-p 2234'\&\fP + .br +! \f(CW \-e '\&ssh \-o \(dq\&ProxyCommand nohup ssh firewall nc \-w1 %h %p\(dq\&'\&\fP + .br + .RE + + .IP +! (Note that ssh users can alternately customize site\-specific connect + options in their .ssh/config file.) + .IP + You can also choose the remote shell program using the RSYNC_RSH +*************** +*** 1479,1489 **** + .IP + .IP "\fB\-\-rsync\-path=PROGRAM\fP" + Use this to specify what program is to be run +! on the remote machine to start-up rsync. Often used when rsync is not in +! the default remote-shell's path (e.g. \-\-rsync\-path=/usr/local/bin/rsync). + Note that PROGRAM is run with the help of a shell, so it can be any +! program, script, or command sequence you'd care to run, so long as it does +! not corrupt the standard-in & standard-out that rsync is using to + communicate. + .IP + One tricky example is to set a different default directory on the remote +--- 1535,1545 ---- + .IP + .IP "\fB\-\-rsync\-path=PROGRAM\fP" + Use this to specify what program is to be run +! on the remote machine to start\-up rsync. Often used when rsync is not in +! the default remote\-shell\(cq\&s path (e.g. \-\-rsync\-path=/usr/local/bin/rsync). + Note that PROGRAM is run with the help of a shell, so it can be any +! program, script, or command sequence you\(cq\&d care to run, so long as it does +! not corrupt the standard\-in & standard\-out that rsync is using to + communicate. + .IP + One tricky example is to set a different default directory on the remote +*************** +*** 1490,1513 **** + machine for use with the \fB\-\-relative\fP option. For instance: + .IP + .RS +! \f(CW rsync \-avR \-\-rsync\-path="cd /a/b && rsync" host:c/d /e/\fP + .RE + + .IP + .IP "\fB\-C, \-\-cvs\-exclude\fP" + This is a useful shorthand for excluding a +! broad range of files that you often don't want to transfer between + systems. It uses a similar algorithm to CVS to determine if + a file should be ignored. + .IP + The exclude list is initialized to exclude the following items (these +! initial items are marked as perishable \(em see the FILTER RULES section): + .IP + .RS + .RS + \f(CWRCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state + \&.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del\-* +! *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .bzr/\fP + .RE + .RE + +--- 1546,1569 ---- + machine for use with the \fB\-\-relative\fP option. For instance: + .IP + .RS +! \f(CW rsync \-avR \-\-rsync\-path=\(dq\&cd /a/b && rsync\(dq\& host:c/d /e/\fP + .RE + + .IP + .IP "\fB\-C, \-\-cvs\-exclude\fP" + This is a useful shorthand for excluding a +! broad range of files that you often don\(cq\&t want to transfer between + systems. It uses a similar algorithm to CVS to determine if + a file should be ignored. + .IP + The exclude list is initialized to exclude the following items (these +! initial items are marked as perishable \-\- see the FILTER RULES section): + .IP + .RS + .RS + \f(CWRCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state + \&.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del\-* +! *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .hg/ .bzr/\fP + .RE + .RE + +*************** +*** 1518,1536 **** + .IP + Finally, any file is ignored if it is in the same directory as a + \&.cvsignore file and matches one of the patterns listed therein. Unlike +! rsync's filter/exclude files, these patterns are split on whitespace. + See the \fBcvs\fP(1) manual for more information. + .IP +! If you're combining \fB\-C\fP with your own \fB\-\-filter\fP rules, you should + note that these CVS excludes are appended at the end of your own rules, +! regardless of where the \fB\-C\fP was placed on the command-line. This makes them + a lower priority than any rules you specified explicitly. If you want to + control where these CVS excludes get inserted into your filter rules, you +! should omit the \fB\-C\fP as a command-line option and use a combination of +! \fB\-\-filter=:C\fP and \fB\-\-filter=\-C\fP (either on your command-line or by +! putting the \(lq:C\(rq and \(lq\-C\(rq rules into a filter file with your other rules). +! The first option turns on the per-directory scanning for the .cvsignore +! file. The second option does a one-time import of the CVS excludes + mentioned above. + .IP + .IP "\fB\-f, \-\-filter=RULE\fP" +--- 1574,1592 ---- + .IP + Finally, any file is ignored if it is in the same directory as a + \&.cvsignore file and matches one of the patterns listed therein. Unlike +! rsync\(cq\&s filter/exclude files, these patterns are split on whitespace. + See the \fBcvs\fP(1) manual for more information. + .IP +! If you\(cq\&re combining \fB\-C\fP with your own \fB\-\-filter\fP rules, you should + note that these CVS excludes are appended at the end of your own rules, +! regardless of where the \fB\-C\fP was placed on the command\-line. This makes them + a lower priority than any rules you specified explicitly. If you want to + control where these CVS excludes get inserted into your filter rules, you +! should omit the \fB\-C\fP as a command\-line option and use a combination of +! \fB\-\-filter=:C\fP and \fB\-\-filter=\-C\fP (either on your command\-line or by +! putting the \(dq\&:C\(dq\& and \(dq\&\-C\(dq\& rules into a filter file with your other rules). +! The first option turns on the per\-directory scanning for the .cvsignore +! file. The second option does a one\-time import of the CVS excludes + mentioned above. + .IP + .IP "\fB\-f, \-\-filter=RULE\fP" +*************** +*** 1551,1567 **** + your command. The first time it is used is a shorthand for this rule: + .IP + .RS +! \f(CW \-\-filter='dir\-merge /.rsync\-filter'\fP + .RE + + .IP +! This tells rsync to look for per-directory .rsync\-filter files that have + been sprinkled through the hierarchy and use their rules to filter the + files in the transfer. If \fB\-F\fP is repeated, it is a shorthand for this + rule: + .IP + .RS +! \f(CW \-\-filter='exclude .rsync\-filter'\fP + .RE + + .IP +--- 1607,1623 ---- + your command. The first time it is used is a shorthand for this rule: + .IP + .RS +! \f(CW \-\-filter='\&dir\-merge /.rsync\-filter'\&\fP + .RE + + .IP +! This tells rsync to look for per\-directory .rsync\-filter files that have + been sprinkled through the hierarchy and use their rules to filter the + files in the transfer. If \fB\-F\fP is repeated, it is a shorthand for this + rule: + .IP + .RS +! \f(CW \-\-filter='\&exclude .rsync\-filter'\&\fP + .RE + + .IP +*************** +*** 1573,1579 **** + .IP "\fB\-\-exclude=PATTERN\fP" + This option is a simplified form of the + \fB\-\-filter\fP option that defaults to an exclude rule and does not allow +! the full rule-parsing syntax of normal filter rules. + .IP + See the FILTER RULES section for detailed information on this option. + .IP +--- 1629,1635 ---- + .IP "\fB\-\-exclude=PATTERN\fP" + This option is a simplified form of the + \fB\-\-filter\fP option that defaults to an exclude rule and does not allow +! the full rule\-parsing syntax of normal filter rules. + .IP + See the FILTER RULES section for detailed information on this option. + .IP +*************** +*** 1580,1592 **** + .IP "\fB\-\-exclude\-from=FILE\fP" + This option is related to the \fB\-\-exclude\fP + option, but it specifies a FILE that contains exclude patterns (one per line). +! Blank lines in the file and lines starting with \(oq;\(cq or \(oq#\(cq are ignored. + If \fIFILE\fP is \fB\-\fP, the list will be read from standard input. + .IP + .IP "\fB\-\-include=PATTERN\fP" + This option is a simplified form of the + \fB\-\-filter\fP option that defaults to an include rule and does not allow +! the full rule-parsing syntax of normal filter rules. + .IP + See the FILTER RULES section for detailed information on this option. + .IP +--- 1636,1648 ---- + .IP "\fB\-\-exclude\-from=FILE\fP" + This option is related to the \fB\-\-exclude\fP + option, but it specifies a FILE that contains exclude patterns (one per line). +! Blank lines in the file and lines starting with \(cq\&;\(cq\& or \(cq\&#\(cq\& are ignored. + If \fIFILE\fP is \fB\-\fP, the list will be read from standard input. + .IP + .IP "\fB\-\-include=PATTERN\fP" + This option is a simplified form of the + \fB\-\-filter\fP option that defaults to an include rule and does not allow +! the full rule\-parsing syntax of normal filter rules. + .IP + See the FILTER RULES section for detailed information on this option. + .IP +*************** +*** 1593,1599 **** + .IP "\fB\-\-include\-from=FILE\fP" + This option is related to the \fB\-\-include\fP + option, but it specifies a FILE that contains include patterns (one per line). +! Blank lines in the file and lines starting with \(oq;\(cq or \(oq#\(cq are ignored. + If \fIFILE\fP is \fB\-\fP, the list will be read from standard input. + .IP + .IP "\fB\-\-files\-from=FILE\fP" +--- 1649,1655 ---- + .IP "\fB\-\-include\-from=FILE\fP" + This option is related to the \fB\-\-include\fP + option, but it specifies a FILE that contains include patterns (one per line). +! Blank lines in the file and lines starting with \(cq\&;\(cq\& or \(cq\&#\(cq\& are ignored. + If \fIFILE\fP is \fB\-\fP, the list will be read from standard input. + .IP + .IP "\fB\-\-files\-from=FILE\fP" +*************** +*** 1612,1622 **** + specified in the list on the destination rather than noisily skipping + them (use \fB\-\-no\-dirs\fP or \fB\-\-no\-d\fP if you want to turn that off). + .IP o +! The \fB\-\-archive\fP (\fB\-a\fP) option's behavior does not imply \fB\-\-recursive\fP + (\fB\-r\fP), so specify it explicitly, if you want it. + .IP o +! These side-effects change the default state of rsync, so the position +! of the \fB\-\-files\-from\fP option on the command-line has no bearing on how + other options are parsed (e.g. \fB\-a\fP works the same before or after + \fB\-\-files\-from\fP, as does \fB\-\-no\-R\fP and all other options). + .RE +--- 1668,1678 ---- + specified in the list on the destination rather than noisily skipping + them (use \fB\-\-no\-dirs\fP or \fB\-\-no\-d\fP if you want to turn that off). + .IP o +! The \fB\-\-archive\fP (\fB\-a\fP) option\(cq\&s behavior does not imply \fB\-\-recursive\fP + (\fB\-r\fP), so specify it explicitly, if you want it. + .IP o +! These side\-effects change the default state of rsync, so the position +! of the \fB\-\-files\-from\fP option on the command\-line has no bearing on how + other options are parsed (e.g. \fB\-a\fP works the same before or after + \fB\-\-files\-from\fP, as does \fB\-\-no\-R\fP and all other options). + .RE +*************** +*** 1623,1629 **** + + .IP + The filenames that are read from the FILE are all relative to the +! source dir \(em any leading slashes are removed and no \(lq..\(rq references are + allowed to go higher than the source dir. For example, take this + command: + .IP +--- 1679,1685 ---- + + .IP + The filenames that are read from the FILE are all relative to the +! source dir \-\- any leading slashes are removed and no \(dq\&..\(dq\& references are + allowed to go higher than the source dir. For example, take this + command: + .IP +*************** +*** 1632,1655 **** + .RE + + .IP +! If /tmp/foo contains the string \(lqbin\(rq (or even \(lq/bin\(rq), the /usr/bin + directory will be created as /backup/bin on the remote host. If it +! contains \(lqbin/\(rq (note the trailing slash), the immediate contents of + the directory would also be sent (without needing to be explicitly +! mentioned in the file \(em this began in version 2.6.4). In both cases, +! if the \fB\-r\fP option was enabled, that dir's entire hierarchy would + also be transferred (keep in mind that \fB\-r\fP needs to be specified + explicitly with \fB\-\-files\-from\fP, since it is not implied by \fB\-a\fP). + Also note + that the effect of the (enabled by default) \fB\-\-relative\fP option is to +! duplicate only the path info that is read from the file \(em it does not +! force the duplication of the source-spec path (/usr in this case). + .IP + In addition, the \fB\-\-files\-from\fP file can be read from the remote host +! instead of the local host if you specify a \(lqhost:\(rq in front of the file +! (the host must match one end of the transfer). As a short-cut, you can +! specify just a prefix of \(lq:\(rq to mean \(lquse the remote end of the +! transfer\(rq. For example: + .IP + .RS + \f(CW rsync \-a \-\-files\-from=:/path/file\-list src:/ /tmp/copy\fP +--- 1688,1711 ---- + .RE + + .IP +! If /tmp/foo contains the string \(dq\&bin\(dq\& (or even \(dq\&/bin\(dq\&), the /usr/bin + directory will be created as /backup/bin on the remote host. If it +! contains \(dq\&bin/\(dq\& (note the trailing slash), the immediate contents of + the directory would also be sent (without needing to be explicitly +! mentioned in the file \-\- this began in version 2.6.4). In both cases, +! if the \fB\-r\fP option was enabled, that dir\(cq\&s entire hierarchy would + also be transferred (keep in mind that \fB\-r\fP needs to be specified + explicitly with \fB\-\-files\-from\fP, since it is not implied by \fB\-a\fP). + Also note + that the effect of the (enabled by default) \fB\-\-relative\fP option is to +! duplicate only the path info that is read from the file \-\- it does not +! force the duplication of the source\-spec path (/usr in this case). + .IP + In addition, the \fB\-\-files\-from\fP file can be read from the remote host +! instead of the local host if you specify a \(dq\&host:\(dq\& in front of the file +! (the host must match one end of the transfer). As a short\-cut, you can +! specify just a prefix of \(dq\&:\(dq\& to mean \(dq\&use the remote end of the +! transfer\(dq\&. For example: + .IP + .RS + \f(CW rsync \-a \-\-files\-from=:/path/file\-list src:/ /tmp/copy\fP +*************** +*** 1656,1687 **** + .RE + + .IP +! This would copy all the files specified in the /path/file-list file that +! was located on the remote \(lqsrc\(rq host. + .IP + .IP "\fB\-0, \-\-from0\fP" + This tells rsync that the rules/filenames it reads from a +! file are terminated by a null ('\e0') character, not a NL, CR, or CR+LF. + This affects \fB\-\-exclude\-from\fP, \fB\-\-include\-from\fP, \fB\-\-files\-from\fP, and any + merged files specified in a \fB\-\-filter\fP rule. + It does not affect \fB\-\-cvs\-exclude\fP (since all names read from a .cvsignore + file are split on whitespace). + .IP +- If the \fB\-\-iconv\fP and \fB\-\-protect\-args\fP options are specified and the +- \fB\-\-files\-from\fP filenames are being sent from one host to another, the +- filenames will be translated from the sending host's charset to the +- receiving host's charset. +- .IP + .IP "\fB\-s, \-\-protect\-args\fP" +! This option sends all filenames and some options to + the remote rsync without allowing the remote shell to interpret them. This +! means that spaces are not split in names, and any non-wildcard special + characters are not translated (such as ~, $, ;, &, etc.). Wildcards are + expanded on the remote host by rsync (instead of the shell doing it). + .IP +! If you use this option with \fB\-\-iconv\fP, the args will also be translated +! from the local to the remote character-set. The translation happens before +! wild-cards are expanded. See also the \fB\-\-files\-from\fP option. + .IP + .IP "\fB\-T, \-\-temp\-dir=DIR\fP" + This option instructs rsync to use DIR as a +--- 1712,1750 ---- + .RE + + .IP +! This would copy all the files specified in the /path/file\-list file that +! was located on the remote \(dq\&src\(dq\& host. + .IP ++ If the \fB\-\-iconv\fP and \fB\-\-protect\-args\fP options are specified and the ++ \fB\-\-files\-from\fP filenames are being sent from one host to another, the ++ filenames will be translated from the sending host\(cq\&s charset to the ++ receiving host\(cq\&s charset. ++ .IP ++ NOTE: sorting the list of files in the \-\-files\-from input helps rsync to be ++ more efficient, as it will avoid re\-visiting the path elements that are shared ++ between adjacent entries. If the input is not sorted, some path elements ++ (implied directories) may end up being scanned multiple times, and rsync will ++ eventually unduplicate them after they get turned into file\-list elements. ++ .IP + .IP "\fB\-0, \-\-from0\fP" + This tells rsync that the rules/filenames it reads from a +! file are terminated by a null (\(cq\&\e0\(cq\&) character, not a NL, CR, or CR+LF. + This affects \fB\-\-exclude\-from\fP, \fB\-\-include\-from\fP, \fB\-\-files\-from\fP, and any + merged files specified in a \fB\-\-filter\fP rule. + It does not affect \fB\-\-cvs\-exclude\fP (since all names read from a .cvsignore + file are split on whitespace). + .IP + .IP "\fB\-s, \-\-protect\-args\fP" +! This option sends all filenames and most options to + the remote rsync without allowing the remote shell to interpret them. This +! means that spaces are not split in names, and any non\-wildcard special + characters are not translated (such as ~, $, ;, &, etc.). Wildcards are + expanded on the remote host by rsync (instead of the shell doing it). + .IP +! If you use this option with \fB\-\-iconv\fP, the args related to the remote +! side will also be translated +! from the local to the remote character\-set. The translation happens before +! wild\-cards are expanded. See also the \fB\-\-files\-from\fP option. + .IP + .IP "\fB\-T, \-\-temp\-dir=DIR\fP" + This option instructs rsync to use DIR as a +*************** +*** 1706,1730 **** + If you are using this option for reasons other than a shortage of disk + space, you may wish to combine it with the \fB\-\-delay\-updates\fP option, + which will ensure that all copied files get put into subdirectories in the +! destination hierarchy, awaiting the end of the transfer. If you don't + have enough room to duplicate all the arriving files on the destination +! partition, another way to tell rsync that you aren't overly concerned + about disk space is to use the \fB\-\-partial\-dir\fP option with a relative + path; because this tells rsync that it is OK to stash off a copy of a + single file in a subdir in the destination hierarchy, rsync will use the +! partial-dir as a staging area to bring over the copied file, and then + rename it into place from there. (Specifying a \fB\-\-partial\-dir\fP with +! an absolute path does not have this side-effect.) + .IP + .IP "\fB\-y, \-\-fuzzy\fP" + This option tells rsync that it should look for a + basis file for any destination file that is missing. The current algorithm + looks in the same directory as the destination file for either a file that +! has an identical size and modified-time, or a similarly-named file. If + found, rsync uses the fuzzy basis file to try to speed up the transfer. + .IP + Note that the use of the \fB\-\-delete\fP option might get rid of any potential +! fuzzy-match files, so either use \fB\-\-delete\-after\fP or specify some + filename exclusions if you need to prevent this. + .IP + .IP "\fB\-\-compare\-dest=DIR\fP" +--- 1769,1793 ---- + If you are using this option for reasons other than a shortage of disk + space, you may wish to combine it with the \fB\-\-delay\-updates\fP option, + which will ensure that all copied files get put into subdirectories in the +! destination hierarchy, awaiting the end of the transfer. If you don\(cq\&t + have enough room to duplicate all the arriving files on the destination +! partition, another way to tell rsync that you aren\(cq\&t overly concerned + about disk space is to use the \fB\-\-partial\-dir\fP option with a relative + path; because this tells rsync that it is OK to stash off a copy of a + single file in a subdir in the destination hierarchy, rsync will use the +! partial\-dir as a staging area to bring over the copied file, and then + rename it into place from there. (Specifying a \fB\-\-partial\-dir\fP with +! an absolute path does not have this side\-effect.) + .IP + .IP "\fB\-y, \-\-fuzzy\fP" + This option tells rsync that it should look for a + basis file for any destination file that is missing. The current algorithm + looks in the same directory as the destination file for either a file that +! has an identical size and modified\-time, or a similarly\-named file. If + found, rsync uses the fuzzy basis file to try to speed up the transfer. + .IP + Note that the use of the \fB\-\-delete\fP option might get rid of any potential +! fuzzy\-match files, so either use \fB\-\-delete\-after\fP or specify some + filename exclusions if you need to prevent this. + .IP + .IP "\fB\-\-compare\-dest=DIR\fP" +*************** +*** 1732,1738 **** + the destination machine as an additional hierarchy to compare destination + files against doing transfers (if the files are missing in the destination + directory). If a file is found in \fIDIR\fP that is identical to the +! sender's file, the file will NOT be transferred to the destination + directory. This is useful for creating a sparse backup of just files that + have changed from an earlier backup. + .IP +--- 1795,1801 ---- + the destination machine as an additional hierarchy to compare destination + files against doing transfers (if the files are missing in the destination + directory). If a file is found in \fIDIR\fP that is identical to the +! sender\(cq\&s file, the file will NOT be transferred to the destination + directory. This is useful for creating a sparse backup of just files that + have changed from an earlier backup. + .IP +*************** +*** 1752,1758 **** + rsync will also copy unchanged files found in \fIDIR\fP to the destination + directory using a local copy. + This is useful for doing transfers to a new destination while leaving +! existing files intact, and then doing a flash-cutover when all files have + been successfully transferred. + .IP + Multiple \fB\-\-copy\-dest\fP directories may be provided, which will cause +--- 1815,1821 ---- + rsync will also copy unchanged files found in \fIDIR\fP to the destination + directory using a local copy. + This is useful for doing transfers to a new destination while leaving +! existing files intact, and then doing a flash\-cutover when all files have + been successfully transferred. + .IP + Multiple \fB\-\-copy\-dest\fP directories may be provided, which will cause +*************** +*** 1775,1784 **** + .RE + + .IP +! If file's aren't linking, double-check their attributes. Also check if some +! attributes are getting forced outside of rsync's control, such a mount option + that squishes root to a single user, or mounts a removable drive with generic +! ownership (such as OS X's \(lqIgnore ownership on this volume\(rq option). + .IP + Beginning in version 2.6.4, multiple \fB\-\-link\-dest\fP directories may be + provided, which will cause rsync to search the list in the order specified +--- 1838,1847 ---- + .RE + + .IP +! If file\(cq\&s aren\(cq\&t linking, double\-check their attributes. Also check if some +! attributes are getting forced outside of rsync\(cq\&s control, such a mount option + that squishes root to a single user, or mounts a removable drive with generic +! ownership (such as OS X\(cq\&s \(dq\&Ignore ownership on this volume\(dq\& option). + .IP + Beginning in version 2.6.4, multiple \fB\-\-link\-dest\fP directories may be + provided, which will cause rsync to search the list in the order specified +*************** +*** 1789,1797 **** + selected to try to speed up the transfer. + .IP + This option works best when copying into an empty destination hierarchy, as +! rsync treats existing files as definitive (so it never looks in the link-dest + dirs when a destination file already exists), and as malleable (so it might +! change the attributes of a destination file, which affects all the hard-linked + versions). + .IP + Note that if you combine this option with \fB\-\-ignore\-times\fP, rsync will not +--- 1852,1860 ---- + selected to try to speed up the transfer. + .IP + This option works best when copying into an empty destination hierarchy, as +! rsync treats existing files as definitive (so it never looks in the link\-dest + dirs when a destination file already exists), and as malleable (so it might +! change the attributes of a destination file, which affects all the hard\-linked + versions). + .IP + Note that if you combine this option with \fB\-\-ignore\-times\fP, rsync will not +*************** +*** 1803,1816 **** + See also \fB\-\-compare\-dest\fP and \fB\-\-copy\-dest\fP. + .IP + Note that rsync versions prior to 2.6.1 had a bug that could prevent +! \fB\-\-link\-dest\fP from working properly for a non-super-user when \fB\-o\fP was +! specified (or implied by \fB\-a\fP). You can work-around this bug by avoiding + the \fB\-o\fP option when sending to an old rsync. + .IP + .IP "\fB\-z, \-\-compress\fP" + With this option, rsync compresses the file data + as it is sent to the destination machine, which reduces the amount of data +! being transmitted \(em something that is useful over a slow connection. + .IP + Note that this option typically achieves better compression ratios than can + be achieved by using a compressing remote shell or a compressing transport +--- 1866,1879 ---- + See also \fB\-\-compare\-dest\fP and \fB\-\-copy\-dest\fP. + .IP + Note that rsync versions prior to 2.6.1 had a bug that could prevent +! \fB\-\-link\-dest\fP from working properly for a non\-super\-user when \fB\-o\fP was +! specified (or implied by \fB\-a\fP). You can work\-around this bug by avoiding + the \fB\-o\fP option when sending to an old rsync. + .IP + .IP "\fB\-z, \-\-compress\fP" + With this option, rsync compresses the file data + as it is sent to the destination machine, which reduces the amount of data +! being transmitted \-\- something that is useful over a slow connection. + .IP + Note that this option typically achieves better compression ratios than can + be achieved by using a compressing remote shell or a compressing transport +*************** +*** 1822,1828 **** + .IP + .IP "\fB\-\-compress\-level=NUM\fP" + Explicitly set the compression level to use +! (see \fB\-\-compress\fP) instead of letting it default. If NUM is non-zero, + the \fB\-\-compress\fP option is implied. + .IP + .IP "\fB\-\-skip\-compress=LIST\fP" +--- 1885,1891 ---- + .IP + .IP "\fB\-\-compress\-level=NUM\fP" + Explicitly set the compression level to use +! (see \fB\-\-compress\fP) instead of letting it default. If NUM is non\-zero, + the \fB\-\-compress\fP option is implied. + .IP + .IP "\fB\-\-skip\-compress=LIST\fP" +*************** +*** 1832,1844 **** + .IP + You may specify an empty string to indicate that no file should be skipped. + .IP +! Simple character-class matching is supported: each must consist of a list + of letters inside the square brackets (e.g. no special classes, such as +! \(lq[:alpha:]\(rq, are supported). + .IP +! The characters asterisk (*) and question-mark (?) have no special meaning. + .IP +! Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules + matches 2 suffixes): + .IP + .nf +--- 1895,1907 ---- + .IP + You may specify an empty string to indicate that no file should be skipped. + .IP +! Simple character\-class matching is supported: each must consist of a list + of letters inside the square brackets (e.g. no special classes, such as +! \(dq\&[:alpha:]\(dq\&, are supported, and \(cq\&\-\(cq\& has no special meaning). + .IP +! The characters asterisk (*) and question\-mark (?) have no special meaning. + .IP +! Here\(cq\&s an example that specifies 6 suffixes to skip (since 1 of the 5 rules + matches 2 suffixes): + .IP + .nf +*************** +*** 1846,1862 **** + .fi + + .IP +! The default list of suffixes that will not be compressed is this (several +! of these are newly added for 3.0.0): + .IP +! .nf +! gz/zip/z/rpm/deb/iso/bz2/t[gb]z/7z/mp[34]/mov/avi/ogg/jpg/jpeg +! .fi +! + .IP + This list will be replaced by your \fB\-\-skip\-compress\fP list in all but one + situation: a copy from a daemon rsync will add your skipped suffixes to +! its list of non-compressing files (and its list may be configured to a + different default). + .IP + .IP "\fB\-\-numeric\-ids\fP" +--- 1909,1938 ---- + .fi + + .IP +! The default list of suffixes that will not be compressed is this (in this +! version of rsync): + .IP +! \fB7z\fP +! \fBavi\fP +! \fBbz2\fP +! \fBdeb\fP +! \fBgz\fP +! \fBiso\fP +! \fBjpeg\fP +! \fBjpg\fP +! \fBmov\fP +! \fBmp3\fP +! \fBmp4\fP +! \fBogg\fP +! \fBrpm\fP +! \fBtbz\fP +! \fBtgz\fP +! \fBz\fP +! \fBzip\fP + .IP + This list will be replaced by your \fB\-\-skip\-compress\fP list in all but one + situation: a copy from a daemon rsync will add your skipped suffixes to +! its list of non\-compressing files (and its list may be configured to a + different default). + .IP + .IP "\fB\-\-numeric\-ids\fP" +*************** +*** 1872,1879 **** + If a user or group has no name on the source system or it has no match + on the destination system, then the numeric ID + from the source system is used instead. See also the comments on the +! \(lquse chroot\(rq setting in the rsyncd.conf manpage for information on how +! the chroot setting affects rsync's ability to look up the names of the + users and groups and what you can do about it. + .IP + .IP "\fB\-\-timeout=TIMEOUT\fP" +--- 1948,1955 ---- + If a user or group has no name on the source system or it has no match + on the destination system, then the numeric ID + from the source system is used instead. See also the comments on the +! \(dq\&use chroot\(dq\& setting in the rsyncd.conf manpage for information on how +! the chroot setting affects rsync\(cq\&s ability to look up the names of the + users and groups and what you can do about it. + .IP + .IP "\fB\-\-timeout=TIMEOUT\fP" +*************** +*** 1895,1901 **** + .IP "\fB\-\-port=PORT\fP" + This specifies an alternate TCP port number to use + rather than the default of 873. This is only needed if you are using the +! double-colon (::) syntax to connect with an rsync daemon (since the URL + syntax has a way to specify the port as a part of the URL). See also this + option in the \fB\-\-daemon\fP mode section. + .IP +--- 1971,1977 ---- + .IP "\fB\-\-port=PORT\fP" + This specifies an alternate TCP port number to use + rather than the default of 873. This is only needed if you are using the +! double\-colon (::) syntax to connect with an rsync daemon (since the URL + syntax has a way to specify the port as a part of the URL). See also this + option in the \fB\-\-daemon\fP mode section. + .IP +*************** +*** 1915,1935 **** + This tells rsync to use blocking I/O when launching + a remote shell transport. If the remote shell is either rsh or remsh, + rsync defaults to using +! blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that +! ssh prefers non-blocking I/O.) + .IP + .IP "\fB\-i, \-\-itemize\-changes\fP" + Requests a simple itemized list of the + changes that are being made to each file, including attribute changes. +! This is exactly the same as specifying \fB\-\-out\-format='%i %n%L'\fP. + If you repeat the option, unchanged files will also be output, but only + if the receiving rsync is at least version 2.6.7 (you can use \fB\-vv\fP + with older versions of rsync, but that also turns on the output of other + verbose messages). + .IP +! The \(lq%i\(rq escape has a cryptic output that is 11 letters long. The general + format is like the string \fBYXcstpoguax\fP, where \fBY\fP is replaced by the +! type of update being done, \fBX\fP is replaced by the file-type, and the + other letters represent attributes that may be output if they are being + modified. + .IP +--- 1991,2011 ---- + This tells rsync to use blocking I/O when launching + a remote shell transport. If the remote shell is either rsh or remsh, + rsync defaults to using +! blocking I/O, otherwise it defaults to using non\-blocking I/O. (Note that +! ssh prefers non\-blocking I/O.) + .IP + .IP "\fB\-i, \-\-itemize\-changes\fP" + Requests a simple itemized list of the + changes that are being made to each file, including attribute changes. +! This is exactly the same as specifying \fB\-\-out\-format='\&%i %n%L'\&\fP. + If you repeat the option, unchanged files will also be output, but only + if the receiving rsync is at least version 2.6.7 (you can use \fB\-vv\fP + with older versions of rsync, but that also turns on the output of other + verbose messages). + .IP +! The \(dq\&%i\(dq\& escape has a cryptic output that is 11 letters long. The general + format is like the string \fBYXcstpoguax\fP, where \fBY\fP is replaced by the +! type of update being done, \fBX\fP is replaced by the file\-type, and the + other letters represent attributes that may be output if they are being + modified. + .IP +*************** +*** 1952,1972 **** + A \fB.\fP means that the item is not being updated (though it might + have attributes that are being modified). + .IP o +! A \fB*\fP means that the rest of the itemized-output area contains +! a message (e.g. \(lqdeleting\(rq). + .RE + + .IP +! The file-types that replace the \fBX\fP are: \fBf\fP for a file, a \fBd\fP for a + directory, an \fBL\fP for a symlink, a \fBD\fP for a device, and a \fBS\fP for a + special file (e.g. named sockets and fifos). + .IP + The other letters in the string above are the actual letters that + will be output if the associated attribute for the item is being updated or +! a \(lq.\(rq for no change. Three exceptions to this are: (1) a newly created +! item replaces each letter with a \(lq+\(rq, (2) an identical item replaces the + dots with spaces, and (3) an unknown attribute replaces each letter with +! a \(lq?\(rq (this can happen when talking to an older rsync). + .IP + The attribute that is associated with each letter is as follows: + .IP +--- 2028,2048 ---- + A \fB.\fP means that the item is not being updated (though it might + have attributes that are being modified). + .IP o +! A \fB*\fP means that the rest of the itemized\-output area contains +! a message (e.g. \(dq\&deleting\(dq\&). + .RE + + .IP +! The file\-types that replace the \fBX\fP are: \fBf\fP for a file, a \fBd\fP for a + directory, an \fBL\fP for a symlink, a \fBD\fP for a device, and a \fBS\fP for a + special file (e.g. named sockets and fifos). + .IP + The other letters in the string above are the actual letters that + will be output if the associated attribute for the item is being updated or +! a \(dq\&.\(dq\& for no change. Three exceptions to this are: (1) a newly created +! item replaces each letter with a \(dq\&+\(dq\&, (2) an identical item replaces the + dots with spaces, and (3) an unknown attribute replaces each letter with +! a \(dq\&?\(dq\& (this can happen when talking to an older rsync). + .IP + The attribute that is associated with each letter is as follows: + .IP +*************** +*** 1976,2002 **** + (requires \fB\-\-checksum\fP) or that a symlink, device, or special file has + a changed value. + Note that if you are sending files to an rsync prior to 3.0.1, this +! change flag will be present only for checksum-differing regular files. + .IP o + A \fBs\fP means the size of a regular file is different and will be updated + by the file transfer. + .IP o + A \fBt\fP means the modification time is different and is being updated +! to the sender's value (requires \fB\-\-times\fP). An alternate value of \fBT\fP + means that the modification time will be set to the transfer time, which happens + when a file/symlink/device is updated without \fB\-\-times\fP and when a +! symlink is changed and the receiver can't set its time. + (Note: when using an rsync 3.0.0 client, you might see the \fBs\fP flag combined +! with \fBt\fP instead of the proper \fBT\fP flag for this time-setting failure.) + .IP o + A \fBp\fP means the permissions are different and are being updated to +! the sender's value (requires \fB\-\-perms\fP). + .IP o + An \fBo\fP means the owner is different and is being updated to the +! sender's value (requires \fB\-\-owner\fP and super-user privileges). + .IP o + A \fBg\fP means the group is different and is being updated to the +! sender's value (requires \fB\-\-group\fP and the authority to set the group). + .IP o + The \fBu\fP slot is reserved for future use. + .IP o +--- 2052,2078 ---- + (requires \fB\-\-checksum\fP) or that a symlink, device, or special file has + a changed value. + Note that if you are sending files to an rsync prior to 3.0.1, this +! change flag will be present only for checksum\-differing regular files. + .IP o + A \fBs\fP means the size of a regular file is different and will be updated + by the file transfer. + .IP o + A \fBt\fP means the modification time is different and is being updated +! to the sender\(cq\&s value (requires \fB\-\-times\fP). An alternate value of \fBT\fP + means that the modification time will be set to the transfer time, which happens + when a file/symlink/device is updated without \fB\-\-times\fP and when a +! symlink is changed and the receiver can\(cq\&t set its time. + (Note: when using an rsync 3.0.0 client, you might see the \fBs\fP flag combined +! with \fBt\fP instead of the proper \fBT\fP flag for this time\-setting failure.) + .IP o + A \fBp\fP means the permissions are different and are being updated to +! the sender\(cq\&s value (requires \fB\-\-perms\fP). + .IP o + An \fBo\fP means the owner is different and is being updated to the +! sender\(cq\&s value (requires \fB\-\-owner\fP and super\-user privileges). + .IP o + A \fBg\fP means the group is different and is being updated to the +! sender\(cq\&s value (requires \fB\-\-group\fP and the authority to set the group). + .IP o + The \fBu\fP slot is reserved for future use. + .IP o +*************** +*** 2006,2055 **** + .RE + + .IP +! One other output is possible: when deleting files, the \(lq%i\(rq will output +! the string \(lq*deleting\(rq for each item that is being removed (assuming that + you are talking to a recent enough rsync that it logs deletions instead of + outputting them as a verbose message). + .IP + .IP "\fB\-\-out\-format=FORMAT\fP" + This allows you to specify exactly what the +! rsync client outputs to the user on a per-update basis. The format is a +! text string containing embedded single-character escape sequences prefixed +! with a percent (%) character. A default format of \(lq%n%L\(rq is assumed if + \fB\-v\fP is specified (which reports the name + of the file and, if the item is a link, where it points). For a full list +! of the possible escape characters, see the \(lqlog format\(rq setting in the + rsyncd.conf manpage. + .IP + Specifying the \fB\-\-out\-format\fP option + will mention each file, dir, etc. that gets updated in a significant + way (a transferred file, a recreated symlink/device, or a touched +! directory). In addition, if the itemize-changes escape (%i) is included in + the string (e.g. if the \fB\-\-itemize\-changes\fP option was used), the logging + of names increases to mention any item that is changed in any way (as long + as the receiving side is at least 2.6.4). See the \fB\-\-itemize\-changes\fP +! option for a description of the output of \(lq%i\(rq. + .IP +! Rsync will output the out-format string prior to a file's transfer unless +! one of the transfer-statistic escapes is requested, in which case the +! logging is done at the end of the file's transfer. When this late logging + is in effect and \fB\-\-progress\fP is also specified, rsync will also output + the name of the file being transferred prior to its progress information +! (followed, of course, by the out-format output). + .IP + .IP "\fB\-\-log\-file=FILE\fP" + This option causes rsync to log what it is doing + to a file. This is similar to the logging that a daemon does, but can be +! requested for the client side and/or the server side of a non-daemon + transfer. If specified as a client option, transfer logging will be +! enabled with a default format of \(lq%i %n%L\(rq. See the \fB\-\-log\-file\-format\fP + option if you wish to override this. + .IP +! Here's a example command that requests the remote side to log what is + happening: + .IP + .nf +! rsync \-av \-\-rsync\-path="rsync \-\-log\-file=/tmp/rlog" src/ dest/ + .fi + + .IP +--- 2082,2131 ---- + .RE + + .IP +! One other output is possible: when deleting files, the \(dq\&%i\(dq\& will output +! the string \(dq\&*deleting\(dq\& for each item that is being removed (assuming that + you are talking to a recent enough rsync that it logs deletions instead of + outputting them as a verbose message). + .IP + .IP "\fB\-\-out\-format=FORMAT\fP" + This allows you to specify exactly what the +! rsync client outputs to the user on a per\-update basis. The format is a +! text string containing embedded single\-character escape sequences prefixed +! with a percent (%) character. A default format of \(dq\&%n%L\(dq\& is assumed if + \fB\-v\fP is specified (which reports the name + of the file and, if the item is a link, where it points). For a full list +! of the possible escape characters, see the \(dq\&log format\(dq\& setting in the + rsyncd.conf manpage. + .IP + Specifying the \fB\-\-out\-format\fP option + will mention each file, dir, etc. that gets updated in a significant + way (a transferred file, a recreated symlink/device, or a touched +! directory). In addition, if the itemize\-changes escape (%i) is included in + the string (e.g. if the \fB\-\-itemize\-changes\fP option was used), the logging + of names increases to mention any item that is changed in any way (as long + as the receiving side is at least 2.6.4). See the \fB\-\-itemize\-changes\fP +! option for a description of the output of \(dq\&%i\(dq\&. + .IP +! Rsync will output the out\-format string prior to a file\(cq\&s transfer unless +! one of the transfer\-statistic escapes is requested, in which case the +! logging is done at the end of the file\(cq\&s transfer. When this late logging + is in effect and \fB\-\-progress\fP is also specified, rsync will also output + the name of the file being transferred prior to its progress information +! (followed, of course, by the out\-format output). + .IP + .IP "\fB\-\-log\-file=FILE\fP" + This option causes rsync to log what it is doing + to a file. This is similar to the logging that a daemon does, but can be +! requested for the client side and/or the server side of a non\-daemon + transfer. If specified as a client option, transfer logging will be +! enabled with a default format of \(dq\&%i %n%L\(dq\&. See the \fB\-\-log\-file\-format\fP + option if you wish to override this. + .IP +! Here\(cq\&s a example command that requests the remote side to log what is + happening: + .IP + .nf +! rsync \-av \-\-rsync\-path=\(dq\&rsync \-\-log\-file=/tmp/rlog\(dq\& src/ dest/ + .fi + + .IP +*************** +*** 2058,2085 **** + .IP + .IP "\fB\-\-log\-file\-format=FORMAT\fP" + This allows you to specify exactly what +! per-update logging is put into the file specified by the \fB\-\-log\-file\fP option + (which must also be specified for this option to have any effect). If you + specify an empty string, updated files will not be mentioned in the log file. +! For a list of the possible escape characters, see the \(lqlog format\(rq setting + in the rsyncd.conf manpage. + .IP + The default FORMAT used if \fB\-\-log\-file\fP is specified and this option is not +! is '%i %n%L'. + .IP + .IP "\fB\-\-stats\fP" + This tells rsync to print a verbose set of statistics +! on the file transfer, allowing you to tell how effective rsync's delta-transfer + algorithm is for your data. + .IP + The current statistics are as follows: + .RS + .IP o +! \fBNumber of files\fP is the count of all \(lqfiles\(rq (in the generic + sense), which includes directories, symlinks, etc. + .IP o + \fBNumber of files transferred\fP is the count of normal files that +! were updated via rsync's delta-transfer algorithm, which does not include created + dirs, symlinks, etc. + .IP o + \fBTotal file size\fP is the total sum of all file sizes in the transfer. +--- 2134,2161 ---- + .IP + .IP "\fB\-\-log\-file\-format=FORMAT\fP" + This allows you to specify exactly what +! per\-update logging is put into the file specified by the \fB\-\-log\-file\fP option + (which must also be specified for this option to have any effect). If you + specify an empty string, updated files will not be mentioned in the log file. +! For a list of the possible escape characters, see the \(dq\&log format\(dq\& setting + in the rsyncd.conf manpage. + .IP + The default FORMAT used if \fB\-\-log\-file\fP is specified and this option is not +! is \(cq\&%i %n%L\(cq\&. + .IP + .IP "\fB\-\-stats\fP" + This tells rsync to print a verbose set of statistics +! on the file transfer, allowing you to tell how effective rsync\(cq\&s delta\-transfer + algorithm is for your data. + .IP + The current statistics are as follows: + .RS + .IP o +! \fBNumber of files\fP is the count of all \(dq\&files\(dq\& (in the generic + sense), which includes directories, symlinks, etc. + .IP o + \fBNumber of files transferred\fP is the count of normal files that +! were updated via rsync\(cq\&s delta\-transfer algorithm, which does not include created + dirs, symlinks, etc. + .IP o + \fBTotal file size\fP is the total sum of all file sizes in the transfer. +*************** +*** 2089,2102 **** + \fBTotal transferred file size\fP is the total sum of all files sizes + for just the transferred files. + .IP o +! \fBLiteral data\fP is how much unmatched file-update data we had to + send to the receiver for it to recreate the updated files. + .IP o + \fBMatched data\fP is how much data the receiver got locally when + recreating the updated files. + .IP o +! \fBFile list size\fP is how big the file-list data was when the sender +! sent it to the receiver. This is smaller than the in-memory size for the + file list due to some compressing of duplicated data when rsync sends the + list. + .IP o +--- 2165,2178 ---- + \fBTotal transferred file size\fP is the total sum of all files sizes + for just the transferred files. + .IP o +! \fBLiteral data\fP is how much unmatched file\-update data we had to + send to the receiver for it to recreate the updated files. + .IP o + \fBMatched data\fP is how much data the receiver got locally when + recreating the updated files. + .IP o +! \fBFile list size\fP is how big the file\-list data was when the sender +! sent it to the receiver. This is smaller than the in\-memory size for the + file list due to some compressing of duplicated data when rsync sends the + list. + .IP o +*************** +*** 2110,2136 **** + \fBTotal bytes sent\fP is the count of all the bytes that rsync sent + from the client side to the server side. + .IP o +! \fBTotal bytes received\fP is the count of all non-message bytes that +! rsync received by the client side from the server side. \(lqNon-message\(rq +! bytes means that we don't count the bytes for a verbose message that the + server sent to us, which makes the stats more consistent. + .RE + + .IP + .IP "\fB\-8, \-\-8\-bit\-output\fP" +! This tells rsync to leave all high-bit characters +! unescaped in the output instead of trying to test them to see if they're + valid in the current locale and escaping the invalid ones. All control +! characters (but never tabs) are always escaped, regardless of this option's + setting. + .IP + The escape idiom that started in 2.6.7 is to output a literal backslash (\e) + and a hash (#), followed by exactly 3 octal digits. For example, a newline +! would output as \(lq\e#012\(rq. A literal backslash that is in a filename is not + escaped unless it is followed by a hash and 3 digits (0\-9). + .IP + .IP "\fB\-h, \-\-human\-readable\fP" +! Output numbers in a more human-readable format. + This makes big numbers output using larger units, with a K, M, or G suffix. If + this option was specified once, these units are K (1000), M (1000*1000), and + G (1000*1000*1000); if the option is repeated, the units are powers of 1024 +--- 2186,2212 ---- + \fBTotal bytes sent\fP is the count of all the bytes that rsync sent + from the client side to the server side. + .IP o +! \fBTotal bytes received\fP is the count of all non\-message bytes that +! rsync received by the client side from the server side. \(dq\&Non\-message\(dq\& +! bytes means that we don\(cq\&t count the bytes for a verbose message that the + server sent to us, which makes the stats more consistent. + .RE + + .IP + .IP "\fB\-8, \-\-8\-bit\-output\fP" +! This tells rsync to leave all high\-bit characters +! unescaped in the output instead of trying to test them to see if they\(cq\&re + valid in the current locale and escaping the invalid ones. All control +! characters (but never tabs) are always escaped, regardless of this option\(cq\&s + setting. + .IP + The escape idiom that started in 2.6.7 is to output a literal backslash (\e) + and a hash (#), followed by exactly 3 octal digits. For example, a newline +! would output as \(dq\&\e#012\(dq\&. A literal backslash that is in a filename is not + escaped unless it is followed by a hash and 3 digits (0\-9). + .IP + .IP "\fB\-h, \-\-human\-readable\fP" +! Output numbers in a more human\-readable format. + This makes big numbers output using larger units, with a K, M, or G suffix. If + this option was specified once, these units are K (1000), M (1000*1000), and + G (1000*1000*1000); if the option is repeated, the units are powers of 1024 +*************** +*** 2151,2189 **** + dir as data to speed up the resumption of the transfer and then delete it + after it has served its purpose. + .IP +! Note that if \fB\-\-whole\-file\fP is specified (or implied), any partial-dir + file that is found for a file that is being updated will simply be removed + (since +! rsync is sending files without using rsync's delta-transfer algorithm). + .IP +! Rsync will create the \fIDIR\fP if it is missing (just the last dir \(em not + the whole path). This makes it easy to use a relative path (such as +! \(lq\fB\-\-partial\-dir=.rsync\-partial\fP\(rq) to have rsync create the +! partial-directory in the destination file's directory when needed, and then + remove it again when the partial file is deleted. + .IP +! If the partial-dir value is not an absolute path, rsync will add an exclude + rule at the end of all your existing excludes. This will prevent the +! sending of any partial-dir files that may exist on the sending side, and +! will also prevent the untimely deletion of partial-dir items on the + receiving side. An example: the above \fB\-\-partial\-dir\fP option would add +! the equivalent of \(lq\fB\-f '\-p .rsync\-partial/'\fP\(rq at the end of any other + filter rules. + .IP + If you are supplying your own exclude rules, you may need to add your own +! exclude/hide/protect rule for the partial-dir because (1) the auto-added + rule may be ineffective at the end of your other rules, or (2) you may wish +! to override rsync's exclude choice. For instance, if you want to make +! rsync clean-up any left-over partial-dirs that may be lying around, you +! should specify \fB\-\-delete\-after\fP and add a \(lqrisk\(rq filter rule, e.g. +! \fB\-f 'R .rsync\-partial/'\fP. (Avoid using \fB\-\-delete\-before\fP or +! \fB\-\-delete\-during\fP unless you don't need rsync to use any of the +! left-over partial-dir data during the current run.) + .IP + IMPORTANT: the \fB\-\-partial\-dir\fP should not be writable by other users or it +! is a security risk. E.g. AVOID \(lq/tmp\(rq. + .IP +! You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment + variable. Setting this in the environment does not force \fB\-\-partial\fP to be + enabled, but rather it affects where partial files go when \fB\-\-partial\fP is + specified. For instance, instead of using \fB\-\-partial\-dir=.rsync\-tmp\fP +--- 2227,2265 ---- + dir as data to speed up the resumption of the transfer and then delete it + after it has served its purpose. + .IP +! Note that if \fB\-\-whole\-file\fP is specified (or implied), any partial\-dir + file that is found for a file that is being updated will simply be removed + (since +! rsync is sending files without using rsync\(cq\&s delta\-transfer algorithm). + .IP +! Rsync will create the \fIDIR\fP if it is missing (just the last dir \-\- not + the whole path). This makes it easy to use a relative path (such as +! \(dq\&\fB\-\-partial\-dir=.rsync\-partial\fP\(dq\&) to have rsync create the +! partial\-directory in the destination file\(cq\&s directory when needed, and then + remove it again when the partial file is deleted. + .IP +! If the partial\-dir value is not an absolute path, rsync will add an exclude + rule at the end of all your existing excludes. This will prevent the +! sending of any partial\-dir files that may exist on the sending side, and +! will also prevent the untimely deletion of partial\-dir items on the + receiving side. An example: the above \fB\-\-partial\-dir\fP option would add +! the equivalent of \(dq\&\fB\-f '\&\-p .rsync\-partial/'\&\fP\(dq\& at the end of any other + filter rules. + .IP + If you are supplying your own exclude rules, you may need to add your own +! exclude/hide/protect rule for the partial\-dir because (1) the auto\-added + rule may be ineffective at the end of your other rules, or (2) you may wish +! to override rsync\(cq\&s exclude choice. For instance, if you want to make +! rsync clean\-up any left\-over partial\-dirs that may be lying around, you +! should specify \fB\-\-delete\-after\fP and add a \(dq\&risk\(dq\& filter rule, e.g. +! \fB\-f '\&R .rsync\-partial/'\&\fP. (Avoid using \fB\-\-delete\-before\fP or +! \fB\-\-delete\-during\fP unless you don\(cq\&t need rsync to use any of the +! left\-over partial\-dir data during the current run.) + .IP + IMPORTANT: the \fB\-\-partial\-dir\fP should not be writable by other users or it +! is a security risk. E.g. AVOID \(dq\&/tmp\(dq\&. + .IP +! You can also set the partial\-dir value the RSYNC_PARTIAL_DIR environment + variable. Setting this in the environment does not force \fB\-\-partial\fP to be + enabled, but rather it affects where partial files go when \fB\-\-partial\fP is + specified. For instance, instead of using \fB\-\-partial\-dir=.rsync\-tmp\fP +*************** +*** 2194,2200 **** + specified (since \fB\-\-inplace\fP conflicts with \fB\-\-partial\-dir\fP), and (2) when + \fB\-\-delay\-updates\fP was specified (see below). + .IP +! For the purposes of the daemon-config's \(lqrefuse options\(rq setting, + \fB\-\-partial\-dir\fP does \fInot\fP imply \fB\-\-partial\fP. This is so that a + refusal of the \fB\-\-partial\fP option can be used to disallow the overwriting + of destination files with a partial transfer, while still allowing the +--- 2270,2276 ---- + specified (since \fB\-\-inplace\fP conflicts with \fB\-\-partial\-dir\fP), and (2) when + \fB\-\-delay\-updates\fP was specified (see below). + .IP +! For the purposes of the daemon\-config\(cq\&s \(dq\&refuse options\(dq\& setting, + \fB\-\-partial\-dir\fP does \fInot\fP imply \fB\-\-partial\fP. This is so that a + refusal of the \fB\-\-partial\fP option can be used to disallow the overwriting + of destination files with a partial transfer, while still allowing the +*************** +*** 2205,2216 **** + updated file into a holding directory until the end of the + transfer, at which time all the files are renamed into place in rapid + succession. This attempts to make the updating of the files a little more +! atomic. By default the files are placed into a directory named \(lq.~tmp~\(rq in +! each file's destination directory, but if you've specified the + \fB\-\-partial\-dir\fP option, that directory will be used instead. See the + comments in the \fB\-\-partial\-dir\fP section for a discussion of how this +! \(lq.~tmp~\(rq dir will be excluded from the transfer, and what you can do if +! you want rsync to cleanup old \(lq.~tmp~\(rq dirs that might be lying around. + Conflicts with \fB\-\-inplace\fP and \fB\-\-append\fP. + .IP + This option uses more memory on the receiving side (one bit per file +--- 2281,2292 ---- + updated file into a holding directory until the end of the + transfer, at which time all the files are renamed into place in rapid + succession. This attempts to make the updating of the files a little more +! atomic. By default the files are placed into a directory named \(dq\&.~tmp~\(dq\& in +! each file\(cq\&s destination directory, but if you\(cq\&ve specified the + \fB\-\-partial\-dir\fP option, that directory will be used instead. See the + comments in the \fB\-\-partial\-dir\fP section for a discussion of how this +! \(dq\&.~tmp~\(dq\& dir will be excluded from the transfer, and what you can do if +! you want rsync to cleanup old \(dq\&.~tmp~\(dq\& dirs that might be lying around. + Conflicts with \fB\-\-inplace\fP and \fB\-\-append\fP. + .IP + This option uses more memory on the receiving side (one bit per file +*************** +*** 2222,2237 **** + the updated files will be put into a single directory if the path is + absolute) + and (2) there are no mount points in the hierarchy (since the +! delayed updates will fail if they can't be renamed into place). + .IP +! See also the \(lqatomic-rsync\(rq perl script in the \(lqsupport\(rq subdir for an + update algorithm that is even more atomic (it uses \fB\-\-link\-dest\fP and a + parallel hierarchy of files). + .IP + .IP "\fB\-m, \-\-prune\-empty\-dirs\fP" + This option tells the receiving rsync to get +! rid of empty directories from the file-list, including nested directories +! that have no non-directory children. This is useful for avoiding the + creation of a bunch of useless directories when the sending rsync is + recursively scanning a hierarchy of files using include/exclude/filter + rules. +--- 2298,2313 ---- + the updated files will be put into a single directory if the path is + absolute) + and (2) there are no mount points in the hierarchy (since the +! delayed updates will fail if they can\(cq\&t be renamed into place). + .IP +! See also the \(dq\&atomic\-rsync\(dq\& perl script in the \(dq\&support\(dq\& subdir for an + update algorithm that is even more atomic (it uses \fB\-\-link\-dest\fP and a + parallel hierarchy of files). + .IP + .IP "\fB\-m, \-\-prune\-empty\-dirs\fP" + This option tells the receiving rsync to get +! rid of empty directories from the file\-list, including nested directories +! that have no non\-directory children. This is useful for avoiding the + creation of a bunch of useless directories when the sending rsync is + recursively scanning a hierarchy of files using include/exclude/filter + rules. +*************** +*** 2240,2280 **** + not affect what goes into the file list, and thus does not leave directories + empty, even if none of the files in a directory match the transfer rule. + .IP +! Because the file-list is actually being pruned, this option also affects + what directories get deleted when a delete is active. However, keep in + mind that excluded files and directories can prevent existing items from + being deleted due to an exclude both hiding source files and protecting +! destination files. See the perishable filter-rule option for how to avoid + this. + .IP +! You can prevent the pruning of certain empty directories from the file-list +! by using a global \(lqprotect\(rq filter. For instance, this option would ensure +! that the directory \(lqemptydir\(rq was kept in the file-list: + .IP + .RS +! \-\-filter 'protect emptydir/' + .RE + + .IP +! Here's an example that copies all .pdf files in a hierarchy, only creating + the necessary destination directories to hold the .pdf files, and ensures + that any superfluous files and directories in the destination are removed +! (note the hide filter of non-directories being used instead of an exclude): + .IP + .RS +! rsync \-avm \-\-del \-\-include='*.pdf' \-f 'hide,! */' src/ dest + .RE + + .IP +! If you didn't want to remove superfluous destination files, the more +! time-honored options of \(lq\fB\-\-include='*/' \-\-exclude='*'\fP\(rq would work fine +! in place of the hide-filter (if that is more natural to you). + .IP + .IP "\fB\-\-progress\fP" + This option tells rsync to print information + showing the progress of the transfer. This gives a bored user + something to watch. +! Implies \fB\-\-verbose\fP if it wasn't already specified. + .IP + While rsync is transferring a regular file, it updates a progress line that + looks like this: +--- 2316,2356 ---- + not affect what goes into the file list, and thus does not leave directories + empty, even if none of the files in a directory match the transfer rule. + .IP +! Because the file\-list is actually being pruned, this option also affects + what directories get deleted when a delete is active. However, keep in + mind that excluded files and directories can prevent existing items from + being deleted due to an exclude both hiding source files and protecting +! destination files. See the perishable filter\-rule option for how to avoid + this. + .IP +! You can prevent the pruning of certain empty directories from the file\-list +! by using a global \(dq\&protect\(dq\& filter. For instance, this option would ensure +! that the directory \(dq\&emptydir\(dq\& was kept in the file\-list: + .IP + .RS +! \-\-filter \(cq\&protect emptydir/\(cq\& + .RE + + .IP +! Here\(cq\&s an example that copies all .pdf files in a hierarchy, only creating + the necessary destination directories to hold the .pdf files, and ensures + that any superfluous files and directories in the destination are removed +! (note the hide filter of non\-directories being used instead of an exclude): + .IP + .RS +! rsync \-avm \-\-del \-\-include=\(cq\&*.pdf\(cq\& \-f \(cq\&hide,! */\(cq\& src/ dest + .RE + + .IP +! If you didn\(cq\&t want to remove superfluous destination files, the more +! time\-honored options of \(dq\&\fB\-\-include='\&*/'\& \-\-exclude='\&*'\&\fP\(dq\& would work fine +! in place of the hide\-filter (if that is more natural to you). + .IP + .IP "\fB\-\-progress\fP" + This option tells rsync to print information + showing the progress of the transfer. This gives a bored user + something to watch. +! Implies \fB\-\-verbose\fP if it wasn\(cq\&t already specified. + .IP + While rsync is transferring a regular file, it updates a progress line that + looks like this: +*************** +*** 2285,2296 **** + + .IP + In this example, the receiver has reconstructed 782448 bytes or 63% of the +! sender's file, which is being reconstructed at a rate of 110.64 kilobytes + per second, and the transfer will finish in 4 seconds if the current rate + is maintained until the end. + .IP +! These statistics can be misleading if rsync's delta-transfer algorithm is +! in use. For example, if the sender's file consists of the basis file + followed by additional data, the reported rate will probably drop + dramatically when the receiver gets to the literal data, and the transfer + will probably take much longer to finish than the receiver estimated as it +--- 2361,2372 ---- + + .IP + In this example, the receiver has reconstructed 782448 bytes or 63% of the +! sender\(cq\&s file, which is being reconstructed at a rate of 110.64 kilobytes + per second, and the transfer will finish in 4 seconds if the current rate + is maintained until the end. + .IP +! These statistics can be misleading if rsync\(cq\&s delta\-transfer algorithm is +! in use. For example, if the sender\(cq\&s file consists of the basis file + followed by additional data, the reported rate will probably drop + dramatically when the receiver gets to the literal data, and the transfer + will probably take much longer to finish than the receiver estimated as it +*************** +*** 2300,2306 **** + summary line that looks like this: + .IP + .nf +! 1238099 100% 146.38kB/s 0:00:08 (xfer#5, to-check=169/396) + .fi + + .IP +--- 2376,2382 ---- + summary line that looks like this: + .IP + .nf +! 1238099 100% 146.38kB/s 0:00:08 (xfer#5, to\-check=169/396) + .fi + + .IP +*************** +*** 2308,2315 **** + of transfer for the whole file was 146.38 kilobytes per second over the 8 + seconds that it took to complete, it was the 5th transfer of a regular file + during the current rsync session, and there are 169 more files for the +! receiver to check (to see if they are up-to-date or not) remaining out of +! the 396 total files in the file-list. + .IP + .IP "\fB\-P\fP" + The \fB\-P\fP option is equivalent to \fB\-\-partial\fP \fB\-\-progress\fP. Its +--- 2384,2391 ---- + of transfer for the whole file was 146.38 kilobytes per second over the 8 + seconds that it took to complete, it was the 5th transfer of a regular file + during the current rsync session, and there are 169 more files for the +! receiver to check (to see if they are up\-to\-date or not) remaining out of +! the 396 total files in the file\-list. + .IP + .IP "\fB\-P\fP" + The \fB\-P\fP option is equivalent to \fB\-\-partial\fP \fB\-\-progress\fP. Its +*************** +*** 2319,2331 **** + .IP "\fB\-\-password\-file\fP" + This option allows you to provide a password in a + file for accessing an rsync daemon. The file must not be world readable. +! It should contain just the password as a single line. + .IP + This option does not supply a password to a remote shell transport such as +! ssh; to learn how to do that, consult the remote shell's documentation. + When accessing an rsync daemon using a remote shell as the transport, this + option only comes into effect after the remote shell finishes its +! authentication (i.e. if you have also specified a password in the daemon's + config file). + .IP + .IP "\fB\-\-list\-only\fP" +--- 2395,2408 ---- + .IP "\fB\-\-password\-file\fP" + This option allows you to provide a password in a + file for accessing an rsync daemon. The file must not be world readable. +! It should contain just the password as the first line of the file (all +! other lines are ignored). + .IP + This option does not supply a password to a remote shell transport such as +! ssh; to learn how to do that, consult the remote shell\(cq\&s documentation. + When accessing an rsync daemon using a remote shell as the transport, this + option only comes into effect after the remote shell finishes its +! authentication (i.e. if you have also specified a password in the daemon\(cq\&s + config file). + .IP + .IP "\fB\-\-list\-only\fP" +*************** +*** 2333,2341 **** + instead of transferred. This option is inferred if there is a single source + arg and no destination specified, so its main uses are: (1) to turn a copy + command that includes a +! destination arg into a file-listing command, or (2) to be able to specify + more than one source arg (note: be sure to include the destination). +! Caution: keep in mind that a source arg with a wild-card is expanded by the + shell into multiple args, so it is never safe to try to list such an arg + without using this option. For example: + .IP +--- 2410,2418 ---- + instead of transferred. This option is inferred if there is a single source + arg and no destination specified, so its main uses are: (1) to turn a copy + command that includes a +! destination arg into a file\-listing command, or (2) to be able to specify + more than one source arg (note: be sure to include the destination). +! Caution: keep in mind that a source arg with a wild\-card is expanded by the + shell into multiple args, so it is never safe to try to list such an arg + without using this option. For example: + .IP +*************** +*** 2346,2356 **** + .IP + Compatibility note: when requesting a remote listing of files from an rsync + that is version 2.6.3 or older, you may encounter an error if you ask for a +! non-recursive listing. This is because a file listing implies the \fB\-\-dirs\fP +! option w/o \fB\-\-recursive\fP, and older rsyncs don't have that option. To +! avoid this problem, either specify the \fB\-\-no\-dirs\fP option (if you don't +! need to expand a directory's content), or turn on recursion and exclude +! the content of subdirectories: \fB\-r \-\-exclude='/*/*'\fP. + .IP + .IP "\fB\-\-bwlimit=KBPS\fP" + This option allows you to specify a maximum +--- 2423,2433 ---- + .IP + Compatibility note: when requesting a remote listing of files from an rsync + that is version 2.6.3 or older, you may encounter an error if you ask for a +! non\-recursive listing. This is because a file listing implies the \fB\-\-dirs\fP +! option w/o \fB\-\-recursive\fP, and older rsyncs don\(cq\&t have that option. To +! avoid this problem, either specify the \fB\-\-no\-dirs\fP option (if you don\(cq\&t +! need to expand a directory\(cq\&s content), or turn on recursion and exclude +! the content of subdirectories: \fB\-r \-\-exclude='\&/*/*'\&\fP. + .IP + .IP "\fB\-\-bwlimit=KBPS\fP" + This option allows you to specify a maximum +*************** +*** 2363,2369 **** + .IP + .IP "\fB\-\-write\-batch=FILE\fP" + Record a file that can later be applied to +! another identical destination with \fB\-\-read\-batch\fP. See the \(lqBATCH MODE\(rq + section for details, and also the \fB\-\-only\-write\-batch\fP option. + .IP + .IP "\fB\-\-only\-write\-batch=FILE\fP" +--- 2440,2446 ---- + .IP + .IP "\fB\-\-write\-batch=FILE\fP" + Record a file that can later be applied to +! another identical destination with \fB\-\-read\-batch\fP. See the \(dq\&BATCH MODE\(dq\& + section for details, and also the \fB\-\-only\-write\-batch\fP option. + .IP + .IP "\fB\-\-only\-write\-batch=FILE\fP" +*************** +*** 2375,2394 **** + Note that you can feel free to write the batch directly to some portable + media: if this media fills to capacity before the end of the transfer, you + can just apply that partial transfer to the destination and repeat the +! whole process to get the rest of the changes (as long as you don't mind a +! partially updated destination system while the multi-update cycle is + happening). + .IP + Also note that you only save bandwidth when pushing changes to a remote + system because this allows the batched data to be diverted from the sender + into the batch file without having to flow over the wire to the receiver +! (when pulling, the sender is remote, and thus can't write the batch). + .IP + .IP "\fB\-\-read\-batch=FILE\fP" + Apply all of the changes stored in FILE, a + file previously generated by \fB\-\-write\-batch\fP. + If \fIFILE\fP is \fB\-\fP, the batch data will be read from standard input. +! See the \(lqBATCH MODE\(rq section for details. + .IP + .IP "\fB\-\-protocol=NUM\fP" + Force an older protocol version to be used. This +--- 2452,2471 ---- + Note that you can feel free to write the batch directly to some portable + media: if this media fills to capacity before the end of the transfer, you + can just apply that partial transfer to the destination and repeat the +! whole process to get the rest of the changes (as long as you don\(cq\&t mind a +! partially updated destination system while the multi\-update cycle is + happening). + .IP + Also note that you only save bandwidth when pushing changes to a remote + system because this allows the batched data to be diverted from the sender + into the batch file without having to flow over the wire to the receiver +! (when pulling, the sender is remote, and thus can\(cq\&t write the batch). + .IP + .IP "\fB\-\-read\-batch=FILE\fP" + Apply all of the changes stored in FILE, a + file previously generated by \fB\-\-write\-batch\fP. + If \fIFILE\fP is \fB\-\fP, the batch data will be read from standard input. +! See the \(dq\&BATCH MODE\(dq\& section for details. + .IP + .IP "\fB\-\-protocol=NUM\fP" + Force an older protocol version to be used. This +*************** +*** 2395,2432 **** + is useful for creating a batch file that is compatible with an older + version of rsync. For instance, if rsync 2.6.4 is being used with the + \fB\-\-write\-batch\fP option, but rsync 2.6.3 is what will be used to run the +! \fB\-\-read\-batch\fP option, you should use \(lq\-\-protocol=28\(rq when creating the + batch file to force the older protocol version to be used in the batch +! file (assuming you can't upgrade the rsync on the reading system). + .IP + .IP "\fB\-\-iconv=CONVERT_SPEC\fP" + Rsync can convert filenames between character +! sets using this option. Using a CONVERT_SPEC of \(lq.\(rq tells rsync to look up +! the default character-set via the locale setting. Alternately, you can + fully specify what conversion to do by giving a local and a remote charset + separated by a comma in the order \fB\-\-iconv=LOCAL,REMOTE\fP, e.g. + \fB\-\-iconv=utf8,iso88591\fP. This order ensures that the option +! will stay the same whether you're pushing or pulling files. +! Finally, you can specify either \fB\-\-no\-iconv\fP or a CONVERT_SPEC of \(lq\-\(rq + to turn off any conversion. +! The default setting of this option is site-specific, and can also be + affected via the RSYNC_ICONV environment variable. + .IP + For a list of what charset names your local iconv library supports, you can +! run \(lqiconv \-\-list\(rq. + .IP + If you specify the \fB\-\-protect\-args\fP option (\fB\-s\fP), rsync will translate +! the filenames you specify on the command-line that are being sent to the + remote host. See also the \fB\-\-files\-from\fP option. + .IP + Note that rsync does not do any conversion of names in filter files +! (including include/exclude files). It is up to you to ensure that you're + specifying matching rules that can match on both sides of the transfer. + For instance, you can specify extra include/exclude rules if there are + filename differences on the two sides that need to be accounted for. + .IP + When you pass an \fB\-\-iconv\fP option to an rsync daemon that allows it, the +! daemon uses the charset specified in its \(lqcharset\(rq configuration parameter + regardless of the remote charset you actually pass. Thus, you may feel free to + specify just the local charset for a daemon transfer (e.g. \fB\-\-iconv=utf8\fP). + .IP +--- 2472,2509 ---- + is useful for creating a batch file that is compatible with an older + version of rsync. For instance, if rsync 2.6.4 is being used with the + \fB\-\-write\-batch\fP option, but rsync 2.6.3 is what will be used to run the +! \fB\-\-read\-batch\fP option, you should use \(dq\&\-\-protocol=28\(dq\& when creating the + batch file to force the older protocol version to be used in the batch +! file (assuming you can\(cq\&t upgrade the rsync on the reading system). + .IP + .IP "\fB\-\-iconv=CONVERT_SPEC\fP" + Rsync can convert filenames between character +! sets using this option. Using a CONVERT_SPEC of \(dq\&.\(dq\& tells rsync to look up +! the default character\-set via the locale setting. Alternately, you can + fully specify what conversion to do by giving a local and a remote charset + separated by a comma in the order \fB\-\-iconv=LOCAL,REMOTE\fP, e.g. + \fB\-\-iconv=utf8,iso88591\fP. This order ensures that the option +! will stay the same whether you\(cq\&re pushing or pulling files. +! Finally, you can specify either \fB\-\-no\-iconv\fP or a CONVERT_SPEC of \(dq\&\-\(dq\& + to turn off any conversion. +! The default setting of this option is site\-specific, and can also be + affected via the RSYNC_ICONV environment variable. + .IP + For a list of what charset names your local iconv library supports, you can +! run \(dq\&iconv \-\-list\(dq\&. + .IP + If you specify the \fB\-\-protect\-args\fP option (\fB\-s\fP), rsync will translate +! the filenames you specify on the command\-line that are being sent to the + remote host. See also the \fB\-\-files\-from\fP option. + .IP + Note that rsync does not do any conversion of names in filter files +! (including include/exclude files). It is up to you to ensure that you\(cq\&re + specifying matching rules that can match on both sides of the transfer. + For instance, you can specify extra include/exclude rules if there are + filename differences on the two sides that need to be accounted for. + .IP + When you pass an \fB\-\-iconv\fP option to an rsync daemon that allows it, the +! daemon uses the charset specified in its \(dq\&charset\(dq\& configuration parameter + regardless of the remote charset you actually pass. Thus, you may feel free to + specify just the local charset for a daemon transfer (e.g. \fB\-\-iconv=utf8\fP). + .IP +*************** +*** 2477,2483 **** + run as a daemon with the \fB\-\-daemon\fP option. The \fB\-\-address\fP option + allows you to specify a specific IP address (or hostname) to bind to. This + makes virtual hosting possible in conjunction with the \fB\-\-config\fP option. +! See also the \(lqaddress\(rq global option in the rsyncd.conf manpage. + .IP + .IP "\fB\-\-bwlimit=KBPS\fP" + This option allows you to specify a maximum +--- 2554,2560 ---- + run as a daemon with the \fB\-\-daemon\fP option. The \fB\-\-address\fP option + allows you to specify a specific IP address (or hostname) to bind to. This + makes virtual hosting possible in conjunction with the \fB\-\-config\fP option. +! See also the \(dq\&address\(dq\& global option in the rsyncd.conf manpage. + .IP + .IP "\fB\-\-bwlimit=KBPS\fP" + This option allows you to specify a maximum +*************** +*** 2490,2496 **** + This specifies an alternate config file than + the default. This is only relevant when \fB\-\-daemon\fP is specified. + The default is /etc/rsyncd.conf unless the daemon is running over +! a remote shell program and the remote user is not the super-user; in that case + the default is rsyncd.conf in the current directory (typically $HOME). + .IP + .IP "\fB\-\-no\-detach\fP" +--- 2567,2573 ---- + This specifies an alternate config file than + the default. This is only relevant when \fB\-\-daemon\fP is specified. + The default is /etc/rsyncd.conf unless the daemon is running over +! a remote shell program and the remote user is not the super\-user; in that case + the default is rsyncd.conf in the current directory (typically $HOME). + .IP + .IP "\fB\-\-no\-detach\fP" +*************** +*** 2498,2504 **** + rsync to not detach itself and become a background process. This + option is required when running as a service on Cygwin, and may also + be useful when rsync is supervised by a program such as +! \fBdaemontools\fP or AIX's \fBSystem Resource Controller\fP. + \fB\-\-no\-detach\fP is also recommended when rsync is run under a + debugger. This option has no effect if rsync is run from inetd or + sshd. +--- 2575,2581 ---- + rsync to not detach itself and become a background process. This + option is required when running as a service on Cygwin, and may also + be useful when rsync is supervised by a program such as +! \fBdaemontools\fP or AIX\(cq\&s \fBSystem Resource Controller\fP. + \fB\-\-no\-detach\fP is also recommended when rsync is run under a + debugger. This option has no effect if rsync is run from inetd or + sshd. +*************** +*** 2505,2522 **** + .IP + .IP "\fB\-\-port=PORT\fP" + This specifies an alternate TCP port number for the +! daemon to listen on rather than the default of 873. See also the \(lqport\(rq + global option in the rsyncd.conf manpage. + .IP + .IP "\fB\-\-log\-file=FILE\fP" + This option tells the rsync daemon to use the +! given log-file name instead of using the \(lqlog file\(rq setting in the config + file. + .IP + .IP "\fB\-\-log\-file\-format=FORMAT\fP" + This option tells the rsync daemon to use the +! given FORMAT string instead of using the \(lqlog format\(rq setting in the config +! file. It also enables \(lqtransfer logging\(rq unless the string is empty, in which + case transfer logging is turned off. + .IP + .IP "\fB\-\-sockopts\fP" +--- 2582,2599 ---- + .IP + .IP "\fB\-\-port=PORT\fP" + This specifies an alternate TCP port number for the +! daemon to listen on rather than the default of 873. See also the \(dq\&port\(dq\& + global option in the rsyncd.conf manpage. + .IP + .IP "\fB\-\-log\-file=FILE\fP" + This option tells the rsync daemon to use the +! given log\-file name instead of using the \(dq\&log file\(dq\& setting in the config + file. + .IP + .IP "\fB\-\-log\-file\-format=FORMAT\fP" + This option tells the rsync daemon to use the +! given FORMAT string instead of using the \(dq\&log format\(dq\& setting in the config +! file. It also enables \(dq\&transfer logging\(dq\& unless the string is empty, in which + case transfer logging is turned off. + .IP + .IP "\fB\-\-sockopts\fP" +*************** +*** 2526,2533 **** + .IP "\fB\-v, \-\-verbose\fP" + This option increases the amount of information the + daemon logs during its startup phase. After the client connects, the +! daemon's verbosity level will be controlled by the options that the client +! used and the \(lqmax verbosity\(rq setting in the module's config section. + .IP + .IP "\fB\-4, \-\-ipv4\fP or \fB\-6, \-\-ipv6\fP" + Tells rsync to prefer IPv4/IPv6 +--- 2603,2610 ---- + .IP "\fB\-v, \-\-verbose\fP" + This option increases the amount of information the + daemon logs during its startup phase. After the client connects, the +! daemon\(cq\&s verbosity level will be controlled by the options that the client +! used and the \(dq\&max verbosity\(dq\& setting in the module\(cq\&s config section. + .IP + .IP "\fB\-4, \-\-ipv4\fP or \fB\-6, \-\-ipv6\fP" + Tells rsync to prefer IPv4/IPv6 +*************** +*** 2534,2540 **** + when creating the incoming sockets that the rsync daemon will use to + listen for connections. One of these options may be required in older + versions of Linux to work around an IPv6 bug in the kernel (if you see +! an \(lqaddress already in use\(rq error when nothing else is using the port, + try specifying \fB\-\-ipv6\fP or \fB\-\-ipv4\fP when starting the daemon). + .IP + If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option +--- 2611,2617 ---- + when creating the incoming sockets that the rsync daemon will use to + listen for connections. One of these options may be required in older + versions of Linux to work around an IPv6 bug in the kernel (if you see +! an \(dq\&address already in use\(dq\& error when nothing else is using the port, + try specifying \fB\-\-ipv6\fP or \fB\-\-ipv4\fP when starting the daemon). + .IP + If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option +*************** +*** 2562,2568 **** + filename is not skipped. + .PP + Rsync builds an ordered list of filter rules as specified on the +! command-line. Filter rules have the following syntax: + .PP + .RS + \f(CWRULE [PATTERN_OR_FILENAME]\fP +--- 2639,2645 ---- + filename is not skipped. + .PP + Rsync builds an ordered list of filter rules as specified on the +! command\-line. Filter rules have the following syntax: + .PP + .RS + \f(CWRULE [PATTERN_OR_FILENAME]\fP +*************** +*** 2573,2579 **** + + .PP + You have your choice of using either short or long RULE names, as described +! below. If you use a short-named rule, the \(oq,\(cq separating the RULE from the + MODIFIERS is optional. The PATTERN or FILENAME that follows (when present) + must come after either a single space or an underscore (_). + Here are the available rule prefixes: +--- 2650,2656 ---- + + .PP + You have your choice of using either short or long RULE names, as described +! below. If you use a short\-named rule, the \(cq\&,\(cq\& separating the RULE from the + MODIFIERS is optional. The PATTERN or FILENAME that follows (when present) + must come after either a single space or an underscore (_). + Here are the available rule prefixes: +*************** +*** 2583,2591 **** + .br + \fBinclude, +\fP specifies an include pattern. + .br +! \fBmerge, .\fP specifies a merge-file to read for more rules. + .br +! \fBdir-merge, :\fP specifies a per-directory merge-file. + .br + \fBhide, H\fP specifies a pattern for hiding files from the transfer. + .br +--- 2660,2668 ---- + .br + \fBinclude, +\fP specifies an include pattern. + .br +! \fBmerge, .\fP specifies a merge\-file to read for more rules. + .br +! \fBdir\-merge, :\fP specifies a per\-directory merge\-file. + .br + \fBhide, H\fP specifies a pattern for hiding files from the transfer. + .br +*************** +*** 2601,2615 **** + + .PP + When rules are being read from a file, empty lines are ignored, as are +! comment lines that start with a \(lq#\(rq. + .PP +! Note that the \fB\-\-include\fP/\fB\-\-exclude\fP command-line options do not allow the +! full range of rule parsing as described above \(em they only allow the +! specification of include/exclude patterns plus a \(lq!\(rq token to clear the + list (and the normal comment parsing when rules are read from a file). + If a pattern +! does not begin with \(lq\- \(rq (dash, space) or \(lq+ \(rq (plus, space), then the +! rule will be interpreted as if \(lq+ \(rq (for an include option) or \(lq\- \(rq (for + an exclude option) were prefixed to the string. A \fB\-\-filter\fP option, on + the other hand, must always contain either a short or long rule name at the + start of the rule. +--- 2678,2692 ---- + + .PP + When rules are being read from a file, empty lines are ignored, as are +! comment lines that start with a \(dq\&#\(dq\&. + .PP +! Note that the \fB\-\-include\fP/\fB\-\-exclude\fP command\-line options do not allow the +! full range of rule parsing as described above \-\- they only allow the +! specification of include/exclude patterns plus a \(dq\&!\(dq\& token to clear the + list (and the normal comment parsing when rules are read from a file). + If a pattern +! does not begin with \(dq\&\- \(dq\& (dash, space) or \(dq\&+ \(dq\& (plus, space), then the +! rule will be interpreted as if \(dq\&+ \(dq\& (for an include option) or \(dq\&\- \(dq\& (for + an exclude option) were prefixed to the string. A \fB\-\-filter\fP option, on + the other hand, must always contain either a short or long rule name at the + start of the rule. +*************** +*** 2616,2629 **** + .PP + Note also that the \fB\-\-filter\fP, \fB\-\-include\fP, and \fB\-\-exclude\fP options take one + rule/pattern each. To add multiple ones, you can repeat the options on +! the command-line, use the merge-file syntax of the \fB\-\-filter\fP option, or + the \fB\-\-include\-from\fP/\fB\-\-exclude\-from\fP options. + .PP + .SH "INCLUDE/EXCLUDE PATTERN RULES" + + .PP +! You can include and exclude files by specifying patterns using the \(lq+\(rq, +! \(lq\-\(rq, etc. filter rules (as introduced in the FILTER RULES section above). + The include/exclude rules each specify a pattern that is matched against + the names of the files that are going to be transferred. These patterns + can take several forms: +--- 2693,2706 ---- + .PP + Note also that the \fB\-\-filter\fP, \fB\-\-include\fP, and \fB\-\-exclude\fP options take one + rule/pattern each. To add multiple ones, you can repeat the options on +! the command\-line, use the merge\-file syntax of the \fB\-\-filter\fP option, or + the \fB\-\-include\-from\fP/\fB\-\-exclude\-from\fP options. + .PP + .SH "INCLUDE/EXCLUDE PATTERN RULES" + + .PP +! You can include and exclude files by specifying patterns using the \(dq\&+\(dq\&, +! \(dq\&\-\(dq\&, etc. filter rules (as introduced in the FILTER RULES section above). + The include/exclude rules each specify a pattern that is matched against + the names of the files that are going to be transferred. These patterns + can take several forms: +*************** +*** 2633,2647 **** + particular spot in the hierarchy of files, otherwise it is matched + against the end of the pathname. This is similar to a leading ^ in + regular expressions. +! Thus \(lq/foo\(rq would match a name of \(lqfoo\(rq at either the \(lqroot of the +! transfer\(rq (for a global rule) or in the merge-file's directory (for a +! per-directory rule). +! An unqualified \(lqfoo\(rq would match a name of \(lqfoo\(rq anywhere in the + tree because the algorithm is applied recursively from the + top down; it behaves as if each path component gets a turn at being the +! end of the filename. Even the unanchored \(lqsub/foo\(rq would match at +! any point in the hierarchy where a \(lqfoo\(rq was found within a directory +! named \(lqsub\(rq. See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for + a full discussion of how to specify a pattern that matches at the root + of the transfer. + .IP o +--- 2710,2724 ---- + particular spot in the hierarchy of files, otherwise it is matched + against the end of the pathname. This is similar to a leading ^ in + regular expressions. +! Thus \(dq\&/foo\(dq\& would match a name of \(dq\&foo\(dq\& at either the \(dq\&root of the +! transfer\(dq\& (for a global rule) or in the merge\-file\(cq\&s directory (for a +! per\-directory rule). +! An unqualified \(dq\&foo\(dq\& would match a name of \(dq\&foo\(dq\& anywhere in the + tree because the algorithm is applied recursively from the + top down; it behaves as if each path component gets a turn at being the +! end of the filename. Even the unanchored \(dq\&sub/foo\(dq\& would match at +! any point in the hierarchy where a \(dq\&foo\(dq\& was found within a directory +! named \(dq\&sub\(dq\&. See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for + a full discussion of how to specify a pattern that matches at the root + of the transfer. + .IP o +*************** +*** 2650,2693 **** + .IP o + rsync chooses between doing a simple string match and wildcard + matching by checking if the pattern contains one of these three wildcard +! characters: \(oq*\(cq, \(oq?\(cq, and \(oq[\(cq . + .IP o +! a \(oq*\(cq matches any path component, but it stops at slashes. + .IP o +! use '**' to match anything, including slashes. + .IP o +! a \(oq?\(cq matches any character except a slash (/). + .IP o +! a \(oq[\(cq introduces a character class, such as [a\-z] or [[:alpha:]]. + .IP o + in a wildcard pattern, a backslash can be used to escape a wildcard + character, but it is matched literally when no wildcards are present. + .IP o +! if the pattern contains a / (not counting a trailing /) or a \(lq**\(rq, + then it is matched against the full pathname, including any leading +! directories. If the pattern doesn't contain a / or a \(lq**\(rq, then it is + matched only against the final component of the filename. +! (Remember that the algorithm is applied recursively so \(lqfull filename\(rq + can actually be any portion of a path from the starting directory on + down.) + .IP o +! a trailing \(lqdir_name/***\(rq will match both the directory (as if +! \(lqdir_name/\(rq had been specified) and everything in the directory +! (as if \(lqdir_name/**\(rq had been specified). This behavior was added in + version 2.6.7. + + .PP + Note that, when using the \fB\-\-recursive\fP (\fB\-r\fP) option (which is implied by + \fB\-a\fP), every subcomponent of every path is visited from the top down, so +! include/exclude patterns get applied recursively to each subcomponent's +! full name (e.g. to include \(lq/foo/bar/baz\(rq the subcomponents \(lq/foo\(rq and +! \(lq/foo/bar\(rq must not be excluded). +! The exclude patterns actually short-circuit the directory traversal stage + when rsync finds the files to send. If a pattern excludes a particular + parent directory, it can render a deeper include pattern ineffectual + because rsync did not descend through that excluded section of the +! hierarchy. This is particularly important when using a trailing \(oq*\(cq rule. +! For instance, this won't work: + .PP + .RS + \f(CW+ /some/path/this\-file\-will\-not\-be\-found\fP +--- 2727,2770 ---- + .IP o + rsync chooses between doing a simple string match and wildcard + matching by checking if the pattern contains one of these three wildcard +! characters: \(cq\&*\(cq\&, \(cq\&?\(cq\&, and \(cq\&[\(cq\& . + .IP o +! a \(cq\&*\(cq\& matches any path component, but it stops at slashes. + .IP o +! use \(cq\&**\(cq\& to match anything, including slashes. + .IP o +! a \(cq\&?\(cq\& matches any character except a slash (/). + .IP o +! a \(cq\&[\(cq\& introduces a character class, such as [a\-z] or [[:alpha:]]. + .IP o + in a wildcard pattern, a backslash can be used to escape a wildcard + character, but it is matched literally when no wildcards are present. + .IP o +! if the pattern contains a / (not counting a trailing /) or a \(dq\&**\(dq\&, + then it is matched against the full pathname, including any leading +! directories. If the pattern doesn\(cq\&t contain a / or a \(dq\&**\(dq\&, then it is + matched only against the final component of the filename. +! (Remember that the algorithm is applied recursively so \(dq\&full filename\(dq\& + can actually be any portion of a path from the starting directory on + down.) + .IP o +! a trailing \(dq\&dir_name/***\(dq\& will match both the directory (as if +! \(dq\&dir_name/\(dq\& had been specified) and everything in the directory +! (as if \(dq\&dir_name/**\(dq\& had been specified). This behavior was added in + version 2.6.7. + + .PP + Note that, when using the \fB\-\-recursive\fP (\fB\-r\fP) option (which is implied by + \fB\-a\fP), every subcomponent of every path is visited from the top down, so +! include/exclude patterns get applied recursively to each subcomponent\(cq\&s +! full name (e.g. to include \(dq\&/foo/bar/baz\(dq\& the subcomponents \(dq\&/foo\(dq\& and +! \(dq\&/foo/bar\(dq\& must not be excluded). +! The exclude patterns actually short\-circuit the directory traversal stage + when rsync finds the files to send. If a pattern excludes a particular + parent directory, it can render a deeper include pattern ineffectual + because rsync did not descend through that excluded section of the +! hierarchy. This is particularly important when using a trailing \(cq\&*\(cq\& rule. +! For instance, this won\(cq\&t work: + .PP + .RS + \f(CW+ /some/path/this\-file\-will\-not\-be\-found\fP +*************** +*** 2699,2709 **** + .RE + + .PP +! This fails because the parent directory \(lqsome\(rq is excluded by the \(oq*\(cq +! rule, so rsync never visits any of the files in the \(lqsome\(rq or \(lqsome/path\(rq + directories. One solution is to ask for all directories in the hierarchy +! to be included by using a single rule: \(lq+ */\(rq (put it somewhere before the +! \(lq\- *\(rq rule), and perhaps use the \fB\-\-prune\-empty\-dirs\fP option. Another + solution is to add specific include rules for all + the parent dirs that need to be visited. For instance, this set of rules + works fine: +--- 2776,2786 ---- + .RE + + .PP +! This fails because the parent directory \(dq\&some\(dq\& is excluded by the \(cq\&*\(cq\& +! rule, so rsync never visits any of the files in the \(dq\&some\(dq\& or \(dq\&some/path\(dq\& + directories. One solution is to ask for all directories in the hierarchy +! to be included by using a single rule: \(dq\&+ */\(dq\& (put it somewhere before the +! \(dq\&\- *\(dq\& rule), and perhaps use the \fB\-\-prune\-empty\-dirs\fP option. Another + solution is to add specific include rules for all + the parent dirs that need to be visited. For instance, this set of rules + works fine: +*************** +*** 2725,2768 **** + Here are some examples of exclude/include matching: + .PP + .IP o +! \(lq\- *.o\(rq would exclude all names matching *.o + .IP o +! \(lq\- /foo\(rq would exclude a file (or directory) named foo in the +! transfer-root directory + .IP o +! \(lq\- foo/\(rq would exclude any directory named foo + .IP o +! \(lq\- /foo/*/bar\(rq would exclude any file named bar which is at two +! levels below a directory named foo in the transfer-root directory + .IP o +! \(lq\- /foo/**/bar\(rq would exclude any file named bar two +! or more levels below a directory named foo in the transfer-root directory + .IP o +! The combination of \(lq+ */\(rq, \(lq+ *.c\(rq, and \(lq\- *\(rq would include all + directories and C source files but nothing else (see also the + \fB\-\-prune\-empty\-dirs\fP option) + .IP o +! The combination of \(lq+ foo/\(rq, \(lq+ foo/bar.c\(rq, and \(lq\- *\(rq would include + only the foo directory and foo/bar.c (the foo directory must be +! explicitly included or it would be excluded by the \(lq*\(rq) + + .PP +! The following modifiers are accepted after a \(lq+\(rq or \(lq\-\(rq: + .PP + .IP o + A \fB/\fP specifies that the include/exclude rule should be matched + against the absolute pathname of the current item. For example, +! \(lq\-/ /etc/passwd\(rq would exclude the passwd file any time the transfer +! was sending files from the \(lq/etc\(rq directory, and \(lq\-/ subdir/foo\(rq +! would always exclude \(lqfoo\(rq when it is in a dir named \(lqsubdir\(rq, even +! if \(lqfoo\(rq is at the root of the current transfer. + .IP o + A \fB!\fP specifies that the include/exclude should take effect if +! the pattern fails to match. For instance, \(lq\-! */\(rq would exclude all +! non-directories. + .IP o +! A \fBC\fP is used to indicate that all the global CVS-exclude rules +! should be inserted as excludes in place of the \(lq\-C\(rq. No arg should + follow. + .IP o + An \fBs\fP is used to indicate that the rule applies to the sending +--- 2802,2845 ---- + Here are some examples of exclude/include matching: + .PP + .IP o +! \(dq\&\- *.o\(dq\& would exclude all names matching *.o + .IP o +! \(dq\&\- /foo\(dq\& would exclude a file (or directory) named foo in the +! transfer\-root directory + .IP o +! \(dq\&\- foo/\(dq\& would exclude any directory named foo + .IP o +! \(dq\&\- /foo/*/bar\(dq\& would exclude any file named bar which is at two +! levels below a directory named foo in the transfer\-root directory + .IP o +! \(dq\&\- /foo/**/bar\(dq\& would exclude any file named bar two +! or more levels below a directory named foo in the transfer\-root directory + .IP o +! The combination of \(dq\&+ */\(dq\&, \(dq\&+ *.c\(dq\&, and \(dq\&\- *\(dq\& would include all + directories and C source files but nothing else (see also the + \fB\-\-prune\-empty\-dirs\fP option) + .IP o +! The combination of \(dq\&+ foo/\(dq\&, \(dq\&+ foo/bar.c\(dq\&, and \(dq\&\- *\(dq\& would include + only the foo directory and foo/bar.c (the foo directory must be +! explicitly included or it would be excluded by the \(dq\&*\(dq\&) + + .PP +! The following modifiers are accepted after a \(dq\&+\(dq\& or \(dq\&\-\(dq\&: + .PP + .IP o + A \fB/\fP specifies that the include/exclude rule should be matched + against the absolute pathname of the current item. For example, +! \(dq\&\-/ /etc/passwd\(dq\& would exclude the passwd file any time the transfer +! was sending files from the \(dq\&/etc\(dq\& directory, and \(dq\&\-/ subdir/foo\(dq\& +! would always exclude \(dq\&foo\(dq\& when it is in a dir named \(dq\&subdir\(dq\&, even +! if \(dq\&foo\(dq\& is at the root of the current transfer. + .IP o + A \fB!\fP specifies that the include/exclude should take effect if +! the pattern fails to match. For instance, \(dq\&\-! */\(dq\& would exclude all +! non\-directories. + .IP o +! A \fBC\fP is used to indicate that all the global CVS\-exclude rules +! should be inserted as excludes in place of the \(dq\&\-C\(dq\&. No arg should + follow. + .IP o + An \fBs\fP is used to indicate that the rule applies to the sending +*************** +*** 2769,2807 **** + side. When a rule affects the sending side, it prevents files from + being transferred. The default is for a rule to affect both sides + unless \fB\-\-delete\-excluded\fP was specified, in which case default rules +! become sender-side only. See also the hide (H) and show (S) rules, +! which are an alternate way to specify sending-side includes/excludes. + .IP o + An \fBr\fP is used to indicate that the rule applies to the receiving + side. When a rule affects the receiving side, it prevents files from + being deleted. See the \fBs\fP modifier for more info. See also the + protect (P) and risk (R) rules, which are an alternate way to +! specify receiver-side includes/excludes. + .IP o + A \fBp\fP indicates that a rule is perishable, meaning that it is + ignored in directories that are being deleted. For instance, the \fB\-C\fP +! option's default rules that exclude things like \(lqCVS\(rq and \(lq*.o\(rq are + marked as perishable, and will not prevent a directory that was removed + on the source from being deleted on the destination. + + .PP +! .SH "MERGE-FILE FILTER RULES" + + .PP + You can merge whole files into your filter rules by specifying either a +! merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES + section above). + .PP +! There are two kinds of merged files \(em single-instance (\(oq.\(cq) and +! per-directory (\(oq:\(cq). A single-instance merge file is read one time, and +! its rules are incorporated into the filter list in the place of the \(lq.\(rq +! rule. For per-directory merge files, rsync will scan every directory that + it traverses for the named file, merging its contents when the file exists +! into the current list of inherited rules. These per-directory rule files + must be created on the sending side because it is the sending side that is + being scanned for the available files to transfer. These rule files may + also need to be transferred to the receiving side if you want them to +! affect what files don't get deleted (see PER-DIRECTORY RULES AND DELETE + below). + .PP + Some examples: +--- 2846,2884 ---- + side. When a rule affects the sending side, it prevents files from + being transferred. The default is for a rule to affect both sides + unless \fB\-\-delete\-excluded\fP was specified, in which case default rules +! become sender\-side only. See also the hide (H) and show (S) rules, +! which are an alternate way to specify sending\-side includes/excludes. + .IP o + An \fBr\fP is used to indicate that the rule applies to the receiving + side. When a rule affects the receiving side, it prevents files from + being deleted. See the \fBs\fP modifier for more info. See also the + protect (P) and risk (R) rules, which are an alternate way to +! specify receiver\-side includes/excludes. + .IP o + A \fBp\fP indicates that a rule is perishable, meaning that it is + ignored in directories that are being deleted. For instance, the \fB\-C\fP +! option\(cq\&s default rules that exclude things like \(dq\&CVS\(dq\& and \(dq\&*.o\(dq\& are + marked as perishable, and will not prevent a directory that was removed + on the source from being deleted on the destination. + + .PP +! .SH "MERGE\-FILE FILTER RULES" + + .PP + You can merge whole files into your filter rules by specifying either a +! merge (.) or a dir\-merge (:) filter rule (as introduced in the FILTER RULES + section above). + .PP +! There are two kinds of merged files \-\- single\-instance (\(cq\&.\(cq\&) and +! per\-directory (\(cq\&:\(cq\&). A single\-instance merge file is read one time, and +! its rules are incorporated into the filter list in the place of the \(dq\&.\(dq\& +! rule. For per\-directory merge files, rsync will scan every directory that + it traverses for the named file, merging its contents when the file exists +! into the current list of inherited rules. These per\-directory rule files + must be created on the sending side because it is the sending side that is + being scanned for the available files to transfer. These rule files may + also need to be transferred to the receiving side if you want them to +! affect what files don\(cq\&t get deleted (see PER\-DIRECTORY RULES AND DELETE + below). + .PP + Some examples: +*************** +*** 2820,2875 **** + .RE + + .PP +! The following modifiers are accepted after a merge or dir-merge rule: + .PP + .IP o + A \fB\-\fP specifies that the file should consist of only exclude +! patterns, with no other rule-parsing except for in-file comments. + .IP o + A \fB+\fP specifies that the file should consist of only include +! patterns, with no other rule-parsing except for in-file comments. + .IP o + A \fBC\fP is a way to specify that the file should be read in a +! CVS-compatible manner. This turns on \(oqn\(cq, \(oqw\(cq, and '\-', but also +! allows the list-clearing token (!) to be specified. If no filename is +! provided, \(lq.cvsignore\(rq is assumed. + .IP o +! A \fBe\fP will exclude the merge-file name from the transfer; e.g. +! \(lqdir-merge,e .rules\(rq is like \(lqdir-merge .rules\(rq and \(lq\- .rules\(rq. + .IP o + An \fBn\fP specifies that the rules are not inherited by subdirectories. + .IP o +! A \fBw\fP specifies that the rules are word-split on whitespace instead +! of the normal line-splitting. This also turns off comments. Note: the + space that separates the prefix from the rule is treated specially, so +! \(lq\- foo + bar\(rq is parsed as two rules (assuming that prefix-parsing wasn't + also disabled). + .IP o +! You may also specify any of the modifiers for the \(lq+\(rq or \(lq\-\(rq rules + (above) in order to have the rules that are read in from the file +! default to having that modifier set. For instance, \(lqmerge,\-/ .excl\(rq would +! treat the contents of .excl as absolute-path excludes, +! while \(lqdir-merge,s .filt\(rq and \(lq:sC\(rq would each make all their +! per-directory rules apply only on the sending side. + + .PP +! Per-directory rules are inherited in all subdirectories of the directory +! where the merge-file was found unless the \(oqn\(cq modifier was used. Each +! subdirectory's rules are prefixed to the inherited per-directory rules + from its parents, which gives the newest rules a higher priority than the +! inherited rules. The entire set of dir-merge rules are grouped together in +! the spot where the merge-file was specified, so it is possible to override +! dir-merge rules via a rule that got specified earlier in the list of global +! rules. When the list-clearing rule (\(lq!\(rq) is read from a per-directory + file, it only clears the inherited rules for the current merge file. + .PP +! Another way to prevent a single rule from a dir-merge file from being inherited is to +! anchor it with a leading slash. Anchored rules in a per-directory +! merge-file are relative to the merge-file's directory, so a pattern \(lq/foo\(rq +! would only match the file \(lqfoo\(rq in the directory where the dir-merge filter + file was found. + .PP +! Here's an example filter file which you'd specify via \fB\-\-filter=". file":\fP + .PP + .RS + \f(CWmerge /home/user/.global\-filter\fP +--- 2897,2956 ---- + .RE + + .PP +! The following modifiers are accepted after a merge or dir\-merge rule: + .PP + .IP o + A \fB\-\fP specifies that the file should consist of only exclude +! patterns, with no other rule\-parsing except for in\-file comments. + .IP o + A \fB+\fP specifies that the file should consist of only include +! patterns, with no other rule\-parsing except for in\-file comments. + .IP o + A \fBC\fP is a way to specify that the file should be read in a +! CVS\-compatible manner. This turns on \(cq\&n\(cq\&, \(cq\&w\(cq\&, and \(cq\&\-\(cq\&, but also +! allows the list\-clearing token (!) to be specified. If no filename is +! provided, \(dq\&.cvsignore\(dq\& is assumed. + .IP o +! A \fBe\fP will exclude the merge\-file name from the transfer; e.g. +! \(dq\&dir\-merge,e .rules\(dq\& is like \(dq\&dir\-merge .rules\(dq\& and \(dq\&\- .rules\(dq\&. + .IP o + An \fBn\fP specifies that the rules are not inherited by subdirectories. + .IP o +! A \fBw\fP specifies that the rules are word\-split on whitespace instead +! of the normal line\-splitting. This also turns off comments. Note: the + space that separates the prefix from the rule is treated specially, so +! \(dq\&\- foo + bar\(dq\& is parsed as two rules (assuming that prefix\-parsing wasn\(cq\&t + also disabled). + .IP o +! You may also specify any of the modifiers for the \(dq\&+\(dq\& or \(dq\&\-\(dq\& rules + (above) in order to have the rules that are read in from the file +! default to having that modifier set (except for the \fB!\fP modifier, which +! would not be useful). For instance, \(dq\&merge,\-/ .excl\(dq\& would +! treat the contents of .excl as absolute\-path excludes, +! while \(dq\&dir\-merge,s .filt\(dq\& and \(dq\&:sC\(dq\& would each make all their +! per\-directory rules apply only on the sending side. If the merge rule +! specifies sides to affect (via the \fBs\fP or \fBr\fP modifier or both), +! then the rules in the file must not specify sides (via a modifier or +! a rule prefix such as \fBhide\fP). + + .PP +! Per\-directory rules are inherited in all subdirectories of the directory +! where the merge\-file was found unless the \(cq\&n\(cq\& modifier was used. Each +! subdirectory\(cq\&s rules are prefixed to the inherited per\-directory rules + from its parents, which gives the newest rules a higher priority than the +! inherited rules. The entire set of dir\-merge rules are grouped together in +! the spot where the merge\-file was specified, so it is possible to override +! dir\-merge rules via a rule that got specified earlier in the list of global +! rules. When the list\-clearing rule (\(dq\&!\(dq\&) is read from a per\-directory + file, it only clears the inherited rules for the current merge file. + .PP +! Another way to prevent a single rule from a dir\-merge file from being inherited is to +! anchor it with a leading slash. Anchored rules in a per\-directory +! merge\-file are relative to the merge\-file\(cq\&s directory, so a pattern \(dq\&/foo\(dq\& +! would only match the file \(dq\&foo\(dq\& in the directory where the dir\-merge filter + file was found. + .PP +! Here\(cq\&s an example filter file which you\(cq\&d specify via \fB\-\-filter=\(dq\&. file\(dq\&:\fP + .PP + .RS + \f(CWmerge /home/user/.global\-filter\fP +*************** +*** 2886,2903 **** + + .PP + This will merge the contents of the /home/user/.global\-filter file at the +! start of the list and also turns the \(lq.rules\(rq filename into a per-directory + filter file. All rules read in prior to the start of the directory scan + follow the global anchoring rules (i.e. a leading slash matches at the root + of the transfer). + .PP +! If a per-directory merge-file is specified with a path that is a parent + directory of the first transfer directory, rsync will scan all the parent + dirs from that starting point to the transfer directory for the indicated +! per-directory file. For instance, here is a common filter (see \fB\-F\fP): + .PP + .RS +! \f(CW\-\-filter=': /.rsync\-filter'\fP + .RE + + .PP +--- 2967,2984 ---- + + .PP + This will merge the contents of the /home/user/.global\-filter file at the +! start of the list and also turns the \(dq\&.rules\(dq\& filename into a per\-directory + filter file. All rules read in prior to the start of the directory scan + follow the global anchoring rules (i.e. a leading slash matches at the root + of the transfer). + .PP +! If a per\-directory merge\-file is specified with a path that is a parent + directory of the first transfer directory, rsync will scan all the parent + dirs from that starting point to the transfer directory for the indicated +! per\-directory file. For instance, here is a common filter (see \fB\-F\fP): + .PP + .RS +! \f(CW\-\-filter='\&: /.rsync\-filter'\&\fP + .RE + + .PP +*************** +*** 2905,2942 **** + directories from the root down through the parent directory of the + transfer prior to the start of the normal directory scan of the file in + the directories that are sent as a part of the transfer. (Note: for an +! rsync daemon, the root is always the same as the module's \(lqpath\(rq.) + .PP +! Some examples of this pre-scanning for per-directory files: + .PP + .RS + \f(CWrsync \-avF /src/path/ /dest/dir\fP + .br +! \f(CWrsync \-av \-\-filter=': ../../.rsync\-filter' /src/path/ /dest/dir\fP + .br +! \f(CWrsync \-av \-\-filter=': .rsync\-filter' /src/path/ /dest/dir\fP + .br + .RE + + .PP +! The first two commands above will look for \(lq.rsync\-filter\(rq in \(lq/\(rq and +! \(lq/src\(rq before the normal scan begins looking for the file in \(lq/src/path\(rq +! and its subdirectories. The last command avoids the parent-dir scan +! and only looks for the \(lq.rsync\-filter\(rq files in each directory that is + a part of the transfer. + .PP +! If you want to include the contents of a \(lq.cvsignore\(rq in your patterns, +! you should use the rule \(lq:C\(rq, which creates a dir-merge of the .cvsignore +! file, but parsed in a CVS-compatible manner. You can +! use this to affect where the \fB\-\-cvs\-exclude\fP (\fB\-C\fP) option's inclusion of the +! per-directory .cvsignore file gets placed into your rules by putting the +! \(lq:C\(rq wherever you like in your filter rules. Without this, rsync would +! add the dir-merge rule for the .cvsignore file at the end of all your other +! rules (giving it a lower priority than your command-line rules). For + example: + .PP + .RS +! \f(CWcat < SYMLINK\(rq, \(lq => HARDLINK\(rq, or \(lq\(rq (where \fBSYMLINK\fP or \fBHARDLINK\fP is a filename) + .IP o + %m the module name + .IP o +! %M the last-modified time of the file + .IP o +! %n the filename (short form; trailing \(lq/\(rq on dir) + .IP o +! %o the operation, which is \(lqsend\(rq, \(lqrecv\(rq, or \(lqdel.\(rq (the latter includes the trailing period) + .IP o + %p the process ID of this rsync session + .IP o +--- 593,607 ---- + .IP o + %l the length of the file in bytes + .IP o +! %L the string \(dq\& \-> SYMLINK\(dq\&, \(dq\& => HARDLINK\(dq\&, or \(dq\&\(dq\& (where \fBSYMLINK\fP or \fBHARDLINK\fP is a filename) + .IP o + %m the module name + .IP o +! %M the last\-modified time of the file + .IP o +! %n the filename (short form; trailing \(dq\&/\(dq\& on dir) + .IP o +! %o the operation, which is \(dq\&send\(dq\&, \(dq\&recv\(dq\&, or \(dq\&del.\(dq\& (the latter includes the trailing period) + .IP o + %p the process ID of this rsync session + .IP o +*************** +*** 615,621 **** + .RE + + .IP +! For a list of what the characters mean that are output by \(lq%i\(rq, see the + \fB\-\-itemize\-changes\fP option in the rsync manpage. + .IP + Note that some of the logged output changes when talking with older +--- 615,621 ---- + .RE + + .IP +! For a list of what the characters mean that are output by \(dq\&%i\(dq\&, see the + \fB\-\-itemize\-changes\fP option in the rsync manpage. + .IP + Note that some of the logged output changes when talking with older +*************** +*** 625,631 **** + .IP "\fBtimeout\fP" + This parameter allows you to override the + clients choice for I/O timeout for this module. Using this parameter you +! can ensure that rsync won't wait on a dead client forever. The timeout + is specified in seconds. A value of zero means no timeout and is the + default. A good choice for anonymous rsync daemons may be 600 (giving + a 10 minute timeout). +--- 625,631 ---- + .IP "\fBtimeout\fP" + This parameter allows you to override the + clients choice for I/O timeout for this module. Using this parameter you +! can ensure that rsync won\(cq\&t wait on a dead client forever. The timeout + is specified in seconds. A value of zero means no timeout and is the + default. A good choice for anonymous rsync daemons may be 600 (giving + a 10 minute timeout). +*************** +*** 632,641 **** + .IP + .IP "\fBrefuse options\fP" + This parameter allows you to +! specify a space-separated list of rsync command line options that will + be refused by your rsync daemon. +! You may specify the full option name, its one-letter abbreviation, or a +! wild-card string that matches multiple options. + For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various + delete options: + .IP +--- 632,641 ---- + .IP + .IP "\fBrefuse options\fP" + This parameter allows you to +! specify a space\-separated list of rsync command line options that will + be refused by your rsync daemon. +! You may specify the full option name, its one\-letter abbreviation, or a +! wild\-card string that matches multiple options. + For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various + delete options: + .IP +*************** +*** 646,660 **** + .IP + The reason the above refuses all delete options is that the options imply + \fB\-\-delete\fP, and implied options are refused just like explicit options. +! As an additional safety feature, the refusal of \(lqdelete\(rq also refuses +! \fBremove-source-files\fP when the daemon is the sender; if you want the latter +! without the former, instead refuse \(lqdelete\-*\(rq \(em that refuses all the + delete modes without affecting \fB\-\-remove\-source\-files\fP. + .IP + When an option is refused, the daemon prints an error message and exits. + To prevent all compression when serving files, +! you can use \(lqdont compress = *\(rq (see below) +! instead of \(lqrefuse options = compress\(rq to avoid returning an error to a + client that requests compression. + .IP + .IP "\fBdont compress\fP" +--- 646,660 ---- + .IP + The reason the above refuses all delete options is that the options imply + \fB\-\-delete\fP, and implied options are refused just like explicit options. +! As an additional safety feature, the refusal of \(dq\&delete\(dq\& also refuses +! \fBremove\-source\-files\fP when the daemon is the sender; if you want the latter +! without the former, instead refuse \(dq\&delete\-*\(dq\& \-\- that refuses all the + delete modes without affecting \fB\-\-remove\-source\-files\fP. + .IP + When an option is refused, the daemon prints an error message and exits. + To prevent all compression when serving files, +! you can use \(dq\&dont compress = *\(dq\& (see below) +! instead of \(dq\&refuse options = compress\(dq\& to avoid returning an error to a + client that requests compression. + .IP + .IP "\fBdont compress\fP" +*************** +*** 663,687 **** + when pulling files from the daemon (no analogous parameter exists to + govern the pushing of files to a daemon). + Compression is expensive in terms of CPU usage, so it +! is usually good to not try to compress files that won't compress well, + such as already compressed files. + .IP +! The \(lqdont compress\(rq parameter takes a space-separated list of +! case-insensitive wildcard patterns. Any source filename matching one + of the patterns will not be compressed during transfer. + .IP + See the \fB\-\-skip\-compress\fP parameter in the \fBrsync\fP(1) manpage for the list + of file suffixes that are not compressed by default. Specifying a value +! for the \(lqdont compress\(rq parameter changes the default when the daemon is + the sender. + .IP +! .IP "\fBpre-xfer exec\fP, \fBpost-xfer exec\fP" + You may specify a command to be run +! before and/or after the transfer. If the \fBpre-xfer exec\fP command fails, the + transfer is aborted before it begins. + .IP + The following environment variables will be set, though some are +! specific to the pre-xfer or the post-xfer environment: + .IP + .RS + .IP o +--- 663,687 ---- + when pulling files from the daemon (no analogous parameter exists to + govern the pushing of files to a daemon). + Compression is expensive in terms of CPU usage, so it +! is usually good to not try to compress files that won\(cq\&t compress well, + such as already compressed files. + .IP +! The \(dq\&dont compress\(dq\& parameter takes a space\-separated list of +! case\-insensitive wildcard patterns. Any source filename matching one + of the patterns will not be compressed during transfer. + .IP + See the \fB\-\-skip\-compress\fP parameter in the \fBrsync\fP(1) manpage for the list + of file suffixes that are not compressed by default. Specifying a value +! for the \(dq\&dont compress\(dq\& parameter changes the default when the daemon is + the sender. + .IP +! .IP "\fBpre\-xfer exec\fP, \fBpost\-xfer exec\fP" + You may specify a command to be run +! before and/or after the transfer. If the \fBpre\-xfer exec\fP command fails, the + transfer is aborted before it begins. + .IP + The following environment variables will be set, though some are +! specific to the pre\-xfer or the post\-xfer environment: + .IP + .RS + .IP o +*************** +*** 689,717 **** + .IP o + \fBRSYNC_MODULE_PATH\fP: The path configured for the module. + .IP o +! \fBRSYNC_HOST_ADDR\fP: The accessing host's IP address. + .IP o +! \fBRSYNC_HOST_NAME\fP: The accessing host's name. + .IP o +! \fBRSYNC_USER_NAME\fP: The accessing user's name (empty if no user). + .IP o + \fBRSYNC_PID\fP: A unique number for this transfer. + .IP o +! \fBRSYNC_REQUEST\fP: (pre-xfer only) The module/path info specified + by the user (note that the user can specify multiple source files, +! so the request can be something like \(lqmod/path1 mod/path2\(rq, etc.). + .IP o +! \fBRSYNC_ARG#\fP: (pre-xfer only) The pre-request arguments are set +! in these numbered values. RSYNC_ARG0 is always \(lqrsyncd\(rq, and the last + value contains a single period. + .IP o +! \fBRSYNC_EXIT_STATUS\fP: (post-xfer only) the server side's exit value. + This will be 0 for a successful run, a positive value for an error that the + server generated, or a \-1 if rsync failed to exit properly. Note that an + error that occurs on the client side does not currently get sent to the + server side, so this is not the final exit status for the whole transfer. + .IP o +! \fBRSYNC_RAW_STATUS\fP: (post-xfer only) the raw exit value from + \f(CWwaitpid()\fP + \&. + .RE +--- 689,717 ---- + .IP o + \fBRSYNC_MODULE_PATH\fP: The path configured for the module. + .IP o +! \fBRSYNC_HOST_ADDR\fP: The accessing host\(cq\&s IP address. + .IP o +! \fBRSYNC_HOST_NAME\fP: The accessing host\(cq\&s name. + .IP o +! \fBRSYNC_USER_NAME\fP: The accessing user\(cq\&s name (empty if no user). + .IP o + \fBRSYNC_PID\fP: A unique number for this transfer. + .IP o +! \fBRSYNC_REQUEST\fP: (pre\-xfer only) The module/path info specified + by the user (note that the user can specify multiple source files, +! so the request can be something like \(dq\&mod/path1 mod/path2\(dq\&, etc.). + .IP o +! \fBRSYNC_ARG#\fP: (pre\-xfer only) The pre\-request arguments are set +! in these numbered values. RSYNC_ARG0 is always \(dq\&rsyncd\(dq\&, and the last + value contains a single period. + .IP o +! \fBRSYNC_EXIT_STATUS\fP: (post\-xfer only) the server side\(cq\&s exit value. + This will be 0 for a successful run, a positive value for an error that the + server generated, or a \-1 if rsync failed to exit properly. Note that an + error that occurs on the client side does not currently get sent to the + server side, so this is not the final exit status for the whole transfer. + .IP o +! \fBRSYNC_RAW_STATUS\fP: (post\-xfer only) the raw exit value from + \f(CWwaitpid()\fP + \&. + .RE +*************** +*** 719,725 **** + .IP + Even though the commands can be associated with a particular module, they + are run using the permissions of the user that started the daemon (not the +! module's uid/gid setting) without any chroot restrictions. + .IP + .SH "AUTHENTICATION STRENGTH" + +--- 719,725 ---- + .IP + Even though the commands can be associated with a particular module, they + are run using the permissions of the user that started the daemon (not the +! module\(cq\&s uid/gid setting) without any chroot restrictions. + .IP + .SH "AUTHENTICATION STRENGTH" + +*************** +*** 726,733 **** + .PP + The authentication protocol used in rsync is a 128 bit MD4 based + challenge response system. This is fairly weak protection, though (with +! at least one brute-force hash-finding algorithm publicly available), so +! if you want really top-quality security, then I recommend that you run + rsync over ssh. (Yes, a future version of rsync will switch over to a + stronger hashing method.) + .PP +--- 726,733 ---- + .PP + The authentication protocol used in rsync is a 128 bit MD4 based + challenge response system. This is fairly weak protection, though (with +! at least one brute\-force hash\-finding algorithm publicly available), so +! if you want really top\-quality security, then I recommend that you run + rsync over ssh. (Yes, a future version of rsync will switch over to a + stronger hashing method.) + .PP +*************** +*** 822,828 **** + .SH "VERSION" + + .PP +! This man page is current for version 3.0.6 of rsync. + .PP + .SH "CREDITS" + +--- 822,828 ---- + .SH "VERSION" + + .PP +! This man page is current for version 3.0.8 of rsync. + .PP + .SH "CREDITS" + +*************** +*** 838,844 **** + .PP + We would be delighted to hear from you if you like this program. + .PP +! This program uses the zlib compression library written by Jean-loup + Gailly and Mark Adler. + .PP + .SH "THANKS" +--- 838,844 ---- + .PP + We would be delighted to hear from you if you like this program. + .PP +! This program uses the zlib compression library written by Jean\-loup + Gailly and Mark Adler. + .PP + .SH "THANKS" diff -r ae0cd5b7bed2 -r 464763778976 components/rsync/rsync.license --- a/components/rsync/rsync.license Thu Jun 09 17:28:09 2011 -0700 +++ b/components/rsync/rsync.license Fri Jun 10 14:01:58 2011 -0700 @@ -10,7 +10,7 @@ Copyright (C) 1996 Andrew Tridgell Copyright (C) 1996 Paul Mackerras Copyright (C) 2001, 2002 Martin Pool - Copyright (C) 2003, 2004, 2005, 2006 Wayne Davison + Copyright (C) 2002-2011 Wayne Davison GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007