High performance, file copying tool, used locally or to/from another host, for backup and mirroring. Can perform most ftp
tasks.
Local side is refered to as the "client" and the remote as the "server".
rsyncd
, the (optional) daemon is always a server. A remote server can be either a daemon or a remote-shell spawned process.
Local: | rsync [option …] src… [dest]
|
Use remote shell: (when rsyncd is not running on host) notice single ': ' | |
Pull: | rsync [option …] [user@]host:src… [dest] |
Push: | rsync [option …] src… [user@]host:dest
|
Use rsync daemon at remote host | |
Pull: | rsync [option …] [user@]host::src… [dest] |
rsync [option …] rsync://[user@]host[:port]/src… [dest] | |
Push: | rsync [option …] src… [user@]host::dest |
rsync [option …] src… rsync://[user@]host[:port]/dest |
Single file example not using remote rsyncd useful when transfering a large file (SD card image) when
Display updates from a repository:
Copies locally (perhaps network shares) if neither the source or destination path are a host.
There is a lot to know about rsync ( and I only know a little), here's what you HAVE TO know.
If a single source is specified without a destination, the files are listed in an output format similar to
Example:
The order of the options is important. The result of
Does not preserve hardlinks,
If
The side-effects of the
Following only seen with
Filenames are displayed in
Each file, dir, etc. that gets updated in a significant way (a transferred file,
a recreated symlink/device, or a touched directory) will be output.
The out-formated string is output prior to a file's transfer.
Statistics can be misleading with the delta-transfer algorithm.
For example, if the file is a log previously sent the reported rate will drop dramatically when the receiver gets to the
new data, and the transfer will take much longer to finish than predicted.
When a file transfer finishes, the progress line is replaced with a summary line like :
Does not affect the copying of symlinks or other special files.
This does not affect updating a file's 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.
If
Rsync creates
When supplying exclude rules, you may need to add your own exclude/hide/protect rule for the partial-dir because
IMPORTANT: the
You can also set the partial-dir value the
For the purposes of the daemon-config's "refuse options" setting, --partial-dir does NOT imply
Requires enough free disk space on the receiving side to hold an additional copy of all the updated files.
Do not use an absolute path to
--partial-dir unless
See also the "atomic-rsync" perl script in the "support" subdir
for an update algorithm that is even more atomic (it uses --link-dest and a parallel hierarchy of files).
WARNING: Do not use this to update files being accessed by others.
Useful for transferring large files with block-based changes or appended data, and also on systems that are disk bound, not network bound.
Implies
These extra path elements are called "implied directories" (i.e. the "foo" and the "foo/bar" directories in the above example).
rsync sends these implied directories as real directories in the file list, even if a path
element is really a symlink on the sending side. This prevents
unexpected behaviors when copying the full path of a file that you didn't realize had a symlink in its path.
To limit the amount of path information that is sent as implied directories for each path,
insert a dot and a slash into the source path.
For instance, if a command-line arg or a files-from entry told rsync to transfer the file "path/foo/file", the directories
"path" and "path/foo" are implied when
without
Without this , if the sending side has replaced a directory with a symlink to a directory, the receiving side will
delete anything that is in the way of the new symlink, including a directory hierarchy (as long as See
For example, transfer a directory "foo" that contains a file "file", but "foo" is a symlink to directory "bar" on the receiver.
See also --copy-dirlinks for an analogous option for the sending side.
When updating a non-empty destination, ensures that files that are hard-linked together on the source
are hard-linked together on the destination.
Rsync can only detect hard links between files that are in the transfer set. If rsync updates a file that has
extra hard-link connections to files outside the transfer, that linkage will be broken.
If incremental recursion is active rsync may
transfer a missing hard-linked file before it finds that another link for that contents exists elsewhere in the hierarchy.
With
rsync alias --compress --no--perms --no--group --chmod=ugo=rwX
then use : rsync -avZ src/ dest/
An item that should only apply to a directory is prefixed with
See
only if the receiver is super-user (see
The preservation of group information will associate matching
names by default, but may fall back to using the ID number
overridden by both
See
If repeated, rsync omits all mount-point directories.
If collapse symlinks (via
This is a transfer rule, not an exclude, it doesn't affect the data that goes into the file-lists, and thus it
doesn't affect deletions. It just limits the files that the receiver requests to be transferred.
Deletions will also occur when
Use
If the sending side detects I/O errors, deletion of any files will be disabled,
May be combined with one of the
Helpful when the destination filesystem is low on space.
Examples:
With
Command-line arguments are permitted in
Examples:
Filters out the
When combining rsync --verbose --verbose --compress --progress --append DaMonitor2-16GB.200421.gz user@host:
rsync --recursive user@fromHost:directory/sub . --list-only
Most basic transfer options: --archive
preserve basic attributes (permissions, owner, type symbolic links ).
--xattrs
preserve eXtended attributes
--acls
preserve Access Control Lists
--hard-links
preserve them, see symbolic links
--compress
in flight data ( no effect on destination)
--update
if existing files are current, skip transferring them again
--exclude-from=rsync-excludes
patterns (one per line).
--log-file=0rsync.log
Is your shell clean?
abort message.
ls -l
.
The "=
" is optional; whitespace can be used.
--no-option
Turn off implied options
For example --archive
is a synonym for -recursive --links
etc. follow it with --no-links
to not recreate links.--no-devices, --no-perms
have different defaults in various circumstances
Example: --no-whole-file, --no-blocking-io, --no-dirs
.
--no--recursive --archive
is that --recursive
would end up being turned on, the opposite of
--archive --no--recursive
.
--list-only
Use to specify more than one source (explicititly or with wild-card expanded by the shell into multiple args)
for listing, otherwise second source would be intrepreted as the destination.
rsync --list-only uname@Real-World-Systems.com:*.txt # list all txt files on that host's root directory
-rw-r----- 160 2017/05/18 20:31:30 apacheNotes.txt
-rw-r--r-- 1490 2018/10/22 16:57:32 pepper-181022.txt
-rw-r----- 3679 2017/12/29 19:04:47 smacproPart4.txt
rsync --list-only /Volumes/big/*.MOV # list all the MOV files on that volume/dirctory
--recursive is not effective
-rw-r--r-- 308842544 2018/05/16 07:56:53 CamperGrandTour_2064.MOV
-rw-r--r-- 12014106 2018/06/23 15:40:36 DoorClosingWithGap188.MOV
-rw-r--r-- 185538306 2017/02/18 13:29:27 Hummers_0655.MOV
-rw-r--r-- 19434966 2019/01/19 09:28:38 IMG_0332.MOV
-n
--dry-run Doesn't perform transfers, produces a similar report as a real run.
-a
--archive synonym for -recursive --links --perms --times --group --owner --devices --specials
( ACL and eXtended attributes may not be preserved(?) ed)
When --files-from
is specified --recursive
is not implied.---hard-links
.-archive
follows --compress
it will reenable the "--no-
" options
--files-from
option are NOT positional, as it affects the default state of
several options and slightly changes the meaning of --archive
.
-v
--verbose
Increases the amount of information displayed during the transfer. By default, rsync works silently.
A single --verbose
gives information about files being transferred and a brief summary at the end.
--verbose --verbose
adds information on what files are being skipped . --verbose --verbose
xxx is over max-size
[sender] hiding file email/Trash because of pattern Trash*.--out-format
of %n%L
by default,
( name and if it is a link, where it points).
At the first level verbosity no mention is made if a file had its attributes changed.
More than two are used for debugging
-q
--quiet decreases the amount of information reported.
Useful when invoking from cron.
Use with --verbose
and/or --itemize-changes
to see what a command is going to do.
options affecting report
-i
--itemize-changes
Increases verbosity. Default --out-format='%i %n%L'
.
Repeating the option causes unchanged files to be output,.
.d var/
.f var/logPrune.sh
%i
string YXcstpoguax
, where
When deleting files, Y
. item is not being updated (attributes may be modified).
<
file is being sent.
>
file is being received
c
change/creation is occurring for
the item
(such as the creation of a directory or the changing of a symlink, etc.).
h
hard link to another item (requires --hard-links).
*
itemized-output area contains a message (example: "deleting").
X
file-type
f
file d
directory L
symlink D
device S
special file (examples: named sockets and fifos). The other letters in the the associated attribute being updated
.
no change.
+
new item ++++++++++
space identical item
?
unknown attribute
Reasons for transfer
c
regular file has a different checksum (requires --checksum
) or
symlink, device, or special file has a changed value.
s
size of a regular file
t
time of last modification (requires --times
).
T
time of last modification will be set to the transfer time
if a file/symlink/device is updated without --times
or
a symlink is changed and the receiver can't set its time.
p
permissions are different (requires --perms
).
o
owner is different (requires --owner
and super-user privileges).
g
group is different (requires --group
and the authority to set the group).
u
future use.
a
ACL (Access Control List) information changed.
x
extended attribute information changed.
%i
will output the string *deleting
.
--out-format=format
string of field specifiers.
Default with --verbose
is %n%L
(name and, if the item is a link, where it points).
See "log format" in rsyncd.conf
.
(e.g. With --itemize-changes
the logging of names includes any item changed.
If a transfer-statistic option is requested, logging is done at the end of the file's transfer.
When this late logging is in effect and --progress
is
specified, the name of the file being transferred is output prior to its progress information followed by the out-format output.
--log-file=file
For a non-daemon transfer, transfer logging will be enabled with a default format of %i %n%L
.
Example: Remote side logs what is happening:
rsync --archive --verbose --rsync-path="rsync --log-file=/tmp/rlog" src/ dest/
Useful to diagnose why a connection is closing unexpectedly.
--log-file-format=format
With an empty string, updated files will not be mentioned in the log file.
Enables "transfer logging" unless the string is empty, in which case transfer logging is turned off.
See log format in rsyncd.conf
.
Default with --log-file
%i %n%L
i.e. name link.
-h
--human-readable K, M, or G. units are K (1000), M (1000*1000), and G (1000*1000*1000);
-h -h
, units are powers of 1024 .
--stats
output statistics
Number of files: 88417
Number of files transferred: 0
Total file size: 5008416760 bytes
Total transferred file size: 0 bytes
Literal data: 0 bytes
Matched data: 0 bytes
File list size: 2710302
File list generation time: 1.156 seconds
File list transfer time: 0.000 seconds
Total bytes sent: 20
Total bytes received: 2710322
sent 20 bytes received 2710322 bytes 285299.16 bytes/sec
total size is 5008416760 speedup is 1847.89
--progress
Implies --verbose
While transferring a regular file, updates a progress line like :
782448 63% 110.64kB/s 0:00:04
The transfer might finish in :04 seconds
1238099 100% 146.38kB/s 0:00:08 (xfer#5, to-check=169/396)
This was the 5th regular file transfered, 169 more files for the receiver to check out of the 396 files
Options that effect how files are determined to be the same and don't need to be transfered.
Some objects (for example: file vs directory) always require an update,
Default: skip files with the same size and modification timestamp.
-I
--ignore-times
--size-only
Useful when a system which does not preserve timestamps well.
timestamps considered equal if they differ by no more than the seconds
.
Default 0 (exact match).
MS Windows FAT filesystem represents times with a 2-second resolution --modify-window=1
allows times to differ by up to 1 second.
-u
--update Do not overwrite the destination if it has a newer modification time
-c
--checksum compare a MD5 128-bit checksums for files that have matching sizes.
Performance degradation affecting both sides. Requires reading all the data in the files with matching size in addition to
reading if the file is transfered.
transfer handling
--append
update by appending data to the file when data
exists on the destination
and the source
begins with the identical data.
If the size of the destination
is the same or longer, the file is not overwirtten.
Implies --inplace
--append-verify
Like --append
but the existing data
on the receiving side is included in the full-file checksum verification, which will cause a file to be resent if the
final verification fails. Normal, non-appending --inplace
transfer is used for the resend.
--partial
keep partial file which should make a subsequent transfer of the rest of the file much faster.
By default, rsync will delete any partially transferred file if the transfer is interrupted.
--partial-dir=dir
to hold the partial data (instead of to the destination file).
On the next transfer, rsync will use a file found in this dir as data to speed up the resumption of the transfer and then delete it
--whole-file
is specified (or implied), any partial-dir file that is found for a file that is being updated
will be removed (since rsync is sending files without using rsync's delta-transfer algorithm).dir
if necessary (just the last dir
-- not the whole path).
Allowing use of relative path (such as "--partial-dir=.rsync-partial
") to have rsync create
the partial-directory in the destination file's directory when
needed, and then remove it again when the partial file is deleted.
If dir
is not an absolute path, rsync will add an exclude rule at the end of all existing excludes. preventing the sending of any partial-dir files that may exist
on the sending side, and will also prevent the untimely deletion of partial-dir items on the receiving side.
An example: the above --partial-dir
option would add the equivalent of -f '-p .rsync-partial/'
at the end of any other filter rules.
(1) the auto-added rule may be ineffective at the end of your other rules, or
(2) you may wish to override rsync's exclude choice. For instance, make rsync clean-up any left-over partial-dirs that may be lying around,
specify --delete-after
and add a "risk" filter rule, eg. -f 'R
.rsync-partial/'. (Avoid using --delete-before
or --delete-du
ing unless you don't need rsync to use any of the left-over partial-dir data during the current run.)
--partial-dir
should not be writable by other users or it is a security risk.
AVOID "/tmp
". RSYNC_PARTIAL_DIR
environment variable. Setting this in the environment does not
force --partial
to be enabled, but rather it affects where partial files go when --partial
is specified. For instance,
instead of using --partial-dir=.rsync-tmp
along with --progress,
Set RSYNC_PARTIAL_DIR=.rsync-tmp
environment variable and then use -P
to turn on the use of the
.rsync-tmp
dir for partial transfers.
The only times that --partial
does not look for this environment value are
(1) when --inplace was specified (since --inplace conflicts with
--partial-dir), and (2) when --delay-updates was specified (see below).--partial.
This is so that a refusal of the --partial option can be used to disallow the
overwriting of destination files with a partial transfer, while still allowing the safer idiom provided by --partial-dir
.
--delay-updates
puts the temporary file from each updated file into
a holding directory until the end of the transfer, at which time all the files are moved into place
in an attempt to make the updating of the files more atomic.
By default the files are placed into directory .~tmp~
in each file's destination directory. With
--partial-dir
that directory will be used instead.
See the comments in the --partial-dir
section for a discussion
of how this ".~tmp~" dir will be excluded from the transfer, and
what you can do if you want rsync to cleanup old tmp~
dirs that might be lying around.
Conflicts with --inplace
and --append
.
(1) there is no chance of any of the files in the transfer having the same name (since all the updated
files will be put into a single directory if the path is absolute)
and
(2) there are no mount points in the hierarchy (since the delayed updates will fail if they can't be renamed into place).
--inplace
Writes the updated data directly to the destination file instead of the Normal creating a copy of the file and moved into place when it is complete.
Effects:
Combine with --backup,
since rsync will use the backup file as the basis file for the transfer to prevent this.
--partial
(since an interrupted transfer does not delete the file),
Conflicts with --partial-dir
and --delay-updates
.
-W
--whole-file delta-transfer algorithm is not used.
The transfer may be faster if this option is used when the bandwidth between the
source and destination machines is higher than the bandwidth to
disk (example: when the "disk" is actually a networked filesystem).
Default when source and destination are local paths, if no batch writing option is in effect.
-S
--sparse Handle sparse files efficiently so they take up less space on the destination.
Conflicts with --inplace
as it is not possible to overwrite data in a sparse fashion.
-R
--relative Use relative paths.
The full path names specified on the command line are sent to the server rather than just the last parts of the filenames.
Useful when sending several different directories at the same time. For example:
creates file rsync -av /foo/bar/baz.c remote:/tmp/
/tmp/baz.c
.
creates rsync -avR /foo/bar/baz.c remote:/tmp/
/tmp/foo/bar/baz.c
preserving its full path.
To duplicate a server-side symlink, include both the symlink via its path, and referent directory via its real path.
Creates rsync -avR /foo/./bar/baz.c remote:/tmp/
/tmp/bar/baz.c
on the remote machine. (Note that the dot must be followed by a slash, so "/foo/." would not
--no-implied-dirs
affects the default behavior of --relative
.
The attributes of the implied directories from the source names are not included in the transfer.
This means that the corresponding path elements on the destination system are left unchanged if they exist, and any
missing implied directories are created with default attributes.
This allows these implied path elements to have big differences, such as being a symlink to a directory on the receiving side.
--relative
is used. If "path/foo" is a symlink to "bar" on the destination system, the
receiving rsync would ordinarily delete "path/foo", recreate it as a directory, and receive the file into the new directory.
With --no-implied-dirs
, the receiving rsync updates "path/foo/file" using the existing path elements, which means
that the file ends up being created in "path/bar".
Another way to accomplish this link preservation is to use the
--keep-dirlinks
option (which will also affect symlinks to directories in the rest of the transfer).
-b
--backup Preexisting destination files are renamed as
each file is transferred or deleted. Controls where the backup file goes and what (if any) suffix gets appended. Use
--backup-dir
and --suffix
(watch free space on destination).
--backup-dir
,
Prevents previously backed-up files from being deleted. If you
are supplying filter rules, insert own exclude/protect rule higher up in the
list so that it has a high enough priority to be effective (e.g., if your rules specify a trailing inclusion/exclusion of
'*', the auto-added rule would never be reached).
--omit-dir-times
will be implied, and
--delete
is also in effect (without --delete-excluded
), rsync will add a
"protect" filter-rule for the backup suffix to the end of all existing excludes (e.g. -f "P *~"
).
--backup-dir=DIR
In combination with --backup
, to
store all backups in the specified directory on the receiving
side. This can be used for incremental backups.
--suffix=SUFFIX
override the default backup suffix
used with --backup
.
Default suffix is ~
if no --backup-dir
was specified, otherwise it is an empty string.
-P
equivalent to --partial --progress
. Make it much easier to specify these two options for a long transfer that may be interrupted.
-d
--dirs
Tell the sending side to include any directories that are encountered. Unlike --recursive
, a directory's contents are not
copied unless the directory name specified is "." or ends with a trailing slash (e.g. ".", "dir/.", "dir/", etc.). Without this
option or --recursive
, rsync will skip all directories it encounters (and output a message to that effect for each
one).
Specifing both --dirs
and --recursive,
--recursive
takes precedence.
--dirs
is implied by --files-from
or --list-only
(including an implied --list-only
usage) if
Specify --no-dirs
to turn this off.
Link handling
skip to attribute handling
-l
--links recreate symlinks on the destination.
-L
--copy-links for symlinks, the item that they point to (the referent) is copied.
--copy-unsafe-links
copy the referent of symlinks that point outside the copied tree.
Absolute symlinks are treated like ordinary files, and as are symlinks in the source path itself when --relative
is used.
Has no additional effect if --copy-links
was also specified.
--safe-links
ignore any symbolic links which point outside the copied tree and absolute symlinks
With --relative
may give unexpected results.
-k
--copy-dirlinks sending side treats a symlink to a
directory as though it were a real directory.
Useful if you don't want symlinks to non-directories to be affected, as they would be using --copy-links
.
--force
or --delete
is in effect).
--keep-dirlinks
for an analogous option for the receiving side.
-K
--keep-dirlinks receiving side treats a symlink to a
directory as though it were a real directory, only if it matches a real directory from the sender.
Without this the receiver's symlink would be deleted and replaced with a real directory.
Without --keep-dirlinks,
the receiver deletes symlink "foo", recreates it as a directory, and receives the file into the new directory.
With --keep-dirlinks,
the receiver keeps the symlink and "file" ends up in "bar".
caution: when using --keep-dirlinks
, you must trust all the symlinks in the copy!
If it is possible for an untrusted user to create their own symlink to any directory, the user could then (on a subsequent copy)
replace the symlink with a real directory and affect the content of whatever directory the symlink references.
For backup copies, use a bind mount instead of a symlink to modify your receiving hierarchy. -H
--hard-links hard-linked files in the transfer are linked to the corresponding files on the receiving side.
Without this option, hard-linked files in the transfer are treated as though they were separate files.
Does NOT break existing hard links on the destination that do not exist between the source files.
If one or more extra-linked files have content changes, they will become unlinked when updated (if not using --inplace
).
Using --inplace
to avoid this breakage, there may be
unintended changes due to lingering hard links (see --inplace
).
This does not affect the accuracy of the transfer, just its efficiency,
To avoid this disable incremental recursion with --no-inc-recursive
Attributes, Meta-data, i.e. file permissions, Access Control Lists, owner, group …
-p
--perms set the destination permissions to be the same as the source permissions.
See --chmod
to modify what are considered to be the source permissions.--no--perms
:
--executability
might change the execute permission.)
umask
, or
the permissions specified via the destination directory's default AccessControlList.
Special mod
bits are disabled except where a new directory inherits setgid
from its parent.
To give new files the destination-default permissions (while leaving existing files
unchanged), use --no--perm
--chmod=ugo=rwX
--chmod
apply comma-separated chmod
strings to the permission of the files in the transfer.
as if they were the permissions supplied by the sender.
Can seem to have no effect on existing files if --perms
is not enabled.D
', or to a file if prefixed with 'F
'.
For example:
Multiple --chmod=Dg+s,ug+w,Fo-w,+X
--chmod
s are permitted.--perms
and --executability
for how the resulting permission value can be applied to the files in the transfer.
-E
--executability preserve the executability (or nonexecutability) of regular files when --perms
is not enabled.
A regular file is considered to be executable if at least one 'x' is turned on in its permissions. When an existing destination
file's executability differs from that of the corresponding source file, rsync modifies the destination file's permissions as follows:
-A
--acls update the ACLs, implies --perms
.
See --fake-super
to backup and restore ACLs that are not compatible.
-X
--xattrs update the remote extended attributes.
When done by super-user, copies all namespaces except system.*.
A normal user only copies the user.* namespace.
To to backup and restore non-user namespaces as a normal user, see --fake-super
.
-o
--owner Preserve owner (other than receiving user)
Default: the owner is set to the user on the receiving side.--super
and --fake-super
).
Caution: The preservation of ownership will associate matching names but if it falls back to using the ID number (see --numeric-ids
it will surely be incorrect!!.
-g
--groupPreserve group
If the receiving program is not running as the super-user (or if --no-super
was specified),
only groups that the invoking user on the receiving side is a member of will be preserved.
Without this option, the group is set to the default group of the invoking user on the receiving side. -t
--times preserve modification times (implied with --archive
).
If times are not preserved (in addition to corrupting the modification time on the destination) the next time a transfer is performed,
the evaluation which excludes files that have not been modified will be incorrect. The deltatransfer algorithm will minimize the update.
-O
--omit-dir-times omit directories when preserving modification times (see --times
).
Suggested if NFS is sharing the directories on the receiving side.
Implied with --backup
without --backup-dir
.
--super
receiving side attempts to execute super-user activities even if it wasn't run by the super-user.
Include: preserving users via the --owner
option,
preserving all groups (not just the current user's groups) via --groups
, and
copying devices via --devices
.
Useful for systems that allow such activities without being the super-user and
ensuring errors if the receiving side isn't being run as the super-user.
To turn off super-user activities, the super-user can use --no-super
.
--fake-super
simulate super-user activities by saving/restoring the privileged attributes via special extended attributes.
Includes the file's owner and group (if it is not the default), the file's device info (device & special files are
created as empty text files), and any permission bits that won't be allowed to be set on the real file (e.g. the real file gets
u-s,g-s,o-t for safety) or that would limit the owner's access
(since the real super-user can always access/change a file, the
files we create can always be accessed/changed by the creating user).
Handles ACLs (if --acls
was specified) and non-user extended attributes (if --xattrs
was specified).
backup data without using a super-user, and to store ACLs from incompatible systems.
Only affects the side where the option is used. To affect the remote side of a remote-shell connection, specify an rsync path:
There is only one "side" in a local copy, this affects both the sending and receiving of files.
Specify a copy using "localhost" to avoid this, possibly using the rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/
lsh
shell script (from the support directory)
as a substitute for an actual remote shell (see --rsh).--super
and --no-super
.fake super
in rsyncd.conf.
-x
--one-file-system avoid crossing a filesystem boundary when recursing.
This does not limit the ability to specify items to copy from multiple filesystems, just rsync's recursion
through the hierarchy of each directory that the user specified,
and also the analogous recursion on the receiving side during deletion.
A "bind" mount to the same device is considered being on the same filesystem.
Otherwise, it includes an empty directory at each mount-point it encounters (using the attributes of the
mounted directory because those of the underlying mount-point directory are inaccessible).--copy-links
or --copy-unsafe-links
), a symlink to a directory on another device
is treated like a mount-point. Symlinks to non-directories are unaffected by this option.
--existing,
--ignore-non-existing skip creating files and directories
that do not exist on the destination.
If combined with the --ignore-existing
, no files will be updated (useful to delete extraneous files).
--ignore-existing
skip updating files that already exist on
the destination (this does NOT ignore existing directories, or nothing would get done). See also --existing.
This is a transfer rule, not an exclude, so it doesn't affect the data that goes into the file-lists, and doesn't affect deletions.
It limits the files that the receiver requests to be transferred.
Useful for doing backups using --link-dest
when continung a n interrupted backup.
Since a --link-dest run is copied into a new directory hierarchy (when it is used properly),
using --ignore existing will ensure that the already-handled files don't get
tweaked (which avoids a change in permissions on the hard-linked files).
This does mean that this option is only looking at the existing files in the destination hierarchy itself.
Removing Files
--max-delete=N
Attempts to delete more than N
files or directories
results in a warning and exit with an error code 25 .--max-delete=0
generates warning about files in the destination without removing them.
Removing Files from the receiving side
--delete
files that aren't on the sending side for directories being synchronized.
It is expected that rsync previously sent the whole directory ( using dir
or dir/
) without
using a wildcard for the directory's contents (e.g. dir/*
)
(A wildcard is expanded by the shell and rsync gets a list of files, not the files' parent directory. )
Files excluded from the transfer are also excluded from being deleted unless --delete-excluded
or mark the rules as only matching on the sending side
See include/exclude modifiers .--dirs
is enabled for directories whose contents are being copied. --dry-run option
to see what files are going to be deleted.--delete-before, --delete-after, --prune-empty-dirs
, and --delay-updates.
The default with --delete
is --delete-during
(use --del --delete-during
to request this deletion mode explicitly).
--delete-delay
is a better choice than using --delete-after
.
Incremental recursion can be disabled using --no-inc-recursive
.
Especially useful with NFS errors on the sending side)
--delete-WHEN
options as well as --delete-excluded
.
Default is --delete-during
.
See --delete-delay
and --delete-after.
--delete-before
all deletions are done before any transfer starts.
See --delete
.
Introduces a delay before the start of the transfer which might cause the transfer to timeout
Forces non-incremental recursion algorithm that requires rsync to scan all the files in the transfer into
memory at once (see --recursive
).
--delete-during
--del File deletions are done as the transfer occurs.
The per-directory delete scan is done before each directory is checked for updates,
--delete-delay
File deletions are done after the transfer completes.
Useful when combined with --delay-updates
and/or --fuzzy
, and is more efficient
than using --delete-after
(can behave differently, since
--delete-after
computes the deletions in a separate pass after all updates are done).
If the number of removed files is very large a temporary file is created with the list. If it cannot be created rsync will use
--delete-after
(unless --recursive
is doing an incremental scan).
See --delete
.
--delete-after
file deletions are done after the transfer has completed.
Useful when sending new per-directory merge files as a part of the transfer and
you want their exclusions to take effect for the delete phase of the current transfer.
Forces rsync to use non-incremental recursion algorithm that requires rsync to scan all the file names in the transfer into memory at once.
--delete-excluded
In addition to deleting the files not present on the sending side,
delete files on the receiving side that are excluded (see --exclude).
See the FILTER RULES section for a way to make individual exclusions behave this way on the receiver, and for a way to protect
files from --delete-excluded
--force
Delete a directory when it is to be replaced by a file, `even if the directory contains files.
Only relevant if deletions are not active (see --delete for details).
--ignore-errors
--delete
deletes files even when there are I/O errors.Danger
remove from the sending side files successfully duplicated . (non-directories)
options to restrict activities
--max-size=bytes
Supress transferring files larger than bytes
.
may be a fractional (e.g. --max-size=1.5m
).
A transfer rule limits the files that the receiver requests to be transferred
not an exclude, doesn't affect the file-lists or deletions.
Suffixes (case insensitive)
+1
or -1
to offset by one byte.
--max-size=1.5mb-1
is 1,499,999 bytes, and
--max-size=2g+1
is 2,147,483,649 bytes.
--min-size=mb
avoid transferring any file that is smaller
than mb
, which can help in not transferring
small, junk files. See the --max-size option for a description of SIZE and other information.
-B
forces the block size in delta-transfer algorithm to a fixed value.
Selected based on the size of each file being updated. See technical report.
-e
--rsh=rmsh Remote shell for communication. default: ssh
prefer to use rsh on a local network.[user@]host::module/path
, the remote shell will be used to run an rsync daemon on the
remote host, and all data will be transmitted through that
remote shell connection, not a socket connection to a running rsync daemon on the remote host.
See using rsync-daemon features via a remote-shell connectionrmsh
provided that
is presented to rsync as a single argument.
Use spaces (not tabs or other whitespace) to separate rmsh
into the command and arguments.
Use apostrophe and/or quotes to preserve spaces in an argument (not backslashes).
Doubling an apostrophe inside a apostrophe'd string results in apostrophe ( likewise for quotes )
(attention to which quotes the shell is parsing and which quotes rsync is parsing). -e 'ssh -p 2234'
-e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"'
ssh
uses .ssh/config
for site specific options.
RSYNC_RSH
environment variable specifies remote shell program,
which accepts the same range of values as -e
.
See --blocking-io which is affected by this option.
--devices
character and block device files are created on remote system.
receiving rsync must be super-user (see also the --super and --fake-super options).
--specials
transfer special files such as named sockets and fifos.
-D
equivalent to --devices --specials
--rsync-path=fullName
When rsync is not in the remote path
e.g. --rsync-path=/usr/local/bin/rsync
.
fullName
is run with a shell and can be any program, script, or
command sequence , so long as it does not corrupt the standard-in &
standard-out that rsync is using to communicate.
To set a different default directory on the remote for use with --relative option
.
example:
rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/
options controling files to be transfered
-r
--recursive copy directories recursively. See --dirs .
-f
--filter=rule add rules to selectively include/exclude files. Useful in combination with a recursive transfer.
Multiple --filter
options are permitted.
If rule
contains whitespace, quote it.
An underscore can be used to replace the space that separates a rule from its arg. See FILTER RULES
-F
-F-F
Exclude .rsync-filter
files sprinkled through the hierarchy
and use their rules to filter the files.
.rsync-filter
files themselves .
--exclude=pattern
--exclude-from=file
file
contains exclude patterns (one per line).
Blank lines and lines starting with ;
or #
are ignored.
If FILE
is -
, the list will be read from standard input.
-C
--cvs-exclude
Exclude files that shouldn't be transfered, similar to CVS
These are marked perishable see filter rules
RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS
.make.state .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak
*.BAK *.orig *.rej .del-* *.a *.olb *.o *.obj *.so *.exe
*.Z *.elc *.ln core .svn/ .git/ .bzr/
CVSIGNORE
environment variable (delimited by whitespace).
$HOME/.cvsignore
.cvsignore
.cvsignore
These patterns are split on whitespace. See CVS --filter
rules with -C
CVS excludes are appended regardless of where the -C was placed on the commandline.
This makes them a lower priority than any rules specified explicitly.
To control where these get inserted into filter rules,
omit -C
as a command-line option and use a combination of
--filter=:C
and --filter=-C
(either on the command-line or by
putting the ":C" and "-C" rules into a filter file with other rules).
:C
turns on the per-directory scanning for the .cvsignore
file.
-C
does a one-time import of the CVS excludes.
--include=pattern
--include-from= file
as with