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":
--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
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 hum-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`
- `xxh64` (aka `xxhash`)
- `md5`
- `md4`
+ - `sha1`
+ - `sha256`
+ - `sha512`
- `none`
Run `rsync --version` to see the default checksum list compiled into your
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.
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`
[`--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`
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.
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