"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "rsync.1" between
rsync-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
--usermap=STRING custom username mapping --usermap=STRING custom username mapping
--groupmap=STRING custom groupname mapping --groupmap=STRING custom groupname mapping
--chown=USER:GROUP simple username/groupname mapping --chown=USER:GROUP simple username/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-
readable. readable.
--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
license/copyright info. license/copyright info.
Repeat the option (-VV) to include some optimization info at the e
nd of the capabilities list.
--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 affect the remote side of a transfer withou t using --remote-option -- 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 environment var using either the --checksum-choice (--cc) option or an environmen
iable 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 default) 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 -V to see the default checksum list compiled into your v Run rsync --version to see the default checksum list compiled into
ersion. your version (which may differ
from the list above).
If "none" is specified for the first (or only) name, the --whole-f If "none" is specified for the first (or only) name, the --whole-
ile 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
none" 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:
If both the client and the server are at least version 3.2.0, they When both sides of the transfer are at least 3.2.0, rsync chooses
will exchange a list of check- the first algorithm in the
sum names and choose the first one in the list that they have in c client's list of choices that is also in the server's list of
ommon. This typically means choices. If no common checksum
that they will choose xxh64 if they both support it and fall b choice is found, rsync exits with an error. If the remote rsync i
ack to MD5. If one side of the s too old to support checksum
transfer is not new enough to support this checksum negotiation, t negotiation, a value is chosen based on the protocol version (whic
hen a value is chosen based on h chooses between MD5 and vari-
the protocol version (which chooses between MD5 and various f ous flavors of MD4 based on protocol age).
lavors of MD4 based on protocol
age). The default order can be customized by setting the environment var
iable RSYNC_CHECKSUM_LIST to a
You can also override the checksum using the RSYNC_CHECKSUM_LIST e space-separated list of acceptable checksum names. If the string
nvironment variable by setting contains a "&" character, it is
it to a space-separated list of checksum names that you consider a separated into the "client string & server string", otherwise the
cceptable. If no common check- same string applies to both.
sum is found, the client exits with an error. This method does no If the string (or string portion) contains no non-whitespace c
t allow you to specify the haracters, the default checksum
transfer checksum separately from the pre-transfer checksum, list is used. This method does not allow you to specify the trans
and it ignores "auto" and all fer checksum separately from
unknown checksum names. If the remote rsync is not new enough to the pre-transfer checksum, and it discards "auto" and all unkno
handle a checksum negotiation wn checksum names. A list with
list, the list is silently ignored unless it contains the string " only invalid names results in a failed negotiation.
FAIL".
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 trea receiving side during deletion. Also keep in mind that rsync tr
ts 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 an empty directory at each mount-point it encounters ( using the attributes of 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 -
--copy-unsafe-links), a symlink -copy-unsafe-links), a symlink
to a directory on another device is treated like a mount-point. S to a directory on another device is treated like a mount-point.
ymlinks 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 aff This option is a transfer rule, not an exclude, so it doesn't affe
ect the data that goes into the ct the data that goes into the
file-lists, and thus it doesn't affect deletions. It just limits file-lists, and thus it doesn't affect deletions. It just lim
the files that the receiver its the files that the receiver
requests to be transferred. requests to be transferred.
--ignore-existing --ignore-existing
This tells rsync to skip updating files that already exist on the destination (this does not This tells rsync to skip updating files that already exist on the destination (this does not
ignore existing directories, or nothing would get done). See also --existing. ignore existing directories, or nothing would get done). See also --existing.
This option is a transfer rule, not an exclude, so it doesn't affe This option is a transfer rule, not an exclude, so it doesn't aff
ct the data that goes into the ect the data that goes into the
file-lists, and thus it doesn't affect deletions. It just lim file-lists, and thus it doesn't affect deletions. It just limits
its the files that the receiver the files that the receiver
requests to be transferred. requests to be transferred.
This option can be useful for those doing backups using the --link This option can be useful for those doing backups using the --lin
-dest 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
run is copied into a new direc- un is copied into a new direc-
tory hierarchy (when it is used properly), using --ignore-existing tory hierarchy (when it is used properly), using --ignore-existin
will ensure that the already- g will ensure that the already-
handled files don't get tweaked (which avoids a change in permiss handled files don't get tweaked (which avoids a change in permissi
ions on the hard-linked files). ons on the hard-linked files).
This does mean that this option is only looking at the existing fi This does mean that this option is only looking at the existing f
les in the destination hierar- iles in the destination hierar-
chy itself. chy itself.
--remove-source-files --remove-source-files
This tells rsync to remove from the sending side the files (mean ing non-directories) that are 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 are 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 dire the finished files get renamed into the source directory, not di
ctly 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 th files into a different directory, you should use a naming idiom
at lets rsync avoid transfer- that lets rsync avoid transfer-
ring files that are not yet finished (e.g. name the file "foo.new 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 with 3.1.0, rsync will skip the sender-side removal (and output an error) if the 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 receivin This tells rsync to delete extraneous files from the receiving sid
g side (ones that aren't on the e (ones that aren't on the
sending side), but only for the directories that are being synchro sending side), but only for the directories that are being syn
nized. You must have asked chronized. You must have asked
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
using a wildcard for the direc- sing a wildcard for the direc-
tory's contents (e.g. "dir/*") since the wildcard is expanded by t tory's contents (e.g. "dir/*") since the wildcard is expanded by
he shell and rsync thus gets a the shell and rsync thus gets a
request to transfer individual files, not the files' parent dire request to transfer individual files, not the files' parent direct
ctory. Files that are excluded ory. Files that are excluded
from the transfer are also excluded from being deleted unless y from the transfer are also excluded from being deleted unles
ou use the --delete-excluded s you use the --delete-excluded
option or mark the rules as only matching on the sending side (se option or mark the rules as only matching on the sending side (see
e 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 any files at the destination ny files at the destination
will be automatically disabled. This is to prevent temporary file will be automatically disabled. This is to prevent temporary f
system 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 --delete-WHEN 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 --delete-WH well as --delete-excluded. However, if none of the --delete-WHEN
EN 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 that the file-deletions on the receiving side be done b efore the transfer starts. 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 tight 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, i neous files would help to make the transfer possible. However, it
t does introduce a delay before does introduce a delay before
the start of the transfer, and this delay might cause the transfer 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, non-incre specified). It also forces rsync to use the old, non-incremen
mental 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 incr Request that the file-deletions on the receiving side be done inc
ementally as the transfer hap- rementally as the transfer hap-
pens. The per-directory delete scan is done right before each di pens. The per-directory delete scan is done right before each dir
rectory is checked for updates, ectory is checked for updates,
so it behaves like a more efficient --delete-before, including doi so it behaves like a more efficient --delete-before, including d
ng the deletions prior to any oing the deletions prior to any
per-directory filter files being updated. This option was firs per-directory filter files being updated. This option was first a
t added 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 compute Request that the file-deletions on the receiving side be com
d during the transfer (like puted during the transfer (like
--delete-during), and then removed after the transfer completes --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 than u with --delay-updates and/or --fuzzy, and is more efficient tha
sing --delete-after (but can n using --delete-after (but can
behave differently, since --delete-after computes the deletio behave differently, since --delete-after computes the deletions in
ns 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 (i will be created on the receiving side to hold the names (it is
t is removed while open, so you removed while open, so you
shouldn't see it during the transfer). If the creation of the tem shouldn't see it during the transfer). If the creation of the t
porary 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 that the file-deletions on the receiving side be done afte r the transfer has 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
that requires rsync to scan all hat requires rsync to scan all
the files in the transfer into memory at once (see --recursive). S the files in the transfer into memory at once (see --recursive).
ee --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 ar In addition to deleting the files on the receiving side that are n
e not on the sending side, this ot on the sending side, this
tells rsync to also delete any files on the receiving side that a tells rsync to also delete any files on the receiving side tha
re excluded (see --exclude). t are excluded (see --exclude).
See the FILTER RULES section for a way to make individual ex See the FILTER RULES section for a way to make individual exclusi
clusions 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 rsync is first processing the explicitly requested source files (e.g. command-line 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 that error, and does not try to transfer the file. This does not affect 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 (should it exist). If the destination file is a non-empty di rectory, it will only be 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 missing source files are represented by special file-list entr ies which display as a "*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 for older rsync versions: --force used to still be required w hen using --delete-after, 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 directori This tells rsync not to delete more than NUM files or directories.
es. If that limit is exceeded, If that limit is exceeded,
all further deletions are skipped through the end of the transfer. 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 w warning (including a count of the skipped deletions) and exits wit
ith 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 with version 3.0.0, you may specify --max-delete=0 to be warned about any 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", so if you don't know what version the client is, you can use the less obvious --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 can be suffixed with a string to indicate a size multiplier , and may be a fractional 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 affe This option is a transfer rule, not an exclude, so it doesn't aff
ct the data that goes into the ect the data that goes into the
file-lists, and thus it doesn't affect deletions. It just lim file-lists, and thus it doesn't affect deletions. It just limits
its the files that the receiver the files that the receiver
requests to be transferred. requests to be transferred.
The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024), The accepted suffix letters are: B, K, G, T, and P fo
"M" (or "MiB") is a mebibyte r bytes, kilobytes/kibibytes,
(1024*1024), and "G" (or "GiB") is a gibibyte (1024*1024*1024). I megabytes/mebibytes, gigabytes/gibibytes, terabytes/tebibytes, and
f you want the multiplier to be petabytes/pebibytes. If you
1000 instead of 1024, use "KB", "MB", or "GB". (Note: lower-case i use a single-char suffix or add-on "ib" to it (e.g. "G" or "Gi
s also accepted for all val- B") then you get units that are
ues.) Finally, if the suffix ends in either "+1" or "-1", the valu multiples of 1024. If you use a two-letter suffix that ends with
e will be 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 th This tells rsync to avoid transferring any file that is smaller
an the specified SIZE, which than the specified SIZE, which
can help in not transferring small, junk files. See the --max-s can help in not transferring small, junk files. See the --max-siz
ize 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
expanded. See also the --files-from option. expanded. See also the --files-from option.
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 -V to check if this is the sync --version to check if this
case, as it will display "default protect-args" or "optional prote is the case, as it will display "default protect-args" or "optiona
ct-args" 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.
The "zlib" compression method typically achieves better compressio Rsync supports multiple compression methods and will choose one fo
n ratios than can be achieved r you unless you force the
by using a compressing remote shell or a compressing transport be choice using the --compress-choice (--zc) option.
cause it takes advantage of the
implicit information in the matching data blocks that are not expl
icitly sent over the connec-
tion. This matching-data compression comes at a cost of CPU,
though, and can be disabled by
using the "zlibx" compresson method instead. This can be selected
by repeating the -z option or
specifying --compress-choice=zlibx, but it only works if both sid
es of the transfer are at least
version 3.1.1.
Note that if you see an error about an option named --old-compress Run rsync --version to see the default compress list compiled into
or --new-compress, this is your version.
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 will not allow you to force the compression type.
See the --skip-compress option for the default list of file suffix When both sides of the transfer are at least 3.2.0, rsync cho
es that will not be compressed. 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 selection of th This option can be used to override the automatic negotiation of
e compression algorithm that is the compression algorithm that
the default when --compress is used. occurs when --compress is used. The option implies --compress unl
ess "none" was specified, which
instead implies --no-compress.
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 -V to see the compress list compiled into your version. Run rsync --version to see the default compress list compiled into
your version (which may differ
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.
The "zlibx" algorithm is given preference over "zlib" if both side Note that the "zlibx" compression algorithm is just the "zl
s of the transfer are at least ib" algorithm with matched data
version 3.2.0, otherwise it will choose "zlib" unless you over excluded from the compression stream (to try to make it more compa
ride it via something like -zz. tible with an external zlib
These 2 algorithms are the stame except that "zlibx" does not try implementation).
to include matched data that
was not transferred in the compression computations.
If "none" is specified, that is equivalent to using --no-compress.
This option implies --compress unless "none" was specified.
You can also override the compression negotiation using the RSYNC_
COMPRESS_LIST environment vari-
able by setting it to a space-separated list of compression names
that you consider acceptable.
If no common compress choice is found, the client exits with an er
ror. It ignores "auto" and all
unknown compression names. If the remote rsync is not new enough
to handle a compression negoti-
ation list, the list is silently ignored unless it contains the st
ring "FAIL".
--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 when the remote rsync is new enough, it can 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 sure of the c option with a --compress-choice (--zc) option unless you're sur
hoice 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 sil If you specify a too-large or too-small value, the number is silen
ently limited to a valid value. tly limited to a valid value.
This allows you to specify something like --zl=999999999 and be as This allows you to specify something like --zl=999999999 and be
sured 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
specify --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 suffix. 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 occur has an "off" level (such as zlib/zlibx) then no compression occurs
s 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
s possible. 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 character-class matching is supported: each must consist of a list of letters inside 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 ace apk avi bz2 deb flac gpg gz iso jar jpeg jpg lz lz4 l zma lzo mkv mov mp3 mp4 odb 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 b This list will be replaced by your --skip-compress list in all but
ut one situation: a copy from a one situation: a copy from a
daemon rsync will add your skipped suffixes to its list of non-com daemon rsync will add your skipped suffixes to its list of non-
pressing 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 this option rsync will transfer numeric group and user IDs r ather than using user and 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 determine 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 v The special uid 0 and the special group 0 are never mapped via u
ia user/group 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 numeric ID from the source system is used instead . See also the comments on 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 b These options allow you to specify users and groups that should be
e mapped to other values by the mapped to other values by the
receiving side. The STRING is one or more FROM:TO pairs of value receiving side. The STRING is one or more FROM:TO pairs of v
s 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 usernames or user IDs for the FROM and TO values, and the FROM value may also be a 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, though see below for why a '*' matches everything). You may instead specify a range of 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:
--usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1: usr --usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1: usr
The first match in the list is the one that is used. You should specify all your user 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 trans Note that the sender's name for the 0 user and group are not tran
mitted to the receiver, so you smitted to the receiver, so you
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 effect on the receiving side ffect on the receiving side
(typically "root"). All other FROM names match those in use on th (typically "root"). All other FROM names match those in use on
e 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 the --numeric-ids option is used, the sender does not sen d any names, so all the IDs 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 the --usermap option to have any effect, the -o (--owner) op tion must be used (or 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 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 impleme than using --usermap and --groupmap directly, but it is implemente
nted using those options inter- d using those options inter-
nally, so you cannot mix them. If either the USER or GROUP is emp nally, so you cannot mix them. If either the USER or GROUP is em
ty, 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 you specify "--chown=foo:bar", this is exactly the same as 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 option allows you to set a maximum I/O timeout in seconds. If no data is transferred 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 option allows you to set the amount of time that rsync will w ait for its connection to 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.
--address=ADDRESS --address=ADDRESS
By default rsync will bind to the wildcard address when conn By default rsync will bind to the wildcard address when connectin
ecting to an rsync daemon. The g to an rsync daemon. The
--address option allows you to specify a specific IP address (or h --address option allows you to specify a specific IP address (or
ostname) to bind to. See also hostname) to bind to. See also
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 th This specifies an alternate TCP port number to use rather than the
e default of 873. This is only default of 873. This is only
needed if you are using the double-colon (::) syntax to connect wi needed if you are using the double-colon (::) syntax to connect
th 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 URL syntax has a way to specify the port as a part of the URL). S
). See 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 tune 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
transfers 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 shel This tells rsync to use blocking I/O when launching a remote
l transport. If the remote shell transport. If the remote
shell is either rsh or remsh, rsync defaults to using blockin shell is either rsh or remsh, rsync defaults to using blocking I/
g I/O, 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 sets the output buffering mode. The mode can be None (aka Un buffered), Line, or Block (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 main use of this option is to change Full buffering to Line b uffering when rsync's output 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 a simple itemized list of the changes that are being m ade to each file, 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 2.6.7 (you can use -vv with older versions of rsync, but t hat also turns on the output 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 b string YXcstpoguax, where Y is replaced by the type of update bein
eing 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 c means that a local change/creation is occurring for th e item (such as the creation 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 . means that the item is not being updated (though it mig ht have attributes that 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 that 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 ch ated attribute for the item is being updated or a "." for no chan
ange. 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 with spaces, and (3) an unknown attribute replaces each lett er with a "?" (this can 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 c means either that a regular file has a different check sum (requires --checksum) 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 to an rsync prior to 3.0.1, this change flag will be present only for 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 s means the size of a regular file is different and wil l be updated by the file 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 being u o A t means the modification time is different and is bein
pdated to the sender's value g updated to the sender's value
(requires --times). An alternate value of T means that th (requires --times). An alternate value of T means that the
e modification time will be set modification time will be set
to the transfer time, which happens when a file/symlink/dev to the transfer time, which happens when a file/symlink/de
ice 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
its 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 p means the permissions are different and are bein g updated to the sender's 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 o means the owner is different and is being updated to the sender's value (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 g means the group is different and is being updated to the sender's value (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 being u o A u means the access (use) time is different and is bein
pdated 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
the 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" will o One other output is possible: when deleting files, the "%i" wil
utput the string "*deleting" l output the string "*deleting"
for each item that is being removed (assuming that you are talkin for each item that is being removed (assuming that you are talking
g 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 outputs t This allows you to specify exactly what the rsync client outp
o the user on a per-update uts to the user on a per-update
basis. The format is a text string containing embedded single- basis. The format is a text string containing embedded single-cha
character escape sequences pre- racter escape sequences pre-
fixed with a percent (%) character. A default format of "%n%L" is 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). For a full list of the possible escape characters, see t he "log format" setting in 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 the --out-format option implies the --info=name option , which will mention each 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 a touched directory). In addition, if the itemize-changes escape (%i) is included in 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 item that is changed in any way (as long as the receiving si de is at least 2.6.4). See 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 will output the out-format string prior to a file's transfer unless one of the 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 s fer. When this late logging is in effect and --progress is also
pecified, rsync will also out- specified, rsync will also out-
put the name of the file being transferred prior to its pro put the name of the file being transferred prior to its progre
gress 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 option 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 t specify an empty string, updated files will not be mentioned in th
he 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 data 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=stats3 --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 generi o Number of files is the count of all "files" (in the generic
c 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: 3 (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 is the count of how many "files" ( generic sense) were created (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 is the count of how many "files" ( generic sense) were created (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 total is non-zero). Note that this line is only out put if deletions are in 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 normal 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
dirs, symlinks, etc. Note that rs, symlinks, etc. Note that
rsync 3.1.0 added the word "regular" into this heading. rsync 3.1.0 added the word "regular" into this heading.
o Total file size is the total sum of all file sizes in the t ransfer. This does not 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 is the total sum of all files sizes for just the transferred o Total transferred file size is the total sum of all files s izes for just the transferred
files. files.
o Literal data is how much unmatched file-update data we had to send to the receiver for 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
sender sent it to the receiver. ender sent it to the receiver.
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 is the number of seconds that the s ender spent sending the file o File list transfer time is the number of seconds that th e sender spent sending the file
list to the receiver. list to the receiver.
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 bytes o Total bytes received is the count of all non-message b
that rsync received by the ytes that rsync received by the
client side from the server side. "Non-message" bytes mean client side from the server side. "Non-message" bytes means
s 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
output instead of trying to the output instead of trying to
test them to see if they're valid in the current locale and escap test them to see if they're valid in the current locale and escapi
ing 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 back The escape idiom that started in 2.6.7 is to output a literal bac
slash (\) and a hash (#), fol- kslash (\) and a hash (#), fol-
lowed by exactly 3 octal digits. For example, a newline woul lowed by exactly 3 octal digits. For example, a newline would ou
d output as "\#012". A literal tput as "\#012". A literal
backslash that is in a filename is not escaped unless it is follow backslash that is in a filename is not escaped unless it is
ed by a hash and 3 digits followed by a hash and 3 digits
(0-9). (0-9).
--human-readable, -h --human-readable, -h
Output numbers in a more human-readable format. There are 3 poss Output numbers in a more human-readable format. There are 3 possi
ible levels: (1) output numbers ble levels: (1) output numbers
with a separator between each set of 3 digits (either a comma or 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 t The default is human-readable level 1. Each -h option increases
he 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 spe the level down to 0 (to output numbers as pure digits) by speci
cifying the --no-human-readable fying the --no-human-readable
(--no-h) option. (--no-h) option.
The unit letters that are appended in levels 2 and 3 are: K (kilo) 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 1. (tera). For example, a 1234567-byte file would output as 1.23M
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 manner in old and new versions as long as you didn't specify a --no-h option prior to one 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 default, rsync will delete any partially transferred file if t he transfer is interrupted. 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 tells rsync to keep the partial file which should make a subsequent transfer of the 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 is 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
destination file). On the next stination file). On the next
transfer, rsync will use a file found in this dir as data to spee transfer, rsync will use a file found in this dir as data to
d 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 parti Note that if --whole-file is specified (or implied), any partial-d
al-dir 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 "--partial-dir=.rsync-part it easy to use a relative path (such as "--partial-dir=.rsync-par
ial") to have rsync create the tial") to have rsync create the
partial-directory in the destination file's directory when needed 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 remo the partial file is deleted. Note that the directory is only re
ved 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 t name, as it is expected that an absolute path is to a directory th
hat 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 add a If the partial-dir value is not an absolute path, rsync will ad
n 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 dele exist on the sending side, and will also prevent the untimely d
tion of partial-dir items on eletion of partial-dir items on
the receiving side. An example: the above --partial-dir opt the receiving side. An example: the above --partial-dir option
ion would add the equivalent of would add the equivalent of
"-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 add If you are supplying your own exclude rules, you may need to ad
your own exclude/hide/protect d your own exclude/hide/protect
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
ineffective at the end of your effective at the end of your
other rules, or (2) you may wish to override rsync's exclude choic other rules, or (2) you may wish to override rsync's exclude cho
e. For instance, if you want ice. For instance, if you want
to make rsync clean-up any left-over partial-dirs that may be l to make rsync clean-up any left-over partial-dirs that may be lyin
ying 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 or --delete-during unless you don't need rsync to use a ny of the left-over 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: the --partial-dir should not be writable by other users or it is a security 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 envi You can also set the partial-dir value the RSYNC_PARTIAL_DIR envir
ronment variable. Setting this onment variable. Setting this
in the environment does not force --partial to be enabled, but rat in the environment does not force --partial to be enabled, but
her 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 RSYNC_PARTIAL_DIR=.rsync-tmp along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-t
in your environment and then mp in your environment and then
just use the -P option to turn on the use of the .rsync-tmp dir f just use the -P option to turn on the use of the .rsync-tmp dir fo
or partial transfers. The only r partial transfers. The only
times that the --partial option does not look for this environment 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), a was specified (since --inplace conflicts with --partial-dir), and
nd (2) when --delay-updates was (2) when --delay-updates was
specified (see below). specified (see below).
When a modern rsync resumes the transfer of a file in the partial- When a modern rsync resumes the transfer of a file in the partia
dir, 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" settin For the purposes of the daemon-config's "refuse options" setting,
g, --partial-dir does not imply --partial-dir does not imply
--partial. This is so that a refusal of the --partial option can --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 stil writing of destination files with a partial transfer, while still
l allowing the safer idiom pro- allowing the safer idiom pro-
vided by --partial-dir. vided by --partial-dir.
--delay-updates --delay-updates
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 the transfer, at which time all the files are renamed into p lace in rapid succession. 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 a directory named .~tmp~ in each file's destination directo ry, but if you've specified 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
from the transfer, and what you rom the transfer, and what you
can do if you want rsync to cleanup old .~tmp~ dirs that might be 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 hold 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 p updated files. Note also that you should not use an absolute path
ath to --partial-dir unless (1) to --partial-dir unless (1)
there is no chance of any of the files in the transfer having th there is no chance of any of the files in the transfer havi
e 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
absolute) and (2) there are no bsolute) and (2) there are no
mount points in the hierarchy (since the delayed updates will fail 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 also the "atomic-rsync" perl script in the "support" subdir for an update algorithm that 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 of a bunch of useless directories when the sending rsync is recursively scanning a 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 op Note that the use of transfer rules, such as the --min-size option
tion, does not affect what goes , does not affect what goes
into the file list, and thus does not leave directories empty, eve into the file list, and thus does not leave directories empty,
n 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 al Because the file-list is actually being pruned, this option also
so affects what directories get affects what directories get
deleted when a delete is active. However, keep in mind that exclu deleted when a delete is active. However, keep in mind that exc
ded 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 th "protect" filter. For instance, this option would ensure that the
e 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 su tion directories to hold the .pdf files, and ensures that any supe
perfluous files and directories rfluous files and directories
in the destination are removed (note the hide filter of non-direct in the destination are removed (note the hide filter of non-direc
ories being used instead of an tories being used instead of an
exclude): exclude):
rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest
If you didn't want to remove superfluous destination files, t he more time-honored options 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 63 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
and 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 algor These statistics can be misleading if rsync's delta-transfer alg
ithm is in use. For example, orithm is in use. For example,
if the sender's file consists of the basis file followed by add if the sender's file consists of the basis file followed by additi
itional 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 take much longer to finish than the receiver estimated as it was finishing the 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 the file transfer finishes, rsync replaces the progress line with a summary line that 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 file was 146.38 kilobytes per second over the 8 seconds that it took to complete, it 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 the receiver to check (to see if they are up-to-date or not) r emaining out of the 396 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 n In an incremental recursion scan, rsync won't know the total numbe
umber 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 tran until it reaches the ends of the scan, but since it starts to tra
sfer files during the scan, it nsfer files during the scan, it
will display a line with the text "ir-chk" (for incremental recur will display a line with the text "ir-chk" (for incremental recurs
sion check) instead of "to-chk" ion check) instead of "to-chk"
until the point that it knows the full size of the list, at which 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 cou "to-chk". Thus, seeing "ir-chk" lets you know that the total coun
nt 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 -P option is equivalent to --partial --progress. Its purpo se is to make it much easier 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 statistics b There is also a --info=progress2 option that outputs statisti
ased on the whole transfer, cs based on the whole transfer,
rather than individual files. Use this flag without outputti rather than individual files. Use this flag without outputting a
ng 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 doing 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 --p with a lot of names. (You don't need to specify the --progr
rogress 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 rsync 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
Ctrl+T (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
current file transfer finishes urrent file transfer finishes
(so it may take a little time if a big file is being handled when (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 f name is output (if needed) followed by the --info=progress2 format
ormat of progress info. If you of progress info. If you
don't know which of the 3 rsync processes is the client process, i don't know which of the 3 rsync processes is the client process
t's 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.
--password-file=FILE --password-file=FILE
This option allows you to provide a password for accessing an This option allows you to provide a password for accessing an rsyn
rsync daemon via a file or via c daemon via a file or via
standard input if FILE is -. The file should contain just the pas standard input if FILE is -. The file should contain just the
sword 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
is 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 option does not supply a password to a remote shell transport such as ssh; to learn how 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 as the transport, this option only comes into effect after t he remote shell finishes 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
exec" script on its stdin. One ec" script on its stdin. One
possible use of this data is to give the script a secret that can 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 specif inferred if there is a single source arg and no destination speci
ied, 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 fil to turn a copy command that includes a destination arg into a file
e-listing command, or (2) to be -listing command, or (2) to be
able to specify more than one source arg (note: be sure to include 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 t keep in mind that a source arg with a wild-card is expanded by the
he 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 aff Starting with rsync 3.1.0, the sizes output by --list-only are a
ected by the --human-readable ffected by the --human-readable
option. By default they will contain digit separators, but hi option. By default they will contain digit separators, but higher
gher levels of readability will levels of readability will
output the sizes with unit suffixes. Note also that the column wi output the sizes with unit suffixes. Note also that the colum
dth for the size output has n width for the size output has
increased from 11 to 14 characters for all human-readable level increased from 11 to 14 characters for all human-readable levels.
s. 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 non-recurs or older, you may encounter an error if you ask for a non-recursiv
ive 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 yo To avoid this problem, either specify the --no-dirs option (if you
u don't need to expand a direc- don't need to expand a direc-
tory's content), or turn on recursion and exclude the 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
the data sent over the socket, e data sent over the socket,
specified in units per second. The RATE value can be suffixed wit specified in units per second. The RATE value can be suffixed w
h a string to indicate a size ith a string to indicate a size
multiplier, and may be a fractional value (e.g. "--bwlimit=1.5m 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 "K" the value will be assumed to be in units of 1024 bytes (as if "
or "KiB" had been appended). K" or "KiB" had been appended).
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 bot Rsync writes data over the socket in blocks, and this option both
h limits the size of the blocks limits the size of the blocks
that rsync writes, and tries to keep the average transfer rate 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 ca how fast the data is being sent. This is because some files can s
n show up as being rapidly sent how up as being rapidly sent
when the data is quickly buffered, while other can show up as very 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 a file that can later be applied to another identical dest ination with --read-batch. 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 batch. This lets you transport the changes to the destinat ion system via some other 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 that you can feel free to write the batch directly to some po rtable media: if this 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 and repeat the whole process to get the rest of the ch anges (as long as you 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 note that you only save bandwidth when pushing changes to a remote system because 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 wire to the receiver (when pulling, the sender is r emote, and thus can't write the over the wire to the receiver (when pulling, the sender is remote , and thus can't write the
batch). batch).
--read-batch=FILE --read-batch=FILE
Apply all of the changes stored in FILE, a file previously generat ed by --write-batch. If 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 fo Force an older protocol version to be used. This is useful for cr
r creating a batch file that is eating a batch file that is
compatible with an older version of rsync. For instance, if rsync 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 r --write-batch option, but rsync 2.6.3 is what will be used to run
un the --read-batch option, you the --read-batch option, you
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 o Rsync can convert filenames between character sets using this opti
ption. Using a CONVERT_SPEC of on. Using a CONVERT_SPEC of
"." tells rsync to look up the default character-set via the local "." tells rsync to look up the default character-set via the lo
e 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 remote 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 f option will stay the same whether you're pushing or pulling files
iles. Finally, you can specify . Finally, you can specify
either --no-iconv or a CONVERT_SPEC of "-" to turn off any convers either --no-iconv or a CONVERT_SPEC of "-" to turn off any conv
ion. 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 you specify the --protect-args option (-s), rsync will transla te the filenames you specify 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 fil Note that rsync does not do any conversion of names in filter f
es (including include/exclude iles (including include/exclude
files). It is up to you to ensure that you're specifying matchi files). It is up to you to ensure that you're specifying matching
ng rules that can match on both rules that can match on both
sides of the transfer. For instance, you can specify extra includ sides of the transfer. For instance, you can specify extra inc
e/exclude 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 t specified in its "charset" configuration parameter regardless of
he remote charset you actually the remote charset you actually
pass. Thus, you may feel free to specify just the local char pass. Thus, you may feel free to specify just the local charset
set 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 rsync to prefer IPv4/IPv6 when creating sockets or running s sh. This affects sockets 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, as well as the forwarding of the -4 or -6 option to ssh when rsync can deduce that ssh 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 option If rsync was complied without support for IPv6, the --ipv6 o
will have no effect. The ption will have no effect. The
rsync -V 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
seed is included in each block ed is included in each block
and MD4 file checksum calculation (the more modern MD5 file checks and MD4 file checksum calculation (the more modern MD5 file c
ums don't use a seed). By hecksums don't use a seed). By
default the checksum seed is generated by the server and defaul default the checksum seed is generated by the server and defaults
ts to the current time(). This to the current time(). This
option is used to set a specific checksum seed, which is useful 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 wan repeatable block checksums, or in the case where the user wants a
ts 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 tells rsync that it is to run as a daemon. The daemon you st art running may be 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 daem will detach from the current terminal and become a background da
on. The daemon will read the emon. The daemon will read the
config file (rsyncd.conf) on each connect made by a client and r config file (rsyncd.conf) on each connect made by a client and res
espond 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.
--address=ADDRESS --address=ADDRESS
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 (
(or hostname) to bind to. This or hostname) to bind to. This
makes virtual hosting possible in conjunction with the --config op makes virtual hosting possible in conjunction with the --config
tion. See also the "address" option. See also the "address"
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
the data the daemon sends over e data the daemon sends over
the socket. The client can still specify a smaller --bwlimit valu the socket. The client can still specify a smaller --bwlimit val
e, 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 and the remote user is not the super-user; in that case th e default is rsyncd.conf in 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 star This option can be used to set a daemon-config parameter when st
ting up rsync in daemon mode. arting up rsync in daemon mode.
It is equivalent to adding the parameter at the end of the glo It is equivalent to adding the parameter at the end of the global
bal 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 d When running as a daemon, this option instructs rsync to not detac
etach itself and become a back- h itself and become a back-
ground process. This option is required when running as a service 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 daemontool useful when rsync is supervised by a program such as daemontools
s 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 specifies an alternate TCP port number for the daemon to li sten on rather than the 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 loggin mat" setting in the config file. It also enables "transfer loggi
g" 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 d This option increases the amount of information the daemon logs du
uring its startup phase. After ring its startup phase. After
the client connects, the daemon's verbosity level will be controll the client connects, the daemon's verbosity level will be con
ed 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 required i to listen for connections. One of these options may be require
n 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 alr work around an IPv6 bug in the kernel (if you see an "address alre
eady 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 option If rsync was complied without support for IPv6, the --ipv6 o
will have no effect. The ption will have no effect. The
rsync -V 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 specified after --daemon, print a short help page descr ibing the options available 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 transfer 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 pa skip (exclude). The rules either directly specify include/exclude patter
tterns 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 p the list of include/exclude patterns in turn, and the first matching patt
attern 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 pattern 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 builds an ordered list of filter rules as specified on the comma nd-line. Filter rules have 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 describ You have your choice of using either short or long RULE names, as descri
ed below. If you use a short- bed below. If you use a short-
named rule, the ',' separating the RULE from the MODIFIERS is optional 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 unders follows (when present) must come after either a single space or an under
core (_). 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 rules are being read from a file, empty lines are ignored, as are comment lines that start with a When rules are being read from a file, empty lines are ignored, as are co mment lines that start with a
"#". "#".
Note that the --include & --exclude command-line options do not allow the 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 / exclu described above -- they only allow the specification of include / exclude
de 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
be interpreted as if "+ " (for e interpreted as if "+ " (for
an include option) or "- " (for an exclude option) were prefixed to the s an include option) or "- " (for an exclude option) were prefixed to the
tring. 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 ones, you can repeat the options on the command-line, use the merge- file syntax of the --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 can include and exclude files by specifying patterns using the "+", "-", etc. filter rules (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 against the names of the files that are going to be transferred . These patterns can take 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 particula o if the pattern starts with a / then it is anchored to a part
r 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
This 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 becau ified foo would match a name of "foo" anywhere in the tree b
se the algorithm is applied ecause the algorithm is applied
recursively from the top down; it behaves as if each path compone recursively from the top down; it behaves as if each path componen
nt 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" was found within a directory named "sub". See the secti on on ANCHORING 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 chooses between doing a simple string match and wildcard mat ching by checking if the 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 wildca o in a wildcard pattern, a backslash can be used to escape a wildcar
rd 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 add a wildcard to "foo\bar" (which matches the backslash) you would need to use "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 pathname, including any leading directories. If the pattern doesn't contain a / or a "**", 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
"dir_name/" had been specified) r_name/" had been specified)
and everything in the directory (as if "dir_name/**" had been sp and everything in the directory (as if "dir_name/**" had been
ecified). This behavior was specified). This behavior was
added in version 2.6.7. added in version 2.6.7.
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
-a), every subdir component of ), every subdir component of
every path is visited left to right, with each directory having a chance 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 t tent. In this way include/exclude patterns are applied recursively to th
he 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
/foo/bar" must not be excluded. /bar" must not be excluded.
Excluding one of those parent directories prevents the examination of its 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
ineffectual (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 a the files in the "some" or "some/path" directories. One solution is to
sk for all directories in the ask for all directories in the
hierarchy to be included by using a single rule: "+ */" (put it somewh hierarchy to be included by using a single rule: "+ */" (put it somewhere
ere before the "- *" rule), and before the "- *" rule), and
perhaps use the --prune-empty-dirs option. Another solution is to add sp perhaps use the --prune-empty-dirs option. Another solution is to add
ecific 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" would exclude any file named bar which is at two levels below a directory 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" would exclude any file named bar two or more level s below a directory named 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 combination of "+ */", "+ *.c", and "- *" would include all directories and C source files o The combination of "+ */", "+ *.c", and "- *" would include all di rectories and C source files
but nothing else (see also the --prune-empty-dirs option) but nothing else (see also the --prune-empty-dirs option)
o The combination of "+ foo/", "+ foo/bar.c", and "- *" would includ e only the foo directory 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 a o A / specifies that the include/exclude rule should be matched agai
gainst the absolute pathname of nst the absolute pathname of
the current item. For example, "-/ /etc/passwd" would exclude th the current item. For example, "-/ /etc/passwd" would exclu
e passwd file any time the de the passwd file any time the
transfer was sending files from the "/etc" directory, and "-/ s transfer was sending files from the "/etc" directory, and "-/ subd
ubdir/foo" 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 ! specifies that the include/exclude should take effect if the p attern fails to match. 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 C is used to indicate that all the global CVS-exclude rules sh ould be inserted as excludes 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 s is used to indicate that the rule applies to the sending side . When a rule affects 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 defa sides unless --delete-excluded was specified, in which case d
ult rules become sender-side efault rules become sender-side
only. See also the hide (H) and show (S) rules, which are an al only. See also the hide (H) and show (S) rules, which are an alte
ternate 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 si o An r is used to indicate that the rule applies to the receiving
de. 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
s modifier for more info. See odifier for more info. See
also the protect (P) and risk (R) rules, which are an alternate also the protect (P) and risk (R) rules, which are an alterna
way to specify receiver-side te way to specify receiver-side
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 exclude 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
was removed on the source from s removed on the source from
being deleted on the destination. being deleted on the destination.
o An x indicates that a rule affects xattr names in xattr copy/del ete operations (and is 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 can merge whole files into your filter rules by specifying either a m erge (.) or a dir-merge (:) 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
that 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
the sending side that is being e sending side that is being
scanned for the available files to transfer. These rule files may also n scanned for the available files to transfer. These rule files may als
eed 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 delet receiving side if you want them to affect what files don't get deleted
ed (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 - specifies that the file should consist of only exclude pattern s, with no other rule-parsing o A - specifies that the file should consist of only exclude patte rns, with no other rule-parsing
except for in-file comments. except for in-file comments.
o A + specifies that the file should consist of only include patte rns, with no other rule-parsing o A + specifies that the file should consist of only include pattern s, with no other rule-parsing
except for in-file comments. except for in-file comments.
o A C is a way to specify that the file should be read in a CVS-comp o A C is a way to specify that the file should be read in a CVS-co
atible manner. This turns on mpatible manner. This turns on
'n', 'w', and '-', but also allows the list-clearing token (!) t 'n', 'w', and '-', but also allows the list-clearing token (!) to
o be specified. If no filename be specified. If no filename
is provided, ".cvsignore" is assumed. is provided, ".cvsignore" is assumed.
o A e will exclude the merge-file name from the transfer; e.g. "dir -merge,e .rules" is like "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 w specifies that the rules are word-split on whitespace instea d of the normal 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 "-" rules 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 modif rules that are read in from the file default to having that modifi
ier set (except for the ! modi- er set (except for the ! modi-
fier, which would not be useful). For instance, "merge,-/ .excl" 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
":sC" 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 rules are inherited in all subdirectories of the directory where the merge-file was 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 from its parents, which gives the newest rules a higher priority th an the inherited 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 specified ear is possible to override dir-merge rules via a rule that got specifie
lier 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
file, 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 way to prevent a single rule from a dir-merge file from being inh erited is to anchor it with 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 rules 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 s the directory scan follow the global anchoring rules (i.e. a leading slas
lash 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 d If a per-directory merge-file is specified with a path that is a parent
irectory of the first transfer directory of the first transfer
directory, rsync will scan all the parent dirs from that starting poin directory, rsync will scan all the parent dirs from that starting point t
t to 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 directori That rule tells rsync to scan for the file .rsync-filter in all directo
es from the root down through ries from the root down through
the parent directory of the transfer prior to the start of the normal di the parent directory of the transfer prior to the start of the normal dir
rectory 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 "/" an The first two commands above will look for ".rsync-filter" in "/" and "/
d "/src" before the normal scan src" before the normal scan
begins looking for the file in "/src/path" and its subdirectories. The l begins looking for the file in "/src/path" and its subdirectories. The
ast 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 patterns If you want to include the contents of a ".cvsignore" in your patterns, y
, you should use the rule ":C", ou should use the rule ":C",
which creates a dir-merge of the .cvsignore file, but parsed in a CVS-com which creates a dir-merge of the .cvsignore file, but parsed in a CVS-
patible 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 filt placed into your rules by putting the ":C" wherever you like in your fil
er rules. Without this, rsync ter rules. Without this, rsync
would add the dir-merge rule for the .cvsignore file at the end of al would add the dir-merge rule for the .cvsignore file at the end of all yo
l your 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 all 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 the rules in the middle of the list rather than at the end. This allows thei
ir dir-specific rules to super- r dir-specific rules to super-
sede the rules that follow the :C instead of being subservient to all you sede the rules that follow the :C instead of being subservient to all y
r 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 $
$HOME/.cvsignore, and the value HOME/.cvsignore, and the value
of $CVSIGNORE) you should omit the -C command-line option and instead ins of $CVSIGNORE) you should omit the -C command-line option and instead in
ert 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 merge-file opposed to per-directory patterns, which are anchored at the merge-file's
'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 re the transfer as a subtree of names that are being sent from sender to
ceiver, the transfer-root is receiver, the transfer-root is
where the tree starts to be duplicated in the destination directory. T where the tree starts to be duplicated in the destination directory. Thi
his 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 trail Because the matching is relative to the transfer-root, changing the tra
ing 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
use in your matching (in addi- se in your matching (in addi-
tion to changing how much of the file tree is duplicated on the destinati tion to changing how much of the file tree is duplicated on the destinat
on 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
path 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 command 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 easiest way to see what name you should filter is to just look at the output when using --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 exclude the merge files themselves without affecting the transfer. T o make this easy, the 'e' 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 so However, if you want to do a delete on the receiving side AND you want
me 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 use 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
sending 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 need t However, if the merge files are not a part of the transfer, you'll nee
o 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
maintain 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 th In the above example the extra.rules file can affect both sides of the tr
e transfer, but (on the sending ansfer, but (on the sending
side) the rules are subservient to the rules merged from the .rules files 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
files 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 t want to use our own .rsync-filter files to control what gets deleted on
he 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 identical 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 change tree which is replicated on a number of hosts. Now suppose some changes
s 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 orde tree and those changes need to be propagated to the other hosts. In ord
r 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 trees. The write-batch option causes the rsync client to store in a "batch file" all 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 transfer the batch update files in parallel to many hosts at once, i nstead of sending the same 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 with 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. Rsy fying the name of the same batch file, and the destination tree. Rsync
nc 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 your convenience, a script file is also created when the write-batch option is used: it will 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 t Bourne-like) shell, optionally passing in an alternate destination tree
ree pathname which is then used pathname which is then used
instead of the original destination path. This is useful when the destin instead of the original destination path. This is useful when the desti
ation 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 these examples, rsync is used to update /adest/dir/ from /source/dir / and the information to 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 be l o The first example shows that the initial copy doesn't have to b
ocal -- you can push or pull e local -- you can push or pull
data to/from a remote host using either the remote-shell sy data to/from a remote host using either the remote-shell syntax
ntax or rsync daemon syntax, as or rsync daemon syntax, as
desired. desired.
o The first example uses the created "foo.sh" file to get the right rsync options when running 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 fo be copied to the remote machine first. This example avoids the
o.sh script because it needed foo.sh script because it needed
to use a modified --read-batch option, but you could edit the sc to use a modified --read-batch option, but you could edit the scri
ript 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 diffe tion tree that was used to create the batch update fileset. When a dif
rence between the destination ference between the destination
trees is encountered the update might be discarded with a warning (if th trees is encountered the update might be discarded with a warning (if the
e 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 read-bat with an error. This means that it should be safe to re-run a read-batch
ch operation if the command got operation if the command got
interrupted. If you wish to force the batched-update to always be attemp interrupted. If you wish to force the batched-update to always be att
ted regardless of the file's empted regardless of the file's
size and date, use the -I option (when reading the batch). If an err size and date, use the -I option (when reading the batch). If an error
or occurs, the destination tree occurs, the destination tree
will probably be in a partially updated state. In that case, rsync can b will probably be in a partially updated state. In that case, rsync c
e 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. Rsync will die with an error if the protocol version in the batch file is too new for the 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 file that an older rsync can understand. (Note that batch files ch anged format in version 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 reading a batch file, rsync will force the value of certain options to match the data in the 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. For instance --write-batch changes to --read-batch, --files-fr om is dropped, and the --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 and just use the shell script as an easy way to run the appropria te --read-batch command for 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 original batch mode in rsync was based on "rsync+", but the latest ve rsion uses a new implementa- The original batch mode in rsync was based on "rsync+", but the latest version uses a new implementa-
tion. tion.
SYMBOLIC LINKS SYMBOLIC LINKS
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
for any symlinks that exist. for any symlinks that exist.
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
--archive implies --links. --archive implies --links.
If --copy-links is specified, then symlinks are "collapsed" by copying their referent, rather than the If --copy-links is specified, then symlinks are "collapsed" by copying th eir referent, rather than the
symlink. symlink.
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 c web site mirror that wishes to ensure that the rsync module that is copie
opied does not include symbolic d does not include symbolic
links to /etc/passwd in the public section of the site. Using --copy-uns links to /etc/passwd in the public section of the site. Using --copy-un
afe-links will cause any links safe-links will cause any links
to be copied as the file they point to on the destination. Using --saf to be copied as the file they point to on the destination. Using --safe-
e-links will cause unsafe links links will cause unsafe links
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 links are considered unsafe if they are absolute symlinks (start with /), empty, or if 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 i Here's a summary of how the symlink options are interpreted. The list is
s in order of precedence, so if in order of precedence, so if
your combination of options isn't mentioned, use the first line that 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:
--copy-links --copy-links
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).
--links --copy-unsafe-links --links --copy-unsafe-links
Turn all unsafe symlinks into files and duplicate all safe symlink s. Turn all unsafe symlinks into files and duplicate all safe symlink s.
--copy-unsafe-links --copy-unsafe-links
Turn all unsafe symlinks into files, noisily skip all safe symlink s. Turn all unsafe symlinks into files, noisily skip all safe symlink s.
--links --safe-links --links --safe-links
Duplicate safe symlinks and skip unsafe ones. Duplicate safe symlinks and skip unsafe ones.
--links --links
Duplicate all symlinks. Duplicate all symlinks.
DIAGNOSTICS DIAGNOSTICS
rsync occasionally produces error messages that may seem a little crypti c. The one that seems to 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 message is usually caused by your startup scripts or remote shell facility producing 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
your remote shell like this: your remote shell like this:
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
that out.dat contains some text at out.dat contains some text
or data. Look at the contents and try to work out what is producing 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
for non-interactive logins. for non-interactive logins.
If you are having trouble debugging filter patterns, then try specifying the -vv option. At this 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 support them; or an option was specified that is supported by the client and not by 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
30 Timeout in data send/receive 30 Timeout in data send/receive
35 Timeout waiting for daemon connection 35 Timeout waiting for daemon connection
ENVIRONMENT VARIABLES ENVIRONMENT VARIABLES
CVSIGNORE CVSIGNORE
The CVSIGNORE environment variable supplements any ignore pattern s in .cvsignore files. See 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 a non-zero numeric value if you want the --protect-args op tion to be enabled by 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 RSYNC_PROXY environment variable allows you to redirect your r sync client to use a web 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.
RSYNC_PASSWORD RSYNC_PASSWORD
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, cons remote shell transport such as ssh; to learn how to do that, consu
ult the remote shell's documen- lt the remote shell's documen-
tation. tation.
USER or LOGNAME USER or LOGNAME
The USER or LOGNAME environment variables are used to determine th e default username sent to 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
SEE ALSO SEE ALSO
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
see also the comments on the --delete option see also the comments on the --delete option
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.1 of rsync. This man page is current for version 3.2.2 of rsync.
INTERNAL OPTIONS INTERNAL OPTIONS
The options --server and --sender are used internally by rsync, and shoul d never be typed by a 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 instance 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
rsync) that can be used with a nc) that can be used with a
restricted ssh login. restricted ssh login.
CREDITS CREDITS
rsync is distributed under the GNU General Public License. See the file COPYING for details. rsync is distributed under the GNU General Public License. See the file COPYING for details.
A web site is available at https://rsync.samba.org/. The site includes a n FAQ-O-Matic which may 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 would be delighted to hear from you if you like this program. Ple ase contact the mailing-list 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 also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwe ll and David Bell. I've 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 was originally written by Andrew Tridgell and Paul Mackerras. Many people have later 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.1 22 Jun 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

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)