## "Fossies" - the Fresh Open Source Software Archive

### Source code changes of the file "rsync.1" betweenrsync-3.2.1.tar.gz and rsync-3.2.2.tar.gz

About: rsync is a fast incremental file-copying tool for bringing remote (and local) files into sync.

rsync.1  (rsync-3.2.1):rsync.1  (rsync-3.2.2)
skipping to change at line 366 skipping to change at line 366
--delete-delay find deletions during, delete after --delete-delay find deletions during, delete after
--delete-after receiver deletes after transfer, not during --delete-after receiver deletes after transfer, not during
--delete-excluded also delete excluded files from dest dirs --delete-excluded also delete excluded files from dest dirs
--ignore-missing-args ignore missing source args without error --ignore-missing-args ignore missing source args without error
--delete-missing-args delete missing source args from destination --delete-missing-args delete missing source args from destination
--ignore-errors delete even if there are I/O errors --ignore-errors delete even if there are I/O errors
--force force deletion of dirs even if not empty --force force deletion of dirs even if not empty
--max-delete=NUM don't delete more than NUM files --max-delete=NUM don't delete more than NUM files
--max-size=SIZE don't transfer any file larger than SIZE --max-size=SIZE don't transfer any file larger than SIZE
--min-size=SIZE don't transfer any file smaller than SIZE --min-size=SIZE don't transfer any file smaller than SIZE
--max-alloc=SIZE change a limit relating to memory alloc
--partial keep partially transferred files --partial keep partially transferred files
--partial-dir=DIR put a partially transferred file into DIR --partial-dir=DIR put a partially transferred file into DIR
--delay-updates put all updated files into place at end --delay-updates put all updated files into place at end
--prune-empty-dirs, -m prune empty directory chains from file-list --prune-empty-dirs, -m prune empty directory chains from file-list
--numeric-ids don't map uid/gid values by user/group name --numeric-ids don't map uid/gid values by user/group name
--groupmap=STRING custom groupname mapping --groupmap=STRING custom groupname mapping
--timeout=SECONDS set I/O timeout in seconds --timeout=SECONDS set I/O timeout in seconds
--contimeout=SECONDS set daemon connection timeout in seconds --contimeout=SECONDS set daemon connection timeout in seconds
skipping to change at line 469 skipping to change at line 470
option will only invoke --help when used without other options s ince it normally means --human- option will only invoke --help when used without other options s ince it normally means --human-
--version, -V --version, -V
Print the rsync version plus other info and exit. Print the rsync version plus other info and exit.
The output includes the default list of checksum algorithms, the default list of compression 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 algorithms, a list of compiled-in capabilities, a link to the rsync web site, and some
--verbose, -v --verbose, -v
This option increases the amount of information you are given duri ng the transfer. By default, This option increases the amount of information you are given duri ng the transfer. By default,
rsync works silently. A single -v will give you information ab out what files are being trans- rsync works silently. A single -v will give you information ab out what files are being trans-
ferred and a brief summary at the end. Two -v options will give y ou information on what files ferred and a brief summary at the end. Two -v options will give y ou information on what files
are being skipped and slightly more information at the end. More than two -v options should only are being skipped and slightly more information at the end. More than two -v options should only
be used if you are debugging rsync. be used if you are debugging rsync.
In a modern rsync, the -v option is equivalent to the setting of g roups of --info and --debug In a modern rsync, the -v option is equivalent to the setting of g roups of --info and --debug
options. You can choose to use these newer options in addition to, or in place of using --ver- options. You can choose to use these newer options in addition to, or in place of using --ver-
bose, as any fine-grained settings override the implied settings o f -v. Both --info and --debug bose, as any fine-grained settings override the implied settings o f -v. Both --info and --debug
skipping to change at line 538 skipping to change at line 537
--msgs2stderr --msgs2stderr
This option changes rsync to send all its output directly to stder r rather than to send messages This option changes rsync to send all its output directly to stder r rather than to send messages
to the client side via the protocol. The protocol allows rsyn c to output normal messages via to the client side via the protocol. The protocol allows rsyn c to output normal messages via
stdout and errors via stderr, but it can delay messages behind a s lew of data. stdout and errors via stderr, but it can delay messages behind a s lew of data.
One case where this is helpful is when sending really large files, since errors that happen on a 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 i s fully sent. It is also help- remote receiver tend to get delayed until after the file's data i s fully sent. It is also help-
ful for debugging, since it helps to avoid overpopulating the prot ocol data with extra message ful for debugging, since it helps to avoid overpopulating the prot ocol data with extra message
data. data.
The option does not e.g. The option does not affect the remote side of a transfer with out using --remote-option, e.g.
-M--msgs2stderr or {-M,}--msgs2stderr. -M--msgs2stderr or {-M,}--msgs2stderr.
Also keep in mind that connecting to a normal (non-remote-shell) d aemon does not have a stderr Also keep in mind that connecting to a normal (non-remote-shell) d aemon does not have a stderr
channel to send messages back to the client side, so a modern rs ync only allows the option on a channel to send messages back to the client side, so a modern rs ync only allows the option on a
remote-shell-run daemon. remote-shell-run daemon.
This option has the side-effect of making stderr output get line-b uffered so that the merging of This option has the side-effect of making stderr output get line-b uffered so that the merging of
the output of 3 programs happens in a more readable manner. the output of 3 programs happens in a more readable manner.
--quiet, -q --quiet, -q
skipping to change at line 607 skipping to change at line 606
list of the available files. The receiver generates its ch ecksums when it is scanning for list of the available files. The receiver generates its ch ecksums when it is scanning for
changed files, and will checksum any file that has the same size a s the corresponding sender's changed files, and will checksum any file that has the same size a s the corresponding sender's
file: files with either a changed size or a changed checksum are s elected for transfer. file: files with either a changed size or a changed checksum are s elected for transfer.
Note that rsync always verifies that each transferred file was correctly reconstructed on the Note that rsync always verifies that each transferred file was correctly reconstructed on the
receiving side by checking a whole-file checksum that is generated as the file is transferred, receiving side by checking a whole-file checksum that is generated as the file is transferred,
but that automatic after-the-transfer verification has nothing t o do with this option's before- but that automatic after-the-transfer verification has nothing t o do with this option's before-
the-transfer "Does this file need to be updated?" check. the-transfer "Does this file need to be updated?" check.
The checksum used is auto-negotiated between the client and the se rver, but can be overridden The checksum used is auto-negotiated between the client and the se rver, but can be overridden
using either the --checksum-choice option or an using either the --checksum-choice (--cc) option or an environmen
that is discussed in that t variable that is discussed in
option's section. that option's section.
--archive, -a --archive, -a
This is equivalent to -rlptgoD. It is a quick way of saying you w ant recursion and want to pre- This is equivalent to -rlptgoD. It is a quick way of saying you w ant recursion and want to pre-
serve almost everything (with -H being a notable omission). The only exception to the above serve 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. equivalence is when --files-from is specified, in which case -r is not implied.
Note that -a does not preserve hardlinks, because finding multipl y-linked files is expensive. Note that -a does not preserve hardlinks, because finding multipl y-linked files is expensive.
You must separately specify -H. You must separately specify -H.
--no-OPTION --no-OPTION
skipping to change at line 1240 skipping to change at line 1239
are specified as local paths, but only if no batch-writing option is in effect. are specified as local paths, but only if no batch-writing option is in effect.
--checksum-choice=STR, --cc=STR --checksum-choice=STR, --cc=STR
This option overrides the checksum algorithms. If one algorith m name is specified, it is used This option overrides the checksum algorithms. If one algorith m name is specified, it is used
for both the transfer checksums and (assuming --checksum is specif ied) the pre-transfer check- for both the transfer checksums and (assuming --checksum is specif ied) the pre-transfer check-
sums. If two comma-separated names are supplied, the first name affects the transfer checksums, sums. If two comma-separated names are supplied, the first name affects the transfer checksums,
and the second name affects the pre-transfer checksums (-c). and the second name affects the pre-transfer checksums (-c).
The checksum options that you may be able to use are: The checksum options that you may be able to use are:
o auto (the o auto (the default automatic choice)
o xxh128
o xxh3
o xxh64 (aka xxhash) o xxh64 (aka xxhash)
o md5 o md5
o md4 o md4
o none o none
Run rsync to see the default checksum list compiled into your Run rsync --version to see the default checksum list compiled into
from the list above).
If "none" is specified for the first (or only) name, the If "none" is specified for the first (or only) name, the --whole-
option is forced on and no file option is forced on and no
checksum verification is performed on the transferred data. If checksum verification is performed on the transferred data. If "n
is specified for the sec- one" is specified for the sec-
ond (or only) name, the --checksum option cannot be used. ond (or only) name, the --checksum option cannot be used.
The "auto" option is the default, where rsync bases its algorithm choice on a negotiation between The "auto" option is the default, where rsync bases its algorithm choice on a negotiation between
the client and the server as follows: the client and the server as follows:
both the are at least 3.2.0, When both sides of the transfer are at least 3.2.0, rsync chooses
the first algorithm in the
the first in the list that in client's list of choices that is also in the server's list of
choices. If no common checksum
choice is found, rsync exits with an error. If the remote rsync i
the s too old to support checksum
is to support checksum negotiation, negotiation, a value is chosen based on the protocol version (whic
a value is chosen based on h chooses between MD5 and vari-
the protocol version chooses between MD5 and ous flavors of MD4 based on protocol age).
of MD4 based on protocol
age). The default order can be customized by setting the environment var
iable RSYNC_CHECKSUM_LIST to a
can space-separated list of acceptable checksum names. If the string
by setting contains a "&" character, it is
to a space-separated list of checksum a separated into the "client string & server string", otherwise the
If no same string applies to both.
the This method does If the string (or string portion) contains no non-whitespace c
allow you to specify the haracters, the default checksum
checksum separately from the pre-transfer checksum, list is used. This method does not allow you to specify the trans
and it "auto" and all fer checksum separately from
checksum names. the pre-transfer checksum, and it discards "auto" and all unkno
wn checksum names. A list with
list only invalid names results in a failed negotiation.
The use of the --checksum-choice option overrides this environment list. The use of the --checksum-choice option overrides this environment list.
--one-file-system, -x --one-file-system, -x
This tells rsync to avoid crossing a filesystem boundary when recu rsing. This does not limit the This tells rsync to avoid crossing a filesystem boundary when recu rsing. This does not limit the
user's ability to specify items to copy from multiple filesystems, just rsync's recursion through user's 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 hierarchy of each directory that the user specified, and also
the analogous recursion on the the analogous recursion on the
receiving side during deletion. Also keep in mind that rsync receiving side during deletion. Also keep in mind that rsync tr
a "bind" mount to the same eats a "bind" mount to the same
device as being on the same filesystem. device as being on the same filesystem.
If this option is repeated, rsync omits all mount-point directorie s from the copy. Otherwise, it If this option is repeated, rsync omits all mount-point directorie s from the copy. Otherwise, it
includes the includes an empty directory at each mount-point it encounte rs (using the attributes of the
mounted directory because those of the underlying mount-point dire ctory are inaccessible). mounted directory because those of the underlying mount-point dire ctory are inaccessible).
If rsync has been told to collapse symlinks (via --copy-links or If rsync has been told to collapse symlinks (via --copy-links or -
to a directory on another device is treated like a mount-point. to a directory on another device is treated like a mount-point.
to non-directories are Symlinks to non-directories are
unaffected by this option. unaffected by this option.
--existing, --ignore-non-existing --existing, --ignore-non-existing
This tells rsync to skip creating files (including directories) th at do not exist yet on the des- This tells rsync to skip creating files (including directories) th at do not exist yet on the des-
tination. If this option is combined with the --ignore-existing o ption, no files will be updated tination. If this option is combined with the --ignore-existing o ption, no files will be updated
(which can be useful if all you want to do is delete extraneous fi les). (which can be useful if all you want to do is delete extraneous fi les).
This option is a transfer rule, not an exclude, so it doesn't This option is a transfer rule, not an exclude, so it doesn't affe
the data that goes into the ct the data that goes into the
file-lists, and thus it doesn't affect deletions. It just file-lists, and thus it doesn't affect deletions. It just lim
requests to be transferred. requests to be transferred.
--ignore-existing --ignore-existing
This not This tells rsync to skip updating files that already exist on the destination (this does not
This option is a transfer rule, not an exclude, so it doesn't This option is a transfer rule, not an exclude, so it doesn't aff
the data that goes into the ect the data that goes into the
file-lists, and thus it doesn't affect deletions. It just file-lists, and thus it doesn't affect deletions. It just limits
requests to be transferred. requests to be transferred.
This option can be useful for those doing backups using the This option can be useful for those doing backups using the --lin
option when they need to k-dest option when they need to
continue a backup run that got interrupted. Since a --link-dest continue a backup run that got interrupted. Since a --link-dest r
is copied into a new direc- un is copied into a new direc-
tory hierarchy (when it is used properly), using tory hierarchy (when it is used properly), using --ignore-existin
handled files don't get tweaked (which avoids a change in handled files don't get tweaked (which avoids a change in permissi
This does mean that this option is only looking at the existing This does mean that this option is only looking at the existing f
in the destination hierar- iles in the destination hierar-
chy itself. chy itself.
--remove-source-files --remove-source-files
This a This tells rsync to remove from the sending side the files (meanin g non-directories) that are a
part of the transfer and have been successfully duplicated on the receiving side. part of the transfer and have been successfully duplicated on the receiving side.
Note that you should only use this option on source files that Note that you should only use this option on source files that a
quiescent. If you are using re quiescent. If you are using
this to move files that show up in a particular directory over this to move files that show up in a particular directory over to
to another host, make sure that another host, make sure that
the finished files get renamed into the source directory, not the finished files get renamed into the source directory, not di
written into it, so that rectly written into it, so that
rsync can't possibly transfer a file that is not yet fully written . If you can't first write the rsync can't possibly transfer a file that is not yet fully written . If you can't first write the
files into a different directory, you should use a naming idiom files into a different directory, you should use a naming idiom
lets rsync avoid transfer- that lets rsync avoid transfer-
ring files that are not yet finished (e.g. name the file ring files that are not yet finished (e.g. name the file "foo.new"
when it is written, rename it when it is written, rename it
to "foo" when it is done, and then use the option --exclude='*.new ' for the rsync transfer). to "foo" when it is done, and then use the option --exclude='*.new ' for the rsync transfer).
Starting file's Starting with 3.1.0, rsync will skip the sender-side removal (and output an error) if the file's
size or modify time has not stayed unchanged. size or modify time has not stayed unchanged.
--delete --delete
This tells rsync to delete extraneous files from the This tells rsync to delete extraneous files from the receiving sid
(ones that aren't on the e (ones that aren't on the
sending side), but only for the directories that are being sending side), but only for the directories that are being syn
rsync to send the whole directory (e.g. "dir" or "dir/") without rsync to send the whole directory (e.g. "dir" or "dir/") without u
a wildcard for the direc- sing a wildcard for the direc-
tory's contents (e.g. "dir/*") since the wildcard is expanded by tory's contents (e.g. "dir/*") since the wildcard is expanded by
shell and rsync thus gets a the shell and rsync thus gets a
request to transfer individual files, not the files' parent request to transfer individual files, not the files' parent direct
Files that are excluded ory. Files that are excluded
from the transfer are also excluded from being deleted from the transfer are also excluded from being deleted unles
use the --delete-excluded s you use the --delete-excluded
option or mark the rules as only matching on the sending side option or mark the rules as only matching on the sending side (see
the include/exclude modifiers the include/exclude modifiers
in the FILTER RULES section). in the FILTER RULES section).
Prior to rsync 2.6.7, this option would have no effect unless --re cursive was enabled. Beginning Prior to rsync 2.6.7, this option would have no effect unless --re cursive was enabled. Beginning
with 2.6.7, deletions will also occur when --dirs (-d) is enabled, but only for directories whose with 2.6.7, deletions will also occur when --dirs (-d) is enabled, but only for directories whose
contents are being copied. contents are being copied.
This option can be dangerous if used incorrectly! It is a very goo d idea to first try a run using This option can be dangerous if used incorrectly! It is a very goo d idea to first try a run using
the --dry-run option (-n) to see what files are going to be delete d. the --dry-run option (-n) to see what files are going to be delete d.
If the sending side detects any I/O errors, then the deletion If the sending side detects any I/O errors, then the deletion of a
of files at the destination ny files at the destination
will be automatically disabled. This is to prevent temporary will be automatically disabled. This is to prevent temporary f
failures (such as NFS ilesystem failures (such as NFS
errors) on the sending side from causing a massive deletion of fil es on the destination. You can errors) on the sending side from causing a massive deletion of fil es on the destination. You can
override this with the --ignore-errors option. override this with the --ignore-errors option.
The --delete option may be combined with one of the The --delete option may be combined with one of the --delete-WH
options without conflict, as EN options without conflict, as
well as --delete-excluded. However, if none of the well as --delete-excluded. However, if none of the --delete-WHEN
options are specified, rsync options are specified, rsync
will choose the --delete-during algorithm when talking to rsync 3. 0.0 or newer, and the --delete- will choose the --delete-during algorithm when talking to rsync 3. 0.0 or newer, and the --delete-
before algorithm when talking to an older rsync. See also --delet e-delay and --delete-after. before algorithm when talking to an older rsync. See also --delet e-delay and --delete-after.
--delete-before --delete-before
Request See Request that the file-deletions on the receiving side be done befo re the transfer starts. See
--delete (which is implied) for more details on file-deletion. --delete (which is implied) for more details on file-deletion.
Deleting before the transfer is helpful if the filesystem is Deleting before the transfer is helpful if the filesystem is tigh
for space and removing extra- t for space and removing extra-
neous files would help to make the transfer possible. However, neous files would help to make the transfer possible. However, it
does introduce a delay before does introduce a delay before
the start of the transfer, and this delay might cause the the start of the transfer, and this delay might cause the transf
to timeout (if --timeout was er to timeout (if --timeout was
specified). It also forces rsync to use the old, specified). It also forces rsync to use the old, non-incremen
recursion algorithm that tal recursion algorithm that
requires rsync to scan all the files in the transfer into memory a t once (see --recursive). requires rsync to scan all the files in the transfer into memory a t once (see --recursive).
--delete-during, --del --delete-during, --del
Request that the file-deletions on the receiving side be done Request that the file-deletions on the receiving side be done inc
as the transfer hap- rementally as the transfer hap-
pens. The per-directory delete scan is done right before each pens. The per-directory delete scan is done right before each dir
so it behaves like a more efficient --delete-before, including so it behaves like a more efficient --delete-before, including d
the deletions prior to any oing the deletions prior to any
per-directory filter files being updated. This option was per-directory filter files being updated. This option was first a
in rsync version 2.6.4. dded in rsync version 2.6.4.
See --delete (which is implied) for more details on file-deletion. See --delete (which is implied) for more details on file-deletion.
--delete-delay --delete-delay
Request that the file-deletions on the receiving side be Request that the file-deletions on the receiving side be com
during the transfer (like puted during the transfer (like
--delete-during), and then removed after the transfer --delete-during), and then removed after the transfer completes.
This is useful when combined This is useful when combined
with --delay-updates and/or --fuzzy, and is more efficient with --delay-updates and/or --fuzzy, and is more efficient tha
--delete-after (but can n using --delete-after (but can
behave differently, since --delete-after computes the behave differently, since --delete-after computes the deletions in
in a separate pass after all a separate pass after all
updates are done). If the number of removed files overflows an in ternal buffer, a temporary file updates are done). If the number of removed files overflows an in ternal buffer, a temporary file
will be created on the receiving side to hold the names will be created on the receiving side to hold the names (it is
is removed while open, so you removed while open, so you
shouldn't see it during the transfer). If the creation of the shouldn't see it during the transfer). If the creation of the t
file fails, rsync will emporary file fails, rsync will
try to fall back to using --delete-after (which it cannot do if -- recursive is doing an incremen- try to fall back to using --delete-after (which it cannot do if -- recursive is doing an incremen-
tal scan). See --delete (which is implied) for more details on fi le-deletion. tal scan). See --delete (which is implied) for more details on fi le-deletion.
--delete-after --delete-after
Request completed. Request that the file-deletions on the receiving side be done af ter the transfer has completed.
This is useful if you are sending new per-directory merge files as a part of the transfer and you This is useful if you are 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 want their exclusions to take effect for the delete phase of
current transfer. It also the current transfer. It also
forces rsync to use the old, non-incremental recursion algorithm forces rsync to use the old, non-incremental recursion algorithm t
requires rsync to scan all hat requires rsync to scan all
the files in the transfer into memory at once (see --recursive). the files in the transfer into memory at once (see --recursive).
--delete (which is implied) See --delete (which is implied)
for more details on file-deletion. for more details on file-deletion.
--delete-excluded --delete-excluded
In addition to deleting the files on the receiving side that In addition to deleting the files on the receiving side that are n
on the sending side, this ot on the sending side, this
tells rsync to also delete any files on the receiving side tells rsync to also delete any files on the receiving side tha
excluded (see --exclude). t are excluded (see --exclude).
See the FILTER RULES section for a way to make individual See the FILTER RULES section for a way to make individual exclusi
behave this way on the ons behave this way on the
receiver, and for a way to protect files from --delete-excluded. See --delete (which is implied) receiver, and for a way to protect files from --delete-excluded. See --delete (which is implied)
for more details on file-deletion. for more details on file-deletion.
--ignore-missing-args --ignore-missing-args
When argu- When rsync is first processing the explicitly requested source fil es (e.g. command-line argu-
ments or --files-from entries), it is normally an error if the fil e cannot be found. This option ments or --files-from entries), it is normally an error if the fil e cannot be found. This option
suppresses subsequent suppresses that error, and does not try to transfer the file. Thi s does not affect subsequent
vanished-file errors if a file was initially found to be present a nd later is no longer there. vanished-file errors if a file was initially found to be present a nd later is no longer there.
--delete-missing-args --delete-missing-args
This option takes the behavior of (the implied) --ignore-missing-a rgs option a step farther: each This option takes the behavior of (the implied) --ignore-missing-a rgs option a step farther: each
missing arg will become a deletion request of the corresponding de stination file on the receiving missing arg will become a deletion request of the corresponding de stination file on the receiving
side suc- side (should it exist). If the destination file is a non-empty directory, it will only be suc-
cessfully deleted if --force or --delete are in effect. Other tha n that, this option is indepen- cessfully deleted if --force or --delete are in effect. Other tha n that, this option is indepen-
dent of any other type of delete processing. dent of any other type of delete processing.
The "*miss- The missing source files are represented by special file-list ent ries which display as a "*miss-
ing" entry in the --list-only output. ing" entry in the --list-only output.
--ignore-errors --ignore-errors
Tells --delete to go ahead and delete files even when there are I/ O errors. Tells --delete to go ahead and delete files even when there are I/ O errors.
--force --force
This option tells rsync to delete a non-empty directory when it is to be replaced by a non-direc- This option tells rsync to delete a non-empty directory when it is to be replaced by a non-direc-
tory. This is only relevant if deletions are not active (see --de lete for details). tory. This is only relevant if deletions are not active (see --de lete for details).
Note and Note for older rsync versions: --force used to still be required when using --delete-after, and
it used to be non-functional unless the --recursive option was als o enabled. it used to be non-functional unless the --recursive option was als o enabled.
--max-delete=NUM --max-delete=NUM
This tells rsync not to delete more than NUM files or This tells rsync not to delete more than NUM files or directories.
If that limit is exceeded, If that limit is exceeded,
all further deletions are skipped through the end of the all further deletions are skipped through the end of the transfe
At the end, rsync outputs a r. At the end, rsync outputs a
warning (including a count of the skipped deletions) and exits warning (including a count of the skipped deletions) and exits wit
an error code of 25 (unless h an error code of 25 (unless
some more important error condition also occurred). some more important error condition also occurred).
Beginning extraneous Beginning with version 3.0.0, you may specify --max-delete=0 to be warned about any extraneous
files in the destination without removing any of them. Older clie nts interpreted this as "unlim- files in the destination without removing any of them. Older clie nts interpreted this as "unlim-
ited", --max- ited", so if you don't know what version the client is, you can use the less obvious --max-
delete=-1 as a backward-compatible way to specify that no deletion s be allowed (though really old delete=-1 as a backward-compatible way to specify that no deletion s be allowed (though really old
versions didn't warn when the limit was exceeded). versions didn't warn when the limit was exceeded).
--max-size=SIZE --max-size=SIZE
This tells rsync to avoid transferring any file that is larger tha n the specified SIZE. The SIZE This tells rsync to avoid transferring any file that is larger tha n the specified SIZE. The SIZE
value value value can be suffixed with a string to indicate a size multiplier, and may be a fractional value
(e.g. --max-size=1.5m). (e.g. --max-size=1.5m).
This option is a transfer rule, not an exclude, so it doesn't This option is a transfer rule, not an exclude, so it doesn't aff
the data that goes into the ect the data that goes into the
file-lists, and thus it doesn't affect deletions. It just file-lists, and thus it doesn't affect deletions. It just limits
requests to be transferred. requests to be transferred.
The The accepted suffix letters are: B, K, G, T, and P fo
r bytes, kilobytes/kibibytes,
and "G" a megabytes/mebibytes, gigabytes/gibibytes, terabytes/tebibytes, and
you be petabytes/pebibytes. If you
of lower-case use a single-char suffix or add-on "ib" to it (e.g. "G" or "Gi
B") then you get units that are
Finally, if the ends either "+1" or "-1", multiples of 1024. If you use a two-letter suffix that ends with
offset by one byte in a "B" (e.g. "kb") then you get
the indicated direction. units that are multiples of 1000. The suffix letters can be any m
ix of upper and lower-case that
you want to use.
Finally, if the string ends with either "+1" or "-1", it is offset
by one byte in the indicated
direction. The largest possible value is 8192P-1.
Examples: --max-size=1.5mb-1 is 1499999 bytes, and --max-size=2g+1 is 2147483649 bytes. Examples: --max-size=1.5mb-1 is 1499999 bytes, and --max-size=2g+1 is 2147483649 bytes.
Note that rsync versions prior to 3.1.0 did not allow --max-size=0 . Note that rsync versions prior to 3.1.0 did not allow --max-size=0 .
--min-size=SIZE --min-size=SIZE
This tells rsync to avoid transferring any file that is smaller This tells rsync to avoid transferring any file that is smaller
the specified SIZE, which than the specified SIZE, which
can help in not transferring small, junk files. See the can help in not transferring small, junk files. See the --max-siz
option for a description of e option for a description of
SIZE and other information. SIZE and other information.
Note that rsync versions prior to 3.1.0 did not allow --min-size=0 . Note that rsync versions prior to 3.1.0 did not allow --min-size=0 .
--max-alloc=SIZE
By default rsync limits an individual malloc/realloc to about 1GB
in size. For most people this
limit works just fine and prevents a protocol error causing rsync
to request massive amounts of
memory. However, if you have many millions of files in a transfer
, a large amount of server mem-
ory, and you don't want to split up your transfer into multiple pa
rts, you can increase the per-
allocation limit to something larger and rsync will consume more m
emory.
Keep in mind that this is not a limit on the total size of all
ocated memory. It is a sanity-
check value for each individual allocation.
See the --max-size option for a description of how SIZE can be spe
cified. The default suffix if
none is given is bytes.
You can set a default value using the environment variable RSYN
C_MAX_ALLOC using the same SIZE
values as supported by this option. If the remote rsync doesn'
t understand the --max-alloc
option, you can override an environmental value by specifying
--max-alloc=1g, which will make
rsync avoid sending the option to the remote side (because "1G" is
the default).
--block-size=SIZE, -B --block-size=SIZE, -B
This forces the block size used in rsync's delta-transfer algorith m to a fixed value. It is nor- This forces the block size used in rsync's delta-transfer algorith m to a fixed value. It is nor-
mally selected based on the size of each file being updated . See the technical report for mally selected based on the size of each file being updated . See the technical report for
details. details.
--rsh=COMMAND, -e --rsh=COMMAND, -e
This option allows you to choose an alternative remote shell progr am to use for communication This option allows you to choose an alternative remote shell progr am to use for communication
between the local and remote copies of rsync. Typically, rs ync is configured to use ssh by between the local and remote copies of rsync. Typically, rs ync is configured to use ssh by
default, but you may prefer to use rsh on a local network. default, but you may prefer to use rsh on a local network.
skipping to change at line 1696 skipping to change at line 1722
You may also control this option via the RSYNC_PROTECT_ARGS envir onment variable. If this vari- You may also control this option via the RSYNC_PROTECT_ARGS envir onment variable. If this vari-
able has a non-zero value, this option will be enabled by default, otherwise it will be disabled able has a non-zero value, this option 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 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 neg ative versions). Since this this option (note that --no-s and --no-protect-args are the neg ative versions). Since this
option was first introduced in 3.0.0, you'll need to make sure it 's disabled if you ever need to option was first introduced in 3.0.0, you'll need to make sure it 's disabled if you ever need to
interact with a remote rsync that is older than that. interact with a remote rsync that is older than that.
Rsync can also be configured (at build time) to have this option enabled by default (with is Rsync can also be configured (at build time) to have this option enabled by default (with is
overridden by both the environment and the command-line). Run r overridden by both the environment and the command-line). Run r
sync to check if this is the sync --version to check if this
case, as it will display "default protect-args" or is the case, as it will display "default protect-args" or "optiona
depending on how it l protect-args" depending on
was compiled. how it was compiled.
This option will eventually become a new default setting at some a s-yet-undetermined point in the This option will eventually become a new default setting at some a s-yet-undetermined point in the
future. future.
--copy-as=USER[:GROUP] --copy-as=USER[:GROUP]
This option instructs rsync to use the USER and (if specified afte r a colon) the GROUP for the This option instructs rsync to use the USER and (if specified afte r a colon) the GROUP for the
copy operations. This only works if the user that is running rsync has the ability to change copy operations. This only works if the user that is running rsync has the ability to change
users. If the group is not specified then the user's default grou ps are used. users. If the group is not specified then the user's default grou ps are used.
This option can help to reduce the risk of an rsync being run as r oot into or out of a directory This option can help to reduce the risk of an rsync being run as r oot into or out of a directory
skipping to change at line 1848 skipping to change at line 1874
and --copy-dest. and --copy-dest.
Note that rsync versions prior to 2.6.1 had a bug that could p revent --link-dest from working Note that rsync versions prior to 2.6.1 had a bug that could p revent --link-dest from working
properly for a non-super-user when -o was specified (or implied by -a). You can work-around this properly for a non-super-user when -o was specified (or implied by -a). You can work-around this
bug by avoiding the -o option when sending to an old rsync. bug by avoiding the -o option when sending to an old rsync.
--compress, -z --compress, -z
With this option, rsync compresses the file data as it is sent to the destination machine, which With this option, rsync compresses the file data as it is sent to the destination machine, which
reduces the amount of data being transmitted -- something that is useful over a slow connection. reduces the amount of data being transmitted -- something that is useful over a slow connection.
compression Rsync supports multiple compression methods and will choose one fo
r you unless you force the
choice using the --compress-choice (--zc) option.
and
the
the
Run rsync --version to see the default compress list compiled into
rsync to
the
See the --skip-compress option for the default list of file When both sides of the transfer are at least 3.2.0, rsync cho
that will oses the first algorithm in the
client's list of choices that is also in the server's list of choi
ces. If no common compress
choice is found, rsync exits with an error. If the remote rsync
is too old to support checksum
negotiation, its list is assumed to be "zlib".
The default order can be customized by setting the environment var
iable RSYNC_COMPRESS_LIST to a
space-separated list of acceptable compression names. If the stri
ng contains a "&" character, it
is separated into the "client string & server string", otherwise t
he same string applies to both.
If the string (or string portion) contains no non-whitespace c
haracters, the default compress
list is used. Any unknown compression names are discarded from th
e list, but a list with only
invalid names results in a failed negotiation.
There are some older rsync versions that were configured to rej
ect a -z option and require the
use of -zz because their compression library was not compatible wi
th the default zlib compression
method. You can usually ignore this weirdness unless the rsync se
rver complains and tells you to
specify -zz.
See also the --skip-compress option for the default list of file s
uffixes that will trasnferred
with no (or minimal) compression.
--compress-choice=STR, --zc=STR --compress-choice=STR, --zc=STR
This option can be used to override the automatic of This option can be used to override the automatic negotiation of
compression algorithm that the compression algorithm that
when --compress is used. occurs when --compress is used. The option implies --compress unl
ess "none" was specified, which
The compression options that you may be able to use are: The compression options that you may be able to use are:
o zstd o zstd
o lz4 o lz4
o zlibx o zlibx
o zlib o zlib
o none o none
Run rsync to see the compress list compiled into your Run rsync --version to see the default compress list compiled into
from the list above).
Note that if you see an error about an option named --old-compress
or --new-compress, this is
rsync trying to send the --compress-choice=zlib or --compress-cho
ice=zlibx option in a backward-
compatible manner that more rsync versions understand. This error
indicates that the older rsync
version on the server will not allow you to force the compression
type.
"zlibx" algorithm is Note that the "zlibx" compression algorithm is just the "zl
the ib" algorithm with matched data
excluded from the compression stream (to try to make it more compa
tible with an external zlib
implementation).
matched data
the compression
to
it
with an
--compress-level=NUM, --zl=NUM --compress-level=NUM, --zl=NUM
Explicitly set the compression level to use (see --compress, -z) instead of letting it default. Explicitly set the compression level to use (see --compress, -z) instead of letting it default.
The --compress option is implied as long as the level chosen is no t a "don't compress" level for The --compress option is implied as long as the level chosen is no t a "don't compress" level for
the compression algorithm that is in effect (e.g. zlib compression treats level 0 as "off"). the compression algorithm that is in effect (e.g. zlib compression treats level 0 as "off").
The level values vary depending on the checksum in effect. Becaus e rsync will negotiate a check- The level values vary depending on the checksum in effect. Becaus e rsync will negotiate a check-
sum choice by default the remote rsync is new it sum choice by default (when the remote rsync is new enough), it c
be good to combine this option an be good to combine this
with a --compress-choice (--zc) option unless you're of the option with a --compress-choice (--zc) option unless you're sur
in effect. For example: e of the choice in effect. For
example:
rsync -aiv --zc=zstd --zl=22 host:src/ dest/ rsync -aiv --zc=zstd --zl=22 host:src/ dest/
For zlib & zlibx compression the valid values are from 1 to 9 with 6 being the default. Specify- For zlib & zlibx compression the valid values are from 1 to 9 with 6 being the default. Specify-
ing 0 turns compression off, and specifying -1 chooses the default of 6. ing 0 turns compression off, and specifying -1 chooses the default of 6.
For zstd compression the valid values are from -131072 to 22 with 3 being the default. Specifying For zstd compression the valid values are from -131072 to 22 with 3 being the default. Specifying
0 chooses the default of 3. 0 chooses the default of 3.
For lz4 compression there are no levels, so the value is always 0. For lz4 compression there are no levels, so the value is always 0.
If you specify a too-large or too-small value, the number is If you specify a too-large or too-small value, the number is silen
limited to a valid value. tly limited to a valid value.
This allows you to specify something like --zl=999999999 and be This allows you to specify something like --zl=999999999 and be
that you'll end up with assured that you'll end up with
the maximum compression level no matter what algorithm was chosen. the maximum compression level no matter what algorithm was chosen.
If you want to know the compression level that is in effect, If you want to know the compression level that is in effect, spec
--debug=nstr to see the ify --debug=nstr to see the
"negotiated string" results. This will report something like "C "negotiated string" results. This will report something like "C
lient compress: zstd (level 3)" lient compress: zstd (level 3)"
(along with the checksum choice in effect). (along with the checksum choice in effect).
--skip-compress=LIST --skip-compress=LIST
Override the list of file suffixes that will be compressed as litt le as possible. Rsync sets the Override the list of file suffixes that will be compressed as litt le as possible. Rsync sets the
compression level on a per-file basis based on the file's compression level on a per-file basis based on the file's suffix
If the compression algorithm . If the compression algorithm
has an "off" level (such as zlib/zlibx) then no compression has an "off" level (such as zlib/zlibx) then no compression occurs
for those files. Other algo- for those files. Other algo-
rithms have the level minimized to reduces the CPU usage as much a rithms that support changing the streaming level on-the-fly w
ill have the level minimized to
reduces the CPU usage as much as possible for a matching file. At
this time, only zlib & zlibx
compression support this changing of levels on a per-file basis.
The LIST should be one or more file suffixes (without the dot) sep arated by slashes (/). You may The LIST should be one or more file suffixes (without the dot) sep arated by slashes (/). You may
specify an empty string to indicate that no files should be skippe d. specify an empty string to indicate that no files should be skippe d.
Simple the Simple character-class matching is supported: each must consist of a list of letters inside the
square brackets (e.g. no special classes, such as "[:alpha:]", are supported, and '-' has no spe- square brackets (e.g. no special classes, such as "[:alpha:]", are supported, and '-' has no spe-
cial meaning). cial meaning).
The characters asterisk (*) and question-mark (?) have no special meaning. The characters asterisk (*) and question-mark (?) have no special meaning.
Here's an example that specifies 6 suffixes to skip (since 1 of th e 5 rules matches 2 suffixes): Here's an example that specifies 6 suffixes to skip (since 1 of th e 5 rules matches 2 suffixes):
--skip-compress=gz/jpg/mp[34]/7z/bz2 --skip-compress=gz/jpg/mp[34]/7z/bz2
The default file suffixes in the skip-compress list in this versio n of rsync are: The default file suffixes in the skip-compress list in this versio n of rsync are:
7z odf 7z ace apk avi bz2 deb flac gpg gz iso jar jpeg jpg lz lz4 lzm a lzo mkv mov mp3 mp4 odb odf
odg odi odm odp ods odt ogg ogv opus otg oth otp ots ott oxt p ng rar rpm rz rzip squashfs sxc odg odi odm odp ods odt ogg ogv opus otg oth otp ots ott oxt p ng rar rpm rz rzip squashfs sxc
sxd sxg sxm sxw tbz tgz tlz txz tzo webm webp xz z zip zst sxd sxg sxm sxw tbz tgz tlz txz tzo webm webp xz z zip zst
This list will be replaced by your --skip-compress list in all This list will be replaced by your --skip-compress list in all but
one situation: a copy from a one situation: a copy from a
daemon rsync will add your skipped suffixes to its list of daemon rsync will add your skipped suffixes to its list of non-
files (and its list compressing files (and its list
may be configured to a different default). may be configured to a different default).
--numeric-ids --numeric-ids
With group With this option rsync will transfer numeric group and user IDs ra ther than using user and group
names and mapping them at both ends. names and mapping them at both ends.
By default rsync will use the username and groupname to By default rsync will use the username and groupname to determin
what ownership to give files. e what ownership to give files.
The special uid 0 and the special group 0 are never mapped The special uid 0 and the special group 0 are never mapped via u
names even if the ser/group names even if the
--numeric-ids option is not specified. --numeric-ids option is not specified.
If a user or group has no name on the source system or it has no m atch on the destination system, If a user or group has no name on the source system or it has no m atch on the destination system,
then the then the numeric ID from the source system is used instead. Se e also the comments on the
"use chroot" setting in the rsyncd.conf manpage for information on how the chroot setting affects "use chroot" setting in the rsyncd.conf manpage for information on how the chroot setting affects
rsync's ability to look up the names of the users and groups and w hat you can do about it. rsync's ability to look up the names of the users and groups and w hat you can do about it.
--usermap=STRING, --groupmap=STRING --usermap=STRING, --groupmap=STRING
These options allow you to specify users and groups that should These options allow you to specify users and groups that should be
mapped to other values by the mapped to other values by the
receiving side. The STRING is one or more FROM:TO pairs of receiving side. The STRING is one or more FROM:TO pairs of v
separated by commas. Any alues separated by commas. Any
matching FROM value from the sender is replaced with a TO value fr om the receiver. You may spec- matching FROM value from the sender is replaced with a TO value fr om the receiver. You may spec-
ify wild-card ify usernames or user IDs for the FROM and TO values, and the FRO M value may also be a wild-card
string, which will be matched against the sender's names (wild-car ds do NOT match against ID num- string, which will be matched against the sender's names (wild-car ds do NOT match against ID num-
bers, ID bers, though see below for why a '*' matches everything). You ma y instead specify a range of ID
numbers via an inclusive range: LOW-HIGH. For example: numbers via an inclusive range: LOW-HIGH. For example:
The mappings The first match in the list is the one that is used. You should s pecify all your user mappings
using a single --usermap option, and/or all your group mappings us ing a single --groupmap option. using a single --usermap option, and/or all your group mappings us ing a single --groupmap option.
Note that the sender's name for the 0 user and group are not Note that the sender's name for the 0 user and group are not tran
should either match these values using a 0, or use the names should either match these values using a 0, or use the names in e
in on the receiving side ffect on the receiving side
(typically "root"). All other FROM names match those in use on (typically "root"). All other FROM names match those in use on
sending side. All TO names the sending side. All TO names
match those in use on the receiving side. match those in use on the receiving side.
Any IDs that do not have a name on the sending side are treated Any IDs that do not have a name on the sending side are treated as
as having an empty name for the having an empty name for the
purpose of matching. This allows them to be matched via a or purpose of matching. This allows them to be matched via a "
using an empty name. For *" or using an empty name. For
instance: instance:
--usermap=:nobody --groupmap=*:nobody --usermap=:nobody --groupmap=*:nobody
When are When the --numeric-ids option is used, the sender does not send an y names, so all the IDs are
treated as having an empty name. This means that you will need to specify numeric FROM values if treated as having an empty name. This means that you will need to specify numeric FROM values if
you want to map these nameless IDs to different values. you want to map these nameless IDs to different values.
For implied), For the --usermap option to have any effect, the -o (--owner) opti on must be used (or implied),
and the receiver will need to be running as a super-user (see also the --fake-super option). For 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 implied), and the --groupmap 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. the receiver will need to have permissions to set that group.
--chown=USER:GROUP --chown=USER:GROUP
This option forces all files to be owned by USER with group This option forces all files to be owned by USER with group GROU
This is a simpler interface P. This is a simpler interface
than using --usermap and --groupmap directly, but it is than using --usermap and --groupmap directly, but it is implemente
using those options inter- d using those options inter-
nally, so you cannot mix them. If either the USER or GROUP is nally, so you cannot mix them. If either the USER or GROUP is em
no mapping for the omitted pty, no mapping for the omitted
user/group will occur. If GROUP is empty, the trailing colon user/group will occur. If GROUP is empty, the trailing colon may
may be omitted, but if USER is be omitted, but if USER is
empty, a leading colon must be supplied. empty, a leading colon must be supplied.
If specifying 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.
--timeout=SECONDS --timeout=SECONDS
This for This option allows you to set a maximum I/O timeout in seconds. I f no data is transferred for
the specified time then rsync will exit. The default is 0, which means no timeout. the specified time then rsync will exit. The default is 0, which means no timeout.
--contimeout=SECONDS --contimeout=SECONDS
This an This option allows you to set the amount of time that rsync wil l wait for its connection to an
rsync daemon to succeed. If the timeout is reached, rsync exits w ith an error. rsync daemon to succeed. If the timeout is reached, rsync exits w ith an error.
By default rsync will bind to the wildcard address when By default rsync will bind to the wildcard address when connectin
to an rsync daemon. The g to an rsync daemon. The
this option in the --daemon mode section. this option in the --daemon mode section.
--port=PORT --port=PORT
This specifies an alternate TCP port number to use rather than This specifies an alternate TCP port number to use rather than the
default of 873. This is only default of 873. This is only
needed if you are using the double-colon (::) syntax to connect needed if you are using the double-colon (::) syntax to connect
an rsync daemon (since the with an rsync daemon (since the
URL syntax has a way to specify the port as a part of the URL syntax has a way to specify the port as a part of the URL). S
also this option in the ee also this option in the
--daemon mode section. --daemon mode section.
--sockopts=OPTIONS --sockopts=OPTIONS
This option can provide endless fun for people who like to This option can provide endless fun for people who like to t
their systems to the utmost une their systems to the utmost
degree. You can set all sorts of socket options which may make degree. You can set all sorts of socket options which may make tr
faster (or slower!). ansfers faster (or slower!).
Read the man page for the setsockopt() system call for details on Read the man page for the setsockopt() system call for details on
some of the options you may be some of the options you may be
able to set. By default no special socket options are set. This only affects direct socket con- able to set. By default no special socket options are set. This only affects direct socket con-
nections to a remote rsync daemon. nections to a remote rsync daemon.
This option also exists in the --daemon mode section. This option also exists in the --daemon mode section.
--blocking-io --blocking-io
This tells rsync to use blocking I/O when launching a remote This tells rsync to use blocking I/O when launching a remote
transport. If the remote shell transport. If the remote
shell is either rsh or remsh, rsync defaults to using shell is either rsh or remsh, rsync defaults to using blocking I/
otherwise it defaults to O, otherwise it defaults to
using non-blocking I/O. (Note that ssh prefers non-blocking I/O.) using non-blocking I/O. (Note that ssh prefers non-blocking I/O.)
--outbuf=MODE --outbuf=MODE
This (aka This sets the output buffering mode. The mode can be None (aka U nbuffered), Line, or Block (aka
Full). You may specify as little as a single letter for the mode, and use upper or lower case. Full). You may specify as little as a single letter for the mode, and use upper or lower case.
The is The main use of this option is to change Full buffering to Line bu ffering when rsync's output is
going to a file or pipe. going to a file or pipe.
--itemize-changes, -i --itemize-changes, -i
Requests including Requests a simple itemized list of the changes that are bei ng made to each file, including
attribute changes. This is exactly the same as specifying --out-f ormat='%i %n%L'. If you repeat attribute changes. This is exactly the same as specifying --out-f ormat='%i %n%L'. If you repeat
the option, unchanged files will also be output, but only if the r eceiving rsync is at least ver- the option, unchanged files will also be output, but only if the r eceiving rsync is at least ver-
sion of sion 2.6.7 (you can use -vv with older versions of rsync, but that also turns on the output of
other verbose messages). other verbose messages).
The "%i" escape has a cryptic output that is 11 letters long. The The "%i" escape has a cryptic output that is 11 letters long.
general format is like the The general format is like the
string YXcstpoguax, where Y is replaced by the type of update string YXcstpoguax, where Y is replaced by the type of update bein
done, X is replaced by the g done, X is replaced by the
file-type, and the other letters represent attributes that may be file-type, and the other letters represent attributes that may be
output if they are being modi- output if they are being modi-
fied. fied.
The update types that replace the Y are as follows: The update types that replace the Y are as follows:
o A < means that a file is being transferred to the remote ho st (sent). o A < means that a file is being transferred to the remote ho st (sent).
o A > means that a file is being transferred to the local hos t (received). o A > means that a file is being transferred to the local hos t (received).
o A of o A c means that a local change/creation is occurring for the item (such as the creation of
a directory or the changing of a symlink, etc.). a directory or the changing of a symlink, etc.).
o A h means that the item is a hard link to another item (req uires --hard-links). o A h means that the item is a hard link to another item (req uires --hard-links).
o A are o A . means that the item is not being updated (though it might have attributes that are
being modified). being modified).
o A * means that the rest of the itemized-output area contain s a message (e.g. "deleting"). o A * means that the rest of the itemized-output area contain s a message (e.g. "deleting").
The file-types that replace the X are: f for a file, a d for a dir ectory, an L for a symlink, a D The file-types that replace the X are: f for a file, a d for a dir ectory, an L for a symlink, a D
for a device, and a S for a special file (e.g. named sockets and f ifos). for a device, and a S for a special file (e.g. named sockets and f ifos).
The other letters in the string above are the actual letters The other letters in the string above are the actual letters tha
will be output if the associ- t will be output if the associ-
ated attribute for the item is being updated or a "." for no ated attribute for the item is being updated or a "." for no chan
Three exceptions to this ge. Three exceptions to this
are: (1) a newly created item replaces each letter with a "+", (2) an identical item replaces the are: (1) a newly created item replaces each letter with a "+", (2) an identical item replaces the
dots happen dots with spaces, and (3) an unknown attribute replaces each lette r with a "?" (this can happen
when talking to an older rsync). when talking to an older rsync).
The attribute that is associated with each letter is as follows: The attribute that is associated with each letter is as follows:
o A or o A c means either that a regular file has a different ch ecksum (requires --checksum) or
that a symlink, device, or special file has a changed value . Note that if you are sending that a symlink, device, or special file has a changed value . Note that if you are sending
files checksum-dif- files to an rsync prior to 3.0.1, this change flag will be present only for checksum-dif-
fering regular files. fering regular files.
o A trans- o A s means the size of a regular file is different and will be updated by the file trans-
fer. fer.
o A t means the modification time is different and is o A t means the modification time is different and is bein
to the sender's value g updated to the sender's value
(requires --times). An alternate value of T means that (requires --times). An alternate value of T means that the
modification time will be set modification time will be set
to the transfer time, which happens when a to the transfer time, which happens when a file/symlink/de
is updated without --times vice is updated without --times
and when a symlink is changed and the receiver can't set and when a symlink is changed and the receiver can't set it
time. (Note: when using an s time. (Note: when using an
rsync 3.0.0 client, you might see the s flag combined with rsync 3.0.0 client, you might see the s flag combined with
t instead of the proper T flag t instead of the proper T flag
for this time-setting failure.) for this time-setting failure.)
o A value o A p means the permissions are different and are being up dated to the sender's value
(requires --perms). (requires --perms).
o An (requires o An o means the owner is different and is being updated to the sender's value (requires
--owner and super-user privileges). --owner and super-user privileges).
o A (requires o A g means the group is different and is being updated to the sender's value (requires
--group and the authority to set the group). --group and the authority to set the group).
o A u means the access (use) time is different and is o A u means the access (use) time is different and is bein
to the sender's value g updated to the sender's value
(requires --atimes). An alternate value of U means that (requires --atimes). An alternate value of U means that th
access time will be set to e access time will be set to
the transfer time, which happens when a symlink or director y is updated. the transfer time, which happens when a symlink or director y is updated.
o The a means that the ACL information changed. o The a means that the ACL information changed.
o The x means that the extended attribute information changed . o The x means that the extended attribute information changed .
One other output is possible: when deleting files, the "%i" One other output is possible: when deleting files, the "%i" wil
the string "*deleting" l output the string "*deleting"
for each item that is being removed (assuming that you are for each item that is being removed (assuming that you are talking
to a recent enough rsync that to a recent enough rsync that
it logs deletions instead of outputting them as a verbose message) . it logs deletions instead of outputting them as a verbose message) .
--out-format=FORMAT --out-format=FORMAT
This allows you to specify exactly what the rsync client This allows you to specify exactly what the rsync client outp
the user on a per-update uts to the user on a per-update
basis. The format is a text string containing embedded basis. The format is a text string containing embedded single-cha
escape sequences pre- racter escape sequences pre-
fixed with a percent (%) character. A default format of "%n%L" fixed with a percent (%) character. A default format of "%n%L" i
assumed if either --info=name s assumed if either --info=name
or -v is specified (this tells you just the name of the file and, if the item is a link, where it or -v is specified (this tells you just the name of the file and, if the item is a link, where it
points). the points). For a full list of the possible escape characters, see the "log format" setting in the
rsyncd.conf manpage. rsyncd.conf manpage.
Specifying file, Specifying the --out-format option implies the --info=name option, which will mention each file,
dir, etc. that gets updated in a significant way (a transferred fi le, a recreated symlink/device, dir, etc. that gets updated in a significant way (a transferred fi le, a recreated symlink/device,
or the or a touched directory). In addition, if the itemize-changes esca pe (%i) is included in the
string (e.g. if the --itemize-changes option was used), the loggin g of names increases to mention string (e.g. if the --itemize-changes option was used), the loggin g of names increases to mention
any the any item that is changed in any way (as long as the receiving side is at least 2.6.4). See the
--itemize-changes option for a description of the output of "%i". --itemize-changes option for a description of the output of "%i".
Rsync transfer- Rsync will output the out-format string prior to a file's trans fer unless one of the transfer-
statistic escapes is requested, in which case the logging is done at the end of the file's trans- statistic escapes is requested, in which case the logging is done at the end of the file's trans-
fer. When this late logging is in effect and --progress is also fer. When this late logging is in effect and --progress is also
rsync will also out- specified, rsync will also out-
put the name of the file being transferred prior to its put the name of the file being transferred prior to its progre
information (followed, of ss information (followed, of
course, by the out-format output). course, by the out-format output).
--log-file=FILE --log-file=FILE
This option causes rsync to log what it is doing to a file. This This option causes rsync to log what it is doing to a file. This
is similar to the logging that is similar to the logging that
a daemon does, but can be requested for the client side and/or a daemon does, but can be requested for the client side and/or the
the server side of a non-daemon server side of a non-daemon
transfer. If specified as a client option, transfer logging will transfer. If specified as a client option, transfer logging will
be enabled with a default for- be enabled with a default for-
mat of "%i %n%L". See the --log-file-format option if you wish to override this. mat of "%i %n%L". See the --log-file-format option if you wish to override this.
Here's a example command that requests the remote side to log what is happening: Here's a example command that requests the remote side to log what is happening:
rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/ rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/
This is very useful if you need to debug why a connection is closi ng unexpectedly. This is very useful if you need to debug why a connection is closi ng unexpectedly.
--log-file-format=FORMAT --log-file-format=FORMAT
This allows you to specify exactly what per-update logging is put This allows you to specify exactly what per-update logging is put
into the file specified by the into the file specified by the
--log-file option (which must also be specified for this to --log-file option (which must also be specified for this opti
have any effect). If you on to have any effect). If you
specify an empty string, updated files will not be mentioned in specify an empty string, updated files will not be mentioned in th
log file. For a list of the e log file. For a list of the
possible escape characters, see the "log format" setting in the rs yncd.conf manpage. possible escape characters, see the "log format" setting in the rs yncd.conf manpage.
The default FORMAT used if --log-file is specified and this option is not is '%i %n%L'. The default FORMAT used if --log-file is specified and this option is not is '%i %n%L'.
--stats --stats
This tells rsync to print a verbose set of statistics on the file This tells rsync to print a verbose set of statistics on the file
transfer, allowing you to tell transfer, allowing you to tell
how effective rsync's delta-transfer algorithm is for your how effective rsync's delta-transfer algorithm is for your data.
This option is equivalent to This option is equivalent to
--info=stats2 if combined with 0 or 1 -v options, or --info=stats2 if combined with 0 or 1 -v options, or --info=stats
if combined with 2 or more -v 3 if combined with 2 or more -v
options. options.
The current statistics are as follows: The current statistics are as follows:
o Number of files is the count of all "files" (in the o Number of files is the count of all "files" (in the generic
sense), which includes direc- sense), which includes direc-
tories, symlinks, etc. The total count will be followed by tories, symlinks, etc. The total count will be followed
a list of counts by filetype by a list of counts by filetype
(if the total is non-zero). For example: "(reg: 5, dir: (if the total is non-zero). For example: "(reg: 5, dir: 3,
link: 2, dev: 1, special: 1)" link: 2, dev: 1, special: 1)"
lists the totals for regular files, directories, symlinks, devices, and special files. If lists the totals for regular files, directories, symlinks, devices, and special files. If
any of value is 0, it is completely omitted from the list. any of value is 0, it is completely omitted from the list.
o Number of created files (as o Number of created files is the count of how many "files" (g eneric sense) were created (as
opposed to updated). The total count will be followed by a list of counts by filetype (if opposed to updated). The total count will be followed by a list of counts by filetype (if
the total is non-zero). the total is non-zero).
o Number of deleted files (as o Number of deleted files is the count of how many "files" (g eneric sense) were created (as
opposed to updated). The total count will be followed by a list of counts by filetype (if opposed to updated). The total count will be followed by a list of counts by filetype (if
the effect, 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 rsyn c 3.1.x). and only if protocol 31 is being used (the default for rsyn c 3.1.x).
o Number of regular files transferred is the count of o Number of regular files transferred is the count of nor
files that were updated via mal files that were updated via
rsync's delta-transfer algorithm, which does not include rsync's delta-transfer algorithm, which does not include di
o Total file size count o Total file size is the total sum of all file sizes in the transfer. This does not count
any size for directories or special files, but does include the size of symlinks. any size for directories or special files, but does include the size of symlinks.
o Total transferred file size transferred o Total transferred file size is the total sum of all files s izes for just the transferred
files. files.
o Literal data it o Literal data is how much unmatched file-update data we had to send to the receiver for it
to recreate the updated files. to recreate the updated files.
o Matched data is how much data the receiver got locally when recreating the updated files. o Matched data is how much data the receiver got locally when recreating the updated files.
o File list size is how big the file-list data was when the o File list size is how big the file-list data was when the s
This is smaller than the in-memory size for the file list This is smaller than the in-memory size for the file
due to some compressing of list due to some compressing of
duplicated data when rsync sends the list. duplicated data when rsync sends the list.
o File list generation time is the number of seconds that the sender spent creating the file o File list generation time is the number of seconds that the sender spent creating the file
list. This requires a modern rsync on the sending side for this to be present. list. This requires a modern rsync on the sending side for this to be present.
o File list transfer time file o File list transfer time is the number of seconds that th e sender spent sending the file
o Total bytes sent is the count of all the bytes that rsync s ent from the client side to the o Total bytes sent is the count of all the bytes that rsync s ent from the client side to the
server side. server side.
o Total bytes received is the count of all non-message o Total bytes received is the count of all non-message b
client side from the server side. "Non-message" bytes client side from the server side. "Non-message" bytes means
that we don't count the bytes that we don't count the bytes
for a verbose message that the server sent to us, which mak es the stats more consistent. for a verbose message that the server sent to us, which mak es the stats more consistent.
--8-bit-output, -8 --8-bit-output, -8
This tells rsync to leave all high-bit characters unescaped in the This tells rsync to leave all high-bit characters unescaped in
test them to see if they're valid in the current locale and test them to see if they're valid in the current locale and escapi
the invalid ones. All con- ng the invalid ones. All con-
trol characters (but never tabs) are always escaped, regardless of this option's setting. trol characters (but never tabs) are always escaped, regardless of this option's setting.
The escape idiom that started in 2.6.7 is to output a literal The escape idiom that started in 2.6.7 is to output a literal bac
(\) and a hash (#), fol- kslash (\) and a hash (#), fol-
lowed by exactly 3 octal digits. For example, a newline lowed by exactly 3 octal digits. For example, a newline would ou
as "\#012". A literal tput as "\#012". A literal
backslash that is in a filename is not escaped unless it is backslash that is in a filename is not escaped unless it is
by a hash and 3 digits followed by a hash and 3 digits
(0-9). (0-9).
Output numbers in a more human-readable format. There are 3 Output numbers in a more human-readable format. There are 3 possi
levels: (1) output numbers ble levels: (1) output numbers
with a separator between each set of 3 digits (either a comma a with a separator between each set of 3 digits (either a comma o
period, depending on if the r a period, depending on if the
decimal point is represented by a period or a comma); (2) output n umbers in units of 1000 (with a decimal point is represented by a period or a comma); (2) output n umbers in units of 1000 (with a
character suffix for larger units -- see below); (3) output number s in units of 1024. character suffix for larger units -- see below); (3) output number s in units of 1024.
The default is human-readable level 1. Each -h option increases The default is human-readable level 1. Each -h option increases
level by one. You can take the level by one. You can take
the level down to 0 (to output numbers as pure digits) by the level down to 0 (to output numbers as pure digits) by speci
(--no-h) option. (--no-h) option.
The unit letters that are appended in levels 2 and 3 are: K The unit letters that are appended in levels 2 and 3 are: K (
M (mega), G (giga), or T kilo), M (mega), G (giga), or T
(tera). For example, a 1234567-byte file would output as (tera). For example, a 1234567-byte file would output as 1.23M
in level-2 (assuming that a in level-2 (assuming that a
period is your local decimal point). period is your local decimal point).
Backward compatibility note: versions of rsync prior to 3.1.0 do n ot support human-readable level Backward compatibility note: versions of rsync prior to 3.1.0 do n ot support human-readable level
1, and they default to level 0. Thus, specifying one or two -h op tions will behave in a compara- 1, and they default to level 0. Thus, specifying one or two -h op tions will behave in a compara-
ble or ble manner in old and new versions as long as you didn't specify a --no-h option prior to one or
more -h options. See the --list-only option for one difference. more -h options. See the --list-only option for one difference.
--partial --partial
By In By default, rsync will delete any partially transferred file if th e transfer is interrupted. In
some circumstances it is more desirable to keep partially transfer red files. Using the --partial some circumstances it is more desirable to keep partially transfer red files. Using the --partial
option rest option tells rsync to keep the partial file which should make a su bsequent transfer of the rest
of the file much faster. of the file much faster.
--partial-dir=DIR --partial-dir=DIR
A better way to keep partial files than the --partial option to A better way to keep partial files than the --partial option i
specify a DIR that will be s to specify a DIR that will be
used to hold the partial data (instead of writing it out to the used to hold the partial data (instead of writing it out to the de
file). On the next stination file). On the next
transfer, rsync will use a file found in this dir as data to transfer, rsync will use a file found in this dir as data to
up the resumption of the speed up the resumption of the
transfer and then delete it after it has served its purpose. transfer and then delete it after it has served its purpose.
Note that if --whole-file is specified (or implied), any Note that if --whole-file is specified (or implied), any partial-d
file that is found for a ir file that is found for a
file that is being updated will simply be removed (since rsync is file that is being updated will simply be removed (since rsync
sending files without using is sending files without using
rsync's delta-transfer algorithm). rsync's delta-transfer algorithm).
Rsync will create the DIR if it is missing (just the last dir -- n ot the whole path). This makes Rsync will create the DIR if it is missing (just the last dir -- n ot the whole path). This makes
it easy to use a relative path (such as it easy to use a relative path (such as "--partial-dir=.rsync-par
to have rsync create the tial") to have rsync create the
partial-directory in the destination file's directory when partial-directory in the destination file's directory when needed,
and then remove it again when and then remove it again when
the partial file is deleted. Note that the directory is only the partial file is deleted. Note that the directory is only re
if it is a relative path- moved if it is a relative path-
name, as it is expected that an absolute path is to a directory name, as it is expected that an absolute path is to a directory th
is reserved for partial-dir at is reserved for partial-dir
work. work.
If the partial-dir value is not an absolute path, rsync will If the partial-dir value is not an absolute path, rsync will ad
exclude rule at the end of d an exclude rule at the end of
all your existing excludes. This will prevent the sending of all your existing excludes. This will prevent the sending of any
any partial-dir files that may partial-dir files that may
exist on the sending side, and will also prevent the untimely exist on the sending side, and will also prevent the untimely d
of partial-dir items on eletion of partial-dir items on
the receiving side. An example: the above --partial-dir the receiving side. An example: the above --partial-dir option
"-f '-p .rsync-partial/'" at the end of any other filter rules. "-f '-p .rsync-partial/'" at the end of any other filter rules.
If you are supplying your own exclude rules, you may need to If you are supplying your own exclude rules, you may need to ad
rule for the partial-dir because (1) the auto-added rule may be rule for the partial-dir because (1) the auto-added rule may be in
at the end of your effective at the end of your
other rules, or (2) you may wish to override rsync's exclude other rules, or (2) you may wish to override rsync's exclude cho
For instance, if you want ice. For instance, if you want
to make rsync clean-up any left-over partial-dirs that may be to make rsync clean-up any left-over partial-dirs that may be lyin
around, you should specify g around, you should specify
--delete-after and add a "risk" filter rule, e.g. -f 'R .rsync-pa rtial/'. (Avoid using --delete- --delete-after and add a "risk" filter rule, e.g. -f 'R .rsync-pa rtial/'. (Avoid using --delete-
before partial-dir before or --delete-during unless you don't need rsync to use any of the left-over partial-dir
data during the current run.) data during the current run.)
IMPORTANT: risk. IMPORTANT: the --partial-dir should not be writable by other users or it is a security risk.
E.g. AVOID "/tmp". E.g. AVOID "/tmp".
You can also set the partial-dir value the RSYNC_PARTIAL_DIR You can also set the partial-dir value the RSYNC_PARTIAL_DIR envir
variable. Setting this onment variable. Setting this
in the environment does not force --partial to be enabled, but in the environment does not force --partial to be enabled, but
it affects where partial rather it affects where partial
files go when --partial is specified. For instance, instead of files go when --partial is specified. For instance, instead of
using --partial-dir=.rsync-tmp using --partial-dir=.rsync-tmp
along with --progress, you could set along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-t
just use the -P option to turn on the use of the .rsync-tmp dir just use the -P option to turn on the use of the .rsync-tmp dir fo
partial transfers. The only r partial transfers. The only
times that the --partial option does not look for this times that the --partial option does not look for this environme
value are (1) when --inplace nt value are (1) when --inplace
was specified (since --inplace conflicts with --partial-dir), was specified (since --inplace conflicts with --partial-dir), and
specified (see below). specified (see below).
When a modern rsync resumes the transfer of a file in the When a modern rsync resumes the transfer of a file in the partia
that partial file is now l-dir, that partial file is now
updated in-place instead of creating yet another tmp-file copy updated in-place instead of creating yet another tmp-file copy (so
(so it maxes out at dest + tmp it maxes out at dest + tmp
instead of dest + partial + tmp). This requires both ends of the transfer to be at least version instead of dest + partial + tmp). This requires both ends of the transfer to be at least version
3.2.0. 3.2.0.
For the purposes of the daemon-config's "refuse options" For the purposes of the daemon-config's "refuse options" setting,
--partial-dir does not imply --partial-dir does not imply
--partial. This is so that a refusal of the --partial option --partial. This is so that a refusal of the --partial option ca
be used to disallow the over- n be used to disallow the over-
writing of destination files with a partial transfer, while writing of destination files with a partial transfer, while still
allowing the safer idiom pro- allowing the safer idiom pro-
vided by --partial-dir. vided by --partial-dir.
This option puts the temporary file from each updated file into a holding directory until the end This option puts the temporary file from each updated file into a holding directory until the end
of This of the transfer, at which time all the files are renamed into plac e in rapid succession. This
attempts to make the updating of the files a little more atomic. By default the files are placed attempts to make the updating of the files a little more atomic. By default the files are placed
into the into a directory named .~tmp~ in each file's destination directory , but if you've specified the
--partial-dir option, that directory will be used instead. See th e comments in the --partial-dir --partial-dir option, that directory will be used instead. See th e comments in the --partial-dir
section for a discussion of how this .~tmp~ dir will be excluded section for a discussion of how this .~tmp~ dir will be excluded f
the transfer, and what you rom the transfer, and what you
can do if you want rsync to cleanup old .~tmp~ dirs that might can do if you want rsync to cleanup old .~tmp~ dirs that might b
lying around. Conflicts with e lying around. Conflicts with
--inplace and --append. --inplace and --append.
This option uses more memory on the receiving side (one bit This option uses more memory on the receiving side (one bit per
per file transferred) and also file transferred) and also
requires enough free disk space on the receiving side to an requires enough free disk space on the receiving side to hol
additional copy of all the d an additional copy of all the
updated files. Note also that you should not use an absolute updated files. Note also that you should not use an absolute path
to --partial-dir unless (1) to --partial-dir unless (1)
there is no chance of any of the files in the transfer there is no chance of any of the files in the transfer havi
same name (since all the ng the same name (since all the
updated files will be put into a single directory if the path is updated files will be put into a single directory if the path is a
and (2) there are no bsolute) and (2) there are no
mount points in the hierarchy (since the delayed updates will mount points in the hierarchy (since the delayed updates will fai
if they can't be renamed into l if they can't be renamed into
place). place).
See is See also the "atomic-rsync" perl script in the "support" subdir fo r an update algorithm that is
even more atomic (it uses --link-dest and a parallel hierarchy of files). even more atomic (it uses --link-dest and a parallel hierarchy of files).
--prune-empty-dirs, -m --prune-empty-dirs, -m
This option tells the receiving rsync to get rid of empty director ies from the file-list, includ- This option tells the receiving rsync to get rid of empty director ies from the file-list, includ-
ing nested directories that have no non-directory children. This is useful for avoiding the cre- ing nested directories that have no non-directory children. This is useful for avoiding the cre-
ation hierar- ation of a bunch of useless directories when the sending rsync is recursively scanning a hierar-
chy of files using include/exclude/filter rules. chy of files using include/exclude/filter rules.
Note that the use of transfer rules, such as the --min-size Note that the use of transfer rules, such as the --min-size option
does not affect what goes , does not affect what goes
into the file list, and thus does not leave directories empty, into the file list, and thus does not leave directories empty,
if none of the files in a even if none of the files in a
directory match the transfer rule. directory match the transfer rule.
Because the file-list is actually being pruned, this option Because the file-list is actually being pruned, this option also
affects what directories get affects what directories get
deleted when a delete is active. However, keep in mind that deleted when a delete is active. However, keep in mind that exc
files and directories can luded files and directories can
prevent existing items from being deleted due to an exclude both h iding source files and protect- prevent existing items from being deleted due to an exclude both h iding source files and protect-
ing destination files. See the perishable filter-rule option for how to avoid this. ing destination files. See the perishable filter-rule option for how to avoid this.
You can prevent the pruning of certain empty directories from the You can prevent the pruning of certain empty directories from
file-list by using a global the file-list by using a global
"protect" filter. For instance, this option would ensure that "protect" filter. For instance, this option would ensure that the
directory "emptydir" was kept directory "emptydir" was kept
in the file-list: in the file-list:
--filter 'protect emptydir/' --filter 'protect emptydir/'
Here's an example that copies all .pdf files in a hierarchy, only creating the necessary destina- Here's an example that copies all .pdf files in a hierarchy, only creating the necessary destina-
tion directories to hold the .pdf files, and ensures that any tion directories to hold the .pdf files, and ensures that any supe
files and directories rfluous files and directories
in the destination are removed (note the hide filter of in the destination are removed (note the hide filter of non-direc
exclude): exclude):
rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest
If of If you didn't want to remove superfluous destination files, the more time-honored options of
--include='*/' --exclude='*' would work fine in place of the hide- filter (if that is more natural --include='*/' --exclude='*' would work fine in place of the hide- filter (if that is more natural
to you). to you).
--progress --progress
This option tells rsync to print information showing the progress This option tells rsync to print information showing the progress
of the transfer. This gives a of the transfer. This gives a
bored user something to watch. With a modern rsync this bored user something to watch. With a modern rsync this
is the same as specifying is the same as specifying
--info=flist2,name,progress, but any user-supplied settings for th ose info flags takes precedence --info=flist2,name,progress, but any user-supplied settings for th ose info flags takes precedence
(e.g. "--info=flist0 --progress"). (e.g. "--info=flist0 --progress").
While rsync is transferring a regular file, it updates a progress line that looks like this: While rsync is transferring a regular file, it updates a progress line that looks like this:
782448 63% 110.64kB/s 0:00:04 782448 63% 110.64kB/s 0:00:04
In this example, the receiver has reconstructed 782448 bytes or In this example, the receiver has reconstructed 782448 bytes or
of the sender's file, which 63% of the sender's file, which
is being reconstructed at a rate of 110.64 kilobytes per second, is being reconstructed at a rate of 110.64 kilobytes per second, a
the transfer will finish in nd the transfer will finish in
4 seconds if the current rate is maintained until the end. 4 seconds if the current rate is maintained until the end.
These statistics can be misleading if rsync's delta-transfer These statistics can be misleading if rsync's delta-transfer alg
is in use. For example, orithm is in use. For example,
if the sender's file consists of the basis file followed by if the sender's file consists of the basis file followed by additi
data, the reported rate onal data, the reported rate
will probably drop dramatically when the receiver gets to the lite ral data, and the transfer will will probably drop dramatically when the receiver gets to the lite ral data, and the transfer will
probably matched probably take much longer to finish than the receiver estimated as it was finishing the matched
part of the file. part of the file.
When looks When the file transfer finishes, rsync replaces the progress line with a summary line that looks
like this: like this:
1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396) 1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396)
In this example, the file was 1,238,099 bytes long in total, the a verage rate of transfer for the In this example, the file was 1,238,099 bytes long in total, the a verage rate of transfer for the
whole was whole file was 146.38 kilobytes per second over the 8 seconds t hat it took to complete, it was
the 5th transfer of a regular file during the current rsync sessio n, and there are 169 more files the 5th transfer of a regular file during the current rsync sessio n, and there are 169 more files
for total for the receiver to check (to see if they are up-to-date or not) remaining out of the 396 total
files in the file-list. files in the file-list.
In an incremental recursion scan, rsync won't know the total In an incremental recursion scan, rsync won't know the total numbe
of files in the file-list r of files in the file-list
until it reaches the ends of the scan, but since it starts to until it reaches the ends of the scan, but since it starts to tra
files during the scan, it nsfer files during the scan, it
will display a line with the text "ir-chk" (for incremental will display a line with the text "ir-chk" (for incremental recurs
until the point that it knows the full size of the list, at until the point that it knows the full size of the list, at whic
point it will switch to using h point it will switch to using
"to-chk". Thus, seeing "ir-chk" lets you know that the total "to-chk". Thus, seeing "ir-chk" lets you know that the total coun
of files in the file list is t of files in the file list is
still going to increase (and each time it does, the count of files left to check will increase by still going to increase (and each time it does, the count of files left to check will increase by
the number of the files added to the list). the number of the files added to the list).
-P The to -P The -P option is equivalent to --partial --progress. Its purpose is to make it much easier to
specify these two options for a long transfer that may be interrup ted. specify these two options for a long transfer that may be interrup ted.
There is also a --info=progress2 option that outputs There is also a --info=progress2 option that outputs statisti
on the whole transfer, cs based on the whole transfer,
rather than individual files. Use this flag without rather than individual files. Use this flag without outputting a
a filename (e.g. avoid -v or filename (e.g. avoid -v or
specify --info=name0) if you want to see how the transfer is specify --info=name0) if you want to see how the transfer is doi
without scrolling the screen ng without scrolling the screen
with a lot of names. (You don't need to specify the with a lot of names. (You don't need to specify the --progr
option in order to use ess option in order to use
--info=progress2.) --info=progress2.)
Finally, you can get an instant progress report by sending a Finally, you can get an instant progress report by sending rsyn
signal of either SIGINFO or c a signal of either SIGINFO or
SIGVTALRM. On BSD systems, a SIGINFO is generated by typing a SIGVTALRM. On BSD systems, a SIGINFO is generated by typing a Ctr
(Linux doesn't currently l+T (Linux doesn't currently
support a SIGINFO signal). When the client-side process receives one of those signals, it sets a support a SIGINFO signal). When the client-side process receives one of those signals, it sets a
flag to output a single progress report which is output when the flag to output a single progress report which is output when the c
file transfer finishes urrent file transfer finishes
(so it may take a little time if a big file is being handled (so it may take a little time if a big file is being handled whe
the signal arrives). A file- n the signal arrives). A file-
name is output (if needed) followed by the --info=progress2 name is output (if needed) followed by the --info=progress2 format
of progress info. If you of progress info. If you
don't know which of the 3 rsync processes is the client don't know which of the 3 rsync processes is the client process
OK to signal all of them , it's OK to signal all of them
(since the non-client processes ignore the signal). (since the non-client processes ignore the signal).
CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it. CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it.
This option allows you to provide a password for accessing an This option allows you to provide a password for accessing an rsyn
daemon via a file or via c daemon via a file or via
standard input if FILE is -. The file should contain just the standard input if FILE is -. The file should contain just the
on the first line (all password on the first line (all
other lines are ignored). Rsync will exit with an error if FILE other lines are ignored). Rsync will exit with an error if FILE i
world readable or if a root- s world readable or if a root-
run rsync command finds a non-root-owned file. run rsync command finds a non-root-owned file.
This to This option does not supply a password to a remote shell transpo rt such as ssh; to learn how to
do that, consult the remote shell's documentation. When accessing an rsync daemon using a remote do that, consult the remote shell's documentation. When accessing an rsync daemon using a remote
shell its shell as the transport, this option only comes into effect afte r the remote shell finishes its
authentication (i.e. if you have also specified a password in the daemon's config file). authentication (i.e. if you have also specified a password in the daemon's config file).
--early-input=FILE --early-input=FILE
This option allows rsync to send up to 5K of data to the "early This option allows rsync to send up to 5K of data to the "early ex
script on its stdin. One ec" script on its stdin. One
possible use of this data is to give the script a secret that possible use of this data is to give the script a secret that ca
be used to mount an encrypted n be used to mount an encrypted
filesystem (which you should unmount in the the "post-xfer exec" s cript). filesystem (which you should unmount in the the "post-xfer exec" s cript).
The daemon must be at least version 3.2.1. The daemon must be at least version 3.2.1.
--list-only --list-only
This option will cause the source files to be listed instead This option will cause the source files to be listed instead of
of transferred. This option is transferred. This option is
inferred if there is a single source arg and no destination inferred if there is a single source arg and no destination speci
so its main uses are: (1) fied, so its main uses are: (1)
to turn a copy command that includes a destination arg into a to turn a copy command that includes a destination arg into a file
command, or (2) to be -listing command, or (2) to be
able to specify more than one source arg (note: be sure to able to specify more than one source arg (note: be sure to incl
the destination). Caution: ude the destination). Caution:
keep in mind that a source arg with a wild-card is expanded by keep in mind that a source arg with a wild-card is expanded by the
shell into multiple args, so shell into multiple args, so
it is never safe to try to list such an arg without using this opt ion. For example: it is never safe to try to list such an arg without using this opt ion. For example:
rsync -av --list-only foo* dest/ rsync -av --list-only foo* dest/
Starting with rsync 3.1.0, the sizes output by --list-only are Starting with rsync 3.1.0, the sizes output by --list-only are a
option. By default they will contain digit separators, but option. By default they will contain digit separators, but higher
output the sizes with unit suffixes. Note also that the output the sizes with unit suffixes. Note also that the colum
for the size output has n width for the size output has
increased from 11 to 14 characters for all human-readable increased from 11 to 14 characters for all human-readable levels.
Use --no-h if you want just Use --no-h if you want just
digits in the sizes, and the old column width of 11 characters. digits in the sizes, and the old column width of 11 characters.
Compatibility note: when requesting a remote listing of files from an rsync that is version 2.6.3 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 or older, you may encounter an error if you ask for a non-recursiv
listing. This is because a e listing. This is because a
file listing implies the --dirs option w/o --recursive, and older file listing implies the --dirs option w/o --recursive, and older
rsyncs don't have that option. rsyncs don't have that option.
To avoid this problem, either specify the --no-dirs option (if To avoid this problem, either specify the --no-dirs option (if you
don't need to expand a direc- don't need to expand a direc-
tory's content), or turn on recursion and exclude tory's content), or turn on recursion and exclude th
content of subdirectories: e content of subdirectories:
-r --exclude='/*/*'. -r --exclude='/*/*'.
--bwlimit=RATE --bwlimit=RATE
This option allows you to specify the maximum transfer rate for This option allows you to specify the maximum transfer rate for th
data sent over the socket, e data sent over the socket,
specified in units per second. The RATE value can be suffixed specified in units per second. The RATE value can be suffixed w
a string to indicate a size ith a string to indicate a size
multiplier, and may be a fractional value (e.g. multiplier, and may be a fractional value (e.g. "--bwlimit=1.5m").
If no suffix is specified, If no suffix is specified,
the value will be assumed to be in units of 1024 bytes (as if the value will be assumed to be in units of 1024 bytes (as if "
See the --max-size option for a description of all the available s uffixes. A value of zero spec- See the --max-size option for a description of all the available s uffixes. A value of zero spec-
ifies no limit. ifies no limit.
For backward-compatibility reasons, the rate limit will be rounded to the nearest KiB unit, so no For backward-compatibility reasons, the rate limit will be rounded to the nearest KiB unit, so no
rate smaller than 1024 bytes per second is possible. rate smaller than 1024 bytes per second is possible.
Rsync writes data over the socket in blocks, and this option Rsync writes data over the socket in blocks, and this option both
limits the size of the blocks limits the size of the blocks
that rsync writes, and tries to keep the average transfer at that rsync writes, and tries to keep the average transfer rat
the requested limit. Some e at the requested limit. Some
burstiness may be seen where rsync writes out a block of data and burstiness may be seen where rsync writes out a block of data and
then sleeps to bring the aver- then sleeps to bring the aver-
age rate into compliance. age rate into compliance.
Due to the internal buffering of data, the --progress option may n ot be an accurate reflection on Due to the internal buffering of data, the --progress option may n ot be an accurate reflection on
how fast the data is being sent. This is because some files how fast the data is being sent. This is because some files can s
up as being rapidly sent how up as being rapidly sent
when the data is quickly buffered, while other can show up as when the data is quickly buffered, while other can show up as ver
slow when the flushing of the y slow when the flushing of the
output buffer occurs. This may be fixed in a future version. output buffer occurs. This may be fixed in a future version.
--write-batch=FILE --write-batch=FILE
Record See Record a file that can later be applied to another identical desti nation with --read-batch. See
the "BATCH MODE" section for details, and also the --only-write-ba tch option. the "BATCH MODE" section for details, and also the --only-write-ba tch option.
This option overrides the negotiated checksum & compress lists
and always negotiates a choice
based on old-school md5/md4/zlib choices. If you want a more mode
rn choice, use the --checksum-
choice (--cc) and/or --compress-choice (--zc) options.
--only-write-batch=FILE --only-write-batch=FILE
Works like --write-batch, except that no updates are made on the d estination system when creating Works like --write-batch, except that no updates are made on the d estination system when creating
the means the batch. This lets you transport the changes to the destination system via some other means
and then apply the changes via --read-batch. and then apply the changes via --read-batch.
Note media Note that you can feel free to write the batch directly to som e portable media: if this media
fills to capacity before the end of the transfer, you can just app ly that partial transfer to the fills to capacity before the end of the transfer, you can just app ly that partial transfer to the
destination don't destination and repeat the whole process to get the rest of th e changes (as long as you don't
mind a partially updated destination system while the multi-update cycle is happening). mind a partially updated destination system while the multi-update cycle is happening).
Also this Also note that you only save bandwidth when pushing changes to a remote system because this
allows the batched data to be diverted from the sender into the ba tch file without having to flow allows the batched data to be diverted from the sender into the ba tch file without having to flow
over the over the wire to the receiver (when pulling, the sender is remote , and thus can't write the
batch). batch).
Apply FILE Apply all of the changes stored in FILE, a file previously gener ated by --write-batch. If FILE
is -, the batch data will be read from standard input. See the "BA TCH MODE" section for details. is -, the batch data will be read from standard input. See the "BA TCH MODE" section for details.
--protocol=NUM --protocol=NUM
Force an older protocol version to be used. This is useful Force an older protocol version to be used. This is useful for cr
a batch file that is eating a batch file that is
compatible with an older version of rsync. For instance, if compatible with an older version of rsync. For instance, if rsy
2.6.4 is being used with the nc 2.6.4 is being used with the
--write-batch option, but rsync 2.6.3 is what will be used to --write-batch option, but rsync 2.6.3 is what will be used to run
should use "--protocol=28" when creating the batch file to force t he older protocol version to be should use "--protocol=28" when creating the batch file to force t he older protocol version to be
used in the batch file (assuming you can't upgrade the rsync on th e reading system). used in the batch file (assuming you can't upgrade the rsync on th e reading system).
--iconv=CONVERT_SPEC --iconv=CONVERT_SPEC
Rsync can convert filenames between character sets using this Rsync can convert filenames between character sets using this opti
Using a CONVERT_SPEC of on. Using a CONVERT_SPEC of
"." tells rsync to look up the default character-set via the "." tells rsync to look up the default character-set via the lo
setting. Alternately, you cale setting. Alternately, you
can fully specify what conversion to do by giving a local and can fully specify what conversion to do by giving a local and a re
a charset separated by a mote charset separated by a
comma in the order --iconv=LOCAL,REMOTE, e.g. --iconv=utf8,iso8859 1. This order ensures that the comma in the order --iconv=LOCAL,REMOTE, e.g. --iconv=utf8,iso8859 1. This order ensures that the
option will stay the same whether you're pushing or pulling option will stay the same whether you're pushing or pulling files
Finally, you can specify . Finally, you can specify
either --no-iconv or a CONVERT_SPEC of "-" to turn off any either --no-iconv or a CONVERT_SPEC of "-" to turn off any conv
The default setting of ersion. The default setting of
this option is site-specific, and can also be affected via the RSY NC_ICONV environment variable. this option is site-specific, and can also be affected via the RSY NC_ICONV environment variable.
For a list of what charset names your local iconv library supports , you can run "iconv --list". For a list of what charset names your local iconv library supports , you can run "iconv --list".
If on If you specify the --protect-args option (-s), rsync will translat e the filenames you specify on
the command-line that are being sent to the remote host. See also the --files-from option. the command-line that are being sent to the remote host. See also the --files-from option.
Note that rsync does not do any conversion of names in filter Note that rsync does not do any conversion of names in filter f
(including include/exclude iles (including include/exclude
files). It is up to you to ensure that you're specifying files). It is up to you to ensure that you're specifying matching
rules that can match on both rules that can match on both
sides of the transfer. For instance, you can specify extra sides of the transfer. For instance, you can specify extra inc
rules if there are lude/exclude rules if there are
filename differences on the two sides that need to be accounted fo r. filename differences on the two sides that need to be accounted fo r.
When you pass an --iconv option to an rsync daemon that allows When you pass an --iconv option to an rsync daemon that allows it,
it, the daemon uses the charset the daemon uses the charset
specified in its "charset" configuration parameter regardless of specified in its "charset" configuration parameter regardless of
remote charset you actually the remote charset you actually
pass. Thus, you may feel free to specify just the local pass. Thus, you may feel free to specify just the local charset
for a daemon transfer (e.g. for a daemon transfer (e.g.
--iconv=utf8). --iconv=utf8).
--ipv4, -4 or --ipv6, -6 --ipv4, -4 or --ipv6, -6
Tells that Tells rsync to prefer IPv4/IPv6 when creating sockets or running ssh. This affects sockets that
rsync has direct control over, such as the outgoing socket when di rectly contacting an rsync dae- rsync has direct control over, such as the outgoing socket when di rectly contacting an rsync dae-
mon, is mon, as well as the forwarding of the -4 or -6 option to ssh wh en rsync can deduce that ssh is
being used as the remote shell. For other remote shells you'll need to specify the being used as the remote shell. For other remote shells you'll need to specify the
"--rsh SHELL -4" option directly (or whatever ipv4/ipv6 hint optio ns it uses). "--rsh SHELL -4" option directly (or whatever ipv4/ipv6 hint optio ns it uses).
These options also exist in the --daemon mode section. These options also exist in the --daemon mode section.
If rsync was complied without support for IPv6, the --ipv6 If rsync was complied without support for IPv6, the --ipv6 o
will have no effect. The ption will have no effect. The
rsync output will contain "no IPv6" if is the case. rsync --version output will contain "no IPv6" if is the case.
--checksum-seed=NUM --checksum-seed=NUM
Set the checksum seed to the integer NUM. This 4 byte checksum Set the checksum seed to the integer NUM. This 4 byte checksum se
is included in each block ed is included in each block
and MD4 file checksum calculation (the more modern MD5 file and MD4 file checksum calculation (the more modern MD5 file c
don't use a seed). By hecksums don't use a seed). By
default the checksum seed is generated by the server and default the checksum seed is generated by the server and defaults
to the current time(). This to the current time(). This
option is used to set a specific checksum seed, which is option is used to set a specific checksum seed, which is us
for applications that want eful for applications that want
repeatable block checksums, or in the case where the user repeatable block checksums, or in the case where the user wants a
a more random checksum seed. more random checksum seed.
Setting NUM to 0 causes rsync to use the default of time() for che cksum seed. Setting NUM to 0 causes rsync to use the default of time() for che cksum seed.
DAEMON OPTIONS DAEMON OPTIONS
The options allowed when starting an rsync daemon are as follows: The options allowed when starting an rsync daemon are as follows:
--daemon --daemon
This accessed This tells rsync that it is to run as a daemon. The daemon yo u start running may be accessed
using an rsync client using the host::module or rsync://host/modul e/ syntax. using an rsync client using the host::module or rsync://host/modul e/ syntax.
If standard input is a socket then rsync will assume that it is be ing run via inetd, otherwise it If standard input is a socket then rsync will assume that it is be ing run via inetd, otherwise it
will detach from the current terminal and become a background will detach from the current terminal and become a background da
config file (rsyncd.conf) on each connect made by a client and config file (rsyncd.conf) on each connect made by a client and res
to requests accordingly. pond to requests accordingly.
See the rsyncd.conf(5) man page for more details. See the rsyncd.conf(5) man page for more details.
By default rsync will bind to the wildcard address when run as a d aemon with the --daemon option. By default rsync will bind to the wildcard address when run as a d aemon with the --daemon option.
The --address option allows you to specify a specific IP address The --address option allows you to specify a specific IP address (
hostname) to bind to. This or hostname) to bind to. This
makes virtual hosting possible in conjunction with the --config makes virtual hosting possible in conjunction with the --config
global option in the rsyncd.conf manpage. global option in the rsyncd.conf manpage.
--bwlimit=RATE --bwlimit=RATE
This option allows you to specify the maximum transfer rate for This option allows you to specify the maximum transfer rate for th
data the daemon sends over e data the daemon sends over
the socket. The client can still specify a smaller --bwlimit the socket. The client can still specify a smaller --bwlimit val
but no larger value will be ue, but no larger value will be
allowed. See the client version of this option (above) for some e xtra details. allowed. See the client version of this option (above) for some e xtra details.
--config=FILE --config=FILE
This specifies an alternate config file than the default. This is only relevant when --daemon is This specifies an alternate config file than the default. This is only relevant when --daemon is
specified. The default is /etc/rsyncd.conf unless the daemon is r unning over a remote shell pro- specified. The default is /etc/rsyncd.conf unless the daemon is r unning over a remote shell pro-
gram the gram and the remote user is not the super-user; in that case the d efault is rsyncd.conf in the
current directory (typically $HOME). current directory (typically$HOME).
--dparam=OVERRIDE, -M --dparam=OVERRIDE, -M
This option can be used to set a daemon-config parameter when This option can be used to set a daemon-config parameter when st
up rsync in daemon mode. arting up rsync in daemon mode.
It is equivalent to adding the parameter at the end of the It is equivalent to adding the parameter at the end of the global
settings prior to the first settings prior to the first
module's definition. The parameter names can be specified without spaces, if you so desire. For module's definition. The parameter names can be specified without spaces, if you so desire. For
instance: instance:
rsync --daemon -M pidfile=/path/rsync.pid rsync --daemon -M pidfile=/path/rsync.pid
--no-detach --no-detach
When running as a daemon, this option instructs rsync to not When running as a daemon, this option instructs rsync to not detac
itself and become a back- h itself and become a back-
ground process. This option is required when running as a ground process. This option is required when running as a ser
on Cygwin, and may also be vice on Cygwin, and may also be
useful when rsync is supervised by a program such as useful when rsync is supervised by a program such as daemontools
or AIX's System Resource Con- or AIX's System Resource Con-
troller. --no-detach is also recommended when rsync is run under a debugger. This option has no troller. --no-detach is also recommended when rsync is run under a debugger. This option has no
effect if rsync is run from inetd or sshd. effect if rsync is run from inetd or sshd.
--port=PORT --port=PORT
This default This specifies an alternate TCP port number for the daemon to list en on rather than the default
of 873. See also the "port" global option in the rsyncd.conf manp age. of 873. See also the "port" global option in the rsyncd.conf manp age.
--log-file=FILE --log-file=FILE
This option tells the rsync daemon to use the given log-file name instead of using the "log file" This option tells the rsync daemon to use the given log-file name instead of using the "log file"
setting in the config file. setting in the config file.
--log-file-format=FORMAT --log-file-format=FORMAT
This option tells the rsync daemon to use the given FORMAT string This option tells the rsync daemon to use the given FORMAT string
instead of using the "log for- instead of using the "log for-
mat" setting in the config file. It also enables "transfer mat" setting in the config file. It also enables "transfer loggi
unless the string is empty, ng" unless the string is empty,
in which case transfer logging is turned off. in which case transfer logging is turned off.
--sockopts --sockopts
This overrides the socket options setting in the rsyncd.conf file and has the same syntax. This overrides the socket options setting in the rsyncd.conf file and has the same syntax.
--verbose, -v --verbose, -v
This option increases the amount of information the daemon logs This option increases the amount of information the daemon logs du
its startup phase. After ring its startup phase. After
the client connects, the daemon's verbosity level will be the client connects, the daemon's verbosity level will be con
by the options that the trolled by the options that the
client used and the "max verbosity" setting in the module's config section. client used and the "max verbosity" setting in the module's config section.
--ipv4, -4 or --ipv6, -6 --ipv4, -4 or --ipv6, -6
Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the rsync daemon will use Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the rsync daemon will use
to listen for connections. One of these options may be to listen for connections. One of these options may be require
older versions of Linux to d in older versions of Linux to
work around an IPv6 bug in the kernel (if you see an "address work around an IPv6 bug in the kernel (if you see an "address alre
in use" error when nothing ady in use" error when nothing
else is using the port, try specifying --ipv6 or --ipv4 when start ing the daemon). else is using the port, try specifying --ipv6 or --ipv4 when start ing the daemon).
These options also exist in the regular rsync options section. These options also exist in the regular rsync options section.
If rsync was complied without support for IPv6, the --ipv6 If rsync was complied without support for IPv6, the --ipv6 o
will have no effect. The ption will have no effect. The
rsync output will contain "no IPv6" if is the case. rsync --version output will contain "no IPv6" if is the case.
--help, -h --help, -h
When for When specified after --daemon, print a short help page describin g the options available for
starting an rsync daemon. starting an rsync daemon.
FILTER RULES FILTER RULES
The filter rules allow for flexible selection of which files to The filter rules allow for flexible selection of which files to transf
(include) and which files to er (include) and which files to
skip (exclude). The rules either directly specify include/exclude skip (exclude). The rules either directly specify include/exclude patter
or they specify a way to ns or they specify a way to
acquire more include/exclude patterns (e.g. to read them from a file). acquire more include/exclude patterns (e.g. to read them from a file).
As the list of files/directories to transfer is built, rsync checks each As the list of files/directories to transfer is built, rsync checks each
name to be transferred against name to be transferred against
the list of include/exclude patterns in turn, and the first matching the list of include/exclude patterns in turn, and the first matching patt
is acted on: if it is an ern is acted on: if it is an
exclude pattern, then that file is skipped; if it is an include exclude pattern, then that file is skipped; if it is an include pa
then that filename is not ttern then that filename is not
skipped; if no matching pattern is found, then the filename is not skippe d. skipped; if no matching pattern is found, then the filename is not skippe d.
Rsync the Rsync builds an ordered list of filter rules as specified on the command- line. Filter rules have the
following syntax: following syntax:
RULE [PATTERN_OR_FILENAME] RULE [PATTERN_OR_FILENAME]
RULE,MODIFIERS [PATTERN_OR_FILENAME] RULE,MODIFIERS [PATTERN_OR_FILENAME]
You have your choice of using either short or long RULE names, as You have your choice of using either short or long RULE names, as descri
below. If you use a short- bed below. If you use a short-
named rule, the ',' separating the RULE from the MODIFIERS is named rule, the ',' separating the RULE from the MODIFIERS is optional.
The PATTERN or FILENAME that The PATTERN or FILENAME that
follows (when present) must come after either a single space or an follows (when present) must come after either a single space or an under
(_). Here are the avail- score (_). Here are the avail-
able rule prefixes: able rule prefixes:
exclude, '-' exclude, '-'
specifies an exclude pattern. specifies an exclude pattern.
include, '+' include, '+'
specifies an include pattern. specifies an include pattern.
merge, '.' merge, '.'
specifies a merge-file to read for more rules. specifies a merge-file to read for more rules.
skipping to change at line 2684 skipping to change at line 2723
protect, 'P' protect, 'P'
specifies a pattern for protecting files from deletion. specifies a pattern for protecting files from deletion.
risk, 'R' risk, 'R'
files that match the pattern are not protected. files that match the pattern are not protected.
clear, '!' clear, '!'
clears the current include/exclude list (takes no arg) clears the current include/exclude list (takes no arg)
When a When rules are being read from a file, empty lines are ignored, as are co mment lines that start with a
"#". "#".
Note that the --include & --exclude command-line options do not allow Note that the --include & --exclude command-line options do not allow th
full range of rule parsing as e full range of rule parsing as
described above -- they only allow the specification of include / described above -- they only allow the specification of include / exclude
patterns plus a "!" token to patterns plus a "!" token to
clear the list (and the normal comment parsing when rules are read from a clear the list (and the normal comment parsing when rules are read from
file). If a pattern does not a file). If a pattern does not
begin with "- " (dash, space) or "+ " (plus, space), then the rule will begin with "- " (dash, space) or "+ " (plus, space), then the rule will b
interpreted as if "+ " (for e interpreted as if "+ " (for
an include option) or "- " (for an exclude option) were prefixed to the an include option) or "- " (for an exclude option) were prefixed to the
A --filter option, on string. A --filter option, on
the other hand, must always contain either a short or long rule name at t he start of the rule. the other hand, must always contain either a short or long rule name at t he start of the rule.
Note also that the --filter, --include, and --exclude options take one ru le/pattern each. To add multi- Note also that the --filter, --include, and --exclude options take one ru le/pattern each. To add multi-
ple --filter ple ones, you can repeat the options on the command-line, use the me rge-file syntax of the --filter
option, or the --include-from / --exclude-from options. option, or the --include-from / --exclude-from options.
INCLUDE/EXCLUDE PATTERN RULES INCLUDE/EXCLUDE PATTERN RULES
You (as You can include and exclude files by specifying patterns using the "+", "-", etc. filter rules (as
introduced in the FILTER RULES section above). The include/exclude rules each specify a pattern that is introduced in the FILTER RULES section above). The include/exclude rules each specify a pattern that is
matched sev- matched against the names of the files that are going to be transferred. These patterns can take sev-
eral forms: eral forms:
o if the pattern starts with a / then it is anchored to a o if the pattern starts with a / then it is anchored to a part
spot in the hierarchy of icular spot in the hierarchy of
files, otherwise it is matched against the end of the pathname. files, otherwise it is matched against the end of the pathname. T
is similar to a leading ^ his is similar to a leading ^
in regular expressions. Thus /foo would match a name of "foo" at in regular expressions. Thus /foo would match a name of "foo" at
either the "root of the trans- either the "root of the trans-
fer" (for a global rule) or in the merge-file's directory (for a p er-directory rule). An unqual- fer" (for a global rule) or in the merge-file's directory (for a p er-directory rule). An unqual-
ified foo would match a name of "foo" anywhere in the tree ified foo would match a name of "foo" anywhere in the tree b
the algorithm is applied ecause the algorithm is applied
recursively from the top down; it behaves as if each path recursively from the top down; it behaves as if each path componen
gets a turn at being the end t gets a turn at being the end
of the filename. Even the unanchored "sub/foo" would match at any point in the hierarchy where a of the filename. Even the unanchored "sub/foo" would match at any point in the hierarchy where a
"foo" INCLUDE/EXCLUDE "foo" was found within a directory named "sub". See the section on ANCHORING INCLUDE/EXCLUDE
PATTERNS for a full discussion of how to specify a pattern that ma tches at the root of the trans- PATTERNS for a full discussion of how to specify a pattern that ma tches at the root of the trans-
fer. fer.
o if the pattern ends with a / then it will only match a directory, not a regular file, symlink, or o if the pattern ends with a / then it will only match a directory, not a regular file, symlink, or
device. device.
o rsync pat- o rsync chooses between doing a simple string match and wildcard m atching by checking if the pat-
tern contains one of these three wildcard characters: '*', '?', an d '[' . tern contains one of these three wildcard characters: '*', '?', an d '[' .
o a '*' matches any path component, but it stops at slashes. o a '*' matches any path component, but it stops at slashes.
o use '**' to match anything, including slashes. o use '**' to match anything, including slashes.
o a '?' matches any character except a slash (/). o a '?' matches any character except a slash (/).
o a '[' introduces a character class, such as [a-z] or [[:alpha:]]. o a '[' introduces a character class, such as [a-z] or [[:alpha:]].
o in a wildcard pattern, a backslash can be used to escape a o in a wildcard pattern, a backslash can be used to escape a wildcar
character, but it is matched d character, but it is matched
literally when no wildcards are present. This means that there is literally when no wildcards are present. This means that there
an extra level of backslash is an extra level of backslash
removal when a pattern contains wildcard characters compared to a pattern that has none. e.g. if removal when a pattern contains wildcard characters compared to a pattern that has none. e.g. if
you "foo\\bar*" you add a wildcard to "foo\bar" (which matches the backslash) yo u would need to use "foo\\bar*"
to avoid the "\b" becoming just "b". to avoid the "\b" becoming just "b".
o if the pattern contains a / (not counting a trailing /) or a "**", then it is matched against the o if the pattern contains a / (not counting a trailing /) or a "**", then it is matched against the
full "**", full pathname, including any leading directories. If the pattern doesn't contain a / or a "**",
then it is matched only against the final component of the filenam e. (Remember that the algorithm then it is matched only against the final component of the filenam e. (Remember that the algorithm
is applied recursively so "full filename" can actually be any port ion of a path from the starting is applied recursively so "full filename" can actually be any port ion of a path from the starting
directory on down.) directory on down.)
o a trailing "dir_name/***" will match both the directory (as if o a trailing "dir_name/***" will match both the directory (as if "di
and everything in the directory (as if "dir_name/**" had been and everything in the directory (as if "dir_name/**" had been
This behavior was specified). This behavior was
Note that, when using the --recursive (-r) option (which is implied by Note that, when using the --recursive (-r) option (which is implied by -a
every subdir component of ), every subdir component of
every path is visited left to right, with each directory having a every path is visited left to right, with each directory having a chanc
for exclusion before its con- e for exclusion before its con-
tent. In this way include/exclude patterns are applied recursively to tent. In this way include/exclude patterns are applied recursively to th
pathname of each node in the e pathname of each node in the
filesystem's tree (those inside the transfer). The exclude patterns shor t-circuit the directory traver- filesystem's tree (those inside the transfer). The exclude patterns shor t-circuit the directory traver-
sal stage as rsync finds the files to send. sal stage as rsync finds the files to send.
For instance, to include "/foo/bar/baz", the directories "/foo" and For instance, to include "/foo/bar/baz", the directories "/foo" and "/foo
must not be excluded. /bar" must not be excluded.
Excluding one of those parent directories prevents the examination of Excluding one of those parent directories prevents the examination of i
content, cutting off rsync's ts content, cutting off rsync's
recursion into those paths and rendering the include for "/foo/bar/baz" recursion into those paths and rendering the include for "/foo/bar/baz" i
(since rsync can't neffectual (since rsync can't
match something it never sees in the cut-off section of the directory hie rarchy). match something it never sees in the cut-off section of the directory hie rarchy).
The concept path exclusion is particularly important when using a trailin g '*' rule. For instance, this The concept path exclusion is particularly important when using a trailin g '*' rule. For instance, this
won't work: won't work:
+ /some/path/this-file-will-not-be-found + /some/path/this-file-will-not-be-found
+ /file-is-included + /file-is-included
- * - *
This fails because the parent directory "some" is excluded by the '*' rul e, so rsync never visits any of This fails because the parent directory "some" is excluded by the '*' rul e, so rsync never visits any of
the files in the "some" or "some/path" directories. One solution is to the files in the "some" or "some/path" directories. One solution is to
for all directories in the ask for all directories in the
hierarchy to be included by using a single rule: "+ */" (put it hierarchy to be included by using a single rule: "+ */" (put it somewhere
before the "- *" rule), and before the "- *" rule), and
perhaps use the --prune-empty-dirs option. Another solution is to add perhaps use the --prune-empty-dirs option. Another solution is to add
include rules for all specific include rules for all
the parent dirs that need to be visited. For instance, this set of rules works fine: the parent dirs that need to be visited. For instance, this set of rules works fine:
+ /some/ + /some/
+ /some/path/ + /some/path/
+ /some/path/this-file-is-found + /some/path/this-file-is-found
+ /file-also-included + /file-also-included
- * - *
Here are some examples of exclude/include matching: Here are some examples of exclude/include matching:
o "- *.o" would exclude all names matching *.o o "- *.o" would exclude all names matching *.o
o "- /foo" would exclude a file (or directory) named foo in the tran sfer-root directory o "- /foo" would exclude a file (or directory) named foo in the tran sfer-root directory
o "- foo/" would exclude any directory named foo o "- foo/" would exclude any directory named foo
o "- /foo/*/bar" named o "- /foo/*/bar" would exclude any file named bar which is at two le vels below a directory named
foo in the transfer-root directory foo in the transfer-root directory
o "- /foo/**/bar" foo o "- /foo/**/bar" would exclude any file named bar two or more lev els below a directory named foo
in the transfer-root directory in the transfer-root directory
o The files o The combination of "+ */", "+ *.c", and "- *" would include all di rectories and C source files
o The and o The combination of "+ foo/", "+ foo/bar.c", and "- *" would inc lude only the foo directory and
foo/bar.c (the foo directory must be explicitly included or it wou ld be excluded by the "*") foo/bar.c (the foo directory must be explicitly included or it wou ld be excluded by the "*")
The following modifiers are accepted after a "+" or "-": The following modifiers are accepted after a "+" or "-":
o A / specifies that the include/exclude rule should be matched o A / specifies that the include/exclude rule should be matched agai
the absolute pathname of nst the absolute pathname of
the current item. For example, "-/ /etc/passwd" would the current item. For example, "-/ /etc/passwd" would exclu
passwd file any time the de the passwd file any time the
transfer was sending files from the "/etc" directory, and "-/ transfer was sending files from the "/etc" directory, and "-/ subd
would always exclude ir/foo" would always exclude
"foo" when it is in a dir named "subdir", even if "foo" is at the root of the current transfer. "foo" when it is in a dir named "subdir", even if "foo" is at the root of the current transfer.
o A For o A ! specifies that the include/exclude should take effect if t he pattern fails to match. For
instance, "-! */" would exclude all non-directories. instance, "-! */" would exclude all non-directories.
o A in o A C is used to indicate that all the global CVS-exclude rules shou ld be inserted as excludes in
place of the "-C". No arg should follow. place of the "-C". No arg should follow.
o An the o An s is used to indicate that the rule applies to the sending side. When a rule affects the
sending side, it prevents files from being transferred. The defau lt is for a rule to affect both sending side, it prevents files from being transferred. The defau lt is for a rule to affect both
sides unless --delete-excluded was specified, in which case sides unless --delete-excluded was specified, in which case d
rules become sender-side efault rules become sender-side
only. See also the hide (H) and show (S) rules, which are an only. See also the hide (H) and show (S) rules, which are an alte
way to specify sending- rnate way to specify sending-
side includes/excludes. side includes/excludes.
o An r is used to indicate that the rule applies to the receiving o An r is used to indicate that the rule applies to the receiving
When a rule affects the side. When a rule affects the
receiving side, it prevents files from being deleted. See the receiving side, it prevents files from being deleted. See the s m
also the protect (P) and risk (R) rules, which are an also the protect (P) and risk (R) rules, which are an alterna
includes/excludes. includes/excludes.
o A p indicates that a rule is perishable, meaning that it is ignore d in directories that are being o A p indicates that a rule is perishable, meaning that it is ignore d in directories that are being
deleted. For instance, the -C option's default rules that deleted. For instance, the -C option's default rules that excl
things like "CVS" and "*.o" ude things like "CVS" and "*.o"
are marked as perishable, and will not prevent a directory that are marked as perishable, and will not prevent a directory that wa
removed on the source from s removed on the source from
being deleted on the destination. being deleted on the destination.
o An thus o An x indicates that a rule affects xattr names in xattr copy /delete operations (and is thus
ignored when matching file/dir names). If no xattr-matching rules are specified, a default xattr ignored when matching file/dir names). If no xattr-matching rules are specified, a default xattr
filtering rule is used (see the --xattrs option). filtering rule is used (see the --xattrs option).
MERGE-FILE FILTER RULES MERGE-FILE FILTER RULES
You (:) You can merge whole files into your filter rules by specifying either a merge (.) or a dir-merge (:)
filter rule (as introduced in the FILTER RULES section above). filter rule (as introduced in the FILTER RULES section above).
There are two kinds of merged files -- single-instance ('.') and per-dire ctory (':'). A single-instance There are two kinds of merged files -- single-instance ('.') and per-dire ctory (':'). A single-instance
merge file is read one time, and its rules are incorporated into the filt er list in the place of the "." merge file is read one time, and its rules are incorporated into the filt er list in the place of the "."
rule. For per-directory merge files, rsync will scan every directory rule. For per-directory merge files, rsync will scan every directory tha
it traverses for the named t it traverses for the named
file, merging its contents when the file exists into the current list of file, merging its contents when the file exists into the current list
inherited rules. These per- of inherited rules. These per-
directory rule files must be created on the sending side because it is directory rule files must be created on the sending side because it is th
sending side that is being e sending side that is being
scanned for the available files to transfer. These rule files may scanned for the available files to transfer. These rule files may als
to be transferred to the o need to be transferred to the
receiving side if you want them to affect what files don't get receiving side if you want them to affect what files don't get deleted
(see PER-DIRECTORY RULES AND (see PER-DIRECTORY RULES AND
DELETE below). DELETE below).
Some examples: Some examples:
merge /etc/rsync/default.rules merge /etc/rsync/default.rules
. /etc/rsync/default.rules . /etc/rsync/default.rules
dir-merge .per-dir-filter dir-merge .per-dir-filter
dir-merge,n- .non-inherited-per-dir-excludes dir-merge,n- .non-inherited-per-dir-excludes
:n- .non-inherited-per-dir-excludes :n- .non-inherited-per-dir-excludes
The following modifiers are accepted after a merge or dir-merge rule: The following modifiers are accepted after a merge or dir-merge rule:
o A rule-parsing o A - specifies that the file should consist of only exclude patte rns, with no other rule-parsing
o A rule-parsing o A + specifies that the file should consist of only include pattern s, with no other rule-parsing
o A C is a way to specify that the file should be read in a o A C is a way to specify that the file should be read in a CVS-co
manner. This turns on mpatible manner. This turns on
'n', 'w', and '-', but also allows the list-clearing token (!) 'n', 'w', and '-', but also allows the list-clearing token (!) to
be specified. If no filename be specified. If no filename
is provided, ".cvsignore" is assumed. is provided, ".cvsignore" is assumed.
o A "dir- o A e will exclude the merge-file name from the transfer; e.g. "di r-merge,e .rules" is like "dir-
merge .rules" and "- .rules". merge .rules" and "- .rules".
o An n specifies that the rules are not inherited by subdirectories. o An n specifies that the rules are not inherited by subdirectories.
o A line-splitting. o A w specifies that the rules are word-split on whitespace instead of the normal line-splitting.
This also turns off comments. Note: the space that separates the prefix from the rule is treated This also turns off comments. Note: the space that separates the prefix from the rule is treated
specially, so "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't also dis- specially, so "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't also dis-
abled). abled).
o You may also specify any of the modifiers for the "+" or "-" o You may also specify any of the modifiers for the "+" or "-" rul
(above) in order to have the es (above) in order to have the
rules that are read in from the file default to having that rules that are read in from the file default to having that modifi
set (except for the ! modi- er set (except for the ! modi-
fier, which would not be useful). For instance, "merge,-/ fier, which would not be useful). For instance, "merge,-/ .ex
would treat the contents of cl" would treat the contents of
.excl as absolute-path excludes, while "dir-merge,s .filt" and .excl as absolute-path excludes, while "dir-merge,s .filt" and ":s
would each make all their C" would each make all their
per-directory rules apply only on the sending side. If the merge per-directory rules apply only on the sending side. If the merge
rule specifies sides to affect rule specifies sides to affect
(via the s or r modifier or both), then the rules in the file must not specify sides (via a modi- (via the s or r modifier or both), then the rules in the file must not specify sides (via a modi-
fier or a rule prefix such as hide). fier or a rule prefix such as hide).
Per-directory found Per-directory rules are inherited in all subdirectories of the directory where the merge-file was found
unless the 'n' modifier was used. Each subdirectory's rules are prefixed to the inherited per-directory unless the 'n' modifier was used. Each subdirectory's rules are prefixed to the inherited per-directory
rules The rules from its parents, which gives the newest rules a higher priority than the inherited rules. The
entire set of dir-merge rules are grouped together in the spot where the merge-file was specified, so it entire set of dir-merge rules are grouped together in the spot where the merge-file was specified, so it
is possible to override dir-merge rules via a rule that got is possible to override dir-merge rules via a rule that got specifie
in the list of global d earlier in the list of global
rules. When the list-clearing rule ("!") is read from a per-directory rules. When the list-clearing rule ("!") is read from a per-directory fi
it only clears the inher- le, it only clears the inher-
ited rules for the current merge file. ited rules for the current merge file.
Another a Another way to prevent a single rule from a dir-merge file from being i nherited is to anchor it with a
leading slash. Anchored rules in a per-directory merge-file are relative to the merge-file's directory, leading slash. Anchored rules in a per-directory merge-file are relative to the merge-file's directory,
so a pattern "/foo" would only match the file "foo" in the directory wher e the dir-merge filter file was so a pattern "/foo" would only match the file "foo" in the directory wher e the dir-merge filter file was
found. found.
Here's an example filter file which you'd specify via --filter=". file": Here's an example filter file which you'd specify via --filter=". file":
merge /home/user/.global-filter merge /home/user/.global-filter
- *.gz - *.gz
dir-merge .rules dir-merge .rules
+ *.[ch] + *.[ch]
- *.o - *.o
- foo* - foo*
This will merge the contents of the /home/user/.global-filter file at This will merge the contents of the /home/user/.global-filter file at the
the start of the list and also start of the list and also
turns the ".rules" filename into a per-directory filter file. All turns the ".rules" filename into a per-directory filter file. All rule
read in prior to the start of s read in prior to the start of
the directory scan follow the global anchoring rules (i.e. a leading the directory scan follow the global anchoring rules (i.e. a leading slas
matches at the root of the h matches at the root of the
transfer). transfer).
If a per-directory merge-file is specified with a path that is a parent If a per-directory merge-file is specified with a path that is a parent
of the first transfer directory of the first transfer
directory, rsync will scan all the parent dirs from that starting directory, rsync will scan all the parent dirs from that starting point t
t the transfer directory for o the transfer directory for
the indicated per-directory file. For instance, here is a common filter (see -F): the indicated per-directory file. For instance, here is a common filter (see -F):
--filter=': /.rsync-filter' --filter=': /.rsync-filter'
That rule tells rsync to scan for the file .rsync-filter in all That rule tells rsync to scan for the file .rsync-filter in all directo
from the root down through ries from the root down through
the parent directory of the transfer prior to the start of the normal the parent directory of the transfer prior to the start of the normal dir
scan of the file in the ectory scan of the file in the
directories that are sent as a part of the transfer. (Note: for an rsync directories that are sent as a part of the transfer. (Note: for an rsync
daemon, the root is always the daemon, the root is always the
same as the module's "path".) same as the module's "path".)
Some examples of this pre-scanning for per-directory files: Some examples of this pre-scanning for per-directory files:
rsync -avF /src/path/ /dest/dir rsync -avF /src/path/ /dest/dir
rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir
The first two commands above will look for ".rsync-filter" in "/" The first two commands above will look for ".rsync-filter" in "/" and "/
before the normal scan src" before the normal scan
begins looking for the file in "/src/path" and its subdirectories. The begins looking for the file in "/src/path" and its subdirectories. The
command avoids the parent- last command avoids the parent-
dir scan and only looks for the ".rsync-filter" files in each directory t hat is a part of the transfer. dir scan and only looks for the ".rsync-filter" files in each directory t hat is a part of the transfer.
If you want to include the contents of a ".cvsignore" in your If you want to include the contents of a ".cvsignore" in your patterns, y
should use the rule ":C", ou should use the rule ":C",
which creates a dir-merge of the .cvsignore file, but parsed in a which creates a dir-merge of the .cvsignore file, but parsed in a CVS-
manner. You can use compatible manner. You can use
this to affect where the --cvs-exclude (-C) option's inclusion of the per -directory .cvsignore file gets this to affect where the --cvs-exclude (-C) option's inclusion of the per -directory .cvsignore file gets
placed into your rules by putting the ":C" wherever you like in your placed into your rules by putting the ":C" wherever you like in your fil
rules. Without this, rsync ter rules. Without this, rsync
would add the dir-merge rule for the .cvsignore file at the end of would add the dir-merge rule for the .cvsignore file at the end of all yo
other rules (giving it a ur other rules (giving it a
lower priority than your command-line rules). For example: lower priority than your command-line rules). For example:
cat <<EOT | rsync -avC --filter='. -' a/ b cat <<EOT | rsync -avC --filter='. -' a/ b
+ foo.o + foo.o
:C :C
- *.old - *.old
EOT EOT
rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
Both of the above rsync commands are identical. Each one will merge Both of the above rsync commands are identical. Each one will merge a
the per-directory .cvsignore ll the per-directory .cvsignore
rules in the middle of the list rather than at the end. This allows rules in the middle of the list rather than at the end. This allows thei
dir-specific rules to super- r dir-specific rules to super-
sede the rules that follow the :C instead of being subservient to all sede the rules that follow the :C instead of being subservient to all y
rules. To affect the other our rules. To affect the other
CVS exclude rules (i.e. the default list of exclusions, the contents of CVS exclude rules (i.e. the default list of exclusions, the contents of $and the value HOME/.cvsignore, and the value of$CVSIGNORE) you should omit the -C command-line option and instead of $CVSIGNORE) you should omit the -C command-line option and instead in a "-C" rule into your fil- sert a "-C" rule into your fil- ter rules; e.g. "--filter=-C". ter rules; e.g. "--filter=-C". LIST-CLEARING FILTER RULE LIST-CLEARING FILTER RULE You can clear the current include/exclude list by using the "!" filter ru le (as introduced in the FILTER You can clear the current include/exclude list by using the "!" filter ru le (as introduced in the FILTER RULES section above). The "current" list is either the global list of ru les (if the rule is encountered RULES section above). The "current" list is either the global list of ru les (if the rule is encountered while parsing the filter options) or a set of per-directory rules (which are inherited in their own sub- while parsing the filter options) or a set of per-directory rules (which are inherited in their own sub- list, so a subdirectory can use this to clear out the parent's rules). list, so a subdirectory can use this to clear out the parent's rules). ANCHORING INCLUDE/EXCLUDE PATTERNS ANCHORING INCLUDE/EXCLUDE PATTERNS As mentioned earlier, global include/exclude patterns are anchored at the As mentioned earlier, global include/exclude patterns are anchored at "root of the transfer" (as the "root of the transfer" (as opposed to per-directory patterns, which are anchored at the opposed to per-directory patterns, which are anchored at the merge-file's directory). If you think of directory). If you think of the transfer as a subtree of names that are being sent from sender to the transfer as a subtree of names that are being sent from sender to the transfer-root is receiver, the transfer-root is where the tree starts to be duplicated in the destination directory. where the tree starts to be duplicated in the destination directory. Thi root governs where patterns s root governs where patterns that start with a / match. that start with a / match. Because the matching is relative to the transfer-root, changing the Because the matching is relative to the transfer-root, changing the tra slash on a source path or iling slash on a source path or changing your use of the --relative option affects the path you need to changing your use of the --relative option affects the path you need to u in your matching (in addi- se in your matching (in addi- tion to changing how much of the file tree is duplicated on the tion to changing how much of the file tree is duplicated on the destinat host). The following exam- ion host). The following exam- ples demonstrate this. ples demonstrate this. Let's say that we want to match two source files, one with an absolute Let's say that we want to match two source files, one with an absolute pa of "/home/me/foo/bar", and th of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz". Here is how the various one with a path of "/home/you/bar/baz". Here is how the various comman choices differ for a 2-source d choices differ for a 2-source transfer: transfer: Example cmd: rsync -a /home/me /home/you /dest Example cmd: rsync -a /home/me /home/you /dest +/- pattern: /me/foo/bar +/- pattern: /me/foo/bar +/- pattern: /you/bar/baz +/- pattern: /you/bar/baz Target file: /dest/me/foo/bar Target file: /dest/me/foo/bar Target file: /dest/you/bar/baz Target file: /dest/you/bar/baz Example cmd: rsync -a /home/me/ /home/you/ /dest Example cmd: rsync -a /home/me/ /home/you/ /dest +/- pattern: /foo/bar (note missing "me") +/- pattern: /foo/bar (note missing "me") skipping to change at line 2994 skipping to change at line 3033 +/- pattern: /home/you/bar/baz (ditto) +/- pattern: /home/you/bar/baz (ditto) Target file: /dest/home/me/foo/bar Target file: /dest/home/me/foo/bar Target file: /dest/home/you/bar/baz Target file: /dest/home/you/bar/baz Example cmd: cd /home; rsync -a --relative me/foo you/ /dest Example cmd: cd /home; rsync -a --relative me/foo you/ /dest +/- pattern: /me/foo/bar (starts at specified path) +/- pattern: /me/foo/bar (starts at specified path) +/- pattern: /you/bar/baz (ditto) +/- pattern: /you/bar/baz (ditto) Target file: /dest/me/foo/bar Target file: /dest/me/foo/bar Target file: /dest/you/bar/baz Target file: /dest/you/bar/baz The --verbose The easiest way to see what name you should filter is to just look at the output when using --verbose and put a / in front of the name (use the --dry-run option if you're not yet ready to copy any files). and put a / in front of the name (use the --dry-run option if you're not yet ready to copy any files). PER-DIRECTORY RULES AND DELETE PER-DIRECTORY RULES AND DELETE Without a delete option, per-directory rules are only relevant on the sen ding side, so you can feel free Without a delete option, per-directory rules are only relevant on the sen ding side, so you can feel free to modi- to exclude the merge files themselves without affecting the transfer. To make this easy, the 'e' modi- fier adds this exclude for you, as seen in these two equivalent commands: fier adds this exclude for you, as seen in these two equivalent commands: rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest rsync -av --filter=':e .excl' host:src/dir /dest rsync -av --filter=':e .excl' host:src/dir /dest However, if you want to do a delete on the receiving side AND you want However, if you want to do a delete on the receiving side AND you want files to be excluded from some files to be excluded from being deleted, you'll need to be sure that the receiving side knows what being deleted, you'll need to be sure that the receiving side knows what files to exclude. The easiest files to exclude. The easiest way is to include the per-directory merge files in the transfer and way is to include the per-directory merge files in the transfer and u --delete-after, because this se --delete-after, because this ensures that the receiving side gets all the same exclude rules as the ensures that the receiving side gets all the same exclude rules as the se side before it tries to nding side before it tries to delete anything: delete anything: rsync -avF --delete-after host:src/dir /dest rsync -avF --delete-after host:src/dir /dest However, if the merge files are not a part of the transfer, you'll However, if the merge files are not a part of the transfer, you'll nee either specify some global d to either specify some global exclude rules (i.e. specified on the command line), or you'll need to exclude rules (i.e. specified on the command line), or you'll need to mai your own per-directory ntain your own per-directory merge files on the receiving side. An example of the first is this (assu me that the remote .rules files merge files on the receiving side. An example of the first is this (assu me that the remote .rules files exclude themselves): exclude themselves): rsync -av --filter=': .rules' --filter='. /my/extra.rules' rsync -av --filter=': .rules' --filter='. /my/extra.rules' --delete host:src/dir /dest --delete host:src/dir /dest In the above example the extra.rules file can affect both sides of In the above example the extra.rules file can affect both sides of the tr but (on the sending ansfer, but (on the sending side) the rules are subservient to the rules merged from the .rules side) the rules are subservient to the rules merged from the .rules fi because they were specified les because they were specified after the per-directory merge rule. after the per-directory merge rule. In one final example, the remote side is excluding the .rsync-filter In one final example, the remote side is excluding the .rsync-filter file from the transfer, but we s from the transfer, but we want to use our own .rsync-filter files to control what gets deleted on want to use our own .rsync-filter files to control what gets deleted on receiving side. To do this the receiving side. To do this we must specifically exclude the per-directory merge files (so that they don't get deleted) and then put we must specifically exclude the per-directory merge files (so that they don't get deleted) and then put rules into the local files to control what else should not get deleted. Like one of these commands: rules into the local files to control what else should not get deleted. Like one of these commands: rsync -av --filter=':e /.rsync-filter' --delete \ rsync -av --filter=':e /.rsync-filter' --delete \ host:src/dir /dest host:src/dir /dest rsync -avFF --delete host:src/dir /dest rsync -avFF --delete host:src/dir /dest BATCH MODE BATCH MODE Batch mode can be used to apply the same set of updates to many Batch mode can be used to apply the same set of updates to many identi systems. Suppose one has a cal systems. Suppose one has a tree which is replicated on a number of hosts. Now suppose some tree which is replicated on a number of hosts. Now suppose some changes have been made to this source have been made to this source tree and those changes need to be propagated to the other hosts. In tree and those changes need to be propagated to the other hosts. In ord to do this using batch mode, er to do this using batch mode, rsync is run with the write-batch option to apply the changes made to the source tree to one of the des- rsync is run with the write-batch option to apply the changes made to the source tree to one of the des- tination the tination trees. The write-batch option causes the rsync client to store in a "batch file" all the information needed to repeat this operation against other, identical dest ination trees. information needed to repeat this operation against other, identical dest ination trees. Generating the batch file once saves having to perform the file status, c hecksum, and data block genera- Generating the batch file once saves having to perform the file status, c hecksum, and data block genera- tion more than once when updating multiple destination trees. Multicast transport protocols can be used tion more than once when updating multiple destination trees. Multicast transport protocols can be used to data to transfer the batch update files in parallel to many hosts at once, ins tead of sending the same data to every host individually. to every host individually. To apply the recorded changes to another destination tree, run rsync To apply the recorded changes to another destination tree, run rsync wit the read-batch option, speci- h the read-batch option, speci- fying the name of the same batch file, and the destination tree. fying the name of the same batch file, and the destination tree. Rsync updates the destination tree updates the destination tree using the information stored in the batch file. using the information stored in the batch file. For be For your convenience, a script file is also created when the write-b atch option is used: it will be named the same as the batch file with ".sh" appended. This script file c ontains a command-line suitable named the same as the batch file with ".sh" appended. This script file c ontains a command-line suitable for updating a destination tree using the associated batch file. It can for updating a destination tree using the associated batch file. It can be executed using a Bourne (or be executed using a Bourne (or Bourne-like) shell, optionally passing in an alternate destination Bourne-like) shell, optionally passing in an alternate destination tree pathname which is then used pathname which is then used instead of the original destination path. This is useful when the instead of the original destination path. This is useful when the desti tree path on the current nation tree path on the current host differs from the one used to create the batch file. host differs from the one used to create the batch file. Examples: Examples:$ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/ $rsync --write-batch=foo -a host:/source/dir/ /adest/dir/$ scp foo* remote: $scp foo* remote:$ ssh remote ./foo.sh /bdest/dir/ $ssh remote ./foo.sh /bdest/dir/$ rsync --write-batch=foo -a /source/dir/ /adest/dir/ $rsync --write-batch=foo -a /source/dir/ /adest/dir/$ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo \$ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
In repeat In these examples, rsync is used to update /adest/dir/ from /source/dir/ and the information to repeat
this operation is stored in "foo" and "foo.sh". The host "remote" is the n updated with the batched data this operation is stored in "foo" and "foo.sh". The host "remote" is the n updated with the batched data
going into the directory /bdest/dir. The differences between the two exa mples reveals some of the flex- going into the directory /bdest/dir. The differences between the two exa mples reveals some of the flex-
ibility you have in how you deal with batches: ibility you have in how you deal with batches:
o The first example shows that the initial copy doesn't have to o The first example shows that the initial copy doesn't have to b
-- you can push or pull e local -- you can push or pull
data to/from a remote host using either the remote-shell data to/from a remote host using either the remote-shell syntax
or rsync daemon syntax, as or rsync daemon syntax, as
desired. desired.
o The the o The first example uses the created "foo.sh" file to get the right rsync options when running the
read-batch command on the remote host. read-batch command on the remote host.
o The second example reads the batch data via standard input so that the batch file doesn't need to o The second example reads the batch data via standard input so that the batch file doesn't need to
be copied to the remote machine first. This example avoids the be copied to the remote machine first. This example avoids the
script because it needed foo.sh script because it needed
to use a modified --read-batch option, but you could edit the to use a modified --read-batch option, but you could edit the scri
file if you wished to make pt file if you wished to make
use of it (just be sure that no other option is trying to use use of it (just be sure that no other option is trying to
standard input, such as the use standard input, such as the
"--exclude-from=-" option). "--exclude-from=-" option).
Caveats: Caveats:
The read-batch option expects the destination tree that it is updating The read-batch option expects the destination tree that it is updating to
to be identical to the destina- be identical to the destina-
tion tree that was used to create the batch update fileset. When a tion tree that was used to create the batch update fileset. When a dif
between the destination ference between the destination
trees is encountered the update might be discarded with a warning (if trees is encountered the update might be discarded with a warning (if the
file appears to be up-to-date file appears to be up-to-date
already) or the file-update may be attempted and then, if the file fails to verify, the update discarded already) or the file-update may be attempted and then, if the file fails to verify, the update discarded
with an error. This means that it should be safe to re-run a with an error. This means that it should be safe to re-run a read-batch
operation if the command got operation if the command got
interrupted. If you wish to force the batched-update to always be interrupted. If you wish to force the batched-update to always be att
regardless of the file's empted regardless of the file's
size and date, use the -I option (when reading the batch). If an size and date, use the -I option (when reading the batch). If an error
occurs, the destination tree occurs, the destination tree
will probably be in a partially updated state. In that case, rsync will probably be in a partially updated state. In that case, rsync c
used in its regular (non- an be used in its regular (non-
batch) mode of operation to fix up the destination tree. batch) mode of operation to fix up the destination tree.
The rsync version used on all destinations must be at least as new as the one used to generate the batch The rsync version used on all destinations must be at least as new as the one used to generate the batch
file. batch- file. Rsync will die with an error if the protocol version in the batch file is too new for the batch-
reading rsync to handle. See also the --protocol option for a way to hav e the creating rsync generate a reading rsync to handle. See also the --protocol option for a way to hav e the creating rsync generate a
batch 2.6.3, batch file that an older rsync can understand. (Note that batch files c hanged format in version 2.6.3,
so mixing versions older than that with newer versions will not work.) so mixing versions older than that with newer versions will not work.)
When batch When reading a batch file, rsync will force the value of certain options to match the data in the batch
file if you didn't set them to the same as the batch-writing command. Ot her options can (and should) be file if you didn't set them to the same as the batch-writing command. Ot her options can (and should) be
changed. --filter changed. For instance --write-batch changes to --read-batch, --files-fro m is dropped, and the --filter
/ --include / --exclude options are not needed unless one of the --delete options is specified. / --include / --exclude options are not needed unless one of the --delete options is specified.
The code that creates the BATCH.sh file transforms any filter/include/exc lude options into a single list The code that creates the BATCH.sh file transforms any filter/include/exc lude options into a single list
that is appended as a "here" document to the shell script file. An advan ced user can use this to modify that is appended as a "here" document to the shell script file. An advan ced user can use this to modify
the exclude list if a change in what gets deleted by --delete is desired. A normal user can ignore this the exclude list if a change in what gets deleted by --delete is desired. A normal user can ignore this
detail the detail and just use the shell script as an easy way to run the appropriat e --read-batch command for the
batched data. batched data.
The implementa- The original batch mode in rsync was based on "rsync+", but the latest version uses a new implementa-
tion. tion.
Three basic behaviors are possible when rsync encounters a symbolic link in the source directory. Three basic behaviors are possible when rsync encounters a symbolic link in the source directory.
By default, symbolic links are not transferred at all. A message "skippi ng non-regular" file is emitted By default, symbolic links are not transferred at all. A message "skippi ng non-regular" file is emitted
If --links is specified, then symlinks are recreated with the same target on the destination. Note that If --links is specified, then symlinks are recreated with the same target on the destination. Note that
If the If --copy-links is specified, then symlinks are "collapsed" by copying th eir referent, rather than the
Rsync can also distinguish "safe" and "unsafe" symbolic links. An exampl e where this might be used is a Rsync can also distinguish "safe" and "unsafe" symbolic links. An exampl e where this might be used is a
web site mirror that wishes to ensure that the rsync module that is web site mirror that wishes to ensure that the rsync module that is copie
does not include symbolic d does not include symbolic
links to /etc/passwd in the public section of the site. Using links to /etc/passwd in the public section of the site. Using --copy-un
to be copied as the file they point to on the destination. Using to be copied as the file they point to on the destination. Using --safe-
to be omitted altogether. (Note that you must specify --links for --safe- links to have any effect.) to be omitted altogether. (Note that you must specify --links for --safe- links to have any effect.)
Symbolic they Symbolic links are considered unsafe if they are absolute symlinks (s tart with /), empty, or if they
contain enough ".." components to ascend from the directory being copied . contain enough ".." components to ascend from the directory being copied .
Here's a summary of how the symlink options are interpreted. The list Here's a summary of how the symlink options are interpreted. The list is
in order of precedence, so if in order of precedence, so if
your combination of options isn't mentioned, use the first line is your combination of options isn't mentioned, use the first line th
a complete subset of your at is a complete subset of your
options: options:
Turn all symlinks into normal files (leaving no symlinks for any o ther options to affect). Turn all symlinks into normal files (leaving no symlinks for any o ther options to affect).
Turn all unsafe symlinks into files and duplicate all safe symlink s. Turn all unsafe symlinks into files and duplicate all safe symlink s.
Turn all unsafe symlinks into files, noisily skip all safe symlink s. Turn all unsafe symlinks into files, noisily skip all safe symlink s.
Duplicate safe symlinks and skip unsafe ones. Duplicate safe symlinks and skip unsafe ones.
DIAGNOSTICS DIAGNOSTICS
rsync cause rsync occasionally produces error messages that may seem a little cryptic . The one that seems to cause
the most confusion is "protocol version mismatch -- is your shell clean?" . the most confusion is "protocol version mismatch -- is your shell clean?" .
This unwanted This message is usually caused by your startup scripts or remote sh ell facility producing unwanted
garbage on the stream that rsync is using for its transport. The way to diagnose this problem is to run garbage on the stream that rsync is using for its transport. The way to diagnose this problem is to run
ssh remotehost /bin/true > out.dat ssh remotehost /bin/true > out.dat
then look at out.dat. If everything is working correctly then out.dat sh ould be a zero length file. If then look at out.dat. If everything is working correctly then out.dat sh ould be a zero length file. If
you are getting the above error from rsync then you will probably find you are getting the above error from rsync then you will probably find th
out.dat contains some text at out.dat contains some text
or data. Look at the contents and try to work out what is it. or data. Look at the contents and try to work out what is producin
The most common cause is g it. The most common cause is
incorrectly configured shell startup scripts (such as .cshrc or .profile) that contain output statements incorrectly configured shell startup scripts (such as .cshrc or .profile) that contain output statements
If level If you are having trouble debugging filter patterns, then try specifying the -vv option. At this level
of verbosity rsync will show why each individual file is included or excl uded. of verbosity rsync will show why each individual file is included or excl uded.
EXIT VALUES EXIT VALUES
0 Success 0 Success
1 Syntax or usage error 1 Syntax or usage error
2 Protocol incompatibility 2 Protocol incompatibility
3 Errors selecting input/output files, dirs 3 Errors selecting input/output files, dirs
4 Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that 4 Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that
cannot the cannot support them; or an option was specified that is support ed by the client and not by the
server. server.
5 Error starting client-server protocol 5 Error starting client-server protocol
6 Daemon unable to append to log-file 6 Daemon unable to append to log-file
10 Error in socket I/O 10 Error in socket I/O
11 Error in file I/O 11 Error in file I/O
skipping to change at line 3221 skipping to change at line 3260
24 Partial transfer due to vanished source files 24 Partial transfer due to vanished source files
25 The --max-delete limit stopped deletions 25 The --max-delete limit stopped deletions
35 Timeout waiting for daemon connection 35 Timeout waiting for daemon connection
ENVIRONMENT VARIABLES ENVIRONMENT VARIABLES
CVSIGNORE CVSIGNORE
The the The CVSIGNORE environment variable supplements any ignore patterns in .cvsignore files. See the
--cvs-exclude option for more details. --cvs-exclude option for more details.
RSYNC_ICONV RSYNC_ICONV
Specify a default --iconv setting using this environment variable. (First supported in 3.0.0.) Specify a default --iconv setting using this environment variable. (First supported in 3.0.0.)
RSYNC_PROTECT_ARGS RSYNC_PROTECT_ARGS
Specify default, Specify a non-zero numeric value if you want the --protect-args o ption to be enabled by default,
or a zero value to make sure that it is disabled by default. (Firs t supported in 3.1.0.) or a zero value to make sure that it is disabled by default. (Firs t supported in 3.1.0.)
RSYNC_RSH RSYNC_RSH
The RSYNC_RSH environment variable allows you to override the defa ult shell used as the transport The RSYNC_RSH environment variable allows you to override the defa ult shell used as the transport
for rsync. Command line options are permitted after the command n ame, just as in the -e option. for rsync. Command line options are permitted after the command n ame, just as in the -e option.
RSYNC_PROXY RSYNC_PROXY
The proxy The RSYNC_PROXY environment variable allows you to redirect your rsync client to use a web proxy
when connecting to a rsync daemon. You should set RSYNC_PROXY to a hostname:port pair. when connecting to a rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
Setting RSYNC_PASSWORD to the required password allows you to run authenticated rsync connections Setting RSYNC_PASSWORD to the required password allows you to run authenticated rsync connections
to an rsync daemon without user intervention. Note that this does to an rsync daemon without user intervention. Note that this
not supply a password to a does not supply a password to a
remote shell transport such as ssh; to learn how to do that, remote shell transport such as ssh; to learn how to do that, consu
the remote shell's documen- lt the remote shell's documen-
tation. tation.
USER or LOGNAME USER or LOGNAME
The an The USER or LOGNAME environment variables are used to determine the default username sent to an
rsync daemon. If neither is set, the username defaults to "nobody ". rsync daemon. If neither is set, the username defaults to "nobody ".
HOME The HOME environment variable is used to find the user's default . cvsignore file. HOME The HOME environment variable is used to find the user's default . cvsignore file.
FILES FILES
/etc/rsyncd.conf or rsyncd.conf /etc/rsyncd.conf or rsyncd.conf
rsync-ssl(1), rsyncd.conf(5) rsync-ssl(1), rsyncd.conf(5)
skipping to change at line 3270 skipping to change at line 3309
When transferring to FAT filesystems rsync may re-sync unmodified files. See the comments on the --mod- When transferring to FAT filesystems rsync may re-sync unmodified files. See the comments on the --mod-
ify-window option. ify-window option.
file permissions, devices, etc. are transferred as native numerical value s file permissions, devices, etc. are transferred as native numerical value s
Please report bugs! See the web site at https://rsync.samba.org/. Please report bugs! See the web site at https://rsync.samba.org/.
VERSION VERSION
This man page is current for version 3.2. of rsync. This man page is current for version 3.2.2 of rsync.
INTERNAL OPTIONS INTERNAL OPTIONS
The user The options --server and --sender are used internally by rsync, and should never be typed by a user
under normal circumstances. Some awareness of these options may be neede d in certain scenarios, such as under normal circumstances. Some awareness of these options may be neede d in certain scenarios, such as
when setting up a login that can only run an rsync command. For when setting up a login that can only run an rsync command. For instanc
the support directory of the e, the support directory of the
rsync distribution has an example script named rrsync (for restricted rsync distribution has an example script named rrsync (for restricted rsy
that can be used with a nc) that can be used with a
CREDITS CREDITS
A cover A web site is available at https://rsync.samba.org/. The site includes an FAQ-O-Matic which may cover
questions unanswered by this manual page. questions unanswered by this manual page.
We at We would be delighted to hear from you if you like this program. Please contact the mailing-list at
rsync@lists.samba.org. rsync@lists.samba.org.
This program uses the excellent zlib compression library written by Jean- loup Gailly and Mark Adler. This program uses the excellent zlib compression library written by Jean- loup Gailly and Mark Adler.
THANKS THANKS
Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terps tra, David Dykstra, Jos Backus, Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terps tra, David Dykstra, Jos Backus,
Sebastian Krahmer, Martin Pool, and our gone-but-not-forgotten compadre, J.W. Schultz. Sebastian Krahmer, Martin Pool, and our gone-but-not-forgotten compadre, J.W. Schultz.
Thanks proba- Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwel l and David Bell. I've proba-
bly missed some people, my apologies if I have. bly missed some people, my apologies if I have.
AUTHOR AUTHOR
rsync contributed rsync was originally written by Andrew Tridgell and Paul Mackerras. Man y people have later contributed
to it. It is currently maintained by Wayne Davison. to it. It is currently maintained by Wayne Davison.
Mailing lists for support and development are available at https://lists. samba.org/. Mailing lists for support and development are available at https://lists. samba.org/.
rsync 3.2. 2020 rsync(1) rsync 3.2.2 04 Jul 2020 rsync(1)
End of changes. 297 change blocks.
1024 lines changed or deleted 1081 lines changed or added