File:  [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / rsync.yo
Revision 1.1.1.3 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Nov 1 09:54:32 2016 UTC (7 years, 7 months ago) by misho
Branches: rsync, MAIN
CVS tags: v3_1_2p5, HEAD
rsync 3.1.2

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>