> 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
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 we sent to the sender.
+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, it is safest to do a copy
-into a dedicated destination directory for the remote files rather than
-requesting the remote content get mixed in with other local content. For
-example, doing an rsync copy into your home directory is potentially unsafe on
-an older rsync if the remote rsync is being controlled by a bad actor:
+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 ~
-A safer command would be:
+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
The syntax for requesting multiple files from a remote host is done by
> 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 ::modname/extra{1,2} /dest/
+> rsync -aiv host::modname/first ::extra-file{1,2} /dest/
+
+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).
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
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":
--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
--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
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 shell to expand it.
+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)
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`
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
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`
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 tells rsync to set the access (use) times of the destination files to
- `xxh64` (aka `xxhash`)
- `md5`
- `md4`
+ - `sha1`
- `none`
Run `rsync --version` to see the default checksum list compiled into your
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
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 occuring). Any
+ 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 modifer letters (e.g., `-f'-sr
+ 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 is saves you from having to edit a bunch of
- `-f'- foo'` rules into `-f'-s foo'` or `-f'H foo'` rules (not to mention
+ 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
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.
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.
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
because we can't know for sure what names to expect when the remote shell
is interpreting the args.
- This option conflicts with the [`--protect-args`](#opt) option.
+ This option conflicts with the [`--secluded-args`](#opt) option.
-0. `--protect-args`, `-s`
+0. `--secluded-args`, `-s`
- 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 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 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.
+ 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.
- 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 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-protect-args` are the negative
+ 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.
- You may need to disable this option when interacting with an older rsync
- (one prior to 3.0.0).
-
This option conflicts with the [`--old-args`](#opt) option.
- Note that this option is incompatible with the use of the restricted rsync
- script (`rrsync`) since it hides options from the script's inspection.
+ 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).
+
+0. `--trust-sender`
+
+ 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).
+
+ 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).
+
+ Note that various options can turn off one or both of these checks if the
+ option interferes with the validation. For instance:
+
+ - 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]`
[`--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`
"`--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`
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:
+ 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
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.
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 were specified as a argument.
+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
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 (\_). Any additional
-spaces and/or undeerscore are considered to be a part of the pattern name.
+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
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, and
- thus it disables the receiver's verification of the file-list names against
- the filter rules (since only the sender can know for sure if it obeyed all
- the filter rules when some are per-dir merged from the sender's files).
+ 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.
Equivalent to a sender-only exclude, so `-f'H foo'` could also be specified
as `-f'-s foo'`.
- 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 `/` 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).
+ 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
+ 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
- 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, which must be at the root of the
- transfer
-- Option `-f'- /foo/**/bar'` would exclude any file/dir named bar two or more
- levels below a directory named foo, which must be at the root of the transfer
+- 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
supersedes the [`RSYNC_PROTECT_ARGS`](#) variable.
This variable is ignored if [`--old-args`](#opt), `--no-old-args`, or
- [`--protect-args`](#opt) is specified on the command line.
+ [`--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.
- This variable is ignored if [`--protect-args`](#opt), `--no-protect-args`,
+ 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
git.samba.org / rsync.git / blobdiff