to this latter rule).
As a special case, if a single source arg is specified without a destination,
-the files are listed in an output format similar to "ls -l".
+the files are listed in an output format similar to "`ls -l`".
As expected, if neither the source or destination path specify a remote host,
the copy occurs locally (see also the `--list-only` option).
-Rsync refers to the local side as the "client" and the remote side as the
-"server". Don't confuse "server" with an rsync daemon -- a daemon is always a
-server, but a server can be either a daemon or a remote-shell spawned process.
+Rsync refers to the local side as the client and the remote side as the server.
+Don't confuse server with an rsync daemon. A daemon is always a server, but a
+server can be either a daemon or a remote-shell spawned process.
# SETUP
directory to the directory src on the machine foo. If any of the files already
exist on the remote system then the rsync remote-update protocol is used to
update the file by sending only the differences in the data. Note that the
-expansion of wildcards on the commandline (`*.c`) into a list of files is
+expansion of wildcards on the command-line (`*.c`) into a list of files is
handled by the shell before it runs rsync and not by rsync itself (exactly the
-same as all other posix-style programs).
+same as all other Posix-style programs).
> rsync -avz foo:src/bar /data/tmp
This would recursively transfer all files from the directory src/bar on the
machine foo into the /data/tmp/bar directory on the local machine. The files
-are transferred in "archive" mode, which ensures that symbolic links, devices,
+are transferred in archive mode, which ensures that symbolic links, devices,
attributes, permissions, ownerships, etc. are preserved in the transfer.
Additionally, compression will be used to reduce the size of data portions of
the transfer.
This is launched from cron every few hours.
-# OPTIONS SUMMARY
+# OPTION SUMMARY
Here is a short summary of the options available in rsync. Please refer to the
detailed description below for a complete description.
+[comment]: # (help-rsync.h)
+[comment]: # (Keep these short enough that they'll be under 80 chars when indented by 7 chars.)
+
```
---verbose, -v increase verbosity
---info=FLAGS fine-grained informational verbosity
---debug=FLAGS fine-grained debug verbosity
---msgs2stderr output messages directly to stderr
---quiet, -q suppress non-error messages
---no-motd suppress daemon-mode MOTD (see caveat)
---checksum, -c skip based on checksum, not mod-time & size
---archive, -a archive mode; equals -rlptgoD (no -H,-A,-X)
---no-OPTION turn off an implied OPTION (e.g. --no-D)
---recursive, -r recurse into directories
---relative, -R use relative path names
---no-implied-dirs don't send implied dirs with --relative
---backup, -b make backups (see --suffix & --backup-dir)
---backup-dir=DIR make backups into hierarchy based in DIR
---suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
---update, -u skip files that are newer on the receiver
---inplace update destination files in-place
---append append data onto shorter files
---append-verify --append w/old data in file checksum
---dirs, -d transfer directories without recursing
---links, -l copy symlinks as symlinks
---copy-links, -L transform symlink into referent file/dir
---copy-unsafe-links only "unsafe" symlinks are transformed
---safe-links ignore symlinks that point outside the tree
---munge-links munge symlinks to make them safer
---copy-dirlinks, -k transform symlink to dir into referent dir
---keep-dirlinks, -K treat symlinked dir on receiver as dir
---hard-links, -H preserve hard links
---perms, -p preserve permissions
---executability, -E preserve executability
---chmod=CHMOD affect file and/or directory permissions
---acls, -A preserve ACLs (implies -p)
---xattrs, -X preserve extended attributes
---owner, -o preserve owner (super-user only)
---group, -g preserve group
---devices preserve device files (super-user only)
---specials preserve special files
--D same as --devices --specials
---times, -t preserve modification times
---atimes, -U preserve access (use) times
---open-noatime avoid changing the atime on opened files
---omit-dir-times, -O omit directories from --times
---omit-link-times, -J omit symlinks from --times
---super receiver attempts super-user activities
---fake-super store/recover privileged attrs using xattrs
---sparse, -S turn sequences of nulls into sparse blocks
---preallocate allocate dest files before writing
---write-devices write to devices as files (implies --inplace)
---dry-run, -n perform a trial run with no changes made
---whole-file, -W copy files whole (w/o delta-xfer algorithm)
---checksum-choice=STR choose the checksum algorithms
---one-file-system, -x don't cross filesystem boundaries
---block-size=SIZE, -B force a fixed checksum block-size
---rsh=COMMAND, -e specify the remote shell to use
---rsync-path=PROGRAM specify the rsync to run on remote machine
---existing skip creating new files on receiver
---ignore-existing skip updating files that exist on receiver
---remove-source-files sender removes synchronized files (non-dir)
---del an alias for --delete-during
---delete delete extraneous files from dest dirs
---delete-before receiver deletes before xfer, not during
---delete-during receiver deletes during the transfer
---delete-delay find deletions during, delete after
---delete-after receiver deletes after transfer, not during
---delete-excluded also delete excluded files from dest dirs
---ignore-missing-args ignore missing source args without error
---delete-missing-args delete missing source args from destination
---ignore-errors delete even if there are I/O errors
---force force deletion of dirs even if not empty
---max-delete=NUM don't delete more than NUM files
---max-size=SIZE don't transfer any file larger than SIZE
---min-size=SIZE don't transfer any file smaller than SIZE
---partial keep partially transferred files
---partial-dir=DIR put a partially transferred file into DIR
---delay-updates put all updated files into place at end
---prune-empty-dirs, -m prune empty directory chains from file-list
---numeric-ids don't map uid/gid values by user/group name
---usermap=STRING custom username mapping
---groupmap=STRING custom groupname mapping
---chown=USER:GROUP simple username/groupname mapping
---timeout=SECONDS set I/O timeout in seconds
---contimeout=SECONDS set daemon connection timeout in seconds
---ignore-times, -I don't skip files that match size and time
---size-only skip files that match in size
---modify-window=NUM, -@ set the accuracy for mod-time comparisons
---temp-dir=DIR, -T create temporary files in directory DIR
---fuzzy, -y find similar file for basis if no dest file
---compare-dest=DIR also compare received files relative to DIR
---copy-dest=DIR ... and include copies of unchanged files
---link-dest=DIR hardlink to files in DIR when unchanged
---compress, -z compress file data during the transfer
---compress-level=NUM explicitly set compression level
---skip-compress=LIST skip compressing files with suffix in LIST
---cvs-exclude, -C auto-ignore files in the same way CVS does
---filter=RULE, -f add a file-filtering RULE
--F same as --filter='dir-merge /.rsync-filter'
- repeated: --filter='- .rsync-filter'
---exclude=PATTERN exclude files matching PATTERN
---exclude-from=FILE read exclude patterns from FILE
---include=PATTERN don't exclude files matching PATTERN
---include-from=FILE read include patterns from FILE
---files-from=FILE read list of source-file names from FILE
---from0, -0 all *from/filter files are delimited by 0s
---protect-args, -s no space-splitting; wildcard chars only
---copy-as=USER[:GROUP] specify user & optional group for the copy
---address=ADDRESS bind address for outgoing socket to daemon
---port=PORT specify double-colon alternate port number
---sockopts=OPTIONS specify custom TCP options
---blocking-io use blocking I/O for the remote shell
---outbuf=N|L|B set out buffering to None, Line, or Block
---stats give some file-transfer stats
---8-bit-output, -8 leave high-bit chars unescaped in output
---human-readable, -h output numbers in a human-readable format
---progress show progress during transfer
--P same as --partial --progress
---itemize-changes, -i output a change-summary for all updates
---remote-option=OPTION, -M send OPTION to the remote side only
---out-format=FORMAT output updates using the specified FORMAT
---log-file=FILE log what we're doing to the specified FILE
---log-file-format=FMT log updates using the specified FMT
---password-file=FILE read daemon-access password from FILE
---list-only list the files instead of copying them
---bwlimit=RATE limit socket I/O bandwidth
---write-batch=FILE write a batched update to FILE
---only-write-batch=FILE like --write-batch but w/o updating dest
---read-batch=FILE read a batched update from FILE
---protocol=NUM force an older protocol version to be used
---iconv=CONVERT_SPEC request charset conversion of filenames
---checksum-seed=NUM set block/file checksum seed (advanced)
---ipv4, -4 prefer IPv4
---ipv6, -6 prefer IPv6
---version, -V print the version + other info and exit
---help, -h (*) show this help (*see below for -h comment)
+--verbose, -v increase verbosity
+--info=FLAGS fine-grained informational verbosity
+--debug=FLAGS fine-grained debug verbosity
+--stderr=e|a|c change stderr output mode (default: errors)
+--quiet, -q suppress non-error messages
+--no-motd suppress daemon-mode MOTD
+--checksum, -c skip based on checksum, not mod-time & size
+--archive, -a archive mode is -rlptgoD (no -A,-X,-U,-N,-H)
+--no-OPTION turn off an implied OPTION (e.g. --no-D)
+--recursive, -r recurse into directories
+--relative, -R use relative path names
+--no-implied-dirs don't send implied dirs with --relative
+--backup, -b make backups (see --suffix & --backup-dir)
+--backup-dir=DIR make backups into hierarchy based in DIR
+--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
+--update, -u skip files that are newer on the receiver
+--inplace update destination files in-place
+--append append data onto shorter files
+--append-verify --append w/old data in file checksum
+--dirs, -d transfer directories without recursing
+--mkpath create the destination's path component
+--links, -l copy symlinks as symlinks
+--copy-links, -L transform symlink into referent file/dir
+--copy-unsafe-links only "unsafe" symlinks are transformed
+--safe-links ignore symlinks that point outside the tree
+--munge-links munge symlinks to make them safe & unusable
+--copy-dirlinks, -k transform symlink to dir into referent dir
+--keep-dirlinks, -K treat symlinked dir on receiver as dir
+--hard-links, -H preserve hard links
+--perms, -p preserve permissions
+--executability, -E preserve executability
+--chmod=CHMOD affect file and/or directory permissions
+--acls, -A preserve ACLs (implies --perms)
+--xattrs, -X preserve extended attributes
+--owner, -o preserve owner (super-user only)
+--group, -g preserve group
+--devices preserve device files (super-user only)
+--specials preserve special files
+-D same as --devices --specials
+--times, -t preserve modification times
+--atimes, -U preserve access (use) times
+--open-noatime avoid changing the atime on opened files
+--crtimes, -N preserve create times (newness)
+--omit-dir-times, -O omit directories from --times
+--omit-link-times, -J omit symlinks from --times
+--super receiver attempts super-user activities
+--fake-super store/recover privileged attrs using xattrs
+--sparse, -S turn sequences of nulls into sparse blocks
+--preallocate allocate dest files before writing them
+--write-devices write to devices as files (implies --inplace)
+--dry-run, -n perform a trial run with no changes made
+--whole-file, -W copy files whole (w/o delta-xfer algorithm)
+--checksum-choice=STR choose the checksum algorithm (aka --cc)
+--one-file-system, -x don't cross filesystem boundaries
+--block-size=SIZE, -B force a fixed checksum block-size
+--rsh=COMMAND, -e specify the remote shell to use
+--rsync-path=PROGRAM specify the rsync to run on remote machine
+--existing skip creating new files on receiver
+--ignore-existing skip updating files that exist on receiver
+--remove-source-files sender removes synchronized files (non-dir)
+--del an alias for --delete-during
+--delete delete extraneous files from dest dirs
+--delete-before receiver deletes before xfer, not during
+--delete-during receiver deletes during the transfer
+--delete-delay find deletions during, delete after
+--delete-after receiver deletes after transfer, not during
+--delete-excluded also delete excluded files from dest dirs
+--ignore-missing-args ignore missing source args without error
+--delete-missing-args delete missing source args from destination
+--ignore-errors delete even if there are I/O errors
+--force force deletion of dirs even if not empty
+--max-delete=NUM don't delete more than NUM files
+--max-size=SIZE don't transfer any file larger than SIZE
+--min-size=SIZE don't transfer any file smaller than SIZE
+--max-alloc=SIZE change a limit relating to memory alloc
+--partial keep partially transferred files
+--partial-dir=DIR put a partially transferred file into DIR
+--delay-updates put all updated files into place at end
+--prune-empty-dirs, -m prune empty directory chains from file-list
+--numeric-ids don't map uid/gid values by user/group name
+--usermap=STRING custom username mapping
+--groupmap=STRING custom groupname mapping
+--chown=USER:GROUP simple username/groupname mapping
+--timeout=SECONDS set I/O timeout in seconds
+--contimeout=SECONDS set daemon connection timeout in seconds
+--ignore-times, -I don't skip files that match size and time
+--size-only skip files that match in size
+--modify-window=NUM, -@ set the accuracy for mod-time comparisons
+--temp-dir=DIR, -T create temporary files in directory DIR
+--fuzzy, -y find similar file for basis if no dest file
+--compare-dest=DIR also compare destination files relative to DIR
+--copy-dest=DIR ... and include copies of unchanged files
+--link-dest=DIR hardlink to files in DIR when unchanged
+--compress, -z compress file data during the transfer
+--compress-choice=STR choose the compression algorithm (aka --zc)
+--compress-level=NUM explicitly set compression level (aka --zl)
+--skip-compress=LIST skip compressing files with suffix in LIST
+--cvs-exclude, -C auto-ignore files in the same way CVS does
+--filter=RULE, -f add a file-filtering RULE
+-F same as --filter='dir-merge /.rsync-filter'
+ repeated: --filter='- .rsync-filter'
+--exclude=PATTERN exclude files matching PATTERN
+--exclude-from=FILE read exclude patterns from FILE
+--include=PATTERN don't exclude files matching PATTERN
+--include-from=FILE read include patterns from FILE
+--files-from=FILE read list of source-file names from FILE
+--from0, -0 all *-from/filter files are delimited by 0s
+--protect-args, -s no space-splitting; wildcard chars only
+--copy-as=USER[:GROUP] specify user & optional group for the copy
+--address=ADDRESS bind address for outgoing socket to daemon
+--port=PORT specify double-colon alternate port number
+--sockopts=OPTIONS specify custom TCP options
+--blocking-io use blocking I/O for the remote shell
+--outbuf=N|L|B set out buffering to None, Line, or Block
+--stats give some file-transfer stats
+--8-bit-output, -8 leave high-bit chars unescaped in output
+--human-readable, -h output numbers in a human-readable format
+--progress show progress during transfer
+-P same as --partial --progress
+--itemize-changes, -i output a change-summary for all updates
+--remote-option=OPT, -M send OPTION to the remote side only
+--out-format=FORMAT output updates using the specified FORMAT
+--log-file=FILE log what we're doing to the specified FILE
+--log-file-format=FMT log updates using the specified FMT
+--password-file=FILE read daemon-access password from FILE
+--early-input=FILE use FILE for daemon's early exec input
+--list-only list the files instead of copying them
+--bwlimit=RATE limit socket I/O bandwidth
+--stop-after=MINS Stop rsync after MINS minutes have elapsed
+--stop-at=y-m-dTh:m Stop rsync at the specified point in time
+--fsync fsync every written file
+--write-batch=FILE write a batched update to FILE
+--only-write-batch=FILE like --write-batch but w/o updating dest
+--read-batch=FILE read a batched update from FILE
+--protocol=NUM force an older protocol version to be used
+--iconv=CONVERT_SPEC request charset conversion of filenames
+--checksum-seed=NUM set block/file checksum seed (advanced)
+--ipv4, -4 prefer IPv4
+--ipv6, -6 prefer IPv6
+--version, -V print the version + other info and exit
+--help, -h (*) show this help (* -h is help only on its own)
```
Rsync can also be run as a daemon, in which case the following options are
accepted:
+[comment]: # (help-rsyncd.h)
+
```
---daemon run as an rsync daemon
---address=ADDRESS bind to the specified address
---bwlimit=RATE limit socket I/O bandwidth
---config=FILE specify alternate rsyncd.conf file
---dparam=OVERRIDE, -M override global daemon config parameter
---no-detach do not detach from the parent
---port=PORT listen on alternate port number
---log-file=FILE override the "log file" setting
---log-file-format=FMT override the "log format" setting
---sockopts=OPTIONS specify custom TCP options
---verbose, -v increase verbosity
---ipv4, -4 prefer IPv4
---ipv6, -6 prefer IPv6
---help, -h show this help (if used after --daemon)
+--daemon run as an rsync daemon
+--address=ADDRESS bind to the specified address
+--bwlimit=RATE limit socket I/O bandwidth
+--config=FILE specify alternate rsyncd.conf file
+--dparam=OVERRIDE, -M override global daemon config parameter
+--no-detach do not detach from the parent
+--port=PORT listen on alternate port number
+--log-file=FILE override the "log file" setting
+--log-file-format=FMT override the "log format" setting
+--sockopts=OPTIONS specify custom TCP options
+--verbose, -v increase verbosity
+--ipv4, -4 prefer IPv4
+--ipv6, -6 prefer IPv6
+--help, -h show this help (when used with --daemon)
```
# OPTIONS
must also be specified for the short. When specifying a parameter, you can
either use the form `--option=param` or replace the '=' with whitespace. The
parameter may need to be quoted in some manner for it to survive the shell's
-command-line parsing. Keep in mind that a leading tilde (\~) in a filename is
+command-line parsing. Keep in mind that a leading tilde (`~`) in a filename is
substituted by your shell, so `--option=~/foo` will not change the tilde into
your home directory (remove the '=' for that).
0. `--help`, `-h` `(*)`
Print a short help page describing the options available in rsync and exit.
- For backward-compatibility with older versions of rsync, the help will also
- be output if you use the `-h` option without any other args.
+ (*) The `-h` short option will only invoke `--help` when used without other
+ options since it normally means `--human-readable`.
0. `--version`, `-V`
and `--debug` have a way to ask for help that tells you exactly what flags
are set for each increase in verbosity.
- However, do keep in mind that a daemon's "max verbosity" setting will limit
+ However, do keep in mind that a daemon's "`max verbosity`" setting will limit
how high of a level the various individual flags can be set on the daemon
side. For instance, if the max is 2, then any info and/or debug flag that
is set to a higher value than what would be set by `-vv` will be downgraded
This option was added to 3.1.0, so an older rsync on the server side might
reject your attempts at fine-grained control (if one or more flags needed
to be send to the server and the server was too old to understand them).
- See also the "max verbosity" caveat above when dealing with a daemon.
+ See also the "`max verbosity`" caveat above when dealing with a daemon.
0. `--debug=FLAGS`
> rsync -avvv --debug=none src/ dest/
> rsync -avA --del --debug=del2,acl src/ dest/
- Note that some debug messages will only be output when `--msgs2stderr` is
+ Note that some debug messages will only be output when `--stderr=all` is
specified, especially those pertaining to I/O and buffer debugging.
- Beginning in 3.2.0, this option is no longer auto-forwared to the server
+ Beginning in 3.2.0, this option is no longer auto-forwarded to the server
side in order to allow you to specify different debug values for each side
of the transfer, as well as to specify a new debug option that is only
present in one of the rsync versions. If you want to duplicate the same
> rsync -aiv {-M,}--debug=del2 src/ dest/
-0. `--msgs2stderr`
-
- This option changes rsync to send all its output directly to stderr rather
- than to send messages to the client side via the protocol. The protocol
- allows rsync to output normal messages via stdout and errors via stderr,
- but it can delay messages behind a slew of data.
-
- One case where this is helpful is when sending really large files, since
- errors that happen on a remote receiver tend to get delayed until afer the
- file's data is fully sent. It is also helpful for debugging, since it helps
- to avoid overpopulating the protocol data with extra message data.
-
- The option does not affect the remote side of a transfer without using
- `--remote-option` -- e.g. `-M--msgs2stderr` or `{-M,}--msgs2stderr`.
-
- Also keep in mind that connecting to a normal (non-remote-shell) daemon
- does not have a stderr channel to send messages back to the client side, so
- a modern rsync only allows the option on a remote-shell-run daemon.
-
- This option has the side-effect of making stderr output get line-buffered
- so that the merging of the output of 3 programs happens in a more readable
- manner.
+0. `--stderr=errors|all|client`
+
+ This option controls which processes output to stderr and if info messages
+ are also changed to stderr. The mode strings can be abbreviated, so feel
+ free to use a single letter value. The 3 possible choices are:
+
+ - `errors` - (the default) causes all the rsync processes to send an
+ error directly to stderr, even if the process is on the remote side of
+ the transfer. Info messages are sent to the client side via the protocol
+ stream. If stderr is not available (i.e. when directly connecting with a
+ daemon via a socket) errors fall back to being sent via the protocol
+ stream.
+
+ - `all` - causes all rsync messages (info and error) to get written
+ directly to stderr from all (possible) processes. This causes stderr to
+ become line-buffered (instead of raw) and eliminates the ability to
+ divide up the info and error messages by file handle. For those doing
+ debugging or using several levels of verbosity, this option can help to
+ avoid clogging up the transfer stream (which should prevent any chance of
+ a deadlock bug hanging things up). It also allows `--debug` to enable
+ some extra I/O related messages.
+
+ - `client` - causes all rsync messages to be sent to the client side
+ via the protocol stream. One client process outputs all messages, with
+ errors on stderr and info messages on stdout. This **was** the default
+ in older rsync versions, but can cause error delays when a lot of
+ transfer data is ahead of the messages. If you're pushing files to an
+ older rsync, you may want to use `--stderr=all` since that idiom has
+ been around for several releases.
+
+ This option was added in rsync 3.2.3. This version also began the
+ forwarding of a non-default setting to the remote side, though rsync uses
+ the backward-compatible options `--msgs2stderr` and `--no-msgs2stderr` to
+ represent the `all` and `client` settings, respectively. A newer rsync
+ will continue to accept these older option names to maintain compatibility.
0. `--quiet`, `-q`
the same modification timestamp. This option turns off this "quick check"
behavior, causing all files to be updated.
+ This option can be a little confusing compared to `--ignore-existing` and
+ `--ignore-non-existing` in that that they cause rsync to transfer fewer
+ files, while this option causes rsync to transfer more files.
+
0. `--size-only`
This modifies rsync's "quick check" algorithm for finding files that need
after using another mirroring system which may not preserve timestamps
exactly.
-0. `--modify-window`, `-@`
+0. `--modify-window=NUM`, `-@`
When comparing two timestamps, rsync treats the timestamps as being equal
if they differ by no more than the modify-window value. The default is 0,
before-the-transfer "Does this file need to be updated?" check.
The checksum used is auto-negotiated between the client and the server, but
- can be overridden using either the `--checksum-choice` option or an
+ can be overridden using either the `--checksum-choice` (`--cc`) option or an
environment variable that is discussed in that option's section.
0. `--archive`, `-a`
This is equivalent to `-rlptgoD`. It is a quick way of saying you want
- recursion and want to preserve almost everything (with `-H` being a notable
- omission). The only exception to the above equivalence is when
- `--files-from` is specified, in which case `-r` is not implied.
+ recursion and want to preserve almost everything. Be aware that it does
+ **not** include preserving ACLs (`-A`), xattrs (`-X`), atimes (`-U`),
+ crtimes (`-N`), nor the finding and preserving of hardlinks (`-H`).
- Note that `-a` **does not preserve hardlinks**, because finding
- multiply-linked files is expensive. You must separately specify `-H`.
+ The only exception to the above equivalence is when
+ `--files-from` is specified, in which case `-r` is not implied.
0. `--no-OPTION`
0. `--backup-dir=DIR`
- In combination with the `--backup` option, this tells rsync to store all
+ This implies the `--backup` option, and tells rsync to store all
backups in the specified directory on the receiving side. This can be used
for incremental backups. You can additionally specify a backup suffix
using the `--suffix` option (otherwise the files backed up in the specified
0. `--append`
- This causes rsync to update a file by appending data onto the end of the
- file, which presumes that the data that already exists on the receiving
- side is identical with the start of the file on the sending side. If a
- file needs to be transferred and its size on the receiver is the same or
- longer than the size on the sender, the file is skipped. This does not
- interfere with the updating of a file's non-content attributes (e.g.
- permissions, ownership, etc.) when the file does not need to be
- transferred, nor does it affect the updating of any non-regular files.
- Implies `--inplace`.
-
- The use of `--append` can be dangerous if you aren't 100% sure that the
- files that are longer have only grown by the appending of data onto the
- end. You should thus use include/exclude/filter rules to ensure that such
- a transfer is only affecting files that you know to be growing via appended
- data.
+ This special copy mode only works to efficiently update files that are
+ known to be growing larger where any existing content on the receiving side
+ is also known to be the same as the content on the sender. The use of
+ `--append` **can be dangerous** if you aren't 100% sure that all the files
+ in the transfer are shared, growing files. You should thus use filter
+ rules to ensure that you weed out any files that do not fit this criteria.
+
+ Rsync updates these growing file in-place without verifying any of the
+ existing content in the file (it only verifies the content that it is
+ appending). Rsync skips any files that exist on the receiving side that
+ are not shorter than the associated file on the sending side (which means
+ that new files are transferred). It also skips any files whose size on the
+ sending side gets shorter during the send negotiations (rsync warns about a
+ "diminished" file when this happens).
+
+ This does not interfere with the updating of a file's non-content
+ attributes (e.g. permissions, ownership, etc.) when the file does not need
+ to be transferred, nor does it affect the updating of any directories or
+ non-regular files.
0. `--append-verify`
- This works just like the `--append` option, but the existing data on the
- receiving side is included in the full-file checksum verification step,
- which will cause a file to be resent if the final verification step fails
- (rsync uses a normal, non-appending `--inplace` transfer for the resend).
- It otherwise has the exact same caveats for files that have not grown
- larger, so don't use this for a general copy.
+ This special copy mode works like `--append` except that all the data in
+ the file is included in the checksum verification (making it much less
+ efficient but also potentially safer). This option **can be dangerous** if
+ you aren't 100% sure that all the files in the transfer are shared, growing
+ files. See the `--append` option for more details.
Note: prior to rsync 3.0.0, the `--append` option worked like
`--append-verify`, so if you are interacting with an older rsync (or the
`--old-d`) that tells rsync to use a hack of `-r --exclude='/*/*'` to get
an older rsync to list a single directory without recursing.
+0. `--mkpath`
+
+ Create a missing path component of the destination arg. This allows rsync
+ to create multiple levels of missing destination dirs and to create a path
+ in which to put a single renamed file. Keep in mind that you'll need to
+ supply a trailing slash if you want the entire destination path to be
+ treated as a directory when copying a single arg (making rsync behave the
+ same way that it would if the path component of the destination had already
+ existed).
+
+ For example, the following creates a copy of file foo as bar in the sub/dir
+ directory, creating dirs "sub" and "sub/dir" if either do not yet exist:
+
+ > rsync -ai --mkpath foo sub/dir/bar
+
+ If you instead ran the following, it would have created file foo in the
+ sub/dir/bar directory:
+
+ > rsync -ai --mkpath foo sub/dir/bar/
+
0. `--links`, `-l`
When symlinks are encountered, recreate the symlink on the destination.
local transfer, the client side is the sender.)
This option has no affect on a daemon, since the daemon configures whether
- it wants munged symlinks via its "munge symlinks" parameter. See also the
+ it wants munged symlinks via its "`munge symlinks`" parameter. See also the
"munge-symlinks" perl script in the support directory of the source code.
0. `--copy-dirlinks`, `-k`
those used by `--fake-super`) unless you repeat the option (e.g. `-XX`).
This "copy all xattrs" mode cannot be used with `--fake-super`.
-0. `--chmod`
+0. `--chmod=CHMOD`
This option tells rsync to apply one or more comma-separated "chmod" modes
to the permission of the files in the transfer. The resulting value is
mounted to avoid updating the atime on read access even without the
O_NOATIME flag being set.
+0. `--crtimes`, `-N,`
+
+ This tells rsync to set the create times (newness) of the destination
+ files to the same value as the source files.
+
0. `--omit-dir-times`, `-O`
- This tells rsync to omit directories when it is preserving modification
- times (see `--times`). If NFS is sharing the directories on the receiving
+ This tells rsync to omit directories when it is preserving modification,
+ access, and create times. If NFS is sharing the directories on the receiving
side, it is a good idea to use `-O`. This option is inferred if you use
`--backup` without `--backup-dir`.
0. `--omit-link-times`, `-J`
- This tells rsync to omit symlinks when it is preserving modification times
- (see `--times`).
+ This tells rsync to omit symlinks when it is preserving modification,
+ access, and create times.
0. `--super`
This tells the receiving side to attempt super-user activities even if the
receiving rsync wasn't run by the super-user. These activities include:
preserving users via the `--owner` option, preserving all groups (not just
- the current user's groups) via the `--groups` option, and copying devices
+ the current user's groups) via the `--group` option, and copying devices
via the `--devices` option. This is useful for systems that allow such
activities without being the super-user, and also for ensuring that you
will get errors if the receiving side isn't being run as the super-user.
This option is overridden by both `--super` and `--no-super`.
- See also the "fake super" setting in the daemon's rsyncd.conf file.
+ See also the "`fake super`" setting in the daemon's rsyncd.conf file.
0. `--sparse`, `-S`
comma-separated names are supplied, the first name affects the transfer
checksums, and the second name affects the pre-transfer checksums (`-c`).
- The algorithm choices are "auto", "xxh64" (aka "xxhash"), "MD5", "MD4", and
- "none".
+ The checksum options that you may be able to use are:
+
+ - `auto` (the default automatic choice)
+ - `xxh128`
+ - `xxh3`
+ - `xxh64` (aka `xxhash`)
+ - `md5`
+ - `md4`
+ - `none`
+
+ Run `rsync --version` to see the default checksum list compiled into your
+ version (which may differ from the list above).
If "none" is specified for the first (or only) name, the `--whole-file`
option is forced on and no checksum verification is performed on the
the `--checksum` option cannot be used.
The "auto" option is the default, where rsync bases its algorithm choice on
- a negotation between the client and the server as follows:
-
- If both the client and the server are at least version 3.2.0, they will
- exchange a list of checksum names and choose the first one in the list that
- they have in common. This typically means that they will choose xxh64 if
- they both support it and fall back to MD5. If one side of the transfer is
- not new enough to support this checksum negotation, then a value is chosen
- based on the protocol version (which chooses between MD5 and various
- flavors of MD4 based on protocol age).
-
- You can also override the checksum using the RSYNC_CHECKSUM_LIST
- environment variable by setting it to a space-separated list of checksum
- names that you consider acceptable. If no common checksum is found, the
- client exits with an error. This method does not allow you to specify the
- transfer checksum separately from the pre-transfer checksum, and it ignores
- "auto" and all unknown checksum names. If the remote rsync is not new
- enough to handle a checksum negotiation list, the list is silently ignored
- unless it contains the string "FAIL".
-
- Use "rsync -V" to see the default checksum list.
+ a negotiation between the client and the server as follows:
+
+ When both sides of the transfer are at least 3.2.0, rsync chooses the first
+ algorithm in the client's list of choices that is also in the server's list
+ of choices. If no common checksum choice is found, rsync exits with
+ an error. If the remote rsync is too old to support checksum negotiation,
+ a value is chosen based on the protocol version (which chooses between MD5
+ and various flavors of MD4 based on protocol age).
+
+ The default order can be customized by setting the environment variable
+ RSYNC_CHECKSUM_LIST to a space-separated list of acceptable checksum names.
+ If the string contains a "`&`" character, it is separated into the "client
+ string & server string", otherwise the same string
+ applies to both. If the string (or string portion) contains no
+ non-whitespace characters, the default checksum list is used. This method
+ does not allow you to specify the transfer checksum separately from the
+ pre-transfer checksum, and it discards "auto" and all unknown checksum
+ names. A list with only invalid names results in a failed negotiation.
The use of the `--checksum-choice` option overrides this environment list.
permissions on the hard-linked files). This does mean that this option is
only looking at the existing files in the destination hierarchy itself.
+ When `--info=skip2` is used rsync will output "FILENAME exists (INFO)"
+ messages where the INFO indicates one of "type change", "sum change"
+ (requires `-c`), "file change" (based on the quick check), "attr change",
+ or "uptodate". Using `--info=skip1` (which is also implied by `-vv`)
+ outputs the exists message without the INFO suffix.
+
0. `--remove-source-files`
This tells rsync to remove from the sending side the files (meaning
0. `--max-size=SIZE`
This tells rsync to avoid transferring any file that is larger than the
- specified SIZE. The SIZE value can be suffixed with a string to indicate a
- size multiplier, and may be a fractional value (e.g. `--max-size=1.5m`).
+ specified SIZE. A numeric value can be suffixed with a string to indicate
+ the numeric units or left unqualified to specify bytes. Feel free to use a
+ fractional value along with the units, such as `--max-size=1.5m`.
This option is a transfer rule, not an exclude, so it doesn't affect the
data that goes into the file-lists, and thus it doesn't affect deletions.
It just limits the files that the receiver requests to be transferred.
- The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024), "M" (or
- "MiB") is a mebibyte (1024\*1024), and "G" (or "GiB") is a gibibyte
- (1024\*1024\*1024). If you want the multiplier to be 1000 instead of 1024,
- use "KB", "MB", or "GB". (Note: lower-case is also accepted for all
- values.) Finally, if the suffix ends in either "+1" or "-1", the value will
- be offset by one byte in the indicated direction.
+ The first letter of a units string can be `B` (bytes), `K` (kilo), `M`
+ (mega), `G` (giga), `T` (tera), or `P` (peta). If the string is a single
+ char or has "ib" added to it (e.g. "G" or "GiB") then the units are
+ multiples of 1024. If you use a two-letter suffix that ends with a "B"
+ (e.g. "kb") then you get units that are multiples of 1000. The string's
+ letters can be any mix of upper and lower-case that you want to use.
+
+ Finally, if the string ends with either "+1" or "-1", it is offset by one
+ byte in the indicated direction. The largest possible value is usually
+ `8192P-1`.
Examples: `--max-size=1.5mb-1` is 1499999 bytes, and `--max-size=2g+1` is
2147483649 bytes.
Note that rsync versions prior to 3.1.0 did not allow `--min-size=0`.
-0. `--block-size=BLOCKSIZE`, `-B`
+0. `--max-alloc=SIZE`
+
+ By default rsync limits an individual malloc/realloc to about 1GB in size.
+ For most people this limit works just fine and prevents a protocol error
+ causing rsync to request massive amounts of memory. However, if you have
+ many millions of files in a transfer, a large amount of server memory, and
+ you don't want to split up your transfer into multiple parts, you can
+ increase the per-allocation limit to something larger and rsync will
+ consume more memory.
+
+ Keep in mind that this is not a limit on the total size of allocated
+ memory. It is a sanity-check value for each individual allocation.
+
+ See the `--max-size` option for a description of how SIZE can be specified.
+ The default suffix if none is given is bytes.
+
+ Beginning in 3.2.3, a value of 0 specifies no limit.
+
+ You can set a default value using the environment variable RSYNC_MAX_ALLOC
+ using the same SIZE values as supported by this option. If the remote
+ rsync doesn't understand the `--max-alloc` option, you can override an
+ environmental value by specifying `--max-alloc=1g`, which will make rsync
+ avoid sending the option to the remote side (because "1G" is the default).
+
+0. `--block-size=SIZE`, `-B`
This forces the block size used in rsync's delta-transfer algorithm to a
fixed value. It is normally selected based on the size of each file being
updated. See the technical report for details.
+ Beginning in 3.2.3 the SIZE can be specified with a suffix as detailed in
+ the `--max-size` option. Older versions only accepted a byte count.
+
0. `--rsh=COMMAND`, `-e`
This option allows you to choose an alternative remote shell program to use
The exclude list is initialized to exclude the following items (these
initial items are marked as perishable -- see the FILTER RULES section):
+ [comment]: # (This list gets used for the default-cvsignore.h file.)
+
> `RCS`
> `SCCS`
> `CVS`
0. `--exclude-from=FILE`
This option is related to the `--exclude` option, but it specifies a FILE
- that contains exclude patterns (one per line). Blank lines in the file and
- lines starting with '`;`' or '`#`' are ignored. If _FILE_ is '`-`', the
- list will be read from standard input.
+ that contains exclude patterns (one per line). Blank lines in the file are
+ ignored, as are whole-line comments that start with '`;`' or '`#`'
+ (filename rules that contain those characters are unaffected).
+
+ If _FILE_ is '`-`', the list will be read from standard input.
0. `--include=PATTERN`
0. `--include-from=FILE`
This option is related to the `--include` option, but it specifies a FILE
- that contains include patterns (one per line). Blank lines in the file and
- lines starting with '`;`' or '`#`' are ignored. If _FILE_ is '`-`', the
- list will be read from standard input.
+ that contains include patterns (one per line). Blank lines in the file are
+ ignored, as are whole-line comments that start with '`;`' or '`#`'
+ (filename rules that contain those characters are unaffected).
+
+ If _FILE_ is '`-`', the list will be read from standard input.
0. `--files-from=FILE`
Rsync can also be configured (at build time) to have this option enabled by
default (with is overridden by both the environment and the command-line).
+ Run `rsync --version` to check if this is the case, as it will display
+ "default protect-args" or "optional protect-args" depending on how it was
+ compiled.
+
This option will eventually become a new default setting at some
as-yet-undetermined point in the future.
has no permissions to change.
The following command does a local copy into the "dest/" dir as user "joe"
- (assumimg you've installed support/lsh into a dir on your $PATH):
+ (assuming you've installed support/lsh into a dir on your $PATH):
> sudo rsync -aive lsh -M--copy-as=joe src/ lh:dest/
> rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
- If file's aren't linking, double-check their attributes. Also check if
+ If files aren't linking, double-check their attributes. Also check if
some attributes are getting forced outside of rsync's control, such a mount
option that squishes root to a single user, or mounts a removable drive
with generic ownership (such as OS X's "Ignore ownership on this volume"
destination machine, which reduces the amount of data being transmitted --
something that is useful over a slow connection.
- The "zlib" compression method typically achieves better compression ratios
- than can be achieved by using a compressing remote shell or a compressing
- transport because it takes advantage of the implicit information in the
- matching data blocks that are not explicitly sent over the connection.
- This matching-data compression comes at a cost of CPU, though, and can be
- disabled by using the "zlibx" compresson method instead. This can be
- selected by repeating the `-z` option or specifying
- `--compress-choice=zlibx`, but it only works if both sides of the transfer
- are at least version 3.1.1.
+ Rsync supports multiple compression methods and will choose one for you
+ unless you force the choice using the `--compress-choice` (`--zc`) option.
+
+ Run `rsync --version` to see the default compress list compiled into your
+ version.
+
+ When both sides of the transfer are at least 3.2.0, rsync chooses the first
+ algorithm in the client's list of choices that is also in the server's list
+ of choices. If no common compress choice is found, rsync exits with
+ an error. If the remote rsync is too old to support checksum negotiation,
+ its list is assumed to be "zlib".
+
+ The default order can be customized by setting the environment variable
+ RSYNC_COMPRESS_LIST to a space-separated list of acceptable compression
+ names. If the string contains a "`&`" character, it is separated into the
+ "client string & server string", otherwise the same string applies to both.
+ If the string (or string portion) contains no
+ non-whitespace characters, the default compress list is used. Any unknown
+ compression names are discarded from the list, but a list with only invalid
+ names results in a failed negotiation.
+
+ There are some older rsync versions that were configured to reject a `-z`
+ option and require the use of `-zz` because their compression library was
+ not compatible with the default zlib compression method. You can usually
+ ignore this weirdness unless the rsync server complains and tells you to
+ specify `-zz`.
+
+ See also the `--skip-compress` option for the default list of file suffixes
+ that will be transferred with no (or minimal) compression.
+
+0. `--compress-choice=STR`, `--zc=STR`
+
+ This option can be used to override the automatic negotiation of the
+ compression algorithm that occurs when `--compress` is used. The option
+ implies `--compress` unless "none" was specified, which instead implies
+ `--no-compress`.
+
+ The compression options that you may be able to use are:
+
+ - `zstd`
+ - `lz4`
+ - `zlibx`
+ - `zlib`
+ - `none`
+
+ Run `rsync --version` to see the default compress list compiled into your
+ version (which may differ from the list above).
Note that if you see an error about an option named `--old-compress` or
`--new-compress`, this is rsync trying to send the `--compress-choice=zlib`
or `--compress-choice=zlibx` option in a backward-compatible manner that
more rsync versions understand. This error indicates that the older rsync
- version will not allow you to force the compression type.
-
- See the `--skip-compress` option for the default list of file suffixes that
- will not be compressed.
+ version on the server will not allow you to force the compression type.
-0. `--compress-choice=STR`, `--zc=STR`
+ Note that the "zlibx" compression algorithm is just the "zlib" algorithm
+ with matched data excluded from the compression stream (to try to make it
+ more compatible with an external zlib implementation).
- This option can be used to override the automatic selection of the
- compression algorithm that is the default when `--compress` is used.
+0. `--compress-level=NUM`, `--zl=NUM`
- Currently the STR can be "zlibx", "zlib", or "none".
+ Explicitly set the compression level to use (see `--compress`, `-z`)
+ instead of letting it default. The `--compress` option is implied as long
+ as the level chosen is not a "don't compress" level for the compression
+ algorithm that is in effect (e.g. zlib compression treats level 0 as
+ "off").
- The "zlibx" algorithm is given preference over "zlib" if both sides of the
- transfer are at least version 3.2.0, otherwise it will choose "zlib" unless
- you override it via something like `-zz`. These 2 algorithms are the stame
- except that "zlibx" does not try to include matched data that was not
- transferred in the compression computations.
+ The level values vary depending on the checksum in effect. Because rsync
+ will negotiate a checksum choice by default (when the remote rsync is new
+ enough), it can be good to combine this option with a `--compress-choice`
+ (`--zc`) option unless you're sure of the choice in effect. For example:
- If "none" is specified, that is equivalent to using `--no-compress`.
+ > rsync -aiv --zc=zstd --zl=22 host:src/ dest/
- This option implies `--compress` unless "none" was specified.
+ For zlib & zlibx compression the valid values are from 1 to 9 with 6 being
+ the default. Specifying 0 turns compression off, and specifying -1 chooses
+ the default of 6.
- You can also override the compression negotation using the
- RSYNC_COMPRESS_LIST environment variable by setting it to a space-separated
- list of compression names that you consider acceptable. If no common
- compress choice is found, the client exits with an error. It ignores
- "auto" and all unknown compression names. If the remote rsync is not new
- enough to handle a compression negotiation list, the list is silently
- ignored unless it contains the string "FAIL".
+ For zstd compression the valid values are from -131072 to 22 with 3 being
+ the default. Specifying 0 chooses the default of 3.
- Use "rsync -V" to see the default compress list.
+ For lz4 compression there are no levels, so the value is always 0.
-0. `--compress-level=NUM`
+ If you specify a too-large or too-small value, the number is silently
+ limited to a valid value. This allows you to specify something like
+ `--zl=999999999` and be assured that you'll end up with the maximum
+ compression level no matter what algorithm was chosen.
- Explicitly set the compression level to use (see `--compress`) instead of
- letting it default. If NUM is non-zero, the `--compress` option is
- implied.
+ If you want to know the compression level that is in effect, specify
+ `--debug=nstr` to see the "negotiated string" results. This will report
+ something like "`Client compress: zstd (level 3)`" (along with the checksum
+ choice in effect).
0. `--skip-compress=LIST`
possible. Rsync sets the compression level on a per-file basis based on
the file's suffix. If the compression algorithm has an "off" level (such
as zlib/zlibx) then no compression occurs for those files. Other
- algorithms have the level minimized to reduces the CPU usage as much as
- possible.
+ algorithms that support changing the streaming level on-the-fly will have
+ the level minimized to reduces the CPU usage as much as possible for a
+ matching file. At this time, only zlib & zlibx compression support this
+ changing of levels on a per-file basis.
The **LIST** should be one or more file suffixes (without the dot) separated
- by slashes (/). You may specify an empty string to indicate that no files
+ by slashes (`/`). You may specify an empty string to indicate that no files
should be skipped.
Simple character-class matching is supported: each must consist of a list
of letters inside the square brackets (e.g. no special classes, such as
"[:alpha:]", are supported, and '-' has no special meaning).
- The characters asterisk (\*) and question-mark (?) have no special meaning.
+ The characters asterisk (`*`) and question-mark (`?`) have no special meaning.
Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules
matches 2 suffixes):
The default file suffixes in the skip-compress list in this version of
rsync are:
+ [comment]: # (This list gets used for the default-dont-compress.h file.)
+
+ > 3g2
+ > 3gp
> 7z
+ > aac
> ace
+ > apk
> avi
> bz2
> deb
+ > dmg
+ > ear
+ > f4v
+ > flac
+ > flv
> gpg
> gz
> iso
+ > jar
> jpeg
> jpg
+ > lrz
> lz
+ > lz4
> lzma
> lzo
+ > m1a
+ > m1v
+ > m2a
+ > m2ts
+ > m2v
+ > m4a
+ > m4b
+ > m4p
+ > m4r
+ > m4v
+ > mka
+ > mkv
> mov
+ > mp1
+ > mp2
> mp3
> mp4
+ > mpa
+ > mpeg
+ > mpg
+ > mpv
+ > mts
+ > odb
+ > odf
+ > odg
+ > odi
+ > odm
+ > odp
+ > ods
+ > odt
+ > oga
> ogg
+ > ogm
> ogv
+ > ogx
+ > opus
+ > otg
+ > oth
+ > otp
+ > ots
+ > ott
+ > oxt
> png
+ > qt
> rar
> rpm
+ > rz
> rzip
+ > spx
> squashfs
+ > sxc
+ > sxd
+ > sxg
+ > sxm
+ > sxw
+ > sz
> tbz
+ > tbz2
> tgz
> tlz
+ > ts
> txz
+ > tzo
+ > vob
+ > war
> webm
> webp
> xz
> z
> zip
+ > zst
This list will be replaced by your `--skip-compress` list in all but one
situation: a copy from a daemon rsync will add your skipped suffixes to its
If a user or group has no name on the source system or it has no match on
the destination system, then the numeric ID from the source system is used
- instead. See also the comments on the "use chroot" setting in the
+ instead. See also the comments on the "`use chroot`" setting in the
rsyncd.conf manpage for information on how the chroot setting affects
rsync's ability to look up the names of the users and groups and what you
can do about it.
You may specify usernames or user IDs for the **FROM** and **TO** values,
and the **FROM** value may also be a wild-card string, which will be
matched against the sender's names (wild-cards do NOT match against ID
- numbers, though see below for why a '\*' matches everything). You may
+ numbers, though see below for why a '`*`' matches everything). You may
instead specify a range of ID numbers via an inclusive range: LOW-HIGH.
For example:
Any IDs that do not have a name on the sending side are treated as having
an empty name for the purpose of matching. This allows them to be matched
- via a "\*" or using an empty name. For instance:
+ via a "`*`" or using an empty name. For instance:
> --usermap=:nobody --groupmap=*:nobody
For the `--usermap` option to have any effect, the `-o` (`--owner`) option
must be used (or implied), and the receiver will need to be running as a
super-user (see also the `--fake-super` option). For the `--groupmap`
- option to have any effect, the `-g` (`--groups`) option must be used (or
+ option to have any effect, the `-g` (`--group`) option must be used (or
implied), and the receiver will need to have permissions to set that group.
+ If your shell complains about the wildcards, use `--protect-args` (`-s`).
+
0. `--chown=USER:GROUP`
This option forces all files to be owned by USER with group GROUP. This is
will occur. If GROUP is empty, the trailing colon may be omitted, but if
USER is empty, a leading colon must be supplied.
- If you specify "--chown=foo:bar, this is exactly the same as specifying
- "`--usermap=*:foo --groupmap=*:bar`", only easier.
+ If you specify "`--chown=foo:bar`", this is exactly the same as specifying
+ "`--usermap=*:foo --groupmap=*:bar`", only easier. If your shell complains
+ about the wildcards, use `--protect-args` (`-s`).
-0. `--timeout=TIMEOUT`
+0. `--timeout=SECONDS`
This option allows you to set a maximum I/O timeout in seconds. If no data
is transferred for the specified time then rsync will exit. The default is
0, which means no timeout.
-0. `--contimeout`
+0. `--contimeout=SECONDS`
This option allows you to set the amount of time that rsync will wait for
its connection to an rsync daemon to succeed. If the timeout is reached,
rsync exits with an error.
-0. `--address`
+0. `--address=ADDRESS`
By default rsync will bind to the wildcard address when connecting to an
rsync daemon. The `--address` option allows you to specify a specific IP
the port as a part of the URL). See also this option in the `--daemon`
mode section.
-0. `--sockopts`
+0. `--sockopts=OPTIONS`
This option can provide endless fun for people who like to tune their
systems to the utmost degree. You can set all sorts of socket options
which may make transfers faster (or slower!). Read the man page for the
`setsockopt()` system call for details on some of the options you may be
able to set. By default no special socket options are set. This only
- affects direct socket connections to a remote rsync daemon. This option
- also exists in the `--daemon` mode section.
+ affects direct socket connections to a remote rsync daemon.
+
+ This option also exists in the `--daemon` mode section.
0. `--blocking-io`
directory, an `L` for a symlink, a `D` for a device, and a `S` for a
special file (e.g. named sockets and fifos).
- The other letters in the string above are the actual letters that will be
- output if the associated attribute for the item is being updated or a "."
- for no change. Three exceptions to this are: (1) a newly created item
- replaces each letter with a "+", (2) an identical item replaces the dots
- with spaces, and (3) an unknown attribute replaces each letter with a "?"
- (this can happen when talking to an older rsync).
+ The other letters in the string indicate if some attributes of the file
+ have changed, as follows:
+
+ - "`.`" - the attribute is unchanged.
+ - "`+`" - the file is newly created.
+ - "` `" - all the attributes are unchanged (all dots turn to spaces).
+ - "`?`" - the change is unknown (when the remote rsync is old).
+ - A letter indicates an attribute is being updated.
The attribute that is associated with each letter is as follows:
value (requires `--owner` and super-user privileges).
- A `g` means the group is different and is being updated to the sender's
value (requires `--group` and the authority to set the group).
- - A `u` means the access (use) time is different and is being updated to
- the sender's value (requires `--atimes`). An alternate value of `U`
- means that the access time will be set to the transfer time, which
- happens when a symlink or directory is updated.
- - The `a` means that the ACL information changed.
- - The `x` means that the extended attribute information changed.
+ - A `u`|`n`|`b` indicates the following information: `u` means the access
+ (use) time is different and is being updated to the sender's value
+ (requires `--atimes`); `n` means the create time (newness) is different
+ and is being updated to the sender's value (requires `--crtimes`); `b`
+ means that both the access and create times are being updated.
+ - The `a` means that the ACL information is being changed.
+ - The `x` means that the extended attribute information is being changed.
One other output is possible: when deleting files, the "%i" will output the
string "`*deleting`" for each item that is being removed (assuming that you
character. A default format of "%n%L" is assumed if either `--info=name`
or `-v` is specified (this tells you just the name of the file and, if the
item is a link, where it points). For a full list of the possible escape
- characters, see the "log format" setting in the rsyncd.conf manpage.
+ characters, see the "`log format`" setting in the rsyncd.conf manpage.
Specifying the `--out-format` option implies the `--info=name` option,
which will mention each file, dir, etc. that gets updated in a significant
file specified by the `--log-file` option (which must also be specified for
this option to have any effect). If you specify an empty string, updated
files will not be mentioned in the log file. For a list of the possible
- escape characters, see the "log format" setting in the rsyncd.conf manpage.
+ escape characters, see the "`log format`" setting in the rsyncd.conf manpage.
The default FORMAT used if `--log-file` is specified and this option is not
is '%i %n%L'.
sense) were created (as opposed to updated). The total count will be
followed by a list of counts by filetype (if the total is non-zero).
- `Number of deleted files` is the count of how many "files" (generic
- sense) were created (as opposed to updated). The total count will be
+ sense) were deleted. The total count will be
followed by a list of counts by filetype (if the total is non-zero).
Note that this line is only output if deletions are in effect, and only
if protocol 31 is being used (the default for rsync 3.1.x).
tabs) are always escaped, regardless of this option's setting.
The escape idiom that started in 2.6.7 is to output a literal backslash
- (\\) and a hash (#), followed by exactly 3 octal digits. For example, a
- newline would output as "\\#012". A literal backslash that is in a
+ (`\`) and a hash (`#`), followed by exactly 3 octal digits. For example, a
+ newline would output as "`\#012`". A literal backslash that is in a
filename is not escaped unless it is followed by a hash and 3 digits (0-9).
0. `--human-readable`, `-h`
level by one. You can take the level down to 0 (to output numbers as pure
digits) by specifying the `--no-human-readable` (`--no-h`) option.
- The unit letters that are appended in levels 2 and 3 are: K (kilo), M
- (mega), G (giga), or T (tera). For example, a 1234567-byte file would
- output as 1.23M in level-2 (assuming that a period is your local decimal
- point).
+ The unit letters that are appended in levels 2 and 3 are: `K` (kilo), `M`
+ (mega), `G` (giga), `T` (tera), or `P` (peta). For example, a 1234567-byte
+ file would output as 1.23M in level-2 (assuming that a period is your local
+ decimal point).
Backward compatibility note: versions of rsync prior to 3.1.0 do not
support human-readable level 1, and they default to level 0. Thus,
rule may be ineffective at the end of your other rules, or (2) you may wish
to override rsync's exclude choice. For instance, if you want to make
rsync clean-up any left-over partial-dirs that may be lying around, you
- should specify `--delete-after` and add a "risk" filter rule, e.g. `-f 'R
- .rsync-partial/'`. (Avoid using `--delete-before` or `--delete-during`
- unless you don't need rsync to use any of the left-over partial-dir data
- during the current run.)
+ should specify `--delete-after` and add a "risk" filter rule, e.g.
+ `-f 'R .rsync-partial/'`. (Avoid using `--delete-before` or
+ `--delete-during` unless you don't need rsync to use any of the left-over
+ partial-dir data during the current run.)
IMPORTANT: the `--partial-dir` should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
tmp). This requires both ends of the transfer to be at least version
3.2.0.
- For the purposes of the daemon-config's "refuse options" setting,
+ For the purposes of the daemon-config's "`refuse options`" setting,
`--partial-dir` does _not_ imply `--partial`. This is so that a refusal of
the `--partial` option can be used to disallow the overwriting of
destination files with a partial transfer, while still allowing the safer
can do if you want rsync to cleanup old `.~tmp~` dirs that might be lying
around. Conflicts with `--inplace` and `--append`.
+ This option implies `--no-inc-recursive` since it needs the full file list
+ in memory in order to be able to iterate over it at the end.
+
This option uses more memory on the receiving side (one bit per file
transferred) and also requires enough free disk space on the receiving side
to hold an additional copy of all the updated files. Note also that you
CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it.
-0. `--password-file=FILE`
+0. `--password-file=FILE`
This option allows you to provide a password for accessing an rsync daemon
via a file or via standard input if **FILE** is `-`. The file should
authentication (i.e. if you have also specified a password in the daemon's
config file).
-0. `--list-only`
+0. `--early-input=FILE`
+
+ This option allows rsync to send up to 5K of data to the "early exec"
+ script on its stdin. One possible use of this data is to give the script a
+ secret that can be used to mount an encrypted filesystem (which you should
+ unmount in the the "post-xfer exec" script).
+
+ The daemon must be at least version 3.2.1.
+
+0. `--list-only`
This option will cause the source files to be listed instead of
transferred. This option is inferred if there is a single source arg and
need to expand a directory's content), or turn on recursion and exclude the
content of subdirectories: `-r --exclude='/*/*'`.
-0. `--bwlimit=RATE`
+0. `--bwlimit=RATE`
This option allows you to specify the maximum transfer rate for the data
sent over the socket, specified in units per second. The RATE value can be
fractional value (e.g. "`--bwlimit=1.5m`"). If no suffix is specified, the
value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had
been appended). See the `--max-size` option for a description of all the
- available suffixes. A value of zero specifies no limit.
+ available suffixes. A value of 0 specifies no limit.
For backward-compatibility reasons, the rate limit will be rounded to the
nearest KiB unit, so no rate smaller than 1024 bytes per second is
Rsync writes data over the socket in blocks, and this option both limits
the size of the blocks that rsync writes, and tries to keep the average
- transfer rate at the requested limit. Some "burstiness" may be seen where
+ transfer rate at the requested limit. Some burstiness may be seen where
rsync writes out a block of data and then sleeps to bring the average rate
into compliance.
buffered, while other can show up as very slow when the flushing of the
output buffer occurs. This may be fixed in a future version.
-0. `--write-batch=FILE`
+0. `--stop-after=MINS
+
+ This option tells rsync to stop copying when the specified number of
+ minutes has elapsed.
+
+ Rsync also accepts an earlier version of this option: `--time-limit=MINS`.
+
+ For maximal flexibility, rsync does not communicate this option to the
+ remote rsync since it is usually enough that one side of the connection
+ quits as specified. This allows the option's use even when only one side
+ of the connection supports it. You can tell the remote side about the time
+ limit using `--remote-option` (`-M`), should the need arise.
+
+0. `--stop-at=y-m-dTh:m
+
+ This option tells rsync to stop copying when the specified point in time
+ has been reached. The date & time can be fully specified in a numeric
+ format of year-month-dayThour:minute (e.g. 2000-12-31T23:59) in the local
+ timezone. You may choose to separate the date numbers using slashes
+ instead of dashes.
+
+ The value can also be abbreviated in a variety of ways, such as specifying
+ a 2-digit year and/or leaving off various values. In all cases, the value
+ will be taken to be the next possible point in time where the supplied
+ information matches. If the value specifies the current time or a past
+ time, rsync exits with an error.
+
+ For example, "1-30" specifies the next January 30th (at midnight local
+ time), "14:00" specifies the next 2 P.M., "1" specifies the next 1st of the
+ month at midnight, "31" specifies the next month where we can stop on its
+ 31st day, and ":59" specifies the next 59th minute after the hour.
+
+ For maximal flexibility, rsync does not communicate this option to the
+ remote rsync since it is usually enough that one side of the connection
+ quits as specified. This allows the option's use even when only one side
+ of the connection supports it. You can tell the remote side about the time
+ limit using `--remote-option` (`-M`), should the need arise. Do keep in
+ mind that the remote host may have a different default timezone than your
+ local host.
+
+0. `--fsync`
+
+ Cause the receiving side to fsync each finished file. This may slow down
+ the transfer, but can help to provide peace of mind when updating critical
+ files.
+
+0. `--write-batch=FILE`
Record a file that can later be applied to another identical destination
with `--read-batch`. See the "BATCH MODE" section for details, and also
the `--only-write-batch` option.
-0. `--only-write-batch=FILE`
+ This option overrides the negotiated checksum & compress lists and always
+ negotiates a choice based on old-school md5/md4/zlib choices. If you want
+ a more modern choice, use the `--checksum-choice` (`--cc`) and/or
+ `--compress-choice` (`--zc`) options.
+
+0. `--only-write-batch=FILE`
Works like `--write-batch`, except that no updates are made on the
destination system when creating the batch. This lets you transport the
into the batch file without having to flow over the wire to the receiver
(when pulling, the sender is remote, and thus can't write the batch).
-0. `--read-batch=FILE`
+0. `--read-batch=FILE`
Apply all of the changes stored in FILE, a file previously generated by
`--write-batch`. If _FILE_ is `-`, the batch data will be read from
standard input. See the "BATCH MODE" section for details.
-0. `--protocol=NUM`
+0. `--protocol=NUM`
Force an older protocol version to be used. This is useful for creating a
batch file that is compatible with an older version of rsync. For
protocol version to be used in the batch file (assuming you can't upgrade
the rsync on the reading system).
-0. `--iconv=CONVERT_SPEC`
+0. `--iconv=CONVERT_SPEC`
Rsync can convert filenames between character sets using this option.
Using a CONVERT_SPEC of "." tells rsync to look up the default
free to specify just the local charset for a daemon transfer (e.g.
`--iconv=utf8`).
-0. `--ipv4`, `-4` or `--ipv6`, `-6`
+0. `--ipv4`, `-4` or `--ipv6`, `-6`
- Tells rsync to prefer IPv4/IPv6 when creating sockets. This only affects
- sockets that rsync has direct control over, such as the outgoing socket
- when directly contacting an rsync daemon. See also these options in the
- `--daemon` mode section.
+ Tells rsync to prefer IPv4/IPv6 when creating sockets or running ssh. This
+ affects sockets that rsync has direct control over, such as the outgoing
+ socket when directly contacting an rsync daemon, as well as the forwarding
+ of the `-4` or `-6` option to ssh when rsync can deduce that ssh is being
+ used as the remote shell. For other remote shells you'll need to specify
+ the "`--rsh SHELL -4`" option directly (or whatever ipv4/ipv6 hint options
+ it uses).
+
+ These options also exist in the `--daemon` mode section.
If rsync was complied without support for IPv6, the `--ipv6` option will
- have no effect. The `--version` output will tell you if this is the case.
+ have no effect. The `rsync --version` output will contain "`no IPv6`" if
+ is the case.
-0. `--checksum-seed=NUM`
+0. `--checksum-seed=NUM`
Set the checksum seed to the integer NUM. This 4 byte checksum seed is
included in each block and MD4 file checksum calculation (the more modern
The options allowed when starting an rsync daemon are as follows:
-0. `--daemon`
+0. `--daemon`
This tells rsync that it is to run as a daemon. The daemon you start
running may be accessed using an rsync client using the `host::module` or
each connect made by a client and respond to requests accordingly. See the
**rsyncd.conf**(5) man page for more details.
-0. `--address`
+0. `--address=ADDRESS`
By default rsync will bind to the wildcard address when run as a daemon
with the `--daemon` option. The `--address` option allows you to specify a
possible in conjunction with the `--config` option. See also the "address"
global option in the rsyncd.conf manpage.
-0. `--bwlimit=RATE`
+0. `--bwlimit=RATE`
This option allows you to specify the maximum transfer rate for the data
the daemon sends over the socket. The client can still specify a smaller
`--bwlimit` value, but no larger value will be allowed. See the client
version of this option (above) for some extra details.
-0. `--config=FILE`
+0. `--config=FILE`
This specifies an alternate config file than the default. This is only
relevant when `--daemon` is specified. The default is /etc/rsyncd.conf
user is not the super-user; in that case the default is rsyncd.conf in the
current directory (typically $HOME).
-0. `--dparam=OVERRIDE`, `-M`
+0. `--dparam=OVERRIDE`, `-M`
This option can be used to set a daemon-config parameter when starting up
rsync in daemon mode. It is equivalent to adding the parameter at the end
> rsync --daemon -M pidfile=/path/rsync.pid
-0. `--no-detach`
+0. `--no-detach`
When running as a daemon, this option instructs rsync to not detach itself
and become a background process. This option is required when running as a
`--no-detach` is also recommended when rsync is run under a debugger. This
option has no effect if rsync is run from inetd or sshd.
-0. `--port=PORT`
+0. `--port=PORT`
This specifies an alternate TCP port number for the daemon to listen on
rather than the default of 873. See also the "port" global option in the
rsyncd.conf manpage.
-0. `--log-file=FILE`
+0. `--log-file=FILE`
This option tells the rsync daemon to use the given log-file name instead
- of using the "log file" setting in the config file.
+ of using the "`log file`" setting in the config file.
-0. `--log-file-format=FORMAT`
+0. `--log-file-format=FORMAT`
This option tells the rsync daemon to use the given FORMAT string instead
- of using the "log format" setting in the config file. It also enables
- "transfer logging" unless the string is empty, in which case transfer
+ of using the "`log format`" setting in the config file. It also enables
+ "`transfer logging`" unless the string is empty, in which case transfer
logging is turned off.
-0. `--sockopts`
+0. `--sockopts`
This overrides the `socket options` setting in the rsyncd.conf file and has
the same syntax.
-0. `--verbose`, `-v`
+0. `--verbose`, `-v`
This option increases the amount of information the daemon logs during its
startup phase. After the client connects, the daemon's verbosity level
- will be controlled by the options that the client used and the "max
- verbosity" setting in the module's config section.
+ will be controlled by the options that the client used and the
+ "`max verbosity`" setting in the module's config section.
-0. `--ipv4`, `-4` or `--ipv6`, `-6`
+0. `--ipv4`, `-4` or `--ipv6`, `-6`
Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the
rsync daemon will use to listen for connections. One of these options may
using the port, try specifying `--ipv6` or `--ipv4` when starting the
daemon).
+ These options also exist in the regular rsync options section.
+
If rsync was complied without support for IPv6, the `--ipv6` option will
- have no effect. The `--version` output will tell you if this is the case.
+ have no effect. The `rsync --version` output will contain "`no IPv6`" if
+ is the case.
-0. `--help`, `-h`
+0. `--help`, `-h`
When specified after `--daemon`, print a short help page describing the
options available for starting an rsync daemon.
0. `risk, 'R'` files that match the pattern are not protected.
0. `clear, '!'` clears the current include/exclude list (takes no arg)
-When rules are being read from a file, empty lines are ignored, as are comment
-lines that start with a "#".
+When rules are being read from a file, empty lines are ignored, as are
+whole-line comments that start with a '`#`' (filename rules that contain a hash
+are unaffected).
-Note that the `--include`/`--exclude` command-line options do not allow the
+[comment]: # (Remember that markdown strips spaces from start/end of ` ... ` sequences!)
+[comment]: # (Thus, the `x ` sequences below use a literal non-breakable space!)
+
+Note that the `--include` & `--exclude` command-line options do not allow the
full range of rule parsing as described above -- they only allow the
-specification of include/exclude patterns plus a "!" token to clear the list
-(and the normal comment parsing when rules are read from a file). If a pattern
-does not begin with "- " (dash, space) or "+ " (plus, space), then the rule
-will be interpreted as if "+ " (for an include option) or "- " (for an exclude
-option) were prefixed to the string. A `--filter` option, on the other hand,
-must always contain either a short or long rule name at the start of the rule.
+specification of include / exclude patterns plus a "`!`" token to clear the
+list (and the normal comment parsing when rules are read from a file). If a
+pattern does not begin with "`- `" (dash, space) or "`+ `" (plus, space), then
+the rule will be interpreted as if "`+ `" (for an include option) or "`- `"
+(for an exclude option) were prefixed to the string. A `--filter` option, on
+the other hand, must always contain either a short or long rule name at the
+start of the rule.
Note also that the `--filter`, `--include`, and `--exclude` options take one
rule/pattern each. To add multiple ones, you can repeat the options on the
command-line, use the merge-file syntax of the `--filter` option, or the
-`--include-from`/`--exclude-from` options.
+`--include-from` / `--exclude-from` options.
# INCLUDE/EXCLUDE PATTERN RULES
of the files that are going to be transferred. These patterns can take several
forms:
-- if the pattern starts with a / then it is anchored to a particular spot in
+- if the pattern starts with a `/` then it is anchored to a particular spot in
the hierarchy of files, otherwise it is matched against the end of the
- pathname. This is similar to a leading ^ in regular expressions. Thus
- "/foo" would match a name of "foo" at either the "root of the transfer" (for
+ pathname. This is similar to a leading `^` in regular expressions. Thus
+ `/foo` would match a name of "foo" at either the "root of the transfer" (for
a global rule) or in the merge-file's directory (for a per-directory rule).
- An unqualified "foo" would match a name of "foo" anywhere in the tree because
+ An unqualified `foo` would match a name of "foo" anywhere in the tree because
the algorithm is applied recursively from the top down; it behaves as if each
path component gets a turn at being the end of the filename. Even the
unanchored "sub/foo" would match at any point in the hierarchy where a "foo"
was found within a directory named "sub". See the section on ANCHORING
INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify a pattern
that matches at the root of the transfer.
-- if the pattern ends with a / then it will only match a directory, not a
+- if the pattern ends with a `/` then it will only match a directory, not a
regular file, symlink, or device.
- rsync chooses between doing a simple string match and wildcard matching by
checking if the pattern contains one of these three wildcard characters:
'`*`', '`?`', and '`[`' .
- a '`*`' matches any path component, but it stops at slashes.
- use '`**`' to match anything, including slashes.
-- a '?' matches any character except a slash (/).
-- a '[' introduces a character class, such as [a-z] or [[:alpha:]].
+- a '`?`' matches any character except a slash (`/`).
+- a '`[`' introduces a character class, such as `[a-z]` or `[[:alpha:]]`.
- in a wildcard pattern, a backslash can be used to escape a wildcard
character, but it is matched literally when no wildcards are present. This
means that there is an extra level of backslash removal when a pattern
contains wildcard characters compared to a pattern that has none. e.g. if
you add a wildcard to "`foo\bar`" (which matches the backslash) you would
need to use "`foo\\bar*`" to avoid the "`\b`" becoming just "b".
-- if the pattern contains a / (not counting a trailing /) or a "`**`", then it
+- if the pattern contains a `/` (not counting a trailing /) or a "`**`", then it
is matched against the full pathname, including any leading directories. If
- the pattern doesn't contain a / or a "`**`", then it is matched only against
+ the pattern doesn't contain a `/` or a "`**`", then it is matched only against
the final component of the filename. (Remember that the algorithm is applied
recursively so "full filename" can actually be any portion of a path from the
starting directory on down.)
in the filesystem's tree (those inside the transfer). The exclude patterns
short-circuit the directory traversal stage as rsync finds the files to send.
-For instance, to include "/foo/bar/baz", the directories "/foo" and "/foo/bar"
+For instance, to include "`/foo/bar/baz`", the directories "`/foo`" and "`/foo/bar`"
must not be excluded. Excluding one of those parent directories prevents the
examination of its content, cutting off rsync's recursion into those paths and
-rendering the include for "/foo/bar/baz" ineffectual (since rsync can't match
+rendering the include for "`/foo/bar/baz`" ineffectual (since rsync can't match
something it never sees in the cut-off section of the directory hierarchy).
-The concept path exclusion is particularly important when using a trailing '\*'
+The concept path exclusion is particularly important when using a trailing '`*`'
rule. For instance, this won't work:
> + /some/path/this-file-will-not-be-found
> + /file-is-included
> - *
-This fails because the parent directory "some" is excluded by the '\*' rule, so
+This fails because the parent directory "some" is excluded by the '`*`' rule, so
rsync never visits any of the files in the "some" or "some/path" directories.
One solution is to ask for all directories in the hierarchy to be included by
using a single rule: "`+ */`" (put it somewhere before the "`- *`" rule), and
see also the comments on the `--delete` option
-Please report bugs! See the web site at <http://rsync.samba.org/>.
+Please report bugs! See the web site at <https://rsync.samba.org/>.
# VERSION
rsync is distributed under the GNU General Public License. See the file
COPYING for details.
-A web site is available at <http://rsync.samba.org/>. The site includes an
+A web site is available at <https://rsync.samba.org/>. The site includes an
FAQ-O-Matic which may cover questions unanswered by this manual page.
-The primary ftp site for rsync is <ftp://rsync.samba.org/pub/rsync>
-
We would be delighted to hear from you if you like this program. Please
contact the mailing-list at <rsync@lists.samba.org>.
Davison.
Mailing lists for support and development are available at
-<http://lists.samba.org/>.
+<https://lists.samba.org/>.
git.samba.org / rsync.git / blobdiff