Return to rsync.1.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync

rsync 3.2.3

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