> rsync somehost.mydomain.com::
-See the following section for more details.
+## COPYING A SINGLE FILE
+
+Rsync has special handling for a copy of a single file that allows for the name
+to be changed on the destination. The rules for this are:
+
+- The transfer list must consist of a single file (with no parent directory in
+ the transfer)
+- 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 file to
+the last element of the destination path.
+
+For example, the following will copy the foo.c file as bar.c in the "dest" dir
+(assuming that bar.c isn't a directory):
+
+> rsync -ai src/foo.c dest/bar.c
+
+This rule might accidentally bite you if you unknowingly copy a single file and
+specify a destination dir that doesn't exist (without a trailing slash). For
+example:
+
+> rsync -ai src/*.c dest/dir
+
+If the `*.c` only matched one file and dest/dir did not yet exist, then rsync
+would rename the single .c file with the name "dir" in "dest". To prevent
+this, it is safest to specify a destination path with a trailing slash when you
+want it to be treated as a directory:
+
+> rsync -ai src/*.c dest/dir/
## SORTED TRANSFER ORDER
> 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 first argument in a follow-up path doesn't begin with the
+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).
- Use either double-colon syntax or rsync:// URL syntax instead of the
single-colon (remote shell) syntax.
-- The first word of (at least) the first "path" is actually a module name.
-- Additional remote source args use an abbreviated syntax as discussed in
- [ADVANCED USAGE](#).
+- 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.
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).
-
- For example, the following creates a copy of file foo as bar in the sub/dir
- directory, creating dirs "sub" and "sub/dir" if either do not yet exist:
-
- > rsync -ai --mkpath foo sub/dir/bar
-
- If you instead ran the following, it would have created file foo in the
- sub/dir/bar directory:
+ Create a missing path component of the destination path. By default, rsync
+ allows only the final element 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.
- > rsync -ai --mkpath foo sub/dir/bar/
+ When specifying a destination path, including a trailing slash ensures that
+ rsync always treats the whole path as the directory name to be created,
+ even if the source arg is a single filename. See the [COPYING A SINGLE
+ FILE](#) section for full details on how rsync decides if a final
+ destination path element is a directory or not.
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
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
> 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
git.samba.org / rsync.git / blobdiff