--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
--bwlimit=RATE limit socket I/O bandwidth
--stop-after=MINS Stop rsync after MINS minutes have elapsed
--stop-at=y-m-dTh:m Stop rsync at the specified point in time
+--fsync fsync every written file
--write-batch=FILE write a batched update to FILE
--only-write-batch=FILE like --write-batch but w/o updating dest
--read-batch=FILE read a batched update from FILE
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 enables the outputting of some
- I/O related debug messages.
+ 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
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 transferred). 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
0. `--omit-dir-times`, `-O`
- This tells rsync to omit directories when it is preserving modification
- times (see `--times`). If NFS is sharing the directories on the receiving
+ This tells rsync to omit directories when it is preserving modification,
+ access, and create times. If NFS is sharing the directories on the receiving
side, it is a good idea to use `-O`. This option is inferred if you use
`--backup` without `--backup-dir`.
0. `--omit-link-times`, `-J`
- This tells rsync to omit symlinks when it is preserving modification times
- (see `--times`).
+ This tells rsync to omit symlinks when it is preserving modification,
+ access, and create times.
0. `--super`
This tells the receiving side to attempt super-user activities even if the
receiving rsync wasn't run by the super-user. These activities include:
preserving users via the `--owner` option, preserving all groups (not just
- the current user's groups) via the `--groups` option, and copying devices
+ the current user's groups) via the `--group` option, and copying devices
via the `--devices` option. This is useful for systems that allow such
activities without being the super-user, and also for ensuring that you
will get errors if the receiving side isn't being run as the super-user.
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
0. `--exclude-from=FILE`
This option is related to the `--exclude` option, but it specifies a FILE
- that contains exclude patterns (one per line). Blank lines in the file and
- lines starting with '`;`' or '`#`' are ignored. If _FILE_ is '`-`', the
- list will be read from standard input.
+ that contains exclude patterns (one per line). Blank lines in the file are
+ ignored, as are whole-line comments that start with '`;`' or '`#`'
+ (filename rules that contain those characters are unaffected).
+
+ If _FILE_ is '`-`', the list will be read from standard input.
0. `--include=PATTERN`
0. `--include-from=FILE`
This option is related to the `--include` option, but it specifies a FILE
- that contains include patterns (one per line). Blank lines in the file and
- lines starting with '`;`' or '`#`' are ignored. If _FILE_ is '`-`', the
- list will be read from standard input.
+ that contains include patterns (one per line). Blank lines in the file are
+ ignored, as are whole-line comments that start with '`;`' or '`#`'
+ (filename rules that contain those characters are unaffected).
+
+ If _FILE_ is '`-`', the list will be read from standard input.
0. `--files-from=FILE`
> rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
- If file's aren't linking, double-check their attributes. Also check if
+ If files aren't linking, double-check their attributes. Also check if
some attributes are getting forced outside of rsync's control, such a mount
option that squishes root to a single user, or mounts a removable drive
with generic ownership (such as OS X's "Ignore ownership on this volume"
specify `-zz`.
See also the `--skip-compress` option for the default list of file suffixes
- that will transferred 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
For the `--usermap` option to have any effect, the `-o` (`--owner`) option
must be used (or implied), and the receiver will need to be running as a
super-user (see also the `--fake-super` option). For the `--groupmap`
- option to have any effect, the `-g` (`--groups`) option must be used (or
+ option to have any effect, the `-g` (`--group`) 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`
sense) were created (as opposed to updated). The total count will be
followed by a list of counts by filetype (if the total is non-zero).
- `Number of deleted files` is the count of how many "files" (generic
- sense) were created (as opposed to updated). The total count will be
+ sense) were deleted. The total count will be
followed by a list of counts by filetype (if the total is non-zero).
Note that this line is only output if deletions are in effect, and only
if protocol 31 is being used (the default for rsync 3.1.x).
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
mind that the remote host may have a different default timezone than your
local host.
+0. `--fsync`
+
+ Cause the receiving side to fsync each finished file. This may slow down
+ the transfer, but can help to provide peace of mind when updating critical
+ files.
+
0. `--write-batch=FILE`
Record a file that can later be applied to another identical destination
0. `risk, 'R'` files that match the pattern are not protected.
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 comment
-lines that start with a "#".
+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!)
git.samba.org / rsync.git / blobdiff