Annotation of embedaddon/rsync/rsync.1.html, revision 1.1
1.1 ! misho 1: <html><head>
! 2: <title>rsync(1) man page</title>
! 3: <link href="https://fonts.googleapis.com/css2?family=Roboto&family=Roboto+Mono&display=swap" rel="stylesheet">
! 4: <style>
! 5: body {
! 6: max-width: 50em;
! 7: margin: auto;
! 8: }
! 9: body, b, strong, u {
! 10: font-family: 'Roboto', sans-serif;
! 11: }
! 12: code {
! 13: font-family: 'Roboto Mono', monospace;
! 14: font-weight: bold;
! 15: white-space: pre;
! 16: }
! 17: pre code {
! 18: display: block;
! 19: font-weight: normal;
! 20: }
! 21: blockquote pre code {
! 22: background: #f1f1f1;
! 23: }
! 24: dd p:first-of-type {
! 25: margin-block-start: 0em;
! 26: }
! 27: </style>
! 28: </head><body>
! 29: <h1>NAME</h1>
! 30: <p>rsync -⁠ a fast, versatile, remote (and local) file-copying tool</p>
! 31: <h1>SYNOPSIS</h1>
! 32: <pre><code>Local:
! 33: rsync [OPTION...] SRC... [DEST]
! 34:
! 35: Access via remote shell:
! 36: Pull:
! 37: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
! 38: Push:
! 39: rsync [OPTION...] SRC... [USER@]HOST:DEST
! 40:
! 41: Access via rsync daemon:
! 42: Pull:
! 43: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
! 44: rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
! 45: Push:
! 46: rsync [OPTION...] SRC... [USER@]HOST::DEST
! 47: rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)
! 48: </code></pre>
! 49: <p>Usages with just one SRC arg and no DEST arg will list the source files instead
! 50: of copying.</p>
! 51: <h1>DESCRIPTION</h1>
! 52: <p>Rsync is a fast and extraordinarily versatile file copying tool. It can copy
! 53: locally, to/from another host over any remote shell, or to/from a remote rsync
! 54: daemon. It offers a large number of options that control every aspect of its
! 55: behavior and permit very flexible specification of the set of files to be
! 56: copied. It is famous for its delta-transfer algorithm, which reduces the
! 57: amount of data sent over the network by sending only the differences between
! 58: the source files and the existing files in the destination. Rsync is widely
! 59: used for backups and mirroring and as an improved copy command for everyday
! 60: use.</p>
! 61: <p>Rsync finds files that need to be transferred using a "quick check" algorithm
! 62: (by default) that looks for files that have changed in size or in last-modified
! 63: time. Any changes in the other preserved attributes (as requested by options)
! 64: are made on the destination file directly when the quick check indicates that
! 65: the file's data does not need to be updated.</p>
! 66: <p>Some of the additional features of rsync are:</p>
! 67: <ul>
! 68: <li>support for copying links, devices, owners, groups, and permissions</li>
! 69: <li>exclude and exclude-from options similar to GNU tar</li>
! 70: <li>a CVS exclude mode for ignoring the same files that CVS would ignore</li>
! 71: <li>can use any transparent remote shell, including ssh or rsh</li>
! 72: <li>does not require super-user privileges</li>
! 73: <li>pipelining of file transfers to minimize latency costs</li>
! 74: <li>support for anonymous or authenticated rsync daemons (ideal for mirroring)</li>
! 75: </ul>
! 76: <h1>GENERAL</h1>
! 77: <p>Rsync copies files either to or from a remote host, or locally on the current
! 78: host (it does not support copying files between two remote hosts).</p>
! 79: <p>There are two different ways for rsync to contact a remote system: using a
! 80: remote-shell program as the transport (such as ssh or rsh) or contacting an
! 81: rsync daemon directly via TCP. The remote-shell transport is used whenever the
! 82: source or destination path contains a single colon (:) separator after a host
! 83: specification. Contacting an rsync daemon directly happens when the source or
! 84: destination path contains a double colon (::) separator after a host
! 85: specification, OR when an rsync:// URL is specified (see also the "USING
! 86: RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for an exception
! 87: to this latter rule).</p>
! 88: <p>As a special case, if a single source arg is specified without a destination,
! 89: the files are listed in an output format similar to "<code>ls -l</code>".</p>
! 90: <p>As expected, if neither the source or destination path specify a remote host,
! 91: the copy occurs locally (see also the <code>--list-only</code> option).</p>
! 92: <p>Rsync refers to the local side as the client and the remote side as the server.
! 93: Don't confuse server with an rsync daemon. A daemon is always a server, but a
! 94: server can be either a daemon or a remote-shell spawned process.</p>
! 95: <h1>SETUP</h1>
! 96: <p>See the file README.md for installation instructions.</p>
! 97: <p>Once installed, you can use rsync to any machine that you can access via a
! 98: remote shell (as well as some that you can access using the rsync daemon-mode
! 99: protocol). For remote transfers, a modern rsync uses ssh for its
! 100: communications, but it may have been configured to use a different remote shell
! 101: by default, such as rsh or remsh.</p>
! 102: <p>You can also specify any remote shell you like, either by using the <code>-e</code>
! 103: command line option, or by setting the RSYNC_RSH environment variable.</p>
! 104: <p>Note that rsync must be installed on both the source and destination machines.</p>
! 105: <h1>USAGE</h1>
! 106: <p>You use rsync in the same way you use rcp. You must specify a source and a
! 107: destination, one of which may be remote.</p>
! 108: <p>Perhaps the best way to explain the syntax is with some examples:</p>
! 109: <blockquote>
! 110: <pre><code>rsync -t *.c foo:src/
! 111: </code></pre>
! 112: </blockquote>
! 113: <p>This would transfer all files matching the pattern <code>*.c</code> from the current
! 114: directory to the directory src on the machine foo. If any of the files already
! 115: exist on the remote system then the rsync remote-update protocol is used to
! 116: update the file by sending only the differences in the data. Note that the
! 117: expansion of wildcards on the command-line (<code>*.c</code>) into a list of files is
! 118: handled by the shell before it runs rsync and not by rsync itself (exactly the
! 119: same as all other Posix-style programs).</p>
! 120: <blockquote>
! 121: <pre><code>rsync -avz foo:src/bar /data/tmp
! 122: </code></pre>
! 123: </blockquote>
! 124: <p>This would recursively transfer all files from the directory src/bar on the
! 125: machine foo into the /data/tmp/bar directory on the local machine. The files
! 126: are transferred in archive mode, which ensures that symbolic links, devices,
! 127: attributes, permissions, ownerships, etc. are preserved in the transfer.
! 128: Additionally, compression will be used to reduce the size of data portions of
! 129: the transfer.</p>
! 130: <blockquote>
! 131: <pre><code>rsync -avz foo:src/bar/ /data/tmp
! 132: </code></pre>
! 133: </blockquote>
! 134: <p>A trailing slash on the source changes this behavior to avoid creating an
! 135: additional directory level at the destination. You can think of a trailing /
! 136: on a source as meaning "copy the contents of this directory" as opposed to
! 137: "copy the directory by name", but in both cases the attributes of the
! 138: containing directory are transferred to the containing directory on the
! 139: destination. In other words, each of the following commands copies the files
! 140: in the same way, including their setting of the attributes of /dest/foo:</p>
! 141: <blockquote>
! 142: <pre><code>rsync -av /src/foo /dest
! 143: rsync -av /src/foo/ /dest/foo
! 144: </code></pre>
! 145: </blockquote>
! 146: <p>Note also that host and module references don't require a trailing slash to
! 147: copy the contents of the default directory. For example, both of these copy
! 148: the remote directory's contents into "/dest":</p>
! 149: <blockquote>
! 150: <pre><code>rsync -av host: /dest
! 151: rsync -av host::module /dest
! 152: </code></pre>
! 153: </blockquote>
! 154: <p>You can also use rsync in local-only mode, where both the source and
! 155: destination don't have a ':' in the name. In this case it behaves like an
! 156: improved copy command.</p>
! 157: <p>Finally, you can list all the (listable) modules available from a particular
! 158: rsync daemon by leaving off the module name:</p>
! 159: <blockquote>
! 160: <pre><code>rsync somehost.mydomain.com::
! 161: </code></pre>
! 162: </blockquote>
! 163: <p>And, if Service Location Protocol is available, the following will list the
! 164: available rsync servers:</p>
! 165: <blockquote>
! 166: <pre><code>rsync rsync://
! 167: </code></pre>
! 168: </blockquote>
! 169: <p>See the following section for even more usage details.</p>
! 170: <p>One more thing, if Service Location Protocol is available, the following will
! 171: list the available rsync servers:</p>
! 172: <blockquote>
! 173: <pre><code>rsync rsync://
! 174: </code></pre>
! 175: </blockquote>
! 176: <p>See the following section for even more usage details.</p>
! 177: <h1>ADVANCED USAGE</h1>
! 178: <p>The syntax for requesting multiple files from a remote host is done by
! 179: specifying additional remote-host args in the same style as the first, or with
! 180: the hostname omitted. For instance, all these work:</p>
! 181: <blockquote>
! 182: <pre><code>rsync -av host:file1 :file2 host:file{3,4} /dest/
! 183: rsync -av host::modname/file{1,2} host::modname/file3 /dest/
! 184: rsync -av host::modname/file1 ::modname/file{3,4}
! 185: </code></pre>
! 186: </blockquote>
! 187: <p>Older versions of rsync required using quoted spaces in the SRC, like these
! 188: examples:</p>
! 189: <blockquote>
! 190: <pre><code>rsync -av host:'dir1/file1 dir2/file2' /dest
! 191: rsync host::'modname/dir1/file1 modname/dir2/file2' /dest
! 192: </code></pre>
! 193: </blockquote>
! 194: <p>This word-splitting still works (by default) in the latest rsync, but is not as
! 195: easy to use as the first method.</p>
! 196: <p>If you need to transfer a filename that contains whitespace, you can either
! 197: specify the <code>--protect-args</code> (<code>-s</code>) option, or you'll need to escape the
! 198: whitespace in a way that the remote shell will understand. For instance:</p>
! 199: <blockquote>
! 200: <pre><code>rsync -av host:'file\ name\ with\ spaces' /dest
! 201: </code></pre>
! 202: </blockquote>
! 203: <h1>CONNECTING TO AN RSYNC DAEMON</h1>
! 204: <p>It is also possible to use rsync without a remote shell as the transport. In
! 205: this case you will directly connect to a remote rsync daemon, typically using
! 206: TCP port 873. (This obviously requires the daemon to be running on the remote
! 207: system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS section
! 208: below for information on that.)</p>
! 209: <p>Using rsync in this way is the same as using it with a remote shell except
! 210: that:</p>
! 211: <ul>
! 212: <li>you either use a double colon :: instead of a single colon to separate the
! 213: hostname from the path, or you use an rsync:// URL.</li>
! 214: <li>the first word of the "path" is actually a module name.</li>
! 215: <li>the remote daemon may print a message of the day when you connect.</li>
! 216: <li>if you specify no path name on the remote daemon then the list of accessible
! 217: paths on the daemon will be shown.</li>
! 218: <li>if you specify no local destination then a listing of the specified files on
! 219: the remote daemon is provided.</li>
! 220: <li>you must not specify the <code>--rsh</code> (<code>-e</code>) option (since that overrides the
! 221: daemon connection to use ssh -⁠-⁠ see USING RSYNC-DAEMON FEATURES VIA A
! 222: REMOTE-SHELL CONNECTION below).</li>
! 223: </ul>
! 224: <p>An example that copies all the files in a remote module named "src":</p>
! 225: <blockquote>
! 226: <pre><code>rsync -av host::src /dest
! 227: </code></pre>
! 228: </blockquote>
! 229: <p>Some modules on the remote daemon may require authentication. If so, you will
! 230: receive a password prompt when you connect. You can avoid the password prompt
! 231: by setting the environment variable RSYNC_PASSWORD to the password you want to
! 232: use or using the <code>--password-file</code> option. This may be useful when scripting
! 233: rsync.</p>
! 234: <p>WARNING: On some systems environment variables are visible to all users. On
! 235: those systems using <code>--password-file</code> is recommended.</p>
! 236: <p>You may establish the connection via a web proxy by setting the environment
! 237: variable RSYNC_PROXY to a hostname:port pair pointing to your web proxy. Note
! 238: that your web proxy's configuration must support proxy connections to port 873.</p>
! 239: <p>You may also establish a daemon connection using a program as a proxy by
! 240: setting the environment variable RSYNC_CONNECT_PROG to the commands you wish to
! 241: run in place of making a direct socket connection. The string may contain the
! 242: escape "%H" to represent the hostname specified in the rsync command (so use
! 243: "%%" if you need a single "%" in your string). For example:</p>
! 244: <blockquote>
! 245: <pre><code>export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
! 246: rsync -av targethost1::module/src/ /dest/
! 247: rsync -av rsync://targethost2/module/src/ /dest/
! 248: </code></pre>
! 249: </blockquote>
! 250: <p>The command specified above uses ssh to run nc (netcat) on a proxyhost, which
! 251: forwards all data to port 873 (the rsync daemon) on the targethost (%H).</p>
! 252: <p>Note also that if the RSYNC_SHELL environment variable is set, that program
! 253: will be used to run the RSYNC_CONNECT_PROG command instead of using the default
! 254: shell of the <strong>system()</strong> call.</p>
! 255: <h1>USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION</h1>
! 256: <p>It is sometimes useful to use various features of an rsync daemon (such as
! 257: named modules) without actually allowing any new socket connections into a
! 258: system (other than what is already required to allow remote-shell access).
! 259: Rsync supports connecting to a host using a remote shell and then spawning a
! 260: single-use "daemon" server that expects to read its config file in the home dir
! 261: of the remote user. This can be useful if you want to encrypt a daemon-style
! 262: transfer's data, but since the daemon is started up fresh by the remote user,
! 263: you may not be able to use features such as chroot or change the uid used by
! 264: the daemon. (For another way to encrypt a daemon transfer, consider using ssh
! 265: to tunnel a local port to a remote machine and configure a normal rsync daemon
! 266: on that remote host to only allow connections from "localhost".)</p>
! 267: <p>From the user's perspective, a daemon transfer via a remote-shell connection
! 268: uses nearly the same command-line syntax as a normal rsync-daemon transfer,
! 269: with the only exception being that you must explicitly set the remote shell
! 270: program on the command-line with the <code>--rsh=COMMAND</code> option. (Setting the
! 271: RSYNC_RSH in the environment will not turn on this functionality.) For example:</p>
! 272: <blockquote>
! 273: <pre><code>rsync -av --rsh=ssh host::module /dest
! 274: </code></pre>
! 275: </blockquote>
! 276: <p>If you need to specify a different remote-shell user, keep in mind that the
! 277: user@ prefix in front of the host is specifying the rsync-user value (for a
! 278: module that requires user-based authentication). This means that you must give
! 279: the '-⁠l user' option to ssh when specifying the remote-shell, as in this
! 280: example that uses the short version of the <code>--rsh</code> option:</p>
! 281: <blockquote>
! 282: <pre><code>rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest
! 283: </code></pre>
! 284: </blockquote>
! 285: <p>The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to
! 286: log-in to the "module".</p>
! 287: <h1>STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS</h1>
! 288: <p>In order to connect to an rsync daemon, the remote system needs to have a
! 289: daemon already running (or it needs to have configured something like inetd to
! 290: spawn an rsync daemon for incoming connections on a particular port). For full
! 291: information on how to start a daemon that will handling incoming socket
! 292: connections, see the <strong>rsyncd.conf</strong>(5) man page -⁠-⁠ that is the config file for
! 293: the daemon, and it contains the full details for how to run the daemon
! 294: (including stand-alone and inetd configurations).</p>
! 295: <p>If you're using one of the remote-shell transports for the transfer, there is
! 296: no need to manually start an rsync daemon.</p>
! 297: <h1>SORTED TRANSFER ORDER</h1>
! 298: <p>Rsync always sorts the specified filenames into its internal transfer list.
! 299: This handles the merging together of the contents of identically named
! 300: directories, makes it easy to remove duplicate filenames, and may confuse
! 301: someone when the files are transferred in a different order than what was given
! 302: on the command-line.</p>
! 303: <p>If you need a particular file to be transferred prior to another, either
! 304: separate the files into different rsync calls, or consider using
! 305: <code>--delay-updates</code> (which doesn't affect the sorted transfer order, but does
! 306: make the final file-updating phase happen much more rapidly).</p>
! 307: <h1>EXAMPLES</h1>
! 308: <p>Here are some examples of how I use rsync.</p>
! 309: <p>To backup my wife's home directory, which consists of large MS Word files and
! 310: mail folders, I use a cron job that runs</p>
! 311: <blockquote>
! 312: <pre><code>rsync -Cavz . arvidsjaur:backup
! 313: </code></pre>
! 314: </blockquote>
! 315: <p>each night over a PPP connection to a duplicate directory on my machine
! 316: "arvidsjaur".</p>
! 317: <p>To synchronize my samba source trees I use the following Makefile targets:</p>
! 318: <blockquote>
! 319: <pre><code>get:
! 320: rsync -avuzb --exclude '*~' samba:samba/ .
! 321: put:
! 322: rsync -Cavuzb . samba:samba/
! 323: sync: get put
! 324: </code></pre>
! 325: </blockquote>
! 326: <p>This allows me to sync with a CVS directory at the other end of the connection.
! 327: I then do CVS operations on the remote machine, which saves a lot of time as
! 328: the remote CVS protocol isn't very efficient.</p>
! 329: <p>I mirror a directory between my "old" and "new" ftp sites with the command:</p>
! 330: <blockquote>
! 331: <pre><code>rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge"
! 332: </code></pre>
! 333: </blockquote>
! 334: <p>This is launched from cron every few hours.</p>
! 335: <h1>OPTION SUMMARY</h1>
! 336: <p>Here is a short summary of the options available in rsync. Please refer to the
! 337: detailed description below for a complete description.</p>
! 338: <pre><code>--verbose, -v increase verbosity
! 339: --info=FLAGS fine-grained informational verbosity
! 340: --debug=FLAGS fine-grained debug verbosity
! 341: --stderr=e|a|c change stderr output mode (default: errors)
! 342: --quiet, -q suppress non-error messages
! 343: --no-motd suppress daemon-mode MOTD
! 344: --checksum, -c skip based on checksum, not mod-time & size
! 345: --sumfiles=MODE use .rsyncsums to speedup --checksum mode
! 346: --archive, -a archive mode; equals -rlptgoD (no -H,-A,-X)
! 347: --no-OPTION turn off an implied OPTION (e.g. --no-D)
! 348: --recursive, -r recurse into directories
! 349: --relative, -R use relative path names
! 350: --no-implied-dirs don't send implied dirs with --relative
! 351: --backup, -b make backups (see --suffix & --backup-dir)
! 352: --backup-deleted make backups only of deleted files
! 353: --backup-dir=DIR make backups into hierarchy based in DIR
! 354: --backup-dir-dels=DIR backup removed files into hierarchy based in DIR
! 355: --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
! 356: --suffix-dels=SUFFIX set removed-files suffix (def. --suffix w/o b-d-d)
! 357: --update, -u skip files that are newer on the receiver
! 358: --downdate, -w skip files that are older on the receiver
! 359: --inplace update destination files in-place
! 360: --append append data onto shorter files
! 361: --append-verify --append w/old data in file checksum
! 362: --dirs, -d transfer directories without recursing
! 363: --mkpath create the destination's path component
! 364: --links, -l copy symlinks as symlinks
! 365: --copy-links, -L transform symlink into referent file/dir
! 366: --copy-unsafe-links only "unsafe" symlinks are transformed
! 367: --safe-links ignore symlinks that point outside the tree
! 368: --munge-links munge symlinks to make them safe & unusable
! 369: --copy-dirlinks, -k transform symlink to dir into referent dir
! 370: --keep-dirlinks, -K treat symlinked dir on receiver as dir
! 371: --hard-links, -H preserve hard links
! 372: --perms, -p preserve permissions
! 373: --fileflags preserve file-flags (aka chflags)
! 374: --executability, -E preserve executability
! 375: --chmod=CHMOD affect file and/or directory permissions
! 376: --acls, -A preserve ACLs (implies --perms)
! 377: --xattrs, -X preserve extended attributes
! 378: --hfs-compression preserve HFS compression if supported
! 379: --protect-decmpfs preserve HFS compression as xattrs
! 380: --owner, -o preserve owner (super-user only)
! 381: --group, -g preserve group
! 382: --devices preserve device files (super-user only)
! 383: --copy-devices copy device contents as regular file
! 384: --specials preserve special files
! 385: -D same as --devices --specials
! 386: --times, -t preserve modification times
! 387: --atimes, -U preserve access (use) times
! 388: --open-noatime avoid changing the atime on opened files
! 389: --crtimes, -N preserve create times (newness)
! 390: --omit-dir-times, -O omit directories from --times
! 391: --omit-link-times, -J omit symlinks from --times
! 392: --omit-dir-changes omit directories from any attribute changes
! 393: --super receiver attempts super-user activities
! 394: --fake-super store/recover privileged attrs using xattrs
! 395: --sparse, -S turn sequences of nulls into sparse blocks
! 396: --sparse-block=SIZE set block size used to handle sparse files
! 397: --preallocate allocate dest files before writing them
! 398: --write-devices write to devices as files (implies --inplace)
! 399: --dry-run, -n perform a trial run with no changes made
! 400: --whole-file, -W copy files whole (w/o delta-xfer algorithm)
! 401: --checksum-choice=STR choose the checksum algorithm (aka --cc)
! 402: --db=CONFIG_FILE specify a CONFIG_FILE for DB checksums
! 403: --db-only=CONFIG_FILE behave like rsyncdb
! 404: --db-lax ignore ctime changes (use with CAUTION)
! 405: --one-file-system, -x don't cross filesystem boundaries
! 406: --block-size=SIZE, -B force a fixed checksum block-size
! 407: --rsh=COMMAND, -e specify the remote shell to use
! 408: --rsync-path=PROGRAM specify the rsync to run on remote machine
! 409: --existing skip creating new files on receiver
! 410: --ignore-existing skip updating files that exist on receiver
! 411: --remove-source-files sender removes synchronized files (non-dir)
! 412: --source-backup ... and backs up those files
! 413: --del an alias for --delete-during
! 414: --delete delete extraneous files from dest dirs
! 415: --delete-before receiver deletes before xfer, not during
! 416: --delete-during receiver deletes during the transfer
! 417: --delete-delay find deletions during, delete after
! 418: --delete-after receiver deletes after transfer, not during
! 419: --delete-excluded also delete excluded files from dest dirs
! 420: --ignore-missing-args ignore missing source args without error
! 421: --delete-missing-args delete missing source args from destination
! 422: --ignore-errors delete even if there are I/O errors
! 423: --force-delete force deletion of directories even if not empty
! 424: --force-change affect user-/system-immutable files/dirs
! 425: --force-uchange affect user-immutable files/dirs
! 426: --force-schange affect system-immutable files/dirs
! 427: --max-delete=NUM don't delete more than NUM files
! 428: --max-size=SIZE don't transfer any file larger than SIZE
! 429: --min-size=SIZE don't transfer any file smaller than SIZE
! 430: --max-alloc=SIZE change a limit relating to memory alloc
! 431: --partial keep partially transferred files
! 432: --partial-dir=DIR put a partially transferred file into DIR
! 433: --delay-updates put all updated files into place at end
! 434: --direct-io don't use buffer cache for xfer file I/O
! 435: --prune-empty-dirs, -m prune empty directory chains from file-list
! 436: --fsync fsync every written file
! 437: --numeric-ids don't map uid/gid values by user/group name
! 438: --usermap=STRING custom username mapping
! 439: --groupmap=STRING custom groupname mapping
! 440: --chown=USER:GROUP simple username/groupname mapping
! 441: --timeout=SECONDS set I/O timeout in seconds
! 442: --contimeout=SECONDS set daemon connection timeout in seconds
! 443: --ignore-times, -I don't skip files that match size and time
! 444: --size-only skip files that match in size
! 445: --date-only skip files that match in mod-time
! 446: --modify-window=NUM, -@ set the accuracy for mod-time comparisons
! 447: --temp-dir=DIR, -T create temporary files in directory DIR
! 448: --fuzzy, -y find similar file for basis if no dest file
! 449: --detect-renamed try to find renamed files to speed the xfer
! 450: --compare-dest=DIR also compare destination files relative to DIR
! 451: --copy-dest=DIR ... and include copies of unchanged files
! 452: --link-dest=DIR hardlink to files in DIR when unchanged
! 453: --clone-dest=DIR clone (reflink) files from DIR when unchanged
! 454: --compress, -z compress file data during the transfer
! 455: --compress-choice=STR choose the compression algorithm (aka --zc)
! 456: --compress-level=NUM explicitly set compression level (aka --zl)
! 457: --skip-compress=LIST skip compressing files with suffix in LIST
! 458: --cvs-exclude, -C auto-ignore files in the same way CVS does
! 459: --filter=RULE, -f add a file-filtering RULE
! 460: -F same as --filter='dir-merge /.rsync-filter'
! 461: repeated: --filter='- .rsync-filter'
! 462: --exclude=PATTERN exclude files matching PATTERN
! 463: --exclude-from=FILE read exclude patterns from FILE
! 464: --include=PATTERN don't exclude files matching PATTERN
! 465: --include-from=FILE read include patterns from FILE
! 466: --files-from=FILE read list of source-file names from FILE
! 467: --from0, -0 all *-from/filter files are delimited by 0s
! 468: --protect-args, -s no space-splitting; wildcard chars only
! 469: --copy-as=USER[:GROUP] specify user & optional group for the copy
! 470: --ignore-case ignore case when comparing filenames
! 471: --address=ADDRESS bind address for outgoing socket to daemon
! 472: --port=PORT specify double-colon alternate port number
! 473: --sockopts=OPTIONS specify custom TCP options
! 474: --diffserv=[0-63] specify diffserv setting
! 475: --congestion-alg=STRING choose a congestion algo
! 476: --blocking-io use blocking I/O for the remote shell
! 477: --outbuf=N|L|B set out buffering to None, Line, or Block
! 478: --stats give some file-transfer stats
! 479: --8-bit-output, -8 leave high-bit chars unescaped in output
! 480: --human-readable, -h output numbers in a human-readable format
! 481: --progress show progress during transfer
! 482: -P same as --partial --progress
! 483: --itemize-changes, -i output a change-summary for all updates
! 484: --remote-option=OPT, -M send OPTION to the remote side only
! 485: --out-format=FORMAT output updates using the specified FORMAT
! 486: --log-file=FILE log what we're doing to the specified FILE
! 487: --log-file-format=FMT log updates using the specified FMT
! 488: --password-file=FILE read daemon-access password from FILE
! 489: --early-input=FILE use FILE for daemon's early exec input
! 490: --list-only list the files instead of copying them
! 491: --bwlimit=RATE limit socket I/O bandwidth
! 492: --slow-down=USECs sleep N usec while creating the filelist
! 493: --stop-after=MINS Stop rsync after MINS minutes have elapsed
! 494: --stop-at=y-m-dTh:m Stop rsync at the specified point in time
! 495: --write-batch=FILE write a batched update to FILE
! 496: --only-write-batch=FILE like --write-batch but w/o updating dest
! 497: --read-batch=FILE read a batched update from FILE
! 498: --source-filter=COMMAND filter file through COMMAND at source
! 499: --dest-filter=COMMAND filter file through COMMAND at destination
! 500: --protocol=NUM force an older protocol version to be used
! 501: --iconv=CONVERT_SPEC request charset conversion of filenames
! 502: --tr=BAD/GOOD transliterate filenames
! 503: --checksum-seed=NUM set block/file checksum seed (advanced)
! 504: --ipv4, -4 prefer IPv4
! 505: --ipv6, -6 prefer IPv6
! 506: --version, -V print the version + other info and exit
! 507: --help, -h (*) show this help (* -h is help only on its own)
! 508: </code></pre>
! 509: <p>Rsync can also be run as a daemon, in which case the following options are
! 510: accepted:</p>
! 511: <pre><code>--daemon run as an rsync daemon
! 512: --address=ADDRESS bind to the specified address
! 513: --bwlimit=RATE limit socket I/O bandwidth
! 514: --config=FILE specify alternate rsyncd.conf file
! 515: --dparam=OVERRIDE, -M override global daemon config parameter
! 516: --no-detach do not detach from the parent
! 517: --port=PORT listen on alternate port number
! 518: --log-file=FILE override the "log file" setting
! 519: --log-file-format=FMT override the "log format" setting
! 520: --sockopts=OPTIONS specify custom TCP options
! 521: --verbose, -v increase verbosity
! 522: --ipv4, -4 prefer IPv4
! 523: --ipv6, -6 prefer IPv6
! 524: --help, -h show this help (when used with --daemon)
! 525: </code></pre>
! 526: <h1>OPTIONS</h1>
! 527: <p>Rsync accepts both long (double-dash + word) and short (single-dash + letter)
! 528: options. The full list of the available options are described below. If an
! 529: option can be specified in more than one way, the choices are comma-separated.
! 530: Some options only have a long variant, not a short. If the option takes a
! 531: parameter, the parameter is only listed after the long variant, even though it
! 532: must also be specified for the short. When specifying a parameter, you can
! 533: either use the form <code>--option=param</code> or replace the '=' with whitespace. The
! 534: parameter may need to be quoted in some manner for it to survive the shell's
! 535: command-line parsing. Keep in mind that a leading tilde (<code>~</code>) in a filename is
! 536: substituted by your shell, so <code>--option=~/foo</code> will not change the tilde into
! 537: your home directory (remove the '=' for that).</p>
! 538: <dl>
! 539:
! 540: <dt><code>--help</code>, <code>-h</code> <code>(*)</code></dt><dd>
! 541: <p>Print a short help page describing the options available in rsync and exit.
! 542: (*) The <code>-h</code> short option will only invoke <code>--help</code> when used without other
! 543: options since it normally means <code>--human-readable</code>.</p>
! 544: </dd>
! 545:
! 546: <dt><code>--version</code>, <code>-V</code></dt><dd>
! 547: <p>Print the rsync version plus other info and exit.</p>
! 548: <p>The output includes the default list of checksum algorithms, the default
! 549: list of compression algorithms, a list of compiled-in capabilities, a link
! 550: to the rsync web site, and some license/copyright info.</p>
! 551: </dd>
! 552:
! 553: <dt><code>--verbose</code>, <code>-v</code></dt><dd>
! 554: <p>This option increases the amount of information you are given during the
! 555: transfer. By default, rsync works silently. A single <code>-v</code> will give you
! 556: information about what files are being transferred and a brief summary at
! 557: the end. Two <code>-v</code> options will give you information on what files are
! 558: being skipped and slightly more information at the end. More than two <code>-v</code>
! 559: options should only be used if you are debugging rsync.</p>
! 560: <p>In a modern rsync, the <code>-v</code> option is equivalent to the setting of groups
! 561: of <code>--info</code> and <code>--debug</code> options. You can choose to use these newer
! 562: options in addition to, or in place of using <code>--verbose</code>, as any
! 563: fine-grained settings override the implied settings of <code>-v</code>. Both <code>--info</code>
! 564: and <code>--debug</code> have a way to ask for help that tells you exactly what flags
! 565: are set for each increase in verbosity.</p>
! 566: <p>However, do keep in mind that a daemon's "<code>max verbosity</code>" setting will limit
! 567: how high of a level the various individual flags can be set on the daemon
! 568: side. For instance, if the max is 2, then any info and/or debug flag that
! 569: is set to a higher value than what would be set by <code>-vv</code> will be downgraded
! 570: to the <code>-vv</code> level in the daemon's logging.</p>
! 571: </dd>
! 572:
! 573: <dt><code>--info=FLAGS</code></dt><dd>
! 574: <p>This option lets you have fine-grained control over the information output
! 575: you want to see. An individual flag name may be followed by a level
! 576: number, with 0 meaning to silence that output, 1 being the default output
! 577: level, and higher numbers increasing the output of that flag (for those
! 578: that support higher levels). Use <code>--info=help</code> to see all the available
! 579: flag names, what they output, and what flag names are added for each
! 580: increase in the verbose level. Some examples:</p>
! 581: <blockquote>
! 582: <pre><code>rsync -a --info=progress2 src/ dest/
! 583: rsync -avv --info=stats2,misc1,flist0 src/ dest/
! 584: </code></pre>
! 585: </blockquote>
! 586: <p>Note that <code>--info=name</code>'s output is affected by the <code>--out-format</code> and
! 587: <code>--itemize-changes</code> (<code>-i</code>) options. See those options for more information
! 588: on what is output and when.</p>
! 589: <p>This option was added to 3.1.0, so an older rsync on the server side might
! 590: reject your attempts at fine-grained control (if one or more flags needed
! 591: to be send to the server and the server was too old to understand them).
! 592: See also the "<code>max verbosity</code>" caveat above when dealing with a daemon.</p>
! 593: </dd>
! 594:
! 595: <dt><code>--debug=FLAGS</code></dt><dd>
! 596: <p>This option lets you have fine-grained control over the debug output you
! 597: want to see. An individual flag name may be followed by a level number,
! 598: with 0 meaning to silence that output, 1 being the default output level,
! 599: and higher numbers increasing the output of that flag (for those that
! 600: support higher levels). Use <code>--debug=help</code> to see all the available flag
! 601: names, what they output, and what flag names are added for each increase in
! 602: the verbose level. Some examples:</p>
! 603: <blockquote>
! 604: <pre><code>rsync -avvv --debug=none src/ dest/
! 605: rsync -avA --del --debug=del2,acl src/ dest/
! 606: </code></pre>
! 607: </blockquote>
! 608: <p>Note that some debug messages will only be output when <code>--stderr=all</code> is
! 609: specified, especially those pertaining to I/O and buffer debugging.</p>
! 610: <p>Beginning in 3.2.0, this option is no longer auto-forwarded to the server
! 611: side in order to allow you to specify different debug values for each side
! 612: of the transfer, as well as to specify a new debug option that is only
! 613: present in one of the rsync versions. If you want to duplicate the same
! 614: option on both sides, using brace expansion is an easy way to save you some
! 615: typing. This works in zsh and bash:</p>
! 616: <blockquote>
! 617: <pre><code>rsync -aiv {-M,}--debug=del2 src/ dest/
! 618: </code></pre>
! 619: </blockquote>
! 620: </dd>
! 621:
! 622: <dt><code>--stderr=errors|all|client</code></dt><dd>
! 623: <p>This option controls which processes output to stderr and if info messages
! 624: are also changed to stderr. The mode strings can be abbreviated, so feel
! 625: free to use a single letter value. The 3 possible choices are:</p>
! 626: <ul>
! 627: <li>
! 628: <p><code>errors</code> -⁠ (the default) causes all the rsync processes to send an
! 629: error directly to stderr, even if the process is on the remote side of
! 630: the transfer. Info messages are sent to the client side via the protocol
! 631: stream. If stderr is not available (i.e. when directly connecting with a
! 632: daemon via a socket) errors fall back to being sent via the protocol
! 633: stream.</p>
! 634: </li>
! 635: <li>
! 636: <p><code>all</code> -⁠ causes all rsync messages (info and error) to get written
! 637: directly to stderr from all (possible) processes. This causes stderr to
! 638: become line-buffered (instead of raw) and eliminates the ability to
! 639: divide up the info and error messages by file handle. For those doing
! 640: debugging or using several levels of verbosity, this option can help to
! 641: avoid clogging up the transfer stream (which should prevent any chance of
! 642: a deadlock bug hanging things up). It also enables the outputting of some
! 643: I/O related debug messages.</p>
! 644: </li>
! 645: <li>
! 646: <p><code>client</code> -⁠ causes all rsync messages to be sent to the client side
! 647: via the protocol stream. One client process outputs all messages, with
! 648: errors on stderr and info messages on stdout. This <strong>was</strong> the default
! 649: in older rsync versions, but can cause error delays when a lot of
! 650: transfer data is ahead of the messages. If you're pushing files to an
! 651: older rsync, you may want to use <code>--stderr=all</code> since that idiom has
! 652: been around for several releases.</p>
! 653: </li>
! 654: </ul>
! 655: <p>This option was added in rsync 3.2.3. This version also began the
! 656: forwarding of a non-default setting to the remote side, though rsync uses
! 657: the backward-compatible options <code>--msgs2stderr</code> and <code>--no-msgs2stderr</code> to
! 658: represent the <code>all</code> and <code>client</code> settings, respectively. A newer rsync
! 659: will continue to accept these older option names to maintain compatibility.</p>
! 660: </dd>
! 661:
! 662: <dt><code>--quiet</code>, <code>-q</code></dt><dd>
! 663: <p>This option decreases the amount of information you are given during the
! 664: transfer, notably suppressing information messages from the remote server.
! 665: This option is useful when invoking rsync from cron.</p>
! 666: </dd>
! 667:
! 668: <dt><code>--no-motd</code></dt><dd>
! 669: <p>This option affects the information that is output by the client at the
! 670: start of a daemon transfer. This suppresses the message-of-the-day (MOTD)
! 671: text, but it also affects the list of modules that the daemon sends in
! 672: response to the "rsync host::" request (due to a limitation in the rsync
! 673: protocol), so omit this option if you want to request the list of modules
! 674: from the daemon.</p>
! 675: </dd>
! 676:
! 677: <dt><code>--ignore-times</code>, <code>-I</code></dt><dd>
! 678: <p>Normally rsync will skip any files that are already the same size and have
! 679: the same modification timestamp. This option turns off this "quick check"
! 680: behavior, causing all files to be updated.</p>
! 681: </dd>
! 682:
! 683: <dt><code>--size-only</code></dt><dd>
! 684: <p>This modifies rsync's "quick check" algorithm for finding files that need
! 685: to be transferred, changing it from the default of transferring files with
! 686: either a changed size or a changed last-modified time to just looking for
! 687: files that have changed in size. This is useful when starting to use rsync
! 688: after using another mirroring system which may not preserve timestamps
! 689: exactly.</p>
! 690: </dd>
! 691:
! 692: <dt><code>--date-only</code></dt><dd>
! 693: <p>Normally rsync will skip any files that are already the same size and have
! 694: the same modification time-stamp. With the -⁠-⁠date-only option, files will
! 695: be skipped if they have the same timestamp, regardless of size. This may be
! 696: useful when the remote files have passed through a size-changing filter,
! 697: e.g. for encryption.</p>
! 698: </dd>
! 699:
! 700: <dt><code>--modify-window=NUM</code>, <code>-@</code></dt><dd>
! 701: <p>When comparing two timestamps, rsync treats the timestamps as being equal
! 702: if they differ by no more than the modify-window value. The default is 0,
! 703: which matches just integer seconds. If you specify a negative value (and
! 704: the receiver is at least version 3.1.3) then nanoseconds will also be taken
! 705: into account. Specifying 1 is useful for copies to/from MS Windows FAT
! 706: filesystems, because FAT represents times with a 2-second resolution
! 707: (allowing times to differ from the original by up to 1 second).</p>
! 708: <p>If you want all your transfers to default to comparing nanoseconds, you can
! 709: create a <code>~/.popt</code> file and put these lines in it:</p>
! 710: <blockquote>
! 711: <pre><code>rsync alias -a -a@-1
! 712: rsync alias -t -t@-1
! 713: </code></pre>
! 714: </blockquote>
! 715: <p>With that as the default, you'd need to specify <code>--modify-window=0</code> (aka
! 716: <code>-@0</code>) to override it and ignore nanoseconds, e.g. if you're copying
! 717: between ext3 and ext4, or if the receiving rsync is older than 3.1.3.</p>
! 718: </dd>
! 719:
! 720: <dt><code>--checksum</code>, <code>-c</code></dt><dd>
! 721: <p>This changes the way rsync checks if the files have been changed and are in
! 722: need of a transfer. Without this option, rsync uses a "quick check" that
! 723: (by default) checks if each file's size and time of last modification match
! 724: between the sender and receiver. This option changes this to compare a
! 725: 128-bit checksum for each file that has a matching size. Generating the
! 726: checksums means that both sides will expend a lot of disk I/O reading all
! 727: the data in the files in the transfer, so this can slow things down
! 728: significantly (and this is prior to any reading that will be done to
! 729: transfer changed files)</p>
! 730: <p>The sending side generates its checksums while it is doing the file-system
! 731: scan that builds the list of the available files. The receiver generates
! 732: its checksums when it is scanning for changed files, and will checksum any
! 733: file that has the same size as the corresponding sender's file: files with
! 734: either a changed size or a changed checksum are selected for transfer.</p>
! 735: <p>See also the <code>--sumfiles</code> option for a way to use cached checksum data.</p>
! 736: <p>Note that rsync always verifies that each <u>transferred</u> file was correctly
! 737: reconstructed on the receiving side by checking a whole-file checksum that
! 738: is generated as the file is transferred, but that automatic
! 739: after-the-transfer verification has nothing to do with this option's
! 740: before-the-transfer "Does this file need to be updated?" check.</p>
! 741: <p>The checksum used is auto-negotiated between the client and the server, but
! 742: can be overridden using either the <code>--checksum-choice</code> (<code>--cc</code>) option or an
! 743: environment variable that is discussed in that option's section.</p>
! 744: </dd>
! 745:
! 746: <dt><code>--sumfiles=MODE</code></dt><dd>
! 747: <p>This option tells rsync to make use of any cached checksum information it
! 748: finds in per-directory .rsyncsums files when the current transfer is using
! 749: the <code>--checksum</code> option. If the checksum data is up-to-date, it is used
! 750: instead of recomputing it, saving both disk I/O and CPU time. If the
! 751: checksum data is missing or outdated, the checksum is computed just as it
! 752: would be if <code>--sumfiles</code> was not specified.</p>
! 753: <p>The MODE value is either "lax", for relaxed checking (which compares size
! 754: and mtime), "strict" (which also compares ctime and inode), or "none" to
! 755: ignore any .rsyncsums files ("none" is the default).
! 756: If you want rsync to create and/or update these files, specify a prefixed
! 757: plus ("+lax" or "+strict"). Adding a second prefixed '+' causes the
! 758: checksum-file updates to happen even when the transfer is in <code>--dry-run</code>
! 759: mode ("++lax" or "++strict"). There is also a perl script in the support
! 760: directory named "rsyncsums" that can be used to update the .rsyncsums
! 761: files.</p>
! 762: <p>This option has no effect unless <code>--checksum</code>, <code>-c</code> was also specified. It
! 763: also only affects the current side of the transfer, so if you want the
! 764: remote side to parse its own .rsyncsums files, specify the option via
! 765: <code>--remote-option</code> (<code>-M</code>) (e.g. "<code>-M--sumfiles=lax</code>").</p>
! 766: <p>To avoid transferring the system's checksum files, you can use an exclude
! 767: (e.g. <code>--exclude=.rsyncsums</code>). To make this easier to type, you can use a
! 768: popt alias. For instance, adding the following line in your ~/.popt file
! 769: defines a <code>--cs</code> option that enables lax checksum files and excludes the
! 770: checksum files:</p>
! 771: <blockquote>
! 772: <pre><code>rsync alias --cs -c --sumfiles=lax -M--sumfiles=lax -f-_.rsyncsums
! 773: </code></pre>
! 774: </blockquote>
! 775: <p>An rsync daemon does not allow the client to control this setting, so see
! 776: the "checksum files" daemon parameter for information on how to make a
! 777: daemon use cached checksum data.</p>
! 778: </dd>
! 779:
! 780: <dt><code>--archive</code>, <code>-a</code></dt><dd>
! 781: <p>This is equivalent to <code>-rlptgoD</code>. It is a quick way of saying you want
! 782: recursion and want to preserve almost everything (with <code>-H</code> being a notable
! 783: omission). The only exception to the above equivalence is when
! 784: <code>--files-from</code> is specified, in which case <code>-r</code> is not implied.</p>
! 785: <p>Note that <code>-a</code> <strong>does not preserve hardlinks</strong>, because finding
! 786: multiply-linked files is expensive. You must separately specify <code>-H</code>.
! 787: Note also that for backward compatibility, <code>-a</code> currently does <strong>not</strong>
! 788: imply the <code>--fileflags</code> option.</p>
! 789: </dd>
! 790:
! 791: <dt><code>--no-OPTION</code></dt><dd>
! 792: <p>You may turn off one or more implied options by prefixing the option name
! 793: with "no-". Not all options may be prefixed with a "no-": only options that
! 794: are implied by other options (e.g. <code>--no-D</code>, <code>--no-perms</code>) or have
! 795: different defaults in various circumstances (e.g. <code>--no-whole-file</code>,
! 796: <code>--no-blocking-io</code>, <code>--no-dirs</code>). You may specify either the short or the
! 797: long option name after the "no-" prefix (e.g. <code>--no-R</code> is the same as
! 798: <code>--no-relative</code>).</p>
! 799: <p>For example: if you want to use <code>-a</code> (<code>--archive</code>) but don't want <code>-o</code>
! 800: (<code>--owner</code>), instead of converting <code>-a</code> into <code>-rlptgD</code>, you could specify
! 801: <code>-a --no-o</code> (or <code>-a --no-owner</code>).</p>
! 802: <p>The order of the options is important: if you specify <code>--no-r -a</code>, the
! 803: <code>-r</code> option would end up being turned on, the opposite of <code>-a --no-r</code>.
! 804: Note also that the side-effects of the <code>--files-from</code> option are NOT
! 805: positional, as it affects the default state of several options and slightly
! 806: changes the meaning of <code>-a</code> (see the <code>--files-from</code> option for more
! 807: details).</p>
! 808: </dd>
! 809:
! 810: <dt><code>--recursive</code>, <code>-r</code></dt><dd>
! 811: <p>This tells rsync to copy directories recursively. See also <code>--dirs</code> (<code>-d</code>).</p>
! 812: <p>Beginning with rsync 3.0.0, the recursive algorithm used is now an
! 813: incremental scan that uses much less memory than before and begins the
! 814: transfer after the scanning of the first few directories have been
! 815: completed. This incremental scan only affects our recursion algorithm, and
! 816: does not change a non-recursive transfer. It is also only possible when
! 817: both ends of the transfer are at least version 3.0.0.</p>
! 818: <p>Some options require rsync to know the full file list, so these options
! 819: disable the incremental recursion mode. These include: <code>--delete-before</code>,
! 820: <code>--delete-after</code>, <code>--prune-empty-dirs</code>, and <code>--delay-updates</code>. Because of
! 821: this, the default delete mode when you specify <code>--delete</code> is now
! 822: <code>--delete-during</code> when both ends of the connection are at least 3.0.0 (use
! 823: <code>--del</code> or <code>--delete-during</code> to request this improved deletion mode
! 824: explicitly). See also the <code>--delete-delay</code> option that is a better choice
! 825: than using <code>--delete-after</code>.</p>
! 826: <p>Incremental recursion can be disabled using the <code>--no-inc-recursive</code> option
! 827: or its shorter <code>--no-i-r</code> alias.</p>
! 828: </dd>
! 829:
! 830: <dt><code>--relative</code>, <code>-R</code></dt><dd>
! 831: <p>Use relative paths. This means that the full path names specified on the
! 832: command line are sent to the server rather than just the last parts of the
! 833: filenames. This is particularly useful when you want to send several
! 834: different directories at the same time. For example, if you used this
! 835: command:</p>
! 836: <blockquote>
! 837: <pre><code>rsync -av /foo/bar/baz.c remote:/tmp/
! 838: </code></pre>
! 839: </blockquote>
! 840: <p>would create a file named baz.c in /tmp/ on the remote machine. If instead
! 841: you used</p>
! 842: <blockquote>
! 843: <pre><code>rsync -avR /foo/bar/baz.c remote:/tmp/
! 844: </code></pre>
! 845: </blockquote>
! 846: <p>then a file named /tmp/foo/bar/baz.c would be created on the remote
! 847: machine, preserving its full path. These extra path elements are called
! 848: "implied directories" (i.e. the "foo" and the "foo/bar" directories in the
! 849: above example).</p>
! 850: <p>Beginning with rsync 3.0.0, rsync always sends these implied directories as
! 851: real directories in the file list, even if a path element is really a
! 852: symlink on the sending side. This prevents some really unexpected behaviors
! 853: when copying the full path of a file that you didn't realize had a symlink
! 854: in its path. If you want to duplicate a server-side symlink, include both
! 855: the symlink via its path, and referent directory via its real path. If
! 856: you're dealing with an older rsync on the sending side, you may need to use
! 857: the <code>--no-implied-dirs</code> option.</p>
! 858: <p>It is also possible to limit the amount of path information that is sent as
! 859: implied directories for each path you specify. With a modern rsync on the
! 860: sending side (beginning with 2.6.7), you can insert a dot and a slash into
! 861: the source path, like this:</p>
! 862: <blockquote>
! 863: <pre><code>rsync -avR /foo/./bar/baz.c remote:/tmp/
! 864: </code></pre>
! 865: </blockquote>
! 866: <p>That would create /tmp/bar/baz.c on the remote machine. (Note that the dot
! 867: must be followed by a slash, so "/foo/." would not be abbreviated.) For
! 868: older rsync versions, you would need to use a chdir to limit the source
! 869: path. For example, when pushing files:</p>
! 870: <blockquote>
! 871: <pre><code>(cd /foo; rsync -avR bar/baz.c remote:/tmp/)
! 872: </code></pre>
! 873: </blockquote>
! 874: <p>(Note that the parens put the two commands into a sub-shell, so that the
! 875: "cd" command doesn't remain in effect for future commands.) If you're
! 876: pulling files from an older rsync, use this idiom (but only for a
! 877: non-daemon transfer):</p>
! 878: <blockquote>
! 879: <pre><code>rsync -avR --rsync-path="cd /foo; rsync" \
! 880: remote:bar/baz.c /tmp/
! 881: </code></pre>
! 882: </blockquote>
! 883: </dd>
! 884:
! 885: <dt><code>--no-implied-dirs</code></dt><dd>
! 886: <p>This option affects the default behavior of the <code>--relative</code> option. When
! 887: it is specified, the attributes of the implied directories from the source
! 888: names are not included in the transfer. This means that the corresponding
! 889: path elements on the destination system are left unchanged if they exist,
! 890: and any missing implied directories are created with default attributes.
! 891: This even allows these implied path elements to have big differences, such
! 892: as being a symlink to a directory on the receiving side.</p>
! 893: <p>For instance, if a command-line arg or a files-from entry told rsync to
! 894: transfer the file "path/foo/file", the directories "path" and "path/foo"
! 895: are implied when <code>--relative</code> is used. If "path/foo" is a symlink to "bar"
! 896: on the destination system, the receiving rsync would ordinarily delete
! 897: "path/foo", recreate it as a directory, and receive the file into the new
! 898: directory. With <code>--no-implied-dirs</code>, the receiving rsync updates
! 899: "path/foo/file" using the existing path elements, which means that the file
! 900: ends up being created in "path/bar". Another way to accomplish this link
! 901: preservation is to use the <code>--keep-dirlinks</code> option (which will also affect
! 902: symlinks to directories in the rest of the transfer).</p>
! 903: <p>When pulling files from an rsync older than 3.0.0, you may need to use this
! 904: option if the sending side has a symlink in the path you request and you
! 905: wish the implied directories to be transferred as normal directories.</p>
! 906: </dd>
! 907:
! 908: <dt><code>--backup</code>, <code>-b</code></dt><dd>
! 909: <p>With this option, preexisting destination files are renamed as each file is
! 910: transferred or deleted. You can control where the backup file goes and
! 911: what (if any) suffix gets appended using the <code>--backup-dir</code> and <code>--suffix</code>
! 912: options.</p>
! 913: <p>Note that if you don't specify <code>--backup-dir</code>, (1) the <code>--omit-dir-times</code>
! 914: option will be forced on, and (2) if <code>--delete</code> is also in effect (without
! 915: <code>--delete-excluded</code>), rsync will add a "protect" filter-rule for the backup
! 916: suffix to the end of all your existing excludes (e.g. <code>-f "P *~"</code>). This
! 917: will prevent previously backed-up files from being deleted. Note that if
! 918: you are supplying your own filter rules, you may need to manually insert
! 919: your own exclude/protect rule somewhere higher up in the list so that it
! 920: has a high enough priority to be effective (e.g., if your rules specify a
! 921: trailing inclusion/exclusion of <code>*</code>, the auto-added rule would never be
! 922: reached).</p>
! 923: </dd>
! 924:
! 925: <dt>-⁠-⁠backup-deleted</dt><dd>
! 926: <p>With this option, deleted destination files are renamed, while modified
! 927: destination files are not. Otherwise, this option behaves the same as
! 928: <code>--backup</code>, described above. Note that if <code>--backup</code> is also specified,
! 929: whichever option is specified last takes precedence.</p>
! 930: </dd>
! 931:
! 932: <dt><code>--backup-dir=DIR</code></dt><dd>
! 933: <p>This implies the <code>--backup</code> option, and tells rsync to store all
! 934: backups in the specified directory on the receiving side. This can be used
! 935: for incremental backups. You can additionally specify a backup suffix
! 936: using the <code>--suffix</code> option (otherwise the files backed up in the specified
! 937: directory will keep their original filenames).</p>
! 938: <p>Note that if you specify a relative path, the backup directory will be
! 939: relative to the destination directory, so you probably want to specify
! 940: either an absolute path or a path that starts with "../". If an rsync
! 941: daemon is the receiver, the backup dir cannot go outside the module's path
! 942: hierarchy, so take extra care not to delete it or copy into it.</p>
! 943: </dd>
! 944:
! 945: <dt><code>--suffix=SUFFIX</code></dt><dd>
! 946: <p>This option allows you to override the default backup suffix used with the
! 947: <code>--backup</code> (<code>-b</code>) option. The default suffix is a <code>~</code> if no <code>--backup-dir</code>
! 948: was specified, otherwise it is an empty string.</p>
! 949: </dd>
! 950:
! 951: <dt><code>--update</code>, <code>-u</code></dt><dd>
! 952: <p>This forces rsync to skip any files which exist on the destination and have
! 953: a modified time that is newer than the source file. (If an existing
! 954: destination file has a modification time equal to the source file's, it
! 955: will be updated if the sizes are different.)</p>
! 956: <p>Note that this does not affect the copying of dirs, symlinks, or other
! 957: special files. Also, a difference of file format between the sender and
! 958: receiver is always considered to be important enough for an update, no
! 959: matter what date is on the objects. In other words, if the source has a
! 960: directory where the destination has a file, the transfer would occur
! 961: regardless of the timestamps.</p>
! 962: <p>This option is a transfer rule, not an exclude, so it doesn't affect the
! 963: data that goes into the file-lists, and thus it doesn't affect deletions.
! 964: It just limits the files that the receiver requests to be transferred.</p>
! 965: </dd>
! 966:
! 967: <dt><code>--inplace</code></dt><dd>
! 968: <p>This option changes how rsync transfers a file when its data needs to be
! 969: updated: instead of the default method of creating a new copy of the file
! 970: and moving it into place when it is complete, rsync instead writes the
! 971: updated data directly to the destination file.</p>
! 972: <p>This has several effects:</p>
! 973: <ul>
! 974: <li>Hard links are not broken. This means the new data will be visible
! 975: through other hard links to the destination file. Moreover, attempts to
! 976: copy differing source files onto a multiply-linked destination file will
! 977: result in a "tug of war" with the destination data changing back and
! 978: forth.</li>
! 979: <li>In-use binaries cannot be updated (either the OS will prevent this from
! 980: happening, or binaries that attempt to swap-in their data will misbehave
! 981: or crash).</li>
! 982: <li>The file's data will be in an inconsistent state during the transfer and
! 983: will be left that way if the transfer is interrupted or if an update
! 984: fails.</li>
! 985: <li>A file that rsync cannot write to cannot be updated. While a super user
! 986: can update any file, a normal user needs to be granted write permission
! 987: for the open of the file for writing to be successful.</li>
! 988: <li>The efficiency of rsync's delta-transfer algorithm may be reduced if some
! 989: data in the destination file is overwritten before it can be copied to a
! 990: position later in the file. This does not apply if you use <code>--backup</code>,
! 991: since rsync is smart enough to use the backup file as the basis file for
! 992: the transfer.</li>
! 993: </ul>
! 994: <p>WARNING: you should not use this option to update files that are being
! 995: accessed by others, so be careful when choosing to use this for a copy.</p>
! 996: <p>This option is useful for transferring large files with block-based changes
! 997: or appended data, and also on systems that are disk bound, not network
! 998: bound. It can also help keep a copy-on-write filesystem snapshot from
! 999: diverging the entire contents of a file that only has minor changes.</p>
! 1000: <p>The option implies <code>--partial</code> (since an interrupted transfer does not
! 1001: delete the file), but conflicts with <code>--partial-dir</code> and <code>--delay-updates</code>.
! 1002: Prior to rsync 2.6.4 <code>--inplace</code> was also incompatible with
! 1003: <code>--compare-dest</code> and <code>--link-dest</code>.</p>
! 1004: </dd>
! 1005:
! 1006: <dt><code>--append</code></dt><dd>
! 1007: <p>This special copy mode only works to efficiently update files that are
! 1008: known to be growing larger where any existing content on the receiving side
! 1009: is also known to be the same as the content on the sender. The use of
! 1010: <code>--append</code> <strong>can be dangerous</strong> if you aren't 100% sure that all the files
! 1011: in the transfer are shared, growing files. You should thus use filter
! 1012: rules to ensure that you weed out any files that do not fit this criteria.</p>
! 1013: <p>Rsync updates these growing file in-place without verifying any of the
! 1014: existing content in the file (it only verifies the content that it is
! 1015: appending). Rsync skips any files that exist on the receiving side that
! 1016: are not shorter than the associated file on the sending side (which means
! 1017: that new files are trasnferred).</p>
! 1018: <p>This does not interfere with the updating of a file's non-content
! 1019: attributes (e.g. permissions, ownership, etc.) when the file does not need
! 1020: to be transferred, nor does it affect the updating of any directories or
! 1021: non-regular files.</p>
! 1022: </dd>
! 1023:
! 1024: <dt><code>--append-verify</code></dt><dd>
! 1025: <p>This special copy mode works like <code>--append</code> except that all the data in
! 1026: the file is included in the checksum verification (making it much less
! 1027: efficient but also potentially safer). This option <strong>can be dangerous</strong> if
! 1028: you aren't 100% sure that all the files in the transfer are shared, growing
! 1029: files. See the <code>--append</code> option for more details.</p>
! 1030: <p>Note: prior to rsync 3.0.0, the <code>--append</code> option worked like
! 1031: <code>--append-verify</code>, so if you are interacting with an older rsync (or the
! 1032: transfer is using a protocol prior to 30), specifying either append option
! 1033: will initiate an <code>--append-verify</code> transfer.</p>
! 1034: </dd>
! 1035:
! 1036: <dt><code>--dirs</code>, <code>-d</code></dt><dd>
! 1037: <p>Tell the sending side to include any directories that are encountered.
! 1038: Unlike <code>--recursive</code>, a directory's contents are not copied unless the
! 1039: directory name specified is "." or ends with a trailing slash (e.g. ".",
! 1040: "dir/.", "dir/", etc.). Without this option or the <code>--recursive</code> option,
! 1041: rsync will skip all directories it encounters (and output a message to that
! 1042: effect for each one). If you specify both <code>--dirs</code> and <code>--recursive</code>,
! 1043: <code>--recursive</code> takes precedence.</p>
! 1044: <p>The <code>--dirs</code> option is implied by the <code>--files-from</code> option or the
! 1045: <code>--list-only</code> option (including an implied <code>--list-only</code> usage) if
! 1046: <code>--recursive</code> wasn't specified (so that directories are seen in the
! 1047: listing). Specify <code>--no-dirs</code> (or <code>--no-d</code>) if you want to turn this off.</p>
! 1048: <p>There is also a backward-compatibility helper option, <code>--old-dirs</code> (or
! 1049: <code>--old-d</code>) that tells rsync to use a hack of <code>-r --exclude='/*/*'</code> to get
! 1050: an older rsync to list a single directory without recursing.</p>
! 1051: </dd>
! 1052:
! 1053: <dt><code>--mkpath</code></dt><dd>
! 1054: <p>Create a missing path component of the destination arg. This allows rsync
! 1055: to create multiple levels of missing destination dirs and to create a path
! 1056: in which to put a single renamed file. Keep in mind that you'll need to
! 1057: supply a trailing slash if you want the entire destination path to be
! 1058: treated as a directory when copying a single arg (making rsync behave the
! 1059: same way that it would if the path component of the destination had already
! 1060: existed).</p>
! 1061: <p>For example, the following creates a copy of file foo as bar in the sub/dir
! 1062: directory, creating dirs "sub" and "sub/dir" if either do not yet exist:</p>
! 1063: <blockquote>
! 1064: <pre><code>rsync -ai --mkpath foo sub/dir/bar
! 1065: </code></pre>
! 1066: </blockquote>
! 1067: <p>If you instead ran the following, it would have created file foo in the
! 1068: sub/dir/bar directory:</p>
! 1069: <blockquote>
! 1070: <pre><code>rsync -ai --mkpath foo sub/dir/bar/
! 1071: </code></pre>
! 1072: </blockquote>
! 1073: </dd>
! 1074:
! 1075: <dt><code>--links</code>, <code>-l</code></dt><dd>
! 1076: <p>When symlinks are encountered, recreate the symlink on the destination.</p>
! 1077: </dd>
! 1078:
! 1079: <dt><code>--copy-links</code>, <code>-L</code></dt><dd>
! 1080: <p>When symlinks are encountered, the item that they point to (the referent)
! 1081: is copied, rather than the symlink. In older versions of rsync, this
! 1082: option also had the side-effect of telling the receiving side to follow
! 1083: symlinks, such as symlinks to directories. In a modern rsync such as this
! 1084: one, you'll need to specify <code>--keep-dirlinks</code> (<code>-K</code>) to get this extra
! 1085: behavior. The only exception is when sending files to an rsync that is too
! 1086: old to understand <code>-K</code> -⁠-⁠ in that case, the <code>-L</code> option will still have the
! 1087: side-effect of <code>-K</code> on that older receiving rsync.</p>
! 1088: </dd>
! 1089:
! 1090: <dt><code>--copy-unsafe-links</code></dt><dd>
! 1091: <p>This tells rsync to copy the referent of symbolic links that point outside
! 1092: the copied tree. Absolute symlinks are also treated like ordinary files,
! 1093: and so are any symlinks in the source path itself when <code>--relative</code> is
! 1094: used. This option has no additional effect if <code>--copy-links</code> was also
! 1095: specified.</p>
! 1096: <p>Note that the cut-off point is the top of the transfer, which is the part
! 1097: of the path that rsync isn't mentioning in the verbose output. If you copy
! 1098: "/src/subdir" to "/dest/" then the "subdir" directory is a name inside the
! 1099: transfer tree, not the top of the transfer (which is /src) so it is legal
! 1100: for created relative symlinks to refer to other names inside the /src and
! 1101: /dest directories. If you instead copy "/src/subdir/" (with a trailing
! 1102: slash) to "/dest/subdir" that would not allow symlinks to any files outside
! 1103: of "subdir".</p>
! 1104: </dd>
! 1105:
! 1106: <dt><code>--safe-links</code></dt><dd>
! 1107: <p>This tells rsync to ignore any symbolic links which point outside the
! 1108: copied tree. All absolute symlinks are also ignored. Using this option in
! 1109: conjunction with <code>--relative</code> may give unexpected results.</p>
! 1110: </dd>
! 1111:
! 1112: <dt><code>--munge-links</code></dt><dd>
! 1113: <p>This option tells rsync to (1) modify all symlinks on the receiving side in
! 1114: a way that makes them unusable but recoverable (see below), or (2) to
! 1115: unmunge symlinks on the sending side that had been stored in a munged
! 1116: state. This is useful if you don't quite trust the source of the data to
! 1117: not try to slip in a symlink to a unexpected place.</p>
! 1118: <p>The way rsync disables the use of symlinks is to prefix each one with the
! 1119: string "/rsyncd-munged/". This prevents the links from being used as long
! 1120: as that directory does not exist. When this option is enabled, rsync will
! 1121: refuse to run if that path is a directory or a symlink to a directory.</p>
! 1122: <p>The option only affects the client side of the transfer, so if you need it
! 1123: to affect the server, specify it via <code>--remote-option</code>. (Note that in a
! 1124: local transfer, the client side is the sender.)</p>
! 1125: <p>This option has no affect on a daemon, since the daemon configures whether
! 1126: it wants munged symlinks via its "<code>munge symlinks</code>" parameter. See also the
! 1127: "munge-symlinks" perl script in the support directory of the source code.</p>
! 1128: </dd>
! 1129:
! 1130: <dt><code>--copy-dirlinks</code>, <code>-k</code></dt><dd>
! 1131: <p>This option causes the sending side to treat a symlink to a directory as
! 1132: though it were a real directory. This is useful if you don't want symlinks
! 1133: to non-directories to be affected, as they would be using <code>--copy-links</code>.</p>
! 1134: <p>Without this option, if the sending side has replaced a directory with a
! 1135: symlink to a directory, the receiving side will delete anything that is in
! 1136: the way of the new symlink, including a directory hierarchy (as long as
! 1137: <code>--force-delete</code> or <code>--delete</code> is in effect).</p>
! 1138: <p>See also <code>--keep-dirlinks</code> for an analogous option for the receiving side.</p>
! 1139: <p><code>--copy-dirlinks</code> applies to all symlinks to directories in the source. If
! 1140: you want to follow only a few specified symlinks, a trick you can use is to
! 1141: pass them as additional source args with a trailing slash, using
! 1142: <code>--relative</code> to make the paths match up right. For example:</p>
! 1143: <blockquote>
! 1144: <pre><code>rsync -r --relative src/./ src/./follow-me/ dest/
! 1145: </code></pre>
! 1146: </blockquote>
! 1147: <p>This works because rsync calls <strong>lstat</strong>(2) on the source arg as given, and
! 1148: the trailing slash makes <strong>lstat</strong>(2) follow the symlink, giving rise to a
! 1149: directory in the file-list which overrides the symlink found during the
! 1150: scan of "src/./".</p>
! 1151: </dd>
! 1152:
! 1153: <dt><code>--keep-dirlinks</code>, <code>-K</code></dt><dd>
! 1154: <p>This option causes the receiving side to treat a symlink to a directory as
! 1155: though it were a real directory, but only if it matches a real directory
! 1156: from the sender. Without this option, the receiver's symlink would be
! 1157: deleted and replaced with a real directory.</p>
! 1158: <p>For example, suppose you transfer a directory "foo" that contains a file
! 1159: "file", but "foo" is a symlink to directory "bar" on the receiver. Without
! 1160: <code>--keep-dirlinks</code>, the receiver deletes symlink "foo", recreates it as a
! 1161: directory, and receives the file into the new directory. With
! 1162: <code>--keep-dirlinks</code>, the receiver keeps the symlink and "file" ends up in
! 1163: "bar".</p>
! 1164: <p>One note of caution: if you use <code>--keep-dirlinks</code>, you must trust all the
! 1165: symlinks in the copy! If it is possible for an untrusted user to create
! 1166: their own symlink to any directory, the user could then (on a subsequent
! 1167: copy) replace the symlink with a real directory and affect the content of
! 1168: whatever directory the symlink references. For backup copies, you are
! 1169: better off using something like a bind mount instead of a symlink to modify
! 1170: your receiving hierarchy.</p>
! 1171: <p>See also <code>--copy-dirlinks</code> for an analogous option for the sending side.</p>
! 1172: </dd>
! 1173:
! 1174: <dt><code>--hard-links</code>, <code>-H</code></dt><dd>
! 1175: <p>This tells rsync to look for hard-linked files in the source and link
! 1176: together the corresponding files on the destination. Without this option,
! 1177: hard-linked files in the source are treated as though they were separate
! 1178: files.</p>
! 1179: <p>This option does NOT necessarily ensure that the pattern of hard links on
! 1180: the destination exactly matches that on the source. Cases in which the
! 1181: destination may end up with extra hard links include the following:</p>
! 1182: <ul>
! 1183: <li>If the destination contains extraneous hard-links (more linking than what
! 1184: is present in the source file list), the copying algorithm will not break
! 1185: them explicitly. However, if one or more of the paths have content
! 1186: differences, the normal file-update process will break those extra links
! 1187: (unless you are using the <code>--inplace</code> option).</li>
! 1188: <li>If you specify a <code>--link-dest</code> directory that contains hard links, the
! 1189: linking of the destination files against the <code>--link-dest</code> files can
! 1190: cause some paths in the destination to become linked together due to the
! 1191: <code>--link-dest</code> associations.</li>
! 1192: </ul>
! 1193: <p>Note that rsync can only detect hard links between files that are inside
! 1194: the transfer set. If rsync updates a file that has extra hard-link
! 1195: connections to files outside the transfer, that linkage will be broken. If
! 1196: you are tempted to use the <code>--inplace</code> option to avoid this breakage, be
! 1197: very careful that you know how your files are being updated so that you are
! 1198: certain that no unintended changes happen due to lingering hard links (and
! 1199: see the <code>--inplace</code> option for more caveats).</p>
! 1200: <p>If incremental recursion is active (see <code>--recursive</code>), rsync may transfer
! 1201: a missing hard-linked file before it finds that another link for that
! 1202: contents exists elsewhere in the hierarchy. This does not affect the
! 1203: accuracy of the transfer (i.e. which files are hard-linked together), just
! 1204: its efficiency (i.e. copying the data for a new, early copy of a
! 1205: hard-linked file that could have been found later in the transfer in
! 1206: another member of the hard-linked set of files). One way to avoid this
! 1207: inefficiency is to disable incremental recursion using the
! 1208: <code>--no-inc-recursive</code> option.</p>
! 1209: </dd>
! 1210:
! 1211: <dt><code>--perms</code>, <code>-p</code></dt><dd>
! 1212: <p>This option causes the receiving rsync to set the destination permissions
! 1213: to be the same as the source permissions. (See also the <code>--chmod</code> option
! 1214: for a way to modify what rsync considers to be the source permissions.)</p>
! 1215: <p>When this option is <u>off</u>, permissions are set as follows:</p>
! 1216: <ul>
! 1217: <li>Existing files (including updated files) retain their existing
! 1218: permissions, though the <code>--executability</code> option might change just the
! 1219: execute permission for the file.</li>
! 1220: <li>New files get their "normal" permission bits set to the source file's
! 1221: permissions masked with the receiving directory's default permissions
! 1222: (either the receiving process's umask, or the permissions specified via
! 1223: the destination directory's default ACL), and their special permission
! 1224: bits disabled except in the case where a new directory inherits a setgid
! 1225: bit from its parent directory.</li>
! 1226: </ul>
! 1227: <p>Thus, when <code>--perms</code> and <code>--executability</code> are both disabled, rsync's
! 1228: behavior is the same as that of other file-copy utilities, such as <strong>cp</strong>(1)
! 1229: and <strong>tar</strong>(1).</p>
! 1230: <p>In summary: to give destination files (both old and new) the source
! 1231: permissions, use <code>--perms</code>. To give new files the destination-default
! 1232: permissions (while leaving existing files unchanged), make sure that the
! 1233: <code>--perms</code> option is off and use <code>--chmod=ugo=rwX</code> (which ensures that all
! 1234: non-masked bits get enabled). If you'd care to make this latter behavior
! 1235: easier to type, you could define a popt alias for it, such as putting this
! 1236: line in the file <code>~/.popt</code> (the following defines the <code>-Z</code> option, and
! 1237: includes <code>--no-g</code> to use the default group of the destination dir):</p>
! 1238: <blockquote>
! 1239: <pre><code> rsync alias -Z --no-p --no-g --chmod=ugo=rwX
! 1240: </code></pre>
! 1241: </blockquote>
! 1242: <p>You could then use this new option in a command such as this one:</p>
! 1243: <blockquote>
! 1244: <pre><code> rsync -avZ src/ dest/
! 1245: </code></pre>
! 1246: </blockquote>
! 1247: <p>(Caveat: make sure that <code>-a</code> does not follow <code>-Z</code>, or it will re-enable the
! 1248: two <code>--no-*</code> options mentioned above.)</p>
! 1249: <p>The preservation of the destination's setgid bit on newly-created
! 1250: directories when <code>--perms</code> is off was added in rsync 2.6.7. Older rsync
! 1251: versions erroneously preserved the three special permission bits for
! 1252: newly-created files when <code>--perms</code> was off, while overriding the
! 1253: destination's setgid bit setting on a newly-created directory. Default ACL
! 1254: observance was added to the ACL patch for rsync 2.6.7, so older (or
! 1255: non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
! 1256: (Keep in mind that it is the version of the receiving rsync that affects
! 1257: these behaviors.)</p>
! 1258: </dd>
! 1259:
! 1260: <dt><code>--executability</code>, <code>-E</code></dt><dd>
! 1261: <p>This option causes rsync to preserve the executability (or
! 1262: non-executability) of regular files when <code>--perms</code> is not enabled. A
! 1263: regular file is considered to be executable if at least one 'x' is turned
! 1264: on in its permissions. When an existing destination file's executability
! 1265: differs from that of the corresponding source file, rsync modifies the
! 1266: destination file's permissions as follows:</p>
! 1267: <ul>
! 1268: <li>To make a file non-executable, rsync turns off all its 'x' permissions.</li>
! 1269: <li>To make a file executable, rsync turns on each 'x' permission that has a
! 1270: corresponding 'r' permission enabled.</li>
! 1271: </ul>
! 1272: <p>If <code>--perms</code> is enabled, this option is ignored.</p>
! 1273: </dd>
! 1274:
! 1275: <dt><code>--acls</code>, <code>-A</code></dt><dd>
! 1276: <p>This option causes rsync to update the destination ACLs to be the same as
! 1277: the source ACLs. The option also implies <code>--perms</code>.</p>
! 1278: <p>The source and destination systems must have compatible ACL entries for
! 1279: this option to work properly. See the <code>--fake-super</code> option for a way to
! 1280: backup and restore ACLs that are not compatible.</p>
! 1281: </dd>
! 1282:
! 1283: <dt><code>--xattrs</code>, <code>-X</code></dt><dd>
! 1284: <p>This option causes rsync to update the destination extended attributes to
! 1285: be the same as the source ones.</p>
! 1286: <p>For systems that support extended-attribute namespaces, a copy being done
! 1287: by a super-user copies all namespaces except system.*. A normal user only
! 1288: copies the user.* namespace. To be able to backup and restore non-user
! 1289: namespaces as a normal user, see the <code>--fake-super</code> option.</p>
! 1290: <p>The above name filtering can be overridden by using one or more filter
! 1291: options with the <strong>x</strong> modifier. When you specify an xattr-affecting
! 1292: filter rule, rsync requires that you do your own system/user filtering, as
! 1293: well as any additional filtering for what xattr names are copied and what
! 1294: names are allowed to be deleted. For example, to skip the system
! 1295: namespace, you could specify:</p>
! 1296: <blockquote>
! 1297: <pre><code>--filter='-x system.*'
! 1298: </code></pre>
! 1299: </blockquote>
! 1300: <p>To skip all namespaces except the user namespace, you could specify a
! 1301: negated-user match:</p>
! 1302: <blockquote>
! 1303: <pre><code>--filter='-x! user.*'
! 1304: </code></pre>
! 1305: </blockquote>
! 1306: <p>To prevent any attributes from being deleted, you could specify a
! 1307: receiver-only rule that excludes all names:</p>
! 1308: <blockquote>
! 1309: <pre><code>--filter='-xr *'
! 1310: </code></pre>
! 1311: </blockquote>
! 1312: <p>Note that the <code>-X</code> option does not copy rsync's special xattr values (e.g.
! 1313: those used by <code>--fake-super</code>) unless you repeat the option (e.g. <code>-XX</code>).
! 1314: This "copy all xattrs" mode cannot be used with <code>--fake-super</code>.</p>
! 1315: </dd>
! 1316:
! 1317: <dt><code>--fileflags</code> This option causes rsync to update the file-flags to be the
! 1318: same as the source files and directories (if your OS supports the
! 1319: <strong>chflags</strong>(2) system call). Some flags can only be altered by the
! 1320: super-user and some might only be unset below a certain secure-level
! 1321: (usually single-user mode). It will not make files alterable that are set
! 1322: to immutable on the receiver. To do that, see <code>--force-change</code>,
! 1323: <code>--force-uchange</code>, and <code>--force-schange</code>.</dt><dd>
! 1324: </dd>
! 1325:
! 1326: <dt><code>--force-change</code> This option causes rsync to disable both user-immutable
! 1327: and system-immutable flags on files and directories that are being updated
! 1328: or deleted on the receiving side. This option overrides <code>--force-uchange</code>
! 1329: and <code>--force-schange</code>.</dt><dd>
! 1330: </dd>
! 1331:
! 1332: <dt><code>--force-uchange</code> This option causes rsync to disable user-immutable flags
! 1333: on files and directories that are being updated or deleted on the receiving
! 1334: side. It does not try to affect system flags. This option overrides
! 1335: <code>--force-change</code> and <code>--force-schange</code>.</dt><dd>
! 1336: </dd>
! 1337:
! 1338: <dt><code>--force-schange</code> This option causes rsync to disable system-immutable
! 1339: flags on files and directories that are being updated or deleted on the
! 1340: receiving side. It does not try to affect user flags. This option
! 1341: overrides <code>--force-change</code> and <code>--force-uchange</code>.</dt><dd>
! 1342: </dd>
! 1343:
! 1344: <dt><code>--hfs-compression</code></dt><dd>
! 1345: <p>This option causes rsync to preserve HFS+ compression if the destination
! 1346: filesystem supports it. If the destination does not support it, rsync will
! 1347: exit with an error.</p>
! 1348: <p>Filesystem compression was introduced to HFS+ in Mac OS 10.6. A file that
! 1349: is compressed has no data in its data fork. Rather, the compressed data is
! 1350: stored in an extended attribute named com.apple.decmpfs and a file flag is
! 1351: set to indicate that the file is compressed (UF_COMPRESSED). HFS+
! 1352: decompresses this data "on-the-fly" and presents it to the operating system
! 1353: as a normal file. Normal attempts to copy compressed files (e.g. in the
! 1354: Finder, via cp, ditto, etc.) will copy the file's decompressed contents,
! 1355: remove the UF_COMPRESSED file flag, and discard the com.apple.decmpfs
! 1356: extended attribute. This option will preserve the data in the
! 1357: com.apple.decmpfs extended attribute and ignore the synthesized data in the
! 1358: file contents.</p>
! 1359: <p>This option implies both <code>--fileflags</code> and (-⁠-⁠xattrs).</p>
! 1360: </dd>
! 1361:
! 1362: <dt><code>--protect-decmpfs</code></dt><dd>
! 1363: <p>The com.apple.decmpfs extended attribute is hidden by default from list/get
! 1364: xattr calls, therefore normal attempts to copy compressed files will
! 1365: functionally decompress those files. While this is desirable behavior when
! 1366: copying files to filesystems that do not support HFS+ compression, it has
! 1367: serious performance and capacity impacts when backing up or restoring the
! 1368: Mac OS X filesystem.</p>
! 1369: <p>This option will transfer the com.apple.decmpfs extended attribute
! 1370: regardless of support on the destination. If a source file is compressed
! 1371: and an existing file on the destination is not compressed, the data fork of
! 1372: the destination file will be truncated and the com.apple.decmpfs xattr will
! 1373: be transferred instead. Note that compressed files will not be readable to
! 1374: the operating system of the destination if that operating system does not
! 1375: support HFS+ compression. Once restored (with or without this option) to an
! 1376: operating system that supports HFS+ compression, however, these files will
! 1377: be accessible as usual.</p>
! 1378: <p>This option implies <code>--fileflags</code> and <code>--xattrs</code>.</p>
! 1379: </dd>
! 1380:
! 1381: <dt><code>--chmod=CHMOD</code></dt><dd>
! 1382: <p>This option tells rsync to apply one or more comma-separated "chmod" modes
! 1383: to the permission of the files in the transfer. The resulting value is
! 1384: treated as though it were the permissions that the sending side supplied
! 1385: for the file, which means that this option can seem to have no effect on
! 1386: existing files if <code>--perms</code> is not enabled.</p>
! 1387: <p>In addition to the normal parsing rules specified in the <strong>chmod</strong>(1)
! 1388: manpage, you can specify an item that should only apply to a directory by
! 1389: prefixing it with a 'D', or specify an item that should only apply to a
! 1390: file by prefixing it with a 'F'. For example, the following will ensure
! 1391: that all directories get marked set-gid, that no files are other-writable,
! 1392: that both are user-writable and group-writable, and that both have
! 1393: consistent executability across all bits:</p>
! 1394: <blockquote>
! 1395: <pre><code>--chmod=Dg+s,ug+w,Fo-w,+X
! 1396: </code></pre>
! 1397: </blockquote>
! 1398: <p>Using octal mode numbers is also allowed:</p>
! 1399: <blockquote>
! 1400: <pre><code>--chmod=D2775,F664
! 1401: </code></pre>
! 1402: </blockquote>
! 1403: <p>It is also legal to specify multiple <code>--chmod</code> options, as each additional
! 1404: option is just appended to the list of changes to make. To change
! 1405: permissions of files matching a pattern, use an include filter with the <code>m</code>
! 1406: modifier, which takes effect before any <code>--chmod</code> options.</p>
! 1407: <p>See the <code>--perms</code> and <code>--executability</code> options for how the resulting
! 1408: permission value can be applied to the files in the transfer.</p>
! 1409: </dd>
! 1410:
! 1411: <dt><code>--owner</code>, <code>-o</code></dt><dd>
! 1412: <p>This option causes rsync to set the owner of the destination file to be the
! 1413: same as the source file, but only if the receiving rsync is being run as
! 1414: the super-user (see also the <code>--super</code> and <code>--fake-super</code> options). Without
! 1415: this option, the owner of new and/or transferred files are set to the
! 1416: invoking user on the receiving side.</p>
! 1417: <p>The preservation of ownership will associate matching names by default, but
! 1418: may fall back to using the ID number in some circumstances (see also the
! 1419: <code>--numeric-ids</code> option for a full discussion).</p>
! 1420: </dd>
! 1421:
! 1422: <dt><code>--group</code>, <code>-g</code></dt><dd>
! 1423: <p>This option causes rsync to set the group of the destination file to be the
! 1424: same as the source file. If the receiving program is not running as the
! 1425: super-user (or if <code>--no-super</code> was specified), only groups that the
! 1426: invoking user on the receiving side is a member of will be preserved.
! 1427: Without this option, the group is set to the default group of the invoking
! 1428: user on the receiving side.</p>
! 1429: <p>The preservation of group information will associate matching names by
! 1430: default, but may fall back to using the ID number in some circumstances
! 1431: (see also the <code>--numeric-ids</code> option for a full discussion).</p>
! 1432: </dd>
! 1433:
! 1434: <dt><code>--devices</code></dt><dd>
! 1435: <p>This option causes rsync to transfer character and block device files to
! 1436: the remote system to recreate these devices. This option has no effect if
! 1437: the receiving rsync is not run as the super-user (see also the <code>--super</code>
! 1438: and <code>--fake-super</code> options).</p>
! 1439: </dd>
! 1440:
! 1441: <dt><code>--specials</code></dt><dd>
! 1442: <p>This option causes rsync to transfer special files such as named sockets
! 1443: and fifos.</p>
! 1444: </dd>
! 1445:
! 1446: <dt><code>-D</code></dt><dd>
! 1447: <p>The <code>-D</code> option is equivalent to <code>--devices --specials</code>.</p>
! 1448: </dd>
! 1449:
! 1450: <dt><code>--write-devices</code></dt><dd>
! 1451: <p>This tells rsync to treat a device on the receiving side as a regular file,
! 1452: allowing the writing of file data into a device.</p>
! 1453: <p>This option implies the <code>--inplace</code> option.</p>
! 1454: <p>Be careful using this, as you should know what devices are present on the
! 1455: receiving side of the transfer, especially if running rsync as root.</p>
! 1456: <p>This option is refused by an rsync daemon.</p>
! 1457: </dd>
! 1458:
! 1459: <dt><code>--times</code>, <code>-t</code></dt><dd>
! 1460: <p>This tells rsync to transfer modification times along with the files and
! 1461: update them on the remote system. Note that if this option is not used,
! 1462: the optimization that excludes files that have not been modified cannot be
! 1463: effective; in other words, a missing <code>-t</code> or <code>-a</code> will cause the next
! 1464: transfer to behave as if it used <code>-I</code>, causing all files to be updated
! 1465: (though rsync's delta-transfer algorithm will make the update fairly
! 1466: efficient if the files haven't actually changed, you're much better off
! 1467: using <code>-t</code>).</p>
! 1468: </dd>
! 1469:
! 1470: <dt><code>--atimes</code>, <code>-U</code></dt><dd>
! 1471: <p>This tells rsync to set the access (use) times of the destination files to
! 1472: the same value as the source files.</p>
! 1473: <p>If repeated, it also sets the <code>--open-noatime</code> option, which can help you
! 1474: to make the sending and receiving systems have the same access times on the
! 1475: transferred files without needing to run rsync an extra time after a file
! 1476: is transferred.</p>
! 1477: <p>Note that some older rsync versions (prior to 3.2.0) may have been built
! 1478: with a pre-release <code>--atimes</code> patch that does not imply <code>--open-noatime</code>
! 1479: when this option is repeated.</p>
! 1480: </dd>
! 1481:
! 1482: <dt><code>--open-noatime</code></dt><dd>
! 1483: <p>This tells rsync to open files with the O_NOATIME flag (on systems that
! 1484: support it) to avoid changing the access time of the files that are being
! 1485: transferred. If your OS does not support the O_NOATIME flag then rsync
! 1486: will silently ignore this option. Note also that some filesystems are
! 1487: mounted to avoid updating the atime on read access even without the
! 1488: O_NOATIME flag being set.</p>
! 1489: </dd>
! 1490:
! 1491: <dt><code>--crtimes</code>, <code>-N,</code></dt><dd>
! 1492: <p>This tells rsync to set the create times (newness) of the destination
! 1493: files to the same value as the source files.</p>
! 1494: </dd>
! 1495:
! 1496: <dt><code>--omit-dir-times</code>, <code>-O</code></dt><dd>
! 1497: <p>This tells rsync to omit directories when it is preserving modification
! 1498: times (see <code>--times</code>). If NFS is sharing the directories on the receiving
! 1499: side, it is a good idea to use <code>-O</code>. This option is inferred if you use
! 1500: <code>--backup</code> without <code>--backup-dir</code>.</p>
! 1501: <p>This option also has the side-effect of avoiding early creation of
! 1502: directories in incremental recursion copies. The default <code>--inc-recursive</code>
! 1503: copying normally does an early-create pass of all the sub-directories in a
! 1504: parent directory in order for it to be able to then set the modify time of
! 1505: the parent directory right away (without having to delay that until a bunch
! 1506: of recursive copying has finished). This early-create idiom is not
! 1507: necessary if directory modify times are not being preserved, so it is
! 1508: skipped. Since early-create directories don't have accurate mode, mtime,
! 1509: or ownership, the use of this option can help when someone wants to avoid
! 1510: these partially-finished directories.</p>
! 1511: </dd>
! 1512:
! 1513: <dt><code>--omit-link-times</code>, <code>-J</code></dt><dd>
! 1514: <p>This tells rsync to omit symlinks when it is preserving modification times
! 1515: (see <code>--times</code>).</p>
! 1516: </dd>
! 1517:
! 1518: <dt><code>--omit-dir-changes</code></dt><dd>
! 1519: <p>This tells rsync to omit directories when applying any preserved attributes
! 1520: (owner, group, times, permissions) to already existing directories.</p>
! 1521: </dd>
! 1522:
! 1523: <dt><code>--super</code></dt><dd>
! 1524: <p>This tells the receiving side to attempt super-user activities even if the
! 1525: receiving rsync wasn't run by the super-user. These activities include:
! 1526: preserving users via the <code>--owner</code> option, preserving all groups (not just
! 1527: the current user's groups) via the <code>--groups</code> option, and copying devices
! 1528: via the <code>--devices</code> option. This is useful for systems that allow such
! 1529: activities without being the super-user, and also for ensuring that you
! 1530: will get errors if the receiving side isn't being run as the super-user.
! 1531: To turn off super-user activities, the super-user can use <code>--no-super</code>.</p>
! 1532: </dd>
! 1533:
! 1534: <dt><code>--fake-super</code></dt><dd>
! 1535: <p>When this option is enabled, rsync simulates super-user activities by
! 1536: saving/restoring the privileged attributes via special extended attributes
! 1537: that are attached to each file (as needed). This includes the file's owner
! 1538: and group (if it is not the default), the file's device info (device &
! 1539: special files are created as empty text files), and any permission bits
! 1540: that we won't allow to be set on the real file (e.g. the real file gets
! 1541: u-s,g-s,o-t for safety) or that would limit the owner's access (since the
! 1542: real super-user can always access/change a file, the files we create can
! 1543: always be accessed/changed by the creating user). This option also handles
! 1544: ACLs (if <code>--acls</code> was specified) and non-user extended attributes (if
! 1545: <code>--xattrs</code> was specified).</p>
! 1546: <p>This is a good way to backup data without using a super-user, and to store
! 1547: ACLs from incompatible systems.</p>
! 1548: <p>The <code>--fake-super</code> option only affects the side where the option is used.
! 1549: To affect the remote side of a remote-shell connection, use the
! 1550: <code>--remote-option</code> (<code>-M</code>) option:</p>
! 1551: <blockquote>
! 1552: <pre><code>rsync -av -M--fake-super /src/ host:/dest/
! 1553: </code></pre>
! 1554: </blockquote>
! 1555: <p>For a local copy, this option affects both the source and the destination.
! 1556: If you wish a local copy to enable this option just for the destination
! 1557: files, specify <code>-M--fake-super</code>. If you wish a local copy to enable this
! 1558: option just for the source files, combine <code>--fake-super</code> with <code>-M--super</code>.</p>
! 1559: <p>This option is overridden by both <code>--super</code> and <code>--no-super</code>.</p>
! 1560: <p>See also the "<code>fake super</code>" setting in the daemon's rsyncd.conf file.</p>
! 1561: </dd>
! 1562:
! 1563: <dt><code>--sparse</code>, <code>-S</code></dt><dd>
! 1564: <p>Try to handle sparse files efficiently so they take up less space on the
! 1565: destination. If combined with <code>--inplace</code> the file created might not end
! 1566: up with sparse blocks with some combinations of kernel version and/or
! 1567: filesystem type. If <code>--whole-file</code> is in effect (e.g. for a local copy)
! 1568: then it will always work because rsync truncates the file prior to writing
! 1569: out the updated version.</p>
! 1570: <p>Note that versions of rsync older than 3.1.3 will reject the combination of
! 1571: <code>--sparse</code> and <code>--inplace</code>.</p>
! 1572: </dd>
! 1573:
! 1574: <dt><code>--preallocate</code></dt><dd>
! 1575: <p>This tells the receiver to allocate each destination file to its eventual
! 1576: size before writing data to the file. Rsync will only use the real
! 1577: filesystem-level preallocation support provided by Linux's <strong>fallocate</strong>(2)
! 1578: system call or Cygwin's <strong>posix_fallocate</strong>(3), not the slow glibc
! 1579: implementation that writes a null byte into each block.</p>
! 1580: <p>Without this option, larger files may not be entirely contiguous on the
! 1581: filesystem, but with this option rsync will probably copy more slowly. If
! 1582: the destination is not an extent-supporting filesystem (such as ext4, xfs,
! 1583: NTFS, etc.), this option may have no positive effect at all.</p>
! 1584: <p>If combined with <code>--sparse</code>, the file will only have sparse blocks (as
! 1585: opposed to allocated sequences of null bytes) if the kernel version and
! 1586: filesystem type support creating holes in the allocated data.</p>
! 1587: </dd>
! 1588:
! 1589: <dt><code>--sparse-block=SIZE</code></dt><dd>
! 1590: <p>Change the block size used to handle sparse files to SIZE bytes. This
! 1591: option only has an effect if the <code>--sparse</code> (<code>-S</code>) option was also
! 1592: specified. The default block size used by rsync to detect a file hole is
! 1593: 1024 bytes; when the receiver writes data to the destination file and
! 1594: option <code>--sparse</code> is used, rsync checks every 1024-bytes chunk to detect if
! 1595: they are actually filled with data or not. With certain filesystems,
! 1596: optimized to receive data streams for example, enlarging this block size
! 1597: can strongly increase performance. The option can be used to tune this
! 1598: block size.</p>
! 1599: </dd>
! 1600:
! 1601: <dt><code>--dry-run</code>, <code>-n</code></dt><dd>
! 1602: <p>This makes rsync perform a trial run that doesn't make any changes (and
! 1603: produces mostly the same output as a real run). It is most commonly used
! 1604: in combination with the <code>--verbose</code>, <code>-v</code> and/or <code>--itemize-changes</code>, <code>-i</code>
! 1605: options to see what an rsync command is going to do before one actually
! 1606: runs it.</p>
! 1607: <p>The output of <code>--itemize-changes</code> is supposed to be exactly the same on a
! 1608: dry run and a subsequent real run (barring intentional trickery and system
! 1609: call failures); if it isn't, that's a bug. Other output should be mostly
! 1610: unchanged, but may differ in some areas. Notably, a dry run does not send
! 1611: the actual data for file transfers, so <code>--progress</code> has no effect, the
! 1612: "bytes sent", "bytes received", "literal data", and "matched data"
! 1613: statistics are too small, and the "speedup" value is equivalent to a run
! 1614: where no file transfers were needed.</p>
! 1615: </dd>
! 1616:
! 1617: <dt><code>--whole-file</code>, <code>-W</code></dt><dd>
! 1618: <p>This option disables rsync's delta-transfer algorithm, which causes all
! 1619: transferred files to be sent whole. The transfer may be faster if this
! 1620: option is used when the bandwidth between the source and destination
! 1621: machines is higher than the bandwidth to disk (especially when the "disk"
! 1622: is actually a networked filesystem). This is the default when both the
! 1623: source and destination are specified as local paths, but only if no
! 1624: batch-writing option is in effect.</p>
! 1625: </dd>
! 1626:
! 1627: <dt><code>--checksum-choice=STR</code>, <code>--cc=STR</code></dt><dd>
! 1628: <p>This option overrides the checksum algorithms. If one algorithm name is
! 1629: specified, it is used for both the transfer checksums and (assuming
! 1630: <code>--checksum</code> is specified) the pre-transfer checksums. If two
! 1631: comma-separated names are supplied, the first name affects the transfer
! 1632: checksums, and the second name affects the pre-transfer checksums (<code>-c</code>).</p>
! 1633: <p>The checksum options that you may be able to use are:</p>
! 1634: <ul>
! 1635: <li><code>auto</code> (the default automatic choice)</li>
! 1636: <li><code>xxh128</code></li>
! 1637: <li><code>xxh3</code></li>
! 1638: <li><code>xxh64</code> (aka <code>xxhash</code>)</li>
! 1639: <li><code>md5</code></li>
! 1640: <li><code>md4</code></li>
! 1641: <li><code>none</code></li>
! 1642: </ul>
! 1643: <p>Run <code>rsync --version</code> to see the default checksum list compiled into your
! 1644: version (which may differ from the list above).</p>
! 1645: <p>If "none" is specified for the first (or only) name, the <code>--whole-file</code>
! 1646: option is forced on and no checksum verification is performed on the
! 1647: transferred data. If "none" is specified for the second (or only) name,
! 1648: the <code>--checksum</code> option cannot be used.</p>
! 1649: <p>The "auto" option is the default, where rsync bases its algorithm choice on
! 1650: a negotiation between the client and the server as follows:</p>
! 1651: <p>When both sides of the transfer are at least 3.2.0, rsync chooses the first
! 1652: algorithm in the client's list of choices that is also in the server's list
! 1653: of choices. If no common checksum choice is found, rsync exits with
! 1654: an error. If the remote rsync is too old to support checksum negotiation,
! 1655: a value is chosen based on the protocol version (which chooses between MD5
! 1656: and various flavors of MD4 based on protocol age).</p>
! 1657: <p>The default order can be customized by setting the environment variable
! 1658: RSYNC_CHECKSUM_LIST to a space-separated list of acceptable checksum names.
! 1659: If the string contains a "<code>&</code>" character, it is separated into the "client
! 1660: string & server string", otherwise the same string
! 1661: applies to both. If the string (or string portion) contains no
! 1662: non-whitespace characters, the default checksum list is used. This method
! 1663: does not allow you to specify the transfer checksum separately from the
! 1664: pre-transfer checksum, and it discards "auto" and all unknown checksum
! 1665: names. A list with only invalid names results in a failed negotiation.</p>
! 1666: <p>The use of the <code>--checksum-choice</code> option overrides this environment list.</p>
! 1667: </dd>
! 1668:
! 1669: <dt><code>--one-file-system</code>, <code>-x</code></dt><dd>
! 1670: <p>This tells rsync to avoid crossing a filesystem boundary when recursing.
! 1671: This does not limit the user's ability to specify items to copy from
! 1672: multiple filesystems, just rsync's recursion through the hierarchy of each
! 1673: directory that the user specified, and also the analogous recursion on the
! 1674: receiving side during deletion. Also keep in mind that rsync treats a
! 1675: "bind" mount to the same device as being on the same filesystem.</p>
! 1676: <p>If this option is repeated, rsync omits all mount-point directories from
! 1677: the copy. Otherwise, it includes an empty directory at each mount-point it
! 1678: encounters (using the attributes of the mounted directory because those of
! 1679: the underlying mount-point directory are inaccessible).</p>
! 1680: <p>If rsync has been told to collapse symlinks (via <code>--copy-links</code> or
! 1681: <code>--copy-unsafe-links</code>), a symlink to a directory on another device is
! 1682: treated like a mount-point. Symlinks to non-directories are unaffected by
! 1683: this option.</p>
! 1684: </dd>
! 1685:
! 1686: <dt><code>--existing</code>, <code>--ignore-non-existing</code></dt><dd>
! 1687: <p>This tells rsync to skip creating files (including directories) that do not
! 1688: exist yet on the destination. If this option is combined with the
! 1689: <code>--ignore-existing</code> option, no files will be updated (which can be useful
! 1690: if all you want to do is delete extraneous files).</p>
! 1691: <p>This option is a transfer rule, not an exclude, so it doesn't affect the
! 1692: data that goes into the file-lists, and thus it doesn't affect deletions.
! 1693: It just limits the files that the receiver requests to be transferred.</p>
! 1694: </dd>
! 1695:
! 1696: <dt><code>--ignore-existing</code></dt><dd>
! 1697: <p>This tells rsync to skip updating files that already exist on the
! 1698: destination (this does <u>not</u> ignore existing directories, or nothing would
! 1699: get done). See also <code>--existing</code>.</p>
! 1700: <p>This option is a transfer rule, not an exclude, so it doesn't affect the
! 1701: data that goes into the file-lists, and thus it doesn't affect deletions.
! 1702: It just limits the files that the receiver requests to be transferred.</p>
! 1703: <p>This option can be useful for those doing backups using the <code>--link-dest</code>
! 1704: option when they need to continue a backup run that got interrupted. Since
! 1705: a <code>--link-dest</code> run is copied into a new directory hierarchy (when it is
! 1706: used properly), using <code>--ignore-existing</code> will ensure that the
! 1707: already-handled files don't get tweaked (which avoids a change in
! 1708: permissions on the hard-linked files). This does mean that this option is
! 1709: only looking at the existing files in the destination hierarchy itself.</p>
! 1710: </dd>
! 1711:
! 1712: <dt><code>--remove-source-files</code></dt><dd>
! 1713: <p>This tells rsync to remove from the sending side the files (meaning
! 1714: non-directories) that are a part of the transfer and have been successfully
! 1715: duplicated on the receiving side.</p>
! 1716: <p>Note that you should only use this option on source files that are
! 1717: quiescent. If you are using this to move files that show up in a
! 1718: particular directory over to another host, make sure that the finished
! 1719: files get renamed into the source directory, not directly written into it,
! 1720: so that rsync can't possibly transfer a file that is not yet fully written.
! 1721: If you can't first write the files into a different directory, you should
! 1722: use a naming idiom that lets rsync avoid transferring files that are not
! 1723: yet finished (e.g. name the file "foo.new" when it is written, rename it to
! 1724: "foo" when it is done, and then use the option <code>--exclude='*.new'</code> for the
! 1725: rsync transfer).</p>
! 1726: <p>Starting with 3.1.0, rsync will skip the sender-side removal (and output an
! 1727: error) if the file's size or modify time has not stayed unchanged.</p>
! 1728: </dd>
! 1729:
! 1730: <dt><code>--source-backup</code></dt><dd>
! 1731: <p>Makes the sender back up the source files it removes due to
! 1732: <code>--remove-source-files</code>. This option is independent of <code>--backup</code> but uses
! 1733: the same <code>--backup-dir</code> and <code>--suffix</code> settings, if any. With
! 1734: <code>--backup-dir</code>, rsync looks for each file's backup dir relative to the
! 1735: source argument the file came from. Consequently, if the <code>--backup-dir</code>
! 1736: path is relative, each source argument gets a separate backup dir at that
! 1737: path relative to the argument.</p>
! 1738: </dd>
! 1739:
! 1740: <dt><code>--delete</code></dt><dd>
! 1741: <p>This tells rsync to delete extraneous files from the receiving side (ones
! 1742: that aren't on the sending side), but only for the directories that are
! 1743: being synchronized. You must have asked rsync to send the whole directory
! 1744: (e.g. "<code>dir</code>" or "<code>dir/</code>") without using a wildcard for the directory's
! 1745: contents (e.g. "<code>dir/*</code>") since the wildcard is expanded by the shell and
! 1746: rsync thus gets a request to transfer individual files, not the files'
! 1747: parent directory. Files that are excluded from the transfer are also
! 1748: excluded from being deleted unless you use the <code>--delete-excluded</code> option
! 1749: or mark the rules as only matching on the sending side (see the
! 1750: include/exclude modifiers in the FILTER RULES section).</p>
! 1751: <p>Prior to rsync 2.6.7, this option would have no effect unless <code>--recursive</code>
! 1752: was enabled. Beginning with 2.6.7, deletions will also occur when <code>--dirs</code>
! 1753: (<code>-d</code>) is enabled, but only for directories whose contents are being
! 1754: copied.</p>
! 1755: <p>This option can be dangerous if used incorrectly! It is a very good idea to
! 1756: first try a run using the <code>--dry-run</code> option (<code>-n</code>) to see what files are
! 1757: going to be deleted.</p>
! 1758: <p>If the sending side detects any I/O errors, then the deletion of any files
! 1759: at the destination will be automatically disabled. This is to prevent
! 1760: temporary filesystem failures (such as NFS errors) on the sending side from
! 1761: causing a massive deletion of files on the destination. You can override
! 1762: this with the <code>--ignore-errors</code> option.</p>
! 1763: <p>The <code>--delete</code> option may be combined with one of the -⁠-⁠delete-WHEN options
! 1764: without conflict, as well as <code>--delete-excluded</code>. However, if none of the
! 1765: <code>--delete-WHEN</code> options are specified, rsync will choose the
! 1766: <code>--delete-during</code> algorithm when talking to rsync 3.0.0 or newer, and the
! 1767: <code>--delete-before</code> algorithm when talking to an older rsync. See also
! 1768: <code>--delete-delay</code> and <code>--delete-after</code>.</p>
! 1769: </dd>
! 1770:
! 1771: <dt><code>--delete-before</code></dt><dd>
! 1772: <p>Request that the file-deletions on the receiving side be done before the
! 1773: transfer starts. See <code>--delete</code> (which is implied) for more details on
! 1774: file-deletion.</p>
! 1775: <p>Deleting before the transfer is helpful if the filesystem is tight for
! 1776: space and removing extraneous files would help to make the transfer
! 1777: possible. However, it does introduce a delay before the start of the
! 1778: transfer, and this delay might cause the transfer to timeout (if
! 1779: <code>--timeout</code> was specified). It also forces rsync to use the old,
! 1780: non-incremental recursion algorithm that requires rsync to scan all the
! 1781: files in the transfer into memory at once (see <code>--recursive</code>).</p>
! 1782: </dd>
! 1783:
! 1784: <dt><code>--delete-during</code>, <code>--del</code></dt><dd>
! 1785: <p>Request that the file-deletions on the receiving side be done incrementally
! 1786: as the transfer happens. The per-directory delete scan is done right
! 1787: before each directory is checked for updates, so it behaves like a more
! 1788: efficient <code>--delete-before</code>, including doing the deletions prior to any
! 1789: per-directory filter files being updated. This option was first added in
! 1790: rsync version 2.6.4. See <code>--delete</code> (which is implied) for more details on
! 1791: file-deletion.</p>
! 1792: </dd>
! 1793:
! 1794: <dt><code>--delete-delay</code></dt><dd>
! 1795: <p>Request that the file-deletions on the receiving side be computed during
! 1796: the transfer (like <code>--delete-during</code>), and then removed after the transfer
! 1797: completes. This is useful when combined with <code>--delay-updates</code> and/or
! 1798: <code>--fuzzy</code>, and is more efficient than using <code>--delete-after</code> (but can
! 1799: behave differently, since <code>--delete-after</code> computes the deletions in a
! 1800: separate pass after all updates are done). If the number of removed files
! 1801: overflows an internal buffer, a temporary file will be created on the
! 1802: receiving side to hold the names (it is removed while open, so you
! 1803: shouldn't see it during the transfer). If the creation of the temporary
! 1804: file fails, rsync will try to fall back to using <code>--delete-after</code> (which it
! 1805: cannot do if <code>--recursive</code> is doing an incremental scan). See <code>--delete</code>
! 1806: (which is implied) for more details on file-deletion.</p>
! 1807: </dd>
! 1808:
! 1809: <dt><code>--delete-after</code></dt><dd>
! 1810: <p>Request that the file-deletions on the receiving side be done after the
! 1811: transfer has completed. This is useful if you are sending new
! 1812: per-directory merge files as a part of the transfer and you want their
! 1813: exclusions to take effect for the delete phase of the current transfer. It
! 1814: also forces rsync to use the old, non-incremental recursion algorithm that
! 1815: requires rsync to scan all the files in the transfer into memory at once
! 1816: (see <code>--recursive</code>). See <code>--delete</code> (which is implied) for more details on
! 1817: file-deletion.</p>
! 1818: </dd>
! 1819:
! 1820: <dt><code>--delete-excluded</code></dt><dd>
! 1821: <p>In addition to deleting the files on the receiving side that are not on the
! 1822: sending side, this tells rsync to also delete any files on the receiving
! 1823: side that are excluded (see <code>--exclude</code>). See the FILTER RULES section for
! 1824: a way to make individual exclusions behave this way on the receiver, and
! 1825: for a way to protect files from <code>--delete-excluded</code>. See <code>--delete</code> (which
! 1826: is implied) for more details on file-deletion.</p>
! 1827: </dd>
! 1828:
! 1829: <dt><code>--ignore-missing-args</code></dt><dd>
! 1830: <p>When rsync is first processing the explicitly requested source files (e.g.
! 1831: command-line arguments or <code>--files-from</code> entries), it is normally an error
! 1832: if the file cannot be found. This option suppresses that error, and does
! 1833: not try to transfer the file. This does not affect subsequent
! 1834: vanished-file errors if a file was initially found to be present and later
! 1835: is no longer there.</p>
! 1836: </dd>
! 1837:
! 1838: <dt><code>--delete-missing-args</code></dt><dd>
! 1839: <p>This option takes the behavior of (the implied) <code>--ignore-missing-args</code>
! 1840: option a step farther: each missing arg will become a deletion request of
! 1841: the corresponding destination file on the receiving side (should it exist).
! 1842: If the destination file is a non-empty directory, it will only be
! 1843: successfully deleted if <code>--force-delete</code> or <code>--delete</code> are in effect. Other than
! 1844: that, this option is independent of any other type of delete processing.</p>
! 1845: <p>The missing source files are represented by special file-list entries which
! 1846: display as a "<code>*missing</code>" entry in the <code>--list-only</code> output.</p>
! 1847: </dd>
! 1848:
! 1849: <dt><code>--ignore-errors</code></dt><dd>
! 1850: <p>Tells <code>--delete</code> to go ahead and delete files even when there are I/O
! 1851: errors.</p>
! 1852: </dd>
! 1853:
! 1854: <dt><code>--force-delete</code></dt><dd>
! 1855: <p>This option tells rsync to delete a non-empty directory when it is to be
! 1856: replaced by a non-directory. This is only relevant if deletions are not
! 1857: active (see <code>--delete</code> for details).</p>
! 1858: <p>This option can be abbreviated <code>--force</code> for backward compatibility. Note
! 1859: that some older rsync versions used to still require <code>--force</code> when using
! 1860: <code>--delete-after</code>, and it used to be non-functional unless the <code>--recursive</code>
! 1861: option was also enabled.</p>
! 1862: </dd>
! 1863:
! 1864: <dt><code>--max-delete=NUM</code></dt><dd>
! 1865: <p>This tells rsync not to delete more than NUM files or directories. If that
! 1866: limit is exceeded, all further deletions are skipped through the end of the
! 1867: transfer. At the end, rsync outputs a warning (including a count of the
! 1868: skipped deletions) and exits with an error code of 25 (unless some more
! 1869: important error condition also occurred).</p>
! 1870: <p>Beginning with version 3.0.0, you may specify <code>--max-delete=0</code> to be warned
! 1871: about any extraneous files in the destination without removing any of them.
! 1872: Older clients interpreted this as "unlimited", so if you don't know what
! 1873: version the client is, you can use the less obvious <code>--max-delete=-1</code> as a
! 1874: backward-compatible way to specify that no deletions be allowed (though
! 1875: really old versions didn't warn when the limit was exceeded).</p>
! 1876: </dd>
! 1877:
! 1878: <dt><code>--max-size=SIZE</code></dt><dd>
! 1879: <p>This tells rsync to avoid transferring any file that is larger than the
! 1880: specified SIZE. A numeric value can be suffixed with a string to indicate
! 1881: the numeric units or left unqualified to specify bytes. Feel free to use a
! 1882: fractional value along with the units, such as <code>--max-size=1.5m</code>.</p>
! 1883: <p>This option is a transfer rule, not an exclude, so it doesn't affect the
! 1884: data that goes into the file-lists, and thus it doesn't affect deletions.
! 1885: It just limits the files that the receiver requests to be transferred.</p>
! 1886: <p>The first letter of a units string can be <code>B</code> (bytes), <code>K</code> (kilo), <code>M</code>
! 1887: (mega), <code>G</code> (giga), <code>T</code> (tera), or <code>P</code> (peta). If the string is a single
! 1888: char or has "ib" added to it (e.g. "G" or "GiB") then the units are
! 1889: multiples of 1024. If you use a two-letter suffix that ends with a "B"
! 1890: (e.g. "kb") then you get units that are multiples of 1000. The string's
! 1891: letters can be any mix of upper and lower-case that you want to use.</p>
! 1892: <p>Finally, if the string ends with either "+1" or "-⁠1", it is offset by one
! 1893: byte in the indicated direction. The largest possible value is usually
! 1894: <code>8192P-1</code>.</p>
! 1895: <p>Examples: <code>--max-size=1.5mb-1</code> is 1499999 bytes, and <code>--max-size=2g+1</code> is
! 1896: 2147483649 bytes.</p>
! 1897: <p>Note that rsync versions prior to 3.1.0 did not allow <code>--max-size=0</code>.</p>
! 1898: </dd>
! 1899:
! 1900: <dt><code>--min-size=SIZE</code></dt><dd>
! 1901: <p>This tells rsync to avoid transferring any file that is smaller than the
! 1902: specified SIZE, which can help in not transferring small, junk files. See
! 1903: the <code>--max-size</code> option for a description of SIZE and other information.</p>
! 1904: <p>Note that rsync versions prior to 3.1.0 did not allow <code>--min-size=0</code>.</p>
! 1905: </dd>
! 1906:
! 1907: <dt><code>--max-alloc=SIZE</code></dt><dd>
! 1908: <p>By default rsync limits an individual malloc/realloc to about 1GB in size.
! 1909: For most people this limit works just fine and prevents a protocol error
! 1910: causing rsync to request massive amounts of memory. However, if you have
! 1911: many millions of files in a transfer, a large amount of server memory, and
! 1912: you don't want to split up your transfer into multiple parts, you can
! 1913: increase the per-allocation limit to something larger and rsync will
! 1914: consume more memory.</p>
! 1915: <p>Keep in mind that this is not a limit on the total size of allocated
! 1916: memory. It is a sanity-check value for each individual allocation.</p>
! 1917: <p>See the <code>--max-size</code> option for a description of how SIZE can be specified.
! 1918: The default suffix if none is given is bytes.</p>
! 1919: <p>Beginning in 3.2.3, a value of 0 specifies no limit.</p>
! 1920: <p>You can set a default value using the environment variable RSYNC_MAX_ALLOC
! 1921: using the same SIZE values as supported by this option. If the remote
! 1922: rsync doesn't understand the <code>--max-alloc</code> option, you can override an
! 1923: environmental value by specifying <code>--max-alloc=1g</code>, which will make rsync
! 1924: avoid sending the option to the remote side (because "1G" is the default).</p>
! 1925: </dd>
! 1926:
! 1927: <dt><code>--block-size=SIZE</code>, <code>-B</code></dt><dd>
! 1928: <p>This forces the block size used in rsync's delta-transfer algorithm to a
! 1929: fixed value. It is normally selected based on the size of each file being
! 1930: updated. See the technical report for details.</p>
! 1931: <p>Beginning in 3.2.3 the SIZE can be specified with a suffix as detailed in
! 1932: the <code>--max-size</code> option. Older versions only accepted a byte count.</p>
! 1933: </dd>
! 1934:
! 1935: <dt><code>--rsh=COMMAND</code>, <code>-e</code></dt><dd>
! 1936: <p>This option allows you to choose an alternative remote shell program to use
! 1937: for communication between the local and remote copies of rsync. Typically,
! 1938: rsync is configured to use ssh by default, but you may prefer to use rsh on
! 1939: a local network.</p>
! 1940: <p>If this option is used with <code>[user@]host::module/path</code>, then the remote
! 1941: shell <u>COMMAND</u> will be used to run an rsync daemon on the remote host, and
! 1942: all data will be transmitted through that remote shell connection, rather
! 1943: than through a direct socket connection to a running rsync daemon on the
! 1944: remote host. See the section "USING RSYNC-DAEMON FEATURES VIA A
! 1945: REMOTE-SHELL CONNECTION" above.</p>
! 1946: <p>Beginning with rsync 3.2.0, the RSYNC_PORT environment variable will be set
! 1947: when a daemon connection is being made via a remote-shell connection. It
! 1948: is set to 0 if the default daemon port is being assumed, or it is set to
! 1949: the value of the rsync port that was specified via either the <code>--port</code>
! 1950: option or a non-empty port value in an rsync:// URL. This allows the
! 1951: script to discern if a non-default port is being requested, allowing for
! 1952: things such as an SSL or stunnel helper script to connect to a default or
! 1953: alternate port.</p>
! 1954: <p>Command-line arguments are permitted in COMMAND provided that COMMAND is
! 1955: presented to rsync as a single argument. You must use spaces (not tabs or
! 1956: other whitespace) to separate the command and args from each other, and you
! 1957: can use single- and/or double-quotes to preserve spaces in an argument (but
! 1958: not backslashes). Note that doubling a single-quote inside a single-quoted
! 1959: string gives you a single-quote; likewise for double-quotes (though you
! 1960: need to pay attention to which quotes your shell is parsing and which
! 1961: quotes rsync is parsing). Some examples:</p>
! 1962: <blockquote>
! 1963: <pre><code>-e 'ssh -p 2234'
! 1964: -e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"'
! 1965: </code></pre>
! 1966: </blockquote>
! 1967: <p>(Note that ssh users can alternately customize site-specific connect
! 1968: options in their .ssh/config file.)</p>
! 1969: <p>You can also choose the remote shell program using the RSYNC_RSH
! 1970: environment variable, which accepts the same range of values as <code>-e</code>.</p>
! 1971: <p>See also the <code>--blocking-io</code> option which is affected by this option.</p>
! 1972: </dd>
! 1973:
! 1974: <dt><code>--rsync-path=PROGRAM</code></dt><dd>
! 1975: <p>Use this to specify what program is to be run on the remote machine to
! 1976: start-up rsync. Often used when rsync is not in the default remote-shell's
! 1977: path (e.g. <code>--rsync-path=/usr/local/bin/rsync</code>). Note that PROGRAM is run
! 1978: with the help of a shell, so it can be any program, script, or command
! 1979: sequence you'd care to run, so long as it does not corrupt the standard-in
! 1980: & standard-out that rsync is using to communicate.</p>
! 1981: <p>One tricky example is to set a different default directory on the remote
! 1982: machine for use with the <code>--relative</code> option. For instance:</p>
! 1983: <blockquote>
! 1984: <pre><code>rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/
! 1985: </code></pre>
! 1986: </blockquote>
! 1987: </dd>
! 1988:
! 1989: <dt><code>--remote-option=OPTION</code>, <code>-M</code></dt><dd>
! 1990: <p>This option is used for more advanced situations where you want certain
! 1991: effects to be limited to one side of the transfer only. For instance, if
! 1992: you want to pass <code>--log-file=FILE</code> and <code>--fake-super</code> to the remote system,
! 1993: specify it like this:</p>
! 1994: <blockquote>
! 1995: <pre><code>rsync -av -M --log-file=foo -M--fake-super src/ dest/
! 1996: </code></pre>
! 1997: </blockquote>
! 1998: <p>If you want to have an option affect only the local side of a transfer when
! 1999: it normally affects both sides, send its negation to the remote side. Like
! 2000: this:</p>
! 2001: <blockquote>
! 2002: <pre><code>rsync -av -x -M--no-x src/ dest/
! 2003: </code></pre>
! 2004: </blockquote>
! 2005: <p>Be cautious using this, as it is possible to toggle an option that will
! 2006: cause rsync to have a different idea about what data to expect next over
! 2007: the socket, and that will make it fail in a cryptic fashion.</p>
! 2008: <p>Note that it is best to use a separate <code>--remote-option</code> for each option
! 2009: you want to pass. This makes your usage compatible with the
! 2010: <code>--protect-args</code> option. If that option is off, any spaces in your remote
! 2011: options will be split by the remote shell unless you take steps to protect
! 2012: them.</p>
! 2013: <p>When performing a local transfer, the "local" side is the sender and the
! 2014: "remote" side is the receiver.</p>
! 2015: <p>Note some versions of the popt option-parsing library have a bug in them
! 2016: that prevents you from using an adjacent arg with an equal in it next to a
! 2017: short option letter (e.g. <code>-M--log-file=/tmp/foo</code>). If this bug affects
! 2018: your version of popt, you can use the version of popt that is included with
! 2019: rsync.</p>
! 2020: </dd>
! 2021:
! 2022: <dt><code>--cvs-exclude</code>, <code>-C</code></dt><dd>
! 2023: <p>This is a useful shorthand for excluding a broad range of files that you
! 2024: often don't want to transfer between systems. It uses a similar algorithm
! 2025: to CVS to determine if a file should be ignored.</p>
! 2026: <p>The exclude list is initialized to exclude the following items (these
! 2027: initial items are marked as perishable -⁠-⁠ see the FILTER RULES section):</p>
! 2028: <blockquote>
! 2029: <p><code>RCS</code>
! 2030: <code>SCCS</code>
! 2031: <code>CVS</code>
! 2032: <code>CVS.adm</code>
! 2033: <code>RCSLOG</code>
! 2034: <code>cvslog.*</code>
! 2035: <code>tags</code>
! 2036: <code>TAGS</code>
! 2037: <code>.make.state</code>
! 2038: <code>.nse_depinfo</code>
! 2039: <code>*~</code>
! 2040: <code>#*</code>
! 2041: <code>.#*</code>
! 2042: <code>,*</code>
! 2043: <code>_$*</code>
! 2044: <code>*$</code>
! 2045: <code>*.old</code>
! 2046: <code>*.bak</code>
! 2047: <code>*.BAK</code>
! 2048: <code>*.orig</code>
! 2049: <code>*.rej</code>
! 2050: <code>.del-*</code>
! 2051: <code>*.a</code>
! 2052: <code>*.olb</code>
! 2053: <code>*.o</code>
! 2054: <code>*.obj</code>
! 2055: <code>*.so</code>
! 2056: <code>*.exe</code>
! 2057: <code>*.Z</code>
! 2058: <code>*.elc</code>
! 2059: <code>*.ln</code>
! 2060: <code>core</code>
! 2061: <code>.svn/</code>
! 2062: <code>.git/</code>
! 2063: <code>.hg/</code>
! 2064: <code>.bzr/</code></p>
! 2065: </blockquote>
! 2066: <p>then, files listed in a $HOME/.cvsignore are added to the list and any
! 2067: files listed in the CVSIGNORE environment variable (all cvsignore names are
! 2068: delimited by whitespace).</p>
! 2069: <p>Finally, any file is ignored if it is in the same directory as a .cvsignore
! 2070: file and matches one of the patterns listed therein. Unlike rsync's
! 2071: filter/exclude files, these patterns are split on whitespace. See the
! 2072: <strong>cvs</strong>(1) manual for more information.</p>
! 2073: <p>If you're combining <code>-C</code> with your own <code>--filter</code> rules, you should note
! 2074: that these CVS excludes are appended at the end of your own rules,
! 2075: regardless of where the <code>-C</code> was placed on the command-line. This makes
! 2076: them a lower priority than any rules you specified explicitly. If you want
! 2077: to control where these CVS excludes get inserted into your filter rules,
! 2078: you should omit the <code>-C</code> as a command-line option and use a combination of
! 2079: <code>--filter=:C</code> and <code>--filter=-C</code> (either on your command-line or by putting
! 2080: the ":C" and "-⁠C" rules into a filter file with your other rules). The
! 2081: first option turns on the per-directory scanning for the .cvsignore file.
! 2082: The second option does a one-time import of the CVS excludes mentioned
! 2083: above.</p>
! 2084: </dd>
! 2085:
! 2086: <dt><code>--filter=RULE</code>, <code>-f</code></dt><dd>
! 2087: <p>This option allows you to add rules to selectively exclude certain files
! 2088: from the list of files to be transferred. This is most useful in
! 2089: combination with a recursive transfer.</p>
! 2090: <p>You may use as many <code>--filter</code> options on the command line as you like to
! 2091: build up the list of files to exclude. If the filter contains whitespace,
! 2092: be sure to quote it so that the shell gives the rule to rsync as a single
! 2093: argument. The text below also mentions that you can use an underscore to
! 2094: replace the space that separates a rule from its arg.</p>
! 2095: <p>See the FILTER RULES section for detailed information on this option.</p>
! 2096: </dd>
! 2097:
! 2098: <dt><code>-F</code></dt><dd>
! 2099: <p>The <code>-F</code> option is a shorthand for adding two <code>--filter</code> rules to your
! 2100: command. The first time it is used is a shorthand for this rule:</p>
! 2101: <blockquote>
! 2102: <pre><code>--filter='dir-merge /.rsync-filter'
! 2103: </code></pre>
! 2104: </blockquote>
! 2105: <p>This tells rsync to look for per-directory .rsync-filter files that have
! 2106: been sprinkled through the hierarchy and use their rules to filter the
! 2107: files in the transfer. If <code>-F</code> is repeated, it is a shorthand for this
! 2108: rule:</p>
! 2109: <blockquote>
! 2110: <pre><code>--filter='exclude .rsync-filter'
! 2111: </code></pre>
! 2112: </blockquote>
! 2113: <p>This filters out the .rsync-filter files themselves from the transfer.</p>
! 2114: <p>See the FILTER RULES section for detailed information on how these options
! 2115: work.</p>
! 2116: </dd>
! 2117:
! 2118: <dt><code>--exclude=PATTERN</code></dt><dd>
! 2119: <p>This option is a simplified form of the <code>--filter</code> option that defaults to
! 2120: an exclude rule and does not allow the full rule-parsing syntax of normal
! 2121: filter rules.</p>
! 2122: <p>See the FILTER RULES section for detailed information on this option.</p>
! 2123: </dd>
! 2124:
! 2125: <dt><code>--exclude-from=FILE</code></dt><dd>
! 2126: <p>This option is related to the <code>--exclude</code> option, but it specifies a FILE
! 2127: that contains exclude patterns (one per line). Blank lines in the file and
! 2128: lines starting with '<code>;</code>' or '<code>#</code>' are ignored. If <u>FILE</u> is '<code>-</code>', the
! 2129: list will be read from standard input.</p>
! 2130: </dd>
! 2131:
! 2132: <dt><code>--include=PATTERN</code></dt><dd>
! 2133: <p>This option is a simplified form of the <code>--filter</code> option that defaults to
! 2134: an include rule and does not allow the full rule-parsing syntax of normal
! 2135: filter rules.</p>
! 2136: <p>See the FILTER RULES section for detailed information on this option.</p>
! 2137: </dd>
! 2138:
! 2139: <dt><code>--include-from=FILE</code></dt><dd>
! 2140: <p>This option is related to the <code>--include</code> option, but it specifies a FILE
! 2141: that contains include patterns (one per line). Blank lines in the file and
! 2142: lines starting with '<code>;</code>' or '<code>#</code>' are ignored. If <u>FILE</u> is '<code>-</code>', the
! 2143: list will be read from standard input.</p>
! 2144: </dd>
! 2145:
! 2146: <dt><code>--files-from=FILE</code></dt><dd>
! 2147: <p>Using this option allows you to specify the exact list of files to transfer
! 2148: (as read from the specified FILE or '<code>-</code>' for standard input). It also
! 2149: tweaks the default behavior of rsync to make transferring just the
! 2150: specified files and directories easier:</p>
! 2151: <ul>
! 2152: <li>The <code>--relative</code> (<code>-R</code>) option is implied, which preserves the path
! 2153: information that is specified for each item in the file (use
! 2154: <code>--no-relative</code> or <code>--no-R</code> if you want to turn that off).</li>
! 2155: <li>The <code>--dirs</code> (<code>-d</code>) option is implied, which will create directories
! 2156: specified in the list on the destination rather than noisily skipping
! 2157: them (use <code>--no-dirs</code> or <code>--no-d</code> if you want to turn that off).</li>
! 2158: <li>The <code>--archive</code> (<code>-a</code>) option's behavior does not imply <code>--recursive</code>
! 2159: (<code>-r</code>), so specify it explicitly, if you want it.</li>
! 2160: <li>These side-effects change the default state of rsync, so the position of
! 2161: the <code>--files-from</code> option on the command-line has no bearing on how other
! 2162: options are parsed (e.g. <code>-a</code> works the same before or after
! 2163: <code>--files-from</code>, as does <code>--no-R</code> and all other options).</li>
! 2164: </ul>
! 2165: <p>The filenames that are read from the FILE are all relative to the source
! 2166: dir -⁠-⁠ any leading slashes are removed and no ".." references are allowed
! 2167: to go higher than the source dir. For example, take this command:</p>
! 2168: <blockquote>
! 2169: <pre><code>rsync -a --files-from=/tmp/foo /usr remote:/backup
! 2170: </code></pre>
! 2171: </blockquote>
! 2172: <p>If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
! 2173: directory will be created as /backup/bin on the remote host. If it
! 2174: contains "bin/" (note the trailing slash), the immediate contents of the
! 2175: directory would also be sent (without needing to be explicitly mentioned in
! 2176: the file -⁠-⁠ this began in version 2.6.4). In both cases, if the <code>-r</code>
! 2177: option was enabled, that dir's entire hierarchy would also be transferred
! 2178: (keep in mind that <code>-r</code> needs to be specified explicitly with
! 2179: <code>--files-from</code>, since it is not implied by <code>-a</code>). Also note that the
! 2180: effect of the (enabled by default) <code>--relative</code> option is to duplicate only
! 2181: the path info that is read from the file -⁠-⁠ it does not force the
! 2182: duplication of the source-spec path (/usr in this case).</p>
! 2183: <p>In addition, the <code>--files-from</code> file can be read from the remote host
! 2184: instead of the local host if you specify a "host:" in front of the file
! 2185: (the host must match one end of the transfer). As a short-cut, you can
! 2186: specify just a prefix of ":" to mean "use the remote end of the transfer".
! 2187: For example:</p>
! 2188: <blockquote>
! 2189: <pre><code>rsync -a --files-from=:/path/file-list src:/ /tmp/copy
! 2190: </code></pre>
! 2191: </blockquote>
! 2192: <p>This would copy all the files specified in the /path/file-list file that
! 2193: was located on the remote "src" host.</p>
! 2194: <p>If the <code>--iconv</code> and <code>--protect-args</code> options are specified and the
! 2195: <code>--files-from</code> filenames are being sent from one host to another, the
! 2196: filenames will be translated from the sending host's charset to the
! 2197: receiving host's charset.</p>
! 2198: <p>NOTE: sorting the list of files in the <code>--files-from</code> input helps rsync to
! 2199: be more efficient, as it will avoid re-visiting the path elements that are
! 2200: shared between adjacent entries. If the input is not sorted, some path
! 2201: elements (implied directories) may end up being scanned multiple times, and
! 2202: rsync will eventually unduplicate them after they get turned into file-list
! 2203: elements.</p>
! 2204: </dd>
! 2205:
! 2206: <dt><code>--from0</code>, <code>-0</code></dt><dd>
! 2207: <p>This tells rsync that the rules/filenames it reads from a file are
! 2208: terminated by a null ('\0') character, not a NL, CR, or CR+LF. This
! 2209: affects <code>--exclude-from</code>, <code>--include-from</code>, <code>--files-from</code>, and any merged
! 2210: files specified in a <code>--filter</code> rule. It does not affect <code>--cvs-exclude</code>
! 2211: (since all names read from a .cvsignore file are split on whitespace).</p>
! 2212: </dd>
! 2213:
! 2214: <dt><code>--protect-args</code>, <code>-s</code></dt><dd>
! 2215: <p>This option sends all filenames and most options to the remote rsync
! 2216: without allowing the remote shell to interpret them. This means that
! 2217: spaces are not split in names, and any non-wildcard special characters are
! 2218: not translated (such as <code>~</code>, <code>$</code>, <code>;</code>, <code>&</code>, etc.). Wildcards are expanded
! 2219: on the remote host by rsync (instead of the shell doing it).</p>
! 2220: <p>If you use this option with <code>--iconv</code>, the args related to the remote side
! 2221: will also be translated from the local to the remote character-set. The
! 2222: translation happens before wild-cards are expanded. See also the
! 2223: <code>--files-from</code> option.</p>
! 2224: <p>You may also control this option via the RSYNC_PROTECT_ARGS environment
! 2225: variable. If this variable has a non-zero value, this option will be
! 2226: enabled by default, otherwise it will be disabled by default. Either state
! 2227: is overridden by a manually specified positive or negative version of this
! 2228: option (note that <code>--no-s</code> and <code>--no-protect-args</code> are the negative
! 2229: versions). Since this option was first introduced in 3.0.0, you'll need to
! 2230: make sure it's disabled if you ever need to interact with a remote rsync
! 2231: that is older than that.</p>
! 2232: <p>Rsync can also be configured (at build time) to have this option enabled by
! 2233: default (with is overridden by both the environment and the command-line).
! 2234: Run <code>rsync --version</code> to check if this is the case, as it will display
! 2235: "default protect-args" or "optional protect-args" depending on how it was
! 2236: compiled.</p>
! 2237: <p>This option will eventually become a new default setting at some
! 2238: as-yet-undetermined point in the future.</p>
! 2239: </dd>
! 2240:
! 2241: <dt><code>--copy-as=USER[:GROUP]</code></dt><dd>
! 2242: <p>This option instructs rsync to use the USER and (if specified after a
! 2243: colon) the GROUP for the copy operations. This only works if the user that
! 2244: is running rsync has the ability to change users. If the group is not
! 2245: specified then the user's default groups are used.</p>
! 2246: <p>This option can help to reduce the risk of an rsync being run as root into
! 2247: or out of a directory that might have live changes happening to it and you
! 2248: want to make sure that root-level read or write actions of system files are
! 2249: not possible. While you could alternatively run all of rsync as the
! 2250: specified user, sometimes you need the root-level host-access credentials
! 2251: to be used, so this allows rsync to drop root for the copying part of the
! 2252: operation after the remote-shell or daemon connection is established.</p>
! 2253: <p>The option only affects one side of the transfer unless the transfer is
! 2254: local, in which case it affects both sides. Use the <code>--remote-option</code> to
! 2255: affect the remote side, such as <code>-M--copy-as=joe</code>. For a local transfer,
! 2256: the lsh (or lsh.sh) support file provides a local-shell helper script that
! 2257: can be used to allow a "localhost:" or "lh:" host-spec to be specified
! 2258: without needing to setup any remote shells, allowing you to specify remote
! 2259: options that affect the side of the transfer that is using the host-spec
! 2260: (and using hostname "lh" avoids the overriding of the remote directory to
! 2261: the user's home dir).</p>
! 2262: <p>For example, the following rsync writes the local files as user "joe":</p>
! 2263: <blockquote>
! 2264: <pre><code>sudo rsync -aiv --copy-as=joe host1:backups/joe/ /home/joe/
! 2265: </code></pre>
! 2266: </blockquote>
! 2267: <p>This makes all files owned by user "joe", limits the groups to those that
! 2268: are available to that user, and makes it impossible for the joe user to do
! 2269: a timed exploit of the path to induce a change to a file that the joe user
! 2270: has no permissions to change.</p>
! 2271: <p>The following command does a local copy into the "dest/" dir as user "joe"
! 2272: (assuming you've installed support/lsh into a dir on your $PATH):</p>
! 2273: <blockquote>
! 2274: <pre><code>sudo rsync -aive lsh -M--copy-as=joe src/ lh:dest/
! 2275: </code></pre>
! 2276: </blockquote>
! 2277: </dd>
! 2278:
! 2279: <dt><code>--ignore-case</code></dt><dd>
! 2280: <p>This option tells rsync to ignore upper-/lower-case differences when
! 2281: comparing filenames. This can avoid problems when sending files to a
! 2282: filesystem that ignores these differences.</p>
! 2283: </dd>
! 2284:
! 2285: <dt><code>--temp-dir=DIR</code>, <code>-T</code></dt><dd>
! 2286: <p>This option instructs rsync to use DIR as a scratch directory when creating
! 2287: temporary copies of the files transferred on the receiving side. The
! 2288: default behavior is to create each temporary file in the same directory as
! 2289: the associated destination file. Beginning with rsync 3.1.1, the temp-file
! 2290: names inside the specified DIR will not be prefixed with an extra dot
! 2291: (though they will still have a random suffix added).</p>
! 2292: <p>This option is most often used when the receiving disk partition does not
! 2293: have enough free space to hold a copy of the largest file in the transfer.
! 2294: In this case (i.e. when the scratch directory is on a different disk
! 2295: partition), rsync will not be able to rename each received temporary file
! 2296: over the top of the associated destination file, but instead must copy it
! 2297: into place. Rsync does this by copying the file over the top of the
! 2298: destination file, which means that the destination file will contain
! 2299: truncated data during this copy. If this were not done this way (even if
! 2300: the destination file were first removed, the data locally copied to a
! 2301: temporary file in the destination directory, and then renamed into place)
! 2302: it would be possible for the old file to continue taking up disk space (if
! 2303: someone had it open), and thus there might not be enough room to fit the
! 2304: new version on the disk at the same time.</p>
! 2305: <p>If you are using this option for reasons other than a shortage of disk
! 2306: space, you may wish to combine it with the <code>--delay-updates</code> option, which
! 2307: will ensure that all copied files get put into subdirectories in the
! 2308: destination hierarchy, awaiting the end of the transfer. If you don't have
! 2309: enough room to duplicate all the arriving files on the destination
! 2310: partition, another way to tell rsync that you aren't overly concerned about
! 2311: disk space is to use the <code>--partial-dir</code> option with a relative path;
! 2312: because this tells rsync that it is OK to stash off a copy of a single file
! 2313: in a subdir in the destination hierarchy, rsync will use the partial-dir as
! 2314: a staging area to bring over the copied file, and then rename it into place
! 2315: from there. (Specifying a <code>--partial-dir</code> with an absolute path does not
! 2316: have this side-effect.)</p>
! 2317: </dd>
! 2318:
! 2319: <dt><code>--fuzzy</code>, <code>-y</code></dt><dd>
! 2320: <p>This option tells rsync that it should look for a basis file for any
! 2321: destination file that is missing. The current algorithm looks in the same
! 2322: directory as the destination file for either a file that has an identical
! 2323: size and modified-time, or a similarly-named file. If found, rsync uses
! 2324: the fuzzy basis file to try to speed up the transfer.</p>
! 2325: <p>If the option is repeated, the fuzzy scan will also be done in any matching
! 2326: alternate destination directories that are specified via <code>--compare-dest</code>,
! 2327: <code>--copy-dest</code>, or <code>--link-dest</code>.</p>
! 2328: <p>Note that the use of the <code>--delete</code> option might get rid of any potential
! 2329: fuzzy-match files, so either use <code>--delete-after</code> or specify some filename
! 2330: exclusions if you need to prevent this.</p>
! 2331: </dd>
! 2332:
! 2333: <dt>``-⁠-⁠detect-renamed-lax<code>This version of</code>-⁠-⁠detect-renamed` makes rsync
! 2334: hard-link `dest/D` to `dest/S` without verifying that `src/S` and
! 2335: `dest/S` have the same data. This poses a significant risk of corrupting
! 2336: the destination by representing a new source file by an unrelated
! 2337: destination file that coincidentally passes the quick check with the source
! 2338: file. Use this option only if you accept the risk and disk I/O is a
! 2339: bottleneck.</dt><dd>
! 2340: </dd>
! 2341:
! 2342: <dt><code>--detect-moved</code> A less risky variant of <code>--detect-renamed-lax</code> that only
! 2343: uses a destination file that has the same basename as the new source file.</dt><dd>
! 2344: </dd>
! 2345:
! 2346: <dt><code>--detect-renamed</code></dt><dd>
! 2347: <p>With this option, for each new source file (call it <code>src/S</code>), rsync looks
! 2348: for a file <code>dest/D</code> anywhere in the destination that passes the quick check
! 2349: with <code>src/S</code>. If such a <code>dest/D</code> is found, rsync uses it as an alternate
! 2350: basis for transferring <code>S</code>. The idea is that if <code>src/S</code> was renamed from
! 2351: <code>src/D</code> (as opposed to <code>src/S</code> passing the quick check with <code>dest/D</code> by
! 2352: coincidence), the delta-transfer algorithm will find that all the data
! 2353: matches between <code>src/S</code> and <code>dest/D</code>, and the transfer will be really fast.</p>
! 2354: <p>By default, alternate-basis files are hard-linked into a directory named
! 2355: ".~tmp~" in each file's destination directory, but if you've specified the
! 2356: <code>--partial-dir</code> option, that directory will be used instead. These
! 2357: otential alternate-basis files will be removed as the transfer progresses.
! 2358: This option conflicts with <code>--inplace</code> and <code>--append</code>.</p>
! 2359: </dd>
! 2360:
! 2361: <dt><code>--compare-dest=DIR</code></dt><dd>
! 2362: <p>This option instructs rsync to use <u>DIR</u> on the destination machine as an
! 2363: additional hierarchy to compare destination files against doing transfers
! 2364: (if the files are missing in the destination directory). If a file is
! 2365: found in <u>DIR</u> that is identical to the sender's file, the file will NOT be
! 2366: transferred to the destination directory. This is useful for creating a
! 2367: sparse backup of just files that have changed from an earlier backup. This
! 2368: option is typically used to copy into an empty (or newly created)
! 2369: directory.</p>
! 2370: <p>Beginning in version 2.6.4, multiple <code>--compare-dest</code> directories may be
! 2371: provided, which will cause rsync to search the list in the order specified
! 2372: for an exact match. If a match is found that differs only in attributes, a
! 2373: local copy is made and the attributes updated. If a match is not found, a
! 2374: basis file from one of the <u>DIRs</u> will be selected to try to speed up the
! 2375: transfer.</p>
! 2376: <p>If <u>DIR</u> is a relative path, it is relative to the destination directory.
! 2377: See also <code>--copy-dest</code> and <code>--link-dest</code>.</p>
! 2378: <p>NOTE: beginning with version 3.1.0, rsync will remove a file from a
! 2379: non-empty destination hierarchy if an exact match is found in one of the
! 2380: compare-dest hierarchies (making the end result more closely match a fresh
! 2381: copy).</p>
! 2382: </dd>
! 2383:
! 2384: <dt><code>--copy-dest=DIR</code></dt><dd>
! 2385: <p>This option behaves like <code>--compare-dest</code>, but rsync will also copy
! 2386: unchanged files found in <u>DIR</u> to the destination directory using a local
! 2387: copy. This is useful for doing transfers to a new destination while
! 2388: leaving existing files intact, and then doing a flash-cutover when all
! 2389: files have been successfully transferred.</p>
! 2390: <p>Multiple <code>--copy-dest</code> directories may be provided, which will cause rsync
! 2391: to search the list in the order specified for an unchanged file. If a
! 2392: match is not found, a basis file from one of the <u>DIRs</u> will be selected to
! 2393: try to speed up the transfer.</p>
! 2394: <p>If <u>DIR</u> is a relative path, it is relative to the destination directory.
! 2395: See also <code>--compare-dest</code> and <code>--link-dest</code>.</p>
! 2396: </dd>
! 2397:
! 2398: <dt><code>--link-dest=DIR</code></dt><dd>
! 2399: <p>This option behaves like <code>--copy-dest</code>, but unchanged files are hard linked
! 2400: from <u>DIR</u> to the destination directory. The files must be identical in
! 2401: all preserved attributes (e.g. permissions, possibly ownership) in order
! 2402: for the files to be linked together. An example:</p>
! 2403: <blockquote>
! 2404: <pre><code>rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
! 2405: </code></pre>
! 2406: </blockquote>
! 2407: <p>If file's aren't linking, double-check their attributes. Also check if
! 2408: some attributes are getting forced outside of rsync's control, such a mount
! 2409: option that squishes root to a single user, or mounts a removable drive
! 2410: with generic ownership (such as OS X's "Ignore ownership on this volume"
! 2411: option).</p>
! 2412: <p>Beginning in version 2.6.4, multiple <code>--link-dest</code> directories may be
! 2413: provided, which will cause rsync to search the list in the order specified
! 2414: for an exact match (there is a limit of 20 such directories). If a match
! 2415: is found that differs only in attributes, a local copy is made and the
! 2416: attributes updated. If a match is not found, a basis file from one of the
! 2417: <u>DIRs</u> will be selected to try to speed up the transfer.</p>
! 2418: <p>This option works best when copying into an empty destination hierarchy, as
! 2419: existing files may get their attributes tweaked, and that can affect
! 2420: alternate destination files via hard-links. Also, itemizing of changes can
! 2421: get a bit muddled. Note that prior to version 3.1.0, an
! 2422: alternate-directory exact match would never be found (nor linked into the
! 2423: destination) when a destination file already exists.</p>
! 2424: <p>Note that if you combine this option with <code>--ignore-times</code>, rsync will not
! 2425: link any files together because it only links identical files together as a
! 2426: substitute for transferring the file, never as an additional check after
! 2427: the file is updated.</p>
! 2428: <p>If <u>DIR</u> is a relative path, it is relative to the destination directory.
! 2429: See also <code>--compare-dest</code> and <code>--copy-dest</code>.</p>
! 2430: <p>Note that rsync versions prior to 2.6.1 had a bug that could prevent
! 2431: <code>--link-dest</code> from working properly for a non-super-user when <code>-o</code> was
! 2432: specified (or implied by <code>-a</code>). You can work-around this bug by avoiding
! 2433: the <code>-o</code> option when sending to an old rsync.</p>
! 2434: </dd>
! 2435:
! 2436: <dt><code>--clone-dest=DIR</code></dt><dd>
! 2437: <p>This option behaves like <code>--link-dest</code>, but unchanged files are reflinked
! 2438: from <u>DIR</u> to the destination directory. The files do not need to match
! 2439: in attributes, as the data is cloned separately from the attributes.</p>
! 2440: <p>If <u>DIR</u> is a relative path, it is relative to the destination directory.
! 2441: See also <code>--compare-dest</code> and <code>--copy-dest</code>.</p>
! 2442: <p>All non-regular files are hard-linked (when possible).</p>
! 2443: </dd>
! 2444:
! 2445: <dt><code>--link-by-hash=DIR</code></dt><dd>
! 2446: <p>This option hard links the destination files into <code>DIR</code>, a link farm
! 2447: arranged by MD5 file hash. The result is that the system will only store
! 2448: (usually) one copy of the unique contents of each file, regardless of the
! 2449: file's name (it will use extra files if the links overflow the available
! 2450: maximum).</p>
! 2451: <p>This patch does not take into account file permissions, extended
! 2452: attributes, or ACLs when linking things together, so you should only use
! 2453: this if you don't care about preserving those extra file attributes (or if
! 2454: they are always the same for identical files).</p>
! 2455: <p>The DIR is relative to the destination directory, so either specify a full
! 2456: path to the hash hierarchy, or specify a relative path that puts the links
! 2457: outside the destination (e.g. "../links").</p>
! 2458: <p>Keep in mind that the hierarchy is never pruned, so if you need to reclaim
! 2459: space, you should remove any files that have just one link (since they are
! 2460: not linked into any destination dirs anymore):</p>
! 2461: <blockquote>
! 2462: <pre><code>find $DIR -links 1 -delete
! 2463: </code></pre>
! 2464: </blockquote>
! 2465: <p>The link farm's directory hierarchy is determined by the file's (32-char)
! 2466: MD5 hash and the file-length. The hash is split up into directory shards.
! 2467: For example, if a file is 54321 bytes long, it could be stored like this:</p>
! 2468: <blockquote>
! 2469: <pre><code>$DIR/123/456/789/01234567890123456789012.54321.0
! 2470: </code></pre>
! 2471: </blockquote>
! 2472: <p>Note that the directory layout in this patch was modified for version
! 2473: 3.1.0, so anyone using an older version of this patch should move their
! 2474: existing link hierarchy out of the way and then use the newer rsync to copy
! 2475: the saved hierarchy into its new layout. Assuming that no files have
! 2476: overflowed their link limits, this would work:</p>
! 2477: <blockquote>
! 2478: <pre><code>mv $DIR $DIR.old
! 2479: rsync -aiv --link-by-hash=$DIR $DIR.old/ $DIR.tmp/
! 2480: rm -rf $DIR.tmp
! 2481: rm -rf $DIR.old
! 2482: </code></pre>
! 2483: </blockquote>
! 2484: <p>If some of your files are at their link limit, you'd be better of using a
! 2485: script to calculate the md5 sum of each file in the hierarchy and move it
! 2486: to its new location.</p>
! 2487: </dd>
! 2488:
! 2489: <dt><code>--compress</code>, <code>-z</code></dt><dd>
! 2490: <p>With this option, rsync compresses the file data as it is sent to the
! 2491: destination machine, which reduces the amount of data being transmitted -⁠-⁠
! 2492: something that is useful over a slow connection.</p>
! 2493: <p>Rsync supports multiple compression methods and will choose one for you
! 2494: unless you force the choice using the <code>--compress-choice</code> (<code>--zc</code>) option.</p>
! 2495: <p>Run <code>rsync --version</code> to see the default compress list compiled into your
! 2496: version.</p>
! 2497: <p>When both sides of the transfer are at least 3.2.0, rsync chooses the first
! 2498: algorithm in the client's list of choices that is also in the server's list
! 2499: of choices. If no common compress choice is found, rsync exits with
! 2500: an error. If the remote rsync is too old to support checksum negotiation,
! 2501: its list is assumed to be "zlib".</p>
! 2502: <p>The default order can be customized by setting the environment variable
! 2503: RSYNC_COMPRESS_LIST to a space-separated list of acceptable compression
! 2504: names. If the string contains a "<code>&</code>" character, it is separated into the
! 2505: "client string & server string", otherwise the same string applies to both.
! 2506: If the string (or string portion) contains no
! 2507: non-whitespace characters, the default compress list is used. Any unknown
! 2508: compression names are discarded from the list, but a list with only invalid
! 2509: names results in a failed negotiation.</p>
! 2510: <p>There are some older rsync versions that were configured to reject a <code>-z</code>
! 2511: option and require the use of <code>-zz</code> because their compression library was
! 2512: not compatible with the default zlib compression method. You can usually
! 2513: ignore this weirdness unless the rsync server complains and tells you to
! 2514: specify <code>-zz</code>.</p>
! 2515: <p>See also the <code>--skip-compress</code> option for the default list of file suffixes
! 2516: that will be transferred with no (or minimal) compression.</p>
! 2517: </dd>
! 2518:
! 2519: <dt><code>--compress-choice=STR</code>, <code>--zc=STR</code></dt><dd>
! 2520: <p>This option can be used to override the automatic negotiation of the
! 2521: compression algorithm that occurs when <code>--compress</code> is used. The option
! 2522: implies <code>--compress</code> unless "none" was specified, which instead implies
! 2523: <code>--no-compress</code>.</p>
! 2524: <p>The compression options that you may be able to use are:</p>
! 2525: <ul>
! 2526: <li><code>zstd</code></li>
! 2527: <li><code>lz4</code></li>
! 2528: <li><code>zlibx</code></li>
! 2529: <li><code>zlib</code></li>
! 2530: <li><code>none</code></li>
! 2531: </ul>
! 2532: <p>Run <code>rsync --version</code> to see the default compress list compiled into your
! 2533: version (which may differ from the list above).</p>
! 2534: <p>Note that if you see an error about an option named <code>--old-compress</code> or
! 2535: <code>--new-compress</code>, this is rsync trying to send the <code>--compress-choice=zlib</code>
! 2536: or <code>--compress-choice=zlibx</code> option in a backward-compatible manner that
! 2537: more rsync versions understand. This error indicates that the older rsync
! 2538: version on the server will not allow you to force the compression type.</p>
! 2539: <p>Note that the "zlibx" compression algorithm is just the "zlib" algorithm
! 2540: with matched data excluded from the compression stream (to try to make it
! 2541: more compatible with an external zlib implementation).</p>
! 2542: </dd>
! 2543:
! 2544: <dt><code>--compress-level=NUM</code>, <code>--zl=NUM</code></dt><dd>
! 2545: <p>Explicitly set the compression level to use (see <code>--compress</code>, <code>-z</code>)
! 2546: instead of letting it default. The <code>--compress</code> option is implied as long
! 2547: as the level chosen is not a "don't compress" level for the compression
! 2548: algorithm that is in effect (e.g. zlib compression treats level 0 as
! 2549: "off").</p>
! 2550: <p>The level values vary depending on the checksum in effect. Because rsync
! 2551: will negotiate a checksum choice by default (when the remote rsync is new
! 2552: enough), it can be good to combine this option with a <code>--compress-choice</code>
! 2553: (<code>--zc</code>) option unless you're sure of the choice in effect. For example:</p>
! 2554: <blockquote>
! 2555: <pre><code>rsync -aiv --zc=zstd --zl=22 host:src/ dest/
! 2556: </code></pre>
! 2557: </blockquote>
! 2558: <p>For zlib & zlibx compression the valid values are from 1 to 9 with 6 being
! 2559: the default. Specifying 0 turns compression off, and specifying -⁠1 chooses
! 2560: the default of 6.</p>
! 2561: <p>For zstd compression the valid values are from -⁠131072 to 22 with 3 being
! 2562: the default. Specifying 0 chooses the default of 3.</p>
! 2563: <p>For lz4 compression there are no levels, so the value is always 0.</p>
! 2564: <p>If you specify a too-large or too-small value, the number is silently
! 2565: limited to a valid value. This allows you to specify something like
! 2566: <code>--zl=999999999</code> and be assured that you'll end up with the maximum
! 2567: compression level no matter what algorithm was chosen.</p>
! 2568: <p>If you want to know the compression level that is in effect, specify
! 2569: <code>--debug=nstr</code> to see the "negotiated string" results. This will report
! 2570: something like "<code>Client compress: zstd (level 3)</code>" (along with the checksum
! 2571: choice in effect).</p>
! 2572: </dd>
! 2573:
! 2574: <dt><code>--skip-compress=LIST</code></dt><dd>
! 2575: <p>Override the list of file suffixes that will be compressed as little as
! 2576: possible. Rsync sets the compression level on a per-file basis based on
! 2577: the file's suffix. If the compression algorithm has an "off" level (such
! 2578: as zlib/zlibx) then no compression occurs for those files. Other
! 2579: algorithms that support changing the streaming level on-the-fly will have
! 2580: the level minimized to reduces the CPU usage as much as possible for a
! 2581: matching file. At this time, only zlib & zlibx compression support this
! 2582: changing of levels on a per-file basis.</p>
! 2583: <p>The <strong>LIST</strong> should be one or more file suffixes (without the dot) separated
! 2584: by slashes (<code>/</code>). You may specify an empty string to indicate that no files
! 2585: should be skipped.</p>
! 2586: <p>Simple character-class matching is supported: each must consist of a list
! 2587: of letters inside the square brackets (e.g. no special classes, such as
! 2588: "[:alpha:]", are supported, and '-⁠' has no special meaning).</p>
! 2589: <p>The characters asterisk (<code>*</code>) and question-mark (<code>?</code>) have no special meaning.</p>
! 2590: <p>Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules
! 2591: matches 2 suffixes):</p>
! 2592: <blockquote>
! 2593: <pre><code>--skip-compress=gz/jpg/mp[34]/7z/bz2
! 2594: </code></pre>
! 2595: </blockquote>
! 2596: <p>The default file suffixes in the skip-compress list in this version of
! 2597: rsync are:</p>
! 2598: <blockquote>
! 2599: <p>3g2
! 2600: 3gp
! 2601: 7z
! 2602: aac
! 2603: ace
! 2604: apk
! 2605: avi
! 2606: bz2
! 2607: deb
! 2608: dmg
! 2609: ear
! 2610: f4v
! 2611: flac
! 2612: flv
! 2613: gpg
! 2614: gz
! 2615: iso
! 2616: jar
! 2617: jpeg
! 2618: jpg
! 2619: lrz
! 2620: lz
! 2621: lz4
! 2622: lzma
! 2623: lzo
! 2624: m1a
! 2625: m1v
! 2626: m2a
! 2627: m2ts
! 2628: m2v
! 2629: m4a
! 2630: m4b
! 2631: m4p
! 2632: m4r
! 2633: m4v
! 2634: mka
! 2635: mkv
! 2636: mov
! 2637: mp1
! 2638: mp2
! 2639: mp3
! 2640: mp4
! 2641: mpa
! 2642: mpeg
! 2643: mpg
! 2644: mpv
! 2645: mts
! 2646: odb
! 2647: odf
! 2648: odg
! 2649: odi
! 2650: odm
! 2651: odp
! 2652: ods
! 2653: odt
! 2654: oga
! 2655: ogg
! 2656: ogm
! 2657: ogv
! 2658: ogx
! 2659: opus
! 2660: otg
! 2661: oth
! 2662: otp
! 2663: ots
! 2664: ott
! 2665: oxt
! 2666: png
! 2667: qt
! 2668: rar
! 2669: rpm
! 2670: rz
! 2671: rzip
! 2672: spx
! 2673: squashfs
! 2674: sxc
! 2675: sxd
! 2676: sxg
! 2677: sxm
! 2678: sxw
! 2679: sz
! 2680: tbz
! 2681: tbz2
! 2682: tgz
! 2683: tlz
! 2684: ts
! 2685: txz
! 2686: tzo
! 2687: vob
! 2688: war
! 2689: webm
! 2690: webp
! 2691: xz
! 2692: z
! 2693: zip
! 2694: zst</p>
! 2695: </blockquote>
! 2696: <p>This list will be replaced by your <code>--skip-compress</code> list in all but one
! 2697: situation: a copy from a daemon rsync will add your skipped suffixes to its
! 2698: list of non-compressing files (and its list may be configured to a
! 2699: different default).</p>
! 2700: </dd>
! 2701:
! 2702: <dt><code>--numeric-ids</code></dt><dd>
! 2703: <p>With this option rsync will transfer numeric group and user IDs rather than
! 2704: using user and group names and mapping them at both ends.</p>
! 2705: <p>By default rsync will use the username and groupname to determine what
! 2706: ownership to give files. The special uid 0 and the special group 0 are
! 2707: never mapped via user/group names even if the <code>--numeric-ids</code> option is not
! 2708: specified.</p>
! 2709: <p>If a user or group has no name on the source system or it has no match on
! 2710: the destination system, then the numeric ID from the source system is used
! 2711: instead. See also the comments on the "<code>use chroot</code>" setting in the
! 2712: rsyncd.conf manpage for information on how the chroot setting affects
! 2713: rsync's ability to look up the names of the users and groups and what you
! 2714: can do about it.</p>
! 2715: </dd>
! 2716:
! 2717: <dt><code>--usermap=STRING</code>, <code>--groupmap=STRING</code></dt><dd>
! 2718: <p>These options allow you to specify users and groups that should be mapped
! 2719: to other values by the receiving side. The <strong>STRING</strong> is one or more
! 2720: <strong>FROM</strong>:<strong>TO</strong> pairs of values separated by commas. Any matching <strong>FROM</strong>
! 2721: value from the sender is replaced with a <strong>TO</strong> value from the receiver.
! 2722: You may specify usernames or user IDs for the <strong>FROM</strong> and <strong>TO</strong> values,
! 2723: and the <strong>FROM</strong> value may also be a wild-card string, which will be
! 2724: matched against the sender's names (wild-cards do NOT match against ID
! 2725: numbers, though see below for why a '<code>*</code>' matches everything). You may
! 2726: instead specify a range of ID numbers via an inclusive range: LOW-HIGH.
! 2727: For example:</p>
! 2728: <blockquote>
! 2729: <pre><code>--usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1:usr
! 2730: </code></pre>
! 2731: </blockquote>
! 2732: <p>The first match in the list is the one that is used. You should specify
! 2733: all your user mappings using a single <code>--usermap</code> option, and/or all your
! 2734: group mappings using a single <code>--groupmap</code> option.</p>
! 2735: <p>Note that the sender's name for the 0 user and group are not transmitted to
! 2736: the receiver, so you should either match these values using a 0, or use the
! 2737: names in effect on the receiving side (typically "root"). All other
! 2738: <strong>FROM</strong> names match those in use on the sending side. All <strong>TO</strong> names
! 2739: match those in use on the receiving side.</p>
! 2740: <p>Any IDs that do not have a name on the sending side are treated as having
! 2741: an empty name for the purpose of matching. This allows them to be matched
! 2742: via a "<code>*</code>" or using an empty name. For instance:</p>
! 2743: <blockquote>
! 2744: <pre><code>--usermap=:nobody --groupmap=*:nobody
! 2745: </code></pre>
! 2746: </blockquote>
! 2747: <p>When the <code>--numeric-ids</code> option is used, the sender does not send any
! 2748: names, so all the IDs are treated as having an empty name. This means that
! 2749: you will need to specify numeric <strong>FROM</strong> values if you want to map these
! 2750: nameless IDs to different values.</p>
! 2751: <p>For the <code>--usermap</code> option to have any effect, the <code>-o</code> (<code>--owner</code>) option
! 2752: must be used (or implied), and the receiver will need to be running as a
! 2753: super-user (see also the <code>--fake-super</code> option). For the <code>--groupmap</code>
! 2754: option to have any effect, the <code>-g</code> (<code>--groups</code>) option must be used (or
! 2755: implied), and the receiver will need to have permissions to set that group.</p>
! 2756: <p>If your shell complains about the wildcards, use <code>--protect-args</code> (<code>-s</code>).</p>
! 2757: </dd>
! 2758:
! 2759: <dt><code>--chown=USER:GROUP</code></dt><dd>
! 2760: <p>This option forces all files to be owned by USER with group GROUP. This is
! 2761: a simpler interface than using <code>--usermap</code> and <code>--groupmap</code> directly, but
! 2762: it is implemented using those options internally, so you cannot mix them.
! 2763: If either the USER or GROUP is empty, no mapping for the omitted user/group
! 2764: will occur. If GROUP is empty, the trailing colon may be omitted, but if
! 2765: USER is empty, a leading colon must be supplied.</p>
! 2766: <p>If you specify "<code>--chown=foo:bar</code>", this is exactly the same as specifying
! 2767: "<code>--usermap=*:foo --groupmap=*:bar</code>", only easier. If your shell complains
! 2768: about the wildcards, use <code>--protect-args</code> (<code>-s</code>).</p>
! 2769: <p>To change ownership of files matching a pattern, use an include filter with
! 2770: a <code>o</code> or <code>g</code> modifier, which take effect before uid/gid mapping and
! 2771: therefore <u>can</u> be mixed with <code>--usermap</code> and <code>--groupmap</code>.</p>
! 2772: </dd>
! 2773:
! 2774: <dt><code>--timeout=SECONDS</code></dt><dd>
! 2775: <p>This option allows you to set a maximum I/O timeout in seconds. If no data
! 2776: is transferred for the specified time then rsync will exit. The default is
! 2777: 0, which means no timeout.</p>
! 2778: </dd>
! 2779:
! 2780: <dt><code>--contimeout=SECONDS</code></dt><dd>
! 2781: <p>This option allows you to set the amount of time that rsync will wait for
! 2782: its connection to an rsync daemon to succeed. If the timeout is reached,
! 2783: rsync exits with an error.</p>
! 2784: </dd>
! 2785:
! 2786: <dt><code>--address=ADDRESS</code></dt><dd>
! 2787: <p>By default rsync will bind to the wildcard address when connecting to an
! 2788: rsync daemon. The <code>--address</code> option allows you to specify a specific IP
! 2789: address (or hostname) to bind to. See also this option in the <code>--daemon</code>
! 2790: mode section.</p>
! 2791: </dd>
! 2792:
! 2793: <dt><code>--port=PORT</code></dt><dd>
! 2794: <p>This specifies an alternate TCP port number to use rather than the default
! 2795: of 873. This is only needed if you are using the double-colon (::) syntax
! 2796: to connect with an rsync daemon (since the URL syntax has a way to specify
! 2797: the port as a part of the URL). See also this option in the <code>--daemon</code>
! 2798: mode section.</p>
! 2799: </dd>
! 2800:
! 2801: <dt><code>--sockopts=OPTIONS</code></dt><dd>
! 2802: <p>This option can provide endless fun for people who like to tune their
! 2803: systems to the utmost degree. You can set all sorts of socket options
! 2804: which may make transfers faster (or slower!). Read the man page for the
! 2805: <code>setsockopt()</code> system call for details on some of the options you may be
! 2806: able to set. By default no special socket options are set. This only
! 2807: affects direct socket connections to a remote rsync daemon.</p>
! 2808: <p>This option also exists in the <code>--daemon</code> mode section.</p>
! 2809: </dd>
! 2810:
! 2811: <dt><code>--blocking-io</code></dt><dd>
! 2812: <p>This tells rsync to use blocking I/O when launching a remote shell
! 2813: transport. If the remote shell is either rsh or remsh, rsync defaults to
! 2814: using blocking I/O, otherwise it defaults to using non-blocking I/O. (Note
! 2815: that ssh prefers non-blocking I/O.)</p>
! 2816: </dd>
! 2817:
! 2818: <dt><code>--outbuf=MODE</code></dt><dd>
! 2819: <p>This sets the output buffering mode. The mode can be None (aka
! 2820: Unbuffered), Line, or Block (aka Full). You may specify as little as a
! 2821: single letter for the mode, and use upper or lower case.</p>
! 2822: <p>The main use of this option is to change Full buffering to Line buffering
! 2823: when rsync's output is going to a file or pipe.</p>
! 2824: </dd>
! 2825:
! 2826: <dt><code>--itemize-changes</code>, <code>-i</code></dt><dd>
! 2827: <p>Requests a simple itemized list of the changes that are being made to each
! 2828: file, including attribute changes. This is exactly the same as specifying
! 2829: <code>--out-format='%i %n%L'</code>. If you repeat the option, unchanged files will
! 2830: also be output, but only if the receiving rsync is at least version 2.6.7
! 2831: (you can use <code>-vv</code> with older versions of rsync, but that also turns on the
! 2832: output of other verbose messages).</p>
! 2833: <p>The "%i" escape has a cryptic output that is 11 letters long. The general
! 2834: format is like the string <code>YXcstpoguaxf</code>, where <strong>Y</strong> is replaced by the type
! 2835: of update being done, <strong>X</strong> is replaced by the file-type, and the other
! 2836: letters represent attributes that may be output if they are being modified.</p>
! 2837: <p>The update types that replace the <strong>Y</strong> are as follows:</p>
! 2838: <ul>
! 2839: <li>A <code><</code> means that a file is being transferred to the remote host (sent).</li>
! 2840: <li>A <code>></code> means that a file is being transferred to the local host
! 2841: (received).</li>
! 2842: <li>A <code>c</code> means that a local change/creation is occurring for the item (such
! 2843: as the creation of a directory or the changing of a symlink, etc.).</li>
! 2844: <li>A <code>h</code> means that the item is a hard link to another item (requires
! 2845: <code>--hard-links</code>).</li>
! 2846: <li>A <code>.</code> means that the item is not being updated (though it might have
! 2847: attributes that are being modified).</li>
! 2848: <li>A <code>*</code> means that the rest of the itemized-output area contains a message
! 2849: (e.g. "deleting").</li>
! 2850: </ul>
! 2851: <p>The file-types that replace the <strong>X</strong> are: <code>f</code> for a file, a <code>d</code> for a
! 2852: directory, an <code>L</code> for a symlink, a <code>D</code> for a device, and a <code>S</code> for a
! 2853: special file (e.g. named sockets and fifos).</p>
! 2854: <p>The other letters in the string indicate if some attributes of the file
! 2855: have changed, as follows:</p>
! 2856: <ul>
! 2857: <li>"<code>.</code>" -⁠ the attribute is unchanged.</li>
! 2858: <li>"<code>+</code>" -⁠ the file is newly created.</li>
! 2859: <li>"<code> </code>" -⁠ all the attributes are unchanged (all dots turn to spaces).</li>
! 2860: <li>"<code>?</code>" -⁠ the change is unknown (when the remote rsync is old).</li>
! 2861: <li>A letter indicates an attribute is being updated.</li>
! 2862: </ul>
! 2863: <p>The attribute that is associated with each letter is as follows:</p>
! 2864: <ul>
! 2865: <li>A <code>c</code> means either that a regular file has a different checksum (requires
! 2866: <code>--checksum</code>) or that a symlink, device, or special file has a changed
! 2867: value. Note that if you are sending files to an rsync prior to 3.0.1,
! 2868: this change flag will be present only for checksum-differing regular
! 2869: files.</li>
! 2870: <li>A <code>s</code> means the size of a regular file is different and will be updated
! 2871: by the file transfer.</li>
! 2872: <li>A <code>t</code> means the modification time is different and is being updated to
! 2873: the sender's value (requires <code>--times</code>). An alternate value of <code>T</code> means
! 2874: that the modification time will be set to the transfer time, which
! 2875: happens when a file/symlink/device is updated without <code>--times</code> and when
! 2876: a symlink is changed and the receiver can't set its time. (Note: when
! 2877: using an rsync 3.0.0 client, you might see the <code>s</code> flag combined with <code>t</code>
! 2878: instead of the proper <code>T</code> flag for this time-setting failure.)</li>
! 2879: <li>A <code>p</code> means the permissions are different and are being updated to the
! 2880: sender's value (requires <code>--perms</code>).</li>
! 2881: <li>An <code>o</code> means the owner is different and is being updated to the sender's
! 2882: value (requires <code>--owner</code> and super-user privileges).</li>
! 2883: <li>A <code>g</code> means the group is different and is being updated to the sender's
! 2884: value (requires <code>--group</code> and the authority to set the group).</li>
! 2885: <li>A <code>u</code>|<code>n</code>|<code>b</code> indicates the following information: <code>u</code> means the access
! 2886: (use) time is different and is being updated to the sender's value
! 2887: (requires <code>--atimes</code>); <code>n</code> means the create time (newness) is different
! 2888: and is being updated to the sender's value (requires <code>--crtimes</code>); <code>b</code>
! 2889: means that both the access and create times are being updated.</li>
! 2890: <li>The <code>a</code> means that the ACL information is being changed.</li>
! 2891: <li>The <code>x</code> means that the extended attribute information is being changed.</li>
! 2892: </ul>
! 2893: <p>One other output is possible: when deleting files, the "%i" will output the
! 2894: string "<code>*deleting</code>" for each item that is being removed (assuming that you
! 2895: are talking to a recent enough rsync that it logs deletions instead of
! 2896: outputting them as a verbose message).</p>
! 2897: </dd>
! 2898:
! 2899: <dt><code>--out-format=FORMAT</code></dt><dd>
! 2900: <p>This allows you to specify exactly what the rsync client outputs to the
! 2901: user on a per-update basis. The format is a text string containing
! 2902: embedded single-character escape sequences prefixed with a percent (%)
! 2903: character. A default format of "%n%L" is assumed if either <code>--info=name</code>
! 2904: or <code>-v</code> is specified (this tells you just the name of the file and, if the
! 2905: item is a link, where it points). For a full list of the possible escape
! 2906: characters, see the "<code>log format</code>" setting in the rsyncd.conf manpage.</p>
! 2907: <p>Specifying the <code>--out-format</code> option implies the <code>--info=name</code> option,
! 2908: which will mention each file, dir, etc. that gets updated in a significant
! 2909: way (a transferred file, a recreated symlink/device, or a touched
! 2910: directory). In addition, if the itemize-changes escape (%i) is included in
! 2911: the string (e.g. if the <code>--itemize-changes</code> option was used), the logging
! 2912: of names increases to mention any item that is changed in any way (as long
! 2913: as the receiving side is at least 2.6.4). See the <code>--itemize-changes</code>
! 2914: option for a description of the output of "%i".</p>
! 2915: <p>Rsync will output the out-format string prior to a file's transfer unless
! 2916: one of the transfer-statistic escapes is requested, in which case the
! 2917: logging is done at the end of the file's transfer. When this late logging
! 2918: is in effect and <code>--progress</code> is also specified, rsync will also output the
! 2919: name of the file being transferred prior to its progress information
! 2920: (followed, of course, by the out-format output).</p>
! 2921: </dd>
! 2922:
! 2923: <dt><code>--log-file=FILE</code></dt><dd>
! 2924: <p>This option causes rsync to log what it is doing to a file. This is
! 2925: similar to the logging that a daemon does, but can be requested for the
! 2926: client side and/or the server side of a non-daemon transfer. If specified
! 2927: as a client option, transfer logging will be enabled with a default format
! 2928: of "%i %n%L". See the <code>--log-file-format</code> option if you wish to override
! 2929: this.</p>
! 2930: <p>Here's a example command that requests the remote side to log what is
! 2931: happening:</p>
! 2932: <blockquote>
! 2933: <pre><code>rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/
! 2934: </code></pre>
! 2935: </blockquote>
! 2936: <p>This is very useful if you need to debug why a connection is closing
! 2937: unexpectedly.</p>
! 2938: </dd>
! 2939:
! 2940: <dt><code>--log-file-format=FORMAT</code></dt><dd>
! 2941: <p>This allows you to specify exactly what per-update logging is put into the
! 2942: file specified by the <code>--log-file</code> option (which must also be specified for
! 2943: this option to have any effect). If you specify an empty string, updated
! 2944: files will not be mentioned in the log file. For a list of the possible
! 2945: escape characters, see the "<code>log format</code>" setting in the rsyncd.conf manpage.</p>
! 2946: <p>The default FORMAT used if <code>--log-file</code> is specified and this option is not
! 2947: is '%i %n%L'.</p>
! 2948: </dd>
! 2949:
! 2950: <dt><code>--stats</code></dt><dd>
! 2951: <p>This tells rsync to print a verbose set of statistics on the file transfer,
! 2952: allowing you to tell how effective rsync's delta-transfer algorithm is for
! 2953: your data. This option is equivalent to <code>--info=stats2</code> if combined with 0
! 2954: or 1 <code>-v</code> options, or <code>--info=stats3</code> if combined with 2 or more <code>-v</code>
! 2955: options.</p>
! 2956: <p>The current statistics are as follows:</p>
! 2957: <ul>
! 2958: <li><code>Number of files</code> is the count of all "files" (in the generic sense),
! 2959: which includes directories, symlinks, etc. The total count will be
! 2960: followed by a list of counts by filetype (if the total is non-zero). For
! 2961: example: "(reg: 5, dir: 3, link: 2, dev: 1, special: 1)" lists the totals
! 2962: for regular files, directories, symlinks, devices, and special files. If
! 2963: any of value is 0, it is completely omitted from the list.</li>
! 2964: <li><code>Number of created files</code> is the count of how many "files" (generic
! 2965: sense) were created (as opposed to updated). The total count will be
! 2966: followed by a list of counts by filetype (if the total is non-zero).</li>
! 2967: <li><code>Number of deleted files</code> is the count of how many "files" (generic
! 2968: sense) were created (as opposed to updated). The total count will be
! 2969: followed by a list of counts by filetype (if the total is non-zero).
! 2970: Note that this line is only output if deletions are in effect, and only
! 2971: if protocol 31 is being used (the default for rsync 3.1.x).</li>
! 2972: <li><code>Number of regular files transferred</code> is the count of normal files that
! 2973: were updated via rsync's delta-transfer algorithm, which does not include
! 2974: dirs, symlinks, etc. Note that rsync 3.1.0 added the word "regular" into
! 2975: this heading.</li>
! 2976: <li><code>Total file size</code> is the total sum of all file sizes in the transfer.
! 2977: This does not count any size for directories or special files, but does
! 2978: include the size of symlinks.</li>
! 2979: <li><code>Total transferred file size</code> is the total sum of all files sizes for
! 2980: just the transferred files.</li>
! 2981: <li><code>Literal data</code> is how much unmatched file-update data we had to send to
! 2982: the receiver for it to recreate the updated files.</li>
! 2983: <li><code>Matched data</code> is how much data the receiver got locally when recreating
! 2984: the updated files.</li>
! 2985: <li><code>File list size</code> is how big the file-list data was when the sender sent
! 2986: it to the receiver. This is smaller than the in-memory size for the file
! 2987: list due to some compressing of duplicated data when rsync sends the
! 2988: list.</li>
! 2989: <li><code>File list generation time</code> is the number of seconds that the sender
! 2990: spent creating the file list. This requires a modern rsync on the
! 2991: sending side for this to be present.</li>
! 2992: <li><code>File list transfer time</code> is the number of seconds that the sender spent
! 2993: sending the file list to the receiver.</li>
! 2994: <li><code>Total bytes sent</code> is the count of all the bytes that rsync sent from the
! 2995: client side to the server side.</li>
! 2996: <li><code>Total bytes received</code> is the count of all non-message bytes that rsync
! 2997: received by the client side from the server side. "Non-message" bytes
! 2998: means that we don't count the bytes for a verbose message that the server
! 2999: sent to us, which makes the stats more consistent.</li>
! 3000: </ul>
! 3001: </dd>
! 3002:
! 3003: <dt><code>--8-bit-output</code>, <code>-8</code></dt><dd>
! 3004: <p>This tells rsync to leave all high-bit characters unescaped in the output
! 3005: instead of trying to test them to see if they're valid in the current
! 3006: locale and escaping the invalid ones. All control characters (but never
! 3007: tabs) are always escaped, regardless of this option's setting.</p>
! 3008: <p>The escape idiom that started in 2.6.7 is to output a literal backslash
! 3009: (<code>\</code>) and a hash (<code>#</code>), followed by exactly 3 octal digits. For example, a
! 3010: newline would output as "<code>\#012</code>". A literal backslash that is in a
! 3011: filename is not escaped unless it is followed by a hash and 3 digits (0-9).</p>
! 3012: </dd>
! 3013:
! 3014: <dt><code>--human-readable</code>, <code>-h</code></dt><dd>
! 3015: <p>Output numbers in a more human-readable format. There are 3 possible
! 3016: levels: (1) output numbers with a separator between each set of 3 digits
! 3017: (either a comma or a period, depending on if the decimal point is
! 3018: represented by a period or a comma); (2) output numbers in units of 1000
! 3019: (with a character suffix for larger units -⁠-⁠ see below); (3) output
! 3020: numbers in units of 1024.</p>
! 3021: <p>The default is human-readable level 1. Each <code>-h</code> option increases the
! 3022: level by one. You can take the level down to 0 (to output numbers as pure
! 3023: digits) by specifying the <code>--no-human-readable</code> (<code>--no-h</code>) option.</p>
! 3024: <p>The unit letters that are appended in levels 2 and 3 are: <code>K</code> (kilo), <code>M</code>
! 3025: (mega), <code>G</code> (giga), <code>T</code> (tera), or <code>P</code> (peta). For example, a 1234567-byte
! 3026: file would output as 1.23M in level-2 (assuming that a period is your local
! 3027: decimal point).</p>
! 3028: <p>Backward compatibility note: versions of rsync prior to 3.1.0 do not
! 3029: support human-readable level 1, and they default to level 0. Thus,
! 3030: specifying one or two <code>-h</code> options will behave in a comparable manner in
! 3031: old and new versions as long as you didn't specify a <code>--no-h</code> option prior
! 3032: to one or more <code>-h</code> options. See the <code>--list-only</code> option for one
! 3033: difference.</p>
! 3034: </dd>
! 3035:
! 3036: <dt><code>--partial</code></dt><dd>
! 3037: <p>By default, rsync will delete any partially transferred file if the
! 3038: transfer is interrupted. In some circumstances it is more desirable to
! 3039: keep partially transferred files. Using the <code>--partial</code> option tells rsync
! 3040: to keep the partial file which should make a subsequent transfer of the
! 3041: rest of the file much faster.</p>
! 3042: </dd>
! 3043:
! 3044: <dt><code>--partial-dir=DIR</code></dt><dd>
! 3045: <p>A better way to keep partial files than the <code>--partial</code> option is to
! 3046: specify a <u>DIR</u> that will be used to hold the partial data (instead of
! 3047: writing it out to the destination file). On the next transfer, rsync will
! 3048: use a file found in this dir as data to speed up the resumption of the
! 3049: transfer and then delete it after it has served its purpose.</p>
! 3050: <p>Note that if <code>--whole-file</code> is specified (or implied), any partial-dir file
! 3051: that is found for a file that is being updated will simply be removed
! 3052: (since rsync is sending files without using rsync's delta-transfer
! 3053: algorithm).</p>
! 3054: <p>Rsync will create the <u>DIR</u> if it is missing (just the last dir -⁠-⁠ not the
! 3055: whole path). This makes it easy to use a relative path (such as
! 3056: "<code>--partial-dir=.rsync-partial</code>") to have rsync create the
! 3057: partial-directory in the destination file's directory when needed, and then
! 3058: remove it again when the partial file is deleted. Note that the directory
! 3059: is only removed if it is a relative pathname, as it is expected that an
! 3060: absolute path is to a directory that is reserved for partial-dir work.</p>
! 3061: <p>If the partial-dir value is not an absolute path, rsync will add an exclude
! 3062: rule at the end of all your existing excludes. This will prevent the
! 3063: sending of any partial-dir files that may exist on the sending side, and
! 3064: will also prevent the untimely deletion of partial-dir items on the
! 3065: receiving side. An example: the above <code>--partial-dir</code> option would add the
! 3066: equivalent of "<code>-f '-p .rsync-partial/'</code>" at the end of any other filter
! 3067: rules.</p>
! 3068: <p>If you are supplying your own exclude rules, you may need to add your own
! 3069: exclude/hide/protect rule for the partial-dir because (1) the auto-added
! 3070: rule may be ineffective at the end of your other rules, or (2) you may wish
! 3071: to override rsync's exclude choice. For instance, if you want to make
! 3072: rsync clean-up any left-over partial-dirs that may be lying around, you
! 3073: should specify <code>--delete-after</code> and add a "risk" filter rule, e.g.
! 3074: <code>-f 'R .rsync-partial/'</code>. (Avoid using <code>--delete-before</code> or
! 3075: <code>--delete-during</code> unless you don't need rsync to use any of the left-over
! 3076: partial-dir data during the current run.)</p>
! 3077: <p>IMPORTANT: the <code>--partial-dir</code> should not be writable by other users or it
! 3078: is a security risk. E.g. AVOID "/tmp".</p>
! 3079: <p>You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
! 3080: variable. Setting this in the environment does not force <code>--partial</code> to be
! 3081: enabled, but rather it affects where partial files go when <code>--partial</code> is
! 3082: specified. For instance, instead of using <code>--partial-dir=.rsync-tmp</code> along
! 3083: with <code>--progress</code>, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
! 3084: environment and then just use the <code>-P</code> option to turn on the use of the
! 3085: .rsync-tmp dir for partial transfers. The only times that the <code>--partial</code>
! 3086: option does not look for this environment value are (1) when <code>--inplace</code>
! 3087: was specified (since <code>--inplace</code> conflicts with <code>--partial-dir</code>), and (2)
! 3088: when <code>--delay-updates</code> was specified (see below).</p>
! 3089: <p>When a modern rsync resumes the transfer of a file in the partial-dir, that
! 3090: partial file is now updated in-place instead of creating yet another
! 3091: tmp-file copy (so it maxes out at dest + tmp instead of dest + partial +
! 3092: tmp). This requires both ends of the transfer to be at least version
! 3093: 3.2.0.</p>
! 3094: <p>For the purposes of the daemon-config's "<code>refuse options</code>" setting,
! 3095: <code>--partial-dir</code> does <u>not</u> imply <code>--partial</code>. This is so that a refusal of
! 3096: the <code>--partial</code> option can be used to disallow the overwriting of
! 3097: destination files with a partial transfer, while still allowing the safer
! 3098: idiom provided by <code>--partial-dir</code>.</p>
! 3099: </dd>
! 3100:
! 3101: <dt><code>--delay-updates</code></dt><dd>
! 3102: <p>This option puts the temporary file from each updated file into a holding
! 3103: directory until the end of the transfer, at which time all the files are
! 3104: renamed into place in rapid succession. This attempts to make the updating
! 3105: of the files a little more atomic. By default the files are placed into a
! 3106: directory named <code>.~tmp~</code> in each file's destination directory, but if
! 3107: you've specified the <code>--partial-dir</code> option, that directory will be used
! 3108: instead. See the comments in the <code>--partial-dir</code> section for a discussion
! 3109: of how this <code>.~tmp~</code> dir will be excluded from the transfer, and what you
! 3110: can do if you want rsync to cleanup old <code>.~tmp~</code> dirs that might be lying
! 3111: around. Conflicts with <code>--inplace</code> and <code>--append</code>.</p>
! 3112: <p>This option implies <code>--no-inc-recursive</code> since it needs the full file list
! 3113: in memory in order to be able to iterate over it at the end.</p>
! 3114: <p>This option uses more memory on the receiving side (one bit per file
! 3115: transferred) and also requires enough free disk space on the receiving side
! 3116: to hold an additional copy of all the updated files. Note also that you
! 3117: should not use an absolute path to <code>--partial-dir</code> unless (1) there is no
! 3118: chance of any of the files in the transfer having the same name (since all
! 3119: the updated files will be put into a single directory if the path is
! 3120: absolute) and (2) there are no mount points in the hierarchy (since the
! 3121: delayed updates will fail if they can't be renamed into place).</p>
! 3122: <p>See also the "atomic-rsync" perl script in the "support" subdir for an
! 3123: update algorithm that is even more atomic (it uses <code>--link-dest</code> and a
! 3124: parallel hierarchy of files).</p>
! 3125: </dd>
! 3126:
! 3127: <dt><code>--direct-io</code></dt><dd>
! 3128: <p>This option opens files with a direct-I/O flag that makes the file I/O
! 3129: avoid the buffer cache. The option only affects one side of the transfer
! 3130: (unless the transfer is local). If you want it to affect both sides, use
! 3131: the <code>--remote-option</code> (<code>-M</code>) option to specify it for the remote side. For
! 3132: instance, this specifies it for both sides:</p>
! 3133: <blockquote>
! 3134: <pre><code>rsync -av {,-M}--direct-io /src/ host:/dest/
! 3135: </code></pre>
! 3136: </blockquote>
! 3137: </dd>
! 3138:
! 3139: <dt><code>--prune-empty-dirs</code>, <code>-m</code></dt><dd>
! 3140: <p>This option tells the receiving rsync to get rid of empty directories from
! 3141: the file-list, including nested directories that have no non-directory
! 3142: children. This is useful for avoiding the creation of a bunch of useless
! 3143: directories when the sending rsync is recursively scanning a hierarchy of
! 3144: files using include/exclude/filter rules.</p>
! 3145: <p>Note that the use of transfer rules, such as the <code>--min-size</code> option, does
! 3146: not affect what goes into the file list, and thus does not leave
! 3147: directories empty, even if none of the files in a directory match the
! 3148: transfer rule.</p>
! 3149: <p>Because the file-list is actually being pruned, this option also affects
! 3150: what directories get deleted when a delete is active. However, keep in
! 3151: mind that excluded files and directories can prevent existing items from
! 3152: being deleted due to an exclude both hiding source files and protecting
! 3153: destination files. See the perishable filter-rule option for how to avoid
! 3154: this.</p>
! 3155: <p>You can prevent the pruning of certain empty directories from the file-list
! 3156: by using a global "protect" filter. For instance, this option would ensure
! 3157: that the directory "emptydir" was kept in the file-list:</p>
! 3158: <blockquote>
! 3159: <pre><code>--filter 'protect emptydir/'
! 3160: </code></pre>
! 3161: </blockquote>
! 3162: <p>Here's an example that copies all .pdf files in a hierarchy, only creating
! 3163: the necessary destination directories to hold the .pdf files, and ensures
! 3164: that any superfluous files and directories in the destination are removed
! 3165: (note the hide filter of non-directories being used instead of an exclude):</p>
! 3166: <blockquote>
! 3167: <pre><code>rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest
! 3168: </code></pre>
! 3169: </blockquote>
! 3170: <p>If you didn't want to remove superfluous destination files, the more
! 3171: time-honored options of <code>--include='*/' --exclude='*'</code> would work
! 3172: fine in place of the hide-filter (if that is more natural to you).</p>
! 3173: </dd>
! 3174:
! 3175: <dt><code>--progress</code></dt><dd>
! 3176: <p>This option tells rsync to print information showing the progress of the
! 3177: transfer. This gives a bored user something to watch. With a modern rsync
! 3178: this is the same as specifying <code>--info=flist2,name,progress</code>, but any
! 3179: user-supplied settings for those info flags takes precedence (e.g.
! 3180: "<code>--info=flist0 --progress</code>").</p>
! 3181: <p>While rsync is transferring a regular file, it updates a progress line that
! 3182: looks like this:</p>
! 3183: <blockquote>
! 3184: <pre><code>782448 63% 110.64kB/s 0:00:04
! 3185: </code></pre>
! 3186: </blockquote>
! 3187: <p>In this example, the receiver has reconstructed 782448 bytes or 63% of the
! 3188: sender's file, which is being reconstructed at a rate of 110.64 kilobytes
! 3189: per second, and the transfer will finish in 4 seconds if the current rate
! 3190: is maintained until the end.</p>
! 3191: <p>These statistics can be misleading if rsync's delta-transfer algorithm is
! 3192: in use. For example, if the sender's file consists of the basis file
! 3193: followed by additional data, the reported rate will probably drop
! 3194: dramatically when the receiver gets to the literal data, and the transfer
! 3195: will probably take much longer to finish than the receiver estimated as it
! 3196: was finishing the matched part of the file.</p>
! 3197: <p>When the file transfer finishes, rsync replaces the progress line with a
! 3198: summary line that looks like this:</p>
! 3199: <blockquote>
! 3200: <pre><code>1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396)
! 3201: </code></pre>
! 3202: </blockquote>
! 3203: <p>In this example, the file was 1,238,099 bytes long in total, the average
! 3204: rate of transfer for the whole file was 146.38 kilobytes per second over
! 3205: the 8 seconds that it took to complete, it was the 5th transfer of a
! 3206: regular file during the current rsync session, and there are 169 more files
! 3207: for the receiver to check (to see if they are up-to-date or not) remaining
! 3208: out of the 396 total files in the file-list.</p>
! 3209: <p>In an incremental recursion scan, rsync won't know the total number of
! 3210: files in the file-list until it reaches the ends of the scan, but since it
! 3211: starts to transfer files during the scan, it will display a line with the
! 3212: text "ir-chk" (for incremental recursion check) instead of "to-chk" until
! 3213: the point that it knows the full size of the list, at which point it will
! 3214: switch to using "to-chk". Thus, seeing "ir-chk" lets you know that the
! 3215: total count of files in the file list is still going to increase (and each
! 3216: time it does, the count of files left to check will increase by the number
! 3217: of the files added to the list).</p>
! 3218: </dd>
! 3219:
! 3220: <dt><code>-P</code></dt><dd>
! 3221: <p>The <code>-P</code> option is equivalent to <code>--partial --progress</code>. Its purpose is
! 3222: to make it much easier to specify these two options for a long transfer
! 3223: that may be interrupted.</p>
! 3224: <p>There is also a <code>--info=progress2</code> option that outputs statistics based on
! 3225: the whole transfer, rather than individual files. Use this flag without
! 3226: outputting a filename (e.g. avoid <code>-v</code> or specify <code>--info=name0</code>) if you
! 3227: want to see how the transfer is doing without scrolling the screen with a
! 3228: lot of names. (You don't need to specify the <code>--progress</code> option in order
! 3229: to use <code>--info=progress2</code>.)</p>
! 3230: <p>Finally, you can get an instant progress report by sending rsync a signal
! 3231: of either SIGINFO or SIGVTALRM. On BSD systems, a SIGINFO is generated by
! 3232: typing a Ctrl+T (Linux doesn't currently support a SIGINFO signal). When
! 3233: the client-side process receives one of those signals, it sets a flag to
! 3234: output a single progress report which is output when the current file
! 3235: transfer finishes (so it may take a little time if a big file is being
! 3236: handled when the signal arrives). A filename is output (if needed)
! 3237: followed by the <code>--info=progress2</code> format of progress info. If you don't
! 3238: know which of the 3 rsync processes is the client process, it's OK to
! 3239: signal all of them (since the non-client processes ignore the signal).</p>
! 3240: <p>CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it.</p>
! 3241: </dd>
! 3242:
! 3243: <dt><code>--password-file=FILE</code></dt><dd>
! 3244: <p>This option allows you to provide a password for accessing an rsync daemon
! 3245: via a file or via standard input if <strong>FILE</strong> is <code>-</code>. The file should
! 3246: contain just the password on the first line (all other lines are ignored).
! 3247: Rsync will exit with an error if <strong>FILE</strong> is world readable or if a
! 3248: root-run rsync command finds a non-root-owned file.</p>
! 3249: <p>This option does not supply a password to a remote shell transport such as
! 3250: ssh; to learn how to do that, consult the remote shell's documentation.
! 3251: When accessing an rsync daemon using a remote shell as the transport, this
! 3252: option only comes into effect after the remote shell finishes its
! 3253: authentication (i.e. if you have also specified a password in the daemon's
! 3254: config file).</p>
! 3255: </dd>
! 3256:
! 3257: <dt><code>--early-input=FILE</code></dt><dd>
! 3258: <p>This option allows rsync to send up to 5K of data to the "early exec"
! 3259: script on its stdin. One possible use of this data is to give the script a
! 3260: secret that can be used to mount an encrypted filesystem (which you should
! 3261: unmount in the the "post-xfer exec" script).</p>
! 3262: <p>The daemon must be at least version 3.2.1.</p>
! 3263: </dd>
! 3264:
! 3265: <dt><code>--list-only</code></dt><dd>
! 3266: <p>This option will cause the source files to be listed instead of
! 3267: transferred. This option is inferred if there is a single source arg and
! 3268: no destination specified, so its main uses are: (1) to turn a copy command
! 3269: that includes a destination arg into a file-listing command, or (2) to be
! 3270: able to specify more than one source arg (note: be sure to include the
! 3271: destination). Caution: keep in mind that a source arg with a wild-card is
! 3272: expanded by the shell into multiple args, so it is never safe to try to
! 3273: list such an arg without using this option. For example:</p>
! 3274: <blockquote>
! 3275: <pre><code>rsync -av --list-only foo* dest/
! 3276: </code></pre>
! 3277: </blockquote>
! 3278: <p>Starting with rsync 3.1.0, the sizes output by <code>--list-only</code> are affected
! 3279: by the <code>--human-readable</code> option. By default they will contain digit
! 3280: separators, but higher levels of readability will output the sizes with
! 3281: unit suffixes. Note also that the column width for the size output has
! 3282: increased from 11 to 14 characters for all human-readable levels. Use
! 3283: <code>--no-h</code> if you want just digits in the sizes, and the old column width of
! 3284: 11 characters.</p>
! 3285: <p>Compatibility note: when requesting a remote listing of files from an rsync
! 3286: that is version 2.6.3 or older, you may encounter an error if you ask for a
! 3287: non-recursive listing. This is because a file listing implies the <code>--dirs</code>
! 3288: option w/o <code>--recursive</code>, and older rsyncs don't have that option. To
! 3289: avoid this problem, either specify the <code>--no-dirs</code> option (if you don't
! 3290: need to expand a directory's content), or turn on recursion and exclude the
! 3291: content of subdirectories: <code>-r --exclude='/*/*'</code>.</p>
! 3292: </dd>
! 3293:
! 3294: <dt><code>--bwlimit=RATE</code></dt><dd>
! 3295: <p>This option allows you to specify the maximum transfer rate for the data
! 3296: sent over the socket, specified in units per second. The RATE value can be
! 3297: suffixed with a string to indicate a size multiplier, and may be a
! 3298: fractional value (e.g. "<code>--bwlimit=1.5m</code>"). If no suffix is specified, the
! 3299: value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had
! 3300: been appended). See the <code>--max-size</code> option for a description of all the
! 3301: available suffixes. A value of 0 specifies no limit.</p>
! 3302: <p>For backward-compatibility reasons, the rate limit will be rounded to the
! 3303: nearest KiB unit, so no rate smaller than 1024 bytes per second is
! 3304: possible.</p>
! 3305: <p>Rsync writes data over the socket in blocks, and this option both limits
! 3306: the size of the blocks that rsync writes, and tries to keep the average
! 3307: transfer rate at the requested limit. Some burstiness may be seen where
! 3308: rsync writes out a block of data and then sleeps to bring the average rate
! 3309: into compliance.</p>
! 3310: <p>Due to the internal buffering of data, the <code>--progress</code> option may not be
! 3311: an accurate reflection on how fast the data is being sent. This is because
! 3312: some files can show up as being rapidly sent when the data is quickly
! 3313: buffered, while other can show up as very slow when the flushing of the
! 3314: output buffer occurs. This may be fixed in a future version.</p>
! 3315: </dd>
! 3316:
! 3317: <dt>`-⁠-⁠stop-after=MINS</dt><dd>
! 3318: <p>This option tells rsync to stop copying when the specified number of
! 3319: minutes has elapsed.</p>
! 3320: <p>Rsync also accepts an earlier version of this option: <code>--time-limit=MINS</code>.</p>
! 3321: <p>For maximal flexibility, rsync does not communicate this option to the
! 3322: remote rsync since it is usually enough that one side of the connection
! 3323: quits as specified. This allows the option's use even when only one side
! 3324: of the connection supports it. You can tell the remote side about the time
! 3325: limit using <code>--remote-option</code> (<code>-M</code>), should the need arise.</p>
! 3326: </dd>
! 3327:
! 3328: <dt>`-⁠-⁠stop-at=y-m-dTh:m</dt><dd>
! 3329: <p>This option tells rsync to stop copying when the specified point in time
! 3330: has been reached. The date & time can be fully specified in a numeric
! 3331: format of year-month-dayThour:minute (e.g. 2000-12-31T23:59) in the local
! 3332: timezone. You may choose to separate the date numbers using slashes
! 3333: instead of dashes.</p>
! 3334: <p>The value can also be abbreviated in a variety of ways, such as specifying
! 3335: a 2-digit year and/or leaving off various values. In all cases, the value
! 3336: will be taken to be the next possible point in time where the supplied
! 3337: information matches. If the value specifies the current time or a past
! 3338: time, rsync exits with an error.</p>
! 3339: <p>For example, "1-30" specifies the next January 30th (at midnight local
! 3340: time), "14:00" specifies the next 2 P.M., "1" specifies the next 1st of the
! 3341: month at midnight, "31" specifies the next month where we can stop on its
! 3342: 31st day, and ":59" specifies the next 59th minute after the hour.</p>
! 3343: <p>For maximal flexibility, rsync does not communicate this option to the
! 3344: remote rsync since it is usually enough that one side of the connection
! 3345: quits as specified. This allows the option's use even when only one side
! 3346: of the connection supports it. You can tell the remote side about the time
! 3347: limit using <code>--remote-option</code> (<code>-M</code>), should the need arise. Do keep in
! 3348: mind that the remote host may have a different default timezone than your
! 3349: local host.</p>
! 3350: </dd>
! 3351:
! 3352: <dt><code>--write-batch=FILE</code></dt><dd>
! 3353: <p>Record a file that can later be applied to another identical destination
! 3354: with <code>--read-batch</code>. See the "BATCH MODE" section for details, and also
! 3355: the <code>--only-write-batch</code> option.</p>
! 3356: <p>This option overrides the negotiated checksum & compress lists and always
! 3357: negotiates a choice based on old-school md5/md4/zlib choices. If you want
! 3358: a more modern choice, use the <code>--checksum-choice</code> (<code>--cc</code>) and/or
! 3359: <code>--compress-choice</code> (<code>--zc</code>) options.</p>
! 3360: </dd>
! 3361:
! 3362: <dt><code>--only-write-batch=FILE</code></dt><dd>
! 3363: <p>Works like <code>--write-batch</code>, except that no updates are made on the
! 3364: destination system when creating the batch. This lets you transport the
! 3365: changes to the destination system via some other means and then apply the
! 3366: changes via <code>--read-batch</code>.</p>
! 3367: <p>Note that you can feel free to write the batch directly to some portable
! 3368: media: if this media fills to capacity before the end of the transfer, you
! 3369: can just apply that partial transfer to the destination and repeat the
! 3370: whole process to get the rest of the changes (as long as you don't mind a
! 3371: partially updated destination system while the multi-update cycle is
! 3372: happening).</p>
! 3373: <p>Also note that you only save bandwidth when pushing changes to a remote
! 3374: system because this allows the batched data to be diverted from the sender
! 3375: into the batch file without having to flow over the wire to the receiver
! 3376: (when pulling, the sender is remote, and thus can't write the batch).</p>
! 3377: </dd>
! 3378:
! 3379: <dt><code>--read-batch=FILE</code></dt><dd>
! 3380: <p>Apply all of the changes stored in FILE, a file previously generated by
! 3381: <code>--write-batch</code>. If <u>FILE</u> is <code>-</code>, the batch data will be read from
! 3382: standard input. See the "BATCH MODE" section for details.</p>
! 3383: </dd>
! 3384:
! 3385: <dt><code>--source-filter=COMMAND</code></dt><dd>
! 3386: <p>This option allows the user to specify a filter program that will be
! 3387: applied to the contents of all transferred regular files before the data is
! 3388: sent to destination. COMMAND will receive the data on its standard input
! 3389: and it should write the filtered data to standard output. COMMAND should
! 3390: exit non-zero if it cannot process the data or if it encounters an error
! 3391: when writing the data to stdout.</p>
! 3392: <p>Example: <code>--source-filter="gzip -9"</code> will cause remote files to be
! 3393: compressed. Use of <code>--source-filter</code> automatically enables <code>--whole-file</code>.
! 3394: If your filter does not output the same number of bytes that it received on
! 3395: input, you should use <code>--times-only</code> to disable size and content checks on
! 3396: subsequent rsync runs.</p>
! 3397: </dd>
! 3398:
! 3399: <dt><code>--dest-filter=COMMAND</code></dt><dd>
! 3400: <p>This option allows you to specify a filter program that will be applied to
! 3401: the contents of all transferred regular files before the data is written to
! 3402: disk. COMMAND will receive the data on its standard input and it should
! 3403: write the filtered data to standard output. COMMAND should exit non-zero
! 3404: if it cannot process the data or if it encounters an error when writing the
! 3405: data to stdout.</p>
! 3406: <p>Example: -⁠-⁠dest-filter="gzip -⁠9" will cause remote files to be compressed.
! 3407: Use of -⁠-⁠dest-filter automatically enables -⁠-⁠whole-file. If your filter
! 3408: does not output the same number of bytes that it received on input, you
! 3409: should use -⁠-⁠times-only to disable size and content checks on subsequent
! 3410: rsync runs.</p>
! 3411: </dd>
! 3412:
! 3413: <dt><code>--protocol=NUM</code></dt><dd>
! 3414: <p>Force an older protocol version to be used. This is useful for creating a
! 3415: batch file that is compatible with an older version of rsync. For
! 3416: instance, if rsync 2.6.4 is being used with the <code>--write-batch</code> option, but
! 3417: rsync 2.6.3 is what will be used to run the <code>--read-batch</code> option, you
! 3418: should use "-⁠-⁠protocol=28" when creating the batch file to force the older
! 3419: protocol version to be used in the batch file (assuming you can't upgrade
! 3420: the rsync on the reading system).</p>
! 3421: </dd>
! 3422:
! 3423: <dt><code>--iconv=CONVERT_SPEC</code></dt><dd>
! 3424: <p>Rsync can convert filenames between character sets using this option.
! 3425: Using a CONVERT_SPEC of "." tells rsync to look up the default
! 3426: character-set via the locale setting. Alternately, you can fully specify
! 3427: what conversion to do by giving a local and a remote charset separated by a
! 3428: comma in the order <code>--iconv=LOCAL,REMOTE</code>, e.g. <code>--iconv=utf8,iso88591</code>.
! 3429: This order ensures that the option will stay the same whether you're
! 3430: pushing or pulling files. Finally, you can specify either <code>--no-iconv</code> or
! 3431: a CONVERT_SPEC of "-⁠" to turn off any conversion. The default setting of
! 3432: this option is site-specific, and can also be affected via the RSYNC_ICONV
! 3433: environment variable.</p>
! 3434: <p>For a list of what charset names your local iconv library supports, you can
! 3435: run "<code>iconv --list</code>".</p>
! 3436: <p>If you specify the <code>--protect-args</code> option (<code>-s</code>), rsync will translate the
! 3437: filenames you specify on the command-line that are being sent to the remote
! 3438: host. See also the <code>--files-from</code> option.</p>
! 3439: <p>Note that rsync does not do any conversion of names in filter files
! 3440: (including include/exclude files). It is up to you to ensure that you're
! 3441: specifying matching rules that can match on both sides of the transfer.
! 3442: For instance, you can specify extra include/exclude rules if there are
! 3443: filename differences on the two sides that need to be accounted for.</p>
! 3444: <p>When you pass an <code>--iconv</code> option to an rsync daemon that allows it, the
! 3445: daemon uses the charset specified in its "charset" configuration parameter
! 3446: regardless of the remote charset you actually pass. Thus, you may feel
! 3447: free to specify just the local charset for a daemon transfer (e.g.
! 3448: <code>--iconv=utf8</code>).</p>
! 3449: </dd>
! 3450:
! 3451: <dt><code>--tr=BAD/GOOD</code></dt><dd>
! 3452: <p>Transliterates filenames on the receiver, after the iconv conversion (if
! 3453: any). This can be used to remove characters illegal on the destination
! 3454: filesystem. If you use this option, consider saving a "find . -⁠ls" listing
! 3455: of the source in the destination to help you determine the original
! 3456: filenames in case of need.</p>
! 3457: <p>The argument consists of a string of characters to remove, optionally
! 3458: followed by a slash and a string of corresponding characters with which to
! 3459: replace them. The second string may be shorter, in which case any leftover
! 3460: characters in the first string are simply deleted. For example,
! 3461: <code>--tr=':\/!'</code> replaces colons with exclamation marks and deletes
! 3462: backslashes. Slashes cannot be transliterated because it would cause
! 3463: havoc.</p>
! 3464: <p>If the receiver is invoked over a remote shell, use <code>--protect-args</code> to
! 3465: stop the shell from interpreting any nasty characters in the argument.</p>
! 3466: </dd>
! 3467:
! 3468: <dt><code>--ipv4</code>, <code>-4</code> or <code>--ipv6</code>, <code>-6</code></dt><dd>
! 3469: <p>Tells rsync to prefer IPv4/IPv6 when creating sockets or running ssh. This
! 3470: affects sockets that rsync has direct control over, such as the outgoing
! 3471: socket when directly contacting an rsync daemon, as well as the forwarding
! 3472: of the <code>-4</code> or <code>-6</code> option to ssh when rsync can deduce that ssh is being
! 3473: used as the remote shell. For other remote shells you'll need to specify
! 3474: the "<code>--rsh SHELL -4</code>" option directly (or whatever ipv4/ipv6 hint options
! 3475: it uses).</p>
! 3476: <p>These options also exist in the <code>--daemon</code> mode section.</p>
! 3477: <p>If rsync was complied without support for IPv6, the <code>--ipv6</code> option will
! 3478: have no effect. The <code>rsync --version</code> output will contain "<code>no IPv6</code>" if
! 3479: is the case.</p>
! 3480: </dd>
! 3481:
! 3482: <dt><code>--checksum-seed=NUM</code></dt><dd>
! 3483: <p>Set the checksum seed to the integer NUM. This 4 byte checksum seed is
! 3484: included in each block and MD4 file checksum calculation (the more modern
! 3485: MD5 file checksums don't use a seed). By default the checksum seed is
! 3486: generated by the server and defaults to the current <strong>time</strong>(). This
! 3487: option is used to set a specific checksum seed, which is useful for
! 3488: applications that want repeatable block checksums, or in the case where the
! 3489: user wants a more random checksum seed. Setting NUM to 0 causes rsync to
! 3490: use the default of <strong>time</strong>() for checksum seed.</p>
! 3491: </dd>
! 3492: </dl>
! 3493: <h1>DAEMON OPTIONS</h1>
! 3494: <p>The options allowed when starting an rsync daemon are as follows:</p>
! 3495: <dl>
! 3496:
! 3497: <dt><code>--daemon</code></dt><dd>
! 3498: <p>This tells rsync that it is to run as a daemon. The daemon you start
! 3499: running may be accessed using an rsync client using the <code>host::module</code> or
! 3500: <code>rsync://host/module/</code> syntax.</p>
! 3501: <p>If standard input is a socket then rsync will assume that it is being run
! 3502: via inetd, otherwise it will detach from the current terminal and become a
! 3503: background daemon. The daemon will read the config file (rsyncd.conf) on
! 3504: each connect made by a client and respond to requests accordingly. See the
! 3505: <strong>rsyncd.conf</strong>(5) man page for more details.</p>
! 3506: </dd>
! 3507:
! 3508: <dt><code>--address=ADDRESS</code></dt><dd>
! 3509: <p>By default rsync will bind to the wildcard address when run as a daemon
! 3510: with the <code>--daemon</code> option. The <code>--address</code> option allows you to specify a
! 3511: specific IP address (or hostname) to bind to. This makes virtual hosting
! 3512: possible in conjunction with the <code>--config</code> option. See also the "address"
! 3513: global option in the rsyncd.conf manpage.</p>
! 3514: </dd>
! 3515:
! 3516: <dt><code>--bwlimit=RATE</code></dt><dd>
! 3517: <p>This option allows you to specify the maximum transfer rate for the data
! 3518: the daemon sends over the socket. The client can still specify a smaller
! 3519: <code>--bwlimit</code> value, but no larger value will be allowed. See the client
! 3520: version of this option (above) for some extra details.</p>
! 3521: </dd>
! 3522:
! 3523: <dt><code>--config=FILE</code></dt><dd>
! 3524: <p>This specifies an alternate config file than the default. This is only
! 3525: relevant when <code>--daemon</code> is specified. The default is /etc/rsyncd.conf
! 3526: unless the daemon is running over a remote shell program and the remote
! 3527: user is not the super-user; in that case the default is rsyncd.conf in the
! 3528: current directory (typically $HOME).</p>
! 3529: </dd>
! 3530:
! 3531: <dt><code>--dparam=OVERRIDE</code>, <code>-M</code></dt><dd>
! 3532: <p>This option can be used to set a daemon-config parameter when starting up
! 3533: rsync in daemon mode. It is equivalent to adding the parameter at the end
! 3534: of the global settings prior to the first module's definition. The
! 3535: parameter names can be specified without spaces, if you so desire. For
! 3536: instance:</p>
! 3537: <blockquote>
! 3538: <pre><code>rsync --daemon -M pidfile=/path/rsync.pid
! 3539: </code></pre>
! 3540: </blockquote>
! 3541: </dd>
! 3542:
! 3543: <dt><code>--no-detach</code></dt><dd>
! 3544: <p>When running as a daemon, this option instructs rsync to not detach itself
! 3545: and become a background process. This option is required when running as a
! 3546: service on Cygwin, and may also be useful when rsync is supervised by a
! 3547: program such as <code>daemontools</code> or AIX's <code>System Resource Controller</code>.
! 3548: <code>--no-detach</code> is also recommended when rsync is run under a debugger. This
! 3549: option has no effect if rsync is run from inetd or sshd.</p>
! 3550: </dd>
! 3551:
! 3552: <dt><code>--port=PORT</code></dt><dd>
! 3553: <p>This specifies an alternate TCP port number for the daemon to listen on
! 3554: rather than the default of 873. See also the "port" global option in the
! 3555: rsyncd.conf manpage.</p>
! 3556: </dd>
! 3557:
! 3558: <dt><code>--log-file=FILE</code></dt><dd>
! 3559: <p>This option tells the rsync daemon to use the given log-file name instead
! 3560: of using the "<code>log file</code>" setting in the config file.</p>
! 3561: </dd>
! 3562:
! 3563: <dt><code>--log-file-format=FORMAT</code></dt><dd>
! 3564: <p>This option tells the rsync daemon to use the given FORMAT string instead
! 3565: of using the "<code>log format</code>" setting in the config file. It also enables
! 3566: "<code>transfer logging</code>" unless the string is empty, in which case transfer
! 3567: logging is turned off.</p>
! 3568: </dd>
! 3569:
! 3570: <dt><code>--sockopts</code></dt><dd>
! 3571: <p>This overrides the <code>socket options</code> setting in the rsyncd.conf file and has
! 3572: the same syntax.</p>
! 3573: </dd>
! 3574:
! 3575: <dt><code>--verbose</code>, <code>-v</code></dt><dd>
! 3576: <p>This option increases the amount of information the daemon logs during its
! 3577: startup phase. After the client connects, the daemon's verbosity level
! 3578: will be controlled by the options that the client used and the
! 3579: "<code>max verbosity</code>" setting in the module's config section.</p>
! 3580: </dd>
! 3581:
! 3582: <dt><code>--ipv4</code>, <code>-4</code> or <code>--ipv6</code>, <code>-6</code></dt><dd>
! 3583: <p>Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the
! 3584: rsync daemon will use to listen for connections. One of these options may
! 3585: be required in older versions of Linux to work around an IPv6 bug in the
! 3586: kernel (if you see an "address already in use" error when nothing else is
! 3587: using the port, try specifying <code>--ipv6</code> or <code>--ipv4</code> when starting the
! 3588: daemon).</p>
! 3589: <p>These options also exist in the regular rsync options section.</p>
! 3590: <p>If rsync was complied without support for IPv6, the <code>--ipv6</code> option will
! 3591: have no effect. The <code>rsync --version</code> output will contain "<code>no IPv6</code>" if
! 3592: is the case.</p>
! 3593: </dd>
! 3594:
! 3595: <dt><code>--help</code>, <code>-h</code></dt><dd>
! 3596: <p>When specified after <code>--daemon</code>, print a short help page describing the
! 3597: options available for starting an rsync daemon.</p>
! 3598: </dd>
! 3599: </dl>
! 3600: <h1>FILTER RULES</h1>
! 3601: <p>The filter rules allow for flexible selection of which files to transfer
! 3602: (include) and which files to skip (exclude). The rules either directly specify
! 3603: include/exclude patterns or they specify a way to acquire more include/exclude
! 3604: patterns (e.g. to read them from a file).</p>
! 3605: <p>As the list of files/directories to transfer is built, rsync checks each name
! 3606: to be transferred against the list of include/exclude patterns in turn, and the
! 3607: first matching pattern is acted on: if it is an exclude pattern, then that file
! 3608: is skipped; if it is an include pattern then that filename is not skipped; if
! 3609: no matching pattern is found, then the filename is not skipped.</p>
! 3610: <p>Rsync builds an ordered list of filter rules as specified on the command-line.
! 3611: Filter rules have the following syntax:</p>
! 3612: <blockquote>
! 3613: <pre><code>RULE [PATTERN_OR_FILENAME]
! 3614: RULE,MODIFIERS [PATTERN_OR_FILENAME]
! 3615: </code></pre>
! 3616: </blockquote>
! 3617: <p>You have your choice of using either short or long RULE names, as described
! 3618: below. If you use a short-named rule, the ',' separating the RULE from the
! 3619: MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
! 3620: must come after either a single space or an underscore (_). Here are the
! 3621: available rule prefixes:</p>
! 3622: <dl>
! 3623: <dt><code>exclude, '-'</code></dt><dd> specifies an exclude pattern.</dd>
! 3624: <dt><code>include, '+'</code></dt><dd> specifies an include pattern.</dd>
! 3625: <dt><code>merge, '.'</code></dt><dd> specifies a merge-file to read for more rules.</dd>
! 3626: <dt><code>dir-merge, ':'</code></dt><dd> specifies a per-directory merge-file.</dd>
! 3627: <dt><code>hide, 'H'</code></dt><dd> specifies a pattern for hiding files from the transfer.</dd>
! 3628: <dt><code>show, 'S'</code></dt><dd> files that match the pattern are not hidden.</dd>
! 3629: <dt><code>protect, 'P'</code></dt><dd> specifies a pattern for protecting files from deletion.</dd>
! 3630: <dt><code>risk, 'R'</code></dt><dd> files that match the pattern are not protected.</dd>
! 3631: <dt><code>clear, '!'</code></dt><dd> clears the current include/exclude list (takes no arg)</dd>
! 3632: </dl>
! 3633: <p>When rules are being read from a file, empty lines are ignored, as are comment
! 3634: lines that start with a "#".</p>
! 3635: <p>Note that the <code>--include</code> & <code>--exclude</code> command-line options do not allow the
! 3636: full range of rule parsing as described above -⁠-⁠ they only allow the
! 3637: specification of include / exclude patterns plus a "<code>!</code>" token to clear the
! 3638: list (and the normal comment parsing when rules are read from a file). If a
! 3639: pattern does not begin with "<code>- </code>" (dash, space) or "<code>+ </code>" (plus, space), then
! 3640: the rule will be interpreted as if "<code>+ </code>" (for an include option) or "<code>- </code>"
! 3641: (for an exclude option) were prefixed to the string. A <code>--filter</code> option, on
! 3642: the other hand, must always contain either a short or long rule name at the
! 3643: start of the rule.</p>
! 3644: <p>Note also that the <code>--filter</code>, <code>--include</code>, and <code>--exclude</code> options take one
! 3645: rule/pattern each. To add multiple ones, you can repeat the options on the
! 3646: command-line, use the merge-file syntax of the <code>--filter</code> option, or the
! 3647: <code>--include-from</code> / <code>--exclude-from</code> options.</p>
! 3648: <h1>INCLUDE/EXCLUDE PATTERN RULES</h1>
! 3649: <p>You can include and exclude files by specifying patterns using the "+", "-⁠",
! 3650: etc. filter rules (as introduced in the FILTER RULES section above). The
! 3651: include/exclude rules each specify a pattern that is matched against the names
! 3652: of the files that are going to be transferred. These patterns can take several
! 3653: forms:</p>
! 3654: <ul>
! 3655: <li>if the pattern starts with a <code>/</code> then it is anchored to a particular spot in
! 3656: the hierarchy of files, otherwise it is matched against the end of the
! 3657: pathname. This is similar to a leading <code>^</code> in regular expressions. Thus
! 3658: <code>/foo</code> would match a name of "foo" at either the "root of the transfer" (for
! 3659: a global rule) or in the merge-file's directory (for a per-directory rule).
! 3660: An unqualified <code>foo</code> would match a name of "foo" anywhere in the tree because
! 3661: the algorithm is applied recursively from the top down; it behaves as if each
! 3662: path component gets a turn at being the end of the filename. Even the
! 3663: unanchored "sub/foo" would match at any point in the hierarchy where a "foo"
! 3664: was found within a directory named "sub". See the section on ANCHORING
! 3665: INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify a pattern
! 3666: that matches at the root of the transfer.</li>
! 3667: <li>if the pattern ends with a <code>/</code> then it will only match a directory, not a
! 3668: regular file, symlink, or device.</li>
! 3669: <li>rsync chooses between doing a simple string match and wildcard matching by
! 3670: checking if the pattern contains one of these three wildcard characters:
! 3671: '<code>*</code>', '<code>?</code>', and '<code>[</code>' .</li>
! 3672: <li>a '<code>*</code>' matches any path component, but it stops at slashes.</li>
! 3673: <li>use '<code>**</code>' to match anything, including slashes.</li>
! 3674: <li>a '<code>?</code>' matches any character except a slash (<code>/</code>).</li>
! 3675: <li>a '<code>[</code>' introduces a character class, such as <code>[a-z]</code> or <code>[[:alpha:]]</code>.</li>
! 3676: <li>in a wildcard pattern, a backslash can be used to escape a wildcard
! 3677: character, but it is matched literally when no wildcards are present. This
! 3678: means that there is an extra level of backslash removal when a pattern
! 3679: contains wildcard characters compared to a pattern that has none. e.g. if
! 3680: you add a wildcard to "<code>foo\bar</code>" (which matches the backslash) you would
! 3681: need to use "<code>foo\\bar*</code>" to avoid the "<code>\b</code>" becoming just "b".</li>
! 3682: <li>if the pattern contains a <code>/</code> (not counting a trailing /) or a "<code>**</code>", then it
! 3683: is matched against the full pathname, including any leading directories. If
! 3684: the pattern doesn't contain a <code>/</code> or a "<code>**</code>", then it is matched only against
! 3685: the final component of the filename. (Remember that the algorithm is applied
! 3686: recursively so "full filename" can actually be any portion of a path from the
! 3687: starting directory on down.)</li>
! 3688: <li>a trailing "<code>dir_name/***</code>" will match both the directory (as if "dir_name/"
! 3689: had been specified) and everything in the directory (as if "<code>dir_name/**</code>"
! 3690: had been specified). This behavior was added in version 2.6.7.</li>
! 3691: </ul>
! 3692: <p>Note that, when using the <code>--recursive</code> (<code>-r</code>) option (which is implied by
! 3693: <code>-a</code>), every subdir component of every path is visited left to right, with each
! 3694: directory having a chance for exclusion before its content. In this way
! 3695: include/exclude patterns are applied recursively to the pathname of each node
! 3696: in the filesystem's tree (those inside the transfer). The exclude patterns
! 3697: short-circuit the directory traversal stage as rsync finds the files to send.</p>
! 3698: <p>For instance, to include "<code>/foo/bar/baz</code>", the directories "<code>/foo</code>" and "<code>/foo/bar</code>"
! 3699: must not be excluded. Excluding one of those parent directories prevents the
! 3700: examination of its content, cutting off rsync's recursion into those paths and
! 3701: rendering the include for "<code>/foo/bar/baz</code>" ineffectual (since rsync can't match
! 3702: something it never sees in the cut-off section of the directory hierarchy).</p>
! 3703: <p>The concept path exclusion is particularly important when using a trailing '<code>*</code>'
! 3704: rule. For instance, this won't work:</p>
! 3705: <blockquote>
! 3706: <pre><code>+ /some/path/this-file-will-not-be-found
! 3707: + /file-is-included
! 3708: - *
! 3709: </code></pre>
! 3710: </blockquote>
! 3711: <p>This fails because the parent directory "some" is excluded by the '<code>*</code>' rule, so
! 3712: rsync never visits any of the files in the "some" or "some/path" directories.
! 3713: One solution is to ask for all directories in the hierarchy to be included by
! 3714: using a single rule: "<code>+ */</code>" (put it somewhere before the "<code>- *</code>" rule), and
! 3715: perhaps use the <code>--prune-empty-dirs</code> option. Another solution is to add
! 3716: specific include rules for all the parent dirs that need to be visited. For
! 3717: instance, this set of rules works fine:</p>
! 3718: <blockquote>
! 3719: <pre><code>+ /some/
! 3720: + /some/path/
! 3721: + /some/path/this-file-is-found
! 3722: + /file-also-included
! 3723: - *
! 3724: </code></pre>
! 3725: </blockquote>
! 3726: <p>Here are some examples of exclude/include matching:</p>
! 3727: <ul>
! 3728: <li>"<code>- *.o</code>" would exclude all names matching <code>*.o</code></li>
! 3729: <li>"<code>- /foo</code>" would exclude a file (or directory) named foo in the transfer-root
! 3730: directory</li>
! 3731: <li>"<code>- foo/</code>" would exclude any directory named foo</li>
! 3732: <li>"<code>- /foo/*/bar</code>" would exclude any file named bar which is at two levels
! 3733: below a directory named foo in the transfer-root directory</li>
! 3734: <li>"<code>- /foo/**/bar</code>" would exclude any file named bar two or more levels below a
! 3735: directory named foo in the transfer-root directory</li>
! 3736: <li>The combination of "<code>+ */</code>", "<code>+ *.c</code>", and "<code>- *</code>" would include all
! 3737: directories and C source files but nothing else (see also the
! 3738: <code>--prune-empty-dirs</code> option)</li>
! 3739: <li>The combination of "<code>+ foo/</code>", "<code>+ foo/bar.c</code>", and "<code>- *</code>" would include
! 3740: only the foo directory and foo/bar.c (the foo directory must be explicitly
! 3741: included or it would be excluded by the "<code>*</code>")</li>
! 3742: </ul>
! 3743: <p>The following modifiers are accepted after a "<code>+</code>" or "<code>-</code>":</p>
! 3744: <ul>
! 3745: <li>A <code>/</code> specifies that the include/exclude rule should be matched against the
! 3746: absolute pathname of the current item. For example, "<code>-/ /etc/passwd</code>" would
! 3747: exclude the passwd file any time the transfer was sending files from the
! 3748: "/etc" directory, and "-⁠/ subdir/foo" would always exclude "foo" when it is
! 3749: in a dir named "subdir", even if "foo" is at the root of the current
! 3750: transfer.</li>
! 3751: <li>A <code>!</code> specifies that the include/exclude should take effect if the pattern
! 3752: fails to match. For instance, "<code>-! */</code>" would exclude all non-directories.</li>
! 3753: <li>A <code>C</code> is used to indicate that all the global CVS-exclude rules should be
! 3754: inserted as excludes in place of the "-⁠C". No arg should follow.</li>
! 3755: <li>An <code>s</code> is used to indicate that the rule applies to the sending side. When a
! 3756: rule affects the sending side, it prevents files from being transferred. The
! 3757: default is for a rule to affect both sides unless <code>--delete-excluded</code> was
! 3758: specified, in which case default rules become sender-side only. See also the
! 3759: hide (H) and show (S) rules, which are an alternate way to specify
! 3760: sending-side includes/excludes.</li>
! 3761: <li>An <code>r</code> is used to indicate that the rule applies to the receiving side. When
! 3762: a rule affects the receiving side, it prevents files from being deleted. See
! 3763: the <code>s</code> modifier for more info. See also the protect (P) and risk (R) rules,
! 3764: which are an alternate way to specify receiver-side includes/excludes.</li>
! 3765: <li>A <code>p</code> indicates that a rule is perishable, meaning that it is ignored in
! 3766: directories that are being deleted. For instance, the <code>-C</code> option's default
! 3767: rules that exclude things like "CVS" and "<code>*.o</code>" are marked as perishable,
! 3768: and will not prevent a directory that was removed on the source from being
! 3769: deleted on the destination.</li>
! 3770: <li>An <code>m(CHMOD)</code> on an include rule tweaks the permissions of matching
! 3771: source files in the same way as <code>--chmod</code>. This happens before any tweaks
! 3772: requested via <code>--chmod</code> options.</li>
! 3773: <li>An <code>o(USER)</code> on an include rule pretends that matching source files are
! 3774: owned by <code>USER</code> (a name or numeric uid). This happens before any uid mapping
! 3775: by name or <code>--usermap</code>.</li>
! 3776: <li>A <code>g(GROUP)</code> on an include rule pretends that matching source files are
! 3777: owned by <code>GROUP</code> (a name or numeric gid). This happens before any gid
! 3778: mapping by name or <code>--groupmap</code>.</li>
! 3779: <li>An <code>x</code> indicates that a rule affects xattr names in xattr copy/delete
! 3780: operations (and is thus ignored when matching file/dir names). If no
! 3781: xattr-matching rules are specified, a default xattr filtering rule is used
! 3782: (see the <code>--xattrs</code> option).</li>
! 3783: </ul>
! 3784: <h1>MERGE-FILE FILTER RULES</h1>
! 3785: <p>You can merge whole files into your filter rules by specifying either a merge
! 3786: (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES section
! 3787: above).</p>
! 3788: <p>There are two kinds of merged files -⁠-⁠ single-instance ('.') and per-directory
! 3789: (':'). A single-instance merge file is read one time, and its rules are
! 3790: incorporated into the filter list in the place of the "." rule. For
! 3791: per-directory merge files, rsync will scan every directory that it traverses
! 3792: for the named file, merging its contents when the file exists into the current
! 3793: list of inherited rules. These per-directory rule files must be created on the
! 3794: sending side because it is the sending side that is being scanned for the
! 3795: available files to transfer. These rule files may also need to be transferred
! 3796: to the receiving side if you want them to affect what files don't get deleted
! 3797: (see PER-DIRECTORY RULES AND DELETE below).</p>
! 3798: <p>Some examples:</p>
! 3799: <blockquote>
! 3800: <pre><code>merge /etc/rsync/default.rules
! 3801: . /etc/rsync/default.rules
! 3802: dir-merge .per-dir-filter
! 3803: dir-merge,n- .non-inherited-per-dir-excludes
! 3804: :n- .non-inherited-per-dir-excludes
! 3805: </code></pre>
! 3806: </blockquote>
! 3807: <p>The following modifiers are accepted after a merge or dir-merge rule:</p>
! 3808: <ul>
! 3809: <li>A <code>-</code> specifies that the file should consist of only exclude patterns, with
! 3810: no other rule-parsing except for in-file comments.</li>
! 3811: <li>A <code>+</code> specifies that the file should consist of only include patterns, with
! 3812: no other rule-parsing except for in-file comments.</li>
! 3813: <li>A <code>C</code> is a way to specify that the file should be read in a CVS-compatible
! 3814: manner. This turns on 'n', 'w', and '-⁠', but also allows the list-clearing
! 3815: token (!) to be specified. If no filename is provided, ".cvsignore" is
! 3816: assumed.</li>
! 3817: <li>A <code>e</code> will exclude the merge-file name from the transfer; e.g. "dir-merge,e
! 3818: .rules" is like "dir-merge .rules" and "-⁠ .rules".</li>
! 3819: <li>An <code>n</code> specifies that the rules are not inherited by subdirectories.</li>
! 3820: <li>A <code>w</code> specifies that the rules are word-split on whitespace instead of the
! 3821: normal line-splitting. This also turns off comments. Note: the space that
! 3822: separates the prefix from the rule is treated specially, so "-⁠ foo + bar" is
! 3823: parsed as two rules (assuming that prefix-parsing wasn't also disabled).</li>
! 3824: <li>You may also specify any of the modifiers for the "+" or "-⁠" rules (above) in
! 3825: order to have the rules that are read in from the file default to having that
! 3826: modifier set (except for the <code>!</code> modifier, which would not be useful). For
! 3827: instance, "merge,-⁠/ .excl" would treat the contents of .excl as absolute-path
! 3828: excludes, while "dir-merge,s .filt" and ":sC" would each make all their
! 3829: per-directory rules apply only on the sending side. If the merge rule
! 3830: specifies sides to affect (via the <code>s</code> or <code>r</code> modifier or both), then the
! 3831: rules in the file must not specify sides (via a modifier or a rule prefix
! 3832: such as <code>hide</code>).</li>
! 3833: </ul>
! 3834: <p>The attribute-affecting modifiers <code>m</code>, <code>o</code>, and <code>g</code> work only in client filters
! 3835: (not in daemon filters), and only the modifiers of the first matching rule are
! 3836: applied. As an example, assuming <code>--super</code> is enabled, the rule
! 3837: "<code>+o(root),g(root),m(go=) *~</code>" would ensure that all "backup"
! 3838: files belong to root and are not accessible to anyone else.</p>
! 3839: <p>Per-directory rules are inherited in all subdirectories of the directory where
! 3840: the merge-file was found unless the 'n' modifier was used. Each subdirectory's
! 3841: rules are prefixed to the inherited per-directory rules from its parents, which
! 3842: gives the newest rules a higher priority than the inherited rules. The entire
! 3843: set of dir-merge rules are grouped together in the spot where the merge-file
! 3844: was specified, so it is possible to override dir-merge rules via a rule that
! 3845: got specified earlier in the list of global rules. When the list-clearing rule
! 3846: ("!") is read from a per-directory file, it only clears the inherited rules for
! 3847: the current merge file.</p>
! 3848: <p>Another way to prevent a single rule from a dir-merge file from being inherited
! 3849: is to anchor it with a leading slash. Anchored rules in a per-directory
! 3850: merge-file are relative to the merge-file's directory, so a pattern "/foo"
! 3851: would only match the file "foo" in the directory where the dir-merge filter
! 3852: file was found.</p>
! 3853: <p>Here's an example filter file which you'd specify via <code>--filter=". file":</code></p>
! 3854: <blockquote>
! 3855: <pre><code>merge /home/user/.global-filter
! 3856: - *.gz
! 3857: dir-merge .rules
! 3858: + *.[ch]
! 3859: - *.o
! 3860: - foo*
! 3861: </code></pre>
! 3862: </blockquote>
! 3863: <p>This will merge the contents of the /home/user/.global-filter file at the start
! 3864: of the list and also turns the ".rules" filename into a per-directory filter
! 3865: file. All rules read in prior to the start of the directory scan follow the
! 3866: global anchoring rules (i.e. a leading slash matches at the root of the
! 3867: transfer).</p>
! 3868: <p>If a per-directory merge-file is specified with a path that is a parent
! 3869: directory of the first transfer directory, rsync will scan all the parent dirs
! 3870: from that starting point to the transfer directory for the indicated
! 3871: per-directory file. For instance, here is a common filter (see <code>-F</code>):</p>
! 3872: <blockquote>
! 3873: <pre><code>--filter=': /.rsync-filter'
! 3874: </code></pre>
! 3875: </blockquote>
! 3876: <p>That rule tells rsync to scan for the file .rsync-filter in all directories
! 3877: from the root down through the parent directory of the transfer prior to the
! 3878: start of the normal directory scan of the file in the directories that are sent
! 3879: as a part of the transfer. (Note: for an rsync daemon, the root is always the
! 3880: same as the module's "path".)</p>
! 3881: <p>Some examples of this pre-scanning for per-directory files:</p>
! 3882: <blockquote>
! 3883: <pre><code>rsync -avF /src/path/ /dest/dir
! 3884: rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
! 3885: rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir
! 3886: </code></pre>
! 3887: </blockquote>
! 3888: <p>The first two commands above will look for ".rsync-filter" in "/" and "/src"
! 3889: before the normal scan begins looking for the file in "/src/path" and its
! 3890: subdirectories. The last command avoids the parent-dir scan and only looks for
! 3891: the ".rsync-filter" files in each directory that is a part of the transfer.</p>
! 3892: <p>If you want to include the contents of a ".cvsignore" in your patterns, you
! 3893: should use the rule ":C", which creates a dir-merge of the .cvsignore file, but
! 3894: parsed in a CVS-compatible manner. You can use this to affect where the
! 3895: <code>--cvs-exclude</code> (<code>-C</code>) option's inclusion of the per-directory .cvsignore file
! 3896: gets placed into your rules by putting the ":C" wherever you like in your
! 3897: filter rules. Without this, rsync would add the dir-merge rule for the
! 3898: .cvsignore file at the end of all your other rules (giving it a lower priority
! 3899: than your command-line rules). For example:</p>
! 3900: <blockquote>
! 3901: <pre><code>cat <<EOT | rsync -avC --filter='. -' a/ b
! 3902: + foo.o
! 3903: :C
! 3904: - *.old
! 3905: EOT
! 3906: rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
! 3907: </code></pre>
! 3908: </blockquote>
! 3909: <p>Both of the above rsync commands are identical. Each one will merge all the
! 3910: per-directory .cvsignore rules in the middle of the list rather than at the
! 3911: end. This allows their dir-specific rules to supersede the rules that follow
! 3912: the :C instead of being subservient to all your rules. To affect the other CVS
! 3913: exclude rules (i.e. the default list of exclusions, the contents of
! 3914: $HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the <code>-C</code>
! 3915: command-line option and instead insert a "-⁠C" rule into your filter rules; e.g.
! 3916: "<code>--filter=-C</code>".</p>
! 3917: <h1>LIST-CLEARING FILTER RULE</h1>
! 3918: <p>You can clear the current include/exclude list by using the "!" filter rule (as
! 3919: introduced in the FILTER RULES section above). The "current" list is either
! 3920: the global list of rules (if the rule is encountered while parsing the filter
! 3921: options) or a set of per-directory rules (which are inherited in their own
! 3922: sub-list, so a subdirectory can use this to clear out the parent's rules).</p>
! 3923: <h1>ANCHORING INCLUDE/EXCLUDE PATTERNS</h1>
! 3924: <p>As mentioned earlier, global include/exclude patterns are anchored at the "root
! 3925: of the transfer" (as opposed to per-directory patterns, which are anchored at
! 3926: the merge-file's directory). If you think of the transfer as a subtree of
! 3927: names that are being sent from sender to receiver, the transfer-root is where
! 3928: the tree starts to be duplicated in the destination directory. This root
! 3929: governs where patterns that start with a / match.</p>
! 3930: <p>Because the matching is relative to the transfer-root, changing the trailing
! 3931: slash on a source path or changing your use of the <code>--relative</code> option affects
! 3932: the path you need to use in your matching (in addition to changing how much of
! 3933: the file tree is duplicated on the destination host). The following examples
! 3934: demonstrate this.</p>
! 3935: <p>Let's say that we want to match two source files, one with an absolute
! 3936: path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
! 3937: Here is how the various command choices differ for a 2-source transfer:</p>
! 3938: <blockquote>
! 3939: <pre><code>Example cmd: rsync -a /home/me /home/you /dest
! 3940: +/- pattern: /me/foo/bar
! 3941: +/- pattern: /you/bar/baz
! 3942: Target file: /dest/me/foo/bar
! 3943: Target file: /dest/you/bar/baz
! 3944: </code></pre>
! 3945: </blockquote>
! 3946: <blockquote>
! 3947: <pre><code>Example cmd: rsync -a /home/me/ /home/you/ /dest
! 3948: +/- pattern: /foo/bar (note missing "me")
! 3949: +/- pattern: /bar/baz (note missing "you")
! 3950: Target file: /dest/foo/bar
! 3951: Target file: /dest/bar/baz
! 3952: </code></pre>
! 3953: </blockquote>
! 3954: <blockquote>
! 3955: <pre><code>Example cmd: rsync -a --relative /home/me/ /home/you /dest
! 3956: +/- pattern: /home/me/foo/bar (note full path)
! 3957: +/- pattern: /home/you/bar/baz (ditto)
! 3958: Target file: /dest/home/me/foo/bar
! 3959: Target file: /dest/home/you/bar/baz
! 3960: </code></pre>
! 3961: </blockquote>
! 3962: <blockquote>
! 3963: <pre><code>Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
! 3964: +/- pattern: /me/foo/bar (starts at specified path)
! 3965: +/- pattern: /you/bar/baz (ditto)
! 3966: Target file: /dest/me/foo/bar
! 3967: Target file: /dest/you/bar/baz
! 3968: </code></pre>
! 3969: </blockquote>
! 3970: <p>The easiest way to see what name you should filter is to just
! 3971: look at the output when using <code>--verbose</code> and put a / in front of the name
! 3972: (use the <code>--dry-run</code> option if you're not yet ready to copy any files).</p>
! 3973: <h1>PER-DIRECTORY RULES AND DELETE</h1>
! 3974: <p>Without a delete option, per-directory rules are only relevant on the sending
! 3975: side, so you can feel free to exclude the merge files themselves without
! 3976: affecting the transfer. To make this easy, the 'e' modifier adds this exclude
! 3977: for you, as seen in these two equivalent commands:</p>
! 3978: <blockquote>
! 3979: <pre><code>rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
! 3980: rsync -av --filter=':e .excl' host:src/dir /dest
! 3981: </code></pre>
! 3982: </blockquote>
! 3983: <p>However, if you want to do a delete on the receiving side AND you want some
! 3984: files to be excluded from being deleted, you'll need to be sure that the
! 3985: receiving side knows what files to exclude. The easiest way is to include the
! 3986: per-directory merge files in the transfer and use <code>--delete-after</code>, because
! 3987: this ensures that the receiving side gets all the same exclude rules as the
! 3988: sending side before it tries to delete anything:</p>
! 3989: <blockquote>
! 3990: <pre><code>rsync -avF --delete-after host:src/dir /dest
! 3991: </code></pre>
! 3992: </blockquote>
! 3993: <p>However, if the merge files are not a part of the transfer, you'll need to
! 3994: either specify some global exclude rules (i.e. specified on the command line),
! 3995: or you'll need to maintain your own per-directory merge files on the receiving
! 3996: side. An example of the first is this (assume that the remote .rules files
! 3997: exclude themselves):</p>
! 3998: <blockquote>
! 3999: <pre><code>rsync -av --filter=': .rules' --filter='. /my/extra.rules'
! 4000: --delete host:src/dir /dest
! 4001: </code></pre>
! 4002: </blockquote>
! 4003: <p>In the above example the extra.rules file can affect both sides of the
! 4004: transfer, but (on the sending side) the rules are subservient to the rules
! 4005: merged from the .rules files because they were specified after the
! 4006: per-directory merge rule.</p>
! 4007: <p>In one final example, the remote side is excluding the .rsync-filter files from
! 4008: the transfer, but we want to use our own .rsync-filter files to control what
! 4009: gets deleted on the receiving side. To do this we must specifically exclude
! 4010: the per-directory merge files (so that they don't get deleted) and then put
! 4011: rules into the local files to control what else should not get deleted. Like
! 4012: one of these commands:</p>
! 4013: <blockquote>
! 4014: <pre><code>rsync -av --filter=':e /.rsync-filter' --delete \
! 4015: host:src/dir /dest
! 4016: rsync -avFF --delete host:src/dir /dest
! 4017: </code></pre>
! 4018: </blockquote>
! 4019: <h1>BATCH MODE</h1>
! 4020: <p>Batch mode can be used to apply the same set of updates to many identical
! 4021: systems. Suppose one has a tree which is replicated on a number of hosts. Now
! 4022: suppose some changes have been made to this source tree and those changes need
! 4023: to be propagated to the other hosts. In order to do this using batch mode,
! 4024: rsync is run with the write-batch option to apply the changes made to the
! 4025: source tree to one of the destination trees. The write-batch option causes the
! 4026: rsync client to store in a "batch file" all the information needed to repeat
! 4027: this operation against other, identical destination trees.</p>
! 4028: <p>Generating the batch file once saves having to perform the file status,
! 4029: checksum, and data block generation more than once when updating multiple
! 4030: destination trees. Multicast transport protocols can be used to transfer the
! 4031: batch update files in parallel to many hosts at once, instead of sending the
! 4032: same data to every host individually.</p>
! 4033: <p>To apply the recorded changes to another destination tree, run rsync with the
! 4034: read-batch option, specifying the name of the same batch file, and the
! 4035: destination tree. Rsync updates the destination tree using the information
! 4036: stored in the batch file.</p>
! 4037: <p>For your convenience, a script file is also created when the write-batch option
! 4038: is used: it will be named the same as the batch file with ".sh" appended. This
! 4039: script file contains a command-line suitable for updating a destination tree
! 4040: using the associated batch file. It can be executed using a Bourne (or
! 4041: Bourne-like) shell, optionally passing in an alternate destination tree
! 4042: pathname which is then used instead of the original destination path. This is
! 4043: useful when the destination tree path on the current host differs from the one
! 4044: used to create the batch file.</p>
! 4045: <p>Examples:</p>
! 4046: <blockquote>
! 4047: <pre><code>$ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
! 4048: $ scp foo* remote:
! 4049: $ ssh remote ./foo.sh /bdest/dir/
! 4050: </code></pre>
! 4051: </blockquote>
! 4052: <blockquote>
! 4053: <pre><code>$ rsync --write-batch=foo -a /source/dir/ /adest/dir/
! 4054: $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
! 4055: </code></pre>
! 4056: </blockquote>
! 4057: <p>In these examples, rsync is used to update /adest/dir/ from /source/dir/ and
! 4058: the information to repeat this operation is stored in "foo" and "foo.sh". The
! 4059: host "remote" is then updated with the batched data going into the directory
! 4060: /bdest/dir. The differences between the two examples reveals some of the
! 4061: flexibility you have in how you deal with batches:</p>
! 4062: <ul>
! 4063: <li>The first example shows that the initial copy doesn't have to be local -⁠-⁠ you
! 4064: can push or pull data to/from a remote host using either the remote-shell
! 4065: syntax or rsync daemon syntax, as desired.</li>
! 4066: <li>The first example uses the created "foo.sh" file to get the right rsync
! 4067: options when running the read-batch command on the remote host.</li>
! 4068: <li>The second example reads the batch data via standard input so that the batch
! 4069: file doesn't need to be copied to the remote machine first. This example
! 4070: avoids the foo.sh script because it needed to use a modified <code>--read-batch</code>
! 4071: option, but you could edit the script file if you wished to make use of it
! 4072: (just be sure that no other option is trying to use standard input, such as
! 4073: the "<code>--exclude-from=-</code>" option).</li>
! 4074: </ul>
! 4075: <p>Caveats:</p>
! 4076: <p>The read-batch option expects the destination tree that it is updating to be
! 4077: identical to the destination tree that was used to create the batch update
! 4078: fileset. When a difference between the destination trees is encountered the
! 4079: update might be discarded with a warning (if the file appears to be up-to-date
! 4080: already) or the file-update may be attempted and then, if the file fails to
! 4081: verify, the update discarded with an error. This means that it should be safe
! 4082: to re-run a read-batch operation if the command got interrupted. If you wish
! 4083: to force the batched-update to always be attempted regardless of the file's
! 4084: size and date, use the <code>-I</code> option (when reading the batch). If an error
! 4085: occurs, the destination tree will probably be in a partially updated state. In
! 4086: that case, rsync can be used in its regular (non-batch) mode of operation to
! 4087: fix up the destination tree.</p>
! 4088: <p>The rsync version used on all destinations must be at least as new as the one
! 4089: used to generate the batch file. Rsync will die with an error if the protocol
! 4090: version in the batch file is too new for the batch-reading rsync to handle.
! 4091: See also the <code>--protocol</code> option for a way to have the creating rsync generate
! 4092: a batch file that an older rsync can understand. (Note that batch files
! 4093: changed format in version 2.6.3, so mixing versions older than that with newer
! 4094: versions will not work.)</p>
! 4095: <p>When reading a batch file, rsync will force the value of certain options to
! 4096: match the data in the batch file if you didn't set them to the same as the
! 4097: batch-writing command. Other options can (and should) be changed. For
! 4098: instance <code>--write-batch</code> changes to <code>--read-batch</code>, <code>--files-from</code> is dropped,
! 4099: and the <code>--filter</code> / <code>--include</code> / <code>--exclude</code> options are not needed unless
! 4100: one of the <code>--delete</code> options is specified.</p>
! 4101: <p>The code that creates the BATCH.sh file transforms any filter/include/exclude
! 4102: options into a single list that is appended as a "here" document to the shell
! 4103: script file. An advanced user can use this to modify the exclude list if a
! 4104: change in what gets deleted by <code>--delete</code> is desired. A normal user can ignore
! 4105: this detail and just use the shell script as an easy way to run the appropriate
! 4106: <code>--read-batch</code> command for the batched data.</p>
! 4107: <p>The original batch mode in rsync was based on "rsync+", but the latest
! 4108: version uses a new implementation.</p>
! 4109: <h1>SYMBOLIC LINKS</h1>
! 4110: <p>Three basic behaviors are possible when rsync encounters a symbolic
! 4111: link in the source directory.</p>
! 4112: <p>By default, symbolic links are not transferred at all. A message "skipping
! 4113: non-regular" file is emitted for any symlinks that exist.</p>
! 4114: <p>If <code>--links</code> is specified, then symlinks are recreated with the same target on
! 4115: the destination. Note that <code>--archive</code> implies <code>--links</code>.</p>
! 4116: <p>If <code>--copy-links</code> is specified, then symlinks are "collapsed" by
! 4117: copying their referent, rather than the symlink.</p>
! 4118: <p>Rsync can also distinguish "safe" and "unsafe" symbolic links. An example
! 4119: where this might be used is a web site mirror that wishes to ensure that the
! 4120: rsync module that is copied does not include symbolic links to <code>/etc/passwd</code> in
! 4121: the public section of the site. Using <code>--copy-unsafe-links</code> will cause any
! 4122: links to be copied as the file they point to on the destination. Using
! 4123: <code>--safe-links</code> will cause unsafe links to be omitted altogether. (Note that you
! 4124: must specify <code>--links</code> for <code>--safe-links</code> to have any effect.)</p>
! 4125: <p>Symbolic links are considered unsafe if they are absolute symlinks
! 4126: (start with <code>/</code>), empty, or if they contain enough ".."
! 4127: components to ascend from the directory being copied.</p>
! 4128: <p>Here's a summary of how the symlink options are interpreted. The list is in
! 4129: order of precedence, so if your combination of options isn't mentioned, use the
! 4130: first line that is a complete subset of your options:</p>
! 4131: <dl>
! 4132: <dt><code>--copy-links</code></dt><dd> Turn all symlinks into normal files (leaving no symlinks for
! 4133: any other options to affect).</dd>
! 4134: <dt><code>--links --copy-unsafe-links</code></dt><dd> Turn all unsafe symlinks into files and
! 4135: duplicate all safe symlinks.</dd>
! 4136: <dt><code>--copy-unsafe-links</code></dt><dd> Turn all unsafe symlinks into files, noisily skip all
! 4137: safe symlinks.</dd>
! 4138: <dt><code>--links --safe-links</code></dt><dd> Duplicate safe symlinks and skip unsafe ones.</dd>
! 4139: <dt><code>--links</code></dt><dd> Duplicate all symlinks.</dd>
! 4140: </dl>
! 4141: <h1>DIAGNOSTICS</h1>
! 4142: <p>rsync occasionally produces error messages that may seem a little cryptic. The
! 4143: one that seems to cause the most confusion is "protocol version mismatch -⁠-⁠ is
! 4144: your shell clean?".</p>
! 4145: <p>This message is usually caused by your startup scripts or remote shell facility
! 4146: producing unwanted garbage on the stream that rsync is using for its transport.
! 4147: The way to diagnose this problem is to run your remote shell like this:</p>
! 4148: <blockquote>
! 4149: <pre><code>ssh remotehost /bin/true > out.dat
! 4150: </code></pre>
! 4151: </blockquote>
! 4152: <p>then look at out.dat. If everything is working correctly then out.dat should
! 4153: be a zero length file. If you are getting the above error from rsync then you
! 4154: will probably find that out.dat contains some text or data. Look at the
! 4155: contents and try to work out what is producing it. The most common cause is
! 4156: incorrectly configured shell startup scripts (such as .cshrc or .profile) that
! 4157: contain output statements for non-interactive logins.</p>
! 4158: <p>If you are having trouble debugging filter patterns, then try specifying the
! 4159: <code>-vv</code> option. At this level of verbosity rsync will show why each individual
! 4160: file is included or excluded.</p>
! 4161: <h1>EXIT VALUES</h1>
! 4162: <dl>
! 4163: <dt><strong>0</strong></dt><dd> Success</dd>
! 4164: <dt><strong>1</strong></dt><dd> Syntax or usage error</dd>
! 4165: <dt><strong>2</strong></dt><dd> Protocol incompatibility</dd>
! 4166: <dt><strong>3</strong></dt><dd> Errors selecting input/output files, dirs</dd>
! 4167: <dt><strong>4</strong></dt><dd> Requested action not supported: an attempt was made to manipulate
! 4168: 64-bit files on a platform that cannot support them; or an option was
! 4169: specified that is supported by the client and not by the server.</dd>
! 4170: <dt><strong>5</strong></dt><dd> Error starting client-server protocol</dd>
! 4171: <dt><strong>6</strong></dt><dd> Daemon unable to append to log-file</dd>
! 4172: <dt><strong>10</strong></dt><dd> Error in socket I/O</dd>
! 4173: <dt><strong>11</strong></dt><dd> Error in file I/O</dd>
! 4174: <dt><strong>12</strong></dt><dd> Error in rsync protocol data stream</dd>
! 4175: <dt><strong>13</strong></dt><dd> Errors with program diagnostics</dd>
! 4176: <dt><strong>14</strong></dt><dd> Error in IPC code</dd>
! 4177: <dt><strong>20</strong></dt><dd> Received SIGUSR1 or SIGINT</dd>
! 4178: <dt><strong>21</strong></dt><dd> Some error returned by <strong>waitpid()</strong></dd>
! 4179: <dt><strong>22</strong></dt><dd> Error allocating core memory buffers</dd>
! 4180: <dt><strong>23</strong></dt><dd> Partial transfer due to error</dd>
! 4181: <dt><strong>24</strong></dt><dd> Partial transfer due to vanished source files</dd>
! 4182: <dt><strong>25</strong></dt><dd> The -⁠-⁠max-delete limit stopped deletions</dd>
! 4183: <dt><strong>30</strong></dt><dd> Timeout in data send/receive</dd>
! 4184: <dt><strong>35</strong></dt><dd> Timeout waiting for daemon connection</dd>
! 4185: </dl>
! 4186: <h1>ENVIRONMENT VARIABLES</h1>
! 4187: <dl>
! 4188:
! 4189: <dt><code>CVSIGNORE</code></dt><dd>
! 4190: <p>The CVSIGNORE environment variable supplements any ignore patterns in
! 4191: .cvsignore files. See the <code>--cvs-exclude</code> option for more details.</p>
! 4192: </dd>
! 4193:
! 4194: <dt><code>RSYNC_ICONV</code></dt><dd>
! 4195: <p>Specify a default <code>--iconv</code> setting using this environment variable. (First
! 4196: supported in 3.0.0.)</p>
! 4197: </dd>
! 4198:
! 4199: <dt><code>RSYNC_PROTECT_ARGS</code></dt><dd>
! 4200: <p>Specify a non-zero numeric value if you want the <code>--protect-args</code> option to
! 4201: be enabled by default, or a zero value to make sure that it is disabled by
! 4202: default. (First supported in 3.1.0.)</p>
! 4203: </dd>
! 4204:
! 4205: <dt><code>RSYNC_RSH</code></dt><dd>
! 4206: <p>The RSYNC_RSH environment variable allows you to override the default shell
! 4207: used as the transport for rsync. Command line options are permitted after
! 4208: the command name, just as in the <code>-e</code> option.</p>
! 4209: </dd>
! 4210:
! 4211: <dt><code>RSYNC_PROXY</code></dt><dd>
! 4212: <p>The RSYNC_PROXY environment variable allows you to redirect your rsync
! 4213: client to use a web proxy when connecting to a rsync daemon. You should
! 4214: set RSYNC_PROXY to a hostname:port pair.</p>
! 4215: </dd>
! 4216:
! 4217: <dt><code>RSYNC_PASSWORD</code></dt><dd>
! 4218: <p>Setting RSYNC_PASSWORD to the required password allows you to run
! 4219: authenticated rsync connections to an rsync daemon without user
! 4220: intervention. Note that this does not supply a password to a remote shell
! 4221: transport such as ssh; to learn how to do that, consult the remote shell's
! 4222: documentation.</p>
! 4223: </dd>
! 4224:
! 4225: <dt><code>USER</code> or <code>LOGNAME</code></dt><dd>
! 4226: <p>The USER or LOGNAME environment variables are used to determine the default
! 4227: username sent to an rsync daemon. If neither is set, the username defaults
! 4228: to "nobody".</p>
! 4229: </dd>
! 4230:
! 4231: <dt><code>HOME</code></dt><dd>
! 4232: <p>The HOME environment variable is used to find the user's default .cvsignore
! 4233: file.</p>
! 4234: </dd>
! 4235: </dl>
! 4236: <h1>FILES</h1>
! 4237: <p>/etc/rsyncd.conf or rsyncd.conf</p>
! 4238: <h1>SEE ALSO</h1>
! 4239: <p><strong>rsync-ssl</strong>(1), <strong>rsyncd.conf</strong>(5)</p>
! 4240: <h1>BUGS</h1>
! 4241: <p>times are transferred as *nix time_t values</p>
! 4242: <p>When transferring to FAT filesystems rsync may re-sync
! 4243: unmodified files.
! 4244: See the comments on the <code>--modify-window</code> option.</p>
! 4245: <p>file permissions, devices, etc. are transferred as native numerical
! 4246: values</p>
! 4247: <p>see also the comments on the <code>--delete</code> option</p>
! 4248: <p>Please report bugs! See the web site at <a href="https://rsync.samba.org/">https://rsync.samba.org/</a>.</p>
! 4249: <h1>VERSION</h1>
! 4250: <p>This man page is current for version 3.2.3 of rsync.</p>
! 4251: <h1>INTERNAL OPTIONS</h1>
! 4252: <p>The options <code>--server</code> and <code>--sender</code> are used internally by rsync, and should
! 4253: never be typed by a user under normal circumstances. Some awareness of these
! 4254: options may be needed in certain scenarios, such as when setting up a login
! 4255: that can only run an rsync command. For instance, the support directory of the
! 4256: rsync distribution has an example script named rrsync (for restricted rsync)
! 4257: that can be used with a restricted ssh login.</p>
! 4258: <h1>CREDITS</h1>
! 4259: <p>rsync is distributed under the GNU General Public License. See the file
! 4260: COPYING for details.</p>
! 4261: <p>A web site is available at <a href="https://rsync.samba.org/">https://rsync.samba.org/</a>. The site includes an
! 4262: FAQ-O-Matic which may cover questions unanswered by this manual page.</p>
! 4263: <p>We would be delighted to hear from you if you like this program. Please
! 4264: contact the mailing-list at <a href="mailto:rsync@lists.samba.org">rsync@lists.samba.org</a>.</p>
! 4265: <p>This program uses the excellent zlib compression library written by Jean-loup
! 4266: Gailly and Mark Adler.</p>
! 4267: <h1>THANKS</h1>
! 4268: <p>Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra,
! 4269: David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
! 4270: gone-but-not-forgotten compadre, J.W. Schultz.</p>
! 4271: <p>Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and
! 4272: David Bell. I've probably missed some people, my apologies if I have.</p>
! 4273: <h1>AUTHOR</h1>
! 4274: <p>rsync was originally written by Andrew Tridgell and Paul Mackerras. Many
! 4275: people have later contributed to it. It is currently maintained by Wayne
! 4276: Davison.</p>
! 4277: <p>Mailing lists for support and development are available at
! 4278: <a href="https://lists.samba.org/">https://lists.samba.org/</a>.</p>
! 4279: <div style="float: right"><p><i>06 Aug 2020</i></p></div>
! 4280: </body></html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rsync.1.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync