Return to rsync.1 CVS log

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

rsync 3.2.3

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