directory to the directory src on the machine foo. If any of the files already
exist on the remote system then the rsync remote-update protocol is used to
update the file by sending only the differences in the data. Note that the
-expansion of wildcards on the commandline (`*.c`) into a list of files is
+expansion of wildcards on the command-line (`*.c`) into a list of files is
handled by the shell before it runs rsync and not by rsync itself (exactly the
-same as all other posix-style programs).
+same as all other Posix-style programs).
> rsync -avz foo:src/bar /data/tmp
detailed description below for a complete description.
[comment]: # (help-rsync.h)
-[comment]: # (Keep these short enough that they'll be under 80 chars when indented by 8 chars.)
+[comment]: # (Keep these short enough that they'll be under 80 chars when indented by 7 chars.)
```
--verbose, -v increase verbosity
--info=FLAGS fine-grained informational verbosity
--debug=FLAGS fine-grained debug verbosity
---msgs2stderr output messages directly to stderr
+--stderr=e|a|c change stderr output mode (default: errors)
--quiet, -q suppress non-error messages
--no-motd suppress daemon-mode MOTD
--checksum, -c skip based on checksum, not mod-time & size
---archive, -a archive mode; equals -rlptgoD (no -H,-A,-X)
+--archive, -a archive mode is -rlptgoD (no -A,-X,-U,-N,-H)
--no-OPTION turn off an implied OPTION (e.g. --no-D)
--recursive, -r recurse into directories
--relative, -R use relative path names
--append append data onto shorter files
--append-verify --append w/old data in file checksum
--dirs, -d transfer directories without recursing
+--mkpath create the destination's path component
--links, -l copy symlinks as symlinks
--copy-links, -L transform symlink into referent file/dir
--copy-unsafe-links only "unsafe" symlinks are transformed
> rsync -avvv --debug=none src/ dest/
> rsync -avA --del --debug=del2,acl src/ dest/
- Note that some debug messages will only be output when `--msgs2stderr` is
+ Note that some debug messages will only be output when `--stderr=all` is
specified, especially those pertaining to I/O and buffer debugging.
- Beginning in 3.2.0, this option is no longer auto-forwared to the server
+ Beginning in 3.2.0, this option is no longer auto-forwarded to the server
side in order to allow you to specify different debug values for each side
of the transfer, as well as to specify a new debug option that is only
present in one of the rsync versions. If you want to duplicate the same
> rsync -aiv {-M,}--debug=del2 src/ dest/
-0. `--msgs2stderr`
-
- This option changes rsync to send all its output directly to stderr rather
- than to send messages to the client side via the protocol. The protocol
- allows rsync to output normal messages via stdout and errors via stderr,
- but it can delay messages behind a slew of data.
-
- One case where this is helpful is when sending really large files, since
- errors that happen on a remote receiver tend to get delayed until after the
- file's data is fully sent. It is also helpful for debugging, since it
- helps to avoid overpopulating the protocol data with extra message data.
-
- The option does not affect the remote side of a transfer without using
- `--remote-option`, e.g. `-M--msgs2stderr` or `{-M,}--msgs2stderr`.
-
- Also keep in mind that connecting to a normal (non-remote-shell) daemon
- does not have a stderr channel to send messages back to the client side, so
- a modern rsync only allows the option on a remote-shell-run daemon.
-
- This option has the side-effect of making stderr output get line-buffered
- so that the merging of the output of 3 programs happens in a more readable
- manner.
+0. `--stderr=errors|all|client`
+
+ This option controls which processes output to stderr and if info messages
+ are also changed to stderr. The mode strings can be abbreviated, so feel
+ free to use a single letter value. The 3 possible choices are:
+
+ - `errors` - (the default) causes all the rsync processes to send an
+ error directly to stderr, even if the process is on the remote side of
+ the transfer. Info messages are sent to the client side via the protocol
+ stream. If stderr is not available (i.e. when directly connecting with a
+ daemon via a socket) errors fall back to being sent via the protocol
+ stream.
+
+ - `all` - causes all rsync messages (info and error) to get written
+ directly to stderr from all (possible) processes. This causes stderr to
+ become line-buffered (instead of raw) and eliminates the ability to
+ divide up the info and error messages by file handle. For those doing
+ debugging or using several levels of verbosity, this option can help to
+ avoid clogging up the transfer stream (which should prevent any chance of
+ a deadlock bug hanging things up). It also allows `--debug` to enable
+ some extra I/O related messages.
+
+ - `client` - causes all rsync messages to be sent to the client side
+ via the protocol stream. One client process outputs all messages, with
+ errors on stderr and info messages on stdout. This **was** the default
+ in older rsync versions, but can cause error delays when a lot of
+ transfer data is ahead of the messages. If you're pushing files to an
+ older rsync, you may want to use `--stderr=all` since that idiom has
+ been around for several releases.
+
+ This option was added in rsync 3.2.3. This version also began the
+ forwarding of a non-default setting to the remote side, though rsync uses
+ the backward-compatible options `--msgs2stderr` and `--no-msgs2stderr` to
+ represent the `all` and `client` settings, respectively. A newer rsync
+ will continue to accept these older option names to maintain compatibility.
0. `--quiet`, `-q`
the same modification timestamp. This option turns off this "quick check"
behavior, causing all files to be updated.
+ This option can be a little confusing compared to `--ignore-existing` and
+ `--ignore-non-existing` in that that they cause rsync to transfer fewer
+ files, while this option causes rsync to transfer more files.
+
0. `--size-only`
This modifies rsync's "quick check" algorithm for finding files that need
0. `--archive`, `-a`
This is equivalent to `-rlptgoD`. It is a quick way of saying you want
- recursion and want to preserve almost everything (with `-H` being a notable
- omission). The only exception to the above equivalence is when
- `--files-from` is specified, in which case `-r` is not implied.
+ recursion and want to preserve almost everything. Be aware that it does
+ **not** include preserving ACLs (`-A`), xattrs (`-X`), atimes (`-U`),
+ crtimes (`-N`), nor the finding and preserving of hardlinks (`-H`).
- Note that `-a` **does not preserve hardlinks**, because finding
- multiply-linked files is expensive. You must separately specify `-H`.
+ The only exception to the above equivalence is when
+ `--files-from` is specified, in which case `-r` is not implied.
0. `--no-OPTION`
0. `--append`
- This causes rsync to update a file by appending data onto the end of the
- file, which presumes that the data that already exists on the receiving
- side is identical with the start of the file on the sending side. If a
- file needs to be transferred and its size on the receiver is the same or
- longer than the size on the sender, the file is skipped. This does not
- interfere with the updating of a file's non-content attributes (e.g.
- permissions, ownership, etc.) when the file does not need to be
- transferred, nor does it affect the updating of any non-regular files.
- Implies `--inplace`.
-
- The use of `--append` can be dangerous if you aren't 100% sure that the
- files that are longer have only grown by the appending of data onto the
- end. You should thus use include/exclude/filter rules to ensure that such
- a transfer is only affecting files that you know to be growing via appended
- data.
+ This special copy mode only works to efficiently update files that are
+ known to be growing larger where any existing content on the receiving side
+ is also known to be the same as the content on the sender. The use of
+ `--append` **can be dangerous** if you aren't 100% sure that all the files
+ in the transfer are shared, growing files. You should thus use filter
+ rules to ensure that you weed out any files that do not fit this criteria.
+
+ Rsync updates these growing file in-place without verifying any of the
+ existing content in the file (it only verifies the content that it is
+ appending). Rsync skips any files that exist on the receiving side that
+ are not shorter than the associated file on the sending side (which means
+ that new files are trasnferred). It also skips any files whose size on the
+ sending side gets shorter during the send negotiations (rsync warns about a
+ "diminished" file when this happens).
+
+ This does not interfere with the updating of a file's non-content
+ attributes (e.g. permissions, ownership, etc.) when the file does not need
+ to be transferred, nor does it affect the updating of any directories or
+ non-regular files.
0. `--append-verify`
- This works just like the `--append` option, but the existing data on the
- receiving side is included in the full-file checksum verification step,
- which will cause a file to be resent if the final verification step fails
- (rsync uses a normal, non-appending `--inplace` transfer for the resend).
- It otherwise has the exact same caveats for files that have not grown
- larger, so don't use this for a general copy.
+ This special copy mode works like `--append` except that all the data in
+ the file is included in the checksum verification (making it much less
+ efficient but also potentially safer). This option **can be dangerous** if
+ you aren't 100% sure that all the files in the transfer are shared, growing
+ files. See the `--append` option for more details.
Note: prior to rsync 3.0.0, the `--append` option worked like
`--append-verify`, so if you are interacting with an older rsync (or the
`--old-d`) that tells rsync to use a hack of `-r --exclude='/*/*'` to get
an older rsync to list a single directory without recursing.
+0. `--mkpath`
+
+ Create a missing path component of the destination arg. This allows rsync
+ to create multiple levels of missing destination dirs and to create a path
+ in which to put a single renamed file. Keep in mind that you'll need to
+ supply a trailing slash if you want the entire destination path to be
+ treated as a directory when copying a single arg (making rsync behave the
+ same way that it would if the path component of the destination had already
+ existed).
+
+ For example, the following creates a copy of file foo as bar in the sub/dir
+ directory, creating dirs "sub" and "sub/dir" if either do not yet exist:
+
+ > rsync -ai --mkpath foo sub/dir/bar
+
+ If you instead ran the following, it would have created file foo in the
+ sub/dir/bar directory:
+
+ > rsync -ai --mkpath foo sub/dir/bar/
+
0. `--links`, `-l`
When symlinks are encountered, recreate the symlink on the destination.
permissions on the hard-linked files). This does mean that this option is
only looking at the existing files in the destination hierarchy itself.
+ When `--info=skip2` is used rsync will output "FILENAME exists (INFO)"
+ messages where the INFO indicates one of "type change", "sum change"
+ (requires `-c`), "file change" (based on the quick check), "attr change",
+ or "uptodate". Using `--info=skip1` (which is also implied by `-vv`)
+ outputs the exists message without the INFO suffix.
+
0. `--remove-source-files`
This tells rsync to remove from the sending side the files (meaning
has no permissions to change.
The following command does a local copy into the "dest/" dir as user "joe"
- (assumimg you've installed support/lsh into a dir on your $PATH):
+ (assuming you've installed support/lsh into a dir on your $PATH):
> sudo rsync -aive lsh -M--copy-as=joe src/ lh:dest/
specify `-zz`.
See also the `--skip-compress` option for the default list of file suffixes
- that will trasnferred with no (or minimal) compression.
+ that will be transferred with no (or minimal) compression.
0. `--compress-choice=STR`, `--zc=STR`
[comment]: # (This list gets used for the default-dont-compress.h file.)
+ > 3g2
+ > 3gp
> 7z
+ > aac
> ace
> apk
> avi
> bz2
> deb
+ > dmg
+ > ear
+ > f4v
> flac
+ > flv
> gpg
> gz
> iso
> jar
> jpeg
> jpg
+ > lrz
> lz
> lz4
> lzma
> lzo
+ > m1a
+ > m1v
+ > m2a
+ > m2ts
+ > m2v
+ > m4a
+ > m4b
+ > m4p
+ > m4r
+ > m4v
+ > mka
> mkv
> mov
+ > mp1
+ > mp2
> mp3
> mp4
+ > mpa
+ > mpeg
+ > mpg
+ > mpv
+ > mts
> odb
> odf
> odg
> odp
> ods
> odt
+ > oga
> ogg
+ > ogm
> ogv
+ > ogx
> opus
> otg
> oth
> ott
> oxt
> png
+ > qt
> rar
> rpm
> rz
> rzip
+ > spx
> squashfs
> sxc
> sxd
> sxg
> sxm
> sxw
+ > sz
> tbz
+ > tbz2
> tgz
> tlz
+ > ts
> txz
> tzo
+ > vob
+ > war
> webm
> webp
> xz
option to have any effect, the `-g` (`--groups`) option must be used (or
implied), and the receiver will need to have permissions to set that group.
+ If your shell complains about the wildcards, use `--protect-args` (`-s`).
+
0. `--chown=USER:GROUP`
This option forces all files to be owned by USER with group GROUP. This is
USER is empty, a leading colon must be supplied.
If you specify "`--chown=foo:bar`", this is exactly the same as specifying
- "`--usermap=*:foo --groupmap=*:bar`", only easier.
+ "`--usermap=*:foo --groupmap=*:bar`", only easier. If your shell complains
+ about the wildcards, use `--protect-args` (`-s`).
0. `--timeout=SECONDS`
can do if you want rsync to cleanup old `.~tmp~` dirs that might be lying
around. Conflicts with `--inplace` and `--append`.
+ This option implies `--no-inc-recursive` since it needs the full file list
+ in memory in order to be able to iterate over it at the end.
+
This option uses more memory on the receiving side (one bit per file
transferred) and also requires enough free disk space on the receiving side
to hold an additional copy of all the updated files. Note also that you
git.samba.org / rsync.git / blobdiff