Usages with just one SRC arg and no DEST arg will list the source files instead
of copying.
-The online version of this man page (that includes cross-linking of topics)
+The online version of this manpage (that includes cross-linking of topics)
is available at <https://download.samba.org/pub/rsync/rsync.1>.
## DESCRIPTION
communications, but it may have been configured to use a different remote shell
by default, such as rsh or remsh.
-You can also specify any remote shell you like, either by using the [`-e`](#opt--rsh)
-command line option, or by setting the RSYNC_RSH environment variable.
+You can also specify any remote shell you like, either by using the [`-e`](#opt)
+command line option, or by setting the [`RSYNC_RSH`](#) environment variable.
Note that rsync must be installed on both the source and destination machines.
> rsync somehost.mydomain.com::
-See the following section for more details.
+## COPYING TO A DIFFERENT NAME
+
+When you want to copy a directory to a different name, use a trailing slash on
+the source directory to put the contents of the directory into any destination
+directory you like:
+
+> rsync -ai foo/ bar/
+
+Rsync also has the ability to customize a destination file's name when copying
+a single item. The rules for this are:
+
+- The transfer list must consist of a single item (either a file or an empty
+ directory)
+- The final element of the destination path must not exist as a directory
+- The destination path must not have been specified with a trailing slash
+
+Under those circumstances, rsync will set the name of the destination's single
+item to the last element of the destination path. Keep in mind that it is best
+to only use this idiom when copying a file and use the above trailing-slash
+idiom when copying a directory.
+
+The following example copies the `foo.c` file as `bar.c` in the `save` dir
+(assuming that `bar.c` isn't a directory):
+
+> rsync -ai src/foo.c save/bar.c
+
+The single-item copy rule might accidentally bite you if you unknowingly copy a
+single item and specify a destination dir that doesn't exist (without using a
+trailing slash). For example, if `src/*.c` matches one file and `save/dir`
+doesn't exist, this will confuse you by naming the destination file `save/dir`:
+
+> rsync -ai src/*.c save/dir
+
+To prevent such an accident, either make sure the destination dir exists or
+specify the destination path with a trailing slash:
+
+> rsync -ai src/*.c save/dir/
+
+## SORTED TRANSFER ORDER
+
+Rsync always sorts the specified filenames into its internal transfer list.
+This handles the merging together of the contents of identically named
+directories, makes it easy to remove duplicate filenames. It can, however,
+confuse someone when the files are transferred in a different order than what
+was given on the command-line.
+
+If you need a particular file to be transferred prior to another, either
+separate the files into different rsync calls, or consider using
+[`--delay-updates`](#opt) (which doesn't affect the sorted transfer order, but
+does make the final file-updating phase happen much more rapidly).
+
+## MULTI-HOST SECURITY
+
+Rsync takes steps to ensure that the file requests that are shared in a
+transfer are protected against various security issues. Most of the potential
+problems arise on the receiving side where rsync takes steps to ensure that the
+list of files being transferred remains within the bounds of what was
+requested.
+
+Toward this end, rsync 3.1.2 and later have aborted when a file list contains
+an absolute or relative path that tries to escape out of the top of the
+transfer. Also, beginning with version 3.2.5, rsync does two more safety
+checks of the file list to (1) ensure that no extra source arguments were added
+into the transfer other than those that the client requested and (2) ensure
+that the file list obeys the exclude rules that were sent to the sender.
+
+For those that don't yet have a 3.2.5 client rsync (or those that want to be
+extra careful), it is safest to do a copy into a dedicated destination
+directory for the remote files when you don't trust the remote host. For
+example, instead of doing an rsync copy into your home directory:
+
+> rsync -aiv host1:dir1 ~
+
+Dedicate a "host1-files" dir to the remote content:
+
+> rsync -aiv host1:dir1 ~/host1-files
+
+See the [`--trust-sender`](#opt) option for additional details.
+
+CAUTION: it is not particularly safe to use rsync to copy files from a
+case-preserving filesystem to a case-ignoring filesystem. If you must perform
+such a copy, you should either disable symlinks via `--no-links` or enable the
+munging of symlinks via [`--munge-links`](#opt) (and make sure you use the
+right local or remote option). This will prevent rsync from doing potentially
+dangerous things if a symlink name overlaps with a file or directory. It does
+not, however, ensure that you get a full copy of all the files (since that may
+not be possible when the names overlap). A potentially better solution is to
+list all the source files and create a safe list of filenames that you pass to
+the [`--files-from`](#opt) option. Any files that conflict in name would need
+to be copied to different destination directories using more than one copy.
+
+While a copy of a case-ignoring filesystem to a case-ignoring filesystem can
+work out fairly well, if no `--delete-during` or `--delete-before` option is
+active, rsync can potentially update an existing file on the receiveing side
+without noticing that the upper-/lower-case of the filename should be changed
+to match the sender.
## ADVANCED USAGE
specifying additional remote-host args in the same style as the first, or with
the hostname omitted. For instance, all these work:
-> rsync -av host:file1 :file2 host:file{3,4} /dest/
-> rsync -av host::modname/file{1,2} host::modname/file3 /dest/
-> rsync -av host::modname/file1 ::modname/file{3,4} /dest/
+> rsync -aiv host:file1 :file2 host:file{3,4} /dest/
+> rsync -aiv host::modname/file{1,2} host::modname/extra /dest/
+> rsync -aiv host::modname/first ::extra-file{1,2} /dest/
-**Older versions of rsync** required using quoted spaces in the SRC, like these
-examples:
+Note that a daemon connection only supports accessing one module per copy
+command, so if the start of a follow-up path doesn't begin with the
+modname of the first path, it is assumed to be a path in the module (such as
+the extra-file1 & extra-file2 that are grabbed above).
-> rsync -av host:'dir1/file1 dir2/file2' /dest
-> rsync host::'modname/dir1/file1 modname/dir2/file2' /dest
+Really old versions of rsync (2.6.9 and before) only allowed specifying one
+remote-source arg, so some people have instead relied on the remote-shell
+performing space splitting to break up an arg into multiple paths. Such
+unintuitive behavior is no longer supported by default (though you can request
+it, as described below).
-This word-splitting only works in a modern rsync by using [`--old-args`](#opt)
-(or its environment variable) and making sure that [`--protect-args`](#opt) is
-not enabled.
+Starting in 3.2.4, filenames are passed to a remote shell in such a way as to
+preserve the characters you give it. Thus, if you ask for a file with spaces
+in the name, that's what the remote rsync looks for:
+
+> rsync -aiv host:'a simple file.pdf' /dest/
+
+If you use scripts that have been written to manually apply extra quoting to
+the remote rsync args (or to require remote arg splitting), you can ask rsync
+to let your script handle the extra escaping. This is done by either adding
+the [`--old-args`](#opt) option to the rsync runs in the script (which requires
+a new rsync) or exporting [RSYNC_OLD_ARGS](#)=1 and [RSYNC_PROTECT_ARGS](#)=0
+(which works with old or new rsync versions).
## CONNECTING TO AN RSYNC DAEMON
Using rsync in this way is the same as using it with a remote shell except
that:
-- you either use a double colon :: instead of a single colon to separate the
- hostname from the path, or you use an rsync:// URL.
-- the first word of the "path" is actually a module name.
-- the remote daemon may print a message of the day when you connect.
-- if you specify no path name on the remote daemon then the list of accessible
- paths on the daemon will be shown.
-- if you specify no local destination then a listing of the specified files on
- the remote daemon is provided.
-- you must not specify the [`--rsh`](#opt) (`-e`) option (since that overrides
- the daemon connection to use ssh -- see [USING RSYNC-DAEMON FEATURES VIA A
- REMOTE-SHELL CONNECTION](#) below).
+- Use either double-colon syntax or rsync:// URL syntax instead of the
+ single-colon (remote shell) syntax.
+- The first element of the "path" is actually a module name.
+- Additional remote source args can use an abbreviated syntax that omits the
+ hostname and/or the module name, as discussed in [ADVANCED USAGE](#).
+- The remote daemon may print a "message of the day" when you connect.
+- If you specify only the host (with no module or path) then a list of
+ accessible modules on the daemon is output.
+- If you specify a remote source path but no destination, a listing of the
+ matching files on the remote daemon is output.
+- The [`--rsh`](#opt) (`-e`) option must be omitted to avoid changing the
+ connection style from using a socket connection to [USING RSYNC-DAEMON
+ FEATURES VIA A REMOTE-SHELL CONNECTION](#).
An example that copies all the files in a remote module named "src":
Some modules on the remote daemon may require authentication. If so, you will
receive a password prompt when you connect. You can avoid the password prompt
-by setting the environment variable RSYNC_PASSWORD to the password you want to
-use or using the [`--password-file`](#opt) option. This may be useful when
-scripting rsync.
+by setting the environment variable [`RSYNC_PASSWORD`](#) to the password you
+want to use or using the [`--password-file`](#opt) option. This may be useful
+when scripting rsync.
WARNING: On some systems environment variables are visible to all users. On
those systems using [`--password-file`](#opt) is recommended.
You may establish the connection via a web proxy by setting the environment
-variable RSYNC_PROXY to a hostname:port pair pointing to your web proxy. Note
-that your web proxy's configuration must support proxy connections to port 873.
+variable [`RSYNC_PROXY`](#) to a hostname:port pair pointing to your web proxy.
+Note that your web proxy's configuration must support proxy connections to port
+873.
You may also establish a daemon connection using a program as a proxy by
-setting the environment variable RSYNC_CONNECT_PROG to the commands you wish to
-run in place of making a direct socket connection. The string may contain the
-escape "%H" to represent the hostname specified in the rsync command (so use
-"%%" if you need a single "%" in your string). For example:
+setting the environment variable [`RSYNC_CONNECT_PROG`](#) to the commands you
+wish to run in place of making a direct socket connection. The string may
+contain the escape "%H" to represent the hostname specified in the rsync
+command (so use "%%" if you need a single "%" in your string). For example:
> export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
> rsync -av targethost1::module/src/ /dest/
The command specified above uses ssh to run nc (netcat) on a proxyhost, which
forwards all data to port 873 (the rsync daemon) on the targethost (%H).
-Note also that if the RSYNC_SHELL environment variable is set, that program
-will be used to run the RSYNC_CONNECT_PROG command instead of using the default
-shell of the **system()** call.
+Note also that if the [`RSYNC_SHELL`](#) environment variable is set, that
+program will be used to run the `RSYNC_CONNECT_PROG` command instead of using
+the default shell of the **system()** call.
## USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION
The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to
log-in to the "module".
+In this setup, the daemon is started by the ssh command that is accessing the
+system (which can be forced via the `~/.ssh/authorized_keys` file, if desired).
+However, when accessing a daemon directly, it needs to be started beforehand.
+
## STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS
In order to connect to an rsync daemon, the remote system needs to have a
daemon already running (or it needs to have configured something like inetd to
spawn an rsync daemon for incoming connections on a particular port). For full
information on how to start a daemon that will handling incoming socket
-connections, see the [**rsyncd.conf**(5)](./rsyncd.conf.5) man page -- that is
+connections, see the [**rsyncd.conf**(5)](rsyncd.conf.5) manpage -- that is
the config file for the daemon, and it contains the full details for how to run
the daemon (including stand-alone and inetd configurations).
If you're using one of the remote-shell transports for the transfer, there is
no need to manually start an rsync daemon.
-## SORTED TRANSFER ORDER
-
-Rsync always sorts the specified filenames into its internal transfer list.
-This handles the merging together of the contents of identically named
-directories, makes it easy to remove duplicate filenames, and may confuse
-someone when the files are transferred in a different order than what was given
-on the command-line.
-
-If you need a particular file to be transferred prior to another, either
-separate the files into different rsync calls, or consider using
-[`--delay-updates`](#opt) (which doesn't affect the sorted transfer order, but
-does make the final file-updating phase happen much more rapidly).
-
## EXAMPLES
-Here are some examples of how I use rsync.
-
-To backup my wife's home directory, which consists of large MS Word files and
-mail folders, I use a cron job that runs
-
-> rsync -Cavz . arvidsjaur:backup
+Here are some examples of how rsync can be used.
-each night over a PPP connection to a duplicate directory on my machine
-"arvidsjaur".
+To backup a home directory, which consists of large MS Word files and mail
+folders, a per-user cron job can be used that runs this each day:
-To synchronize my samba source trees I use the following Makefile targets:
+> rsync -aiz . bkhost:backup/joe/
-> get:
-> rsync -avuzb --exclude '*~' samba:samba/ .
-> put:
-> rsync -Cavuzb . samba:samba/
-> sync: get put
+To move some files from a remote host to the local host, you could run:
-This allows me to sync with a CVS directory at the other end of the connection.
-I then do CVS operations on the remote machine, which saves a lot of time as
-the remote CVS protocol isn't very efficient.
-
-I mirror a directory between my "old" and "new" ftp sites with the command:
-
-> rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge"
-
-This is launched from cron every few hours.
+> rsync -aiv --remove-source-files rhost:/tmp/{file1,file2}.c ~/src/
## OPTION SUMMARY
Here is a short summary of the options available in rsync. Each option also
-has its own detailed description later in this man page.
+has its own detailed description later in this manpage.
[comment]: # (help-rsync.h)
[comment]: # (Keep these short enough that they'll be under 80 chars when indented by 7 chars.)
--append-verify --append w/old data in file checksum
--dirs, -d transfer directories without recursing
--old-dirs, --old-d works like --dirs when talking to old rsync
---mkpath create the destination's path component
+--mkpath create destination's missing path components
--links, -l copy symlinks as symlinks
--copy-links, -L transform symlink into referent file/dir
--copy-unsafe-links only "unsafe" symlinks are transformed
--owner, -o preserve owner (super-user only)
--group, -g preserve group
--devices preserve device files (super-user only)
+--copy-devices copy device contents as a regular file
+--write-devices write to devices as files (implies --inplace)
--specials preserve special files
-D same as --devices --specials
--times, -t preserve modification times
--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)
--files-from=FILE read list of source-file names from FILE
--from0, -0 all *-from/filter files are delimited by 0s
--old-args disable the modern arg-protection idiom
---protect-args, -s no space-splitting; wildcard chars only
+--secluded-args, -s use the protocol to safely send the args
+--trust-sender trust the remote sender's file list
--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
Rsync accepts both long (double-dash + word) and short (single-dash + letter)
options. The full list of the available options are described below. If an
option can be specified in more than one way, the choices are comma-separated.
-Some options only have a long variant, not a short. If the option takes a
-parameter, the parameter is only listed after the long variant, even though it
-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
-substituted by your shell, so `--option=~/foo` will not change the tilde into
-your home directory (remove the '=' for that).
+Some options only have a long variant, not a short.
+
+If the option takes a parameter, the parameter is only listed after the long
+variant, even though it must also be specified for the short. When specifying
+a parameter, you can either use the form `--option=param`, `--option param`,
+`-o=param`, `-o param`, or `-oparam` (the latter choices assume that your
+option has a short variant).
+
+The parameter may need to be quoted in some manner for it to survive the
+shell's command-line parsing. Also keep in mind that a leading tilde (`~`) in
+a pathname is substituted by your shell, so make sure that you separate the
+option name from the pathname using a space if you want the local shell to
+expand it.
+
+[comment]: # (Some markup below uses a literal non-breakable space when a backtick string)
+[comment]: # (needs to contain a space since markdown strips spaces from the start/end)
[comment]: # (An OL starting at 0 is converted into a DL by the parser.)
-0. `--help`, `-h` `(*)`
+0. `--help`
Print a short help page describing the options available in rsync and exit.
- (*) The `-h` short option will only invoke `--help` when used without other
- options since it normally means [`--human-readable`](#opt).
+ You can also use `-h` for `--help` when it is used without any other
+ options (since it normally means [`--human-readable`](#opt)).
0. `--version`, `-V`
- Print the rsync version plus other info and exit.
+ Print the rsync version plus other info and exit. When repeated, the
+ information is output is a JSON format that is still fairly readable
+ (client side only).
- The output includes the default list of checksum algorithms, the default
- list of compression algorithms, a list of compiled-in capabilities, a link
- to the rsync web site, and some license/copyright info.
+ The output includes a list of compiled-in capabilities, a list of
+ optimizations, the default list of checksum algorithms, the default list of
+ compression algorithms, the default list of daemon auth digests, a link to
+ the rsync web site, and a few other items.
0. `--verbose`, `-v`
crtimes (`-N`), nor the finding and preserving of hardlinks (`-H`).
The only exception to the above equivalence is when [`--files-from`](#opt)
- is specified, in which case [`-r`](#opt--recursive) is not implied.
+ is specified, in which case [`-r`](#opt) is not implied.
0. `--no-OPTION`
You may turn off one or more implied options by prefixing the option name
- with "no-". Not all options may be prefixed with a "no-": only options that
- are implied by other options (e.g. `--no-D`, `--no-perms`) or have
- different defaults in various circumstances (e.g. `--no-whole-file`,
- `--no-blocking-io`, `--no-dirs`). You may specify either the short or the
- long option name after the "no-" prefix (e.g. `--no-R` is the same as
- `--no-relative`).
-
- For example: if you want to use [`--archive`](#opt) (`-a`) but don't want
+ with "no-". Not all positive options have a negated opposite, but a lot
+ do, including those that can be used to disable an implied option (e.g.
+ `--no-D`, `--no-perms`) or have different defaults in various circumstances
+ (e.g. [`--no-whole-file`](#opt), `--no-blocking-io`, `--no-dirs`). Every
+ valid negated option accepts both the short and the long option name after
+ the "no-" prefix (e.g. `--no-R` is the same as `--no-relative`).
+
+ As an example, if you want to use [`--archive`](#opt) (`-a`) but don't want
[`--owner`](#opt) (`-o`), instead of converting `-a` into `-rlptgD`, you
- could specify `-a --no-o` (or `-a --no-owner`).
+ can specify `-a --no-o` (aka `--archive --no-owner`).
The order of the options is important: if you specify `--no-r -a`, the `-r`
option would end up being turned on, the opposite of `-a --no-r`. Note
also that the side-effects of the [`--files-from`](#opt) option are NOT
positional, as it affects the default state of several options and slightly
- changes the meaning of [`-a`](#opt--archive) (see the
- [`--files-from`](#opt) option for more details).
+ changes the meaning of [`-a`](#opt) (see the [`--files-from`](#opt) option
+ for more details).
0. `--recursive`, `-r`
In order to make [`--delete`](#opt) compatible with incremental recursion,
rsync 3.0.0 made [`--delete-during`](#opt) the default delete mode (which
- was first first added in 2.6.4).
+ was first added in 2.6.4).
One side-effect of incremental recursion is that any missing
sub-directories inside a recursively-scanned directory are (by default)
created prior to recursing into the sub-dirs. This earlier creation point
- (commpared to a non-incremental recursion) allows rsync to then set the
+ (compared to a non-incremental recursion) allows rsync to then set the
modify time of the finished directory right away (without having to delay
that until a bunch of recursive copying has finished). However, these
early directories don't yet have their completed mode, mtime, or ownership
set -- they have more restrictive rights until the subdirectory's copying
- actually begins. This early-creation idiom can be avoiding by using the
+ actually begins. This early-creation idiom can be avoided by using the
[`--omit-dir-times`](#opt) option.
Incremental recursion can be disabled using the
what (if any) suffix gets appended using the [`--backup-dir`](#opt) and
[`--suffix`](#opt) options.
- Note that if you don't specify [`--backup-dir`](#opt), (1) the
- [`--omit-dir-times`](#opt) option will be forced on, and (2) if
- [`--delete`](#opt) is also in effect (without [`--delete-excluded`](#opt)),
- rsync will add a "protect" filter-rule for the backup suffix to the end of
- all your existing excludes (e.g. `-f "P *~"`). This will prevent
- previously backed-up files from being deleted. Note that if you are
- supplying your own filter rules, you may need to manually insert your own
- exclude/protect rule somewhere higher up in the list so that it has a high
- enough priority to be effective (e.g., if your rules specify a trailing
- inclusion/exclusion of `*`, the auto-added rule would never be reached).
+ If you don't specify [`--backup-dir`](#opt):
+
+ 1. the [`--omit-dir-times`](#opt) option will be forced on
+ 2. the use of [`--delete`](#opt) (without [`--delete-excluded`](#opt)),
+ causes rsync to add a "protect" [filter-rule](#FILTER_RULES) for the
+ backup suffix to the end of all your existing filters that looks like
+ this: `-f "P *~"`. This rule prevents previously backed-up files from
+ being deleted.
+
+ Note that if you are supplying your own filter rules, you may need to
+ manually insert your own exclude/protect rule somewhere higher up in the
+ list so that it has a high enough priority to be effective (e.g. if your
+ rules specify a trailing inclusion/exclusion of `*`, the auto-added rule
+ would never be reached).
0. `--backup-dir=DIR`
directory where the destination has a file, the transfer would occur
regardless of the timestamps.
- 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.
+ This option is a [TRANSFER RULE](#TRANSFER_RULES), so don't expect any
+ exclude side effects.
A caution for those that choose to combine [`--inplace`](#opt) with
`--update`: an interrupted transfer will leave behind a partial file on the
receiving side that has a very recent modified time, so re-running the
- transfer will probably **not** continue the interrutped file. As such, it
+ transfer will probably **not** continue the interrupted file. As such, it
is usually best to avoid combining this with[ `--inplace`](#opt) unless you
- have implemented manual steps to handle any interrutped in-progress files.
+ have implemented manual steps to handle any interrupted in-progress files.
0. `--inplace`
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).
+ Create all missing path components of the destination path.
- 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:
+ By default, rsync allows only the final component of the destination path
+ to not exist, which is an attempt to help you to validate your destination
+ path. With this option, rsync creates all the missing destination-path
+ components, just as if `mkdir -p $DEST_PATH` had been run on the receiving
+ side.
- > rsync -ai --mkpath foo sub/dir/bar
+ When specifying a destination path, including a trailing slash ensures that
+ the whole path is treated as directory names to be created, even when the
+ file list has a single item. See the [COPYING TO A DIFFERENT NAME](#)
+ section for full details on how rsync decides if a final destination-path
+ component should be created as a directory or not.
- If you instead ran the following, it would have created file foo in the
- sub/dir/bar directory:
+ If you would like the newly-created destination dirs to match the dirs on
+ the sending side, you should be using [`--relative`](#opt) (`-R`) instead
+ of `--mkpath`. For instance, the following two commands result in the same
+ destination tree, but only the second command ensures that the
+ "some/extra/path" components match the dirs on the sending side:
- > rsync -ai --mkpath foo sub/dir/bar/
+ > rsync -ai --mkpath host:some/extra/path/*.c some/extra/path/
+ > rsync -aiR host:some/extra/path/*.c ./
0. `--links`, `-l`
transfer, the client is the sender, so specifying the option directly
unmunges symlinks while specifying it as a remote option munges symlinks.
- This option has no affect when sent to a daemon via [`--remote-option`](#opt)
+ This option has no effect when sent to a daemon via [`--remote-option`](#opt)
because the daemon configures whether it wants munged symlinks via its
"`munge symlinks`" parameter.
The `-D` option is equivalent to "[`--devices`](#opt)
[`--specials`](#opt)".
+0. `--copy-devices`
+
+ This tells rsync to treat a device on the sending side as a regular file,
+ allowing it to be copied to a normal destination file (or another device
+ if `--write-devices` was also specified).
+
+ This option is refused by default by an rsync daemon.
+
0. `--write-devices`
This tells rsync to treat a device on the receiving side as a regular file,
This option implies the [`--inplace`](#opt) option.
Be careful using this, as you should know what devices are present on the
- receiving side of the transfer, especially if running rsync as root.
+ receiving side of the transfer, especially when running rsync as root.
- This option is refused by an rsync daemon.
+ This option is refused by default by an rsync daemon.
0. `--times`, `-t`
This tells rsync to transfer modification times along with the files and
update them on the remote system. Note that if this option is not used,
the optimization that excludes files that have not been modified cannot be
- effective; in other words, a missing `-t` (or [`-a`](#opt--archive)) will
- cause the next transfer to behave as if it used [`--ignore-times`](#opt)
- (`-I`), causing all files to be updated (though rsync's delta-transfer
- algorithm will make the update fairly efficient if the files haven't
- actually changed, you're much better off using `-t`).
+ effective; in other words, a missing `-t` (or [`-a`](#opt)) will cause the
+ next transfer to behave as if it used [`--ignore-times`](#opt) (`-I`),
+ causing all files to be updated (though rsync's delta-transfer algorithm
+ will make the update fairly efficient if the files haven't actually
+ changed, you're much better off using `-t`).
+
+ A modern rsync that is using transfer protocol 30 or 31 conveys a modify
+ time using up to 8-bytes. If rsync is forced to speak an older protocol
+ (perhaps due to the remote rsync being older than 3.0.0) a modify time is
+ conveyed using 4-bytes. Prior to 3.2.7, these shorter values could convey
+ a date range of 13-Dec-1901 to 19-Jan-2038. Beginning with 3.2.7, these
+ 4-byte values now convey a date range of 1-Jan-1970 to 7-Feb-2106. If you
+ have files dated older than 1970, make sure your rsync executables are
+ upgraded so that the full range of dates can be conveyed.
0. `--atimes`, `-U`
This option is overridden by both [`--super`](#opt) and `--no-super`.
- See also the [`fake super`](./rsyncd.conf.5#fake_super) setting in the
+ See also the [`fake super`](rsyncd.conf.5#fake_super) setting in the
daemon's rsyncd.conf file.
0. `--sparse`, `-S`
source and destination are specified as local paths, but only if no
batch-writing option is in effect.
+0. `--no-whole-file`, `--no-W`
+
+ Disable whole-file updating when it is enabled by default for a local
+ transfer. This usually slows rsync down, but it can be useful if you are
+ trying to minimize the writes to the destination file (if combined with
+ [`--inplace`](#opt)) or for testing the checksum-based update algorithm.
+
+ See also the [`--whole-file`](#opt) option.
+
0. `--checksum-choice=STR`, `--cc=STR`
This option overrides the checksum algorithms. If one algorithm name is
- `xxh64` (aka `xxhash`)
- `md5`
- `md4`
+ - `sha1`
- `none`
Run `rsync --version` to see the default checksum list compiled into your
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.
+ [`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.
[`--ignore-existing`](#opt) option, no files will be updated (which can be
useful if all you want to do is delete extraneous files).
- 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.
+ This option is a [TRANSFER RULE](#TRANSFER_RULES), so don't expect any
+ exclude side effects.
0. `--ignore-existing`
destination (this does _not_ ignore existing directories, or nothing would
get done). See also [`--ignore-non-existing`](#opt).
- 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.
+ This option is a [TRANSFER RULE](#TRANSFER_RULES), so don't expect any
+ exclude side effects.
This option can be useful for those doing backups using the
[`--link-dest`](#opt) option when they need to continue a backup run that
When [`--info=skip2`](#opt) is used rsync will output "FILENAME exists
(INFO)" messages where the INFO indicates one of "type change", "sum
- change" (requires [`-c`](#opt--checksum)), "file change" (based on the
- quick check), "attr change", or "uptodate". Using [`--info=skip1`](#opt)
- (which is also implied by 2 [`-v`](#opt--verbose) options) outputs the
- exists message without the INFO suffix.
+ change" (requires [`-c`](#opt)), "file change" (based on the quick check),
+ "attr change", or "uptodate". Using [`--info=skip1`](#opt) (which is also
+ implied by 2 [`-v`](#opt) options) outputs the exists message without the
+ INFO suffix.
0. `--remove-source-files`
Starting with 3.1.0, rsync will skip the sender-side removal (and output an
error) if the file's size or modify time has not stayed unchanged.
+ Starting with 3.2.6, a local rsync copy will ensure that the sender does
+ not remove a file the receiver just verified, such as when the user
+ accidentally makes the source and destination directory the same path.
+
0. `--delete`
This tells rsync to delete extraneous files from the receiving side (ones
0. `--delete-excluded`
- In addition to deleting the files on the receiving side that are not on the
- sending side, this tells rsync to also delete any files on the receiving
- side that are excluded (see [`--exclude`](#opt)). See the [FILTER
- RULES](#) section for a way to make individual exclusions behave this way
- on the receiver, and for a way to protect files from `--delete-excluded`.
- See [`--delete`](#opt) (which is implied) for more details on
- file-deletion.
+ This option turns any unqualified exclude/include rules into server-side
+ rules that do not affect the receiver's deletions.
+
+ By default, an exclude or include has both a server-side effect (to "hide"
+ and "show" files when building the server's file list) and a receiver-side
+ effect (to "protect" and "risk" files when deletions are occurring). Any
+ rule that has no modifier to specify what sides it is executed on will be
+ instead treated as if it were a server-side rule only, avoiding any
+ "protect" effects of the rules.
+
+ A rule can still apply to both sides even with this option specified if the
+ rule is given both the sender & receiver modifier letters (e.g., `-f'-sr
+ foo'`). Receiver-side protect/risk rules can also be explicitly specified
+ to limit the deletions. This saves you from having to edit a bunch of
+ `-f'- foo'` rules into `-f'-s foo'` (aka `-f'H foo'`) rules (not to mention
+ the corresponding includes).
+
+ See the [FILTER RULES](#) section for more information. See
+ [`--delete`](#opt) (which is implied) for more details on deletion.
0. `--ignore-missing-args`
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.
+ This option is a [TRANSFER RULE](#TRANSFER_RULES), so don't expect any
+ exclude side effects.
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
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).
+ 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`
remote host. See the [USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL
CONNECTION](#) section above.
- Beginning with rsync 3.2.0, the RSYNC_PORT environment variable will be set
- when a daemon connection is being made via a remote-shell connection. It
- is set to 0 if the default daemon port is being assumed, or it is set to
- the value of the rsync port that was specified via either the
+ Beginning with rsync 3.2.0, the [`RSYNC_PORT`](#) environment variable will
+ be set when a daemon connection is being made via a remote-shell
+ connection. It is set to 0 if the default daemon port is being assumed, or
+ it is set to the value of the rsync port that was specified via either the
[`--port`](#opt) option or a non-empty port value in an `rsync://` URL.
This allows the script to discern if a non-default port is being requested,
allowing for things such as an SSL or stunnel helper script to connect to a
(Note that ssh users can alternately customize site-specific connect
options in their .ssh/config file.)
- You can also choose the remote shell program using the RSYNC_RSH
+ You can also choose the remote shell program using the [`RSYNC_RSH`](#)
environment variable, which accepts the same range of values as `-e`.
See also the [`--blocking-io`](#opt) option which is affected by this
0. `--exclude=PATTERN`
This option is a simplified form of the [`--filter`](#opt) option that
- defaults to an exclude rule and does not allow the full rule-parsing syntax
- of normal filter rules.
+ specifies an exclude rule and does not allow the full rule-parsing syntax
+ of normal filter rules. This is equivalent to specifying `-f'- PATTERN'`.
See the [FILTER RULES](#) section for detailed information on this option.
file are ignored, as are whole-line comments that start with '`;`' or '`#`'
(filename rules that contain those characters are unaffected).
+ If a line begins with "`- `" (dash, space) or "`+ `" (plus, space), then
+ the type of rule is being explicitly specified as an exclude or an include
+ (respectively). Any rules without such a prefix are taken to be an exclude.
+
+ If a line consists of just "`!`", then the current filter rules are cleared
+ before adding any further rules.
+
If _FILE_ is '`-`', the list will be read from standard input.
0. `--include=PATTERN`
This option is a simplified form of the [`--filter`](#opt) option that
- defaults to an include rule and does not allow the full rule-parsing syntax
- of normal filter rules.
+ specifies an include rule and does not allow the full rule-parsing syntax
+ of normal filter rules. This is equivalent to specifying `-f'+ PATTERN'`.
See the [FILTER RULES](#) section for detailed information on this option.
file are ignored, as are whole-line comments that start with '`;`' or '`#`'
(filename rules that contain those characters are unaffected).
+ If a line begins with "`- `" (dash, space) or "`+ `" (plus, space), then
+ the type of rule is being explicitly specified as an exclude or an include
+ (respectively). Any rules without such a prefix are taken to be an include.
+
+ If a line consists of just "`!`", then the current filter rules are cleared
+ before adding any further rules.
+
If _FILE_ is '`-`', the list will be read from standard input.
0. `--files-from=FILE`
[`--recursive`](#opt) (`-r`), so specify it explicitly, if you want it.
- These side-effects change the default state of rsync, so the position of
the `--files-from` option on the command-line has no bearing on how other
- options are parsed (e.g. [`-a`](#opt--archive) works the same before or
- after `--files-from`, as does `--no-R` and all other options).
+ options are parsed (e.g. [`-a`](#opt) works the same before or after
+ `--files-from`, as does `--no-R` and all other options).
The filenames that are read from the FILE are all relative to the source
dir -- any leading slashes are removed and no ".." references are allowed
contains "bin/" (note the trailing slash), the immediate contents of the
directory would also be sent (without needing to be explicitly mentioned in
the file -- this began in version 2.6.4). In both cases, if the
- [`-r`](#opt--recursive) option was enabled, that dir's entire hierarchy
- would also be transferred (keep in mind that [`-r`](#opt--recursive) needs
- to be specified explicitly with `--files-from`, since it is not implied by
- [`-a`](#opt--archive). Also note that the effect of the (enabled by
- default) [`-r`](#opt--relative) option is to duplicate only the path info
- that is read from the file -- it does not force the duplication of the
- source-spec path (/usr in this case).
+ [`-r`](#opt) option was enabled, that dir's entire hierarchy would also be
+ transferred (keep in mind that [`-r`](#opt) needs to be specified
+ explicitly with `--files-from`, since it is not implied by [`-a`](#opt).
+ Also note that the effect of the (enabled by default) [`-r`](#opt) option
+ is to duplicate only the path info that is read from the file -- it does
+ not force the duplication of the source-spec path (/usr in this case).
In addition, the `--files-from` file can be read from the remote host
instead of the local host if you specify a "host:" in front of the file
This would copy all the files specified in the /path/file-list file that
was located on the remote "src" host.
- If the [`--iconv`](#opt) and [`--protect-args`](#opt) options are specified
+ If the [`--iconv`](#opt) and [`--secluded-args`](#opt) options are specified
and the `--files-from` filenames are being sent from one host to another,
the filenames will be translated from the sending host's charset to the
receiving host's charset.
0. `--old-args`
- This option tells rsync to stop trying to protect the arg values from
- unintended word-splitting or other misinterpretation by using its new
- backslash-escape idiom. The newest default is for remote filenames to only
- allow wildcards characters to be interpretated by the shell while
- protecting other shell-interpreted characters (and the args of options get
- even wildcards escaped). The only active wildcard characters on the remote
- side are: `*`, `?`, `[`, & `]`.
+ This option tells rsync to stop trying to protect the arg values on the
+ remote side from unintended word-splitting or other misinterpretation.
+ It also allows the client to treat an empty arg as a "." instead of
+ generating an error.
- If you have a script that wants to use old-style arg splitting in the
+ The default in a modern rsync is for "shell-active" characters (including
+ spaces) to be backslash-escaped in the args that are sent to the remote
+ shell. The wildcard characters `*`, `?`, `[`, & `]` are not escaped in
+ filename args (allowing them to expand into multiple filenames) while being
+ protected in option args, such as [`--usermap`](#opt).
+
+ If you have a script that wants to use old-style arg splitting in its
filenames, specify this option once. If the remote shell has a problem
- with any backslash escapes, specify the option twice.
+ with any backslash escapes at all, specify this option twice.
- You may also control this setting via the RSYNC_OLD_ARGS environment
+ You may also control this setting via the [`RSYNC_OLD_ARGS`](#) environment
variable. If it has the value "1", rsync will default to a single-option
setting. If it has the value "2" (or more), rsync will default to a
repeated-option setting. If it is "0", you'll get the default escaping
behavior. The environment is always overridden by manually specified
positive or negative options (the negative is `--no-old-args`).
-0. `--protect-args`, `-s`
+ Note that this option also disables the extra safety check added in 3.2.5
+ that ensures that a remote sender isn't including extra top-level items in
+ the file-list that you didn't request. This side-effect is necessary
+ because we can't know for sure what names to expect when the remote shell
+ is interpreting the args.
+
+ This option conflicts with the [`--secluded-args`](#opt) option.
+
+0. `--secluded-args`, `-s`
+
+ This option sends all filenames and most options to the remote rsync via
+ the protocol (not the remote shell command line) which avoids letting the
+ remote shell modify them. Wildcards are expanded on the remote host by
+ rsync instead of a shell.
+
+ This is similar to the default backslash-escaping of args that was added
+ in 3.2.4 (see [`--old-args`](#opt)) in that it prevents things like space
+ splitting and unwanted special-character side-effects. However, it has the
+ drawbacks of being incompatible with older rsync versions (prior to 3.0.0)
+ and of being refused by restricted shells that want to be able to inspect
+ all the option values for safety.
+
+ This option is useful for those times that you need the argument's
+ character set to be converted for the remote host, if the remote shell is
+ incompatible with the default backslash-escpaing method, or there is some
+ other reason that you want the majority of the options and arguments to
+ bypass the command-line of the remote shell.
+
+ If you combine this option with [`--iconv`](#opt), the args related to the
+ remote side will be translated from the local to the remote character-set.
+ The translation happens before wild-cards are expanded. See also the
+ [`--files-from`](#opt) option.
+
+ You may also control this setting via the [`RSYNC_PROTECT_ARGS`](#)
+ environment variable. If it has a non-zero value, this setting will be
+ enabled by default, otherwise it will be disabled by default. Either state
+ is overridden by a manually specified positive or negative version of this
+ option (note that `--no-s` and `--no-secluded-args` are the negative
+ versions). This environment variable is also superseded by a non-zero
+ [`RSYNC_OLD_ARGS`](#) export.
+
+ This option conflicts with the [`--old-args`](#opt) option.
- This option sends all filenames and most options to the remote rsync
- without allowing the remote shell to interpret them. Wildcards are
- expanded on the remote host by rsync instead of the shell doing it.
+ This option used to be called `--protect-args` (before 3.2.6) and that
+ older name can still be used (though specifying it as `-s` is always the
+ easiest and most compatible choice).
- This is similar to the new-style backslash-escaping of args that was added
- in 3.2.4, but supports some extra features and doesn't rely on backslash
- escaping in the remote shell.
+0. `--trust-sender`
- If you use this option with [`--iconv`](#opt), the args related to the
- remote side will also be translated from the local to the remote
- character-set. The translation happens before wild-cards are expanded.
- See also the [`--files-from`](#opt) option.
+ This option disables two extra validation checks that a local client
+ performs on the file list generated by a remote sender. This option should
+ only be used if you trust the sender to not put something malicious in the
+ file list (something that could possibly be done via a modified rsync, a
+ modified shell, or some other similar manipulation).
- You may also control this setting via the RSYNC_PROTECT_ARGS environment
- variable. If it has a non-zero value, this setting will be
- enabled by default, otherwise it will be disabled by default. Either state
- is overridden by a manually specified positive or negative version of this
- option (note that `--no-s` and `--no-protect-args` are the negative
- versions).
+ Normally, the rsync client (as of version 3.2.5) runs two extra validation
+ checks when pulling files from a remote rsync:
+
+ - It verifies that additional arg items didn't get added at the top of the
+ transfer.
+ - It verifies that none of the items in the file list are names that should
+ have been excluded (if filter rules were specified).
- You may need to disable this option when interacting with an older rsync
- (one prior to 3.0.0).
+ Note that various options can turn off one or both of these checks if the
+ option interferes with the validation. For instance:
- Note that this option is incompatible with the use of the restricted rsync
- script (`rrsync`) since it hides options from the script's inspection.
+ - Using a per-directory filter file reads filter rules that only the server
+ knows about, so the filter checking is disabled.
+ - Using the [`--old-args`](#opt) option allows the sender to manipulate the
+ requested args, so the arg checking is disabled.
+ - Reading the files-from list from the server side means that the client
+ doesn't know the arg list, so the arg checking is disabled.
+ - Using [`--read-batch`](#opt) disables both checks since the batch file's
+ contents will have been verified when it was created.
+
+ This option may help an under-powered client server if the extra pattern
+ matching is slowing things down on a huge transfer. It can also be used to
+ work around a currently-unknown bug in the verification logic for a transfer
+ from a trusted sender.
+
+ When using this option it is a good idea to specify a dedicated destination
+ directory, as discussed in the [MULTI-HOST SECURITY](#) section.
0. `--copy-as=USER[:GROUP]`
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
+ [`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.
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 [`use chroot`](./rsyncd.conf.5#use_chroot) setting
+ instead. See also the [`use chroot`](rsyncd.conf.5#use_chroot) setting
in the rsyncd.conf manpage for some comments 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.
[`--group`](#opt) (`-g`) option (since rsync needs to have those options
enabled for the mapping options to work).
- An older rsync client may need to use [`--protect-args`](#opt) (`-s`) to
- avoid a complaint about wildcard characters, but a modern rsync handles
- this automatically.
+ An older rsync client may need to use [`-s`](#opt) to avoid a complaint
+ about wildcard characters, but a modern rsync handles this automatically.
0. `--chown=USER:GROUP`
This option forces all files to be owned by USER with group GROUP. This is
- a simpler interface than using [`--usermap` & `--groupmap`](#opt--usermap)
+ a simpler interface than using [`--usermap`](#opt) & [`--groupmap`](#opt)
directly, but it is implemented using those options internally so they
cannot be mixed. If either the USER or GROUP is empty, no mapping for the
omitted user/group will occur. If GROUP is empty, the trailing colon may
"`--usermap=*:foo --groupmap=*:bar`", only easier (and with the same
implied [`--owner`](#opt) and/or [`--group`](#opt) options).
- An older rsync client may need to use [`--protect-args`](#opt) (`-s`) to
- avoid a complaint about wildcard characters, but a modern rsync handles
- this automatically.
+ An older rsync client may need to use [`-s`](#opt) to avoid a complaint
+ about wildcard characters, but a modern rsync handles this automatically.
0. `--timeout=SECONDS`
rsync daemon. The `--address` option allows you to specify a specific IP
address (or hostname) to bind to.
- See also [the daemon version of the `--address`
- option](#daemon-opt--address).
+ See also [the daemon version of the `--address` option](#dopt--address).
0. `--port=PORT`
to connect with an rsync daemon (since the URL syntax has a way to specify
the port as a part of the URL).
- See also [the daemon version of the `--port` option](#daemon-opt--port).
+ See also [the daemon version of the `--port` option](#dopt--port).
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
+ which may make transfers faster (or slower!). Read the manpage 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.
- See also [the daemon version of the `--sockopts`
- option](#daemon-opt--sockopts).
+ See also [the daemon version of the `--sockopts` option](#dopt--sockopts).
0. `--blocking-io`
user on a per-update basis. The format is a text string containing
embedded single-character escape sequences prefixed with a percent (%)
character. A default format of "%n%L" is assumed if either
- [`--info=name`](#opt) or [`-v`](#opt--verbose) 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`](./rsyncd.conf.5#log_format) setting in the rsyncd.conf
- manpage.
+ [`--info=name`](#opt) or [`-v`](#opt) 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`](rsyncd.conf.5#log_format) setting in the rsyncd.conf manpage.
Specifying the `--out-format` option implies the [`--info=name`](#opt)
option, which will mention each file, dir, etc. that gets updated in a
of "%i %n%L". See the [`--log-file-format`](#opt) option if you wish to
override this.
- Here's a example command that requests the remote side to log what is
+ Here's an example command that requests the remote side to log what is
happening:
> rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/
This is very useful if you need to debug why a connection is closing
unexpectedly.
- See also [the daemon version of the `--log-file`
- option](#daemon-opt--log-file).
+ See also [the daemon version of the `--log-file` option](#dopt--log-file).
0. `--log-file-format=FORMAT`
file specified by the [`--log-file`](#opt) 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`](./rsyncd.conf.5#log_format)
+ the possible escape characters, see the [`log format`](rsyncd.conf.5#log_format)
setting in the rsyncd.conf manpage.
The default FORMAT used if [`--log-file`](#opt) is specified and this
option is not is '%i %n%L'.
See also [the daemon version of the `--log-file-format`
- option](#daemon-opt--log-file-format).
+ option](#dopt--log-file-format).
0. `--stats`
This tells rsync to print a verbose set of statistics on the file transfer,
allowing you to tell how effective rsync's delta-transfer algorithm is for
your data. This option is equivalent to [`--info=stats2`](#opt) if
- combined with 0 or 1 [`-v`](#opt--verbose) options, or
- [`--info=stats3`](#opt) if combined with 2 or more [`-v`](#opt--verbose)
- options.
+ combined with 0 or 1 [`-v`](#opt) options, or [`--info=stats3`](#opt) if
+ combined with 2 or more [`-v`](#opt) options.
The current statistics are as follows:
0. `--human-readable`, `-h`
- Output numbers in a more human-readable format. There are 3 possible
- levels: (1) output numbers with a separator between each set of 3 digits
- (either a comma or a period, depending on if the decimal point is
- represented by a period or a comma); (2) output numbers in units of 1000
- (with a character suffix for larger units -- see below); (3) output
- numbers in units of 1024.
+ Output numbers in a more human-readable format. There are 3 possible levels:
+
+ 1. output numbers with a separator between each set of 3 digits (either a
+ comma or a period, depending on if the decimal point is represented by a
+ period or a comma).
+ 2. output numbers in units of 1000 (with a character suffix for larger
+ units -- see below).
+ 3. output numbers in units of 1024.
The default is human-readable level 1. Each `-h` option increases the
level by one. You can take the level down to 0 (to output numbers as pure
0. `--partial-dir=DIR`
- A better way to keep partial files than the [`--partial`](#opt) option is
- to specify a _DIR_ that will be used to hold the partial data (instead of
- writing it out to the destination file). On the next transfer, rsync will
- use a file found in this dir as data to speed up the resumption of the
+ This option modifies the behavior of the [`--partial`](#opt) option while
+ also implying that it be enabled. This enhanced partial-file method puts
+ any partially transferred files into the specified _DIR_ instead of writing
+ the partial file out to the destination file. On the next transfer, rsync
+ will use a file found in this dir as data to speed up the resumption of the
transfer and then delete it after it has served its purpose.
Note that if [`--whole-file`](#opt) is specified (or implied), any
- partial-dir file that is found for a file that is being updated will simply
- be removed (since rsync is sending files without using rsync's
+ partial-dir files that are found for a file that is being updated will
+ simply be removed (since rsync is sending files without using rsync's
delta-transfer algorithm).
- Rsync will create the _DIR_ if it is missing (just the last dir -- not the
- whole path). This makes it easy to use a relative path (such as
+ Rsync will create the _DIR_ if it is missing, but just the last dir -- not
+ the whole path. This makes it easy to use a relative path (such as
"`--partial-dir=.rsync-partial`") to have rsync create the
- partial-directory in the destination file's directory when needed, and then
- remove it again when the partial file is deleted. Note that the directory
- is only removed if it is a relative pathname, as it is expected that an
- absolute path is to a directory that is reserved for partial-dir work.
+ partial-directory in the destination file's directory when it is needed,
+ and then remove it again when the partial file is deleted. Note that this
+ directory removal is only done for a relative pathname, as it is expected
+ that an absolute path is to a directory that is reserved for partial-dir
+ work.
If the partial-dir value is not an absolute path, rsync will add an exclude
rule at the end of all your existing excludes. This will prevent the
sending of any partial-dir files that may exist on the sending side, and
will also prevent the untimely deletion of partial-dir items on the
receiving side. An example: the above `--partial-dir` option would add the
- equivalent of "`-f '-p .rsync-partial/'`" at the end of any other filter
- rules.
+ equivalent of this "perishable" exclude at the end of any other filter
+ rules: `-f '-p .rsync-partial/'`
If you are supplying your own exclude rules, you may need to add your own
- exclude/hide/protect rule for the partial-dir because (1) the auto-added
- 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`](#opt) and add a "risk" filter rule, e.g.
- `-f 'R .rsync-partial/'`. (Avoid using [`--delete-before`](#opt) or
- [`--delete-during`](#opt) unless you don't need rsync to use any of the
- left-over partial-dir data during the current run.)
+ exclude/hide/protect rule for the partial-dir because:
+
+ 1. the auto-added 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`](#opt) and
+ add a "risk" filter rule, e.g. `-f 'R .rsync-partial/'`. Avoid using
+ [`--delete-before`](#opt) or [`--delete-during`](#opt) 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".
+ is a security risk! E.g. AVOID "/tmp"!
- You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
- variable. Setting this in the environment does not force
+ You can also set the partial-dir value the [`RSYNC_PARTIAL_DIR`](#)
+ environment variable. Setting this in the environment does not force
[`--partial`](#opt) to be enabled, but rather it affects where partial
files go when [`--partial`](#opt) is specified. For instance, instead of
using `--partial-dir=.rsync-tmp` along with [`--progress`](#opt), you could
- set RSYNC_PARTIAL_DIR=.rsync-tmp in your environment and then just use the
- [`-P`](#opt) option to turn on the use of the .rsync-tmp dir for partial
- transfers. The only times that the [`--partial`](#opt) option does not
- look for this environment value are (1) when [`--inplace`](#opt) was
- specified (since [`--inplace`](#opt) conflicts with `--partial-dir`), and
- (2) when [`--delay-updates`](#opt) was specified (see below).
+ set [`RSYNC_PARTIAL_DIR=.rsync-tmp`](#) in your environment and then use
+ the [`-P`](#opt) option to turn on the use of the .rsync-tmp dir for
+ partial transfers. The only times that the [`--partial`](#opt) option does
+ not look for this environment value are:
+
+ 1. when [`--inplace`](#opt) was specified (since [`--inplace`](#opt)
+ conflicts with `--partial-dir`), and
+ 2. when [`--delay-updates`](#opt) was specified (see below).
When a modern rsync resumes the transfer of a file in the partial-dir, that
partial file is now updated in-place instead of creating yet another
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
- should not use an absolute path to [`--partial-dir`](#opt) unless (1) there
- is no chance of any of the files in the transfer having the same name
- (since all the updated files will be put into a single directory if the
- path is absolute) and (2) there are no mount points in the hierarchy (since
- the delayed updates will fail if they can't be renamed into place).
+ should not use an absolute path to [`--partial-dir`](#opt) unless:
+
+ 1. there is no chance of any of the files in the transfer having the same
+ name (since all the updated files will be put into a single directory if
+ the path is absolute), and
+ 2. there are no mount points in the hierarchy (since the delayed updates
+ will fail if they can't be renamed into place).
See also the "atomic-rsync" python script in the "support" subdir for an
update algorithm that is even more atomic (it uses [`--link-dest`](#opt)
directories when the sending rsync is recursively scanning a hierarchy of
files using include/exclude/filter rules.
- Note that the use of transfer rules, such as the [`--min-size`](#opt)
- option, does not affect what goes into the file list, and thus does not
- leave directories empty, even if none of the files in a directory match the
- transfer rule.
+ This option can still leave empty directories on the receiving side if you
+ make use of [TRANSFER_RULES](#).
Because the file-list is actually being pruned, this option also affects
what directories get deleted when a delete is active. However, keep in
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
- no destination specified, so its main uses are: (1) to turn a copy command
- that includes a destination arg into a file-listing command, or (2) to be
- able to specify more than one source arg (note: be sure to include the
- destination). Caution: keep in mind that a source arg with a wild-card is
- expanded by the shell into multiple args, so it is never safe to try to
- list such an arg without using this option. For example:
+ no destination specified, so its main uses are:
+
+ 1. to turn a copy command that includes a destination arg into a
+ file-listing command, or
+ 2. to be able to specify more than one source arg. Note: be sure to
+ include the destination.
+
+ CAUTION: keep in mind that a source arg with a wild-card is expanded by the
+ shell into multiple args, so it is never safe to try to specify a single
+ wild-card arg to try to infer this option. A safe example is:
> rsync -av --list-only foo* dest/
- Starting with rsync 3.1.0, the sizes output by `--list-only` are affected
- by the [`--human-readable`](#opt) option. By default they will contain
- digit separators, but higher levels of readability will output the sizes
- with unit suffixes. Note also that the column width for the size output
- has increased from 11 to 14 characters for all human-readable levels. Use
- `--no-h` if you want just digits in the sizes, and the old column width of
- 11 characters.
+ This option always uses an output format that looks similar to this:
+
+ > drwxrwxr-x 4,096 2022/09/30 12:53:11 support
+ > -rw-rw-r-- 80 2005/01/11 10:37:37 support/Makefile
+
+ The only option that affects this output style is (as of 3.1.0) the
+ [`--human-readable`](#opt) (`-h`) option. The default is to output sizes
+ as byte counts with digit separators (in a 14-character-width column).
+ Specifying at least one `-h` option makes the sizes output with unit
+ suffixes. If you want old-style bytecount sizes without digit separators
+ (and an 11-character-width column) use `--no-h`.
Compatibility note: when requesting a remote listing of files from an rsync
that is version 2.6.3 or older, you may encounter an error if you ask for a
quickly 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.
- See also [the daemon version of the `--bwlimit`
- option](#daemon-opt--bwlimit).
+ See also [the daemon version of the `--bwlimit` option](#dopt--bwlimit).
-0. `--stop-after=MINS`
+0. `--stop-after=MINS`, (`--time-limit=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`](#opt) (`-M`), should the need arise.
+ The `--time-limit` version of this option is deprecated.
+
0. `--stop-at=y-m-dTh:m`
This option tells rsync to stop copying when the specified point in time
This order ensures that the option will stay the same whether you're
pushing or pulling files. Finally, you can specify either `--no-iconv` or
a CONVERT_SPEC of "-" to turn off any conversion. The default setting of
- this option is site-specific, and can also be affected via the RSYNC_ICONV
- environment variable.
+ this option is site-specific, and can also be affected via the
+ [`RSYNC_ICONV`](#) environment variable.
For a list of what charset names your local iconv library supports, you can
run "`iconv --list`".
- If you specify the [`--protect-args`](#opt) (`-s`) option, rsync will
+ If you specify the [`--secluded-args`](#opt) (`-s`) option, rsync will
translate the filenames you specify on the command-line that are being sent
to the remote host. See also the [`--files-from`](#opt) option.
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
+ the "`--rsh SHELL -4`" option directly (or whatever IPv4/IPv6 hint options
it uses).
- See also [the daemon version of these options](#daemon-opt--ipv4).
+ See also [the daemon version of these options](#dopt--ipv4).
If rsync was compiled without support for IPv6, the `--ipv6` option will
have no effect. The `rsync --version` output will contain "`no IPv6`" if
background daemon. The daemon will read the config file (rsyncd.conf) on
each connect made by a client and respond to requests accordingly.
- See the [**rsyncd.conf**(5)](./rsyncd.conf.5) man page for more details.
+ See the [**rsyncd.conf**(5)](rsyncd.conf.5) manpage for more details.
0. `--address=ADDRESS`
specific IP address (or hostname) to bind to. This makes virtual hosting
possible in conjunction with the `--config` option.
- See also the [address](./rsyncd.conf.5#address) global option in the
+ See also the [address](rsyncd.conf.5#address) global option in the
rsyncd.conf manpage and the [client version of the `--address`
option](#opt--address).
0. `--config=FILE`
This specifies an alternate config file than the default. This is only
- relevant when [`--daemon`](#daemon-opt) is specified. The default is
+ relevant when [`--daemon`](#dopt) is specified. The default is
/etc/rsyncd.conf unless the daemon is running over a remote shell program
and the remote user is not the super-user; in that case the default is
rsyncd.conf in the current directory (typically $HOME).
rather than the default of 873.
See also [the client version of the `--port` option](#opt--port) and the
- [port](./rsyncd.conf.5#port) global setting in the rsyncd.conf manpage.
+ [port](rsyncd.conf.5#port) global setting in the rsyncd.conf manpage.
0. `--log-file=FILE`
0. `--sockopts`
- This overrides the [`socket options`](./rsyncd.conf.5#socket_options)
+ This overrides the [`socket options`](rsyncd.conf.5#socket_options)
setting in the rsyncd.conf file and has the same syntax.
See also [the client version of the `--sockopts` option](#opt--sockopts).
## FILTER RULES
-The filter rules allow for flexible selection of which files to transfer
-(include) and which files to skip (exclude). The rules either directly specify
-include/exclude patterns or they specify a way to acquire more include/exclude
-patterns (e.g. to read them from a file).
-
-As the list of files/directories to transfer is built, rsync checks each name
-to be transferred against the list of include/exclude patterns in turn, and the
-first matching pattern is acted on: if it is an exclude pattern, then that file
-is skipped; if it is an include pattern then that filename is not skipped; if
-no matching pattern is found, then the filename is not skipped.
-
-Rsync builds an ordered list of filter rules as specified on the command-line.
-Filter rules have the following syntax:
+The filter rules allow for custom control of several aspects of how files are
+handled:
+
+- Control which files the sending side puts into the file list that describes
+ the transfer hierarchy
+- Control which files the receiving side protects from deletion when the file
+ is not in the sender's file list
+- Control which extended attribute names are skipped when copying xattrs
+
+The rules are either directly specified via option arguments or they can be
+read in from one or more files. The filter-rule files can even be a part of
+the hierarchy of files being copied, affecting different parts of the tree in
+different ways.
+
+### SIMPLE INCLUDE/EXCLUDE RULES
+
+We will first cover the basics of how include & exclude rules affect what files
+are transferred, ignoring any deletion side-effects. Filter rules mainly
+affect the contents of directories that rsync is "recursing" into, but they can
+also affect a top-level item in the transfer that was specified as a argument.
+
+The default for any unmatched file/dir is for it to be included in the
+transfer, which puts the file/dir into the sender's file list. The use of an
+exclude rule causes one or more matching files/dirs to be left out of the
+sender's file list. An include rule can be used to limit the effect of an
+exclude rule that is matching too many files.
+
+The order of the rules is important because the first rule that matches is the
+one that takes effect. Thus, if an early rule excludes a file, no include rule
+that comes after it can have any effect. This means that you must place any
+include overrides somewhere prior to the exclude that it is intended to limit.
+
+When a directory is excluded, all its contents and sub-contents are also
+excluded. The sender doesn't scan through any of it at all, which can save a
+lot of time when skipping large unneeded sub-trees.
+
+It is also important to understand that the include/exclude rules are applied
+to every file and directory that the sender is recursing into. Thus, if you
+want a particular deep file to be included, you have to make sure that none of
+the directories that must be traversed on the way down to that file are
+excluded or else the file will never be discovered to be included. As an
+example, if the directory "`a/path`" was given as a transfer argument and you
+want to ensure that the file "`a/path/down/deep/wanted.txt`" is a part of the
+transfer, then the sender must not exclude the directories "`a/path`",
+"`a/path/down`", or "`a/path/down/deep`" as it makes it way scanning through
+the file tree.
+
+When you are working on the rules, it can be helpful to ask rsync to tell you
+what is being excluded/included and why. Specifying `--debug=FILTER` or (when
+pulling files) `-M--debug=FILTER` turns on level 1 of the FILTER debug
+information that will output a message any time that a file or directory is
+included or excluded and which rule it matched. Beginning in 3.2.4 it will
+also warn if a filter rule has trailing whitespace, since an exclude of "foo "
+(with a trailing space) will not exclude a file named "foo".
+
+Exclude and include rules can specify wildcard [PATTERN MATCHING RULES](#)
+(similar to shell wildcards) that allow you to match things like a file suffix
+or a portion of a filename.
+
+A rule can be limited to only affecting a directory by putting a trailing slash
+onto the filename.
+
+### SIMPLE INCLUDE/EXCLUDE EXAMPLE
+
+With the following file tree created on the sending side:
+
+> mkdir x/
+> touch x/file.txt
+> mkdir x/y/
+> touch x/y/file.txt
+> touch x/y/zzz.txt
+> mkdir x/z/
+> touch x/z/file.txt
+
+Then the following rsync command will transfer the file "`x/y/file.txt`" and
+the directories needed to hold it, resulting in the path "`/tmp/x/y/file.txt`"
+existing on the remote host:
+
+> rsync -ai -f'+ x/' -f'+ x/y/' -f'+ x/y/file.txt' -f'- *' x host:/tmp/
+
+Aside: this copy could also have been accomplished using the [`-R`](#opt)
+option (though the 2 commands behave differently if deletions are enabled):
+
+> rsync -aiR x/y/file.txt host:/tmp/
+
+The following command does not need an include of the "x" directory because it
+is not a part of the transfer (note the traililng slash). Running this command
+would copy just "`/tmp/x/file.txt`" because the "y" and "z" dirs get excluded:
+
+> rsync -ai -f'+ file.txt' -f'- *' x/ host:/tmp/x/
+
+This command would omit the zzz.txt file while copying "x" and everything else
+it contains:
+
+> rsync -ai -f'- zzz.txt' x host:/tmp/
+
+### FILTER RULES WHEN DELETING
+
+By default the include & exclude filter rules affect both the sender
+(as it creates its file list)
+and the receiver (as it creates its file lists for calculating deletions). If
+no delete option is in effect, the receiver skips creating the delete-related
+file lists. This two-sided default can be manually overridden so that you are
+only specifying sender rules or receiver rules, as described in the [FILTER
+RULES IN DEPTH](#) section.
+
+When deleting, an exclude protects a file from being removed on the receiving
+side while an include overrides that protection (putting the file at risk of
+deletion). The default is for a file to be at risk -- its safety depends on it
+matching a corresponding file from the sender.
+
+An example of the two-sided exclude effect can be illustrated by the copying of
+a C development directory between 2 systems. When doing a touch-up copy, you
+might want to skip copying the built executable and the `.o` files (sender
+hide) so that the receiving side can build their own and not lose any object
+files that are already correct (receiver protect). For instance:
+
+> rsync -ai --del -f'- *.o' -f'- cmd' src host:/dest/
+
+Note that using `-f'-p *.o'` is even better than `-f'- *.o'` if there is a
+chance that the directory structure may have changed. The "p" modifier is
+discussed in [FILTER RULE MODIFIERS](#).
+
+One final note, if your shell doesn't mind unexpanded wildcards, you could
+simplify the typing of the filter options by using an underscore in place of
+the space and leaving off the quotes. For instance, `-f -_*.o -f -_cmd` (and
+similar) could be used instead of the filter options above.
+
+### FILTER RULES IN DEPTH
+
+Rsync supports old-style include/exclude rules and new-style filter rules. The
+older rules are specified using [`--include`](#opt) and [`--exclude`](#opt) as
+well as the [`--include-from`](#opt) and [`--exclude-from`](#opt). These are
+limited in behavior but they don't require a "-" or "+" prefix. An old-style
+exclude rule is turned into a "`- name`" filter rule (with no modifiers) and an
+old-style include rule is turned into a "`+ name`" filter rule (with no
+modifiers).
+
+Rsync builds an ordered list of filter rules as specified on the command-line
+and/or read-in from files. New style filter rules have the following syntax:
> RULE [PATTERN_OR_FILENAME]
> RULE,MODIFIERS [PATTERN_OR_FILENAME]
You have your choice of using either short or long RULE names, as described
below. If you use a short-named rule, the ',' separating the RULE from the
MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
-must come after either a single space or an underscore (\_). Here are the
-available rule prefixes:
-
-0. `exclude, '-'` specifies an exclude pattern.
-0. `include, '+'` specifies an include pattern.
-0. `merge, '.'` specifies a merge-file to read for more rules.
-0. `dir-merge, ':'` specifies a per-directory merge-file.
+must come after either a single space or an underscore (\_). Any additional
+spaces and/or underscores are considered to be a part of the pattern name.
+Here are the available rule prefixes:
+
+0. `exclude, '-'` specifies an exclude pattern that (by default) is both a
+ `hide` and a `protect`.
+0. `include, '+'` specifies an include pattern that (by default) is both a
+ `show` and a `risk`.
+0. `merge, '.'` specifies a merge-file on the client side to read for more
+ rules.
+0. `dir-merge, ':'` specifies a per-directory merge-file. Using this kind of
+ filter rule requires that you trust the sending side's filter checking, so
+ it has the side-effect mentioned under the [`--trust-sender`](#opt) option.
0. `hide, 'H'` specifies a pattern for hiding files from the transfer.
-0. `show, 'S'` files that match the pattern are not hidden.
+ Equivalent to a sender-only exclude, so `-f'H foo'` could also be specified
+ as `-f'-s foo'`.
+0. `show, 'S'` files that match the pattern are not hidden. Equivalent to a
+ sender-only include, so `-f'S foo'` could also be specified as `-f'+s
+ foo'`.
0. `protect, 'P'` specifies a pattern for protecting files from deletion.
-0. `risk, 'R'` files that match the pattern are not protected.
+ Equivalent to a receiver-only exclude, so `-f'P foo'` could also be
+ specified as `-f'-r foo'`.
+0. `risk, 'R'` files that match the pattern are not protected. Equivalent to a
+ receiver-only include, so `-f'R foo'` could also be specified as `-f'+r
+ foo'`.
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
-whole-line comments that start with a '`#`' (filename rules that contain a hash
-are unaffected).
-
-[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`](#opt) & [`--exclude`](#opt) 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`](#opt)
-option, on the other hand, must always contain either a short or long rule name
-at the start of the rule.
+When rules are being read from a file (using merge or dir-merge), empty lines
+are ignored, as are whole-line comments that start with a '`#`' (filename rules
+that contain a hash character are unaffected).
Note also that the [`--filter`](#opt), [`--include`](#opt), and
[`--exclude`](#opt) options take one rule/pattern each. To add multiple ones,
the [`--filter`](#opt) option, or the [`--include-from`](#opt) /
[`--exclude-from`](#opt) options.
-## INCLUDE/EXCLUDE PATTERN RULES
-
-You can include and exclude files by specifying patterns using the "+", "-",
-etc. filter rules (as introduced in the [FILTER RULES](#) section above). The
-include/exclude rules each specify a pattern that is matched against the names
-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
- 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
- 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
- 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
- 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:]]`.
-- 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
- 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 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.)
-- a trailing "`dir_name/***`" will match both the directory (as if "dir_name/"
+### PATTERN MATCHING RULES
+
+Most of the rules mentioned above take an argument that specifies what the rule
+should match. If rsync is recursing through a directory hierarchy, keep in
+mind that each pattern is matched against the name of every directory in the
+descent path as rsync finds the filenames to send.
+
+The matching rules for the pattern argument take several forms:
+
+- If a pattern contains a `/` (not counting a trailing slash) or a "`**`"
+ (which can match a slash), then the pattern is matched against the full
+ pathname, including any leading directories within the transfer. If the
+ pattern doesn't contain a (non-trailing) `/` or a "`**`", then it is matched
+ only against the final component of the filename or pathname. For example,
+ `foo` means that the final path component must be "foo" while `foo/bar` would
+ match the last 2 elements of the path (as long as both elements are within
+ the transfer).
+- A pattern that ends with a `/` only matches a directory, not a regular file,
+ symlink, or device.
+- A pattern that starts with a `/` is anchored to the start of the transfer
+ path instead of the end. For example, `/foo/**` or `/foo/bar/**` match only
+ leading elements in the path. If the rule is read from a per-directory
+ filter file, the transfer path being matched will begin at the level of the
+ filter file instead of the top of the transfer. 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.
+
+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 single character except a slash (`/`).
+- a '`*`' matches zero or more non-slash characters.
+- a '`**`' matches zero or more characters, including slashes.
+- a '`[`' introduces a character class, such as `[a-z]` or `[[:alpha:]]`, that
+ must match one character.
+- a trailing `***` in the pattern is a shorthand that allows you to match a
+ directory and all its contents using a single rule. For example, specifying
+ "`dir_name/***`" will match both the "dir_name" directory (as if "`dir_name/`"
had been specified) and everything in the directory (as if "`dir_name/**`"
- had been specified). This behavior was added in version 2.6.7.
-
-Note that, when using the [`--recursive`](#opt) (`-r`) option (which is implied
-by [`-a`](#opt--archive)), every subdir component of every path is visited left
-to right, with each directory having a chance for exclusion before its content.
-In this way include/exclude patterns are applied recursively to the pathname of
-each node 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`"
-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
-something it never sees in the cut-off section of the directory hierarchy).
-
-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
-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
-perhaps use the [`--prune-empty-dirs`](#opt) option. Another solution is to add
-specific include rules for all the parent dirs that need to be visited. For
-instance, this set of rules works fine:
-
-> + /some/
-> + /some/path/
-> + /some/path/this-file-is-found
-> + /file-also-included
-> - *
+ had been specified).
+- a backslash can be used to escape a wildcard character, but it is only
+ interpreted as an escape character if at least one wildcard character is
+ present in the match pattern. For instance, the pattern "`foo\bar`" matches
+ that single backslash literally, while the pattern "`foo\bar*`" would need to
+ be changed to "`foo\\bar*`" to avoid the "`\b`" becoming just "b".
Here are some examples of exclude/include matching:
-- "`- *.o`" would exclude all names matching `*.o`
-- "`- /foo`" would exclude a file (or directory) named foo in the transfer-root
- directory
-- "`- foo/`" would exclude any directory named foo
-- "`- /foo/*/bar`" would exclude any file named bar which is at two levels
- below a directory named foo in the transfer-root directory
-- "`- /foo/**/bar`" would exclude any file named bar two or more levels below a
- directory named foo in the transfer-root directory
-- The combination of "`+ */`", "`+ *.c`", and "`- *`" would include all
- directories and C source files but nothing else (see also the
- [`--prune-empty-dirs`](#opt) option)
-- The combination of "`+ foo/`", "`+ foo/bar.c`", and "`- *`" would include
- only the foo directory and foo/bar.c (the foo directory must be explicitly
- included or it would be excluded by the "`*`")
-
-The following modifiers are accepted after a "`+`" or "`-`":
+- Option `-f'- *.o'` would exclude all filenames ending with `.o`
+- Option `-f'- /foo'` would exclude a file (or directory) named foo in the
+ transfer-root directory
+- Option `-f'- foo/'` would exclude any directory named foo
+- Option `-f'- foo/*/bar'` would exclude any file/dir named bar which is at two
+ levels below a directory named foo (if foo is in the transfer)
+- Option `-f'- /foo/**/bar'` would exclude any file/dir named bar that was two
+ or more levels below a top-level directory named foo (note that /foo/bar is
+ **not** excluded by this)
+- Options `-f'+ */' -f'+ *.c' -f'- *'` would include all directories and .c
+ source files but nothing else
+- Options `-f'+ foo/' -f'+ foo/bar.c' -f'- *'` would include only the foo
+ directory and foo/bar.c (the foo directory must be explicitly included or it
+ would be excluded by the "`- *`")
+
+### FILTER RULE MODIFIERS
+
+The following modifiers are accepted after an include (+) or exclude (-) rule:
- A `/` specifies that the include/exclude rule should be matched against the
- absolute pathname of the current item. For example, "`-/ /etc/passwd`" would
- exclude the passwd file any time the transfer was sending files from the
- "/etc" directory, and "-/ subdir/foo" would always exclude "foo" when it is
- in a dir named "subdir", even if "foo" is at the root of the current
+ absolute pathname of the current item. For example, `-f'-/ /etc/passwd'`
+ would exclude the passwd file any time the transfer was sending files from
+ the "/etc" directory, and "-/ subdir/foo" would always exclude "foo" when it
+ is in a dir named "subdir", even if "foo" is at the root of the current
transfer.
- A `!` specifies that the include/exclude should take effect if the pattern
- fails to match. For instance, "`-! */`" would exclude all non-directories.
+ fails to match. For instance, `-f'-! */'` would exclude all non-directories.
- A `C` is used to indicate that all the global CVS-exclude rules should be
inserted as excludes in place of the "-C". No arg should follow.
- An `s` is used to indicate that the rule applies to the sending side. When a
- rule affects the sending side, it prevents files from being transferred. The
- default is for a rule to affect both sides unless [`--delete-excluded`](#opt)
- was specified, in which case default rules become sender-side only. See also
- the hide (H) and show (S) rules, which are an alternate way to specify
- sending-side includes/excludes.
+ rule affects the sending side, it affects what files are put into the
+ sender's file list. The default is for a rule to affect both sides unless
+ [`--delete-excluded`](#opt) was specified, in which case default rules become
+ sender-side only. See also the hide (H) and show (S) rules, which are an
+ alternate way to specify sending-side includes/excludes.
- An `r` is used to indicate that the rule applies to the receiving side. When
a rule affects the receiving side, it prevents files from being deleted. See
the `s` modifier for more info. See also the protect (P) and risk (R) rules,
xattr-matching rules are specified, a default xattr filtering rule is used
(see the [`--xattrs`](#opt) option).
-## MERGE-FILE FILTER RULES
+### MERGE-FILE FILTER RULES
You can merge whole files into your filter rules by specifying either a merge
(.) or a dir-merge (:) filter rule (as introduced in the [FILTER RULES](#)
command-line option and instead insert a "-C" rule into your filter rules; e.g.
"`--filter=-C`".
-## LIST-CLEARING FILTER RULE
+### LIST-CLEARING FILTER RULE
You can clear the current include/exclude list by using the "!" filter rule (as
introduced in the [FILTER RULES](#) section above). The "current" list is either
options) or a set of per-directory rules (which are inherited in their own
sub-list, so a subdirectory can use this to clear out the parent's rules).
-## ANCHORING INCLUDE/EXCLUDE PATTERNS
+### ANCHORING INCLUDE/EXCLUDE PATTERNS
As mentioned earlier, global include/exclude patterns are anchored at the "root
of the transfer" (as opposed to per-directory patterns, which are anchored at
output when using [`--verbose`](#opt) and put a / in front of the name (use the
`--dry-run` option if you're not yet ready to copy any files).
-## PER-DIRECTORY RULES AND DELETE
+### PER-DIRECTORY RULES AND DELETE
Without a delete option, per-directory rules are only relevant on the sending
side, so you can feel free to exclude the merge files themselves without
> rsync -avFF --delete host:src/dir /dest
> ```
+## TRANSFER RULES
+
+In addition to the [FILTER RULES](#) that affect the recursive file scans that
+generate the file list on the sending and (when deleting) receiving sides,
+there are transfer rules. These rules affect which files the generator decides
+need to be transferred without the side effects of an exclude filter rule.
+Transfer rules affect only files and never directories.
+
+Because a transfer rule does not affect what goes into the sender's (and
+receiver's) file list, it cannot have any effect on which files get deleted on
+the receiving side. For example, if the file "foo" is present in the sender's
+list but its size is such that it is omitted due to a transfer rule, the
+receiving side does not request the file. However, its presence in the file
+list means that a delete pass will not remove a matching file named "foo" on
+the receiving side. On the other hand, a server-side exclude (hide) of the
+file "foo" leaves the file out of the server's file list, and absent a
+receiver-side exclude (protect) the receiver will remove a matching file named
+"foo" if deletions are requested.
+
+Given that the files are still in the sender's file list, the
+[`--prune-empty-dirs`](#opt) option will not judge a directory as being empty
+even if it contains only files that the transfer rules omitted.
+
+Similarly, a transfer rule does not have any extra effect on which files are
+deleted on the receiving side, so setting a maximum file size for the transfer
+does not prevent big files from being deleted.
+
+Examples of transfer rules include the default "quick check" algorithm (which
+compares size & modify time), the [`--update`](#opt) option, the
+[`--max-size`](#opt) option, the [`--ignore-non-existing`](#opt) option, and a
+few others.
+
## BATCH MODE
Batch mode can be used to apply the same set of updates to many identical
verify, the update discarded with an error. This means that it should be safe
to re-run a read-batch operation if the command got interrupted. If you wish
to force the batched-update to always be attempted regardless of the file's
-size and date, use the [`-I`](#opt--ignore-times) option (when reading the
-batch). If an error occurs, the destination tree will probably be in a
-partially updated state. In that case, rsync can be used in its regular
-(non-batch) mode of operation to fix up the destination tree.
+size and date, use the [`-I`](#opt) option (when reading the batch). If an
+error occurs, the destination tree will probably be in a partially updated
+state. In that case, rsync can be used in its regular (non-batch) mode of
+operation to fix up the destination tree.
The rsync version used on all destinations must be at least as new as the one
used to generate the batch file. Rsync will die with an error if the protocol
Specify a "1" if you want the [`--old-args`](#opt) option to be enabled by
default, a "2" (or more) if you want it to be enabled in the
- option-repeated state, or a "0" to make sure that it is disabled by
- default. First supported in 3.2.4.
+ repeated-option state, or a "0" to make sure that it is disabled by
+ default. When this environment variable is set to a non-zero value, it
+ supersedes the [`RSYNC_PROTECT_ARGS`](#) variable.
+
+ This variable is ignored if [`--old-args`](#opt), `--no-old-args`, or
+ [`--secluded-args`](#opt) is specified on the command line.
+
+ First supported in 3.2.4.
0. `RSYNC_PROTECT_ARGS`
- Specify a non-zero numeric value if you want the [`--protect-args`](#opt)
+ Specify a non-zero numeric value if you want the [`--secluded-args`](#opt)
option to be enabled by default, or a zero value to make sure that it is
- disabled by default. First supported in 3.1.0.
+ disabled by default.
+
+ This variable is ignored if [`--secluded-args`](#opt), `--no-secluded-args`,
+ or [`--old-args`](#opt) is specified on the command line.
+
+ First supported in 3.1.0. Starting in 3.2.4, this variable is ignored if
+ [`RSYNC_OLD_ARGS`](#) is set to a non-zero value.
0. `RSYNC_RSH`
- The RSYNC_RSH environment variable allows you to override the default shell
- used as the transport for rsync. Command line options are permitted after
- the command name, just as in the [`--rsh`](#opt) (`-e`) option.
+ This environment variable allows you to override the default shell used as
+ the transport for rsync. Command line options are permitted after the
+ command name, just as in the [`--rsh`](#opt) (`-e`) option.
0. `RSYNC_PROXY`
- The RSYNC_PROXY environment variable allows you to redirect your rsync
- client to use a web proxy when connecting to a rsync daemon. You should
- set RSYNC_PROXY to a hostname:port pair.
+ This environment variable allows you to redirect your rsync
+ client to use a web proxy when connecting to an rsync daemon. You should
+ set `RSYNC_PROXY` to a hostname:port pair.
0. `RSYNC_PASSWORD`
- Setting RSYNC_PASSWORD to the required password allows you to run
- authenticated rsync connections to an rsync daemon without user
- intervention. Note that this does not supply a password to a remote shell
- transport such as ssh; to learn how to do that, consult the remote shell's
- documentation.
+ This environment variable allows you to set the password for an rsync
+ **daemon** connection, which avoids the password prompt. Note that this
+ does **not** supply a password to a remote shell transport such as ssh
+ (consult its documentation for how to do that).
0. `USER` or `LOGNAME`
The USER or LOGNAME environment variables are used to determine the default
username sent to an rsync daemon. If neither is set, the username defaults
- to "nobody".
+ to "nobody". If both are set, `USER` takes precedence.
+
+0. `RSYNC_PARTIAL_DIR`
+
+ This environment variable specifies the directory to use for a
+ [`--partial`](#opt) transfer without implying that partial transfers be
+ enabled. See the [`--partial-dir`](#opt) option for full details.
+
+0. `RSYNC_COMPRESS_LIST`
+
+ This environment variable allows you to customize the negotiation of the
+ compression algorithm by specifying an alternate order or a reduced list of
+ names. Use the command `rsync --version` to see the available compression
+ names. See the [`--compress`](#opt) option for full details.
+
+0. `RSYNC_CHECKSUM_LIST`
+
+ This environment variable allows you to customize the negotiation of the
+ checksum algorithm by specifying an alternate order or a reduced list of
+ names. Use the command `rsync --version` to see the available checksum
+ names. See the [`--checksum-choice`](#opt) option for full details.
+
+0. `RSYNC_MAX_ALLOC`
+
+ This environment variable sets an allocation maximum as if you had used the
+ [`--max-alloc`](#opt) option.
+
+0. `RSYNC_PORT`
+
+ This environment variable is not read by rsync, but is instead set in
+ its sub-environment when rsync is running the remote shell in combination
+ with a daemon connection. This allows a script such as
+ [`rsync-ssl`](rsync-ssl.1) to be able to know the port number that the user
+ specified on the command line.
0. `HOME`
- The HOME environment variable is used to find the user's default .cvsignore
+ This environment variable is used to find the user's default .cvsignore
file.
+0. `RSYNC_CONNECT_PROG`
+
+ This environment variable is mainly used in debug setups to set the program
+ to use when making a daemon connection. See [CONNECTING TO AN RSYNC
+ DAEMON](#) for full details.
+
+0. `RSYNC_SHELL`
+
+ This environment variable is mainly used in debug setups to set the program
+ to use to run the program specified by [`RSYNC_CONNECT_PROG`](#). See
+ [CONNECTING TO AN RSYNC DAEMON](#) for full details.
+
## FILES
/etc/rsyncd.conf or rsyncd.conf
## SEE ALSO
-[**rsync-ssl**(1)](./rsync-ssl.1), [**rsyncd.conf**(5)](./rsyncd.conf.5), [**rrsync**(1)](./rrsync.1)
+[**rsync-ssl**(1)](rsync-ssl.1), [**rsyncd.conf**(5)](rsyncd.conf.5), [**rrsync**(1)](rrsync.1)
## BUGS
## VERSION
-This man page is current for version @VERSION@ of rsync.
+This manpage is current for version @VERSION@ of rsync.
## INTERNAL OPTIONS
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
-[COPYING](./COPYING) for details.
+[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/>. The site
includes an FAQ-O-Matic which may cover questions unanswered by this manual
git.samba.org / rsync.git / blobdiff