version 1.1.1.3, 2016/11/01 09:54:32
|
version 1.1.1.4, 2021/03/17 00:32:36
|
Line 1
|
Line 1
|
.TH "rsync" "1" "21 Dec 2015" "" "" | .TH "rsync" "1" "06 Aug 2020" "rsync 3.2.3" "User Commands" |
| .P |
.SH "NAME" |
.SH "NAME" |
rsync \- a fast, versatile, remote (and local) file\-copying tool | .P |
| rsync \- a fast, versatile, remote (and local) file-copying tool |
| .P |
.SH "SYNOPSIS" |
.SH "SYNOPSIS" |
|
.P |
|
.nf |
|
Local: |
|
rsync [OPTION...] SRC... [DEST] |
|
|
.PP |
|
.nf |
|
Local: rsync [OPTION...] SRC... [DEST] |
|
|
|
Access via remote shell: |
Access via remote shell: |
Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST] | Pull: |
Push: rsync [OPTION...] SRC... [USER@]HOST:DEST | rsync [OPTION...] [USER@]HOST:SRC... [DEST] |
| Push: |
| rsync [OPTION...] SRC... [USER@]HOST:DEST |
|
|
Access via rsync daemon: |
Access via rsync daemon: |
Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST] | Pull: |
| rsync [OPTION...] [USER@]HOST::SRC... [DEST] |
rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST] |
rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST] |
Push: rsync [OPTION...] SRC... [USER@]HOST::DEST | Push: |
rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST | rsync [OPTION...] SRC... [USER@]HOST::DEST |
.fi | rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST) |
| .fi |
.PP | .P |
Usages with just one SRC arg and no DEST arg will list the source files | Usages with just one SRC arg and no DEST arg will list the source files instead |
instead of copying. | of copying. |
.PP | .P |
.SH "DESCRIPTION" |
.SH "DESCRIPTION" |
| .P |
.PP | Rsync is a fast and extraordinarily versatile file copying tool. It can copy |
Rsync is a fast and extraordinarily versatile file copying tool. It can | locally, to/from another host over any remote shell, or to/from a remote rsync |
copy locally, to/from another host over any remote shell, or to/from a | daemon. It offers a large number of options that control every aspect of its |
remote rsync daemon. It offers a large number of options that control | behavior and permit very flexible specification of the set of files to be |
every aspect of its behavior and permit very flexible specification of the | copied. It is famous for its delta-transfer algorithm, which reduces the |
set of files to be copied. It is famous for its delta\-transfer algorithm, | amount of data sent over the network by sending only the differences between |
which reduces the amount of data sent over the network by sending only the | the source files and the existing files in the destination. Rsync is widely |
differences between the source files and the existing files in the | used for backups and mirroring and as an improved copy command for everyday |
destination. Rsync is widely used for backups and mirroring and as an | use. |
improved copy command for everyday use. | .P |
.PP | Rsync finds files that need to be transferred using a "quick check" algorithm |
Rsync finds files that need to be transferred using a \(dq\&quick check\(dq\& | (by default) that looks for files that have changed in size or in last-modified |
algorithm (by default) that looks for files that have changed in size or | time. Any changes in the other preserved attributes (as requested by options) |
in last\-modified time. Any changes in the other preserved attributes (as | are made on the destination file directly when the quick check indicates that |
requested by options) are made on the destination file directly when the | the file's data does not need to be updated. |
quick check indicates that the file\(cq\&s data does not need to be updated. | .P |
.PP | |
Some of the additional features of rsync are: |
Some of the additional features of rsync are: |
.PP | .P |
.IP o | .IP o |
support for copying links, devices, owners, groups, and permissions |
support for copying links, devices, owners, groups, and permissions |
.IP o | .IP o |
exclude and exclude\-from options similar to GNU tar | exclude and exclude-from options similar to GNU tar |
.IP o | .IP o |
a CVS exclude mode for ignoring the same files that CVS would ignore |
a CVS exclude mode for ignoring the same files that CVS would ignore |
.IP o | .IP o |
can use any transparent remote shell, including ssh or rsh |
can use any transparent remote shell, including ssh or rsh |
.IP o | .IP o |
does not require super\-user privileges | does not require super-user privileges |
.IP o | .IP o |
pipelining of file transfers to minimize latency costs |
pipelining of file transfers to minimize latency costs |
.IP o | .IP o |
support for anonymous or authenticated rsync daemons (ideal for | support for anonymous or authenticated rsync daemons (ideal for mirroring) |
mirroring) | .P |
| |
.PP | |
.SH "GENERAL" |
.SH "GENERAL" |
| .P |
.PP | Rsync copies files either to or from a remote host, or locally on the current |
Rsync copies files either to or from a remote host, or locally on the | host (it does not support copying files between two remote hosts). |
current host (it does not support copying files between two remote hosts). | .P |
.PP | |
There are two different ways for rsync to contact a remote system: using a |
There are two different ways for rsync to contact a remote system: using a |
remote\-shell program as the transport (such as ssh or rsh) or contacting an | remote-shell program as the transport (such as ssh or rsh) or contacting an |
rsync daemon directly via TCP. The remote\-shell transport is used whenever | rsync daemon directly via TCP. The remote-shell transport is used whenever the |
the source or destination path contains a single colon (:) separator after | source or destination path contains a single colon (:) separator after a host |
a host specification. Contacting an rsync daemon directly happens when the | specification. Contacting an rsync daemon directly happens when the source or |
source or destination path contains a double colon (::) separator after a | destination path contains a double colon (::) separator after a host |
host specification, OR when an rsync:// URL is specified (see also the | specification, OR when an rsync:// URL is specified (see also the "USING |
\(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION\(dq\& section for | RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for an exception |
an exception to this latter rule). | to this latter rule). |
.PP | .P |
As a special case, if a single source arg is specified without a | As a special case, if a single source arg is specified without a destination, |
destination, the files are listed in an output format similar to \(dq\&ls \-l\(dq\&. | the files are listed in an output format similar to "\fBls\ \-l\fP". |
.PP | .P |
As expected, if neither the source or destination path specify a remote | As expected, if neither the source or destination path specify a remote host, |
host, the copy occurs locally (see also the \fB\-\-list\-only\fP option). | the copy occurs locally (see also the \fB\-\-list-only\fP option). |
.PP | .P |
Rsync refers to the local side as the \(dq\&client\(dq\& and the remote side as the | Rsync refers to the local side as the client and the remote side as the server. |
\(dq\&server\(dq\&. Don\(cq\&t confuse \(dq\&server\(dq\& with an rsync daemon \-\- a daemon is always a | Don't confuse server with an rsync daemon. A daemon is always a server, but a |
server, but a server can be either a daemon or a remote\-shell spawned process. | server can be either a daemon or a remote-shell spawned process. |
.PP | .P |
.SH "SETUP" |
.SH "SETUP" |
| .P |
.PP | See the file README.md for installation instructions. |
See the file README for installation instructions. | .P |
.PP | Once installed, you can use rsync to any machine that you can access via a |
Once installed, you can use rsync to any machine that you can access via | remote shell (as well as some that you can access using the rsync daemon-mode |
a remote shell (as well as some that you can access using the rsync | protocol). For remote transfers, a modern rsync uses ssh for its |
daemon\-mode protocol). For remote transfers, a modern rsync uses ssh | communications, but it may have been configured to use a different remote shell |
for its communications, but it may have been configured to use a | by default, such as rsh or remsh. |
different remote shell by default, such as rsh or remsh. | .P |
.PP | |
You can also specify any remote shell you like, either by using the \fB\-e\fP |
You can also specify any remote shell you like, either by using the \fB\-e\fP |
command line option, or by setting the RSYNC_RSH environment variable. |
command line option, or by setting the RSYNC_RSH environment variable. |
.PP | .P |
Note that rsync must be installed on both the source and destination | Note that rsync must be installed on both the source and destination machines. |
machines. | .P |
.PP | |
.SH "USAGE" |
.SH "USAGE" |
| .P |
.PP | You use rsync in the same way you use rcp. You must specify a source and a |
You use rsync in the same way you use rcp. You must specify a source | destination, one of which may be remote. |
and a destination, one of which may be remote. | .P |
.PP | |
Perhaps the best way to explain the syntax is with some examples: |
Perhaps the best way to explain the syntax is with some examples: |
.PP | .RS 4 |
.RS | .P |
\f(CWrsync \-t *.c foo:src/\fP | .nf |
| rsync -t *.c foo:src/ |
| .fi |
.RE |
.RE |
| .P |
.PP | This would transfer all files matching the pattern \fB*.c\fP from the current |
This would transfer all files matching the pattern *.c from the | directory to the directory src on the machine foo. If any of the files already |
current directory to the directory src on the machine foo. If any of | exist on the remote system then the rsync remote-update protocol is used to |
the files already exist on the remote system then the rsync | update the file by sending only the differences in the data. Note that the |
remote\-update protocol is used to update the file by sending only the | expansion of wildcards on the command-line (\fB*.c\fP) into a list of files is |
differences in the data. Note that the expansion of wildcards on the | handled by the shell before it runs rsync and not by rsync itself (exactly the |
commandline (*.c) into a list of files is handled by the shell before | same as all other Posix-style programs). |
it runs rsync and not by rsync itself (exactly the same as all other | .RS 4 |
posix\-style programs). | .P |
.PP | .nf |
.RS | rsync -avz foo:src/bar /data/tmp |
\f(CWrsync \-avz foo:src/bar /data/tmp\fP | .fi |
.RE |
.RE |
| .P |
.PP | |
This would recursively transfer all files from the directory src/bar on the |
This would recursively transfer all files from the directory src/bar on the |
machine foo into the /data/tmp/bar directory on the local machine. The | machine foo into the /data/tmp/bar directory on the local machine. The files |
files are transferred in \(dq\&archive\(dq\& mode, which ensures that symbolic | are transferred in archive mode, which ensures that symbolic links, devices, |
links, devices, attributes, permissions, ownerships, etc. are preserved | attributes, permissions, ownerships, etc. are preserved in the transfer. |
in the transfer. Additionally, compression will be used to reduce the | Additionally, compression will be used to reduce the size of data portions of |
size of data portions of the transfer. | the transfer. |
.PP | .RS 4 |
.RS | .P |
\f(CWrsync \-avz foo:src/bar/ /data/tmp\fP | .nf |
| rsync -avz foo:src/bar/ /data/tmp |
| .fi |
.RE |
.RE |
| .P |
.PP | |
A trailing slash on the source changes this behavior to avoid creating an |
A trailing slash on the source changes this behavior to avoid creating an |
additional directory level at the destination. You can think of a trailing | additional directory level at the destination. You can think of a trailing / |
/ on a source as meaning \(dq\© the contents of this directory\(dq\& as opposed | on a source as meaning "copy the contents of this directory" as opposed to |
to \(dq\© the directory by name\(dq\&, but in both cases the attributes of the | "copy the directory by name", but in both cases the attributes of the |
containing directory are transferred to the containing directory on the |
containing directory are transferred to the containing directory on the |
destination. In other words, each of the following commands copies the | destination. In other words, each of the following commands copies the files |
files in the same way, including their setting of the attributes of | in the same way, including their setting of the attributes of /dest/foo: |
/dest/foo: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWrsync \-av /src/foo /dest\fP | rsync -av /src/foo /dest |
.br | rsync -av /src/foo/ /dest/foo |
\f(CWrsync \-av /src/foo/ /dest/foo\fP | .fi |
.br | |
.RE |
.RE |
| .P |
.PP | Note also that host and module references don't require a trailing slash to |
Note also that host and module references don\(cq\&t require a trailing slash to | copy the contents of the default directory. For example, both of these copy |
copy the contents of the default directory. For example, both of these | the remote directory's contents into "/dest": |
copy the remote directory\(cq\&s contents into \(dq\&/dest\(dq\&: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWrsync \-av host: /dest\fP | rsync -av host: /dest |
.br | rsync -av host::module /dest |
\f(CWrsync \-av host::module /dest\fP | .fi |
.br | |
.RE |
.RE |
| .P |
.PP | You can also use rsync in local-only mode, where both the source and |
You can also use rsync in local\-only mode, where both the source and | destination don't have a ':' in the name. In this case it behaves like an |
destination don\(cq\&t have a \(cq\&:\(cq\& in the name. In this case it behaves like | improved copy command. |
an improved copy command. | .P |
.PP | Finally, you can list all the (listable) modules available from a particular |
Finally, you can list all the (listable) modules available from a | rsync daemon by leaving off the module name: |
particular rsync daemon by leaving off the module name: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWrsync somehost.mydomain.com::\fP | rsync somehost.mydomain.com:: |
| .fi |
.RE |
.RE |
| .P |
.PP | And, if Service Location Protocol is available, the following will list the |
See the following section for more details. | available rsync servers: |
.PP | .RS 4 |
| .P |
| .nf |
| rsync rsync:// |
| .fi |
| .RE |
| .P |
| See the following section for even more usage details. |
| .P |
| One more thing, if Service Location Protocol is available, the following will |
| list the available rsync servers: |
| .RS 4 |
| .P |
| .nf |
| rsync rsync:// |
| .fi |
| .RE |
| .P |
| See the following section for even more usage details. |
| .P |
.SH "ADVANCED USAGE" |
.SH "ADVANCED USAGE" |
| .P |
.PP | |
The syntax for requesting multiple files from a remote host is done by |
The syntax for requesting multiple files from a remote host is done by |
specifying additional remote\-host args in the same style as the first, | specifying additional remote-host args in the same style as the first, or with |
or with the hostname omitted. For instance, all these work: | the hostname omitted. For instance, all these work: |
.PP | .RS 4 |
.RS | .P |
\f(CWrsync \-av host:file1 :file2 host:file{3,4} /dest/\fP | .nf |
.br | rsync -av host:file1 :file2 host:file{3,4} /dest/ |
\f(CWrsync \-av host::modname/file{1,2} host::modname/file3 /dest/\fP | rsync -av host::modname/file{1,2} host::modname/file3 /dest/ |
.br | rsync -av host::modname/file1 ::modname/file{3,4} |
\f(CWrsync \-av host::modname/file1 ::modname/file{3,4}\fP | .fi |
.RE |
.RE |
| .P |
.PP | |
Older versions of rsync required using quoted spaces in the SRC, like these |
Older versions of rsync required using quoted spaces in the SRC, like these |
examples: |
examples: |
.PP | .RS 4 |
.RS | .P |
\f(CWrsync \-av host:'\&dir1/file1 dir2/file2'\& /dest\fP | .nf |
.br | rsync -av host:'dir1/file1 dir2/file2' /dest |
\f(CWrsync host::'\&modname/dir1/file1 modname/dir2/file2'\& /dest\fP | rsync host::'modname/dir1/file1 modname/dir2/file2' /dest |
| .fi |
.RE |
.RE |
| .P |
.PP | This word-splitting still works (by default) in the latest rsync, but is not as |
This word\-splitting still works (by default) in the latest rsync, but is | easy to use as the first method. |
not as easy to use as the first method. | .P |
.PP | |
If you need to transfer a filename that contains whitespace, you can either |
If you need to transfer a filename that contains whitespace, you can either |
specify the \fB\-\-protect\-args\fP (\fB\-s\fP) option, or you\(cq\&ll need to escape | specify the \fB\-\-protect-args\fP (\fB\-s\fP) option, or you'll need to escape the |
the whitespace in a way that the remote shell will understand. For | whitespace in a way that the remote shell will understand. For instance: |
instance: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWrsync \-av host:'\&file\e name\e with\e spaces'\& /dest\fP | rsync -av host:'file\\ name\\ with\\ spaces' /dest |
| .fi |
.RE |
.RE |
| .P |
.PP | |
.SH "CONNECTING TO AN RSYNC DAEMON" |
.SH "CONNECTING TO AN RSYNC DAEMON" |
| .P |
.PP | It is also possible to use rsync without a remote shell as the transport. In |
It is also possible to use rsync without a remote shell as the transport. | this case you will directly connect to a remote rsync daemon, typically using |
In this case you will directly connect to a remote rsync daemon, typically | TCP port 873. (This obviously requires the daemon to be running on the remote |
using TCP port 873. (This obviously requires the daemon to be running on | system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS section |
the remote system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT | below for information on that.) |
CONNECTIONS section below for information on that.) | .P |
.PP | |
Using rsync in this way is the same as using it with a remote shell except |
Using rsync in this way is the same as using it with a remote shell except |
that: |
that: |
.PP | .P |
.IP o | .IP o |
you either use a double colon :: instead of a single colon to | you either use a double colon :: instead of a single colon to separate the |
separate the hostname from the path, or you use an rsync:// URL. | hostname from the path, or you use an rsync:// URL. |
.IP o | .IP o |
the first word of the \(dq\&path\(dq\& is actually a module name. | the first word of the "path" is actually a module name. |
.IP o | .IP o |
the remote daemon may print a message of the day when you | the remote daemon may print a message of the day when you connect. |
connect. | .IP o |
.IP o | if you specify no path name on the remote daemon then the list of accessible |
if you specify no path name on the remote daemon then the | paths on the daemon will be shown. |
list of accessible paths on the daemon will be shown. | .IP o |
.IP o | if you specify no local destination then a listing of the specified files on |
if you specify no local destination then a listing of the | the remote daemon is provided. |
specified files on the remote daemon is provided. | .IP o |
.IP o | you must not specify the \fB\-\-rsh\fP (\fB\-e\fP) option (since that overrides the |
you must not specify the \fB\-\-rsh\fP (\fB\-e\fP) option. | daemon connection to use ssh\ \-\- see USING RSYNC-DAEMON FEATURES VIA A |
| REMOTE-SHELL CONNECTION below). |
.PP | .P |
An example that copies all the files in a remote module named \(dq\&src\(dq\&: | An example that copies all the files in a remote module named "src": |
.PP | .RS 4 |
.nf | .P |
rsync \-av host::src /dest | .nf |
.fi | rsync -av host::src /dest |
| .fi |
.PP | .RE |
Some modules on the remote daemon may require authentication. If so, | .P |
you will receive a password prompt when you connect. You can avoid the | Some modules on the remote daemon may require authentication. If so, you will |
password prompt by setting the environment variable RSYNC_PASSWORD to | receive a password prompt when you connect. You can avoid the password prompt |
the password you want to use or using the \fB\-\-password\-file\fP option. This | by setting the environment variable RSYNC_PASSWORD to the password you want to |
may be useful when scripting rsync. | use or using the \fB\-\-password-file\fP option. This may be useful when scripting |
.PP | rsync. |
WARNING: On some systems environment variables are visible to all | .P |
users. On those systems using \fB\-\-password\-file\fP is recommended. | WARNING: On some systems environment variables are visible to all users. On |
.PP | those systems using \fB\-\-password-file\fP is recommended. |
You may establish the connection via a web proxy by setting the | .P |
environment variable RSYNC_PROXY to a hostname:port pair pointing to | You may establish the connection via a web proxy by setting the environment |
your web proxy. Note that your web proxy\(cq\&s configuration must support | variable RSYNC_PROXY to a hostname:port pair pointing to your web proxy. Note |
proxy connections to port 873. | that your web proxy's configuration must support proxy connections to port 873. |
.PP | .P |
You may also establish a daemon connection using a program as a proxy by |
You may also establish a daemon connection using a program as a proxy by |
setting the environment variable RSYNC_CONNECT_PROG to the commands you | setting the environment variable RSYNC_CONNECT_PROG to the commands you wish to |
wish to run in place of making a direct socket connection. The string may | run in place of making a direct socket connection. The string may contain the |
contain the escape \(dq\&%H\(dq\& to represent the hostname specified in the rsync | escape "%H" to represent the hostname specified in the rsync command (so use |
command (so use \(dq\&%%\(dq\& if you need a single \(dq\&%\(dq\& in your string). For | "%%" if you need a single "%" in your string). For example: |
example: | .RS 4 |
.PP | .P |
.nf | .nf |
export RSYNC_CONNECT_PROG='\&ssh proxyhost nc %H 873'\& | export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873' |
rsync \-av targethost1::module/src/ /dest/ | rsync -av targethost1::module/src/ /dest/ |
rsync \-av rsync:://targethost2/module/src/ /dest/ | rsync -av rsync://targethost2/module/src/ /dest/ |
.fi | .fi |
| .RE |
.PP | .P |
The command specified above uses ssh to run nc (netcat) on a proxyhost, | The command specified above uses ssh to run nc (netcat) on a proxyhost, which |
which forwards all data to port 873 (the rsync daemon) on the targethost | forwards all data to port 873 (the rsync daemon) on the targethost (%H). |
(%H). | .P |
.PP | Note also that if the RSYNC_SHELL environment variable is set, that program |
.SH "USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION" | will be used to run the RSYNC_CONNECT_PROG command instead of using the default |
| shell of the \fBsystem()\fP call. |
.PP | .P |
| .SH "USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" |
| .P |
It is sometimes useful to use various features of an rsync daemon (such as |
It is sometimes useful to use various features of an rsync daemon (such as |
named modules) without actually allowing any new socket connections into a |
named modules) without actually allowing any new socket connections into a |
system (other than what is already required to allow remote\-shell access). | system (other than what is already required to allow remote-shell access). |
Rsync supports connecting to a host using a remote shell and then spawning | Rsync supports connecting to a host using a remote shell and then spawning a |
a single\-use \(dq\&daemon\(dq\& server that expects to read its config file in the | single-use "daemon" server that expects to read its config file in the home dir |
home dir of the remote user. This can be useful if you want to encrypt a | of the remote user. This can be useful if you want to encrypt a daemon-style |
daemon\-style transfer\(cq\&s data, but since the daemon is started up fresh by | transfer's data, but since the daemon is started up fresh by the remote user, |
the remote user, you may not be able to use features such as chroot or | you may not be able to use features such as chroot or change the uid used by |
change the uid used by the daemon. (For another way to encrypt a daemon | the daemon. (For another way to encrypt a daemon transfer, consider using ssh |
transfer, consider using ssh to tunnel a local port to a remote machine and | to tunnel a local port to a remote machine and configure a normal rsync daemon |
configure a normal rsync daemon on that remote host to only allow | on that remote host to only allow connections from "localhost".) |
connections from \(dq\&localhost\(dq\&.) | .P |
.PP | From the user's perspective, a daemon transfer via a remote-shell connection |
From the user\(cq\&s perspective, a daemon transfer via a remote\-shell | uses nearly the same command-line syntax as a normal rsync-daemon transfer, |
connection uses nearly the same command\-line syntax as a normal | with the only exception being that you must explicitly set the remote shell |
rsync\-daemon transfer, with the only exception being that you must | program on the command-line with the \fB\-\-rsh=COMMAND\fP option. (Setting the |
explicitly set the remote shell program on the command\-line with the | RSYNC_RSH in the environment will not turn on this functionality.) For example: |
\fB\-\-rsh=COMMAND\fP option. (Setting the RSYNC_RSH in the environment | .RS 4 |
will not turn on this functionality.) For example: | .P |
.PP | .nf |
.nf | rsync -av --rsh=ssh host::module /dest |
rsync \-av \-\-rsh=ssh host::module /dest | .fi |
.fi | .RE |
| .P |
.PP | If you need to specify a different remote-shell user, keep in mind that the |
If you need to specify a different remote\-shell user, keep in mind that the | user@ prefix in front of the host is specifying the rsync-user value (for a |
user@ prefix in front of the host is specifying the rsync\-user value (for a | module that requires user-based authentication). This means that you must give |
module that requires user\-based authentication). This means that you must | the '\-l user' option to ssh when specifying the remote-shell, as in this |
give the \(cq\&\-l user\(cq\& option to ssh when specifying the remote\-shell, as in | example that uses the short version of the \fB\-\-rsh\fP option: |
this example that uses the short version of the \fB\-\-rsh\fP option: | .RS 4 |
.PP | .P |
.nf | .nf |
rsync \-av \-e \(dq\&ssh \-l ssh\-user\(dq\& rsync\-user@host::module /dest | rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest |
.fi | .fi |
| .RE |
.PP | .P |
The \(dq\&ssh\-user\(dq\& will be used at the ssh level; the \(dq\&rsync\-user\(dq\& will be | The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to |
used to log\-in to the \(dq\&module\(dq\&. | log-in to the "module". |
.PP | .P |
.SH "STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS" |
.SH "STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS" |
| .P |
.PP | |
In order to connect to an rsync daemon, the remote system needs to have a |
In order to connect to an rsync daemon, the remote system needs to have a |
daemon already running (or it needs to have configured something like inetd | daemon already running (or it needs to have configured something like inetd to |
to spawn an rsync daemon for incoming connections on a particular port). | spawn an rsync daemon for incoming connections on a particular port). For full |
For full information on how to start a daemon that will handling incoming | information on how to start a daemon that will handling incoming socket |
socket connections, see the \fBrsyncd.conf\fP(5) man page \-\- that is the config | connections, see the \fBrsyncd.conf\fP(5) man page\ \-\- that is the config file for |
file for the daemon, and it contains the full details for how to run the | the daemon, and it contains the full details for how to run the daemon |
daemon (including stand\-alone and inetd configurations). | (including stand-alone and inetd configurations). |
.PP | .P |
If you\(cq\&re using one of the remote\-shell transports for the transfer, there is | If you're using one of the remote-shell transports for the transfer, there is |
no need to manually start an rsync daemon. |
no need to manually start an rsync daemon. |
.PP | .P |
.SH "SORTED TRANSFER ORDER" |
.SH "SORTED TRANSFER ORDER" |
| .P |
.PP | |
Rsync always sorts the specified filenames into its internal transfer list. |
Rsync always sorts the specified filenames into its internal transfer list. |
This handles the merging together of the contents of identically named |
This handles the merging together of the contents of identically named |
directories, makes it easy to remove duplicate filenames, and may confuse |
directories, makes it easy to remove duplicate filenames, and may confuse |
someone when the files are transferred in a different order than what was | someone when the files are transferred in a different order than what was given |
given on the command\-line. | on the command-line. |
.PP | .P |
If you need a particular file to be transferred prior to another, either |
If you need a particular file to be transferred prior to another, either |
separate the files into different rsync calls, or consider using |
separate the files into different rsync calls, or consider using |
\fB\-\-delay\-updates\fP (which doesn\(cq\&t affect the sorted transfer order, but | \fB\-\-delay-updates\fP (which doesn't affect the sorted transfer order, but does |
does make the final file\-updating phase happen much more rapidly). | make the final file-updating phase happen much more rapidly). |
.PP | .P |
.SH "EXAMPLES" |
.SH "EXAMPLES" |
| .P |
.PP | |
Here are some examples of how I use rsync. |
Here are some examples of how I use rsync. |
.PP | .P |
To backup my wife\(cq\&s home directory, which consists of large MS Word | To backup my wife's home directory, which consists of large MS Word files and |
files and mail folders, I use a cron job that runs | mail folders, I use a cron job that runs |
.PP | .RS 4 |
.RS | .P |
\f(CWrsync \-Cavz . arvidsjaur:backup\fP | .nf |
| rsync -Cavz . arvidsjaur:backup |
| .fi |
.RE |
.RE |
| .P |
.PP | |
each night over a PPP connection to a duplicate directory on my machine |
each night over a PPP connection to a duplicate directory on my machine |
\(dq\&arvidsjaur\(dq\&. | "arvidsjaur". |
.PP | .P |
To synchronize my samba source trees I use the following Makefile | To synchronize my samba source trees I use the following Makefile targets: |
targets: | .RS 4 |
.PP | .P |
.nf | .nf |
get: | get: |
rsync \-avuzb \-\-exclude '\&*~'\& samba:samba/ . | rsync -avuzb --exclude '*~' samba:samba/ . |
put: | put: |
rsync \-Cavuzb . samba:samba/ | rsync -Cavuzb . samba:samba/ |
sync: get put | sync: get put |
.fi | .fi |
| .RE |
.PP | .P |
this allows me to sync with a CVS directory at the other end of the | This allows me to sync with a CVS directory at the other end of the connection. |
connection. I then do CVS operations on the remote machine, which saves a | I then do CVS operations on the remote machine, which saves a lot of time as |
lot of time as the remote CVS protocol isn\(cq\&t very efficient. | the remote CVS protocol isn't very efficient. |
.PP | .P |
I mirror a directory between my \(dq\&old\(dq\& and \(dq\&new\(dq\& ftp sites with the | I mirror a directory between my "old" and "new" ftp sites with the command: |
command: | .RS 4 |
.PP | .P |
\f(CWrsync \-az \-e ssh \-\-delete ~ftp/pub/samba nimbus:\(dq\&~ftp/pub/tridge\(dq\&\fP | .nf |
.PP | rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge" |
| .fi |
| .RE |
| .P |
This is launched from cron every few hours. |
This is launched from cron every few hours. |
.PP | .P |
.SH "OPTIONS SUMMARY" | .SH "OPTION SUMMARY" |
| .P |
.PP | Here is a short summary of the options available in rsync. Please refer to the |
Here is a short summary of the options available in rsync. Please refer | detailed description below for a complete description. |
to the detailed description below for a complete description. | .P |
.nf | .nf |
| --verbose, -v increase verbosity |
\-v, \-\-verbose increase verbosity | --info=FLAGS fine-grained informational verbosity |
\-\-info=FLAGS fine\-grained informational verbosity | --debug=FLAGS fine-grained debug verbosity |
\-\-debug=FLAGS fine\-grained debug verbosity | --stderr=e|a|c change stderr output mode (default: errors) |
\-\-msgs2stderr special output handling for debugging | --quiet, -q suppress non-error messages |
\-q, \-\-quiet suppress non\-error messages | --no-motd suppress daemon-mode MOTD |
\-\-no\-motd suppress daemon\-mode MOTD (see caveat) | --checksum, -c skip based on checksum, not mod-time & size |
\-c, \-\-checksum skip based on checksum, not mod\-time & size | --sumfiles=MODE use .rsyncsums to speedup --checksum mode |
\-a, \-\-archive archive mode; equals \-rlptgoD (no \-H,\-A,\-X) | --archive, -a archive mode; equals -rlptgoD (no -H,-A,-X) |
\-\-no\-OPTION turn off an implied OPTION (e.g. \-\-no\-D) | --no-OPTION turn off an implied OPTION (e.g. --no-D) |
\-r, \-\-recursive recurse into directories | --recursive, -r recurse into directories |
\-R, \-\-relative use relative path names | --relative, -R use relative path names |
\-\-no\-implied\-dirs don'\&t send implied dirs with \-\-relative | --no-implied-dirs don't send implied dirs with --relative |
\-b, \-\-backup make backups (see \-\-suffix & \-\-backup\-dir) | --backup, -b make backups (see --suffix & --backup-dir) |
\-\-backup\-dir=DIR make backups into hierarchy based in DIR | --backup-deleted make backups only of deleted files |
\-\-suffix=SUFFIX backup suffix (default ~ w/o \-\-backup\-dir) | --backup-dir=DIR make backups into hierarchy based in DIR |
\-u, \-\-update skip files that are newer on the receiver | --backup-dir-dels=DIR backup removed files into hierarchy based in DIR |
\-\-inplace update destination files in\-place | --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) |
\-\-append append data onto shorter files | --suffix-dels=SUFFIX set removed-files suffix (def. --suffix w/o b-d-d) |
\-\-append\-verify \-\-append w/old data in file checksum | --update, -u skip files that are newer on the receiver |
\-d, \-\-dirs transfer directories without recursing | --downdate, -w skip files that are older on the receiver |
\-l, \-\-links copy symlinks as symlinks | --inplace update destination files in-place |
\-L, \-\-copy\-links transform symlink into referent file/dir | --append append data onto shorter files |
\-\-copy\-unsafe\-links only \(dq\&unsafe\(dq\& symlinks are transformed | --append-verify --append w/old data in file checksum |
\-\-safe\-links ignore symlinks that point outside the tree | --dirs, -d transfer directories without recursing |
\-\-munge\-links munge symlinks to make them safer | --mkpath create the destination's path component |
\-k, \-\-copy\-dirlinks transform symlink to dir into referent dir | --links, -l copy symlinks as symlinks |
\-K, \-\-keep\-dirlinks treat symlinked dir on receiver as dir | --copy-links, -L transform symlink into referent file/dir |
\-H, \-\-hard\-links preserve hard links | --copy-unsafe-links only "unsafe" symlinks are transformed |
\-p, \-\-perms preserve permissions | --safe-links ignore symlinks that point outside the tree |
\-E, \-\-executability preserve executability | --munge-links munge symlinks to make them safe & unusable |
\-\-chmod=CHMOD affect file and/or directory permissions | --copy-dirlinks, -k transform symlink to dir into referent dir |
\-A, \-\-acls preserve ACLs (implies \-p) | --keep-dirlinks, -K treat symlinked dir on receiver as dir |
\-X, \-\-xattrs preserve extended attributes | --hard-links, -H preserve hard links |
\-o, \-\-owner preserve owner (super\-user only) | --perms, -p preserve permissions |
\-g, \-\-group preserve group | --fileflags preserve file-flags (aka chflags) |
\-\-devices preserve device files (super\-user only) | --executability, -E preserve executability |
\-\-specials preserve special files | --chmod=CHMOD affect file and/or directory permissions |
\-D same as \-\-devices \-\-specials | --acls, -A preserve ACLs (implies --perms) |
\-t, \-\-times preserve modification times | --xattrs, -X preserve extended attributes |
\-O, \-\-omit\-dir\-times omit directories from \-\-times | --hfs-compression preserve HFS compression if supported |
\-J, \-\-omit\-link\-times omit symlinks from \-\-times | --protect-decmpfs preserve HFS compression as xattrs |
\-\-super receiver attempts super\-user activities | --owner, -o preserve owner (super-user only) |
\-\-fake\-super store/recover privileged attrs using xattrs | --group, -g preserve group |
\-S, \-\-sparse handle sparse files efficiently | --devices preserve device files (super-user only) |
\-\-preallocate allocate dest files before writing | --copy-devices copy device contents as regular file |
\-n, \-\-dry\-run perform a trial run with no changes made | --specials preserve special files |
\-W, \-\-whole\-file copy files whole (w/o delta\-xfer algorithm) | -D same as --devices --specials |
\-x, \-\-one\-file\-system don'\&t cross filesystem boundaries | --times, -t preserve modification times |
\-B, \-\-block\-size=SIZE force a fixed checksum block\-size | --atimes, -U preserve access (use) times |
\-e, \-\-rsh=COMMAND specify the remote shell to use | --open-noatime avoid changing the atime on opened files |
\-\-rsync\-path=PROGRAM specify the rsync to run on remote machine | --crtimes, -N preserve create times (newness) |
\-\-existing skip creating new files on receiver | --omit-dir-times, -O omit directories from --times |
\-\-ignore\-existing skip updating files that exist on receiver | --omit-link-times, -J omit symlinks from --times |
\-\-remove\-source\-files sender removes synchronized files (non\-dir) | --omit-dir-changes omit directories from any attribute changes |
\-\-del an alias for \-\-delete\-during | --super receiver attempts super-user activities |
\-\-delete delete extraneous files from dest dirs | --fake-super store/recover privileged attrs using xattrs |
\-\-delete\-before receiver deletes before xfer, not during | --sparse, -S turn sequences of nulls into sparse blocks |
\-\-delete\-during receiver deletes during the transfer | --sparse-block=SIZE set block size used to handle sparse files |
\-\-delete\-delay find deletions during, delete after | --preallocate allocate dest files before writing them |
\-\-delete\-after receiver deletes after transfer, not during | --write-devices write to devices as files (implies --inplace) |
\-\-delete\-excluded also delete excluded files from dest dirs | --dry-run, -n perform a trial run with no changes made |
\-\-ignore\-missing\-args ignore missing source args without error | --whole-file, -W copy files whole (w/o delta-xfer algorithm) |
\-\-delete\-missing\-args delete missing source args from destination | --checksum-choice=STR choose the checksum algorithm (aka --cc) |
\-\-ignore\-errors delete even if there are I/O errors | --db=CONFIG_FILE specify a CONFIG_FILE for DB checksums |
\-\-force force deletion of dirs even if not empty | --db-only=CONFIG_FILE behave like rsyncdb |
\-\-max\-delete=NUM don'\&t delete more than NUM files | --db-lax ignore ctime changes (use with CAUTION) |
\-\-max\-size=SIZE don'\&t transfer any file larger than SIZE | --one-file-system, -x don't cross filesystem boundaries |
\-\-min\-size=SIZE don'\&t transfer any file smaller than SIZE | --block-size=SIZE, -B force a fixed checksum block-size |
\-\-partial keep partially transferred files | --rsh=COMMAND, -e specify the remote shell to use |
\-\-partial\-dir=DIR put a partially transferred file into DIR | --rsync-path=PROGRAM specify the rsync to run on remote machine |
\-\-delay\-updates put all updated files into place at end | --existing skip creating new files on receiver |
\-m, \-\-prune\-empty\-dirs prune empty directory chains from file\-list | --ignore-existing skip updating files that exist on receiver |
\-\-numeric\-ids don'\&t map uid/gid values by user/group name | --remove-source-files sender removes synchronized files (non-dir) |
\-\-usermap=STRING custom username mapping | --source-backup ... and backs up those files |
\-\-groupmap=STRING custom groupname mapping | --del an alias for --delete-during |
\-\-chown=USER:GROUP simple username/groupname mapping | --delete delete extraneous files from dest dirs |
\-\-timeout=SECONDS set I/O timeout in seconds | --delete-before receiver deletes before xfer, not during |
\-\-contimeout=SECONDS set daemon connection timeout in seconds | --delete-during receiver deletes during the transfer |
\-I, \-\-ignore\-times don'\&t skip files that match size and time | --delete-delay find deletions during, delete after |
\-\-size\-only skip files that match in size | --delete-after receiver deletes after transfer, not during |
\-\-modify\-window=NUM compare mod\-times with reduced accuracy | --delete-excluded also delete excluded files from dest dirs |
\-T, \-\-temp\-dir=DIR create temporary files in directory DIR | --ignore-missing-args ignore missing source args without error |
\-y, \-\-fuzzy find similar file for basis if no dest file | --delete-missing-args delete missing source args from destination |
\-\-compare\-dest=DIR also compare received files relative to DIR | --ignore-errors delete even if there are I/O errors |
\-\-copy\-dest=DIR ... and include copies of unchanged files | --force-delete force deletion of directories even if not empty |
\-\-link\-dest=DIR hardlink to files in DIR when unchanged | --force-change affect user-/system-immutable files/dirs |
\-z, \-\-compress compress file data during the transfer | --force-uchange affect user-immutable files/dirs |
\-\-compress\-level=NUM explicitly set compression level | --force-schange affect system-immutable files/dirs |
\-\-skip\-compress=LIST skip compressing files with suffix in LIST | --max-delete=NUM don't delete more than NUM files |
\-C, \-\-cvs\-exclude auto\-ignore files in the same way CVS does | --max-size=SIZE don't transfer any file larger than SIZE |
\-f, \-\-filter=RULE add a file\-filtering RULE | --min-size=SIZE don't transfer any file smaller than SIZE |
\-F same as \-\-filter='\&dir\-merge /.rsync\-filter'\& | --max-alloc=SIZE change a limit relating to memory alloc |
repeated: \-\-filter='\&\- .rsync\-filter'\& | --partial keep partially transferred files |
\-\-exclude=PATTERN exclude files matching PATTERN | --partial-dir=DIR put a partially transferred file into DIR |
\-\-exclude\-from=FILE read exclude patterns from FILE | --delay-updates put all updated files into place at end |
\-\-include=PATTERN don'\&t exclude files matching PATTERN | --direct-io don't use buffer cache for xfer file I/O |
\-\-include\-from=FILE read include patterns from FILE | --prune-empty-dirs, -m prune empty directory chains from file-list |
\-\-files\-from=FILE read list of source\-file names from FILE | --fsync fsync every written file |
\-0, \-\-from0 all *from/filter files are delimited by 0s | --numeric-ids don't map uid/gid values by user/group name |
\-s, \-\-protect\-args no space\-splitting; wildcard chars only | --usermap=STRING custom username mapping |
\-\-address=ADDRESS bind address for outgoing socket to daemon | --groupmap=STRING custom groupname mapping |
\-\-port=PORT specify double\-colon alternate port number | --chown=USER:GROUP simple username/groupname mapping |
\-\-sockopts=OPTIONS specify custom TCP options | --timeout=SECONDS set I/O timeout in seconds |
\-\-blocking\-io use blocking I/O for the remote shell | --contimeout=SECONDS set daemon connection timeout in seconds |
\-\-outbuf=N|L|B set out buffering to None, Line, or Block | --ignore-times, -I don't skip files that match size and time |
\-\-stats give some file\-transfer stats | --size-only skip files that match in size |
\-8, \-\-8\-bit\-output leave high\-bit chars unescaped in output | --date-only skip files that match in mod-time |
\-h, \-\-human\-readable output numbers in a human\-readable format | --modify-window=NUM, -@ set the accuracy for mod-time comparisons |
\-\-progress show progress during transfer | --temp-dir=DIR, -T create temporary files in directory DIR |
\-P same as \-\-partial \-\-progress | --fuzzy, -y find similar file for basis if no dest file |
\-i, \-\-itemize\-changes output a change\-summary for all updates | --detect-renamed try to find renamed files to speed the xfer |
\-M, \-\-remote\-option=OPTION send OPTION to the remote side only | --compare-dest=DIR also compare destination files relative to DIR |
\-\-out\-format=FORMAT output updates using the specified FORMAT | --copy-dest=DIR ... and include copies of unchanged files |
\-\-log\-file=FILE log what we'\&re doing to the specified FILE | --link-dest=DIR hardlink to files in DIR when unchanged |
\-\-log\-file\-format=FMT log updates using the specified FMT | --clone-dest=DIR clone (reflink) files from DIR when unchanged |
\-\-password\-file=FILE read daemon\-access password from FILE | --compress, -z compress file data during the transfer |
\-\-list\-only list the files instead of copying them | --compress-choice=STR choose the compression algorithm (aka --zc) |
\-\-bwlimit=RATE limit socket I/O bandwidth | --compress-level=NUM explicitly set compression level (aka --zl) |
\-\-write\-batch=FILE write a batched update to FILE | --skip-compress=LIST skip compressing files with suffix in LIST |
\-\-only\-write\-batch=FILE like \-\-write\-batch but w/o updating dest | --cvs-exclude, -C auto-ignore files in the same way CVS does |
\-\-read\-batch=FILE read a batched update from FILE | --filter=RULE, -f add a file-filtering RULE |
\-\-protocol=NUM force an older protocol version to be used | -F same as --filter='dir-merge /.rsync-filter' |
\-\-iconv=CONVERT_SPEC request charset conversion of filenames | repeated: --filter='- .rsync-filter' |
\-\-checksum\-seed=NUM set block/file checksum seed (advanced) | --exclude=PATTERN exclude files matching PATTERN |
\-4, \-\-ipv4 prefer IPv4 | --exclude-from=FILE read exclude patterns from FILE |
\-6, \-\-ipv6 prefer IPv6 | --include=PATTERN don't exclude files matching PATTERN |
\-\-version print version number | --include-from=FILE read include patterns from FILE |
(\-h) \-\-help show this help (see below for \-h comment) | --files-from=FILE read list of source-file names from FILE |
.fi | --from0, -0 all *-from/filter files are delimited by 0s |
| --protect-args, -s no space-splitting; wildcard chars only |
.PP | --copy-as=USER[:GROUP] specify user & optional group for the copy |
| --ignore-case ignore case when comparing filenames |
| --address=ADDRESS bind address for outgoing socket to daemon |
| --port=PORT specify double-colon alternate port number |
| --sockopts=OPTIONS specify custom TCP options |
| --diffserv=[0-63] specify diffserv setting |
| --congestion-alg=STRING choose a congestion algo |
| --blocking-io use blocking I/O for the remote shell |
| --outbuf=N|L|B set out buffering to None, Line, or Block |
| --stats give some file-transfer stats |
| --8-bit-output, -8 leave high-bit chars unescaped in output |
| --human-readable, -h output numbers in a human-readable format |
| --progress show progress during transfer |
| -P same as --partial --progress |
| --itemize-changes, -i output a change-summary for all updates |
| --remote-option=OPT, -M send OPTION to the remote side only |
| --out-format=FORMAT output updates using the specified FORMAT |
| --log-file=FILE log what we're doing to the specified FILE |
| --log-file-format=FMT log updates using the specified FMT |
| --password-file=FILE read daemon-access password from FILE |
| --early-input=FILE use FILE for daemon's early exec input |
| --list-only list the files instead of copying them |
| --bwlimit=RATE limit socket I/O bandwidth |
| --slow-down=USECs sleep N usec while creating the filelist |
| --stop-after=MINS Stop rsync after MINS minutes have elapsed |
| --stop-at=y-m-dTh:m Stop rsync at the specified point in time |
| --write-batch=FILE write a batched update to FILE |
| --only-write-batch=FILE like --write-batch but w/o updating dest |
| --read-batch=FILE read a batched update from FILE |
| --source-filter=COMMAND filter file through COMMAND at source |
| --dest-filter=COMMAND filter file through COMMAND at destination |
| --protocol=NUM force an older protocol version to be used |
| --iconv=CONVERT_SPEC request charset conversion of filenames |
| --tr=BAD/GOOD transliterate filenames |
| --checksum-seed=NUM set block/file checksum seed (advanced) |
| --ipv4, -4 prefer IPv4 |
| --ipv6, -6 prefer IPv6 |
| --version, -V print the version + other info and exit |
| --help, -h (*) show this help (* -h is help only on its own) |
| .fi |
| .P |
Rsync can also be run as a daemon, in which case the following options are |
Rsync can also be run as a daemon, in which case the following options are |
accepted: | accepted: |
.nf | .P |
| .nf |
\-\-daemon run as an rsync daemon | --daemon run as an rsync daemon |
\-\-address=ADDRESS bind to the specified address | --address=ADDRESS bind to the specified address |
\-\-bwlimit=RATE limit socket I/O bandwidth | --bwlimit=RATE limit socket I/O bandwidth |
\-\-config=FILE specify alternate rsyncd.conf file | --config=FILE specify alternate rsyncd.conf file |
\-M, \-\-dparam=OVERRIDE override global daemon config parameter | --dparam=OVERRIDE, -M override global daemon config parameter |
\-\-no\-detach do not detach from the parent | --no-detach do not detach from the parent |
\-\-port=PORT listen on alternate port number | --port=PORT listen on alternate port number |
\-\-log\-file=FILE override the \(dq\&log file\(dq\& setting | --log-file=FILE override the "log file" setting |
\-\-log\-file\-format=FMT override the \(dq\&log format\(dq\& setting | --log-file-format=FMT override the "log format" setting |
\-\-sockopts=OPTIONS specify custom TCP options | --sockopts=OPTIONS specify custom TCP options |
\-v, \-\-verbose increase verbosity | --verbose, -v increase verbosity |
\-4, \-\-ipv4 prefer IPv4 | --ipv4, -4 prefer IPv4 |
\-6, \-\-ipv6 prefer IPv6 | --ipv6, -6 prefer IPv6 |
\-h, \-\-help show this help (if used after \-\-daemon) | --help, -h show this help (when used with --daemon) |
.fi | .fi |
| .P |
.PP | |
.SH "OPTIONS" |
.SH "OPTIONS" |
| .P |
.PP | Rsync accepts both long (double-dash + word) and short (single-dash + letter) |
Rsync accepts both long (double\-dash + word) and short (single\-dash + letter) | |
options. The full list of the available options are described below. If an |
options. The full list of the available options are described below. If an |
option can be specified in more than one way, the choices are comma\-separated. | option can be specified in more than one way, the choices are comma-separated. |
Some options only have a long variant, not a short. If the option takes a |
Some options only have a long variant, not a short. If the option takes a |
parameter, the parameter is only listed after the long variant, even though it |
parameter, the parameter is only listed after the long variant, even though it |
must also be specified for the short. When specifying a parameter, you can |
must also be specified for the short. When specifying a parameter, you can |
either use the form \-\-option=param or replace the \(cq\&=\(cq\& with whitespace. The | either use the form \fB\-\-option=param\fP or replace the '=' with whitespace. The |
parameter may need to be quoted in some manner for it to survive the shell\(cq\&s | parameter may need to be quoted in some manner for it to survive the shell's |
command\-line parsing. Keep in mind that a leading tilde (~) in a filename is | command-line parsing. Keep in mind that a leading tilde (\fB~\fP) in a filename is |
substituted by your shell, so \-\-option=~/foo will not change the tilde into | substituted by your shell, so \fB\-\-option=~/foo\fP will not change the tilde into |
your home directory (remove the \(cq\&=\(cq\& for that). | your home directory (remove the '=' for that). |
.PP | .P |
.IP "\fB\-\-help\fP" | .IP "\fB\-\-help\fP, \fB\-h\fP \fB(*)\fP" |
Print a short help page describing the options | Print a short help page describing the options available in rsync and exit. |
available in rsync and exit. For backward\-compatibility with older | (*) The \fB\-h\fP short option will only invoke \fB\-\-help\fP when used without other |
versions of rsync, the help will also be output if you use the \fB\-h\fP | options since it normally means \fB\-\-human-readable\fP. |
option without any other args. | .IP "\fB\-\-version\fP, \fB\-V\fP" |
.IP | Print the rsync version plus other info and exit. |
.IP "\fB\-\-version\fP" | .IP |
print the rsync version number and exit. | The output includes the default list of checksum algorithms, the default |
.IP | list of compression algorithms, a list of compiled-in capabilities, a link |
.IP "\fB\-v, \-\-verbose\fP" | to the rsync web site, and some license/copyright info. |
This option increases the amount of information you | .IP "\fB\-\-verbose\fP, \fB\-v\fP" |
are given during the transfer. By default, rsync works silently. A | This option increases the amount of information you are given during the |
single \fB\-v\fP will give you information about what files are being | transfer. By default, rsync works silently. A single \fB\-v\fP will give you |
transferred and a brief summary at the end. Two \fB\-v\fP options will give you | information about what files are being transferred and a brief summary at |
information on what files are being skipped and slightly more | the end. Two \fB\-v\fP options will give you information on what files are |
information at the end. More than two \fB\-v\fP options should only be used if | being skipped and slightly more information at the end. More than two \fB\-v\fP |
you are debugging rsync. | options should only be used if you are debugging rsync. |
.IP | .IP |
In a modern rsync, the \fB\-v\fP option is equivalent to the setting of groups |
In a modern rsync, the \fB\-v\fP option is equivalent to the setting of groups |
of \fB\-\-info\fP and \fB\-\-debug\fP options. You can choose to use these newer |
of \fB\-\-info\fP and \fB\-\-debug\fP options. You can choose to use these newer |
options in addition to, or in place of using \fB\-\-verbose\fP, as any |
options in addition to, or in place of using \fB\-\-verbose\fP, as any |
fine\-grained settings override the implied settings of \fB\-v\fP. Both | fine-grained settings override the implied settings of \fB\-v\fP. Both \fB\-\-info\fP |
\fB\-\-info\fP and \fB\-\-debug\fP have a way to ask for help that tells you | and \fB\-\-debug\fP have a way to ask for help that tells you exactly what flags |
exactly what flags are set for each increase in verbosity. | are set for each increase in verbosity. |
.IP | .IP |
However, do keep in mind that a daemon\(cq\&s \(dq\&max verbosity\(dq\& setting will limit how | However, do keep in mind that a daemon's "\fBmax\ verbosity\fP" setting will limit |
high of a level the various individual flags can be set on the daemon side. | how high of a level the various individual flags can be set on the daemon |
For instance, if the max is 2, then any info and/or debug flag that is set to | side. For instance, if the max is 2, then any info and/or debug flag that |
a higher value than what would be set by \fB\-vv\fP will be downgraded to the | is set to a higher value than what would be set by \fB\-vv\fP will be downgraded |
\fB\-vv\fP level in the daemon\(cq\&s logging. | to the \fB\-vv\fP level in the daemon's logging. |
.IP | |
.IP "\fB\-\-info=FLAGS\fP" |
.IP "\fB\-\-info=FLAGS\fP" |
This option lets you have fine\-grained control over the | This option lets you have fine-grained control over the information output |
information | you want to see. An individual flag name may be followed by a level |
output you want to see. An individual flag name may be followed by a level | |
number, with 0 meaning to silence that output, 1 being the default output |
number, with 0 meaning to silence that output, 1 being the default output |
level, and higher numbers increasing the output of that flag (for those |
level, and higher numbers increasing the output of that flag (for those |
that support higher levels). Use | that support higher levels). Use \fB\-\-info=help\fP to see all the available |
\fB\-\-info=help\fP | flag names, what they output, and what flag names are added for each |
to see all the available flag names, what they output, and what flag names | increase in the verbose level. Some examples: |
are added for each increase in the verbose level. Some examples: | .RS 4 |
.IP | .IP |
.nf | .nf |
rsync \-a \-\-info=progress2 src/ dest/ | rsync -a --info=progress2 src/ dest/ |
rsync \-avv \-\-info=stats2,misc1,flist0 src/ dest/ | rsync -avv --info=stats2,misc1,flist0 src/ dest/ |
.fi | .fi |
| .RE |
.IP | .IP |
Note that \fB\-\-info=name\fP\(cq\&s output is affected by the \fB\-\-out\-format\fP and | Note that \fB\-\-info=name\fP's output is affected by the \fB\-\-out-format\fP and |
\fB\-\-itemize\-changes\fP (\fB\-i\fP) options. See those options for more | \fB\-\-itemize-changes\fP (\fB\-i\fP) options. See those options for more information |
information on what is output and when. | on what is output and when. |
.IP | .IP |
This option was added to 3.1.0, so an older rsync on the server side might |
This option was added to 3.1.0, so an older rsync on the server side might |
reject your attempts at fine\-grained control (if one or more flags needed | reject your attempts at fine-grained control (if one or more flags needed |
to be send to the server and the server was too old to understand them). |
to be send to the server and the server was too old to understand them). |
See also the \(dq\&max verbosity\(dq\& caveat above when dealing with a daemon. | See also the "\fBmax\ verbosity\fP" caveat above when dealing with a daemon. |
.IP | |
.IP "\fB\-\-debug=FLAGS\fP" |
.IP "\fB\-\-debug=FLAGS\fP" |
This option lets you have fine\-grained control over the debug | This option lets you have fine-grained control over the debug output you |
output you want to see. An individual flag name may be followed by a level | want to see. An individual flag name may be followed by a level number, |
number, with 0 meaning to silence that output, 1 being the default output | with 0 meaning to silence that output, 1 being the default output level, |
level, and higher numbers increasing the output of that flag (for those | and higher numbers increasing the output of that flag (for those that |
that support higher levels). Use | support higher levels). Use \fB\-\-debug=help\fP to see all the available flag |
\fB\-\-debug=help\fP | names, what they output, and what flag names are added for each increase in |
to see all the available flag names, what they output, and what flag names | the verbose level. Some examples: |
are added for each increase in the verbose level. Some examples: | .RS 4 |
.IP | .IP |
.nf | .nf |
rsync \-avvv \-\-debug=none src/ dest/ | rsync -avvv --debug=none src/ dest/ |
rsync \-avA \-\-del \-\-debug=del2,acl src/ dest/ | rsync -avA --del --debug=del2,acl src/ dest/ |
.fi | .fi |
| .RE |
.IP | .IP |
Note that some debug messages will only be output when \fB\-\-msgs2stderr\fP is | Note that some debug messages will only be output when \fB\-\-stderr=all\fP is |
specified, especially those pertaining to I/O and buffer debugging. |
specified, especially those pertaining to I/O and buffer debugging. |
.IP | .IP |
This option was added to 3.1.0, so an older rsync on the server side might | Beginning in 3.2.0, this option is no longer auto-forwarded to the server |
reject your attempts at fine\-grained control (if one or more flags needed | side in order to allow you to specify different debug values for each side |
to be send to the server and the server was too old to understand them). | of the transfer, as well as to specify a new debug option that is only |
See also the \(dq\&max verbosity\(dq\& caveat above when dealing with a daemon. | present in one of the rsync versions. If you want to duplicate the same |
.IP | option on both sides, using brace expansion is an easy way to save you some |
.IP "\fB\-\-msgs2stderr\fP" | typing. This works in zsh and bash: |
This option changes rsync to send all its output | .RS 4 |
directly to stderr rather than to send messages to the client side via the | .IP |
protocol (which normally outputs info messages via stdout). This is mainly | .nf |
intended for debugging in order to avoid changing the data sent via the | rsync -aiv {-M,}--debug=del2 src/ dest/ |
protocol, since the extra protocol data can change what is being tested. | .fi |
The option does not affect the remote side of a transfer without using | .RE |
\fB\-\-remote\-option\fP \-\- e.g. \fB\-M\-\-msgs2stderr\fP. | .IP "\fB\-\-stderr=errors|all|client\fP" |
Also keep in mind that a daemon connection does not have a stderr channel to send | This option controls which processes output to stderr and if info messages |
messages back to the client side, so if you are doing any daemon\-transfer | are also changed to stderr. The mode strings can be abbreviated, so feel |
debugging using this option, you should start up a daemon using \fB\-\-no\-detach\fP | free to use a single letter value. The 3 possible choices are: |
so that you can see the stderr output on the daemon side. | .IP |
.IP | .RS |
This option has the side\-effect of making stderr output get line\-buffered so | .IP o |
that the merging of the output of 3 programs happens in a more readable manner. | \fBerrors\fP \- (the default) causes all the rsync processes to send an |
.IP | error directly to stderr, even if the process is on the remote side of |
.IP "\fB\-q, \-\-quiet\fP" | the transfer. Info messages are sent to the client side via the protocol |
This option decreases the amount of information you | stream. If stderr is not available (i.e. when directly connecting with a |
are given during the transfer, notably suppressing information messages | daemon via a socket) errors fall back to being sent via the protocol |
from the remote server. This option is useful when invoking rsync from | stream. |
cron. | .IP o |
.IP | \fBall\fP \- causes all rsync messages (info and error) to get written |
.IP "\fB\-\-no\-motd\fP" | directly to stderr from all (possible) processes. This causes stderr to |
This option affects the information that is output | become line-buffered (instead of raw) and eliminates the ability to |
by the client at the start of a daemon transfer. This suppresses the | divide up the info and error messages by file handle. For those doing |
message\-of\-the\-day (MOTD) text, but it also affects the list of modules | debugging or using several levels of verbosity, this option can help to |
that the daemon sends in response to the \(dq\&rsync host::\(dq\& request (due to | avoid clogging up the transfer stream (which should prevent any chance of |
a limitation in the rsync protocol), so omit this option if you want to | a deadlock bug hanging things up). It also enables the outputting of some |
request the list of modules from the daemon. | I/O related debug messages. |
.IP | .IP o |
.IP "\fB\-I, \-\-ignore\-times\fP" | \fBclient\fP \- causes all rsync messages to be sent to the client side |
Normally rsync will skip any files that are | via the protocol stream. One client process outputs all messages, with |
already the same size and have the same modification timestamp. | errors on stderr and info messages on stdout. This \fBwas\fP the default |
This option turns off this \(dq\&quick check\(dq\& behavior, causing all files to | in older rsync versions, but can cause error delays when a lot of |
be updated. | transfer data is ahead of the messages. If you're pushing files to an |
.IP | older rsync, you may want to use \fB\-\-stderr=all\fP since that idiom has |
.IP "\fB\-\-size\-only\fP" | been around for several releases. |
This modifies rsync\(cq\&s \(dq\&quick check\(dq\& algorithm for | .RE |
finding files that need to be transferred, changing it from the default of | .IP |
transferring files with either a changed size or a changed last\-modified | This option was added in rsync 3.2.3. This version also began the |
time to just looking for files that have changed in size. This is useful | forwarding of a non-default setting to the remote side, though rsync uses |
when starting to use rsync after using another mirroring system which may | the backward-compatible options \fB\-\-msgs2stderr\fP and \fB\-\-no-msgs2stderr\fP to |
not preserve timestamps exactly. | represent the \fBall\fP and \fBclient\fP settings, respectively. A newer rsync |
.IP | will continue to accept these older option names to maintain compatibility. |
.IP "\fB\-\-modify\-window\fP" | .IP "\fB\-\-quiet\fP, \fB\-q\fP" |
When comparing two timestamps, rsync treats the | This option decreases the amount of information you are given during the |
timestamps as being equal if they differ by no more than the modify\-window | transfer, notably suppressing information messages from the remote server. |
value. This is normally 0 (for an exact match), but you may find it useful | This option is useful when invoking rsync from cron. |
to set this to a larger value in some situations. In particular, when | .IP "\fB\-\-no-motd\fP" |
transferring to or from an MS Windows FAT filesystem (which represents | This option affects the information that is output by the client at the |
times with a 2\-second resolution), \fB\-\-modify\-window=1\fP is useful | start of a daemon transfer. This suppresses the message-of-the-day (MOTD) |
(allowing times to differ by up to 1 second). | text, but it also affects the list of modules that the daemon sends in |
.IP | response to the "rsync host::" request (due to a limitation in the rsync |
.IP "\fB\-c, \-\-checksum\fP" | protocol), so omit this option if you want to request the list of modules |
This changes the way rsync checks if the files have | from the daemon. |
been changed and are in need of a transfer. Without this option, rsync | .IP "\fB\-\-ignore-times\fP, \fB\-I\fP" |
uses a \(dq\&quick check\(dq\& that (by default) checks if each file\(cq\&s size and time | Normally rsync will skip any files that are already the same size and have |
of last modification match between the sender and receiver. This option | the same modification timestamp. This option turns off this "quick check" |
changes this to compare a 128\-bit checksum for each file that has a | behavior, causing all files to be updated. |
matching size. Generating the checksums means that both sides will expend | .IP "\fB\-\-size-only\fP" |
a lot of disk I/O reading all the data in the files in the transfer (and | This modifies rsync's "quick check" algorithm for finding files that need |
this is prior to any reading that will be done to transfer changed files), | to be transferred, changing it from the default of transferring files with |
so this can slow things down significantly. | either a changed size or a changed last-modified time to just looking for |
.IP | files that have changed in size. This is useful when starting to use rsync |
The sending side generates its checksums while it is doing the file\-system | after using another mirroring system which may not preserve timestamps |
| exactly. |
| .IP "\fB\-\-date-only\fP" |
| Normally rsync will skip any files that are already the same size and have |
| the same modification time-stamp. With the \-\-date-only option, files will |
| be skipped if they have the same timestamp, regardless of size. This may be |
| useful when the remote files have passed through a size-changing filter, |
| e.g. for encryption. |
| .IP "\fB\-\-modify-window=NUM\fP, \fB\-@\fP" |
| When comparing two timestamps, rsync treats the timestamps as being equal |
| if they differ by no more than the modify-window value. The default is 0, |
| which matches just integer seconds. If you specify a negative value (and |
| the receiver is at least version 3.1.3) then nanoseconds will also be taken |
| into account. Specifying 1 is useful for copies to/from MS Windows FAT |
| filesystems, because FAT represents times with a 2-second resolution |
| (allowing times to differ from the original by up to 1 second). |
| .IP |
| If you want all your transfers to default to comparing nanoseconds, you can |
| create a \fB~/.popt\fP file and put these lines in it: |
| .RS 4 |
| .IP |
| .nf |
| rsync alias -a -a@-1 |
| rsync alias -t -t@-1 |
| .fi |
| .RE |
| .IP |
| With that as the default, you'd need to specify \fB\-\-modify-window=0\fP (aka |
| \fB\-@0\fP) to override it and ignore nanoseconds, e.g. if you're copying |
| between ext3 and ext4, or if the receiving rsync is older than 3.1.3. |
| .IP "\fB\-\-checksum\fP, \fB\-c\fP" |
| This changes the way rsync checks if the files have been changed and are in |
| need of a transfer. Without this option, rsync uses a "quick check" that |
| (by default) checks if each file's size and time of last modification match |
| between the sender and receiver. This option changes this to compare a |
| 128-bit checksum for each file that has a matching size. Generating the |
| checksums means that both sides will expend a lot of disk I/O reading all |
| the data in the files in the transfer, so this can slow things down |
| significantly (and this is prior to any reading that will be done to |
| transfer changed files) |
| .IP |
| The sending side generates its checksums while it is doing the file-system |
scan that builds the list of the available files. The receiver generates |
scan that builds the list of the available files. The receiver generates |
its checksums when it is scanning for changed files, and will checksum any |
its checksums when it is scanning for changed files, and will checksum any |
file that has the same size as the corresponding sender\(cq\&s file: files with | file that has the same size as the corresponding sender's file: files with |
either a changed size or a changed checksum are selected for transfer. |
either a changed size or a changed checksum are selected for transfer. |
.IP | .IP |
Note that rsync always verifies that each \fItransferred\fP file was | See also the \fB\-\-sumfiles\fP option for a way to use cached checksum data. |
correctly reconstructed on the receiving side by checking a whole\-file | .IP |
checksum that is generated as the file is transferred, but that | Note that rsync always verifies that each \fItransferred\fP file was correctly |
automatic after\-the\-transfer verification has nothing to do with this | reconstructed on the receiving side by checking a whole-file checksum that |
option\(cq\&s before\-the\-transfer \(dq\&Does this file need to be updated?\(dq\& check. | is generated as the file is transferred, but that automatic |
.IP | after-the-transfer verification has nothing to do with this option's |
For protocol 30 and beyond (first supported in 3.0.0), the checksum used is | before-the-transfer "Does this file need to be updated?" check. |
MD5. For older protocols, the checksum used is MD4. | .IP |
.IP | The checksum used is auto-negotiated between the client and the server, but |
.IP "\fB\-a, \-\-archive\fP" | can be overridden using either the \fB\-\-checksum-choice\fP (\fB\-\-cc\fP) option or an |
This is equivalent to \fB\-rlptgoD\fP. It is a quick | environment variable that is discussed in that option's section. |
way of saying you want recursion and want to preserve almost | .IP "\fB\-\-sumfiles=MODE\fP" |
everything (with \-H being a notable omission). | This option tells rsync to make use of any cached checksum information it |
The only exception to the above equivalence is when \fB\-\-files\-from\fP is | finds in per-directory .rsyncsums files when the current transfer is using |
specified, in which case \fB\-r\fP is not implied. | the \fB\-\-checksum\fP option. If the checksum data is up-to-date, it is used |
.IP | instead of recomputing it, saving both disk I/O and CPU time. If the |
Note that \fB\-a\fP \fBdoes not preserve hardlinks\fP, because | checksum data is missing or outdated, the checksum is computed just as it |
finding multiply\-linked files is expensive. You must separately | would be if \fB\-\-sumfiles\fP was not specified. |
specify \fB\-H\fP. | .IP |
.IP | The MODE value is either "lax", for relaxed checking (which compares size |
.IP "\-\-no\-OPTION" | and mtime), "strict" (which also compares ctime and inode), or "none" to |
You may turn off one or more implied options by prefixing | ignore any .rsyncsums files ("none" is the default). |
the option name with \(dq\&no\-\(dq\&. Not all options may be prefixed with a \(dq\&no\-\(dq\&: | If you want rsync to create and/or update these files, specify a prefixed |
only options that are implied by other options (e.g. \fB\-\-no\-D\fP, | plus ("+lax" or "+strict"). Adding a second prefixed '+' causes the |
\fB\-\-no\-perms\fP) or have different defaults in various circumstances | checksum-file updates to happen even when the transfer is in \fB\-\-dry-run\fP |
(e.g. \fB\-\-no\-whole\-file\fP, \fB\-\-no\-blocking\-io\fP, \fB\-\-no\-dirs\fP). You may | mode ("++lax" or "++strict"). There is also a perl script in the support |
specify either the short or the long option name after the \(dq\&no\-\(dq\& prefix | directory named "rsyncsums" that can be used to update the .rsyncsums |
(e.g. \fB\-\-no\-R\fP is the same as \fB\-\-no\-relative\fP). | files. |
.IP | .IP |
For example: if you want to use \fB\-a\fP (\fB\-\-archive\fP) but don\(cq\&t want | This option has no effect unless \fB\-\-checksum\fP, \fB\-c\fP was also specified. It |
\fB\-o\fP (\fB\-\-owner\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you | also only affects the current side of the transfer, so if you want the |
could specify \fB\-a \-\-no\-o\fP (or \fB\-a \-\-no\-owner\fP). | remote side to parse its own .rsyncsums files, specify the option via |
.IP | \fB\-\-remote-option\fP (\fB\-M\fP) (e.g. "\fB\-M\-\-sumfiles=lax\fP"). |
The order of the options is important: if you specify \fB\-\-no\-r \-a\fP, the | .IP |
\fB\-r\fP option would end up being turned on, the opposite of \fB\-a \-\-no\-r\fP. | To avoid transferring the system's checksum files, you can use an exclude |
Note also that the side\-effects of the \fB\-\-files\-from\fP option are NOT | (e.g. \fB\-\-exclude=.rsyncsums\fP). To make this easier to type, you can use a |
| popt alias. For instance, adding the following line in your ~/.popt file |
| defines a \fB\-\-cs\fP option that enables lax checksum files and excludes the |
| checksum files: |
| .RS 4 |
| .IP |
| .nf |
| rsync alias --cs -c --sumfiles=lax -M--sumfiles=lax -f-_.rsyncsums |
| .fi |
| .RE |
| .IP |
| An rsync daemon does not allow the client to control this setting, so see |
| the "checksum files" daemon parameter for information on how to make a |
| daemon use cached checksum data. |
| .IP "\fB\-\-archive\fP, \fB\-a\fP" |
| This is equivalent to \fB\-rlptgoD\fP. It is a quick way of saying you want |
| recursion and want to preserve almost everything (with \fB\-H\fP being a notable |
| omission). The only exception to the above equivalence is when |
| \fB\-\-files-from\fP is specified, in which case \fB\-r\fP is not implied. |
| .IP |
| Note that \fB\-a\fP \fBdoes not preserve hardlinks\fP, because finding |
| multiply-linked files is expensive. You must separately specify \fB\-H\fP. |
| Note also that for backward compatibility, \fB\-a\fP currently does \fBnot\fP |
| imply the \fB\-\-fileflags\fP option. |
| .IP "\fB\-\-no-OPTION\fP" |
| You may turn off one or more implied options by prefixing the option name |
| with "no-". Not all options may be prefixed with a "no-": only options that |
| are implied by other options (e.g. \fB\-\-no-D\fP, \fB\-\-no-perms\fP) or have |
| different defaults in various circumstances (e.g. \fB\-\-no-whole-file\fP, |
| \fB\-\-no-blocking-io\fP, \fB\-\-no-dirs\fP). You may specify either the short or the |
| long option name after the "no-" prefix (e.g. \fB\-\-no-R\fP is the same as |
| \fB\-\-no-relative\fP). |
| .IP |
| For example: if you want to use \fB\-a\fP (\fB\-\-archive\fP) but don't want \fB\-o\fP |
| (\fB\-\-owner\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you could specify |
| \fB\-a\ \-\-no-o\fP (or \fB\-a\ \-\-no-owner\fP). |
| .IP |
| The order of the options is important: if you specify \fB\-\-no-r\ \-a\fP, the |
| \fB\-r\fP option would end up being turned on, the opposite of \fB\-a\ \-\-no-r\fP. |
| Note also that the side-effects of the \fB\-\-files-from\fP option are NOT |
positional, as it affects the default state of several options and slightly |
positional, as it affects the default state of several options and slightly |
changes the meaning of \fB\-a\fP (see the \fB\-\-files\-from\fP option for more | changes the meaning of \fB\-a\fP (see the \fB\-\-files-from\fP option for more |
details). |
details). |
.IP | .IP "\fB\-\-recursive\fP, \fB\-r\fP" |
.IP "\fB\-r, \-\-recursive\fP" | This tells rsync to copy directories recursively. See also \fB\-\-dirs\fP (\fB\-d\fP). |
This tells rsync to copy directories | .IP |
recursively. See also \fB\-\-dirs\fP (\fB\-d\fP). | |
.IP | |
Beginning with rsync 3.0.0, the recursive algorithm used is now an |
Beginning with rsync 3.0.0, the recursive algorithm used is now an |
incremental scan that uses much less memory than before and begins the |
incremental scan that uses much less memory than before and begins the |
transfer after the scanning of the first few directories have been |
transfer after the scanning of the first few directories have been |
completed. This incremental scan only affects our recursion algorithm, and |
completed. This incremental scan only affects our recursion algorithm, and |
does not change a non\-recursive transfer. It is also only possible when | does not change a non-recursive transfer. It is also only possible when |
both ends of the transfer are at least version 3.0.0. |
both ends of the transfer are at least version 3.0.0. |
.IP | .IP |
Some options require rsync to know the full file list, so these options |
Some options require rsync to know the full file list, so these options |
disable the incremental recursion mode. These include: \fB\-\-delete\-before\fP, | disable the incremental recursion mode. These include: \fB\-\-delete-before\fP, |
\fB\-\-delete\-after\fP, \fB\-\-prune\-empty\-dirs\fP, and \fB\-\-delay\-updates\fP. | \fB\-\-delete-after\fP, \fB\-\-prune-empty-dirs\fP, and \fB\-\-delay-updates\fP. Because of |
Because of this, the default delete mode when you specify \fB\-\-delete\fP is now | this, the default delete mode when you specify \fB\-\-delete\fP is now |
\fB\-\-delete\-during\fP when both ends of the connection are at least 3.0.0 | \fB\-\-delete-during\fP when both ends of the connection are at least 3.0.0 (use |
(use \fB\-\-del\fP or \fB\-\-delete\-during\fP to request this improved deletion mode | \fB\-\-del\fP or \fB\-\-delete-during\fP to request this improved deletion mode |
explicitly). See also the \fB\-\-delete\-delay\fP option that is a better choice | explicitly). See also the \fB\-\-delete-delay\fP option that is a better choice |
than using \fB\-\-delete\-after\fP. | than using \fB\-\-delete-after\fP. |
.IP | .IP |
Incremental recursion can be disabled using the \fB\-\-no\-inc\-recursive\fP | Incremental recursion can be disabled using the \fB\-\-no-inc-recursive\fP option |
option or its shorter \fB\-\-no\-i\-r\fP alias. | or its shorter \fB\-\-no-i-r\fP alias. |
.IP | .IP "\fB\-\-relative\fP, \fB\-R\fP" |
.IP "\fB\-R, \-\-relative\fP" | Use relative paths. This means that the full path names specified on the |
Use relative paths. This means that the full path | command line are sent to the server rather than just the last parts of the |
names specified on the command line are sent to the server rather than | filenames. This is particularly useful when you want to send several |
just the last parts of the filenames. This is particularly useful when | different directories at the same time. For example, if you used this |
you want to send several different directories at the same time. For | command: |
example, if you used this command: | .RS 4 |
.IP | .IP |
.RS | .nf |
\f(CW rsync \-av /foo/bar/baz.c remote:/tmp/\fP | rsync -av /foo/bar/baz.c remote:/tmp/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | would create a file named baz.c in /tmp/ on the remote machine. If instead |
\&... this would create a file named baz.c in /tmp/ on the remote | you used |
machine. If instead you used | .RS 4 |
.IP | .IP |
.RS | .nf |
\f(CW rsync \-avR /foo/bar/baz.c remote:/tmp/\fP | rsync -avR /foo/bar/baz.c remote:/tmp/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | |
then a file named /tmp/foo/bar/baz.c would be created on the remote |
then a file named /tmp/foo/bar/baz.c would be created on the remote |
machine, preserving its full path. These extra path elements are called |
machine, preserving its full path. These extra path elements are called |
\(dq\&implied directories\(dq\& (i.e. the \(dq\&foo\(dq\& and the \(dq\&foo/bar\(dq\& directories in the | "implied directories" (i.e. the "foo" and the "foo/bar" directories in the |
above example). |
above example). |
.IP | .IP |
Beginning with rsync 3.0.0, rsync always sends these implied directories as |
Beginning with rsync 3.0.0, rsync always sends these implied directories as |
real directories in the file list, even if a path element is really a |
real directories in the file list, even if a path element is really a |
symlink on the sending side. This prevents some really unexpected | symlink on the sending side. This prevents some really unexpected behaviors |
behaviors when copying the full path of a file that you didn\(cq\&t realize had | when copying the full path of a file that you didn't realize had a symlink |
a symlink in its path. If you want to duplicate a server\-side symlink, | in its path. If you want to duplicate a server-side symlink, include both |
include both the symlink via its path, and referent directory via its real | the symlink via its path, and referent directory via its real path. If |
path. If you\(cq\&re dealing with an older rsync on the sending side, you may | you're dealing with an older rsync on the sending side, you may need to use |
need to use the \fB\-\-no\-implied\-dirs\fP option. | the \fB\-\-no-implied-dirs\fP option. |
.IP | .IP |
It is also possible to limit the amount of path information that is sent as |
It is also possible to limit the amount of path information that is sent as |
implied directories for each path you specify. With a modern rsync on the |
implied directories for each path you specify. With a modern rsync on the |
sending side (beginning with 2.6.7), you can insert a dot and a slash into |
sending side (beginning with 2.6.7), you can insert a dot and a slash into |
the source path, like this: |
the source path, like this: |
.IP | .RS 4 |
.RS | .IP |
\f(CW rsync \-avR /foo/./bar/baz.c remote:/tmp/\fP | .nf |
| rsync -avR /foo/./bar/baz.c remote:/tmp/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | That would create /tmp/bar/baz.c on the remote machine. (Note that the dot |
That would create /tmp/bar/baz.c on the remote machine. (Note that the | must be followed by a slash, so "/foo/." would not be abbreviated.) For |
dot must be followed by a slash, so \(dq\&/foo/.\(dq\& would not be abbreviated.) | older rsync versions, you would need to use a chdir to limit the source |
For older rsync versions, you would need to use a chdir to limit the | path. For example, when pushing files: |
source path. For example, when pushing files: | .RS 4 |
.IP | .IP |
.RS | .nf |
\f(CW (cd /foo; rsync \-avR bar/baz.c remote:/tmp/) \fP | (cd /foo; rsync -avR bar/baz.c remote:/tmp/) |
| .fi |
.RE |
.RE |
| .IP |
.IP | (Note that the parens put the two commands into a sub-shell, so that the |
(Note that the parens put the two commands into a sub\-shell, so that the | "cd" command doesn't remain in effect for future commands.) If you're |
\(dq\&cd\(dq\& command doesn\(cq\&t remain in effect for future commands.) | pulling files from an older rsync, use this idiom (but only for a |
If you\(cq\&re pulling files from an older rsync, use this idiom (but only | non-daemon transfer): |
for a non\-daemon transfer): | .RS 4 |
.IP | .IP |
.RS | .nf |
\f(CW rsync \-avR \-\-rsync\-path=\(dq\&cd /foo; rsync\(dq\& \e \fP | rsync -avR --rsync-path="cd /foo; rsync" \\ |
.br | remote:bar/baz.c /tmp/ |
\f(CW remote:bar/baz.c /tmp/\fP | .fi |
.RE |
.RE |
| .IP "\fB\-\-no-implied-dirs\fP" |
.IP | This option affects the default behavior of the \fB\-\-relative\fP option. When |
.IP "\fB\-\-no\-implied\-dirs\fP" | it is specified, the attributes of the implied directories from the source |
This option affects the default behavior of the | names are not included in the transfer. This means that the corresponding |
\fB\-\-relative\fP option. When it is specified, the attributes of the implied | path elements on the destination system are left unchanged if they exist, |
directories from the source names are not included in the transfer. This | and any missing implied directories are created with default attributes. |
means that the corresponding path elements on the destination system are | This even allows these implied path elements to have big differences, such |
left unchanged if they exist, and any missing implied directories are | as being a symlink to a directory on the receiving side. |
created with default attributes. This even allows these implied path | .IP |
elements to have big differences, such as being a symlink to a directory on | For instance, if a command-line arg or a files-from entry told rsync to |
the receiving side. | transfer the file "path/foo/file", the directories "path" and "path/foo" |
.IP | are implied when \fB\-\-relative\fP is used. If "path/foo" is a symlink to "bar" |
For instance, if a command\-line arg or a files\-from entry told rsync to | on the destination system, the receiving rsync would ordinarily delete |
transfer the file \(dq\&path/foo/file\(dq\&, the directories \(dq\&path\(dq\& and \(dq\&path/foo\(dq\& | "path/foo", recreate it as a directory, and receive the file into the new |
are implied when \fB\-\-relative\fP is used. If \(dq\&path/foo\(dq\& is a symlink to | directory. With \fB\-\-no-implied-dirs\fP, the receiving rsync updates |
\(dq\&bar\(dq\& on the destination system, the receiving rsync would ordinarily | "path/foo/file" using the existing path elements, which means that the file |
delete \(dq\&path/foo\(dq\&, recreate it as a directory, and receive the file into | ends up being created in "path/bar". Another way to accomplish this link |
the new directory. With \fB\-\-no\-implied\-dirs\fP, the receiving rsync updates | preservation is to use the \fB\-\-keep-dirlinks\fP option (which will also affect |
\(dq\&path/foo/file\(dq\& using the existing path elements, which means that the file | symlinks to directories in the rest of the transfer). |
ends up being created in \(dq\&path/bar\(dq\&. Another way to accomplish this link | .IP |
preservation is to use the \fB\-\-keep\-dirlinks\fP option (which will also | |
affect symlinks to directories in the rest of the transfer). | |
.IP | |
When pulling files from an rsync older than 3.0.0, you may need to use this |
When pulling files from an rsync older than 3.0.0, you may need to use this |
option if the sending side has a symlink in the path you request and you |
option if the sending side has a symlink in the path you request and you |
wish the implied directories to be transferred as normal directories. |
wish the implied directories to be transferred as normal directories. |
.IP | .IP "\fB\-\-backup\fP, \fB\-b\fP" |
.IP "\fB\-b, \-\-backup\fP" | With this option, preexisting destination files are renamed as each file is |
With this option, preexisting destination files are | transferred or deleted. You can control where the backup file goes and |
renamed as each file is transferred or deleted. You can control where the | what (if any) suffix gets appended using the \fB\-\-backup-dir\fP and \fB\-\-suffix\fP |
backup file goes and what (if any) suffix gets appended using the | options. |
\fB\-\-backup\-dir\fP and \fB\-\-suffix\fP options. | .IP |
.IP | Note that if you don't specify \fB\-\-backup-dir\fP, (1) the \fB\-\-omit-dir-times\fP |
Note that if you don\(cq\&t specify \fB\-\-backup\-dir\fP, (1) the | option will be forced on, and (2) if \fB\-\-delete\fP is also in effect (without |
\fB\-\-omit\-dir\-times\fP option will be implied, and (2) if \fB\-\-delete\fP is | \fB\-\-delete-excluded\fP), rsync will add a "protect" filter-rule for the backup |
also in effect (without \fB\-\-delete\-excluded\fP), rsync will add a \(dq\&protect\(dq\& | suffix to the end of all your existing excludes (e.g. \fB\-f\ "P\ *~"\fP). This |
filter\-rule for the backup suffix to the end of all your existing excludes | will prevent previously backed-up files from being deleted. Note that if |
(e.g. \fB\-f \(dq\&P *~\(dq\&\fP). This will prevent previously backed\-up files from being | you are supplying your own filter rules, you may need to manually insert |
deleted. Note that if you are supplying your own filter rules, you may | your own exclude/protect rule somewhere higher up in the list so that it |
need to manually insert your own exclude/protect rule somewhere higher up | has a high enough priority to be effective (e.g., if your rules specify a |
in the list so that it has a high enough priority to be effective (e.g., if | trailing inclusion/exclusion of \fB*\fP, the auto-added rule would never be |
your rules specify a trailing inclusion/exclusion of \(cq\&*\(cq\&, the auto\-added | reached). |
rule would never be reached). | .IP "\-\-backup-deleted" |
.IP | With this option, deleted destination files are renamed, while modified |
.IP "\fB\-\-backup\-dir=DIR\fP" | destination files are not. Otherwise, this option behaves the same as |
In combination with the \fB\-\-backup\fP option, this | \fB\-\-backup\fP, described above. Note that if \fB\-\-backup\fP is also specified, |
tells rsync to store all backups in the specified directory on the receiving | whichever option is specified last takes precedence. |
side. This can be used for incremental backups. You can additionally | .IP "\fB\-\-backup-dir=DIR\fP" |
specify a backup suffix using the \fB\-\-suffix\fP option | This implies the \fB\-\-backup\fP option, and tells rsync to store all |
(otherwise the files backed up in the specified directory | backups in the specified directory on the receiving side. This can be used |
will keep their original filenames). | for incremental backups. You can additionally specify a backup suffix |
.IP | using the \fB\-\-suffix\fP option (otherwise the files backed up in the specified |
| directory will keep their original filenames). |
| .IP |
Note that if you specify a relative path, the backup directory will be |
Note that if you specify a relative path, the backup directory will be |
relative to the destination directory, so you probably want to specify |
relative to the destination directory, so you probably want to specify |
either an absolute path or a path that starts with \(dq\&../\(dq\&. If an rsync | either an absolute path or a path that starts with "../". If an rsync |
daemon is the receiver, the backup dir cannot go outside the module\(cq\&s path | daemon is the receiver, the backup dir cannot go outside the module's path |
hierarchy, so take extra care not to delete it or copy into it. |
hierarchy, so take extra care not to delete it or copy into it. |
.IP |
|
.IP "\fB\-\-suffix=SUFFIX\fP" |
.IP "\fB\-\-suffix=SUFFIX\fP" |
This option allows you to override the default | This option allows you to override the default backup suffix used with the |
backup suffix used with the \fB\-\-backup\fP (\fB\-b\fP) option. The default suffix is a ~ | \fB\-\-backup\fP (\fB\-b\fP) option. The default suffix is a \fB~\fP if no \fB\-\-backup-dir\fP |
if no \-\fB\-backup\-dir\fP was specified, otherwise it is an empty string. | was specified, otherwise it is an empty string. |
.IP | .IP "\fB\-\-update\fP, \fB\-u\fP" |
.IP "\fB\-u, \-\-update\fP" | This forces rsync to skip any files which exist on the destination and have |
This forces rsync to skip any files which exist on | a modified time that is newer than the source file. (If an existing |
the destination and have a modified time that is newer than the source | destination file has a modification time equal to the source file's, it |
file. (If an existing destination file has a modification time equal to the | will be updated if the sizes are different.) |
source file\(cq\&s, it will be updated if the sizes are different.) | .IP |
.IP | Note that this does not affect the copying of dirs, symlinks, or other |
Note that this does not affect the copying of dirs, symlinks, or other special | special files. Also, a difference of file format between the sender and |
files. Also, a difference of file format between the sender and receiver | receiver is always considered to be important enough for an update, no |
is always considered to be important enough for an update, no matter what | matter what date is on the objects. In other words, if the source has a |
date is on the objects. In other words, if the source has a directory | directory where the destination has a file, the transfer would occur |
where the destination has a file, the transfer would occur regardless of | regardless of the timestamps. |
the timestamps. | .IP |
.IP | This option is a transfer rule, not an exclude, so it doesn't affect the |
This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the | data that goes into the file-lists, and thus it doesn't affect deletions. |
data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. | |
It just limits the files that the receiver requests to be transferred. |
It just limits the files that the receiver requests to be transferred. |
.IP |
|
.IP "\fB\-\-inplace\fP" |
.IP "\fB\-\-inplace\fP" |
This option changes how rsync transfers a file when | This option changes how rsync transfers a file when its data needs to be |
its data needs to be updated: instead of the default method of creating | updated: instead of the default method of creating a new copy of the file |
a new copy of the file and moving it into place when it is complete, rsync | and moving it into place when it is complete, rsync instead writes the |
instead writes the updated data directly to the destination file. | updated data directly to the destination file. |
.IP | .IP |
This has several effects: |
This has several effects: |
.IP | .IP |
.RS | .RS |
.IP o | .IP o |
Hard links are not broken. This means the new data will be visible |
Hard links are not broken. This means the new data will be visible |
through other hard links to the destination file. Moreover, attempts to |
through other hard links to the destination file. Moreover, attempts to |
copy differing source files onto a multiply\-linked destination file will | copy differing source files onto a multiply-linked destination file will |
result in a \(dq\&tug of war\(dq\& with the destination data changing back and forth. | result in a "tug of war" with the destination data changing back and |
.IP o | forth. |
In\-use binaries cannot be updated (either the OS will prevent this from | .IP o |
happening, or binaries that attempt to swap\-in their data will misbehave or | In-use binaries cannot be updated (either the OS will prevent this from |
crash). | happening, or binaries that attempt to swap-in their data will misbehave |
.IP o | or crash). |
The file\(cq\&s data will be in an inconsistent state during the transfer | .IP o |
and will be left that way if the transfer is interrupted or if an update | The file's data will be in an inconsistent state during the transfer and |
| will be left that way if the transfer is interrupted or if an update |
fails. |
fails. |
.IP o | .IP o |
A file that rsync cannot write to cannot be updated. While a super user | A file that rsync cannot write to cannot be updated. While a super user |
can update any file, a normal user needs to be granted write permission for | can update any file, a normal user needs to be granted write permission |
the open of the file for writing to be successful. | for the open of the file for writing to be successful. |
.IP o | .IP o |
The efficiency of rsync\(cq\&s delta\-transfer algorithm may be reduced if | The efficiency of rsync's delta-transfer algorithm may be reduced if some |
some data in the destination file is overwritten before it can be copied to | data in the destination file is overwritten before it can be copied to a |
a position later in the file. This does not apply if you use \fB\-\-backup\fP, | position later in the file. This does not apply if you use \fB\-\-backup\fP, |
since rsync is smart enough to use the backup file as the basis file for the | since rsync is smart enough to use the backup file as the basis file for |
transfer. | the transfer. |
.RE |
.RE |
| .IP |
.IP | |
WARNING: you should not use this option to update files that are being |
WARNING: you should not use this option to update files that are being |
accessed by others, so be careful when choosing to use this for a copy. |
accessed by others, so be careful when choosing to use this for a copy. |
.IP | .IP |
This option is useful for transferring large files with block\-based changes | This option is useful for transferring large files with block-based changes |
or appended data, and also on systems that are disk bound, not network |
or appended data, and also on systems that are disk bound, not network |
bound. It can also help keep a copy\-on\-write filesystem snapshot from | bound. It can also help keep a copy-on-write filesystem snapshot from |
diverging the entire contents of a file that only has minor changes. |
diverging the entire contents of a file that only has minor changes. |
.IP | .IP |
The option implies \fB\-\-partial\fP (since an interrupted transfer does not delete | The option implies \fB\-\-partial\fP (since an interrupted transfer does not |
the file), but conflicts with \fB\-\-partial\-dir\fP and \fB\-\-delay\-updates\fP. | delete the file), but conflicts with \fB\-\-partial-dir\fP and \fB\-\-delay-updates\fP. |
Prior to rsync 2.6.4 \fB\-\-inplace\fP was also incompatible with \fB\-\-compare\-dest\fP | Prior to rsync 2.6.4 \fB\-\-inplace\fP was also incompatible with |
and \fB\-\-link\-dest\fP. | \fB\-\-compare-dest\fP and \fB\-\-link-dest\fP. |
.IP | |
.IP "\fB\-\-append\fP" |
.IP "\fB\-\-append\fP" |
This causes rsync to update a file by appending data onto | This special copy mode only works to efficiently update files that are |
the end of the file, which presumes that the data that already exists on | known to be growing larger where any existing content on the receiving side |
the receiving side is identical with the start of the file on the sending | is also known to be the same as the content on the sender. The use of |
side. If a file needs to be transferred and its size on the receiver is | \fB\-\-append\fP \fBcan be dangerous\fP if you aren't 100% sure that all the files |
the same or longer than the size on the sender, the file is skipped. This | in the transfer are shared, growing files. You should thus use filter |
does not interfere with the updating of a file\(cq\&s non\-content attributes | rules to ensure that you weed out any files that do not fit this criteria. |
(e.g. permissions, ownership, etc.) when the file does not need to be | .IP |
transferred, nor does it affect the updating of any non\-regular files. | Rsync updates these growing file in-place without verifying any of the |
Implies \fB\-\-inplace\fP, | existing content in the file (it only verifies the content that it is |
but does not conflict with \fB\-\-sparse\fP (since it is always extending a | appending). Rsync skips any files that exist on the receiving side that |
file\(cq\&s length). | are not shorter than the associated file on the sending side (which means |
.IP | that new files are trasnferred). |
The use of \fB\-\-append\fP can be dangerous if you aren\(cq\&t 100% sure that the files | .IP |
that are longer have only grown by the appending of data onto the end. You | This does not interfere with the updating of a file's non-content |
should thus use include/exclude/filter rules to ensure that such a transfer is | attributes (e.g. permissions, ownership, etc.) when the file does not need |
only affecting files that you know to be growing via appended data. | to be transferred, nor does it affect the updating of any directories or |
.IP | non-regular files. |
.IP "\fB\-\-append\-verify\fP" | .IP "\fB\-\-append-verify\fP" |
This works just like the \fB\-\-append\fP option, but | This special copy mode works like \fB\-\-append\fP except that all the data in |
the existing data on the receiving side is included in the full\-file | the file is included in the checksum verification (making it much less |
checksum verification step, which will cause a file to be resent if the | efficient but also potentially safer). This option \fBcan be dangerous\fP if |
final verification step fails (rsync uses a normal, non\-appending | you aren't 100% sure that all the files in the transfer are shared, growing |
\fB\-\-inplace\fP transfer for the resend). | files. See the \fB\-\-append\fP option for more details. |
.IP | .IP |
Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like |
Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like |
\fB\-\-append\-verify\fP, so if you are interacting with an older rsync (or the | \fB\-\-append-verify\fP, so if you are interacting with an older rsync (or the |
transfer is using a protocol prior to 30), specifying either append option |
transfer is using a protocol prior to 30), specifying either append option |
will initiate an \fB\-\-append\-verify\fP transfer. | will initiate an \fB\-\-append-verify\fP transfer. |
.IP | .IP "\fB\-\-dirs\fP, \fB\-d\fP" |
.IP "\fB\-d, \-\-dirs\fP" | Tell the sending side to include any directories that are encountered. |
Tell the sending side to include any directories that | Unlike \fB\-\-recursive\fP, a directory's contents are not copied unless the |
are encountered. Unlike \fB\-\-recursive\fP, a directory\(cq\&s contents are not copied | directory name specified is "." or ends with a trailing slash (e.g. ".", |
unless the directory name specified is \(dq\&.\(dq\& or ends with a trailing slash | "dir/.", "dir/", etc.). Without this option or the \fB\-\-recursive\fP option, |
(e.g. \(dq\&.\(dq\&, \(dq\&dir/.\(dq\&, \(dq\&dir/\(dq\&, etc.). Without this option or the | rsync will skip all directories it encounters (and output a message to that |
\fB\-\-recursive\fP option, rsync will skip all directories it encounters (and | effect for each one). If you specify both \fB\-\-dirs\fP and \fB\-\-recursive\fP, |
output a message to that effect for each one). If you specify both | \fB\-\-recursive\fP takes precedence. |
\fB\-\-dirs\fP and \fB\-\-recursive\fP, \fB\-\-recursive\fP takes precedence. | .IP |
.IP | The \fB\-\-dirs\fP option is implied by the \fB\-\-files-from\fP option or the |
The \fB\-\-dirs\fP option is implied by the \fB\-\-files\-from\fP option | \fB\-\-list-only\fP option (including an implied \fB\-\-list-only\fP usage) if |
or the \fB\-\-list\-only\fP option (including an implied | \fB\-\-recursive\fP wasn't specified (so that directories are seen in the |
\fB\-\-list\-only\fP usage) if \fB\-\-recursive\fP wasn\(cq\&t specified (so that | listing). Specify \fB\-\-no-dirs\fP (or \fB\-\-no-d\fP) if you want to turn this off. |
directories are seen in the listing). Specify \fB\-\-no\-dirs\fP (or \fB\-\-no\-d\fP) | .IP |
if you want to turn this off. | There is also a backward-compatibility helper option, \fB\-\-old-dirs\fP (or |
.IP | \fB\-\-old-d\fP) that tells rsync to use a hack of \fB\-r\ \-\-exclude='/*/*'\fP to get |
There is also a backward\-compatibility helper option, \fB\-\-old\-dirs\fP (or | |
\fB\-\-old\-d\fP) that tells rsync to use a hack of \(dq\&\-r \-\-exclude=\(cq\&/*/*\(cq\&\(dq\& to get | |
an older rsync to list a single directory without recursing. |
an older rsync to list a single directory without recursing. |
.IP | .IP "\fB\-\-mkpath\fP" |
.IP "\fB\-l, \-\-links\fP" | Create a missing path component of the destination arg. This allows rsync |
When symlinks are encountered, recreate the | to create multiple levels of missing destination dirs and to create a path |
symlink on the destination. | in which to put a single renamed file. Keep in mind that you'll need to |
.IP | supply a trailing slash if you want the entire destination path to be |
.IP "\fB\-L, \-\-copy\-links\fP" | treated as a directory when copying a single arg (making rsync behave the |
When symlinks are encountered, the item that | same way that it would if the path component of the destination had already |
they point to (the referent) is copied, rather than the symlink. In older | existed). |
versions of rsync, this option also had the side\-effect of telling the | .IP |
receiving side to follow symlinks, such as symlinks to directories. In a | For example, the following creates a copy of file foo as bar in the sub/dir |
modern rsync such as this one, you\(cq\&ll need to specify \fB\-\-keep\-dirlinks\fP (\fB\-K\fP) | directory, creating dirs "sub" and "sub/dir" if either do not yet exist: |
to get this extra behavior. The only exception is when sending files to | .RS 4 |
an rsync that is too old to understand \fB\-K\fP \-\- in that case, the \fB\-L\fP option | .IP |
will still have the side\-effect of \fB\-K\fP on that older receiving rsync. | .nf |
.IP | rsync -ai --mkpath foo sub/dir/bar |
.IP "\fB\-\-copy\-unsafe\-links\fP" | .fi |
This tells rsync to copy the referent of | .RE |
symbolic links that point outside the copied tree. Absolute symlinks | .IP |
are also treated like ordinary files, and so are any symlinks in the | If you instead ran the following, it would have created file foo in the |
source path itself when \fB\-\-relative\fP is used. This option has no | sub/dir/bar directory: |
additional effect if \fB\-\-copy\-links\fP was also specified. | .RS 4 |
.IP | .IP |
.IP "\fB\-\-safe\-links\fP" | .nf |
This tells rsync to ignore any symbolic links | rsync -ai --mkpath foo sub/dir/bar/ |
which point outside the copied tree. All absolute symlinks are | .fi |
also ignored. Using this option in conjunction with \fB\-\-relative\fP may | .RE |
give unexpected results. | .IP "\fB\-\-links\fP, \fB\-l\fP" |
.IP | When symlinks are encountered, recreate the symlink on the destination. |
.IP "\fB\-\-munge\-links\fP" | .IP "\fB\-\-copy-links\fP, \fB\-L\fP" |
This option tells rsync to (1) modify all symlinks on | When symlinks are encountered, the item that they point to (the referent) |
the receiving side in a way that makes them unusable but recoverable (see | is copied, rather than the symlink. In older versions of rsync, this |
below), or (2) to unmunge symlinks on the sending side that had been stored in | option also had the side-effect of telling the receiving side to follow |
a munged state. This is useful if you don\(cq\&t quite trust the source of the data | symlinks, such as symlinks to directories. In a modern rsync such as this |
to not try to slip in a symlink to a unexpected place. | one, you'll need to specify \fB\-\-keep-dirlinks\fP (\fB\-K\fP) to get this extra |
.IP | behavior. The only exception is when sending files to an rsync that is too |
| old to understand \fB\-K\fP\ \-\- in that case, the \fB\-L\fP option will still have the |
| side-effect of \fB\-K\fP on that older receiving rsync. |
| .IP "\fB\-\-copy-unsafe-links\fP" |
| This tells rsync to copy the referent of symbolic links that point outside |
| the copied tree. Absolute symlinks are also treated like ordinary files, |
| and so are any symlinks in the source path itself when \fB\-\-relative\fP is |
| used. This option has no additional effect if \fB\-\-copy-links\fP was also |
| specified. |
| .IP |
| Note that the cut-off point is the top of the transfer, which is the part |
| of the path that rsync isn't mentioning in the verbose output. If you copy |
| "/src/subdir" to "/dest/" then the "subdir" directory is a name inside the |
| transfer tree, not the top of the transfer (which is /src) so it is legal |
| for created relative symlinks to refer to other names inside the /src and |
| /dest directories. If you instead copy "/src/subdir/" (with a trailing |
| slash) to "/dest/subdir" that would not allow symlinks to any files outside |
| of "subdir". |
| .IP "\fB\-\-safe-links\fP" |
| This tells rsync to ignore any symbolic links which point outside the |
| copied tree. All absolute symlinks are also ignored. Using this option in |
| conjunction with \fB\-\-relative\fP may give unexpected results. |
| .IP "\fB\-\-munge-links\fP" |
| This option tells rsync to (1) modify all symlinks on the receiving side in |
| a way that makes them unusable but recoverable (see below), or (2) to |
| unmunge symlinks on the sending side that had been stored in a munged |
| state. This is useful if you don't quite trust the source of the data to |
| not try to slip in a symlink to a unexpected place. |
| .IP |
The way rsync disables the use of symlinks is to prefix each one with the |
The way rsync disables the use of symlinks is to prefix each one with the |
string \(dq\&/rsyncd\-munged/\(dq\&. This prevents the links from being used as long as | string "/rsyncd-munged/". This prevents the links from being used as long |
that directory does not exist. When this option is enabled, rsync will refuse | as that directory does not exist. When this option is enabled, rsync will |
to run if that path is a directory or a symlink to a directory. | refuse to run if that path is a directory or a symlink to a directory. |
.IP | .IP |
The option only affects the client side of the transfer, so if you need it to | The option only affects the client side of the transfer, so if you need it |
affect the server, specify it via \fB\-\-remote\-option\fP. (Note that in a local | to affect the server, specify it via \fB\-\-remote-option\fP. (Note that in a |
transfer, the client side is the sender.) | local transfer, the client side is the sender.) |
.IP | .IP |
This option has no affect on a daemon, since the daemon configures whether it | This option has no affect on a daemon, since the daemon configures whether |
wants munged symlinks via its \(dq\&munge symlinks\(dq\& parameter. See also the | it wants munged symlinks via its "\fBmunge\ symlinks\fP" parameter. See also the |
\(dq\&munge\-symlinks\(dq\& perl script in the support directory of the source code. | "munge-symlinks" perl script in the support directory of the source code. |
.IP | .IP "\fB\-\-copy-dirlinks\fP, \fB\-k\fP" |
.IP "\fB\-k, \-\-copy\-dirlinks\fP" | This option causes the sending side to treat a symlink to a directory as |
This option causes the sending side to treat | though it were a real directory. This is useful if you don't want symlinks |
a symlink to a directory as though it were a real directory. This is | to non-directories to be affected, as they would be using \fB\-\-copy-links\fP. |
useful if you don\(cq\&t want symlinks to non\-directories to be affected, as | .IP |
they would be using \fB\-\-copy\-links\fP. | |
.IP | |
Without this option, if the sending side has replaced a directory with a |
Without this option, if the sending side has replaced a directory with a |
symlink to a directory, the receiving side will delete anything that is in |
symlink to a directory, the receiving side will delete anything that is in |
the way of the new symlink, including a directory hierarchy (as long as |
the way of the new symlink, including a directory hierarchy (as long as |
\fB\-\-force\fP or \fB\-\-delete\fP is in effect). | \fB\-\-force-delete\fP or \fB\-\-delete\fP is in effect). |
.IP | .IP |
See also \fB\-\-keep\-dirlinks\fP for an analogous option for the receiving | See also \fB\-\-keep-dirlinks\fP for an analogous option for the receiving side. |
side. | .IP |
.IP | \fB\-\-copy-dirlinks\fP applies to all symlinks to directories in the source. If |
\fB\-\-copy\-dirlinks\fP applies to all symlinks to directories in the source. If | |
you want to follow only a few specified symlinks, a trick you can use is to |
you want to follow only a few specified symlinks, a trick you can use is to |
pass them as additional source args with a trailing slash, using \fB\-\-relative\fP | pass them as additional source args with a trailing slash, using |
to make the paths match up right. For example: | \fB\-\-relative\fP to make the paths match up right. For example: |
.IP | .RS 4 |
.RS | .IP |
\f(CWrsync \-r \-\-relative src/./ src/./follow\-me/ dest/\fP | .nf |
| rsync -r --relative src/./ src/./follow-me/ dest/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | This works because rsync calls \fBlstat\fP(2) on the source arg as given, and |
This works because rsync calls \fBlstat\fP(2) on the source arg as given, and the | the trailing slash makes \fBlstat\fP(2) follow the symlink, giving rise to a |
trailing slash makes \fBlstat\fP(2) follow the symlink, giving rise to a directory | directory in the file-list which overrides the symlink found during the |
in the file\-list which overrides the symlink found during the scan of \(dq\&src/./\(dq\&. | scan of "src/./". |
.IP | .IP "\fB\-\-keep-dirlinks\fP, \fB\-K\fP" |
.IP "\fB\-K, \-\-keep\-dirlinks\fP" | This option causes the receiving side to treat a symlink to a directory as |
This option causes the receiving side to treat | though it were a real directory, but only if it matches a real directory |
a symlink to a directory as though it were a real directory, but only if it | from the sender. Without this option, the receiver's symlink would be |
matches a real directory from the sender. Without this option, the | deleted and replaced with a real directory. |
receiver\(cq\&s symlink would be deleted and replaced with a real directory. | .IP |
.IP | For example, suppose you transfer a directory "foo" that contains a file |
For example, suppose you transfer a directory \(dq\&foo\(dq\& that contains a file | "file", but "foo" is a symlink to directory "bar" on the receiver. Without |
\(dq\&file\(dq\&, but \(dq\&foo\(dq\& is a symlink to directory \(dq\&bar\(dq\& on the receiver. Without | \fB\-\-keep-dirlinks\fP, the receiver deletes symlink "foo", recreates it as a |
\fB\-\-keep\-dirlinks\fP, the receiver deletes symlink \(dq\&foo\(dq\&, recreates it as a | |
directory, and receives the file into the new directory. With |
directory, and receives the file into the new directory. With |
\fB\-\-keep\-dirlinks\fP, the receiver keeps the symlink and \(dq\&file\(dq\& ends up in | \fB\-\-keep-dirlinks\fP, the receiver keeps the symlink and "file" ends up in |
\(dq\&bar\(dq\&. | "bar". |
.IP | .IP |
One note of caution: if you use \fB\-\-keep\-dirlinks\fP, you must trust all | One note of caution: if you use \fB\-\-keep-dirlinks\fP, you must trust all the |
the symlinks in the copy! If it is possible for an untrusted user to | symlinks in the copy! If it is possible for an untrusted user to create |
create their own symlink to any directory, the user could then (on a | their own symlink to any directory, the user could then (on a subsequent |
subsequent copy) replace the symlink with a real directory and affect the | copy) replace the symlink with a real directory and affect the content of |
content of whatever directory the symlink references. For backup copies, | whatever directory the symlink references. For backup copies, you are |
you are better off using something like a bind mount instead of a symlink | better off using something like a bind mount instead of a symlink to modify |
to modify your receiving hierarchy. | your receiving hierarchy. |
.IP | .IP |
See also \fB\-\-copy\-dirlinks\fP for an analogous option for the sending side. | See also \fB\-\-copy-dirlinks\fP for an analogous option for the sending side. |
.IP | .IP "\fB\-\-hard-links\fP, \fB\-H\fP" |
.IP "\fB\-H, \-\-hard\-links\fP" | This tells rsync to look for hard-linked files in the source and link |
This tells rsync to look for hard\-linked files in | together the corresponding files on the destination. Without this option, |
the source and link together the corresponding files on the destination. | hard-linked files in the source are treated as though they were separate |
Without this option, hard\-linked files in the source are treated | files. |
as though they were separate files. | .IP |
.IP | This option does NOT necessarily ensure that the pattern of hard links on |
This option does NOT necessarily ensure that the pattern of hard links on the | the destination exactly matches that on the source. Cases in which the |
destination exactly matches that on the source. Cases in which the | |
destination may end up with extra hard links include the following: |
destination may end up with extra hard links include the following: |
.IP | .IP |
.RS | .RS |
.IP o | .IP o |
If the destination contains extraneous hard\-links (more linking than | If the destination contains extraneous hard-links (more linking than what |
what is present in the source file list), the copying algorithm will not | is present in the source file list), the copying algorithm will not break |
break them explicitly. However, if one or more of the paths have content | them explicitly. However, if one or more of the paths have content |
differences, the normal file\-update process will break those extra links | differences, the normal file-update process will break those extra links |
(unless you are using the \fB\-\-inplace\fP option). |
(unless you are using the \fB\-\-inplace\fP option). |
.IP o | .IP o |
If you specify a \fB\-\-link\-dest\fP directory that contains hard links, | If you specify a \fB\-\-link-dest\fP directory that contains hard links, the |
the linking of the destination files against the \fB\-\-link\-dest\fP files can | linking of the destination files against the \fB\-\-link-dest\fP files can |
cause some paths in the destination to become linked together due to the |
cause some paths in the destination to become linked together due to the |
\fB\-\-link\-dest\fP associations. | \fB\-\-link-dest\fP associations. |
.RE |
.RE |
| .IP |
.IP | |
Note that rsync can only detect hard links between files that are inside |
Note that rsync can only detect hard links between files that are inside |
the transfer set. If rsync updates a file that has extra hard\-link | the transfer set. If rsync updates a file that has extra hard-link |
connections to files outside the transfer, that linkage will be broken. If |
connections to files outside the transfer, that linkage will be broken. If |
you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be |
you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be |
very careful that you know how your files are being updated so that you are |
very careful that you know how your files are being updated so that you are |
certain that no unintended changes happen due to lingering hard links (and |
certain that no unintended changes happen due to lingering hard links (and |
see the \fB\-\-inplace\fP option for more caveats). |
see the \fB\-\-inplace\fP option for more caveats). |
.IP | .IP |
If incremental recursion is active (see \fB\-\-recursive\fP), rsync may transfer |
If incremental recursion is active (see \fB\-\-recursive\fP), rsync may transfer |
a missing hard\-linked file before it finds that another link for that contents | a missing hard-linked file before it finds that another link for that |
exists elsewhere in the hierarchy. This does not affect the accuracy of | contents exists elsewhere in the hierarchy. This does not affect the |
the transfer (i.e. which files are hard\-linked together), just its efficiency | accuracy of the transfer (i.e. which files are hard-linked together), just |
(i.e. copying the data for a new, early copy of a hard\-linked file that could | its efficiency (i.e. copying the data for a new, early copy of a |
have been found later in the transfer in another member of the hard\-linked | hard-linked file that could have been found later in the transfer in |
set of files). One way to avoid this inefficiency is to disable | another member of the hard-linked set of files). One way to avoid this |
incremental recursion using the \fB\-\-no\-inc\-recursive\fP option. | inefficiency is to disable incremental recursion using the |
.IP | \fB\-\-no-inc-recursive\fP option. |
.IP "\fB\-p, \-\-perms\fP" | .IP "\fB\-\-perms\fP, \fB\-p\fP" |
This option causes the receiving rsync to set the | This option causes the receiving rsync to set the destination permissions |
destination permissions to be the same as the source permissions. (See | to be the same as the source permissions. (See also the \fB\-\-chmod\fP option |
also the \fB\-\-chmod\fP option for a way to modify what rsync considers to | for a way to modify what rsync considers to be the source permissions.) |
be the source permissions.) | .IP |
.IP | |
When this option is \fIoff\fP, permissions are set as follows: |
When this option is \fIoff\fP, permissions are set as follows: |
.IP | .IP |
.RS | .RS |
.IP o | .IP o |
Existing files (including updated files) retain their existing |
Existing files (including updated files) retain their existing |
permissions, though the \fB\-\-executability\fP option might change just | permissions, though the \fB\-\-executability\fP option might change just the |
the execute permission for the file. | execute permission for the file. |
.IP o | .IP o |
New files get their \(dq\&normal\(dq\& permission bits set to the source | New files get their "normal" permission bits set to the source file's |
file\(cq\&s permissions masked with the receiving directory\(cq\&s default | permissions masked with the receiving directory's default permissions |
permissions (either the receiving process\(cq\&s umask, or the permissions | (either the receiving process's umask, or the permissions specified via |
specified via the destination directory\(cq\&s default ACL), and | the destination directory's default ACL), and their special permission |
their special permission bits disabled except in the case where a new | bits disabled except in the case where a new directory inherits a setgid |
directory inherits a setgid bit from its parent directory. | bit from its parent directory. |
.RE |
.RE |
| .IP |
.IP | Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled, rsync's |
Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled, | behavior is the same as that of other file-copy utilities, such as \fBcp\fP(1) |
rsync\(cq\&s behavior is the same as that of other file\-copy utilities, | and \fBtar\fP(1). |
such as \fBcp\fP(1) and \fBtar\fP(1). | .IP |
.IP | |
In summary: to give destination files (both old and new) the source |
In summary: to give destination files (both old and new) the source |
permissions, use \fB\-\-perms\fP. To give new files the destination\-default | permissions, use \fB\-\-perms\fP. To give new files the destination-default |
permissions (while leaving existing files unchanged), make sure that the |
permissions (while leaving existing files unchanged), make sure that the |
\fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures that | \fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures that all |
all non\-masked bits get enabled). If you\(cq\&d care to make this latter | non-masked bits get enabled). If you'd care to make this latter behavior |
behavior easier to type, you could define a popt alias for it, such as | easier to type, you could define a popt alias for it, such as putting this |
putting this line in the file ~/.popt (the following defines the \fB\-Z\fP option, | line in the file \fB~/.popt\fP (the following defines the \fB\-Z\fP option, and |
and includes \-\-no\-g to use the default group of the destination dir): | includes \fB\-\-no-g\fP to use the default group of the destination dir): |
.IP | .RS 4 |
.RS | .IP |
\f(CW rsync alias \-Z \-\-no\-p \-\-no\-g \-\-chmod=ugo=rwX\fP | .nf |
| rsync alias -Z --no-p --no-g --chmod=ugo=rwX |
| .fi |
.RE |
.RE |
| .IP |
.IP | |
You could then use this new option in a command such as this one: |
You could then use this new option in a command such as this one: |
.IP | .RS 4 |
.RS | .IP |
\f(CW rsync \-avZ src/ dest/\fP | .nf |
| rsync -avZ src/ dest/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | (Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re-enable the |
(Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re\-enable | two \fB\-\-no-*\fP options mentioned above.) |
the two \(dq\&\-\-no\-*\(dq\& options mentioned above.) | .IP |
.IP | The preservation of the destination's setgid bit on newly-created |
The preservation of the destination\(cq\&s setgid bit on newly\-created | |
directories when \fB\-\-perms\fP is off was added in rsync 2.6.7. Older rsync |
directories when \fB\-\-perms\fP is off was added in rsync 2.6.7. Older rsync |
versions erroneously preserved the three special permission bits for |
versions erroneously preserved the three special permission bits for |
newly\-created files when \fB\-\-perms\fP was off, while overriding the | newly-created files when \fB\-\-perms\fP was off, while overriding the |
destination\(cq\&s setgid bit setting on a newly\-created directory. Default ACL | destination's setgid bit setting on a newly-created directory. Default ACL |
observance was added to the ACL patch for rsync 2.6.7, so older (or |
observance was added to the ACL patch for rsync 2.6.7, so older (or |
non\-ACL\-enabled) rsyncs use the umask even if default ACLs are present. | non-ACL-enabled) rsyncs use the umask even if default ACLs are present. |
(Keep in mind that it is the version of the receiving rsync that affects |
(Keep in mind that it is the version of the receiving rsync that affects |
these behaviors.) |
these behaviors.) |
.IP | .IP "\fB\-\-executability\fP, \fB\-E\fP" |
.IP "\fB\-E, \-\-executability\fP" | This option causes rsync to preserve the executability (or |
This option causes rsync to preserve the | non-executability) of regular files when \fB\-\-perms\fP is not enabled. A |
executability (or non\-executability) of regular files when \fB\-\-perms\fP is | regular file is considered to be executable if at least one 'x' is turned |
not enabled. A regular file is considered to be executable if at least one | on in its permissions. When an existing destination file's executability |
\(cq\&x\(cq\& is turned on in its permissions. When an existing destination file\(cq\&s | differs from that of the corresponding source file, rsync modifies the |
executability differs from that of the corresponding source file, rsync | destination file's permissions as follows: |
modifies the destination file\(cq\&s permissions as follows: | .IP |
.IP | .RS |
.RS | .IP o |
.IP o | To make a file non-executable, rsync turns off all its 'x' permissions. |
To make a file non\-executable, rsync turns off all its \(cq\&x\(cq\& | .IP o |
permissions. | To make a file executable, rsync turns on each 'x' permission that has a |
.IP o | corresponding 'r' permission enabled. |
To make a file executable, rsync turns on each \(cq\&x\(cq\& permission that | |
has a corresponding \(cq\&r\(cq\& permission enabled. | |
.RE |
.RE |
| .IP |
.IP | |
If \fB\-\-perms\fP is enabled, this option is ignored. |
If \fB\-\-perms\fP is enabled, this option is ignored. |
.IP | .IP "\fB\-\-acls\fP, \fB\-A\fP" |
.IP "\fB\-A, \-\-acls\fP" | This option causes rsync to update the destination ACLs to be the same as |
This option causes rsync to update the destination | the source ACLs. The option also implies \fB\-\-perms\fP. |
ACLs to be the same as the source ACLs. | .IP |
The option also implies \fB\-\-perms\fP. | The source and destination systems must have compatible ACL entries for |
.IP | this option to work properly. See the \fB\-\-fake-super\fP option for a way to |
The source and destination systems must have compatible ACL entries for this | backup and restore ACLs that are not compatible. |
option to work properly. See the \fB\-\-fake\-super\fP option for a way to backup | .IP "\fB\-\-xattrs\fP, \fB\-X\fP" |
and restore ACLs that are not compatible. | This option causes rsync to update the destination extended attributes to |
.IP | be the same as the source ones. |
.IP "\fB\-X, \-\-xattrs\fP" | .IP |
This option causes rsync to update the destination | For systems that support extended-attribute namespaces, a copy being done |
extended attributes to be the same as the source ones. | by a super-user copies all namespaces except system.*. A normal user only |
.IP | copies the user.* namespace. To be able to backup and restore non-user |
For systems that support extended\-attribute namespaces, a copy being done by a | namespaces as a normal user, see the \fB\-\-fake-super\fP option. |
super\-user copies all namespaces except system.*. A normal user only copies | .IP |
the user.* namespace. To be able to backup and restore non\-user namespaces as | The above name filtering can be overridden by using one or more filter |
a normal user, see the \fB\-\-fake\-super\fP option. | options with the \fBx\fP modifier. When you specify an xattr-affecting |
.IP | filter rule, rsync requires that you do your own system/user filtering, as |
Note that this option does not copy rsyncs special xattr values (e.g. those | well as any additional filtering for what xattr names are copied and what |
used by \fB\-\-fake\-super\fP) unless you repeat the option (e.g. \-XX). This | names are allowed to be deleted. For example, to skip the system |
\(dq\© all xattrs\(dq\& mode cannot be used with \fB\-\-fake\-super\fP. | namespace, you could specify: |
.IP | .RS 4 |
.IP "\fB\-\-chmod\fP" | .IP |
This option tells rsync to apply one or more | .nf |
comma\-separated \(dq\&chmod\(dq\& modes to the permission of the files in the | --filter='-x system.*' |
transfer. The resulting value is treated as though it were the permissions | .fi |
that the sending side supplied for the file, which means that this option | .RE |
can seem to have no effect on existing files if \fB\-\-perms\fP is not enabled. | .IP |
.IP | To skip all namespaces except the user namespace, you could specify a |
| negated-user match: |
| .RS 4 |
| .IP |
| .nf |
| --filter='-x! user.*' |
| .fi |
| .RE |
| .IP |
| To prevent any attributes from being deleted, you could specify a |
| receiver-only rule that excludes all names: |
| .RS 4 |
| .IP |
| .nf |
| --filter='-xr *' |
| .fi |
| .RE |
| .IP |
| Note that the \fB\-X\fP option does not copy rsync's special xattr values (e.g. |
| those used by \fB\-\-fake-super\fP) unless you repeat the option (e.g. \fB\-XX\fP). |
| This "copy all xattrs" mode cannot be used with \fB\-\-fake-super\fP. |
| .IP "\fB\-\-fileflags\fP This option causes rsync to update the file-flags to be the |
| same as the source files and directories (if your OS supports the |
| \fBchflags\fP(2) system call). Some flags can only be altered by the |
| super-user and some might only be unset below a certain secure-level |
| (usually single-user mode). It will not make files alterable that are set |
| to immutable on the receiver. To do that, see \fB\-\-force-change\fP, |
| \fB\-\-force-uchange\fP, and \fB\-\-force-schange\fP." |
| .IP "\fB\-\-force-change\fP This option causes rsync to disable both user-immutable |
| and system-immutable flags on files and directories that are being updated |
| or deleted on the receiving side. This option overrides \fB\-\-force-uchange\fP |
| and \fB\-\-force-schange\fP." |
| .IP "\fB\-\-force-uchange\fP This option causes rsync to disable user-immutable flags |
| on files and directories that are being updated or deleted on the receiving |
| side. It does not try to affect system flags. This option overrides |
| \fB\-\-force-change\fP and \fB\-\-force-schange\fP." |
| .IP "\fB\-\-force-schange\fP This option causes rsync to disable system-immutable |
| flags on files and directories that are being updated or deleted on the |
| receiving side. It does not try to affect user flags. This option |
| overrides \fB\-\-force-change\fP and \fB\-\-force-uchange\fP." |
| .IP "\fB\-\-hfs-compression\fP" |
| This option causes rsync to preserve HFS+ compression if the destination |
| filesystem supports it. If the destination does not support it, rsync will |
| exit with an error. |
| .IP |
| Filesystem compression was introduced to HFS+ in Mac OS 10.6. A file that |
| is compressed has no data in its data fork. Rather, the compressed data is |
| stored in an extended attribute named com.apple.decmpfs and a file flag is |
| set to indicate that the file is compressed (UF_COMPRESSED). HFS+ |
| decompresses this data "on-the-fly" and presents it to the operating system |
| as a normal file. Normal attempts to copy compressed files (e.g. in the |
| Finder, via cp, ditto, etc.) will copy the file's decompressed contents, |
| remove the UF_COMPRESSED file flag, and discard the com.apple.decmpfs |
| extended attribute. This option will preserve the data in the |
| com.apple.decmpfs extended attribute and ignore the synthesized data in the |
| file contents. |
| .IP |
| This option implies both \fB\-\-fileflags\fP and (\-\-xattrs). |
| .IP "\fB\-\-protect-decmpfs\fP" |
| The com.apple.decmpfs extended attribute is hidden by default from list/get |
| xattr calls, therefore normal attempts to copy compressed files will |
| functionally decompress those files. While this is desirable behavior when |
| copying files to filesystems that do not support HFS+ compression, it has |
| serious performance and capacity impacts when backing up or restoring the |
| Mac OS X filesystem. |
| .IP |
| This option will transfer the com.apple.decmpfs extended attribute |
| regardless of support on the destination. If a source file is compressed |
| and an existing file on the destination is not compressed, the data fork of |
| the destination file will be truncated and the com.apple.decmpfs xattr will |
| be transferred instead. Note that compressed files will not be readable to |
| the operating system of the destination if that operating system does not |
| support HFS+ compression. Once restored (with or without this option) to an |
| operating system that supports HFS+ compression, however, these files will |
| be accessible as usual. |
| .IP |
| This option implies \fB\-\-fileflags\fP and \fB\-\-xattrs\fP. |
| .IP "\fB\-\-chmod=CHMOD\fP" |
| This option tells rsync to apply one or more comma-separated "chmod" modes |
| to the permission of the files in the transfer. The resulting value is |
| treated as though it were the permissions that the sending side supplied |
| for the file, which means that this option can seem to have no effect on |
| existing files if \fB\-\-perms\fP is not enabled. |
| .IP |
In addition to the normal parsing rules specified in the \fBchmod\fP(1) |
In addition to the normal parsing rules specified in the \fBchmod\fP(1) |
manpage, you can specify an item that should only apply to a directory by |
manpage, you can specify an item that should only apply to a directory by |
prefixing it with a \(cq\&D\(cq\&, or specify an item that should only apply to a | prefixing it with a 'D', or specify an item that should only apply to a |
file by prefixing it with a \(cq\&F\(cq\&. For example, the following will ensure | file by prefixing it with a 'F'. For example, the following will ensure |
that all directories get marked set\-gid, that no files are other\-writable, | that all directories get marked set-gid, that no files are other-writable, |
that both are user\-writable and group\-writable, and that both have | that both are user-writable and group-writable, and that both have |
consistent executability across all bits: |
consistent executability across all bits: |
.IP | .RS 4 |
.RS | .IP |
\-\-chmod=Dg+s,ug+w,Fo\-w,+X | .nf |
| --chmod=Dg+s,ug+w,Fo-w,+X |
| .fi |
.RE |
.RE |
| .IP |
.IP | |
Using octal mode numbers is also allowed: |
Using octal mode numbers is also allowed: |
.IP | .RS 4 |
.RS | .IP |
\-\-chmod=D2775,F664 | .nf |
| --chmod=D2775,F664 |
| .fi |
.RE |
.RE |
| .IP |
.IP | It is also legal to specify multiple \fB\-\-chmod\fP options, as each additional |
It is also legal to specify multiple \fB\-\-chmod\fP options, as each | option is just appended to the list of changes to make. To change |
additional option is just appended to the list of changes to make. | permissions of files matching a pattern, use an include filter with the \fBm\fP |
.IP | modifier, which takes effect before any \fB\-\-chmod\fP options. |
| .IP |
See the \fB\-\-perms\fP and \fB\-\-executability\fP options for how the resulting |
See the \fB\-\-perms\fP and \fB\-\-executability\fP options for how the resulting |
permission value can be applied to the files in the transfer. |
permission value can be applied to the files in the transfer. |
.IP | .IP "\fB\-\-owner\fP, \fB\-o\fP" |
.IP "\fB\-o, \-\-owner\fP" | This option causes rsync to set the owner of the destination file to be the |
This option causes rsync to set the owner of the | same as the source file, but only if the receiving rsync is being run as |
destination file to be the same as the source file, but only if the | the super-user (see also the \fB\-\-super\fP and \fB\-\-fake-super\fP options). Without |
receiving rsync is being run as the super\-user (see also the \fB\-\-super\fP | this option, the owner of new and/or transferred files are set to the |
and \fB\-\-fake\-super\fP options). | invoking user on the receiving side. |
Without this option, the owner of new and/or transferred files are set to | .IP |
the invoking user on the receiving side. | |
.IP | |
The preservation of ownership will associate matching names by default, but |
The preservation of ownership will associate matching names by default, but |
may fall back to using the ID number in some circumstances (see also the |
may fall back to using the ID number in some circumstances (see also the |
\fB\-\-numeric\-ids\fP option for a full discussion). | \fB\-\-numeric-ids\fP option for a full discussion). |
.IP | .IP "\fB\-\-group\fP, \fB\-g\fP" |
.IP "\fB\-g, \-\-group\fP" | This option causes rsync to set the group of the destination file to be the |
This option causes rsync to set the group of the | same as the source file. If the receiving program is not running as the |
destination file to be the same as the source file. If the receiving | super-user (or if \fB\-\-no-super\fP was specified), only groups that the |
program is not running as the super\-user (or if \fB\-\-no\-super\fP was | invoking user on the receiving side is a member of will be preserved. |
specified), only groups that the invoking user on the receiving side | |
is a member of will be preserved. | |
Without this option, the group is set to the default group of the invoking |
Without this option, the group is set to the default group of the invoking |
user on the receiving side. |
user on the receiving side. |
.IP | .IP |
The preservation of group information will associate matching names by |
The preservation of group information will associate matching names by |
default, but may fall back to using the ID number in some circumstances |
default, but may fall back to using the ID number in some circumstances |
(see also the \fB\-\-numeric\-ids\fP option for a full discussion). | (see also the \fB\-\-numeric-ids\fP option for a full discussion). |
.IP | |
.IP "\fB\-\-devices\fP" |
.IP "\fB\-\-devices\fP" |
This option causes rsync to transfer character and | This option causes rsync to transfer character and block device files to |
block device files to the remote system to recreate these devices. | the remote system to recreate these devices. This option has no effect if |
This option has no effect if the receiving rsync is not run as the | the receiving rsync is not run as the super-user (see also the \fB\-\-super\fP |
super\-user (see also the \fB\-\-super\fP and \fB\-\-fake\-super\fP options). | and \fB\-\-fake-super\fP options). |
.IP | |
.IP "\fB\-\-specials\fP" |
.IP "\fB\-\-specials\fP" |
This option causes rsync to transfer special files | This option causes rsync to transfer special files such as named sockets |
such as named sockets and fifos. | and fifos. |
.IP | |
.IP "\fB\-D\fP" |
.IP "\fB\-D\fP" |
The \fB\-D\fP option is equivalent to \fB\-\-devices\fP \fB\-\-specials\fP. | The \fB\-D\fP option is equivalent to \fB\-\-devices\ \-\-specials\fP. |
.IP | .IP "\fB\-\-write-devices\fP" |
.IP "\fB\-t, \-\-times\fP" | This tells rsync to treat a device on the receiving side as a regular file, |
This tells rsync to transfer modification times along | allowing the writing of file data into a device. |
with the files and update them on the remote system. Note that if this | .IP |
option is not used, the optimization that excludes files that have not been | This option implies the \fB\-\-inplace\fP option. |
modified cannot be effective; in other words, a missing \fB\-t\fP or \fB\-a\fP will | .IP |
cause the next transfer to behave as if it used \fB\-I\fP, causing all files to be | Be careful using this, as you should know what devices are present on the |
updated (though rsync\(cq\&s delta\-transfer algorithm will make the update fairly efficient | receiving side of the transfer, especially if running rsync as root. |
if the files haven\(cq\&t actually changed, you\(cq\&re much better off using \fB\-t\fP). | .IP |
.IP | This option is refused by an rsync daemon. |
.IP "\fB\-O, \-\-omit\-dir\-times\fP" | .IP "\fB\-\-times\fP, \fB\-t\fP" |
This tells rsync to omit directories when | This tells rsync to transfer modification times along with the files and |
it is preserving modification times (see \fB\-\-times\fP). If NFS is sharing | update them on the remote system. Note that if this option is not used, |
the directories on the receiving side, it is a good idea to use \fB\-O\fP. | the optimization that excludes files that have not been modified cannot be |
This option is inferred if you use \fB\-\-backup\fP without \fB\-\-backup\-dir\fP. | effective; in other words, a missing \fB\-t\fP or \fB\-a\fP will cause the next |
.IP | transfer to behave as if it used \fB\-I\fP, causing all files to be updated |
This option also has the side\-effect of avoiding early creation of directories | (though rsync's delta-transfer algorithm will make the update fairly |
in incremental recursion copies. The default \fB\-\-inc\-recursive\fP copying | efficient if the files haven't actually changed, you're much better off |
normally does an early\-create pass of all the sub\-directories in a parent | using \fB\-t\fP). |
directory in order for it to be able to then set the modify time of the parent | .IP "\fB\-\-atimes\fP, \fB\-U\fP" |
directory right away (without having to delay that until a bunch of recursive | This tells rsync to set the access (use) times of the destination files to |
copying has finished). This early\-create idiom is not necessary if directory | the same value as the source files. |
modify times are not being preserved, so it is skipped. Since early\-create | .IP |
directories don\(cq\&t have accurate mode, mtime, or ownership, the use of this | If repeated, it also sets the \fB\-\-open-noatime\fP option, which can help you |
option can help when someone wants to avoid these partially\-finished | to make the sending and receiving systems have the same access times on the |
directories. | transferred files without needing to run rsync an extra time after a file |
.IP | is transferred. |
.IP "\fB\-J, \-\-omit\-link\-times\fP" | .IP |
This tells rsync to omit symlinks when | Note that some older rsync versions (prior to 3.2.0) may have been built |
it is preserving modification times (see \fB\-\-times\fP). | with a pre-release \fB\-\-atimes\fP patch that does not imply \fB\-\-open-noatime\fP |
.IP | when this option is repeated. |
| .IP "\fB\-\-open-noatime\fP" |
| This tells rsync to open files with the O_NOATIME flag (on systems that |
| support it) to avoid changing the access time of the files that are being |
| transferred. If your OS does not support the O_NOATIME flag then rsync |
| will silently ignore this option. Note also that some filesystems are |
| mounted to avoid updating the atime on read access even without the |
| O_NOATIME flag being set. |
| .IP "\fB\-\-crtimes\fP, \fB\-N,\fP" |
| This tells rsync to set the create times (newness) of the destination |
| files to the same value as the source files. |
| .IP "\fB\-\-omit-dir-times\fP, \fB\-O\fP" |
| This tells rsync to omit directories when it is preserving modification |
| times (see \fB\-\-times\fP). If NFS is sharing the directories on the receiving |
| side, it is a good idea to use \fB\-O\fP. This option is inferred if you use |
| \fB\-\-backup\fP without \fB\-\-backup-dir\fP. |
| .IP |
| This option also has the side-effect of avoiding early creation of |
| directories in incremental recursion copies. The default \fB\-\-inc-recursive\fP |
| copying normally does an early-create pass of all the sub-directories in a |
| parent directory in order for it to be able to then set the modify time of |
| the parent directory right away (without having to delay that until a bunch |
| of recursive copying has finished). This early-create idiom is not |
| necessary if directory modify times are not being preserved, so it is |
| skipped. Since early-create directories don't have accurate mode, mtime, |
| or ownership, the use of this option can help when someone wants to avoid |
| these partially-finished directories. |
| .IP "\fB\-\-omit-link-times\fP, \fB\-J\fP" |
| This tells rsync to omit symlinks when it is preserving modification times |
| (see \fB\-\-times\fP). |
| .IP "\fB\-\-omit-dir-changes\fP" |
| This tells rsync to omit directories when applying any preserved attributes |
| (owner, group, times, permissions) to already existing directories. |
.IP "\fB\-\-super\fP" |
.IP "\fB\-\-super\fP" |
This tells the receiving side to attempt super\-user | This tells the receiving side to attempt super-user activities even if the |
activities even if the receiving rsync wasn\(cq\&t run by the super\-user. These | receiving rsync wasn't run by the super-user. These activities include: |
activities include: preserving users via the \fB\-\-owner\fP option, preserving | preserving users via the \fB\-\-owner\fP option, preserving all groups (not just |
all groups (not just the current user\(cq\&s groups) via the \fB\-\-groups\fP | the current user's groups) via the \fB\-\-groups\fP option, and copying devices |
option, and copying devices via the \fB\-\-devices\fP option. This is useful | via the \fB\-\-devices\fP option. This is useful for systems that allow such |
for systems that allow such activities without being the super\-user, and | activities without being the super-user, and also for ensuring that you |
also for ensuring that you will get errors if the receiving side isn\(cq\&t | will get errors if the receiving side isn't being run as the super-user. |
being run as the super\-user. To turn off super\-user activities, the | To turn off super-user activities, the super-user can use \fB\-\-no-super\fP. |
super\-user can use \fB\-\-no\-super\fP. | .IP "\fB\-\-fake-super\fP" |
.IP | When this option is enabled, rsync simulates super-user activities by |
.IP "\fB\-\-fake\-super\fP" | saving/restoring the privileged attributes via special extended attributes |
When this option is enabled, rsync simulates | that are attached to each file (as needed). This includes the file's owner |
super\-user activities by saving/restoring the privileged attributes via | and group (if it is not the default), the file's device info (device & |
special extended attributes that are attached to each file (as needed). This | special files are created as empty text files), and any permission bits |
includes the file\(cq\&s owner and group (if it is not the default), the file\(cq\&s | that we won't allow to be set on the real file (e.g. the real file gets |
device info (device & special files are created as empty text files), and | u-s,g-s,o-t for safety) or that would limit the owner's access (since the |
any permission bits that we won\(cq\&t allow to be set on the real file (e.g. | real super-user can always access/change a file, the files we create can |
the real file gets u\-s,g\-s,o\-t for safety) or that would limit the owner\(cq\&s | always be accessed/changed by the creating user). This option also handles |
access (since the real super\-user can always access/change a file, the | ACLs (if \fB\-\-acls\fP was specified) and non-user extended attributes (if |
files we create can always be accessed/changed by the creating user). | \fB\-\-xattrs\fP was specified). |
This option also handles ACLs (if \fB\-\-acls\fP was specified) and non\-user | .IP |
extended attributes (if \fB\-\-xattrs\fP was specified). | This is a good way to backup data without using a super-user, and to store |
.IP | |
This is a good way to backup data without using a super\-user, and to store | |
ACLs from incompatible systems. |
ACLs from incompatible systems. |
.IP | .IP |
The \fB\-\-fake\-super\fP option only affects the side where the option is used. | The \fB\-\-fake-super\fP option only affects the side where the option is used. |
To affect the remote side of a remote\-shell connection, use the | To affect the remote side of a remote-shell connection, use the |
\fB\-\-remote\-option\fP (\fB\-M\fP) option: | \fB\-\-remote-option\fP (\fB\-M\fP) option: |
.IP | .RS 4 |
.RS | .IP |
\f(CW rsync \-av \-M\-\-fake\-super /src/ host:/dest/\fP | .nf |
| rsync -av -M--fake-super /src/ host:/dest/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | |
For a local copy, this option affects both the source and the destination. |
For a local copy, this option affects both the source and the destination. |
If you wish a local copy to enable this option just for the destination |
If you wish a local copy to enable this option just for the destination |
files, specify \fB\-M\-\-fake\-super\fP. If you wish a local copy to enable | files, specify \fB\-M\-\-fake-super\fP. If you wish a local copy to enable this |
this option just for the source files, combine \fB\-\-fake\-super\fP with | option just for the source files, combine \fB\-\-fake-super\fP with \fB\-M\-\-super\fP. |
\fB\-M\-\-super\fP. | .IP |
.IP | This option is overridden by both \fB\-\-super\fP and \fB\-\-no-super\fP. |
This option is overridden by both \fB\-\-super\fP and \fB\-\-no\-super\fP. | .IP |
.IP | See also the "\fBfake\ super\fP" setting in the daemon's rsyncd.conf file. |
See also the \(dq\&fake super\(dq\& setting in the daemon\(cq\&s rsyncd.conf file. | .IP "\fB\-\-sparse\fP, \fB\-S\fP" |
.IP | Try to handle sparse files efficiently so they take up less space on the |
.IP "\fB\-S, \-\-sparse\fP" | destination. If combined with \fB\-\-inplace\fP the file created might not end |
Try to handle sparse files efficiently so they take | up with sparse blocks with some combinations of kernel version and/or |
up less space on the destination. Conflicts with \fB\-\-inplace\fP because it\(cq\&s | filesystem type. If \fB\-\-whole-file\fP is in effect (e.g. for a local copy) |
not possible to overwrite data in a sparse fashion. | then it will always work because rsync truncates the file prior to writing |
.IP | out the updated version. |
| .IP |
| Note that versions of rsync older than 3.1.3 will reject the combination of |
| \fB\-\-sparse\fP and \fB\-\-inplace\fP. |
.IP "\fB\-\-preallocate\fP" |
.IP "\fB\-\-preallocate\fP" |
This tells the receiver to allocate each destination | This tells the receiver to allocate each destination file to its eventual |
file to its eventual size before writing data to the file. Rsync will only use | size before writing data to the file. Rsync will only use the real |
the real filesystem\-level preallocation support provided by Linux\(cq\&s | filesystem-level preallocation support provided by Linux's \fBfallocate\fP(2) |
\fBfallocate\fP(2) system call or Cygwin\(cq\&s \fBposix_fallocate\fP(3), not the slow | system call or Cygwin's \fBposix_fallocate\fP(3), not the slow glibc |
glibc implementation that writes a zero byte into each block. | implementation that writes a null byte into each block. |
.IP | .IP |
Without this option, larger files may not be entirely contiguous on the |
Without this option, larger files may not be entirely contiguous on the |
filesystem, but with this option rsync will probably copy more slowly. If the | filesystem, but with this option rsync will probably copy more slowly. If |
destination is not an extent\-supporting filesystem (such as ext4, xfs, NTFS, | the destination is not an extent-supporting filesystem (such as ext4, xfs, |
etc.), this option may have no positive effect at all. | NTFS, etc.), this option may have no positive effect at all. |
.IP | .IP |
.IP "\fB\-n, \-\-dry\-run\fP" | If combined with \fB\-\-sparse\fP, the file will only have sparse blocks (as |
This makes rsync perform a trial run that doesn\(cq\&t | opposed to allocated sequences of null bytes) if the kernel version and |
make any changes (and produces mostly the same output as a real run). It | filesystem type support creating holes in the allocated data. |
is most commonly used in combination with the \fB\-v, \-\-verbose\fP and/or | .IP "\fB\-\-sparse-block=SIZE\fP" |
\fB\-i, \-\-itemize\-changes\fP options to see what an rsync command is going | Change the block size used to handle sparse files to SIZE bytes. This |
to do before one actually runs it. | option only has an effect if the \fB\-\-sparse\fP (\fB\-S\fP) option was also |
.IP | specified. The default block size used by rsync to detect a file hole is |
The output of \fB\-\-itemize\-changes\fP is supposed to be exactly the same on a | 1024 bytes; when the receiver writes data to the destination file and |
| option \fB\-\-sparse\fP is used, rsync checks every 1024-bytes chunk to detect if |
| they are actually filled with data or not. With certain filesystems, |
| optimized to receive data streams for example, enlarging this block size |
| can strongly increase performance. The option can be used to tune this |
| block size. |
| .IP "\fB\-\-dry-run\fP, \fB\-n\fP" |
| This makes rsync perform a trial run that doesn't make any changes (and |
| produces mostly the same output as a real run). It is most commonly used |
| in combination with the \fB\-\-verbose\fP, \fB\-v\fP and/or \fB\-\-itemize-changes\fP, \fB\-i\fP |
| options to see what an rsync command is going to do before one actually |
| runs it. |
| .IP |
| The output of \fB\-\-itemize-changes\fP is supposed to be exactly the same on a |
dry run and a subsequent real run (barring intentional trickery and system |
dry run and a subsequent real run (barring intentional trickery and system |
call failures); if it isn\(cq\&t, that\(cq\&s a bug. Other output should be mostly | call failures); if it isn't, that's a bug. Other output should be mostly |
unchanged, but may differ in some areas. Notably, a dry run does not | unchanged, but may differ in some areas. Notably, a dry run does not send |
send the actual data for file transfers, so \fB\-\-progress\fP has no effect, | the actual data for file transfers, so \fB\-\-progress\fP has no effect, the |
the \(dq\&bytes sent\(dq\&, \(dq\&bytes received\(dq\&, \(dq\&literal data\(dq\&, and \(dq\&matched data\(dq\& | "bytes sent", "bytes received", "literal data", and "matched data" |
statistics are too small, and the \(dq\&speedup\(dq\& value is equivalent to a run | statistics are too small, and the "speedup" value is equivalent to a run |
where no file transfers were needed. |
where no file transfers were needed. |
.IP | .IP "\fB\-\-whole-file\fP, \fB\-W\fP" |
.IP "\fB\-W, \-\-whole\-file\fP" | This option disables rsync's delta-transfer algorithm, which causes all |
With this option rsync\(cq\&s delta\-transfer algorithm | transferred files to be sent whole. The transfer may be faster if this |
is not used and the whole file is sent as\-is instead. The transfer may be | option is used when the bandwidth between the source and destination |
faster if this option is used when the bandwidth between the source and | machines is higher than the bandwidth to disk (especially when the "disk" |
destination machines is higher than the bandwidth to disk (especially when the | is actually a networked filesystem). This is the default when both the |
\(dq\&disk\(dq\& is actually a networked filesystem). This is the default when both | source and destination are specified as local paths, but only if no |
the source and destination are specified as local paths, but only if no | batch-writing option is in effect. |
batch\-writing option is in effect. | .IP "\fB\-\-checksum-choice=STR\fP, \fB\-\-cc=STR\fP" |
.IP | This option overrides the checksum algorithms. If one algorithm name is |
.IP "\fB\-x, \-\-one\-file\-system\fP" | specified, it is used for both the transfer checksums and (assuming |
This tells rsync to avoid crossing a | \fB\-\-checksum\fP is specified) the pre-transfer checksums. If two |
filesystem boundary when recursing. This does not limit the user\(cq\&s ability | comma-separated names are supplied, the first name affects the transfer |
to specify items to copy from multiple filesystems, just rsync\(cq\&s recursion | checksums, and the second name affects the pre-transfer checksums (\fB\-c\fP). |
through the hierarchy of each directory that the user specified, and also | .IP |
the analogous recursion on the receiving side during deletion. Also keep | The checksum options that you may be able to use are: |
in mind that rsync treats a \(dq\&bind\(dq\& mount to the same device as being on the | .IP |
same filesystem. | .RS |
.IP | .IP o |
If this option is repeated, rsync omits all mount\-point directories from | \fBauto\fP (the default automatic choice) |
the copy. Otherwise, it includes an empty directory at each mount\-point it | .IP o |
| \fBxxh128\fP |
| .IP o |
| \fBxxh3\fP |
| .IP o |
| \fBxxh64\fP (aka \fBxxhash\fP) |
| .IP o |
| \fBmd5\fP |
| .IP o |
| \fBmd4\fP |
| .IP o |
| \fBnone\fP |
| .RE |
| .IP |
| Run \fBrsync\ \-\-version\fP to see the default checksum list compiled into your |
| version (which may differ from the list above). |
| .IP |
| If "none" is specified for the first (or only) name, the \fB\-\-whole-file\fP |
| option is forced on and no checksum verification is performed on the |
| transferred data. If "none" is specified for the second (or only) name, |
| the \fB\-\-checksum\fP option cannot be used. |
| .IP |
| The "auto" option is the default, where rsync bases its algorithm choice on |
| a negotiation between the client and the server as follows: |
| .IP |
| When both sides of the transfer are at least 3.2.0, rsync chooses the first |
| algorithm in the client's list of choices that is also in the server's list |
| of choices. If no common checksum choice is found, rsync exits with |
| an error. If the remote rsync is too old to support checksum negotiation, |
| a value is chosen based on the protocol version (which chooses between MD5 |
| and various flavors of MD4 based on protocol age). |
| .IP |
| The default order can be customized by setting the environment variable |
| RSYNC_CHECKSUM_LIST to a space-separated list of acceptable checksum names. |
| If the string contains a "\fB&\fP" character, it is separated into the "client |
| string & server string", otherwise the same string |
| applies to both. If the string (or string portion) contains no |
| non-whitespace characters, the default checksum list is used. This method |
| does not allow you to specify the transfer checksum separately from the |
| pre-transfer checksum, and it discards "auto" and all unknown checksum |
| names. A list with only invalid names results in a failed negotiation. |
| .IP |
| The use of the \fB\-\-checksum-choice\fP option overrides this environment list. |
| .IP "\fB\-\-one-file-system\fP, \fB\-x\fP" |
| This tells rsync to avoid crossing a filesystem boundary when recursing. |
| This does not limit the 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 analogous recursion on the |
| receiving side during deletion. Also keep in mind that rsync treats a |
| "bind" mount to the same device as being on the same filesystem. |
| .IP |
| If this option is repeated, rsync omits all mount-point directories from |
| the copy. Otherwise, it includes an empty directory at each mount-point it |
encounters (using the attributes of the mounted directory because those of |
encounters (using the attributes of the mounted directory because those of |
the underlying mount\-point directory are inaccessible). | the underlying mount-point directory are inaccessible). |
.IP | .IP |
If rsync has been told to collapse symlinks (via \fB\-\-copy\-links\fP or | If rsync has been told to collapse symlinks (via \fB\-\-copy-links\fP or |
\fB\-\-copy\-unsafe\-links\fP), a symlink to a directory on another device is | \fB\-\-copy-unsafe-links\fP), a symlink to a directory on another device is |
treated like a mount\-point. Symlinks to non\-directories are unaffected | treated like a mount-point. Symlinks to non-directories are unaffected by |
by this option. | this option. |
.IP | .IP "\fB\-\-existing\fP, \fB\-\-ignore-non-existing\fP" |
.IP "\fB\-\-existing, \-\-ignore\-non\-existing\fP" | This tells rsync to skip creating files (including directories) that do not |
This tells rsync to skip | exist yet on the destination. If this option is combined with the |
creating files (including directories) that do not exist | \fB\-\-ignore-existing\fP option, no files will be updated (which can be useful |
yet on the destination. If this option is | if all you want to do is delete extraneous files). |
combined with the \fB\-\-ignore\-existing\fP option, no files will be updated | .IP |
(which can be useful if all you want to do is delete extraneous files). | This option is a transfer rule, not an exclude, so it doesn't affect the |
.IP | data that goes into the file-lists, and thus it doesn't affect deletions. |
This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the | |
data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. | |
It just limits the files that the receiver requests to be transferred. |
It just limits the files that the receiver requests to be transferred. |
.IP | .IP "\fB\-\-ignore-existing\fP" |
.IP "\fB\-\-ignore\-existing\fP" | This tells rsync to skip updating files that already exist on the |
This tells rsync to skip updating files that | destination (this does \fInot\fP ignore existing directories, or nothing would |
already exist on the destination (this does \fInot\fP ignore existing | get done). See also \fB\-\-existing\fP. |
directories, or nothing would get done). See also \fB\-\-existing\fP. | .IP |
.IP | This option is a transfer rule, not an exclude, so it doesn't affect the |
This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the | data that goes into the file-lists, and thus it doesn't affect deletions. |
data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. | |
It just limits the files that the receiver requests to be transferred. |
It just limits the files that the receiver requests to be transferred. |
.IP | .IP |
This option can be useful for those doing backups using the \fB\-\-link\-dest\fP | This option can be useful for those doing backups using the \fB\-\-link-dest\fP |
option when they need to continue a backup run that got interrupted. Since |
option when they need to continue a backup run that got interrupted. Since |
a \fB\-\-link\-dest\fP run is copied into a new directory hierarchy (when it is | a \fB\-\-link-dest\fP run is copied into a new directory hierarchy (when it is |
used properly), using \fB\-\-ignore existing\fP will ensure that the | used properly), using \fB\-\-ignore-existing\fP will ensure that the |
already\-handled files don\(cq\&t get tweaked (which avoids a change in | already-handled files don't get tweaked (which avoids a change in |
permissions on the hard\-linked files). This does mean that this option | permissions on the hard-linked files). This does mean that this option is |
is only looking at the existing files in the destination hierarchy itself. | only looking at the existing files in the destination hierarchy itself. |
.IP | .IP "\fB\-\-remove-source-files\fP" |
.IP "\fB\-\-remove\-source\-files\fP" | This tells rsync to remove from the sending side the files (meaning |
This tells rsync to remove from the sending | non-directories) that are a part of the transfer and have been successfully |
side the files (meaning non\-directories) that are a part of the transfer | duplicated on the receiving side. |
and have been successfully duplicated on the receiving side. | .IP |
.IP | 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 are quiescent. | quiescent. If you are using this to move files that show up in a |
If you are using this to move files that show up in a particular directory over | particular directory over to another host, make sure that the finished |
to another host, make sure that the finished files get renamed into the source | files get renamed into the source directory, not directly written into it, |
directory, not directly written into it, so that rsync can\(cq\&t possibly transfer | so that rsync can't possibly transfer a file that is not yet fully written. |
a file that is not yet fully written. If you can\(cq\&t first write the files into | If you can't first write the files into a different directory, you should |
a different directory, you should use a naming idiom that lets rsync avoid | use a naming idiom that lets rsync avoid transferring files that are not |
transferring files that are not yet finished (e.g. name the file \(dq\&foo.new\(dq\& when | yet finished (e.g. name the file "foo.new" when it is written, rename it to |
it is written, rename it to \(dq\&foo\(dq\& when it is done, and then use the option | "foo" when it is done, and then use the option \fB\-\-exclude='*.new'\fP for the |
\fB\-\-exclude='\&*.new'\&\fP for the rsync transfer). | rsync transfer). |
.IP | .IP |
Starting with 3.1.0, rsync will skip the sender\-side removal (and output an | Starting with 3.1.0, rsync will skip the sender-side removal (and output an |
error) if the file\(cq\&s size or modify time has not stayed unchanged. | error) if the file's size or modify time has not stayed unchanged. |
.IP | .IP "\fB\-\-source-backup\fP" |
| Makes the sender back up the source files it removes due to |
| \fB\-\-remove-source-files\fP. This option is independent of \fB\-\-backup\fP but uses |
| the same \fB\-\-backup-dir\fP and \fB\-\-suffix\fP settings, if any. With |
| \fB\-\-backup-dir\fP, rsync looks for each file's backup dir relative to the |
| source argument the file came from. Consequently, if the \fB\-\-backup-dir\fP |
| path is relative, each source argument gets a separate backup dir at that |
| path relative to the argument. |
.IP "\fB\-\-delete\fP" |
.IP "\fB\-\-delete\fP" |
This tells rsync to delete extraneous files from the | This tells rsync to delete extraneous files from the receiving side (ones |
receiving side (ones that aren\(cq\&t on the sending side), but only for the | that aren't on the sending side), but only for the directories that are |
directories that are being synchronized. You must have asked rsync to | being synchronized. You must have asked rsync to send the whole directory |
send the whole directory (e.g. \(dq\&dir\(dq\& or \(dq\&dir/\(dq\&) without using a wildcard | (e.g. "\fBdir\fP" or "\fBdir/\fP") without using a wildcard for the directory's |
for the directory\(cq\&s contents (e.g. \(dq\&dir/*\(dq\&) since the wildcard is expanded | contents (e.g. "\fBdir/*\fP") since the wildcard is expanded by the shell and |
by the shell and rsync thus gets a request to transfer individual files, not | rsync thus gets a request to transfer individual files, not the files' |
the files\(cq\& parent directory. Files that are excluded from the transfer are | parent directory. Files that are excluded from the transfer are also |
also excluded from being deleted unless you use the \fB\-\-delete\-excluded\fP | excluded from being deleted unless you use the \fB\-\-delete-excluded\fP option |
option or mark the rules as only matching on the sending side (see the | or mark the rules as only matching on the sending side (see the |
include/exclude modifiers in the FILTER RULES section). |
include/exclude modifiers in the FILTER RULES section). |
.IP | .IP |
Prior to rsync 2.6.7, this option would have no effect unless \fB\-\-recursive\fP |
Prior to rsync 2.6.7, this option would have no effect unless \fB\-\-recursive\fP |
was enabled. Beginning with 2.6.7, deletions will also occur when \fB\-\-dirs\fP |
was enabled. Beginning with 2.6.7, deletions will also occur when \fB\-\-dirs\fP |
(\fB\-d\fP) is enabled, but only for directories whose contents are being copied. | (\fB\-d\fP) is enabled, but only for directories whose contents are being |
.IP | copied. |
This option can be dangerous if used incorrectly! It is a very good idea to | .IP |
first try a run using the \fB\-\-dry\-run\fP option (\fB\-n\fP) to see what files are | This option can be dangerous if used incorrectly! It is a very good idea to |
| first try a run using the \fB\-\-dry-run\fP option (\fB\-n\fP) to see what files are |
going to be deleted. |
going to be deleted. |
.IP | .IP |
If the sending side detects any I/O errors, then the deletion of any | If the sending side detects any I/O errors, then the deletion of any files |
files at the destination will be automatically disabled. This is to | at the destination will be automatically disabled. This is to prevent |
prevent temporary filesystem failures (such as NFS errors) on the | temporary filesystem failures (such as NFS errors) on the sending side from |
sending side from causing a massive deletion of files on the | causing a massive deletion of files on the destination. You can override |
destination. You can override this with the \fB\-\-ignore\-errors\fP option. | this with the \fB\-\-ignore-errors\fP option. |
.IP | .IP |
The \fB\-\-delete\fP option may be combined with one of the \-\-delete\-WHEN options | The \fB\-\-delete\fP option may be combined with one of the \-\-delete-WHEN options |
without conflict, as well as \fB\-\-delete\-excluded\fP. However, if none of the | without conflict, as well as \fB\-\-delete-excluded\fP. However, if none of the |
\-\-delete\-WHEN options are specified, rsync will choose the | \fB\-\-delete-WHEN\fP options are specified, rsync will choose the |
\fB\-\-delete\-during\fP algorithm when talking to rsync 3.0.0 or newer, and | \fB\-\-delete-during\fP algorithm when talking to rsync 3.0.0 or newer, and the |
the \fB\-\-delete\-before\fP algorithm when talking to an older rsync. See also | \fB\-\-delete-before\fP algorithm when talking to an older rsync. See also |
\fB\-\-delete\-delay\fP and \fB\-\-delete\-after\fP. | \fB\-\-delete-delay\fP and \fB\-\-delete-after\fP. |
.IP | .IP "\fB\-\-delete-before\fP" |
.IP "\fB\-\-delete\-before\fP" | Request that the file-deletions on the receiving side be done before the |
Request that the file\-deletions on the receiving | transfer starts. See \fB\-\-delete\fP (which is implied) for more details on |
side be done before the transfer starts. | file-deletion. |
See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. | .IP |
.IP | Deleting before the transfer is helpful if the filesystem is tight for |
Deleting before the transfer is helpful if the filesystem is tight for space | space and removing extraneous files would help to make the transfer |
and removing extraneous files would help to make the transfer possible. | possible. However, it does introduce a delay before the start of the |
However, it does introduce a delay before the start of the transfer, | transfer, and this delay might cause the transfer to timeout (if |
and this delay might cause the transfer to timeout (if \fB\-\-timeout\fP was | \fB\-\-timeout\fP was specified). It also forces rsync to use the old, |
specified). It also forces rsync to use the old, non\-incremental recursion | non-incremental recursion algorithm that requires rsync to scan all the |
algorithm that requires rsync to scan all the files in the transfer into | files in the transfer into memory at once (see \fB\-\-recursive\fP). |
memory at once (see \fB\-\-recursive\fP). | .IP "\fB\-\-delete-during\fP, \fB\-\-del\fP" |
.IP | Request that the file-deletions on the receiving side be done incrementally |
.IP "\fB\-\-delete\-during, \-\-del\fP" | as the transfer happens. The per-directory delete scan is done right |
Request that the file\-deletions on the | before each directory is checked for updates, so it behaves like a more |
receiving side be done incrementally as the transfer happens. The | efficient \fB\-\-delete-before\fP, including doing the deletions prior to any |
per\-directory delete scan is done right before each directory is checked | per-directory filter files being updated. This option was first added in |
for updates, so it behaves like a more efficient \fB\-\-delete\-before\fP, | rsync version 2.6.4. See \fB\-\-delete\fP (which is implied) for more details on |
including doing the deletions prior to any per\-directory filter files | file-deletion. |
being updated. This option was first added in rsync version 2.6.4. | .IP "\fB\-\-delete-delay\fP" |
See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. | Request that the file-deletions on the receiving side be computed during |
.IP | the transfer (like \fB\-\-delete-during\fP), and then removed after the transfer |
.IP "\fB\-\-delete\-delay\fP" | completes. This is useful when combined with \fB\-\-delay-updates\fP and/or |
Request that the file\-deletions on the receiving | \fB\-\-fuzzy\fP, and is more efficient than using \fB\-\-delete-after\fP (but can |
side be computed during the transfer (like \fB\-\-delete\-during\fP), and then | behave differently, since \fB\-\-delete-after\fP computes the deletions in a |
removed after the transfer completes. This is useful when combined with | separate pass after all updates are done). If the number of removed files |
\fB\-\-delay\-updates\fP and/or \fB\-\-fuzzy\fP, and is more efficient than using | overflows an internal buffer, a temporary file will be created on the |
\fB\-\-delete\-after\fP (but can behave differently, since \fB\-\-delete\-after\fP | receiving side to hold the names (it is removed while open, so you |
computes the deletions in a separate pass after all updates are done). | shouldn't see it during the transfer). If the creation of the temporary |
If the number of removed files overflows an internal buffer, a | file fails, rsync will try to fall back to using \fB\-\-delete-after\fP (which it |
temporary file will be created on the receiving side to hold the names (it | cannot do if \fB\-\-recursive\fP is doing an incremental scan). See \fB\-\-delete\fP |
is removed while open, so you shouldn\(cq\&t see it during the transfer). If | (which is implied) for more details on file-deletion. |
the creation of the temporary file fails, rsync will try to fall back to | .IP "\fB\-\-delete-after\fP" |
using \fB\-\-delete\-after\fP (which it cannot do if \fB\-\-recursive\fP is doing an | Request that the file-deletions on the receiving side be done after the |
incremental scan). | transfer has completed. This is useful if you are sending new |
See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. | per-directory merge files as a part of the transfer and you want their |
.IP | exclusions to take effect for the delete phase of the current transfer. It |
.IP "\fB\-\-delete\-after\fP" | also forces rsync to use the old, non-incremental recursion algorithm that |
Request that the file\-deletions on the receiving | requires rsync to scan all the files in the transfer into memory at once |
side be done after the transfer has completed. This is useful if you | (see \fB\-\-recursive\fP). See \fB\-\-delete\fP (which is implied) for more details on |
are sending new per\-directory merge files as a part of the transfer and | file-deletion. |
you want their exclusions to take effect for the delete phase of the | .IP "\fB\-\-delete-excluded\fP" |
current transfer. It also forces rsync to use the old, non\-incremental | In addition to deleting the files on the receiving side that are not on the |
recursion algorithm that requires rsync to scan all the files in the | sending side, this tells rsync to also delete any files on the receiving |
transfer into memory at once (see \fB\-\-recursive\fP). | side that are excluded (see \fB\-\-exclude\fP). See the FILTER RULES section for |
See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. | a way to make individual exclusions behave this way on the receiver, and |
.IP | for a way to protect files from \fB\-\-delete-excluded\fP. See \fB\-\-delete\fP (which |
.IP "\fB\-\-delete\-excluded\fP" | is implied) for more details on file-deletion. |
In addition to deleting the files on the | .IP "\fB\-\-ignore-missing-args\fP" |
receiving side that are not on the sending side, this tells rsync to also | When rsync is first processing the explicitly requested source files (e.g. |
delete any files on the receiving side that are excluded (see \fB\-\-exclude\fP). | command-line arguments or \fB\-\-files-from\fP entries), it is normally an error |
See the FILTER RULES section for a way to make individual exclusions behave | if the file cannot be found. This option suppresses that error, and does |
this way on the receiver, and for a way to protect files from | not try to transfer the file. This does not affect subsequent |
\fB\-\-delete\-excluded\fP. | vanished-file errors if a file was initially found to be present and later |
See \fB\-\-delete\fP (which is implied) for more details on file\-deletion. | is no longer there. |
.IP | .IP "\fB\-\-delete-missing-args\fP" |
.IP "\fB\-\-ignore\-missing\-args\fP" | This option takes the behavior of (the implied) \fB\-\-ignore-missing-args\fP |
When rsync is first processing the explicitly | option a step farther: each missing arg will become a deletion request of |
requested source files (e.g. command\-line arguments or \fB\-\-files\-from\fP | the corresponding destination file on the receiving side (should it exist). |
entries), it is normally an error if the file cannot be found. This option | If the destination file is a non-empty directory, it will only be |
suppresses that error, and does not try to transfer the file. This does not | successfully deleted if \fB\-\-force-delete\fP or \fB\-\-delete\fP are in effect. Other than |
affect subsequent vanished\-file errors if a file was initially found to be | |
present and later is no longer there. | |
.IP | |
.IP "\fB\-\-delete\-missing\-args\fP" | |
This option takes the behavior of (the implied) | |
\fB\-\-ignore\-missing\-args\fP option a step farther: each missing arg will become | |
a deletion request of the corresponding destination file on the receiving side | |
(should it exist). If the destination file is a non\-empty directory, it will | |
only be successfully deleted if \-\-force or \-\-delete are in effect. Other than | |
that, this option is independent of any other type of delete processing. |
that, this option is independent of any other type of delete processing. |
.IP | .IP |
The missing source files are represented by special file\-list entries which | The missing source files are represented by special file-list entries which |
display as a \(dq\&*missing\(dq\& entry in the \fB\-\-list\-only\fP output. | display as a "\fB*missing\fP" entry in the \fB\-\-list-only\fP output. |
.IP | .IP "\fB\-\-ignore-errors\fP" |
.IP "\fB\-\-ignore\-errors\fP" | Tells \fB\-\-delete\fP to go ahead and delete files even when there are I/O |
Tells \fB\-\-delete\fP to go ahead and delete files | errors. |
even when there are I/O errors. | .IP "\fB\-\-force-delete\fP" |
.IP | This option tells rsync to delete a non-empty directory when it is to be |
.IP "\fB\-\-force\fP" | replaced by a non-directory. This is only relevant if deletions are not |
This option tells rsync to delete a non\-empty directory | active (see \fB\-\-delete\fP for details). |
when it is to be replaced by a non\-directory. This is only relevant if | .IP |
deletions are not active (see \fB\-\-delete\fP for details). | This option can be abbreviated \fB\-\-force\fP for backward compatibility. Note |
.IP | that some older rsync versions used to still require \fB\-\-force\fP when using |
Note for older rsync versions: \fB\-\-force\fP used to still be required when | \fB\-\-delete-after\fP, and it used to be non-functional unless the \fB\-\-recursive\fP |
using \fB\-\-delete\-after\fP, and it used to be non\-functional unless the | option was also enabled. |
\fB\-\-recursive\fP option was also enabled. | .IP "\fB\-\-max-delete=NUM\fP" |
.IP | This tells rsync not to delete more than NUM files or directories. If that |
.IP "\fB\-\-max\-delete=NUM\fP" | limit is exceeded, all further deletions are skipped through the end of the |
This tells rsync not to delete more than NUM | transfer. At the end, rsync outputs a warning (including a count of the |
files or directories. If that limit is exceeded, all further deletions are | skipped deletions) and exits with an error code of 25 (unless some more |
skipped through the end of the transfer. At the end, rsync outputs a warning | important error condition also occurred). |
(including a count of the skipped deletions) and exits with an error code | .IP |
of 25 (unless some more important error condition also occurred). | Beginning with version 3.0.0, you may specify \fB\-\-max-delete=0\fP to be warned |
.IP | |
Beginning with version 3.0.0, you may specify \fB\-\-max\-delete=0\fP to be warned | |
about any extraneous files in the destination without removing any of them. |
about any extraneous files in the destination without removing any of them. |
Older clients interpreted this as \(dq\&unlimited\(dq\&, so if you don\(cq\&t know what | Older clients interpreted this as "unlimited", so if you don't know what |
version the client is, you can use the less obvious \fB\-\-max\-delete=\-1\fP as | version the client is, you can use the less obvious \fB\-\-max-delete=\-1\fP as a |
a backward\-compatible way to specify that no deletions be allowed (though | backward-compatible way to specify that no deletions be allowed (though |
really old versions didn\(cq\&t warn when the limit was exceeded). | really old versions didn't warn when the limit was exceeded). |
.IP | .IP "\fB\-\-max-size=SIZE\fP" |
.IP "\fB\-\-max\-size=SIZE\fP" | This tells rsync to avoid transferring any file that is larger than the |
This tells rsync to avoid transferring any | specified SIZE. A numeric value can be suffixed with a string to indicate |
file that is larger than the specified SIZE. The SIZE value can be | the numeric units or left unqualified to specify bytes. Feel free to use a |
suffixed with a string to indicate a size multiplier, and | fractional value along with the units, such as \fB\-\-max-size=1.5m\fP. |
may be a fractional value (e.g. \(dq\&\fB\-\-max\-size=1.5m\fP\(dq\&). | .IP |
.IP | This option is a transfer rule, not an exclude, so it doesn't affect the |
This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the | data that goes into the file-lists, and thus it doesn't affect deletions. |
data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions. | |
It just limits the files that the receiver requests to be transferred. |
It just limits the files that the receiver requests to be transferred. |
.IP | .IP |
The suffixes are as follows: \(dq\&K\(dq\& (or \(dq\&KiB\(dq\&) is a kibibyte (1024), | The first letter of a units string can be \fBB\fP (bytes), \fBK\fP (kilo), \fBM\fP |
\(dq\&M\(dq\& (or \(dq\&MiB\(dq\&) is a mebibyte (1024*1024), and \(dq\&G\(dq\& (or \(dq\&GiB\(dq\&) is a | (mega), \fBG\fP (giga), \fBT\fP (tera), or \fBP\fP (peta). If the string is a single |
gibibyte (1024*1024*1024). | char or has "ib" added to it (e.g. "G" or "GiB") then the units are |
If you want the multiplier to be 1000 instead of 1024, use \(dq\&KB\(dq\&, | multiples of 1024. If you use a two-letter suffix that ends with a "B" |
\(dq\&MB\(dq\&, or \(dq\&GB\(dq\&. (Note: lower\-case is also accepted for all values.) | (e.g. "kb") then you get units that are multiples of 1000. The string's |
Finally, if the suffix ends in either \(dq\&+1\(dq\& or \(dq\&\-1\(dq\&, the value will | letters can be any mix of upper and lower-case that you want to use. |
be offset by one byte in the indicated direction. | .IP |
.IP | Finally, if the string ends with either "+1" or "\-1", it is offset by one |
Examples: \-\-max\-size=1.5mb\-1 is 1499999 bytes, and \-\-max\-size=2g+1 is | byte in the indicated direction. The largest possible value is usually |
| \fB8192P-1\fP. |
| .IP |
| Examples: \fB\-\-max-size=1.5mb-1\fP is 1499999 bytes, and \fB\-\-max-size=2g+1\fP is |
2147483649 bytes. |
2147483649 bytes. |
.IP | .IP |
Note that rsync versions prior to 3.1.0 did not allow \fB\-\-max\-size=0\fP. | Note that rsync versions prior to 3.1.0 did not allow \fB\-\-max-size=0\fP. |
.IP | .IP "\fB\-\-min-size=SIZE\fP" |
.IP "\fB\-\-min\-size=SIZE\fP" | This tells rsync to avoid transferring any file that is smaller than the |
This tells rsync to avoid transferring any | specified SIZE, which can help in not transferring small, junk files. See |
file that is smaller than the specified SIZE, which can help in not | the \fB\-\-max-size\fP option for a description of SIZE and other information. |
transferring small, junk files. | .IP |
See the \fB\-\-max\-size\fP option for a description of SIZE and other information. | Note that rsync versions prior to 3.1.0 did not allow \fB\-\-min-size=0\fP. |
.IP | .IP "\fB\-\-max-alloc=SIZE\fP" |
Note that rsync versions prior to 3.1.0 did not allow \fB\-\-min\-size=0\fP. | By default rsync limits an individual malloc/realloc to about 1GB in size. |
.IP | For most people this limit works just fine and prevents a protocol error |
.IP "\fB\-B, \-\-block\-size=BLOCKSIZE\fP" | causing rsync to request massive amounts of memory. However, if you have |
This forces the block size used in | many millions of files in a transfer, a large amount of server memory, and |
rsync\(cq\&s delta\-transfer algorithm to a fixed value. It is normally selected based on | you don't want to split up your transfer into multiple parts, you can |
the size of each file being updated. See the technical report for details. | increase the per-allocation limit to something larger and rsync will |
.IP | consume more memory. |
.IP "\fB\-e, \-\-rsh=COMMAND\fP" | .IP |
This option allows you to choose an alternative | Keep in mind that this is not a limit on the total size of allocated |
remote shell program to use for communication between the local and | memory. It is a sanity-check value for each individual allocation. |
remote copies of rsync. Typically, rsync is configured to use ssh by | .IP |
default, but you may prefer to use rsh on a local network. | See the \fB\-\-max-size\fP option for a description of how SIZE can be specified. |
.IP | The default suffix if none is given is bytes. |
If this option is used with \fB[user@]host::module/path\fP, then the | .IP |
remote shell \fICOMMAND\fP will be used to run an rsync daemon on the | Beginning in 3.2.3, a value of 0 specifies no limit. |
remote host, and all data will be transmitted through that remote | .IP |
shell connection, rather than through a direct socket connection to a | You can set a default value using the environment variable RSYNC_MAX_ALLOC |
running rsync daemon on the remote host. See the section \(dq\&USING | using the same SIZE values as supported by this option. If the remote |
RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION\(dq\& above. | rsync doesn't understand the \fB\-\-max-alloc\fP option, you can override an |
.IP | environmental value by specifying \fB\-\-max-alloc=1g\fP, which will make rsync |
Command\-line arguments are permitted in COMMAND provided that COMMAND is | avoid sending the option to the remote side (because "1G" is the default). |
presented to rsync as a single argument. You must use spaces (not tabs | .IP "\fB\-\-block-size=SIZE\fP, \fB\-B\fP" |
or other whitespace) to separate the command and args from each other, | This forces the block size used in rsync's delta-transfer algorithm to a |
and you can use single\- and/or double\-quotes to preserve spaces in an | fixed value. It is normally selected based on the size of each file being |
argument (but not backslashes). Note that doubling a single\-quote | updated. See the technical report for details. |
inside a single\-quoted string gives you a single\-quote; likewise for | .IP |
double\-quotes (though you need to pay attention to which quotes your | Beginning in 3.2.3 the SIZE can be specified with a suffix as detailed in |
shell is parsing and which quotes rsync is parsing). Some examples: | the \fB\-\-max-size\fP option. Older versions only accepted a byte count. |
.IP | .IP "\fB\-\-rsh=COMMAND\fP, \fB\-e\fP" |
.RS | This option allows you to choose an alternative remote shell program to use |
\f(CW \-e '\&ssh \-p 2234'\&\fP | for communication between the local and remote copies of rsync. Typically, |
.br | rsync is configured to use ssh by default, but you may prefer to use rsh on |
\f(CW \-e '\&ssh \-o \(dq\&ProxyCommand nohup ssh firewall nc \-w1 %h %p\(dq\&'\&\fP | a local network. |
.br | .IP |
| If this option is used with \fB[user@]host::module/path\fP, then the remote |
| shell \fICOMMAND\fP will be used to run an rsync daemon on the remote host, and |
| all data will be transmitted through that remote shell connection, rather |
| than through a direct socket connection to a running rsync daemon on the |
| remote host. See the section "USING RSYNC-DAEMON FEATURES VIA A |
| REMOTE-SHELL CONNECTION" above. |
| .IP |
| Beginning with rsync 3.2.0, the RSYNC_PORT environment variable will be set |
| when a daemon connection is being made via a remote-shell connection. It |
| is set to 0 if the default daemon port is being assumed, or it is set to |
| the value of the rsync port that was specified via either the \fB\-\-port\fP |
| option or a non-empty port value in an rsync:// URL. This allows the |
| script to discern if a non-default port is being requested, allowing for |
| things such as an SSL or stunnel helper script to connect to a default or |
| alternate port. |
| .IP |
| Command-line arguments are permitted in COMMAND provided that COMMAND is |
| presented to rsync as a single argument. You must use spaces (not tabs or |
| other whitespace) to separate the command and args from each other, and you |
| can use single- and/or double-quotes to preserve spaces in an argument (but |
| not backslashes). Note that doubling a single-quote inside a single-quoted |
| string gives you a single-quote; likewise for double-quotes (though you |
| need to pay attention to which quotes your shell is parsing and which |
| quotes rsync is parsing). Some examples: |
| .RS 4 |
| .IP |
| .nf |
| -e 'ssh -p 2234' |
| -e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"' |
| .fi |
.RE |
.RE |
| .IP |
.IP | (Note that ssh users can alternately customize site-specific connect |
(Note that ssh users can alternately customize site\-specific connect | |
options in their .ssh/config file.) |
options in their .ssh/config file.) |
.IP | .IP |
You can also choose the remote shell program using the RSYNC_RSH |
You can also choose the remote shell program using the RSYNC_RSH |
environment variable, which accepts the same range of values as \fB\-e\fP. |
environment variable, which accepts the same range of values as \fB\-e\fP. |
.IP | .IP |
See also the \fB\-\-blocking\-io\fP option which is affected by this option. | See also the \fB\-\-blocking-io\fP option which is affected by this option. |
.IP | .IP "\fB\-\-rsync-path=PROGRAM\fP" |
.IP "\fB\-\-rsync\-path=PROGRAM\fP" | Use this to specify what program is to be run on the remote machine to |
Use this to specify what program is to be run | start-up rsync. Often used when rsync is not in the default remote-shell's |
on the remote machine to start\-up rsync. Often used when rsync is not in | path (e.g. \fB\-\-rsync-path=/usr/local/bin/rsync\fP). Note that PROGRAM is run |
the default remote\-shell\(cq\&s path (e.g. \-\-rsync\-path=/usr/local/bin/rsync). | with the help of a shell, so it can be any program, script, or command |
Note that PROGRAM is run with the help of a shell, so it can be any | sequence you'd care to run, so long as it does not corrupt the standard-in |
program, script, or command sequence you\(cq\&d care to run, so long as it does | & standard-out that rsync is using to communicate. |
not corrupt the standard\-in & standard\-out that rsync is using to | .IP |
communicate. | |
.IP | |
One tricky example is to set a different default directory on the remote |
One tricky example is to set a different default directory on the remote |
machine for use with the \fB\-\-relative\fP option. For instance: |
machine for use with the \fB\-\-relative\fP option. For instance: |
.IP | .RS 4 |
.RS | .IP |
\f(CW rsync \-avR \-\-rsync\-path=\(dq\&cd /a/b && rsync\(dq\& host:c/d /e/\fP | .nf |
| rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/ |
| .fi |
.RE |
.RE |
| .IP "\fB\-\-remote-option=OPTION\fP, \fB\-M\fP" |
.IP | This option is used for more advanced situations where you want certain |
.IP "\fB\-M, \-\-remote\-option=OPTION\fP" | effects to be limited to one side of the transfer only. For instance, if |
This option is used for more advanced | you want to pass \fB\-\-log-file=FILE\fP and \fB\-\-fake-super\fP to the remote system, |
situations where you want certain effects to be limited to one side of the | specify it like this: |
transfer only. For instance, if you want to pass \fB\-\-log\-file=FILE\fP and | .RS 4 |
\fB\-\-fake\-super\fP to the remote system, specify it like this: | .IP |
.IP | .nf |
.RS | rsync -av -M --log-file=foo -M--fake-super src/ dest/ |
\f(CW rsync \-av \-M \-\-log\-file=foo \-M\-\-fake\-super src/ dest/\fP | .fi |
.RE |
.RE |
| .IP |
.IP | |
If you want to have an option affect only the local side of a transfer when |
If you want to have an option affect only the local side of a transfer when |
it normally affects both sides, send its negation to the remote side. Like |
it normally affects both sides, send its negation to the remote side. Like |
this: |
this: |
.IP | .RS 4 |
.RS | .IP |
\f(CW rsync \-av \-x \-M\-\-no\-x src/ dest/\fP | .nf |
| rsync -av -x -M--no-x src/ dest/ |
| .fi |
.RE |
.RE |
| .IP |
.IP | Be cautious using this, as it is possible to toggle an option that will |
Be cautious using this, as it is possible to toggle an option that will cause | cause rsync to have a different idea about what data to expect next over |
rsync to have a different idea about what data to expect next over the socket, | the socket, and that will make it fail in a cryptic fashion. |
and that will make it fail in a cryptic fashion. | .IP |
.IP | Note that it is best to use a separate \fB\-\-remote-option\fP for each option |
Note that it is best to use a separate \fB\-\-remote\-option\fP for each option you | you want to pass. This makes your usage compatible with the |
want to pass. This makes your useage compatible with the \fB\-\-protect\-args\fP | \fB\-\-protect-args\fP option. If that option is off, any spaces in your remote |
option. If that option is off, any spaces in your remote options will be split | options will be split by the remote shell unless you take steps to protect |
by the remote shell unless you take steps to protect them. | them. |
.IP | .IP |
When performing a local transfer, the \(dq\&local\(dq\& side is the sender and the | When performing a local transfer, the "local" side is the sender and the |
\(dq\&remote\(dq\& side is the receiver. | "remote" side is the receiver. |
.IP | .IP |
Note some versions of the popt option\-parsing library have a bug in them that | Note some versions of the popt option-parsing library have a bug in them |
prevents you from using an adjacent arg with an equal in it next to a short | that prevents you from using an adjacent arg with an equal in it next to a |
option letter (e.g. \f(CW\-M\-\-log\-file=/tmp/foo\fP. If this bug affects your | short option letter (e.g. \fB\-M\-\-log-file=/tmp/foo\fP). If this bug affects |
version of popt, you can use the version of popt that is included with rsync. | your version of popt, you can use the version of popt that is included with |
.IP | rsync. |
.IP "\fB\-C, \-\-cvs\-exclude\fP" | .IP "\fB\-\-cvs-exclude\fP, \fB\-C\fP" |
This is a useful shorthand for excluding a | This is a useful shorthand for excluding a broad range of files that you |
broad range of files that you often don\(cq\&t want to transfer between | often don't want to transfer between systems. It uses a similar algorithm |
systems. It uses a similar algorithm to CVS to determine if | to CVS to determine if a file should be ignored. |
a file should be ignored. | .IP |
.IP | |
The exclude list is initialized to exclude the following items (these |
The exclude list is initialized to exclude the following items (these |
initial items are marked as perishable \-\- see the FILTER RULES section): | initial items are marked as perishable\ \-\- see the FILTER RULES section): |
.IP | .RS 4 |
.RS | .IP |
.RS | \fBRCS\fP |
\f(CWRCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state | \fBSCCS\fP |
\&.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del\-* | \fBCVS\fP |
*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .hg/ .bzr/\fP | \fBCVS.adm\fP |
| \fBRCSLOG\fP |
| \fBcvslog.*\fP |
| \fBtags\fP |
| \fBTAGS\fP |
| \fB.make.state\fP |
| \fB.nse_depinfo\fP |
| \fB*~\fP |
| \fB#*\fP |
| \fB.#*\fP |
| \fB,*\fP |
| \fB_$*\fP |
| \fB*$\fP |
| \fB*.old\fP |
| \fB*.bak\fP |
| \fB*.BAK\fP |
| \fB*.orig\fP |
| \fB*.rej\fP |
| \fB.del-*\fP |
| \fB*.a\fP |
| \fB*.olb\fP |
| \fB*.o\fP |
| \fB*.obj\fP |
| \fB*.so\fP |
| \fB*.exe\fP |
| \fB*.Z\fP |
| \fB*.elc\fP |
| \fB*.ln\fP |
| \fBcore\fP |
| \fB.svn/\fP |
| \fB.git/\fP |
| \fB.hg/\fP |
| \fB.bzr/\fP |
.RE |
.RE |
.RE | .IP |
| |
.IP | |
then, files listed in a $HOME/.cvsignore are added to the list and any |
then, files listed in a $HOME/.cvsignore are added to the list and any |
files listed in the CVSIGNORE environment variable (all cvsignore names | files listed in the CVSIGNORE environment variable (all cvsignore names are |
are delimited by whitespace). | delimited by whitespace). |
.IP | .IP |
Finally, any file is ignored if it is in the same directory as a | Finally, any file is ignored if it is in the same directory as a .cvsignore |
\&.cvsignore file and matches one of the patterns listed therein. Unlike | file and matches one of the patterns listed therein. Unlike rsync's |
rsync\(cq\&s filter/exclude files, these patterns are split on whitespace. | filter/exclude files, these patterns are split on whitespace. See the |
See the \fBcvs\fP(1) manual for more information. | \fBcvs\fP(1) manual for more information. |
.IP | .IP |
If you\(cq\&re combining \fB\-C\fP with your own \fB\-\-filter\fP rules, you should | If you're combining \fB\-C\fP with your own \fB\-\-filter\fP rules, you should note |
note that these CVS excludes are appended at the end of your own rules, | that these CVS excludes are appended at the end of your own rules, |
regardless of where the \fB\-C\fP was placed on the command\-line. This makes them | regardless of where the \fB\-C\fP was placed on the command-line. This makes |
a lower priority than any rules you specified explicitly. If you want to | them a lower priority than any rules you specified explicitly. If you want |
control where these CVS excludes get inserted into your filter rules, you | to control where these CVS excludes get inserted into your filter rules, |
should omit the \fB\-C\fP as a command\-line option and use a combination of | you should omit the \fB\-C\fP as a command-line option and use a combination of |
\fB\-\-filter=:C\fP and \fB\-\-filter=\-C\fP (either on your command\-line or by | \fB\-\-filter=:C\fP and \fB\-\-filter=\-C\fP (either on your command-line or by putting |
putting the \(dq\&:C\(dq\& and \(dq\&\-C\(dq\& rules into a filter file with your other rules). | the ":C" and "\-C" rules into a filter file with your other rules). The |
The first option turns on the per\-directory scanning for the .cvsignore | first option turns on the per-directory scanning for the .cvsignore file. |
file. The second option does a one\-time import of the CVS excludes | The second option does a one-time import of the CVS excludes mentioned |
mentioned above. | above. |
.IP | .IP "\fB\-\-filter=RULE\fP, \fB\-f\fP" |
.IP "\fB\-f, \-\-filter=RULE\fP" | This option allows you to add rules to selectively exclude certain files |
This option allows you to add rules to selectively | from the list of files to be transferred. This is most useful in |
exclude certain files from the list of files to be transferred. This is | combination with a recursive transfer. |
most useful in combination with a recursive transfer. | .IP |
.IP | You may use as many \fB\-\-filter\fP options on the command line as you like to |
You may use as many \fB\-\-filter\fP options on the command line as you like | build up the list of files to exclude. If the filter contains whitespace, |
to build up the list of files to exclude. If the filter contains whitespace, | |
be sure to quote it so that the shell gives the rule to rsync as a single |
be sure to quote it so that the shell gives the rule to rsync as a single |
argument. The text below also mentions that you can use an underscore to |
argument. The text below also mentions that you can use an underscore to |
replace the space that separates a rule from its arg. |
replace the space that separates a rule from its arg. |
.IP | .IP |
See the FILTER RULES section for detailed information on this option. |
See the FILTER RULES section for detailed information on this option. |
.IP |
|
.IP "\fB\-F\fP" |
.IP "\fB\-F\fP" |
The \fB\-F\fP option is a shorthand for adding two \fB\-\-filter\fP rules to | The \fB\-F\fP option is a shorthand for adding two \fB\-\-filter\fP rules to your |
your command. The first time it is used is a shorthand for this rule: | command. The first time it is used is a shorthand for this rule: |
.IP | .RS 4 |
.RS | .IP |
\f(CW \-\-filter='\&dir\-merge /.rsync\-filter'\&\fP | .nf |
| --filter='dir-merge /.rsync-filter' |
| .fi |
.RE |
.RE |
| .IP |
.IP | This tells rsync to look for per-directory .rsync-filter files that have |
This tells rsync to look for per\-directory .rsync\-filter files that have | |
been sprinkled through the hierarchy and use their rules to filter the |
been sprinkled through the hierarchy and use their rules to filter the |
files in the transfer. If \fB\-F\fP is repeated, it is a shorthand for this |
files in the transfer. If \fB\-F\fP is repeated, it is a shorthand for this |
rule: |
rule: |
.IP | .RS 4 |
.RS | .IP |
\f(CW \-\-filter='\&exclude .rsync\-filter'\&\fP | .nf |
| --filter='exclude .rsync-filter' |
| .fi |
.RE |
.RE |
| .IP |
.IP | This filters out the .rsync-filter files themselves from the transfer. |
This filters out the .rsync\-filter files themselves from the transfer. | .IP |
.IP | |
See the FILTER RULES section for detailed information on how these options |
See the FILTER RULES section for detailed information on how these options |
work. |
work. |
.IP |
|
.IP "\fB\-\-exclude=PATTERN\fP" |
.IP "\fB\-\-exclude=PATTERN\fP" |
This option is a simplified form of the | This option is a simplified form of the \fB\-\-filter\fP option that defaults to |
\fB\-\-filter\fP option that defaults to an exclude rule and does not allow | an exclude rule and does not allow the full rule-parsing syntax of normal |
the full rule\-parsing syntax of normal filter rules. | filter rules. |
.IP | .IP |
See the FILTER RULES section for detailed information on this option. |
See the FILTER RULES section for detailed information on this option. |
.IP | .IP "\fB\-\-exclude-from=FILE\fP" |
.IP "\fB\-\-exclude\-from=FILE\fP" | This option is related to the \fB\-\-exclude\fP option, but it specifies a FILE |
This option is related to the \fB\-\-exclude\fP | that contains exclude patterns (one per line). Blank lines in the file and |
option, but it specifies a FILE that contains exclude patterns (one per line). | lines starting with '\fB;\fP' or '\fB#\fP' are ignored. If \fIFILE\fP is '\fB\-\fP', the |
Blank lines in the file and lines starting with \(cq\&;\(cq\& or \(cq\&#\(cq\& are ignored. | list will be read from standard input. |
If \fIFILE\fP is \fB\-\fP, the list will be read from standard input. | |
.IP | |
.IP "\fB\-\-include=PATTERN\fP" |
.IP "\fB\-\-include=PATTERN\fP" |
This option is a simplified form of the | This option is a simplified form of the \fB\-\-filter\fP option that defaults to |
\fB\-\-filter\fP option that defaults to an include rule and does not allow | an include rule and does not allow the full rule-parsing syntax of normal |
the full rule\-parsing syntax of normal filter rules. | filter rules. |
.IP | .IP |
See the FILTER RULES section for detailed information on this option. |
See the FILTER RULES section for detailed information on this option. |
.IP | .IP "\fB\-\-include-from=FILE\fP" |
.IP "\fB\-\-include\-from=FILE\fP" | This option is related to the \fB\-\-include\fP option, but it specifies a FILE |
This option is related to the \fB\-\-include\fP | that contains include patterns (one per line). Blank lines in the file and |
option, but it specifies a FILE that contains include patterns (one per line). | lines starting with '\fB;\fP' or '\fB#\fP' are ignored. If \fIFILE\fP is '\fB\-\fP', the |
Blank lines in the file and lines starting with \(cq\&;\(cq\& or \(cq\&#\(cq\& are ignored. | list will be read from standard input. |
If \fIFILE\fP is \fB\-\fP, the list will be read from standard input. | .IP "\fB\-\-files-from=FILE\fP" |
.IP | Using this option allows you to specify the exact list of files to transfer |
.IP "\fB\-\-files\-from=FILE\fP" | (as read from the specified FILE or '\fB\-\fP' for standard input). It also |
Using this option allows you to specify the | tweaks the default behavior of rsync to make transferring just the |
exact list of files to transfer (as read from the specified FILE or \fB\-\fP | specified files and directories easier: |
for standard input). It also tweaks the default behavior of rsync to make | .IP |
transferring just the specified files and directories easier: | .RS |
.IP | .IP o |
.RS | |
.IP o | |
The \fB\-\-relative\fP (\fB\-R\fP) option is implied, which preserves the path |
The \fB\-\-relative\fP (\fB\-R\fP) option is implied, which preserves the path |
information that is specified for each item in the file (use |
information that is specified for each item in the file (use |
\fB\-\-no\-relative\fP or \fB\-\-no\-R\fP if you want to turn that off). | \fB\-\-no-relative\fP or \fB\-\-no-R\fP if you want to turn that off). |
.IP o | .IP o |
The \fB\-\-dirs\fP (\fB\-d\fP) option is implied, which will create directories |
The \fB\-\-dirs\fP (\fB\-d\fP) option is implied, which will create directories |
specified in the list on the destination rather than noisily skipping |
specified in the list on the destination rather than noisily skipping |
them (use \fB\-\-no\-dirs\fP or \fB\-\-no\-d\fP if you want to turn that off). | them (use \fB\-\-no-dirs\fP or \fB\-\-no-d\fP if you want to turn that off). |
.IP o | .IP o |
The \fB\-\-archive\fP (\fB\-a\fP) option\(cq\&s behavior does not imply \fB\-\-recursive\fP | The \fB\-\-archive\fP (\fB\-a\fP) option's behavior does not imply \fB\-\-recursive\fP |
(\fB\-r\fP), so specify it explicitly, if you want it. |
(\fB\-r\fP), so specify it explicitly, if you want it. |
.IP o | .IP o |
These side\-effects change the default state of rsync, so the position | These side-effects change the default state of rsync, so the position of |
of the \fB\-\-files\-from\fP option on the command\-line has no bearing on how | the \fB\-\-files-from\fP option on the command-line has no bearing on how other |
other options are parsed (e.g. \fB\-a\fP works the same before or after | options are parsed (e.g. \fB\-a\fP works the same before or after |
\fB\-\-files\-from\fP, as does \fB\-\-no\-R\fP and all other options). | \fB\-\-files-from\fP, as does \fB\-\-no-R\fP and all other options). |
.RE |
.RE |
| .IP |
.IP | The filenames that are read from the FILE are all relative to the source |
The filenames that are read from the FILE are all relative to the | dir\ \-\- any leading slashes are removed and no ".." references are allowed |
source dir \-\- any leading slashes are removed and no \(dq\&..\(dq\& references are | to go higher than the source dir. For example, take this command: |
allowed to go higher than the source dir. For example, take this | .RS 4 |
command: | .IP |
.IP | .nf |
.RS | rsync -a --files-from=/tmp/foo /usr remote:/backup |
\f(CW rsync \-a \-\-files\-from=/tmp/foo /usr remote:/backup\fP | .fi |
.RE |
.RE |
| .IP |
.IP | If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin |
If /tmp/foo contains the string \(dq\&bin\(dq\& (or even \(dq\&/bin\(dq\&), the /usr/bin | |
directory will be created as /backup/bin on the remote host. If it |
directory will be created as /backup/bin on the remote host. If it |
contains \(dq\&bin/\(dq\& (note the trailing slash), the immediate contents of | contains "bin/" (note the trailing slash), the immediate contents of the |
the directory would also be sent (without needing to be explicitly | directory would also be sent (without needing to be explicitly mentioned in |
mentioned in the file \-\- this began in version 2.6.4). In both cases, | the file\ \-\- this began in version 2.6.4). In both cases, if the \fB\-r\fP |
if the \fB\-r\fP option was enabled, that dir\(cq\&s entire hierarchy would | option was enabled, that dir's entire hierarchy would also be transferred |
also be transferred (keep in mind that \fB\-r\fP needs to be specified | (keep in mind that \fB\-r\fP needs to be specified explicitly with |
explicitly with \fB\-\-files\-from\fP, since it is not implied by \fB\-a\fP). | \fB\-\-files-from\fP, since it is not implied by \fB\-a\fP). Also note that the |
Also note | effect of the (enabled by default) \fB\-\-relative\fP option is to duplicate only |
that the effect of the (enabled by default) \fB\-\-relative\fP option is to | the path info that is read from the file\ \-\- it does not force the |
duplicate only the path info that is read from the file \-\- it does not | duplication of the source-spec path (/usr in this case). |
force the duplication of the source\-spec path (/usr in this case). | .IP |
.IP | In addition, the \fB\-\-files-from\fP file can be read from the remote host |
In addition, the \fB\-\-files\-from\fP file can be read from the remote host | instead of the local host if you specify a "host:" in front of the file |
instead of the local host if you specify a \(dq\&host:\(dq\& in front of the file | (the host must match one end of the transfer). As a short-cut, you can |
(the host must match one end of the transfer). As a short\-cut, you can | specify just a prefix of ":" to mean "use the remote end of the transfer". |
specify just a prefix of \(dq\&:\(dq\& to mean \(dq\&use the remote end of the | For example: |
transfer\(dq\&. For example: | .RS 4 |
.IP | .IP |
.RS | .nf |
\f(CW rsync \-a \-\-files\-from=:/path/file\-list src:/ /tmp/copy\fP | rsync -a --files-from=:/path/file-list src:/ /tmp/copy |
| .fi |
.RE |
.RE |
| .IP |
.IP | This would copy all the files specified in the /path/file-list file that |
This would copy all the files specified in the /path/file\-list file that | was located on the remote "src" host. |
was located on the remote \(dq\&src\(dq\& host. | .IP |
.IP | If the \fB\-\-iconv\fP and \fB\-\-protect-args\fP options are specified and the |
If the \fB\-\-iconv\fP and \fB\-\-protect\-args\fP options are specified and the | \fB\-\-files-from\fP filenames are being sent from one host to another, the |
\fB\-\-files\-from\fP filenames are being sent from one host to another, the | filenames will be translated from the sending host's charset to the |
filenames will be translated from the sending host\(cq\&s charset to the | receiving host's charset. |
receiving host\(cq\&s charset. | .IP |
.IP | NOTE: sorting the list of files in the \fB\-\-files-from\fP input helps rsync to |
NOTE: sorting the list of files in the \-\-files\-from input helps rsync to be | be more efficient, as it will avoid re-visiting the path elements that are |
more efficient, as it will avoid re\-visiting the path elements that are shared | shared between adjacent entries. If the input is not sorted, some path |
between adjacent entries. If the input is not sorted, some path elements | elements (implied directories) may end up being scanned multiple times, and |
(implied directories) may end up being scanned multiple times, and rsync will | rsync will eventually unduplicate them after they get turned into file-list |
eventually unduplicate them after they get turned into file\-list elements. | elements. |
.IP | .IP "\fB\-\-from0\fP, \fB\-0\fP" |
.IP "\fB\-0, \-\-from0\fP" | This tells rsync that the rules/filenames it reads from a file are |
This tells rsync that the rules/filenames it reads from a | terminated by a null ('\\0') character, not a NL, CR, or CR+LF. This |
file are terminated by a null (\(cq\&\e0\(cq\&) character, not a NL, CR, or CR+LF. | affects \fB\-\-exclude-from\fP, \fB\-\-include-from\fP, \fB\-\-files-from\fP, and any merged |
This affects \fB\-\-exclude\-from\fP, \fB\-\-include\-from\fP, \fB\-\-files\-from\fP, and any | files specified in a \fB\-\-filter\fP rule. It does not affect \fB\-\-cvs-exclude\fP |
merged files specified in a \fB\-\-filter\fP rule. | (since all names read from a .cvsignore file are split on whitespace). |
It does not affect \fB\-\-cvs\-exclude\fP (since all names read from a .cvsignore | .IP "\fB\-\-protect-args\fP, \fB\-s\fP" |
file are split on whitespace). | This option sends all filenames and most options to the remote rsync |
.IP | without allowing the remote shell to interpret them. This means that |
.IP "\fB\-s, \-\-protect\-args\fP" | spaces are not split in names, and any non-wildcard special characters are |
This option sends all filenames and most options to | not translated (such as \fB~\fP, \fB$\fP, \fB;\fP, \fB&\fP, etc.). Wildcards are expanded |
the remote rsync without allowing the remote shell to interpret them. This | on the remote host by rsync (instead of the shell doing it). |
means that spaces are not split in names, and any non\-wildcard special | .IP |
characters are not translated (such as ~, $, ;, &, etc.). Wildcards are | If you use this option with \fB\-\-iconv\fP, the args related to the remote side |
expanded on the remote host by rsync (instead of the shell doing it). | will also be translated from the local to the remote character-set. The |
.IP | translation happens before wild-cards are expanded. See also the |
If you use this option with \fB\-\-iconv\fP, the args related to the remote | \fB\-\-files-from\fP option. |
side will also be translated | .IP |
from the local to the remote character\-set. The translation happens before | |
wild\-cards are expanded. See also the \fB\-\-files\-from\fP option. | |
.IP | |
You may also control this option via the RSYNC_PROTECT_ARGS environment |
You may also control this option via the RSYNC_PROTECT_ARGS environment |
variable. If this variable has a non\-zero value, this option will be enabled | variable. If this variable has a non-zero value, this option will be |
by default, otherwise it will be disabled by default. Either state is | enabled by default, otherwise it will be disabled by default. Either state |
overridden by a manually specified positive or negative version of this option | is overridden by a manually specified positive or negative version of this |
(note that \fB\-\-no\-s\fP and \fB\-\-no\-protect\-args\fP are the negative versions). | option (note that \fB\-\-no-s\fP and \fB\-\-no-protect-args\fP are the negative |
Since this option was first introduced in 3.0.0, you\(cq\&ll need to make sure it\(cq\&s | versions). Since this option was first introduced in 3.0.0, you'll need to |
disabled if you ever need to interact with a remote rsync that is older than | make sure it's disabled if you ever need to interact with a remote rsync |
that. | that is older than that. |
.IP | .IP |
Rsync can also be configured (at build time) to have this option enabled by |
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). | default (with is overridden by both the environment and the command-line). |
| Run \fBrsync\ \-\-version\fP to check if this is the case, as it will display |
| "default protect-args" or "optional protect-args" depending on how it was |
| compiled. |
| .IP |
This option will eventually become a new default setting at some |
This option will eventually become a new default setting at some |
as\-yet\-undetermined point in the future. | as-yet-undetermined point in the future. |
.IP | .IP "\fB\-\-copy-as=USER[:GROUP]\fP" |
.IP "\fB\-T, \-\-temp\-dir=DIR\fP" | This option instructs rsync to use the USER and (if specified after a |
This option instructs rsync to use DIR as a | colon) the GROUP for the copy operations. This only works if the user that |
scratch directory when creating temporary copies of the files transferred | is running rsync has the ability to change users. If the group is not |
on the receiving side. The default behavior is to create each temporary | specified then the user's default groups are used. |
file in the same directory as the associated destination file. | .IP |
Beginning with rsync 3.1.1, the temp\-file names inside the specified DIR will | This option can help to reduce the risk of an rsync being run as root into |
not be prefixed with an extra dot (though they will still have a random suffix | or out of a directory that might have live changes happening to it and you |
added). | want to make sure that root-level read or write actions of system files are |
.IP | not possible. While you could alternatively run all of rsync as the |
| specified user, sometimes you need the root-level host-access credentials |
| to be used, so this allows rsync to drop root for the copying part of the |
| operation after the remote-shell or daemon connection is established. |
| .IP |
| The option only affects one side of the transfer unless the transfer is |
| local, in which case it affects both sides. Use the \fB\-\-remote-option\fP to |
| affect the remote side, such as \fB\-M\-\-copy-as=joe\fP. For a local transfer, |
| the lsh (or lsh.sh) support file provides a local-shell helper script that |
| can be used to allow a "localhost:" or "lh:" host-spec to be specified |
| without needing to setup any remote shells, allowing you to specify remote |
| options that affect the side of the transfer that is using the host-spec |
| (and using hostname "lh" avoids the overriding of the remote directory to |
| the user's home dir). |
| .IP |
| For example, the following rsync writes the local files as user "joe": |
| .RS 4 |
| .IP |
| .nf |
| sudo rsync -aiv --copy-as=joe host1:backups/joe/ /home/joe/ |
| .fi |
| .RE |
| .IP |
| This makes all files owned by user "joe", limits the groups to those that |
| are available to that user, and makes it impossible for the joe user to do |
| a timed exploit of the path to induce a change to a file that the joe user |
| has no permissions to change. |
| .IP |
| The following command does a local copy into the "dest/" dir as user "joe" |
| (assuming you've installed support/lsh into a dir on your $PATH): |
| .RS 4 |
| .IP |
| .nf |
| sudo rsync -aive lsh -M--copy-as=joe src/ lh:dest/ |
| .fi |
| .RE |
| .IP "\fB\-\-ignore-case\fP" |
| This option tells rsync to ignore upper-/lower-case differences when |
| comparing filenames. This can avoid problems when sending files to a |
| filesystem that ignores these differences. |
| .IP "\fB\-\-temp-dir=DIR\fP, \fB\-T\fP" |
| This option instructs rsync to use DIR as a scratch directory when creating |
| temporary copies of the files transferred on the receiving side. The |
| default behavior is to create each temporary file in the same directory as |
| the associated destination file. Beginning with rsync 3.1.1, the temp-file |
| names inside the specified DIR will not be prefixed with an extra dot |
| (though they will still have a random suffix added). |
| .IP |
This option is most often used when the receiving disk partition does not |
This option is most often used when the receiving disk partition does not |
have enough free space to hold a copy of the largest file in the transfer. |
have enough free space to hold a copy of the largest file in the transfer. |
In this case (i.e. when the scratch directory is on a different disk |
In this case (i.e. when the scratch directory is on a different disk |
Line 2023 temporary file in the destination directory, and then
|
Line 2450 temporary file in the destination directory, and then
|
it would be possible for the old file to continue taking up disk space (if |
it would be possible for the old file to continue taking up disk space (if |
someone had it open), and thus there might not be enough room to fit the |
someone had it open), and thus there might not be enough room to fit the |
new version on the disk at the same time. |
new version on the disk at the same time. |
.IP | .IP |
If you are using this option for reasons other than a shortage of disk |
If you are using this option for reasons other than a shortage of disk |
space, you may wish to combine it with the \fB\-\-delay\-updates\fP option, | space, you may wish to combine it with the \fB\-\-delay-updates\fP option, which |
which will ensure that all copied files get put into subdirectories in the | will ensure that all copied files get put into subdirectories in the |
destination hierarchy, awaiting the end of the transfer. If you don\(cq\&t | destination hierarchy, awaiting the end of the transfer. If you don't have |
have enough room to duplicate all the arriving files on the destination | enough room to duplicate all the arriving files on the destination |
partition, another way to tell rsync that you aren\(cq\&t overly concerned | partition, another way to tell rsync that you aren't overly concerned about |
about disk space is to use the \fB\-\-partial\-dir\fP option with a relative | disk space is to use the \fB\-\-partial-dir\fP option with a relative path; |
path; because this tells rsync that it is OK to stash off a copy of a | because this tells rsync that it is OK to stash off a copy of a single file |
single file in a subdir in the destination hierarchy, rsync will use the | in a subdir in the destination hierarchy, rsync will use the partial-dir as |
partial\-dir as a staging area to bring over the copied file, and then | a staging area to bring over the copied file, and then rename it into place |
rename it into place from there. (Specifying a \fB\-\-partial\-dir\fP with | from there. (Specifying a \fB\-\-partial-dir\fP with an absolute path does not |
an absolute path does not have this side\-effect.) | have this side-effect.) |
.IP | .IP "\fB\-\-fuzzy\fP, \fB\-y\fP" |
.IP "\fB\-y, \-\-fuzzy\fP" | This option tells rsync that it should look for a basis file for any |
This option tells rsync that it should look for a | destination file that is missing. The current algorithm looks in the same |
basis file for any destination file that is missing. The current algorithm | directory as the destination file for either a file that has an identical |
looks in the same directory as the destination file for either a file that | size and modified-time, or a similarly-named file. If found, rsync uses |
has an identical size and modified\-time, or a similarly\-named file. If | the fuzzy basis file to try to speed up the transfer. |
found, rsync uses the fuzzy basis file to try to speed up the transfer. | .IP |
.IP | |
If the option is repeated, the fuzzy scan will also be done in any matching |
If the option is repeated, the fuzzy scan will also be done in any matching |
alternate destination directories that are specified via \fB\-\-compare\-dest\fP, | alternate destination directories that are specified via \fB\-\-compare-dest\fP, |
\fB\-\-copy\-dest\fP, or \fB\-\-link\-dest\fP. | \fB\-\-copy-dest\fP, or \fB\-\-link-dest\fP. |
.IP | .IP |
Note that the use of the \fB\-\-delete\fP option might get rid of any potential |
Note that the use of the \fB\-\-delete\fP option might get rid of any potential |
fuzzy\-match files, so either use \fB\-\-delete\-after\fP or specify some | fuzzy-match files, so either use \fB\-\-delete-after\fP or specify some filename |
filename exclusions if you need to prevent this. | exclusions if you need to prevent this. |
.IP | .IP "\fB\-\-detect-renamed\fP" |
.IP "\fB\-\-compare\-dest=DIR\fP" | With this option, for each new source file (call it \fBsrc/S\fP), rsync looks |
This option instructs rsync to use \fIDIR\fP on | for a file \fBdest/D\fP anywhere in the destination that passes the quick check |
the destination machine as an additional hierarchy to compare destination | with \fBsrc/S\fP. If such a \fBdest/D\fP is found, rsync uses it as an alternate |
files against doing transfers (if the files are missing in the destination | basis for transferring \fBS\fP. The idea is that if \fBsrc/S\fP was renamed from |
directory). If a file is found in \fIDIR\fP that is identical to the | \fBsrc/D\fP (as opposed to \fBsrc/S\fP passing the quick check with \fBdest/D\fP by |
sender\(cq\&s file, the file will NOT be transferred to the destination | coincidence), the delta-transfer algorithm will find that all the data |
directory. This is useful for creating a sparse backup of just files that | matches between \fBsrc/S\fP and \fBdest/D\fP, and the transfer will be really fast. |
have changed from an earlier backup. | .IP |
This option is typically used to copy into an empty (or newly created) | By default, alternate-basis files are hard-linked into a directory named |
| ".~tmp~" in each file's destination directory, but if you've specified the |
| \fB\-\-partial-dir\fP option, that directory will be used instead. These |
| otential alternate-basis files will be removed as the transfer progresses. |
| This option conflicts with \fB\-\-inplace\fP and \fB\-\-append\fP. |
| .IP "\fB\-\-compare-dest=DIR\fP" |
| This option instructs rsync to use \fIDIR\fP on the destination machine as an |
| additional hierarchy to compare destination files against doing transfers |
| (if the files are missing in the destination directory). If a file is |
| found in \fIDIR\fP that is identical to the sender's file, the file will NOT be |
| transferred to the destination directory. This is useful for creating a |
| sparse backup of just files that have changed from an earlier backup. This |
| option is typically used to copy into an empty (or newly created) |
directory. |
directory. |
.IP | .IP |
Beginning in version 2.6.4, multiple \fB\-\-compare\-dest\fP directories may be | Beginning in version 2.6.4, multiple \fB\-\-compare-dest\fP directories may be |
provided, which will cause rsync to search the list in the order specified |
provided, which will cause rsync to search the list in the order specified |
for an exact match. | for an exact match. If a match is found that differs only in attributes, a |
If a match is found that differs only in attributes, a local copy is made | local copy is made and the attributes updated. If a match is not found, a |
and the attributes updated. | basis file from one of the \fIDIRs\fP will be selected to try to speed up the |
If a match is not found, a basis file from one of the \fIDIR\fPs will be | transfer. |
selected to try to speed up the transfer. | .IP |
.IP | |
If \fIDIR\fP is a relative path, it is relative to the destination directory. |
If \fIDIR\fP is a relative path, it is relative to the destination directory. |
See also \fB\-\-copy\-dest\fP and \fB\-\-link\-dest\fP. | See also \fB\-\-copy-dest\fP and \fB\-\-link-dest\fP. |
.IP | .IP |
NOTE: beginning with version 3.1.0, rsync will remove a file from a non\-empty | NOTE: beginning with version 3.1.0, rsync will remove a file from a |
destination hierarchy if an exact match is found in one of the compare\-dest | non-empty destination hierarchy if an exact match is found in one of the |
hierarchies (making the end result more closely match a fresh copy). | compare-dest hierarchies (making the end result more closely match a fresh |
.IP | copy). |
.IP "\fB\-\-copy\-dest=DIR\fP" | .IP "\fB\-\-copy-dest=DIR\fP" |
This option behaves like \fB\-\-compare\-dest\fP, but | This option behaves like \fB\-\-compare-dest\fP, but rsync will also copy |
rsync will also copy unchanged files found in \fIDIR\fP to the destination | unchanged files found in \fIDIR\fP to the destination directory using a local |
directory using a local copy. | copy. This is useful for doing transfers to a new destination while |
This is useful for doing transfers to a new destination while leaving | leaving existing files intact, and then doing a flash-cutover when all |
existing files intact, and then doing a flash\-cutover when all files have | files have been successfully transferred. |
been successfully transferred. | .IP |
.IP | Multiple \fB\-\-copy-dest\fP directories may be provided, which will cause rsync |
Multiple \fB\-\-copy\-dest\fP directories may be provided, which will cause | to search the list in the order specified for an unchanged file. If a |
rsync to search the list in the order specified for an unchanged file. | match is not found, a basis file from one of the \fIDIRs\fP will be selected to |
If a match is not found, a basis file from one of the \fIDIR\fPs will be | try to speed up the transfer. |
selected to try to speed up the transfer. | .IP |
.IP | |
If \fIDIR\fP is a relative path, it is relative to the destination directory. |
If \fIDIR\fP is a relative path, it is relative to the destination directory. |
See also \fB\-\-compare\-dest\fP and \fB\-\-link\-dest\fP. | See also \fB\-\-compare-dest\fP and \fB\-\-link-dest\fP. |
.IP | .IP "\fB\-\-link-dest=DIR\fP" |
.IP "\fB\-\-link\-dest=DIR\fP" | This option behaves like \fB\-\-copy-dest\fP, but unchanged files are hard linked |
This option behaves like \fB\-\-copy\-dest\fP, but | from \fIDIR\fP to the destination directory. The files must be identical in |
unchanged files are hard linked from \fIDIR\fP to the destination directory. | all preserved attributes (e.g. permissions, possibly ownership) in order |
The files must be identical in all preserved attributes (e.g. permissions, | for the files to be linked together. An example: |
possibly ownership) in order for the files to be linked together. | .RS 4 |
An example: | .IP |
.IP | .nf |
.RS | rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/ |
\f(CW rsync \-av \-\-link\-dest=$PWD/prior_dir host:src_dir/ new_dir/\fP | .fi |
.RE |
.RE |
| .IP |
.IP | If file's aren't linking, double-check their attributes. Also check if |
If file\(cq\&s aren\(cq\&t linking, double\-check their attributes. Also check if some | some attributes are getting forced outside of rsync's control, such a mount |
attributes are getting forced outside of rsync\(cq\&s control, such a mount option | option that squishes root to a single user, or mounts a removable drive |
that squishes root to a single user, or mounts a removable drive with generic | with generic ownership (such as OS X's "Ignore ownership on this volume" |
ownership (such as OS X\(cq\&s \(dq\&Ignore ownership on this volume\(dq\& option). | option). |
.IP | .IP |
Beginning in version 2.6.4, multiple \fB\-\-link\-dest\fP directories may be | Beginning in version 2.6.4, multiple \fB\-\-link-dest\fP directories may be |
provided, which will cause rsync to search the list in the order specified |
provided, which will cause rsync to search the list in the order specified |
for an exact match. | for an exact match (there is a limit of 20 such directories). If a match |
If a match is found that differs only in attributes, a local copy is made | is found that differs only in attributes, a local copy is made and the |
and the attributes updated. | attributes updated. If a match is not found, a basis file from one of the |
If a match is not found, a basis file from one of the \fIDIR\fPs will be | \fIDIRs\fP will be selected to try to speed up the transfer. |
selected to try to speed up the transfer. | .IP |
.IP | |
This option works best when copying into an empty destination hierarchy, as |
This option works best when copying into an empty destination hierarchy, as |
existing files may get their attributes tweaked, and that can affect alternate | existing files may get their attributes tweaked, and that can affect |
destination files via hard\-links. Also, itemizing of changes can get a bit | alternate destination files via hard-links. Also, itemizing of changes can |
muddled. Note that prior to version 3.1.0, an alternate\-directory exact match | get a bit muddled. Note that prior to version 3.1.0, an |
would never be found (nor linked into the destination) when a destination file | alternate-directory exact match would never be found (nor linked into the |
already exists. | destination) when a destination file already exists. |
.IP | .IP |
Note that if you combine this option with \fB\-\-ignore\-times\fP, rsync will not | Note that if you combine this option with \fB\-\-ignore-times\fP, rsync will not |
link any files together because it only links identical files together as a |
link any files together because it only links identical files together as a |
substitute for transferring the file, never as an additional check after the | substitute for transferring the file, never as an additional check after |
file is updated. | the file is updated. |
.IP | .IP |
If \fIDIR\fP is a relative path, it is relative to the destination directory. |
If \fIDIR\fP is a relative path, it is relative to the destination directory. |
See also \fB\-\-compare\-dest\fP and \fB\-\-copy\-dest\fP. | See also \fB\-\-compare-dest\fP and \fB\-\-copy-dest\fP. |
.IP | .IP |
Note that rsync versions prior to 2.6.1 had a bug that could prevent |
Note that rsync versions prior to 2.6.1 had a bug that could prevent |
\fB\-\-link\-dest\fP from working properly for a non\-super\-user when \fB\-o\fP was | \fB\-\-link-dest\fP from working properly for a non-super-user when \fB\-o\fP was |
specified (or implied by \fB\-a\fP). You can work\-around this bug by avoiding | specified (or implied by \fB\-a\fP). You can work-around this bug by avoiding |
the \fB\-o\fP option when sending to an old rsync. |
the \fB\-o\fP option when sending to an old rsync. |
.IP | .IP "\fB\-\-clone-dest=DIR\fP" |
.IP "\fB\-z, \-\-compress\fP" | This option behaves like \fB\-\-link-dest\fP, but unchanged files are reflinked |
With this option, rsync compresses the file data | from \fIDIR\fP to the destination directory. The files do not need to match |
as it is sent to the destination machine, which reduces the amount of data | in attributes, as the data is cloned separately from the attributes. |
being transmitted \-\- something that is useful over a slow connection. | .IP |
.IP | If \fIDIR\fP is a relative path, it is relative to the destination directory. |
Note that this option typically achieves better compression ratios than can | See also \fB\-\-compare-dest\fP and \fB\-\-copy-dest\fP. |
be achieved by using a compressing remote shell or a compressing transport | .IP |
because it takes advantage of the implicit information in the matching data | All non-regular files are hard-linked (when possible). |
blocks that are not explicitly sent over the connection. This matching\-data | .IP "\fB\-\-compress\fP, \fB\-z\fP" |
compression comes at a cost of CPU, though, and can be disabled by repeating | With this option, rsync compresses the file data as it is sent to the |
the \fB\-z\fP option, but only if both sides are at least version 3.1.1. | destination machine, which reduces the amount of data being transmitted\ \-\- |
.IP | something that is useful over a slow connection. |
Note that if your version of rsync was compiled with an external zlib (instead | .IP |
of the zlib that comes packaged with rsync) then it will not support the | Rsync supports multiple compression methods and will choose one for you |
old\-style compression, only the new\-style (repeated\-option) compression. In | unless you force the choice using the \fB\-\-compress-choice\fP (\fB\-\-zc\fP) option. |
the future this new\-style compression will likely become the default. | .IP |
.IP | Run \fBrsync\ \-\-version\fP to see the default compress list compiled into your |
The client rsync requests new\-style compression on the server via the | version. |
\fB\-\-new\-compress\fP option, so if you see that option rejected it means that | .IP |
the server is not new enough to support \fB\-zz\fP. Rsync also accepts the | When both sides of the transfer are at least 3.2.0, rsync chooses the first |
\fB\-\-old\-compress\fP option for a future time when new\-style compression | algorithm in the client's list of choices that is also in the server's list |
becomes the default. | of choices. If no common compress choice is found, rsync exits with |
.IP | an error. If the remote rsync is too old to support checksum negotiation, |
See the \fB\-\-skip\-compress\fP option for the default list of file suffixes | its list is assumed to be "zlib". |
that will not be compressed. | .IP |
.IP | The default order can be customized by setting the environment variable |
.IP "\fB\-\-compress\-level=NUM\fP" | RSYNC_COMPRESS_LIST to a space-separated list of acceptable compression |
Explicitly set the compression level to use | names. If the string contains a "\fB&\fP" character, it is separated into the |
(see \fB\-\-compress\fP) instead of letting it default. If NUM is non\-zero, | "client string & server string", otherwise the same string applies to both. |
the \fB\-\-compress\fP option is implied. | If the string (or string portion) contains no |
.IP | non-whitespace characters, the default compress list is used. Any unknown |
.IP "\fB\-\-skip\-compress=LIST\fP" | compression names are discarded from the list, but a list with only invalid |
Override the list of file suffixes that will | names results in a failed negotiation. |
not be compressed. The \fBLIST\fP should be one or more file suffixes | .IP |
(without the dot) separated by slashes (/). | There are some older rsync versions that were configured to reject a \fB\-z\fP |
.IP | option and require the use of \fB\-zz\fP because their compression library was |
You may specify an empty string to indicate that no file should be skipped. | not compatible with the default zlib compression method. You can usually |
.IP | ignore this weirdness unless the rsync server complains and tells you to |
Simple character\-class matching is supported: each must consist of a list | specify \fB\-zz\fP. |
| .IP |
| See also the \fB\-\-skip-compress\fP option for the default list of file suffixes |
| that will be transferred with no (or minimal) compression. |
| .IP "\fB\-\-compress-choice=STR\fP, \fB\-\-zc=STR\fP" |
| This option can be used to override the automatic negotiation of the |
| compression algorithm that occurs when \fB\-\-compress\fP is used. The option |
| implies \fB\-\-compress\fP unless "none" was specified, which instead implies |
| \fB\-\-no-compress\fP. |
| .IP |
| The compression options that you may be able to use are: |
| .IP |
| .RS |
| .IP o |
| \fBzstd\fP |
| .IP o |
| \fBlz4\fP |
| .IP o |
| \fBzlibx\fP |
| .IP o |
| \fBzlib\fP |
| .IP o |
| \fBnone\fP |
| .RE |
| .IP |
| Run \fBrsync\ \-\-version\fP to see the default compress list compiled into your |
| version (which may differ from the list above). |
| .IP |
| Note that if you see an error about an option named \fB\-\-old-compress\fP or |
| \fB\-\-new-compress\fP, this is rsync trying to send the \fB\-\-compress-choice=zlib\fP |
| or \fB\-\-compress-choice=zlibx\fP 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. |
| .IP |
| Note that the "zlibx" compression algorithm is just the "zlib" algorithm |
| with matched data excluded from the compression stream (to try to make it |
| more compatible with an external zlib implementation). |
| .IP "\fB\-\-compress-level=NUM\fP, \fB\-\-zl=NUM\fP" |
| Explicitly set the compression level to use (see \fB\-\-compress\fP, \fB\-z\fP) |
| instead of letting it default. The \fB\-\-compress\fP option is implied as long |
| as the level chosen is not a "don't compress" level for the compression |
| algorithm that is in effect (e.g. zlib compression treats level 0 as |
| "off"). |
| .IP |
| The level values vary depending on the checksum in effect. Because rsync |
| will negotiate a checksum choice by default (when the remote rsync is new |
| enough), it can be good to combine this option with a \fB\-\-compress-choice\fP |
| (\fB\-\-zc\fP) option unless you're sure of the choice in effect. For example: |
| .RS 4 |
| .IP |
| .nf |
| rsync -aiv --zc=zstd --zl=22 host:src/ dest/ |
| .fi |
| .RE |
| .IP |
| For zlib & zlibx compression the valid values are from 1 to 9 with 6 being |
| the default. Specifying 0 turns compression off, and specifying \-1 chooses |
| the default of 6. |
| .IP |
| For zstd compression the valid values are from \-131072 to 22 with 3 being |
| the default. Specifying 0 chooses the default of 3. |
| .IP |
| For lz4 compression there are no levels, so the value is always 0. |
| .IP |
| If you specify a too-large or too-small value, the number is silently |
| limited to a valid value. This allows you to specify something like |
| \fB\-\-zl=999999999\fP and be assured that you'll end up with the maximum |
| compression level no matter what algorithm was chosen. |
| .IP |
| If you want to know the compression level that is in effect, specify |
| \fB\-\-debug=nstr\fP to see the "negotiated string" results. This will report |
| something like "\fBClient\ compress:\ zstd\ (level\ 3)\fP" (along with the checksum |
| choice in effect). |
| .IP "\fB\-\-skip-compress=LIST\fP" |
| Override the list of file suffixes that will be compressed as little as |
| possible. Rsync sets the compression level on a per-file basis based on |
| the file's suffix. If the compression algorithm has an "off" level (such |
| as zlib/zlibx) then no compression occurs for those files. Other |
| algorithms that support changing the streaming level on-the-fly will 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. |
| .IP |
| The \fBLIST\fP should be one or more file suffixes (without the dot) separated |
| by slashes (\fB/\fP). You may specify an empty string to indicate that no files |
| should be skipped. |
| .IP |
| 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 |
of letters inside the square brackets (e.g. no special classes, such as |
\(dq\&[:alpha:]\(dq\&, are supported, and \(cq\&\-\(cq\& has no special meaning). | "[:alpha:]", are supported, and '\-' has no special meaning). |
.IP | .IP |
The characters asterisk (*) and question\-mark (?) have no special meaning. | The characters asterisk (\fB*\fP) and question-mark (\fB?\fP) have no special meaning. |
.IP | .IP |
Here\(cq\&s an example that specifies 6 suffixes to skip (since 1 of the 5 rules | Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules |
matches 2 suffixes): |
matches 2 suffixes): |
.IP | .RS 4 |
.nf | .IP |
\-\-skip\-compress=gz/jpg/mp[34]/7z/bz2 | .nf |
.fi | --skip-compress=gz/jpg/mp[34]/7z/bz2 |
| .fi |
.IP | .RE |
The default list of suffixes that will not be compressed is this (in this | .IP |
version of rsync): | The default file suffixes in the skip-compress list in this version of |
.IP | rsync are: |
\fB7z\fP | .RS 4 |
\fBace\fP | .IP |
\fBavi\fP | 3g2 |
\fBbz2\fP | 3gp |
\fBdeb\fP | 7z |
\fBgpg\fP | aac |
\fBgz\fP | ace |
\fBiso\fP | apk |
\fBjpeg\fP | avi |
\fBjpg\fP | bz2 |
\fBlz\fP | deb |
\fBlzma\fP | dmg |
\fBlzo\fP | ear |
\fBmov\fP | f4v |
\fBmp3\fP | flac |
\fBmp4\fP | flv |
\fBogg\fP | gpg |
\fBpng\fP | gz |
\fBrar\fP | iso |
\fBrpm\fP | jar |
\fBrzip\fP | jpeg |
\fBtbz\fP | jpg |
\fBtgz\fP | lrz |
\fBtlz\fP | lz |
\fBtxz\fP | lz4 |
\fBxz\fP | lzma |
\fBz\fP | lzo |
\fBzip\fP | m1a |
.IP | m1v |
This list will be replaced by your \fB\-\-skip\-compress\fP list in all but one | m2a |
situation: a copy from a daemon rsync will add your skipped suffixes to | m2ts |
its list of non\-compressing files (and its list may be configured to a | m2v |
| m4a |
| m4b |
| m4p |
| m4r |
| m4v |
| mka |
| mkv |
| mov |
| mp1 |
| mp2 |
| mp3 |
| mp4 |
| mpa |
| mpeg |
| mpg |
| mpv |
| mts |
| odb |
| odf |
| odg |
| odi |
| odm |
| odp |
| ods |
| odt |
| oga |
| ogg |
| ogm |
| ogv |
| ogx |
| opus |
| otg |
| oth |
| otp |
| ots |
| ott |
| oxt |
| png |
| qt |
| rar |
| rpm |
| rz |
| rzip |
| spx |
| squashfs |
| sxc |
| sxd |
| sxg |
| sxm |
| sxw |
| sz |
| tbz |
| tbz2 |
| tgz |
| tlz |
| ts |
| txz |
| tzo |
| vob |
| war |
| webm |
| webp |
| xz |
| z |
| zip |
| zst |
| .RE |
| .IP |
| This list will be replaced by your \fB\-\-skip-compress\fP list in all but one |
| situation: a copy from a daemon rsync will add your skipped suffixes to its |
| list of non-compressing files (and its list may be configured to a |
different default). |
different default). |
.IP | .IP "\fB\-\-numeric-ids\fP" |
.IP "\fB\-\-numeric\-ids\fP" | With this option rsync will transfer numeric group and user IDs rather than |
With this option rsync will transfer numeric group | using user and group names and mapping them at both ends. |
and user IDs rather than using user and group names and mapping them | .IP |
at both ends. | By default rsync will use the username and groupname to determine what |
.IP | ownership to give files. The special uid 0 and the special group 0 are |
By default rsync will use the username and groupname to determine | never mapped via user/group names even if the \fB\-\-numeric-ids\fP option is not |
what ownership to give files. The special uid 0 and the special group | specified. |
0 are never mapped via user/group names even if the \fB\-\-numeric\-ids\fP | .IP |
option is not specified. | If a user or group has no name on the source system or it has no match on |
.IP | the destination system, then the numeric ID from the source system is used |
If a user or group has no name on the source system or it has no match | instead. See also the comments on the "\fBuse\ chroot\fP" setting in the |
on the destination system, then the numeric ID | rsyncd.conf manpage for information on how the chroot setting affects |
from the source system is used instead. See also the comments on the | rsync's ability to look up the names of the users and groups and what you |
\(dq\&use chroot\(dq\& setting in the rsyncd.conf manpage for information on how | can do about it. |
the chroot setting affects rsync\(cq\&s ability to look up the names of the | .IP "\fB\-\-usermap=STRING\fP, \fB\-\-groupmap=STRING\fP" |
users and groups and what you can do about it. | These options allow you to specify users and groups that should be mapped |
.IP | to other values by the receiving side. The \fBSTRING\fP is one or more |
.IP "\fB\-\-usermap=STRING, \-\-groupmap=STRING\fP" | \fBFROM\fP:\fBTO\fP pairs of values separated by commas. Any matching \fBFROM\fP |
These options allow you to | value from the sender is replaced with a \fBTO\fP value from the receiver. |
specify users and groups that should be mapped to other values by the | You may specify usernames or user IDs for the \fBFROM\fP and \fBTO\fP values, |
receiving side. The \fBSTRING\fP is one or more \fBFROM\fP:\fBTO\fP pairs of | and the \fBFROM\fP value may also be a wild-card string, which will be |
values separated by commas. Any matching \fBFROM\fP value from the sender is | matched against the sender's names (wild-cards do NOT match against ID |
replaced with a \fBTO\fP value from the receiver. You may specify usernames | numbers, though see below for why a '\fB*\fP' matches everything). You may |
or user IDs for the \fBFROM\fP and \fBTO\fP values, and the \fBFROM\fP value may | instead specify a range of ID numbers via an inclusive range: LOW-HIGH. |
also be a wild\-card string, which will be matched against the sender\(cq\&s | For example: |
names (wild\-cards do NOT match against ID numbers, though see below for | .RS 4 |
why a \(cq\&*\(cq\& matches everything). You may instead specify a range of ID | .IP |
numbers via an inclusive range: LOW\-HIGH. For example: | .nf |
.IP | --usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1:usr |
.nf | .fi |
\-\-usermap=0\-99:nobody,wayne:admin,*:normal \-\-groupmap=usr:1,1:usr | .RE |
.fi | .IP |
| |
.IP | |
The first match in the list is the one that is used. You should specify |
The first match in the list is the one that is used. You should specify |
all your user mappings using a single \fB\-\-usermap\fP option, and/or all | all your user mappings using a single \fB\-\-usermap\fP option, and/or all your |
your group mappings using a single \fB\-\-groupmap\fP option. | group mappings using a single \fB\-\-groupmap\fP option. |
.IP | .IP |
Note that the sender\(cq\&s name for the 0 user and group are not transmitted | Note that the sender's name for the 0 user and group are not transmitted to |
to the receiver, so you should either match these values using a 0, or use | the receiver, so you should either match these values using a 0, or use the |
the names in effect on the receiving side (typically \(dq\&root\(dq\&). All other | names in effect on the receiving side (typically "root"). All other |
\fBFROM\fP names match those in use on the sending side. All \fBTO\fP names |
\fBFROM\fP names match those in use on the sending side. All \fBTO\fP names |
match those in use on the receiving side. |
match those in use on the receiving side. |
.IP | .IP |
Any IDs that do not have a name on the sending side are treated as having an | Any IDs that do not have a name on the sending side are treated as having |
empty name for the purpose of matching. This allows them to be matched via | an empty name for the purpose of matching. This allows them to be matched |
a \(dq\&*\(dq\& or using an empty name. For instance: | via a "\fB*\fP" or using an empty name. For instance: |
.IP | .RS 4 |
.nf | .IP |
\-\-usermap=:nobody \-\-groupmap=*:nobody | .nf |
.fi | --usermap=:nobody --groupmap=*:nobody |
| .fi |
.IP | .RE |
When the \fB\-\-numeric\-ids\fP option is used, the sender does not send any | .IP |
| When the \fB\-\-numeric-ids\fP option is used, the sender does not send any |
names, so all the IDs are treated as having an empty name. This means that |
names, so all the IDs are treated as having an empty name. This means that |
you will need to specify numeric \fBFROM\fP values if you want to map these |
you will need to specify numeric \fBFROM\fP values if you want to map these |
nameless IDs to different values. |
nameless IDs to different values. |
.IP | .IP |
For the \fB\-\-usermap\fP option to have any effect, the \fB\-o\fP (\fB\-\-owner\fP) | For the \fB\-\-usermap\fP option to have any effect, the \fB\-o\fP (\fB\-\-owner\fP) option |
option must be used (or implied), and the receiver will need to be running | must be used (or implied), and the receiver will need to be running as a |
as a super\-user (see also the \fB\-\-fake\-super\fP option). For the \fB\-\-groupmap\fP | super-user (see also the \fB\-\-fake-super\fP option). For the \fB\-\-groupmap\fP |
option to have any effect, the \fB\-g\fP (\fB\-\-groups\fP) option must be used | option to have any effect, the \fB\-g\fP (\fB\-\-groups\fP) option must be used (or |
(or implied), and the receiver will need to have permissions to set that | implied), and the receiver will need to have permissions to set that group. |
group. | .IP |
.IP | If your shell complains about the wildcards, use \fB\-\-protect-args\fP (\fB\-s\fP). |
.IP "\fB\-\-chown=USER:GROUP\fP" |
.IP "\fB\-\-chown=USER:GROUP\fP" |
This option forces all files to be owned by USER | This option forces all files to be owned by USER with group GROUP. This is |
with group GROUP. This is a simpler interface than using \fB\-\-usermap\fP and | a simpler interface than using \fB\-\-usermap\fP and \fB\-\-groupmap\fP directly, but |
\fB\-\-groupmap\fP directly, but it is implemented using those options internally, | it is implemented using those options internally, so you cannot mix them. |
so you cannot mix them. If either the USER or GROUP is empty, no mapping for | If either the USER or GROUP is empty, no mapping for the omitted user/group |
the omitted user/group will occur. If GROUP is empty, the trailing colon may | will occur. If GROUP is empty, the trailing colon may be omitted, but if |
be omitted, but if USER is empty, a leading colon must be supplied. | USER is empty, a leading colon must be supplied. |
.IP | .IP |
If you specify \(dq\&\-\-chown=foo:bar, this is exactly the same as specifying | If you specify "\fB\-\-chown=foo:bar\fP", this is exactly the same as specifying |
\(dq\&\-\-usermap=*:foo \-\-groupmap=*:bar\(dq\&, only easier. | "\fB\-\-usermap=*:foo\ \-\-groupmap=*:bar\fP", only easier. If your shell complains |
.IP | about the wildcards, use \fB\-\-protect-args\fP (\fB\-s\fP). |
.IP "\fB\-\-timeout=TIMEOUT\fP" | .IP |
This option allows you to set a maximum I/O | To change ownership of files matching a pattern, use an include filter with |
timeout in seconds. If no data is transferred for the specified time | a \fBo\fP or \fBg\fP modifier, which take effect before uid/gid mapping and |
then rsync will exit. The default is 0, which means no timeout. | therefore \fIcan\fP be mixed with \fB\-\-usermap\fP and \fB\-\-groupmap\fP. |
.IP | .IP "\fB\-\-timeout=SECONDS\fP" |
.IP "\fB\-\-contimeout\fP" | This option allows you to set a maximum I/O timeout in seconds. If no data |
This option allows you to set the amount of time | is transferred for the specified time then rsync will exit. The default is |
that rsync will wait for its connection to an rsync daemon to succeed. | 0, which means no timeout. |
If the timeout is reached, rsync exits with an error. | .IP "\fB\-\-contimeout=SECONDS\fP" |
.IP | This option allows you to set the amount of time that rsync will wait for |
.IP "\fB\-\-address\fP" | its connection to an rsync daemon to succeed. If the timeout is reached, |
By default rsync will bind to the wildcard address when | rsync exits with an error. |
connecting to an rsync daemon. The \fB\-\-address\fP option allows you to | .IP "\fB\-\-address=ADDRESS\fP" |
specify a specific IP address (or hostname) to bind to. See also this | By default rsync will bind to the wildcard address when connecting to an |
option in the \fB\-\-daemon\fP mode section. | rsync daemon. The \fB\-\-address\fP option allows you to specify a specific IP |
.IP | address (or hostname) to bind to. See also this option in the \fB\-\-daemon\fP |
| mode section. |
.IP "\fB\-\-port=PORT\fP" |
.IP "\fB\-\-port=PORT\fP" |
This specifies an alternate TCP port number to use | This specifies an alternate TCP port number to use rather than the default |
rather than the default of 873. This is only needed if you are using the | of 873. This is only needed if you are using the double-colon (::) syntax |
double\-colon (::) syntax to connect with an rsync daemon (since the URL | to connect with an rsync daemon (since the URL syntax has a way to specify |
syntax has a way to specify the port as a part of the URL). See also this | the port as a part of the URL). See also this option in the \fB\-\-daemon\fP |
option in the \fB\-\-daemon\fP mode section. | mode section. |
.IP | .IP "\fB\-\-sockopts=OPTIONS\fP" |
.IP "\fB\-\-sockopts\fP" | This option can provide endless fun for people who like to tune their |
This option can provide endless fun for people | systems to the utmost degree. You can set all sorts of socket options |
who like to tune their systems to the utmost degree. You can set all | which may make transfers faster (or slower!). Read the man page for the |
sorts of socket options which may make transfers faster (or | \fBsetsockopt()\fP system call for details on some of the options you may be |
slower!). Read the man page for the | able to set. By default no special socket options are set. This only |
\f(CWsetsockopt()\fP | affects direct socket connections to a remote rsync daemon. |
system call for | .IP |
details on some of the options you may be able to set. By default no | This option also exists in the \fB\-\-daemon\fP mode section. |
special socket options are set. This only affects direct socket | .IP "\fB\-\-blocking-io\fP" |
connections to a remote rsync daemon. This option also exists in the | This tells rsync to use blocking I/O when launching a remote shell |
\fB\-\-daemon\fP mode section. | transport. If the remote shell is either rsh or remsh, rsync defaults to |
.IP | using blocking I/O, otherwise it defaults to using non-blocking I/O. (Note |
.IP "\fB\-\-blocking\-io\fP" | that ssh prefers non-blocking I/O.) |
This tells rsync to use blocking I/O when launching | |
a remote shell transport. If the remote shell is either rsh or remsh, | |
rsync defaults to using | |
blocking I/O, otherwise it defaults to using non\-blocking I/O. (Note that | |
ssh prefers non\-blocking I/O.) | |
.IP | |
.IP "\fB\-\-outbuf=MODE\fP" |
.IP "\fB\-\-outbuf=MODE\fP" |
This sets the output buffering mode. The mode can be | This sets the output buffering mode. The mode can be None (aka |
None (aka Unbuffered), Line, or Block (aka Full). You may specify as little | Unbuffered), Line, or Block (aka Full). You may specify as little as a |
as a single letter for the mode, and use upper or lower case. | single letter for the mode, and use upper or lower case. |
.IP | .IP |
The main use of this option is to change Full buffering to Line buffering |
The main use of this option is to change Full buffering to Line buffering |
when rsync\(cq\&s output is going to a file or pipe. | when rsync's output is going to a file or pipe. |
.IP | .IP "\fB\-\-itemize-changes\fP, \fB\-i\fP" |
.IP "\fB\-i, \-\-itemize\-changes\fP" | Requests a simple itemized list of the changes that are being made to each |
Requests a simple itemized list of the | file, including attribute changes. This is exactly the same as specifying |
changes that are being made to each file, including attribute changes. | \fB\-\-out-format='%i\ %n%L'\fP. If you repeat the option, unchanged files will |
This is exactly the same as specifying \fB\-\-out\-format='\&%i %n%L'\&\fP. | also be output, but only if the receiving rsync is at least version 2.6.7 |
If you repeat the option, unchanged files will also be output, but only | (you can use \fB\-vv\fP with older versions of rsync, but that also turns on the |
if the receiving rsync is at least version 2.6.7 (you can use \fB\-vv\fP | output of other verbose messages). |
with older versions of rsync, but that also turns on the output of other | .IP |
verbose messages). | The "%i" escape has a cryptic output that is 11 letters long. The general |
.IP | format is like the string \fBYXcstpoguaxf\fP, where \fBY\fP is replaced by the type |
The \(dq\&%i\(dq\& escape has a cryptic output that is 11 letters long. The general | of update being done, \fBX\fP is replaced by the file-type, and the other |
format is like the string \fBYXcstpoguax\fP, where \fBY\fP is replaced by the | letters represent attributes that may be output if they are being modified. |
type of update being done, \fBX\fP is replaced by the file\-type, and the | .IP |
other letters represent attributes that may be output if they are being | |
modified. | |
.IP | |
The update types that replace the \fBY\fP are as follows: |
The update types that replace the \fBY\fP are as follows: |
.IP | .IP |
.RS | .RS |
.IP o | .IP o |
A \fB<\fP means that a file is being transferred to the remote host | A \fB<\fP means that a file is being transferred to the remote host (sent). |
(sent). | .IP o |
.IP o | |
A \fB>\fP means that a file is being transferred to the local host |
A \fB>\fP means that a file is being transferred to the local host |
(received). |
(received). |
.IP o | .IP o |
A \fBc\fP means that a local change/creation is occurring for the item | A \fBc\fP means that a local change/creation is occurring for the item (such |
(such as the creation of a directory or the changing of a symlink, etc.). | as the creation of a directory or the changing of a symlink, etc.). |
.IP o | .IP o |
A \fBh\fP means that the item is a hard link to another item (requires |
A \fBh\fP means that the item is a hard link to another item (requires |
\fB\-\-hard\-links\fP). | \fB\-\-hard-links\fP). |
.IP o | .IP o |
A \fB.\fP means that the item is not being updated (though it might | A \fB.\fP means that the item is not being updated (though it might have |
have attributes that are being modified). | attributes that are being modified). |
.IP o | .IP o |
A \fB*\fP means that the rest of the itemized\-output area contains | A \fB*\fP means that the rest of the itemized-output area contains a message |
a message (e.g. \(dq\&deleting\(dq\&). | (e.g. "deleting"). |
.RE |
.RE |
| .IP |
.IP | The file-types that replace the \fBX\fP are: \fBf\fP for a file, a \fBd\fP for a |
The file\-types that replace the \fBX\fP are: \fBf\fP for a file, a \fBd\fP for a | |
directory, an \fBL\fP for a symlink, a \fBD\fP for a device, and a \fBS\fP for a |
directory, an \fBL\fP for a symlink, a \fBD\fP for a device, and a \fBS\fP for a |
special file (e.g. named sockets and fifos). |
special file (e.g. named sockets and fifos). |
.IP | .IP |
The other letters in the string above are the actual letters that | The other letters in the string indicate if some attributes of the file |
will be output if the associated attribute for the item is being updated or | have changed, as follows: |
a \(dq\&.\(dq\& for no change. Three exceptions to this are: (1) a newly created | .IP |
item replaces each letter with a \(dq\&+\(dq\&, (2) an identical item replaces the | .RS |
dots with spaces, and (3) an unknown attribute replaces each letter with | .IP o |
a \(dq\&?\(dq\& (this can happen when talking to an older rsync). | "\fB.\fP" \- the attribute is unchanged. |
.IP | .IP o |
| "\fB+\fP" \- the file is newly created. |
| .IP o |
| "\fB\ \fP" \- all the attributes are unchanged (all dots turn to spaces). |
| .IP o |
| "\fB?\fP" \- the change is unknown (when the remote rsync is old). |
| .IP o |
| A letter indicates an attribute is being updated. |
| .RE |
| .IP |
The attribute that is associated with each letter is as follows: |
The attribute that is associated with each letter is as follows: |
.IP | .IP |
.RS | .RS |
.IP o | .IP o |
A \fBc\fP means either that a regular file has a different checksum | A \fBc\fP means either that a regular file has a different checksum (requires |
(requires \fB\-\-checksum\fP) or that a symlink, device, or special file has | \fB\-\-checksum\fP) or that a symlink, device, or special file has a changed |
a changed value. | value. Note that if you are sending files to an rsync prior to 3.0.1, |
Note that if you are sending files to an rsync prior to 3.0.1, this | this change flag will be present only for checksum-differing regular |
change flag will be present only for checksum\-differing regular files. | files. |
.IP o | .IP o |
A \fBs\fP means the size of a regular file is different and will be updated |
A \fBs\fP means the size of a regular file is different and will be updated |
by the file transfer. |
by the file transfer. |
.IP o | .IP o |
A \fBt\fP means the modification time is different and is being updated | A \fBt\fP means the modification time is different and is being updated to |
to the sender\(cq\&s value (requires \fB\-\-times\fP). An alternate value of \fBT\fP | the sender's value (requires \fB\-\-times\fP). An alternate value of \fBT\fP means |
means that the modification time will be set to the transfer time, which happens | that the modification time will be set to the transfer time, which |
when a file/symlink/device is updated without \fB\-\-times\fP and when a | happens when a file/symlink/device is updated without \fB\-\-times\fP and when |
symlink is changed and the receiver can\(cq\&t set its time. | a symlink is changed and the receiver can't set its time. (Note: when |
(Note: when using an rsync 3.0.0 client, you might see the \fBs\fP flag combined | using an rsync 3.0.0 client, you might see the \fBs\fP flag combined with \fBt\fP |
with \fBt\fP instead of the proper \fBT\fP flag for this time\-setting failure.) | instead of the proper \fBT\fP flag for this time-setting failure.) |
.IP o | .IP o |
A \fBp\fP means the permissions are different and are being updated to | A \fBp\fP means the permissions are different and are being updated to the |
the sender\(cq\&s value (requires \fB\-\-perms\fP). | sender's value (requires \fB\-\-perms\fP). |
.IP o | .IP o |
An \fBo\fP means the owner is different and is being updated to the | An \fBo\fP means the owner is different and is being updated to the sender's |
sender\(cq\&s value (requires \fB\-\-owner\fP and super\-user privileges). | value (requires \fB\-\-owner\fP and super-user privileges). |
.IP o | .IP o |
A \fBg\fP means the group is different and is being updated to the | A \fBg\fP means the group is different and is being updated to the sender's |
sender\(cq\&s value (requires \fB\-\-group\fP and the authority to set the group). | value (requires \fB\-\-group\fP and the authority to set the group). |
.IP o | .IP o |
The \fBu\fP slot is reserved for future use. | A \fBu\fP|\fBn\fP|\fBb\fP indicates the following information: \fBu\fP means the access |
.IP o | (use) time is different and is being updated to the sender's value |
The \fBa\fP means that the ACL information changed. | (requires \fB\-\-atimes\fP); \fBn\fP means the create time (newness) is different |
.IP o | and is being updated to the sender's value (requires \fB\-\-crtimes\fP); \fBb\fP |
The \fBx\fP means that the extended attribute information changed. | means that both the access and create times are being updated. |
| .IP o |
| The \fBa\fP means that the ACL information is being changed. |
| .IP o |
| The \fBx\fP means that the extended attribute information is being changed. |
.RE |
.RE |
| .IP |
.IP | One other output is possible: when deleting files, the "%i" will output the |
One other output is possible: when deleting files, the \(dq\&%i\(dq\& will output | string "\fB*deleting\fP" for each item that is being removed (assuming that you |
the string \(dq\&*deleting\(dq\& for each item that is being removed (assuming that | are talking to a recent enough rsync that it logs deletions instead of |
you are talking to a recent enough rsync that it logs deletions instead of | |
outputting them as a verbose message). |
outputting them as a verbose message). |
.IP | .IP "\fB\-\-out-format=FORMAT\fP" |
.IP "\fB\-\-out\-format=FORMAT\fP" | This allows you to specify exactly what the rsync client outputs to the |
This allows you to specify exactly what the | user on a per-update basis. The format is a text string containing |
rsync client outputs to the user on a per\-update basis. The format is a | embedded single-character escape sequences prefixed with a percent (%) |
text string containing embedded single\-character escape sequences prefixed | character. A default format of "%n%L" is assumed if either \fB\-\-info=name\fP |
with a percent (%) character. A default format of \(dq\&%n%L\(dq\& is assumed if | or \fB\-v\fP is specified (this tells you just the name of the file and, if the |
either \fB\-\-info=name\fP or \fB\-v\fP is specified (this tells you just the name | item is a link, where it points). For a full list of the possible escape |
of the file and, if the item is a link, where it points). For a full list | characters, see the "\fBlog\ format\fP" setting in the rsyncd.conf manpage. |
of the possible escape characters, see the \(dq\&log format\(dq\& setting in the | .IP |
rsyncd.conf manpage. | Specifying the \fB\-\-out-format\fP option implies the \fB\-\-info=name\fP option, |
.IP | |
Specifying the \fB\-\-out\-format\fP option implies the \fB\-\-info=name\fP option, | |
which will mention each file, dir, etc. that gets updated in a significant |
which will mention each file, dir, etc. that gets updated in a significant |
way (a transferred file, a recreated symlink/device, or a touched |
way (a transferred file, a recreated symlink/device, or a touched |
directory). In addition, if the itemize\-changes escape (%i) is included in | directory). In addition, if the itemize-changes escape (%i) is included in |
the string (e.g. if the \fB\-\-itemize\-changes\fP option was used), the logging | the string (e.g. if the \fB\-\-itemize-changes\fP option was used), the logging |
of names increases to mention any item that is changed in any way (as long |
of names increases to mention any item that is changed in any way (as long |
as the receiving side is at least 2.6.4). See the \fB\-\-itemize\-changes\fP | as the receiving side is at least 2.6.4). See the \fB\-\-itemize-changes\fP |
option for a description of the output of \(dq\&%i\(dq\&. | option for a description of the output of "%i". |
.IP | .IP |
Rsync will output the out\-format string prior to a file\(cq\&s transfer unless | Rsync will output the out-format string prior to a file's transfer unless |
one of the transfer\-statistic escapes is requested, in which case the | one of the transfer-statistic escapes is requested, in which case the |
logging is done at the end of the file\(cq\&s transfer. When this late logging | logging is done at the end of the file's transfer. When this late logging |
is in effect and \fB\-\-progress\fP is also specified, rsync will also output | is in effect and \fB\-\-progress\fP is also specified, rsync will also output the |
the name of the file being transferred prior to its progress information | name of the file being transferred prior to its progress information |
(followed, of course, by the out\-format output). | (followed, of course, by the out-format output). |
.IP | .IP "\fB\-\-log-file=FILE\fP" |
.IP "\fB\-\-log\-file=FILE\fP" | This option causes rsync to log what it is doing to a file. This is |
This option causes rsync to log what it is doing | similar to the logging that a daemon does, but can be requested for the |
to a file. This is similar to the logging that a daemon does, but can be | client side and/or the server side of a non-daemon transfer. If specified |
requested for the client side and/or the server side of a non\-daemon | as a client option, transfer logging will be enabled with a default format |
transfer. If specified as a client option, transfer logging will be | of "%i %n%L". See the \fB\-\-log-file-format\fP option if you wish to override |
enabled with a default format of \(dq\&%i %n%L\(dq\&. See the \fB\-\-log\-file\-format\fP | this. |
option if you wish to override this. | .IP |
.IP | Here's a example command that requests the remote side to log what is |
Here\(cq\&s a example command that requests the remote side to log what is | |
happening: |
happening: |
.IP | .RS 4 |
.nf | .IP |
rsync \-av \-\-remote\-option=\-\-log\-file=/tmp/rlog src/ dest/ | .nf |
.fi | rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/ |
| .fi |
.IP | .RE |
| .IP |
This is very useful if you need to debug why a connection is closing |
This is very useful if you need to debug why a connection is closing |
unexpectedly. |
unexpectedly. |
.IP | .IP "\fB\-\-log-file-format=FORMAT\fP" |
.IP "\fB\-\-log\-file\-format=FORMAT\fP" | This allows you to specify exactly what per-update logging is put into the |
This allows you to specify exactly what | file specified by the \fB\-\-log-file\fP option (which must also be specified for |
per\-update logging is put into the file specified by the \fB\-\-log\-file\fP option | this option to have any effect). If you specify an empty string, updated |
(which must also be specified for this option to have any effect). If you | files will not be mentioned in the log file. For a list of the possible |
specify an empty string, updated files will not be mentioned in the log file. | escape characters, see the "\fBlog\ format\fP" setting in the rsyncd.conf manpage. |
For a list of the possible escape characters, see the \(dq\&log format\(dq\& setting | .IP |
in the rsyncd.conf manpage. | The default FORMAT used if \fB\-\-log-file\fP is specified and this option is not |
.IP | is '%i %n%L'. |
The default FORMAT used if \fB\-\-log\-file\fP is specified and this option is not | |
is \(cq\&%i %n%L\(cq\&. | |
.IP | |
.IP "\fB\-\-stats\fP" |
.IP "\fB\-\-stats\fP" |
This tells rsync to print a verbose set of statistics | This tells rsync to print a verbose set of statistics on the file transfer, |
on the file transfer, allowing you to tell how effective rsync\(cq\&s delta\-transfer | allowing you to tell how effective rsync's delta-transfer algorithm is for |
algorithm is for your data. This option is equivalent to \fB\-\-info=stats2\fP | your data. This option is equivalent to \fB\-\-info=stats2\fP if combined with 0 |
if combined with 0 or 1 \fB\-v\fP options, or \fB\-\-info=stats3\fP if combined | or 1 \fB\-v\fP options, or \fB\-\-info=stats3\fP if combined with 2 or more \fB\-v\fP |
with 2 or more \fB\-v\fP options. | options. |
.IP | .IP |
The current statistics are as follows: | The current statistics are as follows: |
.RS | .IP |
.IP o | .RS |
\fBNumber of files\fP is the count of all \(dq\&files\(dq\& (in the generic | .IP o |
sense), which includes directories, symlinks, etc. The total count will | \fBNumber\ of\ files\fP is the count of all "files" (in the generic sense), |
be followed by a list of counts by filetype (if the total is non\-zero). | which includes directories, symlinks, etc. The total count will be |
For example: \(dq\&(reg: 5, dir: 3, link: 2, dev: 1, special: 1)\(dq\& lists the | followed by a list of counts by filetype (if the total is non-zero). For |
totals for regular files, directories, symlinks, devices, and special | example: "(reg: 5, dir: 3, link: 2, dev: 1, special: 1)" lists the totals |
files. If any of value is 0, it is completely omitted from the list. | for regular files, directories, symlinks, devices, and special files. If |
.IP o | any of value is 0, it is completely omitted from the list. |
\fBNumber of created files\fP is the count of how many \(dq\&files\(dq\& (generic | .IP o |
| \fBNumber\ of\ created\ files\fP is the count of how many "files" (generic |
sense) were created (as opposed to updated). The total count will be |
sense) were created (as opposed to updated). The total count will be |
followed by a list of counts by filetype (if the total is non\-zero). | followed by a list of counts by filetype (if the total is non-zero). |
.IP o | .IP o |
\fBNumber of deleted files\fP is the count of how many \(dq\&files\(dq\& (generic | \fBNumber\ of\ deleted\ files\fP is the count of how many "files" (generic |
sense) were created (as opposed to updated). The total count will be |
sense) were created (as opposed to updated). The total count will be |
followed by a list of counts by filetype (if the total is non\-zero). | followed by a list of counts by filetype (if the total is non-zero). |
Note that this line is only output if deletions are in effect, and only |
Note that this line is only output if deletions are in effect, and only |
if protocol 31 is being used (the default for rsync 3.1.x). |
if protocol 31 is being used (the default for rsync 3.1.x). |
.IP o | .IP o |
\fBNumber of regular files transferred\fP is the count of normal files | \fBNumber\ of\ regular\ files\ transferred\fP is the count of normal files that |
that were updated via rsync\(cq\&s delta\-transfer algorithm, which does not | were updated via rsync's delta-transfer algorithm, which does not include |
include dirs, symlinks, etc. Note that rsync 3.1.0 added the word | dirs, symlinks, etc. Note that rsync 3.1.0 added the word "regular" into |
\(dq\®ular\(dq\& into this heading. | this heading. |
.IP o | .IP o |
\fBTotal file size\fP is the total sum of all file sizes in the transfer. | \fBTotal\ file\ size\fP is the total sum of all file sizes in the transfer. |
This does not count any size for directories or special files, but does |
This does not count any size for directories or special files, but does |
include the size of symlinks. |
include the size of symlinks. |
.IP o | .IP o |
\fBTotal transferred file size\fP is the total sum of all files sizes | \fBTotal\ transferred\ file\ size\fP is the total sum of all files sizes for |
for just the transferred files. | just the transferred files. |
.IP o | .IP o |
\fBLiteral data\fP is how much unmatched file\-update data we had to | \fBLiteral\ data\fP is how much unmatched file-update data we had to send to |
send to the receiver for it to recreate the updated files. | the receiver for it to recreate the updated files. |
.IP o | .IP o |
\fBMatched data\fP is how much data the receiver got locally when | \fBMatched\ data\fP is how much data the receiver got locally when recreating |
recreating the updated files. | the updated files. |
.IP o | .IP o |
\fBFile list size\fP is how big the file\-list data was when the sender | \fBFile\ list\ size\fP is how big the file-list data was when the sender sent |
sent it to the receiver. This is smaller than the in\-memory size for the | it to the receiver. This is smaller than the in-memory size for the file |
file list due to some compressing of duplicated data when rsync sends the | list due to some compressing of duplicated data when rsync sends the |
list. |
list. |
.IP o | .IP o |
\fBFile list generation time\fP is the number of seconds that the | \fBFile\ list\ generation\ time\fP is the number of seconds that the sender |
sender spent creating the file list. This requires a modern rsync on the | spent creating the file list. This requires a modern rsync on the |
sending side for this to be present. |
sending side for this to be present. |
.IP o | .IP o |
\fBFile list transfer time\fP is the number of seconds that the sender | \fBFile\ list\ transfer\ time\fP is the number of seconds that the sender spent |
spent sending the file list to the receiver. | sending the file list to the receiver. |
.IP o | .IP o |
\fBTotal bytes sent\fP is the count of all the bytes that rsync sent | \fBTotal\ bytes\ sent\fP is the count of all the bytes that rsync sent from the |
from the client side to the server side. | client side to the server side. |
.IP o | .IP o |
\fBTotal bytes received\fP is the count of all non\-message bytes that | \fBTotal\ bytes\ received\fP is the count of all non-message bytes that rsync |
rsync received by the client side from the server side. \(dq\&Non\-message\(dq\& | received by the client side from the server side. "Non-message" bytes |
bytes means that we don\(cq\&t count the bytes for a verbose message that the | means that we don't count the bytes for a verbose message that the server |
server sent to us, which makes the stats more consistent. | sent to us, which makes the stats more consistent. |
.RE |
.RE |
| .IP "\fB\-\-8-bit-output\fP, \fB\-8\fP" |
.IP | This tells rsync to leave all high-bit characters unescaped in the output |
.IP "\fB\-8, \-\-8\-bit\-output\fP" | instead of trying to test them to see if they're valid in the current |
This tells rsync to leave all high\-bit characters | locale and escaping the invalid ones. All control characters (but never |
unescaped in the output instead of trying to test them to see if they\(cq\&re | tabs) are always escaped, regardless of this option's setting. |
valid in the current locale and escaping the invalid ones. All control | .IP |
characters (but never tabs) are always escaped, regardless of this option\(cq\&s | The escape idiom that started in 2.6.7 is to output a literal backslash |
setting. | (\fB\\\fP) and a hash (\fB#\fP), followed by exactly 3 octal digits. For example, a |
.IP | newline would output as "\fB\\#012\fP". A literal backslash that is in a |
The escape idiom that started in 2.6.7 is to output a literal backslash (\e) | filename is not escaped unless it is followed by a hash and 3 digits (0-9). |
and a hash (#), followed by exactly 3 octal digits. For example, a newline | .IP "\fB\-\-human-readable\fP, \fB\-h\fP" |
would output as \(dq\&\e#012\(dq\&. A literal backslash that is in a filename is not | Output numbers in a more human-readable format. There are 3 possible |
escaped unless it is followed by a hash and 3 digits (0\-9). | levels: (1) output numbers with a separator between each set of 3 digits |
.IP | (either a comma or a period, depending on if the decimal point is |
.IP "\fB\-h, \-\-human\-readable\fP" | represented by a period or a comma); (2) output numbers in units of 1000 |
Output numbers in a more human\-readable format. | (with a character suffix for larger units\ \-\- see below); (3) output |
There are 3 possible levels: (1) output numbers with a separator between each | numbers in units of 1024. |
set of 3 digits (either a comma or a period, depending on if the decimal point | .IP |
is represented by a period or a comma); (2) output numbers in units of 1000 | The default is human-readable level 1. Each \fB\-h\fP option increases the |
(with a character suffix for larger units \-\- see below); (3) output numbers in | level by one. You can take the level down to 0 (to output numbers as pure |
units of 1024. | digits) by specifying the \fB\-\-no-human-readable\fP (\fB\-\-no-h\fP) option. |
.IP | .IP |
The default is human\-readable level 1. Each \fB\-h\fP option increases the level | The unit letters that are appended in levels 2 and 3 are: \fBK\fP (kilo), \fBM\fP |
by one. You can take the level down to 0 (to output numbers as pure digits) by | (mega), \fBG\fP (giga), \fBT\fP (tera), or \fBP\fP (peta). For example, a 1234567-byte |
specifing the \fB\-\-no\-human\-readable\fP (\fB\-\-no\-h\fP) option. | file would output as 1.23M in level-2 (assuming that a period is your local |
.IP | decimal point). |
The unit letters that are appended in levels 2 and 3 are: K (kilo), M (mega), | .IP |
G (giga), or T (tera). For example, a 1234567\-byte file would output as 1.23M | Backward compatibility note: versions of rsync prior to 3.1.0 do not |
in level\-2 (assuming that a period is your local decimal point). | support human-readable level 1, and they default to level 0. Thus, |
.IP | specifying one or two \fB\-h\fP options will behave in a comparable manner in |
Backward compatibility note: versions of rsync prior to 3.1.0 do not support | old and new versions as long as you didn't specify a \fB\-\-no-h\fP option prior |
human\-readable level 1, and they default to level 0. Thus, specifying one or | to one or more \fB\-h\fP options. See the \fB\-\-list-only\fP option for one |
two \fB\-h\fP options will behave in a comparable manner in old and new versions | difference. |
as long as you didn\(cq\&t specify a \fB\-\-no\-h\fP option prior to one or more \fB\-h\fP | |
options. See the \fB\-\-list\-only\fP option for one difference. | |
.IP | |
.IP "\fB\-\-partial\fP" |
.IP "\fB\-\-partial\fP" |
By default, rsync will delete any partially | By default, rsync will delete any partially transferred file if the |
transferred file if the transfer is interrupted. In some circumstances | transfer is interrupted. In some circumstances it is more desirable to |
it is more desirable to keep partially transferred files. Using the | keep partially transferred files. Using the \fB\-\-partial\fP option tells rsync |
\fB\-\-partial\fP option tells rsync to keep the partial file which should | to keep the partial file which should make a subsequent transfer of the |
make a subsequent transfer of the rest of the file much faster. | rest of the file much faster. |
.IP | .IP "\fB\-\-partial-dir=DIR\fP" |
.IP "\fB\-\-partial\-dir=DIR\fP" | A better way to keep partial files than the \fB\-\-partial\fP option is to |
A better way to keep partial files than the | specify a \fIDIR\fP that will be used to hold the partial data (instead of |
\fB\-\-partial\fP option is to specify a \fIDIR\fP that will be used to hold the | writing it out to the destination file). On the next transfer, rsync will |
partial data (instead of writing it out to the destination file). | use a file found in this dir as data to speed up the resumption of the |
On the next transfer, rsync will use a file found in this | transfer and then delete it after it has served its purpose. |
dir as data to speed up the resumption of the transfer and then delete it | .IP |
after it has served its purpose. | Note that if \fB\-\-whole-file\fP is specified (or implied), any partial-dir file |
.IP | that is found for a file that is being updated will simply be removed |
Note that if \fB\-\-whole\-file\fP is specified (or implied), any partial\-dir | (since rsync is sending files without using rsync's delta-transfer |
file that is found for a file that is being updated will simply be removed | algorithm). |
(since | .IP |
rsync is sending files without using rsync\(cq\&s delta\-transfer algorithm). | Rsync will create the \fIDIR\fP if it is missing (just the last dir\ \-\- not the |
.IP | whole path). This makes it easy to use a relative path (such as |
Rsync will create the \fIDIR\fP if it is missing (just the last dir \-\- not | "\fB\-\-partial-dir=.rsync-partial\fP") to have rsync create the |
the whole path). This makes it easy to use a relative path (such as | partial-directory in the destination file's directory when needed, and then |
\(dq\&\fB\-\-partial\-dir=.rsync\-partial\fP\(dq\&) to have rsync create the | remove it again when the partial file is deleted. Note that the directory |
partial\-directory in the destination file\(cq\&s directory when needed, and then | is only removed if it is a relative pathname, as it is expected that an |
remove it again when the partial file is deleted. | absolute path is to a directory that is reserved for partial-dir work. |
.IP | .IP |
If the partial\-dir value is not an absolute path, rsync will add an exclude | If the partial-dir value is not an absolute path, rsync will add an exclude |
rule at the end of all your existing excludes. This will prevent the |
rule at the end of all your existing excludes. This will prevent the |
sending of any partial\-dir files that may exist on the sending side, and | sending of any partial-dir files that may exist on the sending side, and |
will also prevent the untimely deletion of partial\-dir items on the | will also prevent the untimely deletion of partial-dir items on the |
receiving side. An example: the above \fB\-\-partial\-dir\fP option would add | receiving side. An example: the above \fB\-\-partial-dir\fP option would add the |
the equivalent of \(dq\&\fB\-f '\&\-p .rsync\-partial/'\&\fP\(dq\& at the end of any other | equivalent of "\fB\-f\ '\-p\ .rsync-partial/'\fP" at the end of any other filter |
filter rules. | rules. |
.IP | .IP |
If you are supplying your own exclude rules, you may need to add your own |
If you are supplying your own exclude rules, you may need to add your own |
exclude/hide/protect rule for the partial\-dir because (1) the auto\-added | exclude/hide/protect rule for the partial-dir because (1) the auto-added |
rule may be ineffective at the end of your other rules, or (2) you may wish |
rule may be ineffective at the end of your other rules, or (2) you may wish |
to override rsync\(cq\&s exclude choice. For instance, if you want to make | to override rsync's exclude choice. For instance, if you want to make |
rsync clean\-up any left\-over partial\-dirs that may be lying around, you | rsync clean-up any left-over partial-dirs that may be lying around, you |
should specify \fB\-\-delete\-after\fP and add a \(dq\&risk\(dq\& filter rule, e.g. | should specify \fB\-\-delete-after\fP and add a "risk" filter rule, e.g. |
\fB\-f '\&R .rsync\-partial/'\&\fP. (Avoid using \fB\-\-delete\-before\fP or | \fB\-f\ 'R\ .rsync-partial/'\fP. (Avoid using \fB\-\-delete-before\fP or |
\fB\-\-delete\-during\fP unless you don\(cq\&t need rsync to use any of the | \fB\-\-delete-during\fP unless you don't need rsync to use any of the left-over |
left\-over partial\-dir data during the current run.) | partial-dir data during the current run.) |
.IP | .IP |
IMPORTANT: the \fB\-\-partial\-dir\fP should not be writable by other users or it | IMPORTANT: the \fB\-\-partial-dir\fP should not be writable by other users or it |
is a security risk. E.g. AVOID \(dq\&/tmp\(dq\&. | is a security risk. E.g. AVOID "/tmp". |
.IP | .IP |
You can also set the partial\-dir value the RSYNC_PARTIAL_DIR environment | You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment |
variable. Setting this in the environment does not force \fB\-\-partial\fP to be |
variable. Setting this in the environment does not force \fB\-\-partial\fP to be |
enabled, but rather it affects where partial files go when \fB\-\-partial\fP is |
enabled, but rather it affects where partial files go when \fB\-\-partial\fP is |
specified. For instance, instead of using \fB\-\-partial\-dir=.rsync\-tmp\fP | specified. For instance, instead of using \fB\-\-partial-dir=.rsync-tmp\fP along |
along with \fB\-\-progress\fP, you could set RSYNC_PARTIAL_DIR=.rsync\-tmp in your | with \fB\-\-progress\fP, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your |
environment and then just use the \fB\-P\fP option to turn on the use of the |
environment and then just use the \fB\-P\fP option to turn on the use of the |
\&.rsync\-tmp dir for partial transfers. The only times that the \fB\-\-partial\fP | \&.rsync-tmp dir for partial transfers. The only times that the \fB\-\-partial\fP |
option does not look for this environment value are (1) when \fB\-\-inplace\fP was | option does not look for this environment value are (1) when \fB\-\-inplace\fP |
specified (since \fB\-\-inplace\fP conflicts with \fB\-\-partial\-dir\fP), and (2) when | was specified (since \fB\-\-inplace\fP conflicts with \fB\-\-partial-dir\fP), and (2) |
\fB\-\-delay\-updates\fP was specified (see below). | when \fB\-\-delay-updates\fP was specified (see below). |
.IP | .IP |
For the purposes of the daemon\-config\(cq\&s \(dq\&refuse options\(dq\& setting, | When a modern rsync resumes the transfer of a file in the partial-dir, that |
\fB\-\-partial\-dir\fP does \fInot\fP imply \fB\-\-partial\fP. This is so that a | partial file is now updated in-place instead of creating yet another |
refusal of the \fB\-\-partial\fP option can be used to disallow the overwriting | tmp-file copy (so it maxes out at dest + tmp instead of dest + partial + |
of destination files with a partial transfer, while still allowing the | tmp). This requires both ends of the transfer to be at least version |
safer idiom provided by \fB\-\-partial\-dir\fP. | 3.2.0. |
.IP | .IP |
.IP "\fB\-\-delay\-updates\fP" | For the purposes of the daemon-config's "\fBrefuse\ options\fP" setting, |
This option puts the temporary file from each | \fB\-\-partial-dir\fP does \fInot\fP imply \fB\-\-partial\fP. This is so that a refusal of |
updated file into a holding directory until the end of the | the \fB\-\-partial\fP option can be used to disallow the overwriting of |
transfer, at which time all the files are renamed into place in rapid | destination files with a partial transfer, while still allowing the safer |
succession. This attempts to make the updating of the files a little more | idiom provided by \fB\-\-partial-dir\fP. |
atomic. By default the files are placed into a directory named \(dq\&.~tmp~\(dq\& in | .IP "\fB\-\-delay-updates\fP" |
each file\(cq\&s destination directory, but if you\(cq\&ve specified the | This option puts the temporary file from each updated file into a holding |
\fB\-\-partial\-dir\fP option, that directory will be used instead. See the | directory until the end of the transfer, at which time all the files are |
comments in the \fB\-\-partial\-dir\fP section for a discussion of how this | renamed into place in rapid succession. This attempts to make the updating |
\(dq\&.~tmp~\(dq\& dir will be excluded from the transfer, and what you can do if | of the files a little more atomic. By default the files are placed into a |
you want rsync to cleanup old \(dq\&.~tmp~\(dq\& dirs that might be lying around. | directory named \fB.~tmp~\fP in each file's destination directory, but if |
Conflicts with \fB\-\-inplace\fP and \fB\-\-append\fP. | you've specified the \fB\-\-partial-dir\fP option, that directory will be used |
.IP | instead. See the comments in the \fB\-\-partial-dir\fP section for a discussion |
| of how this \fB.~tmp~\fP dir will be excluded from the transfer, and what you |
| can do if you want rsync to cleanup old \fB.~tmp~\fP dirs that might be lying |
| around. Conflicts with \fB\-\-inplace\fP and \fB\-\-append\fP. |
| .IP |
| This option implies \fB\-\-no-inc-recursive\fP since it needs the full file list |
| in memory in order to be able to iterate over it at the end. |
| .IP |
This option uses more memory on the receiving side (one bit per file |
This option uses more memory on the receiving side (one bit per file |
transferred) and also requires enough free disk space on the receiving | transferred) and also requires enough free disk space on the receiving side |
side to hold an additional copy of all the updated files. Note also that | to hold an additional copy of all the updated files. Note also that you |
you should not use an absolute path to \fB\-\-partial\-dir\fP unless (1) | should not use an absolute path to \fB\-\-partial-dir\fP unless (1) there is no |
there is no | |
chance of any of the files in the transfer having the same name (since all |
chance of any of the files in the transfer having the same name (since all |
the updated files will be put into a single directory if the path is |
the updated files will be put into a single directory if the path is |
absolute) | absolute) and (2) there are no mount points in the hierarchy (since the |
and (2) there are no mount points in the hierarchy (since the | delayed updates will fail if they can't be renamed into place). |
delayed updates will fail if they can\(cq\&t be renamed into place). | .IP |
.IP | See also the "atomic-rsync" perl script in the "support" subdir for an |
See also the \(dq\&atomic\-rsync\(dq\& perl script in the \(dq\&support\(dq\& subdir for an | update algorithm that is even more atomic (it uses \fB\-\-link-dest\fP and a |
update algorithm that is even more atomic (it uses \fB\-\-link\-dest\fP and a | |
parallel hierarchy of files). |
parallel hierarchy of files). |
.IP | .IP "\fB\-\-direct-io\fP" |
.IP "\fB\-m, \-\-prune\-empty\-dirs\fP" | This option opens files with a direct-I/O flag that makes the file I/O |
This option tells the receiving rsync to get | avoid the buffer cache. The option only affects one side of the transfer |
rid of empty directories from the file\-list, including nested directories | (unless the transfer is local). If you want it to affect both sides, use |
that have no non\-directory children. This is useful for avoiding the | the \fB\-\-remote-option\fP (\fB\-M\fP) option to specify it for the remote side. For |
creation of a bunch of useless directories when the sending rsync is | instance, this specifies it for both sides: |
recursively scanning a hierarchy of files using include/exclude/filter | .RS 4 |
rules. | .IP |
.IP | .nf |
Note that the use of transfer rules, such as the \fB\-\-min\-size\fP option, does | rsync -av {,-M}--direct-io /src/ host:/dest/ |
not affect what goes into the file list, and thus does not leave directories | .fi |
empty, even if none of the files in a directory match the transfer rule. | .RE |
.IP | .IP "\fB\-\-prune-empty-dirs\fP, \fB\-m\fP" |
Because the file\-list is actually being pruned, this option also affects | This option tells the receiving rsync to get rid of empty directories from |
| the file-list, including nested directories that have no non-directory |
| children. This is useful for avoiding the creation of a bunch of useless |
| directories when the sending rsync is recursively scanning a hierarchy of |
| files using include/exclude/filter rules. |
| .IP |
| Note that the use of transfer rules, such as the \fB\-\-min-size\fP option, does |
| not affect what goes into the file list, and thus does not leave |
| directories empty, even if none of the files in a directory match the |
| transfer rule. |
| .IP |
| Because the file-list is actually being pruned, this option also affects |
what directories get deleted when a delete is active. However, keep in |
what directories get deleted when a delete is active. However, keep in |
mind that excluded files and directories can prevent existing items from |
mind that excluded files and directories can prevent existing items from |
being deleted due to an exclude both hiding source files and protecting |
being deleted due to an exclude both hiding source files and protecting |
destination files. See the perishable filter\-rule option for how to avoid | destination files. See the perishable filter-rule option for how to avoid |
this. |
this. |
.IP | .IP |
You can prevent the pruning of certain empty directories from the file\-list | You can prevent the pruning of certain empty directories from the file-list |
by using a global \(dq\&protect\(dq\& filter. For instance, this option would ensure | by using a global "protect" filter. For instance, this option would ensure |
that the directory \(dq\&emptydir\(dq\& was kept in the file\-list: | that the directory "emptydir" was kept in the file-list: |
.IP | .RS 4 |
.RS | .IP |
\-\-filter \(cq\&protect emptydir/\(cq\& | .nf |
| --filter 'protect emptydir/' |
| .fi |
.RE |
.RE |
| .IP |
.IP | Here's an example that copies all .pdf files in a hierarchy, only creating |
Here\(cq\&s an example that copies all .pdf files in a hierarchy, only creating | |
the necessary destination directories to hold the .pdf files, and ensures |
the necessary destination directories to hold the .pdf files, and ensures |
that any superfluous files and directories in the destination are removed |
that any superfluous files and directories in the destination are removed |
(note the hide filter of non\-directories being used instead of an exclude): | (note the hide filter of non-directories being used instead of an exclude): |
.IP | .RS 4 |
.RS | .IP |
rsync \-avm \-\-del \-\-include=\(cq\&*.pdf\(cq\& \-f \(cq\&hide,! */\(cq\& src/ dest | .nf |
| rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest |
| .fi |
.RE |
.RE |
| .IP |
.IP | If you didn't want to remove superfluous destination files, the more |
If you didn\(cq\&t want to remove superfluous destination files, the more | time-honored options of \fB\-\-include='*/'\ \-\-exclude='*'\fP would work |
time\-honored options of \(dq\&\fB\-\-include='\&*/'\& \-\-exclude='\&*'\&\fP\(dq\& would work fine | fine in place of the hide-filter (if that is more natural to you). |
in place of the hide\-filter (if that is more natural to you). | |
.IP | |
.IP "\fB\-\-progress\fP" |
.IP "\fB\-\-progress\fP" |
This option tells rsync to print information | This option tells rsync to print information showing the progress of the |
showing the progress of the transfer. This gives a bored user | transfer. This gives a bored user something to watch. With a modern rsync |
something to watch. | this is the same as specifying \fB\-\-info=flist2,name,progress\fP, but any |
With a modern rsync this is the same as specifying | user-supplied settings for those info flags takes precedence (e.g. |
\fB\-\-info=flist2,name,progress\fP, but any user\-supplied settings for those | "\fB\-\-info=flist0\ \-\-progress\fP"). |
info flags takes precedence (e.g. \(dq\&\-\-info=flist0 \-\-progress\(dq\&). | .IP |
.IP | |
While rsync is transferring a regular file, it updates a progress line that |
While rsync is transferring a regular file, it updates a progress line that |
looks like this: |
looks like this: |
.IP | .RS 4 |
.nf | .IP |
782448 63% 110.64kB/s 0:00:04 | .nf |
.fi | 782448 63% 110.64kB/s 0:00:04 |
| .fi |
.IP | .RE |
| .IP |
In this example, the receiver has reconstructed 782448 bytes or 63% of the |
In this example, the receiver has reconstructed 782448 bytes or 63% of the |
sender\(cq\&s file, which is being reconstructed at a rate of 110.64 kilobytes | sender's file, which is being reconstructed at a rate of 110.64 kilobytes |
per second, and the transfer will finish in 4 seconds if the current rate |
per second, and the transfer will finish in 4 seconds if the current rate |
is maintained until the end. |
is maintained until the end. |
.IP | .IP |
These statistics can be misleading if rsync\(cq\&s delta\-transfer algorithm is | These statistics can be misleading if rsync's delta-transfer algorithm is |
in use. For example, if the sender\(cq\&s file consists of the basis file | in use. For example, if the sender's file consists of the basis file |
followed by additional data, the reported rate will probably drop |
followed by additional data, the reported rate will probably drop |
dramatically when the receiver gets to the literal data, and the transfer |
dramatically when the receiver gets to the literal data, and the transfer |
will probably take much longer to finish than the receiver estimated as it |
will probably take much longer to finish than the receiver estimated as it |
was finishing the matched part of the file. |
was finishing the matched part of the file. |
.IP | .IP |
When the file transfer finishes, rsync replaces the progress line with a |
When the file transfer finishes, rsync replaces the progress line with a |
summary line that looks like this: |
summary line that looks like this: |
.IP | .RS 4 |
.nf | .IP |
1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to\-chk=169/396) | .nf |
.fi | 1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396) |
| .fi |
.IP | .RE |
In this example, the file was 1,238,099 bytes long in total, the average rate | .IP |
of transfer for the whole file was 146.38 kilobytes per second over the 8 | In this example, the file was 1,238,099 bytes long in total, the average |
seconds that it took to complete, it was the 5th transfer of a regular file | rate of transfer for the whole file was 146.38 kilobytes per second over |
during the current rsync session, and there are 169 more files for the | the 8 seconds that it took to complete, it was the 5th transfer of a |
receiver to check (to see if they are up\-to\-date or not) remaining out of | regular file during the current rsync session, and there are 169 more files |
the 396 total files in the file\-list. | for the receiver to check (to see if they are up-to-date or not) remaining |
.IP | out of the 396 total files in the file-list. |
In an incremental recursion scan, rsync won\(cq\&t know the total number of files | .IP |
in the file\-list until it reaches the ends of the scan, but since it starts to | In an incremental recursion scan, rsync won't know the total number of |
transfer files during the scan, it will display a line with the text \(dq\&ir\-chk\(dq\& | files in the file-list until it reaches the ends of the scan, but since it |
(for incremental recursion check) instead of \(dq\&to\-chk\(dq\& until the point that it | starts to transfer files during the scan, it will display a line with the |
knows the full size of the list, at which point it will switch to using | text "ir-chk" (for incremental recursion check) instead of "to-chk" until |
\(dq\&to\-chk\(dq\&. Thus, seeing \(dq\&ir\-chk\(dq\& lets you know that the total count of files | the point that it knows the full size of the list, at which point it will |
in the file list is still going to increase (and each time it does, the count | switch to using "to-chk". Thus, seeing "ir-chk" lets you know that the |
of files left to check will increase by the number of the files added to the | total count of files in the file list is still going to increase (and each |
list). | time it does, the count of files left to check will increase by the number |
.IP | of the files added to the list). |
.IP "\fB\-P\fP" |
.IP "\fB\-P\fP" |
The \fB\-P\fP option is equivalent to \fB\-\-partial\fP \fB\-\-progress\fP. Its | The \fB\-P\fP option is equivalent to \fB\-\-partial\ \-\-progress\fP. Its purpose is |
purpose is to make it much easier to specify these two options for a long | to make it much easier to specify these two options for a long transfer |
transfer that may be interrupted. | that may be interrupted. |
.IP | .IP |
There is also a \fB\-\-info=progress2\fP option that outputs statistics based | There is also a \fB\-\-info=progress2\fP option that outputs statistics based on |
on the whole transfer, rather than individual files. Use this flag without | the whole transfer, rather than individual files. Use this flag without |
outputting a filename (e.g. avoid \fB\-v\fP or specify \fB\-\-info=name0\fP) if you |
outputting a filename (e.g. avoid \fB\-v\fP or specify \fB\-\-info=name0\fP) if you |
want to see how the transfer is doing without scrolling the screen with a |
want to see how the transfer is doing without scrolling the screen with a |
lot of names. (You don\(cq\&t need to specify the \fB\-\-progress\fP option in | lot of names. (You don't need to specify the \fB\-\-progress\fP option in order |
order to use \fB\-\-info=progress2\fP.) | to use \fB\-\-info=progress2\fP.) |
.IP | .IP |
.IP "\fB\-\-password\-file=FILE\fP" | Finally, you can get an instant progress report by sending rsync a signal |
This option allows you to provide a password for | of either SIGINFO or SIGVTALRM. On BSD systems, a SIGINFO is generated by |
accessing an rsync daemon via a file or via standard input if \fBFILE\fP is | typing a Ctrl+T (Linux doesn't currently support a SIGINFO signal). When |
\fB\-\fP. The file should contain just the password on the first line (all other | the client-side process receives one of those signals, it sets a flag to |
lines are ignored). Rsync will exit with an error if \fBFILE\fP is world | output a single progress report which is output when the current file |
readable or if a root\-run rsync command finds a non\-root\-owned file. | transfer finishes (so it may take a little time if a big file is being |
.IP | handled when the signal arrives). A filename is output (if needed) |
| followed by the \fB\-\-info=progress2\fP format of progress info. If you don't |
| know which of the 3 rsync processes is the client process, it's OK to |
| signal all of them (since the non-client processes ignore the signal). |
| .IP |
| CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it. |
| .IP "\fB\-\-password-file=FILE\fP" |
| This option allows you to provide a password for accessing an rsync daemon |
| via a file or via standard input if \fBFILE\fP is \fB\-\fP. The file should |
| contain just the password on the first line (all other lines are ignored). |
| Rsync will exit with an error if \fBFILE\fP is world readable or if a |
| root-run rsync command finds a non-root-owned file. |
| .IP |
This option does not supply a password to a remote shell transport such as |
This option does not supply a password to a remote shell transport such as |
ssh; to learn how to do that, consult the remote shell\(cq\&s documentation. | ssh; to learn how to do that, consult the remote shell's documentation. |
When accessing an rsync daemon using a remote shell as the transport, this |
When accessing an rsync daemon using a remote shell as the transport, this |
option only comes into effect after the remote shell finishes its |
option only comes into effect after the remote shell finishes its |
authentication (i.e. if you have also specified a password in the daemon\(cq\&s | authentication (i.e. if you have also specified a password in the daemon's |
config file). |
config file). |
.IP | .IP "\fB\-\-early-input=FILE\fP" |
.IP "\fB\-\-list\-only\fP" | This option allows rsync to send up to 5K of data to the "early exec" |
This option will cause the source files to be listed | script on its stdin. One possible use of this data is to give the script a |
instead of transferred. This option is inferred if there is a single source | secret that can be used to mount an encrypted filesystem (which you should |
arg and no destination specified, so its main uses are: (1) to turn a copy | unmount in the the "post-xfer exec" script). |
command that includes a | .IP |
destination arg into a file\-listing command, or (2) to be able to specify | The daemon must be at least version 3.2.1. |
more than one source arg (note: be sure to include the destination). | .IP "\fB\-\-list-only\fP" |
Caution: keep in mind that a source arg with a wild\-card is expanded by the | This option will cause the source files to be listed instead of |
shell into multiple args, so it is never safe to try to list such an arg | transferred. This option is inferred if there is a single source arg and |
without using this option. For example: | no destination specified, so its main uses are: (1) to turn a copy command |
.IP | that includes a destination arg into a file-listing command, or (2) to be |
.nf | able to specify more than one source arg (note: be sure to include the |
rsync \-av \-\-list\-only foo* dest/ | destination). Caution: keep in mind that a source arg with a wild-card is |
.fi | expanded by the shell into multiple args, so it is never safe to try to |
| list such an arg without using this option. For example: |
.IP | .RS 4 |
Starting with rsync 3.1.0, the sizes output by \fB\-\-list\-only\fP are affected | .IP |
by the \fB\-\-human\-readable\fP option. By default they will contain digit | .nf |
| rsync -av --list-only foo* dest/ |
| .fi |
| .RE |
| .IP |
| Starting with rsync 3.1.0, the sizes output by \fB\-\-list-only\fP are affected |
| by the \fB\-\-human-readable\fP option. By default they will contain digit |
separators, but higher levels of readability will output the sizes with |
separators, but higher levels of readability will output the sizes with |
unit suffixes. Note also that the column width for the size output has |
unit suffixes. Note also that the column width for the size output has |
increased from 11 to 14 characters for all human\-readable levels. Use | increased from 11 to 14 characters for all human-readable levels. Use |
\fB\-\-no\-h\fP if you want just digits in the sizes, and the old column width | \fB\-\-no-h\fP if you want just digits in the sizes, and the old column width of |
of 11 characters. | 11 characters. |
.IP | .IP |
Compatibility note: when requesting a remote listing of files from an rsync | 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 |
that is version 2.6.3 or older, you may encounter an error if you ask for a |
non\-recursive listing. This is because a file listing implies the \fB\-\-dirs\fP | non-recursive listing. This is because a file listing implies the \fB\-\-dirs\fP |
option w/o \fB\-\-recursive\fP, and older rsyncs don\(cq\&t have that option. To | option w/o \fB\-\-recursive\fP, and older rsyncs don't have that option. To |
avoid this problem, either specify the \fB\-\-no\-dirs\fP option (if you don\(cq\&t | avoid this problem, either specify the \fB\-\-no-dirs\fP option (if you don't |
need to expand a directory\(cq\&s content), or turn on recursion and exclude | need to expand a directory's content), or turn on recursion and exclude the |
the content of subdirectories: \fB\-r \-\-exclude='\&/*/*'\&\fP. | content of subdirectories: \fB\-r\ \-\-exclude='/*/*'\fP. |
.IP | |
.IP "\fB\-\-bwlimit=RATE\fP" |
.IP "\fB\-\-bwlimit=RATE\fP" |
This option allows you to specify the maximum transfer | This option allows you to specify the maximum transfer rate for the data |
rate for the data sent over the socket, specified in units per second. The | sent over the socket, specified in units per second. The RATE value can be |
RATE value can be suffixed with a string to indicate a size multiplier, and may | suffixed with a string to indicate a size multiplier, and may be a |
be a fractional value (e.g. \(dq\&\fB\-\-bwlimit=1.5m\fP\(dq\&). If no suffix is specified, | fractional value (e.g. "\fB\-\-bwlimit=1.5m\fP"). If no suffix is specified, the |
the value will be assumed to be in units of 1024 bytes (as if \(dq\&K\(dq\& or \(dq\&KiB\(dq\& had | value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had |
been appended). See the \fB\-\-max\-size\fP option for a description of all the | been appended). See the \fB\-\-max-size\fP option for a description of all the |
available suffixes. A value of zero specifies no limit. | available suffixes. A value of 0 specifies no limit. |
.IP | .IP |
For backward\-compatibility reasons, the rate limit will be rounded to the | 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. | nearest KiB unit, so no rate smaller than 1024 bytes per second is |
.IP | possible. |
Rsync writes data over the socket in blocks, and this option both limits the | .IP |
size of the blocks that rsync writes, and tries to keep the average transfer | Rsync writes data over the socket in blocks, and this option both limits |
rate at the requested limit. Some \(dq\&burstiness\(dq\& may be seen where rsync writes | the size of the blocks that rsync writes, and tries to keep the average |
out a block of data and then sleeps to bring the average rate into compliance. | transfer rate at the requested limit. Some burstiness may be seen where |
.IP | rsync writes out a block of data and then sleeps to bring the average rate |
Due to the internal buffering of data, the \fB\-\-progress\fP option may not be an | into compliance. |
accurate reflection on how fast the data is being sent. This is because some | .IP |
files can show up as being rapidly sent when the data is quickly buffered, | Due to the internal buffering of data, the \fB\-\-progress\fP option may not be |
while other can show up as very slow when the flushing of the output buffer | an accurate reflection on how fast the data is being sent. This is because |
occurs. This may be fixed in a future version. | some files can show up as being rapidly sent when the data is quickly |
.IP | buffered, while other can show up as very slow when the flushing of the |
.IP "\fB\-\-write\-batch=FILE\fP" | output buffer occurs. This may be fixed in a future version. |
Record a file that can later be applied to | .IP "`\-\-stop-after=MINS" |
another identical destination with \fB\-\-read\-batch\fP. See the \(dq\&BATCH MODE\(dq\& | This option tells rsync to stop copying when the specified number of |
section for details, and also the \fB\-\-only\-write\-batch\fP option. | minutes has elapsed. |
.IP | .IP |
.IP "\fB\-\-only\-write\-batch=FILE\fP" | Rsync also accepts an earlier version of this option: \fB\-\-time-limit=MINS\fP. |
Works like \fB\-\-write\-batch\fP, except that | .IP |
no updates are made on the destination system when creating the batch. | For maximal flexibility, rsync does not communicate this option to the |
This lets you transport the changes to the destination system via some | remote rsync since it is usually enough that one side of the connection |
other means and then apply the changes via \fB\-\-read\-batch\fP. | quits as specified. This allows the option's use even when only one side |
.IP | of the connection supports it. You can tell the remote side about the time |
| limit using \fB\-\-remote-option\fP (\fB\-M\fP), should the need arise. |
| .IP "`\-\-stop-at=y-m-dTh:m" |
| This option tells rsync to stop copying when the specified point in time |
| has been reached. The date & time can be fully specified in a numeric |
| format of year-month-dayThour:minute (e.g. 2000-12-31T23:59) in the local |
| timezone. You may choose to separate the date numbers using slashes |
| instead of dashes. |
| .IP |
| The value can also be abbreviated in a variety of ways, such as specifying |
| a 2-digit year and/or leaving off various values. In all cases, the value |
| will be taken to be the next possible point in time where the supplied |
| information matches. If the value specifies the current time or a past |
| time, rsync exits with an error. |
| .IP |
| For example, "1-30" specifies the next January 30th (at midnight local |
| time), "14:00" specifies the next 2 P.M., "1" specifies the next 1st of the |
| month at midnight, "31" specifies the next month where we can stop on its |
| 31st day, and ":59" specifies the next 59th minute after the hour. |
| .IP |
| For maximal flexibility, rsync does not communicate this option to the |
| remote rsync since it is usually enough that one side of the connection |
| quits as specified. This allows the option's use even when only one side |
| of the connection supports it. You can tell the remote side about the time |
| limit using \fB\-\-remote-option\fP (\fB\-M\fP), should the need arise. Do keep in |
| mind that the remote host may have a different default timezone than your |
| local host. |
| .IP "\fB\-\-write-batch=FILE\fP" |
| Record a file that can later be applied to another identical destination |
| with \fB\-\-read-batch\fP. See the "BATCH MODE" section for details, and also |
| the \fB\-\-only-write-batch\fP option. |
| .IP |
| 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 modern choice, use the \fB\-\-checksum-choice\fP (\fB\-\-cc\fP) and/or |
| \fB\-\-compress-choice\fP (\fB\-\-zc\fP) options. |
| .IP "\fB\-\-only-write-batch=FILE\fP" |
| Works like \fB\-\-write-batch\fP, except that no updates are made on the |
| destination system when creating the batch. This lets you transport the |
| changes to the destination system via some other means and then apply the |
| changes via \fB\-\-read-batch\fP. |
| .IP |
Note that you can feel free to write the batch directly to some portable |
Note that you can feel free to write the batch directly to some portable |
media: if this media fills to capacity before the end of the transfer, you |
media: if this media fills to capacity before the end of the transfer, you |
can just apply that partial transfer to the destination and repeat the |
can just apply that partial transfer to the destination and repeat the |
whole process to get the rest of the changes (as long as you don\(cq\&t mind a | whole process to get the rest of the changes (as long as you don't mind a |
partially updated destination system while the multi\-update cycle is | partially updated destination system while the multi-update cycle is |
happening). |
happening). |
.IP | .IP |
Also note that you only save bandwidth when pushing changes to a remote |
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 |
system because this allows the batched data to be diverted from the sender |
into the batch file without having to flow over the wire to the receiver |
into the batch file without having to flow over the wire to the receiver |
(when pulling, the sender is remote, and thus can\(cq\&t write the batch). | (when pulling, the sender is remote, and thus can't write the batch). |
.IP | .IP "\fB\-\-read-batch=FILE\fP" |
.IP "\fB\-\-read\-batch=FILE\fP" | Apply all of the changes stored in FILE, a file previously generated by |
Apply all of the changes stored in FILE, a | \fB\-\-write-batch\fP. If \fIFILE\fP is \fB\-\fP, the batch data will be read from |
file previously generated by \fB\-\-write\-batch\fP. | standard input. See the "BATCH MODE" section for details. |
If \fIFILE\fP is \fB\-\fP, the batch data will be read from standard input. | .IP "\fB\-\-source-filter=COMMAND\fP" |
See the \(dq\&BATCH MODE\(dq\& section for details. | This option allows the user to specify a filter program that will be |
.IP | applied to the contents of all transferred regular files before the data is |
| sent to destination. COMMAND will receive the data on its standard input |
| and it should write the filtered data to standard output. COMMAND should |
| exit non-zero if it cannot process the data or if it encounters an error |
| when writing the data to stdout. |
| .IP |
| Example: \fB\-\-source-filter="gzip\ \-9"\fP will cause remote files to be |
| compressed. Use of \fB\-\-source-filter\fP automatically enables \fB\-\-whole-file\fP. |
| If your filter does not output the same number of bytes that it received on |
| input, you should use \fB\-\-times-only\fP to disable size and content checks on |
| subsequent rsync runs. |
| .IP "\fB\-\-dest-filter=COMMAND\fP" |
| This option allows you to specify a filter program that will be applied to |
| the contents of all transferred regular files before the data is written to |
| disk. COMMAND will receive the data on its standard input and it should |
| write the filtered data to standard output. COMMAND should exit non-zero |
| if it cannot process the data or if it encounters an error when writing the |
| data to stdout. |
| .IP |
| Example: \-\-dest-filter="gzip \-9" will cause remote files to be compressed. |
| Use of \-\-dest-filter automatically enables \-\-whole-file. If your filter |
| does not output the same number of bytes that it received on input, you |
| should use \-\-times-only to disable size and content checks on subsequent |
| rsync runs. |
.IP "\fB\-\-protocol=NUM\fP" |
.IP "\fB\-\-protocol=NUM\fP" |
Force an older protocol version to be used. This | Force an older protocol version to be used. This is useful for creating a |
is useful for creating a batch file that is compatible with an older | batch file that is compatible with an older version of rsync. For |
version of rsync. For instance, if rsync 2.6.4 is being used with the | instance, if rsync 2.6.4 is being used with the \fB\-\-write-batch\fP option, but |
\fB\-\-write\-batch\fP option, but rsync 2.6.3 is what will be used to run the | rsync 2.6.3 is what will be used to run the \fB\-\-read-batch\fP option, you |
\fB\-\-read\-batch\fP option, you should use \(dq\&\-\-protocol=28\(dq\& when creating the | should use "\-\-protocol=28" when creating the batch file to force the older |
batch file to force the older protocol version to be used in the batch | protocol version to be used in the batch file (assuming you can't upgrade |
file (assuming you can\(cq\&t upgrade the rsync on the reading system). | the rsync on the reading system). |
.IP | |
.IP "\fB\-\-iconv=CONVERT_SPEC\fP" |
.IP "\fB\-\-iconv=CONVERT_SPEC\fP" |
Rsync can convert filenames between character | Rsync can convert filenames between character sets using this option. |
sets using this option. Using a CONVERT_SPEC of \(dq\&.\(dq\& tells rsync to look up | Using a CONVERT_SPEC of "." tells rsync to look up the default |
the default character\-set via the locale setting. Alternately, you can | character-set via the locale setting. Alternately, you can fully specify |
fully specify what conversion to do by giving a local and a remote charset | what conversion to do by giving a local and a remote charset separated by a |
separated by a comma in the order \fB\-\-iconv=LOCAL,REMOTE\fP, e.g. | comma in the order \fB\-\-iconv=LOCAL,REMOTE\fP, e.g. \fB\-\-iconv=utf8,iso88591\fP. |
\fB\-\-iconv=utf8,iso88591\fP. This order ensures that the option | This order ensures that the option will stay the same whether you're |
will stay the same whether you\(cq\&re pushing or pulling files. | pushing or pulling files. Finally, you can specify either \fB\-\-no-iconv\fP or |
Finally, you can specify either \fB\-\-no\-iconv\fP or a CONVERT_SPEC of \(dq\&\-\(dq\& | a CONVERT_SPEC of "\-" to turn off any conversion. The default setting of |
to turn off any conversion. | this option is site-specific, and can also be affected via the RSYNC_ICONV |
The default setting of this option is site\-specific, and can also be | environment variable. |
affected via the RSYNC_ICONV environment variable. | .IP |
.IP | |
For a list of what charset names your local iconv library supports, you can |
For a list of what charset names your local iconv library supports, you can |
run \(dq\&iconv \-\-list\(dq\&. | run "\fBiconv\ \-\-list\fP". |
.IP | .IP |
If you specify the \fB\-\-protect\-args\fP option (\fB\-s\fP), rsync will translate | If you specify the \fB\-\-protect-args\fP option (\fB\-s\fP), rsync will translate the |
the filenames you specify on the command\-line that are being sent to the | filenames you specify on the command-line that are being sent to the remote |
remote host. See also the \fB\-\-files\-from\fP option. | host. See also the \fB\-\-files-from\fP option. |
.IP | .IP |
Note that rsync does not do any conversion of names in filter files |
Note that rsync does not do any conversion of names in filter files |
(including include/exclude files). It is up to you to ensure that you\(cq\&re | (including include/exclude files). It is up to you to ensure that you're |
specifying matching rules that can match on both sides of the transfer. |
specifying matching rules that can match on both sides of the transfer. |
For instance, you can specify extra include/exclude rules if there are |
For instance, you can specify extra include/exclude rules if there are |
filename differences on the two sides that need to be accounted for. |
filename differences on the two sides that need to be accounted for. |
.IP | .IP |
When you pass an \fB\-\-iconv\fP option to an rsync daemon that allows it, the |
When you pass an \fB\-\-iconv\fP option to an rsync daemon that allows it, the |
daemon uses the charset specified in its \(dq\&charset\(dq\& configuration parameter | daemon uses the charset specified in its "charset" configuration parameter |
regardless of the remote charset you actually pass. Thus, you may feel free to | regardless of the remote charset you actually pass. Thus, you may feel |
specify just the local charset for a daemon transfer (e.g. \fB\-\-iconv=utf8\fP). | free to specify just the local charset for a daemon transfer (e.g. |
.IP | \fB\-\-iconv=utf8\fP). |
.IP "\fB\-4, \-\-ipv4\fP or \fB\-6, \-\-ipv6\fP" | .IP "\fB\-\-tr=BAD/GOOD\fP" |
Tells rsync to prefer IPv4/IPv6 | Transliterates filenames on the receiver, after the iconv conversion (if |
when creating sockets. This only affects sockets that rsync has direct | any). This can be used to remove characters illegal on the destination |
control over, such as the outgoing socket when directly contacting an | filesystem. If you use this option, consider saving a "find . \-ls" listing |
rsync daemon. See also these options in the \fB\-\-daemon\fP mode section. | of the source in the destination to help you determine the original |
.IP | filenames in case of need. |
If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option | .IP |
will have no effect. The \fB\-\-version\fP output will tell you if this | The argument consists of a string of characters to remove, optionally |
| followed by a slash and a string of corresponding characters with which to |
| replace them. The second string may be shorter, in which case any leftover |
| characters in the first string are simply deleted. For example, |
| \fB\-\-tr=':\\/!'\fP replaces colons with exclamation marks and deletes |
| backslashes. Slashes cannot be transliterated because it would cause |
| havoc. |
| .IP |
| If the receiver is invoked over a remote shell, use \fB\-\-protect-args\fP to |
| stop the shell from interpreting any nasty characters in the argument. |
| .IP "\fB\-\-ipv4\fP, \fB\-4\fP or \fB\-\-ipv6\fP, \fB\-6\fP" |
| 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 directly contacting an rsync daemon, as well as the forwarding |
| of the \fB\-4\fP or \fB\-6\fP option to ssh when rsync can deduce that ssh is being |
| used as the remote shell. For other remote shells you'll need to specify |
| the "\fB\-\-rsh\ SHELL\ \-4\fP" option directly (or whatever ipv4/ipv6 hint options |
| it uses). |
| .IP |
| These options also exist in the \fB\-\-daemon\fP mode section. |
| .IP |
| If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option will |
| have no effect. The \fBrsync\ \-\-version\fP output will contain "\fBno\ IPv6\fP" if |
is the case. |
is the case. |
.IP | .IP "\fB\-\-checksum-seed=NUM\fP" |
.IP "\fB\-\-checksum\-seed=NUM\fP" | Set the checksum seed to the integer NUM. This 4 byte checksum seed is |
Set the checksum seed to the integer NUM. This 4 | included in each block and MD4 file checksum calculation (the more modern |
byte checksum seed is included in each block and MD4 file checksum calculation | MD5 file checksums don't use a seed). By default the checksum seed is |
(the more modern MD5 file checksums don\(cq\&t use a seed). By default the checksum | generated by the server and defaults to the current \fBtime\fP(). This |
seed is generated by the server and defaults to the current | |
\f(CWtime()\fP | |
\&. This | |
option is used to set a specific checksum seed, which is useful for |
option is used to set a specific checksum seed, which is useful for |
applications that want repeatable block checksums, or in the case where the |
applications that want repeatable block checksums, or in the case where the |
user wants a more random checksum seed. Setting NUM to 0 causes rsync to use | user wants a more random checksum seed. Setting NUM to 0 causes rsync to |
the default of | use the default of \fBtime\fP() for checksum seed. |
\f(CWtime()\fP | .P |
for checksum seed. | |
.IP | |
.SH "DAEMON OPTIONS" |
.SH "DAEMON OPTIONS" |
| .P |
.PP | |
The options allowed when starting an rsync daemon are as follows: |
The options allowed when starting an rsync daemon are as follows: |
.PP | .P |
.IP "\fB\-\-daemon\fP" |
.IP "\fB\-\-daemon\fP" |
This tells rsync that it is to run as a daemon. The | This tells rsync that it is to run as a daemon. The daemon you start |
daemon you start running may be accessed using an rsync client using | running may be accessed using an rsync client using the \fBhost::module\fP or |
the \fBhost::module\fP or \fBrsync://host/module/\fP syntax. | \fBrsync://host/module/\fP syntax. |
.IP | .IP |
If standard input is a socket then rsync will assume that it is being | If standard input is a socket then rsync will assume that it is being run |
run via inetd, otherwise it will detach from the current terminal and | via inetd, otherwise it will detach from the current terminal and become a |
become a background daemon. The daemon will read the config file | background daemon. The daemon will read the config file (rsyncd.conf) on |
(rsyncd.conf) on each connect made by a client and respond to | each connect made by a client and respond to requests accordingly. See the |
requests accordingly. See the \fBrsyncd.conf\fP(5) man page for more | \fBrsyncd.conf\fP(5) man page for more details. |
details. | .IP "\fB\-\-address=ADDRESS\fP" |
.IP | By default rsync will bind to the wildcard address when run as a daemon |
.IP "\fB\-\-address\fP" | with the \fB\-\-daemon\fP option. The \fB\-\-address\fP option allows you to specify a |
By default rsync will bind to the wildcard address when | specific IP address (or hostname) to bind to. This makes virtual hosting |
run as a daemon with the \fB\-\-daemon\fP option. The \fB\-\-address\fP option | possible in conjunction with the \fB\-\-config\fP option. See also the "address" |
allows you to specify a specific IP address (or hostname) to bind to. This | global option in the rsyncd.conf manpage. |
makes virtual hosting possible in conjunction with the \fB\-\-config\fP option. | |
See also the \(dq\&address\(dq\& global option in the rsyncd.conf manpage. | |
.IP | |
.IP "\fB\-\-bwlimit=RATE\fP" |
.IP "\fB\-\-bwlimit=RATE\fP" |
This option allows you to specify the maximum transfer | This option allows you to specify the maximum transfer rate for the data |
rate for the data the daemon sends over the socket. The client can still | the daemon sends over the socket. The client can still specify a smaller |
specify a smaller \fB\-\-bwlimit\fP value, but no larger value will be allowed. | \fB\-\-bwlimit\fP value, but no larger value will be allowed. See the client |
See the client version of this option (above) for some extra details. | version of this option (above) for some extra details. |
.IP | |
.IP "\fB\-\-config=FILE\fP" |
.IP "\fB\-\-config=FILE\fP" |
This specifies an alternate config file than | This specifies an alternate config file than the default. This is only |
the default. This is only relevant when \fB\-\-daemon\fP is specified. | relevant when \fB\-\-daemon\fP is specified. The default is /etc/rsyncd.conf |
The default is /etc/rsyncd.conf unless the daemon is running over | unless the daemon is running over a remote shell program and the remote |
a remote shell program and the remote user is not the super\-user; in that case | user is not the super-user; in that case the default is rsyncd.conf in the |
the default is rsyncd.conf in the current directory (typically $HOME). | current directory (typically $HOME). |
.IP | .IP "\fB\-\-dparam=OVERRIDE\fP, \fB\-M\fP" |
.IP "\fB\-M, \-\-dparam=OVERRIDE\fP" | This option can be used to set a daemon-config parameter when starting up |
This option can be used to set a daemon\-config | rsync in daemon mode. It is equivalent to adding the parameter at the end |
parameter when starting up rsync in daemon mode. It is equivalent to adding | of the global settings prior to the first module's definition. The |
the parameter at the end of the global settings prior to the first module\(cq\&s | parameter names can be specified without spaces, if you so desire. For |
definition. The parameter names can be specified without spaces, if you so | instance: |
desire. For instance: | .RS 4 |
.IP | .IP |
.nf | .nf |
rsync \-\-daemon \-M pidfile=/path/rsync.pid | rsync --daemon -M pidfile=/path/rsync.pid |
.fi | .fi |
| .RE |
.IP | .IP "\fB\-\-no-detach\fP" |
.IP "\fB\-\-no\-detach\fP" | When running as a daemon, this option instructs rsync to not detach itself |
When running as a daemon, this option instructs | and become a background process. This option is required when running as a |
rsync to not detach itself and become a background process. This | service on Cygwin, and may also be useful when rsync is supervised by a |
option is required when running as a service on Cygwin, and may also | program such as \fBdaemontools\fP or AIX's \fBSystem\ Resource\ Controller\fP. |
be useful when rsync is supervised by a program such as | \fB\-\-no-detach\fP is also recommended when rsync is run under a debugger. This |
\fBdaemontools\fP or AIX\(cq\&s \fBSystem Resource Controller\fP. | option has no effect if rsync is run from inetd or sshd. |
\fB\-\-no\-detach\fP is also recommended when rsync is run under a | |
debugger. This option has no effect if rsync is run from inetd or | |
sshd. | |
.IP | |
.IP "\fB\-\-port=PORT\fP" |
.IP "\fB\-\-port=PORT\fP" |
This specifies an alternate TCP port number for the | This specifies an alternate TCP port number for the daemon to listen on |
daemon to listen on rather than the default of 873. See also the \(dq\&port\(dq\& | rather than the default of 873. See also the "port" global option in the |
global option in the rsyncd.conf manpage. | rsyncd.conf manpage. |
.IP | .IP "\fB\-\-log-file=FILE\fP" |
.IP "\fB\-\-log\-file=FILE\fP" | This option tells the rsync daemon to use the given log-file name instead |
This option tells the rsync daemon to use the | of using the "\fBlog\ file\fP" setting in the config file. |
given log\-file name instead of using the \(dq\&log file\(dq\& setting in the config | .IP "\fB\-\-log-file-format=FORMAT\fP" |
file. | This option tells the rsync daemon to use the given FORMAT string instead |
.IP | of using the "\fBlog\ format\fP" setting in the config file. It also enables |
.IP "\fB\-\-log\-file\-format=FORMAT\fP" | "\fBtransfer\ logging\fP" unless the string is empty, in which case transfer |
This option tells the rsync daemon to use the | logging is turned off. |
given FORMAT string instead of using the \(dq\&log format\(dq\& setting in the config | |
file. It also enables \(dq\&transfer logging\(dq\& unless the string is empty, in which | |
case transfer logging is turned off. | |
.IP | |
.IP "\fB\-\-sockopts\fP" |
.IP "\fB\-\-sockopts\fP" |
This overrides the \fBsocket options\fP setting in the | This overrides the \fBsocket\ options\fP setting in the rsyncd.conf file and has |
rsyncd.conf file and has the same syntax. | the same syntax. |
.IP | .IP "\fB\-\-verbose\fP, \fB\-v\fP" |
.IP "\fB\-v, \-\-verbose\fP" | This option increases the amount of information the daemon logs during its |
This option increases the amount of information the | startup phase. After the client connects, the daemon's verbosity level |
daemon logs during its startup phase. After the client connects, the | will be controlled by the options that the client used and the |
daemon\(cq\&s verbosity level will be controlled by the options that the client | "\fBmax\ verbosity\fP" setting in the module's config section. |
used and the \(dq\&max verbosity\(dq\& setting in the module\(cq\&s config section. | .IP "\fB\-\-ipv4\fP, \fB\-4\fP or \fB\-\-ipv6\fP, \fB\-6\fP" |
.IP | Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the |
.IP "\fB\-4, \-\-ipv4\fP or \fB\-6, \-\-ipv6\fP" | rsync daemon will use to listen for connections. One of these options may |
Tells rsync to prefer IPv4/IPv6 | be required in older versions of Linux to work around an IPv6 bug in the |
when creating the incoming sockets that the rsync daemon will use to | kernel (if you see an "address already in use" error when nothing else is |
listen for connections. One of these options may be required in older | using the port, try specifying \fB\-\-ipv6\fP or \fB\-\-ipv4\fP when starting the |
versions of Linux to work around an IPv6 bug in the kernel (if you see | daemon). |
an \(dq\&address already in use\(dq\& error when nothing else is using the port, | .IP |
try specifying \fB\-\-ipv6\fP or \fB\-\-ipv4\fP when starting the daemon). | These options also exist in the regular rsync options section. |
.IP | .IP |
If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option | If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option will |
will have no effect. The \fB\-\-version\fP output will tell you if this | have no effect. The \fBrsync\ \-\-version\fP output will contain "\fBno\ IPv6\fP" if |
is the case. |
is the case. |
.IP | .IP "\fB\-\-help\fP, \fB\-h\fP" |
.IP "\fB\-h, \-\-help\fP" | When specified after \fB\-\-daemon\fP, print a short help page describing the |
When specified after \fB\-\-daemon\fP, print a short help | options available for starting an rsync daemon. |
page describing the options available for starting an rsync daemon. | .P |
| |
.PP | |
.SH "FILTER RULES" |
.SH "FILTER RULES" |
| .P |
.PP | |
The filter rules allow for flexible selection of which files to transfer |
The filter rules allow for flexible selection of which files to transfer |
(include) and which files to skip (exclude). The rules either directly | (include) and which files to skip (exclude). The rules either directly specify |
specify include/exclude patterns or they specify a way to acquire more | include/exclude patterns or they specify a way to acquire more include/exclude |
include/exclude patterns (e.g. to read them from a file). | patterns (e.g. to read them from a file). |
.PP | .P |
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 |
name to be transferred against the list of include/exclude patterns in | to be transferred against the list of include/exclude patterns in turn, and the |
turn, and the first matching pattern is acted on: if it is an exclude | first matching pattern is acted on: if it is an exclude pattern, then that file |
pattern, then that file is skipped; if it is an include pattern then that | is skipped; if it is an include pattern then that filename is not skipped; if |
filename is not skipped; if no matching pattern is found, then the | no matching pattern is found, then the filename is not skipped. |
filename is not skipped. | .P |
.PP | Rsync builds an ordered list of filter rules as specified on the command-line. |
Rsync builds an ordered list of filter rules as specified on the | Filter rules have the following syntax: |
command\-line. Filter rules have the following syntax: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWRULE [PATTERN_OR_FILENAME]\fP | RULE [PATTERN_OR_FILENAME] |
.br | RULE,MODIFIERS [PATTERN_OR_FILENAME] |
\f(CWRULE,MODIFIERS [PATTERN_OR_FILENAME]\fP | .fi |
.br | |
.RE |
.RE |
| .P |
.PP | |
You have your choice of using either short or long RULE names, as described |
You have your choice of using either short or long RULE names, as described |
below. If you use a short\-named rule, the \(cq\&,\(cq\& separating the RULE from the | below. If you use a short-named rule, the ',' separating the RULE from the |
MODIFIERS is optional. The PATTERN or FILENAME that follows (when present) |
MODIFIERS is optional. The PATTERN or FILENAME that follows (when present) |
must come after either a single space or an underscore (_). | must come after either a single space or an underscore (_). Here are the |
Here are the available rule prefixes: | available rule prefixes: |
.PP | .P |
.RS | .IP "\fBexclude,\ '\-'\fP" |
\fBexclude, \-\fP specifies an exclude pattern. | specifies an exclude pattern. |
.br | .IP "\fBinclude,\ '+'\fP" |
\fBinclude, +\fP specifies an include pattern. | specifies an include pattern. |
.br | .IP "\fBmerge,\ '.'\fP" |
\fBmerge, .\fP specifies a merge\-file to read for more rules. | specifies a merge-file to read for more rules. |
.br | .IP "\fBdir-merge,\ ':'\fP" |
\fBdir\-merge, :\fP specifies a per\-directory merge\-file. | specifies a per-directory merge-file. |
.br | .IP "\fBhide,\ 'H'\fP" |
\fBhide, H\fP specifies a pattern for hiding files from the transfer. | specifies a pattern for hiding files from the transfer. |
.br | .IP "\fBshow,\ 'S'\fP" |
\fBshow, S\fP files that match the pattern are not hidden. | files that match the pattern are not hidden. |
.br | .IP "\fBprotect,\ 'P'\fP" |
\fBprotect, P\fP specifies a pattern for protecting files from deletion. | specifies a pattern for protecting files from deletion. |
.br | .IP "\fBrisk,\ 'R'\fP" |
\fBrisk, R\fP files that match the pattern are not protected. | files that match the pattern are not protected. |
.br | .IP "\fBclear,\ '!'\fP" |
\fBclear, !\fP clears the current include/exclude list (takes no arg) | clears the current include/exclude list (takes no arg) |
.br | .P |
.RE | When rules are being read from a file, empty lines are ignored, as are comment |
| lines that start with a "#". |
.PP | .P |
When rules are being read from a file, empty lines are ignored, as are | Note that the \fB\-\-include\fP & \fB\-\-exclude\fP command-line options do not allow the |
comment lines that start with a \(dq\&#\(dq\&. | full range of rule parsing as described above\ \-\- they only allow the |
.PP | specification of include / exclude patterns plus a "\fB!\fP" token to clear the |
Note that the \fB\-\-include\fP/\fB\-\-exclude\fP command\-line options do not allow the | list (and the normal comment parsing when rules are read from a file). If a |
full range of rule parsing as described above \-\- they only allow the | pattern does not begin with "\fB\-\ \fP" (dash, space) or "\fB+\ \fP" (plus, space), then |
specification of include/exclude patterns plus a \(dq\&!\(dq\& token to clear the | the rule will be interpreted as if "\fB+\ \fP" (for an include option) or "\fB\-\ \fP" |
list (and the normal comment parsing when rules are read from a file). | (for an exclude option) were prefixed to the string. A \fB\-\-filter\fP option, on |
If a pattern | |
does not begin with \(dq\&\- \(dq\& (dash, space) or \(dq\&+ \(dq\& (plus, space), then the | |
rule will be interpreted as if \(dq\&+ \(dq\& (for an include option) or \(dq\&\- \(dq\& (for | |
an exclude option) were prefixed to the string. A \fB\-\-filter\fP option, on | |
the other hand, must always contain either a short or long rule name at the |
the other hand, must always contain either a short or long rule name at the |
start of the rule. |
start of the rule. |
.PP | .P |
Note also that the \fB\-\-filter\fP, \fB\-\-include\fP, and \fB\-\-exclude\fP options take one |
Note also that the \fB\-\-filter\fP, \fB\-\-include\fP, and \fB\-\-exclude\fP options take one |
rule/pattern each. To add multiple ones, you can repeat the options on | rule/pattern each. To add multiple ones, you can repeat the options on the |
the command\-line, use the merge\-file syntax of the \fB\-\-filter\fP option, or | command-line, use the merge-file syntax of the \fB\-\-filter\fP option, or the |
the \fB\-\-include\-from\fP/\fB\-\-exclude\-from\fP options. | \fB\-\-include-from\fP / \fB\-\-exclude-from\fP options. |
.PP | .P |
.SH "INCLUDE/EXCLUDE PATTERN RULES" |
.SH "INCLUDE/EXCLUDE PATTERN RULES" |
| .P |
.PP | You can include and exclude files by specifying patterns using the "+", "\-", |
You can include and exclude files by specifying patterns using the \(dq\&+\(dq\&, | etc. filter rules (as introduced in the FILTER RULES section above). The |
\(dq\&\-\(dq\&, etc. filter rules (as introduced in the FILTER RULES section above). | include/exclude rules each specify a pattern that is matched against the names |
The include/exclude rules each specify a pattern that is matched against | of the files that are going to be transferred. These patterns can take several |
the names of the files that are going to be transferred. These patterns | forms: |
can take several forms: | .P |
.PP | .IP o |
.IP o | if the pattern starts with a \fB/\fP then it is anchored to a particular spot in |
if the pattern starts with a / then it is anchored to a | the hierarchy of files, otherwise it is matched against the end of the |
particular spot in the hierarchy of files, otherwise it is matched | pathname. This is similar to a leading \fB^\fP in regular expressions. Thus |
against the end of the pathname. This is similar to a leading ^ in | \fB/foo\fP would match a name of "foo" at either the "root of the transfer" (for |
regular expressions. | a global rule) or in the merge-file's directory (for a per-directory rule). |
Thus \(dq\&/foo\(dq\& would match a name of \(dq\&foo\(dq\& at either the \(dq\&root of the | An unqualified \fBfoo\fP would match a name of "foo" anywhere in the tree because |
transfer\(dq\& (for a global rule) or in the merge\-file\(cq\&s directory (for a | the algorithm is applied recursively from the top down; it behaves as if each |
per\-directory rule). | path component gets a turn at being the end of the filename. Even the |
An unqualified \(dq\&foo\(dq\& would match a name of \(dq\&foo\(dq\& anywhere in the | unanchored "sub/foo" would match at any point in the hierarchy where a "foo" |
tree because the algorithm is applied recursively from the | was found within a directory named "sub". See the section on ANCHORING |
top down; it behaves as if each path component gets a turn at being the | INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify a pattern |
end of the filename. Even the unanchored \(dq\&sub/foo\(dq\& would match at | that matches at the root of the transfer. |
any point in the hierarchy where a \(dq\&foo\(dq\& was found within a directory | .IP o |
named \(dq\&sub\(dq\&. See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for | if the pattern ends with a \fB/\fP then it will only match a directory, not a |
a full discussion of how to specify a pattern that matches at the root | regular file, symlink, or device. |
of the transfer. | .IP o |
.IP o | rsync chooses between doing a simple string match and wildcard matching by |
if the pattern ends with a / then it will only match a | checking if the pattern contains one of these three wildcard characters: |
directory, not a regular file, symlink, or device. | \&'\fB*\fP', '\fB?\fP', and '\fB[\fP' . |
.IP o | .IP o |
rsync chooses between doing a simple string match and wildcard | a '\fB*\fP' matches any path component, but it stops at slashes. |
matching by checking if the pattern contains one of these three wildcard | .IP o |
characters: \(cq\&*\(cq\&, \(cq\&?\(cq\&, and \(cq\&[\(cq\& . | use '\fB**\fP' to match anything, including slashes. |
.IP o | .IP o |
a \(cq\&*\(cq\& matches any path component, but it stops at slashes. | a '\fB?\fP' matches any character except a slash (\fB/\fP). |
.IP o | .IP o |
use \(cq\&**\(cq\& to match anything, including slashes. | a '\fB[\fP' introduces a character class, such as \fB[a-z]\fP or \fB[[:alpha:]]\fP. |
.IP o | .IP o |
a \(cq\&?\(cq\& matches any character except a slash (/). | |
.IP o | |
a \(cq\&[\(cq\& introduces a character class, such as [a\-z] or [[:alpha:]]. | |
.IP o | |
in a wildcard pattern, a backslash can be used to escape a wildcard |
in a wildcard pattern, a backslash can be used to escape a wildcard |
character, but it is matched literally when no wildcards are present. | character, but it is matched literally when no wildcards are present. This |
This means that there is an extra level of backslash removal when a | means that there is an extra level of backslash removal when a pattern |
pattern contains wildcard characters compared to a pattern that has none. | contains wildcard characters compared to a pattern that has none. e.g. if |
e.g. if you add a wildcard to \(dq\&foo\ebar\(dq\& (which matches the backslash) you | you add a wildcard to "\fBfoo\\bar\fP" (which matches the backslash) you would |
would need to use \(dq\&foo\e\ebar*\(dq\& to avoid the \(dq\&\eb\(dq\& becoming just \(dq\&b\(dq\&. | need to use "\fBfoo\\\\bar*\fP" to avoid the "\fB\\b\fP" becoming just "b". |
.IP o | .IP o |
if the pattern contains a / (not counting a trailing /) or a \(dq\&**\(dq\&, | if the pattern contains a \fB/\fP (not counting a trailing /) or a "\fB**\fP", then it |
then it is matched against the full pathname, including any leading | is matched against the full pathname, including any leading directories. If |
directories. If the pattern doesn\(cq\&t contain a / or a \(dq\&**\(dq\&, then it is | the pattern doesn't contain a \fB/\fP or a "\fB**\fP", then it is matched only against |
matched only against the final component of the filename. | the final component of the filename. (Remember that the algorithm is applied |
(Remember that the algorithm is applied recursively so \(dq\&full filename\(dq\& | recursively so "full filename" can actually be any portion of a path from the |
can actually be any portion of a path from the starting directory on | starting directory on down.) |
down.) | .IP o |
.IP o | a trailing "\fBdir_name/***\fP" will match both the directory (as if "dir_name/" |
a trailing \(dq\&dir_name/***\(dq\& will match both the directory (as if | had been specified) and everything in the directory (as if "\fBdir_name/**\fP" |
\(dq\&dir_name/\(dq\& had been specified) and everything in the directory | had been specified). This behavior was added in version 2.6.7. |
(as if \(dq\&dir_name/**\(dq\& had been specified). This behavior was added in | .P |
version 2.6.7. | |
| |
.PP | |
Note that, when using the \fB\-\-recursive\fP (\fB\-r\fP) option (which is implied by |
Note that, when using the \fB\-\-recursive\fP (\fB\-r\fP) option (which is implied by |
\fB\-a\fP), every subcomponent of every path is visited from the top down, so | \fB\-a\fP), every subdir component of every path is visited left to right, with each |
include/exclude patterns get applied recursively to each subcomponent\(cq\&s | directory having a chance for exclusion before its content. In this way |
full name (e.g. to include \(dq\&/foo/bar/baz\(dq\& the subcomponents \(dq\&/foo\(dq\& and | include/exclude patterns are applied recursively to the pathname of each node |
\(dq\&/foo/bar\(dq\& must not be excluded). | in the filesystem's tree (those inside the transfer). The exclude patterns |
The exclude patterns actually short\-circuit the directory traversal stage | short-circuit the directory traversal stage as rsync finds the files to send. |
when rsync finds the files to send. If a pattern excludes a particular | .P |
parent directory, it can render a deeper include pattern ineffectual | For instance, to include "\fB/foo/bar/baz\fP", the directories "\fB/foo\fP" and "\fB/foo/bar\fP" |
because rsync did not descend through that excluded section of the | must not be excluded. Excluding one of those parent directories prevents the |
hierarchy. This is particularly important when using a trailing \(cq\&*\(cq\& rule. | examination of its content, cutting off rsync's recursion into those paths and |
For instance, this won\(cq\&t work: | rendering the include for "\fB/foo/bar/baz\fP" ineffectual (since rsync can't match |
.PP | something it never sees in the cut-off section of the directory hierarchy). |
.RS | .P |
\f(CW+ /some/path/this\-file\-will\-not\-be\-found\fP | The concept path exclusion is particularly important when using a trailing '\fB*\fP' |
.br | rule. For instance, this won't work: |
\f(CW+ /file\-is\-included\fP | .RS 4 |
.br | .P |
\f(CW\- *\fP | .nf |
.br | + /some/path/this-file-will-not-be-found |
| + /file-is-included |
| - * |
| .fi |
.RE |
.RE |
| .P |
.PP | This fails because the parent directory "some" is excluded by the '\fB*\fP' rule, so |
This fails because the parent directory \(dq\&some\(dq\& is excluded by the \(cq\&*\(cq\& | rsync never visits any of the files in the "some" or "some/path" directories. |
rule, so rsync never visits any of the files in the \(dq\&some\(dq\& or \(dq\&some/path\(dq\& | One solution is to ask for all directories in the hierarchy to be included by |
directories. One solution is to ask for all directories in the hierarchy | using a single rule: "\fB+\ */\fP" (put it somewhere before the "\fB\-\ *\fP" rule), and |
to be included by using a single rule: \(dq\&+ */\(dq\& (put it somewhere before the | perhaps use the \fB\-\-prune-empty-dirs\fP option. Another solution is to add |
\(dq\&\- *\(dq\& rule), and perhaps use the \fB\-\-prune\-empty\-dirs\fP option. Another | specific include rules for all the parent dirs that need to be visited. For |
solution is to add specific include rules for all | instance, this set of rules works fine: |
the parent dirs that need to be visited. For instance, this set of rules | .RS 4 |
works fine: | .P |
.PP | .nf |
.RS | + /some/ |
\f(CW+ /some/\fP | + /some/path/ |
.br | + /some/path/this-file-is-found |
\f(CW+ /some/path/\fP | + /file-also-included |
.br | - * |
\f(CW+ /some/path/this\-file\-is\-found\fP | .fi |
.br | |
\f(CW+ /file\-also\-included\fP | |
.br | |
\f(CW\- *\fP | |
.br | |
.RE |
.RE |
| .P |
.PP | |
Here are some examples of exclude/include matching: |
Here are some examples of exclude/include matching: |
.PP | .P |
.IP o | .IP o |
\(dq\&\- *.o\(dq\& would exclude all names matching *.o | "\fB\-\ *.o\fP" would exclude all names matching \fB*.o\fP |
.IP o | .IP o |
\(dq\&\- /foo\(dq\& would exclude a file (or directory) named foo in the | "\fB\-\ /foo\fP" would exclude a file (or directory) named foo in the transfer-root |
transfer\-root directory | directory |
.IP o | .IP o |
\(dq\&\- foo/\(dq\& would exclude any directory named foo | "\fB\-\ foo/\fP" would exclude any directory named foo |
.IP o | .IP o |
\(dq\&\- /foo/*/bar\(dq\& would exclude any file named bar which is at two | "\fB\-\ /foo/*/bar\fP" would exclude any file named bar which is at two levels |
levels below a directory named foo in the transfer\-root directory | below a directory named foo in the transfer-root directory |
.IP o | .IP o |
\(dq\&\- /foo/**/bar\(dq\& would exclude any file named bar two | "\fB\-\ /foo/**/bar\fP" would exclude any file named bar two or more levels below a |
or more levels below a directory named foo in the transfer\-root directory | directory named foo in the transfer-root directory |
.IP o | .IP o |
The combination of \(dq\&+ */\(dq\&, \(dq\&+ *.c\(dq\&, and \(dq\&\- *\(dq\& would include all | The combination of "\fB+\ */\fP", "\fB+\ *.c\fP", and "\fB\-\ *\fP" would include all |
directories and C source files but nothing else (see also the |
directories and C source files but nothing else (see also the |
\fB\-\-prune\-empty\-dirs\fP option) | \fB\-\-prune-empty-dirs\fP option) |
.IP o | .IP o |
The combination of \(dq\&+ foo/\(dq\&, \(dq\&+ foo/bar.c\(dq\&, and \(dq\&\- *\(dq\& would include | The combination of "\fB+\ foo/\fP", "\fB+\ foo/bar.c\fP", and "\fB\-\ *\fP" would include |
only the foo directory and foo/bar.c (the foo directory must be | only the foo directory and foo/bar.c (the foo directory must be explicitly |
explicitly included or it would be excluded by the \(dq\&*\(dq\&) | included or it would be excluded by the "\fB*\fP") |
| .P |
.PP | The following modifiers are accepted after a "\fB+\fP" or "\fB\-\fP": |
The following modifiers are accepted after a \(dq\&+\(dq\& or \(dq\&\-\(dq\&: | .P |
.PP | .IP o |
.IP o | A \fB/\fP specifies that the include/exclude rule should be matched against the |
A \fB/\fP specifies that the include/exclude rule should be matched | absolute pathname of the current item. For example, "\fB\-/\ /etc/passwd\fP" would |
against the absolute pathname of the current item. For example, | exclude the passwd file any time the transfer was sending files from the |
\(dq\&\-/ /etc/passwd\(dq\& would exclude the passwd file any time the transfer | "/etc" directory, and "\-/ subdir/foo" would always exclude "foo" when it is |
was sending files from the \(dq\&/etc\(dq\& directory, and \(dq\&\-/ subdir/foo\(dq\& | in a dir named "subdir", even if "foo" is at the root of the current |
would always exclude \(dq\&foo\(dq\& when it is in a dir named \(dq\&subdir\(dq\&, even | transfer. |
if \(dq\&foo\(dq\& is at the root of the current transfer. | .IP o |
.IP o | A \fB!\fP specifies that the include/exclude should take effect if the pattern |
A \fB!\fP specifies that the include/exclude should take effect if | fails to match. For instance, "\fB\-!\ */\fP" would exclude all non-directories. |
the pattern fails to match. For instance, \(dq\&\-! */\(dq\& would exclude all | .IP o |
non\-directories. | A \fBC\fP is used to indicate that all the global CVS-exclude rules should be |
.IP o | inserted as excludes in place of the "\-C". No arg should follow. |
A \fBC\fP is used to indicate that all the global CVS\-exclude rules | .IP o |
should be inserted as excludes in place of the \(dq\&\-C\(dq\&. No arg should | An \fBs\fP is used to indicate that the rule applies to the sending side. When a |
follow. | rule affects the sending side, it prevents files from being transferred. The |
.IP o | default is for a rule to affect both sides unless \fB\-\-delete-excluded\fP was |
An \fBs\fP is used to indicate that the rule applies to the sending | specified, in which case default rules become sender-side only. See also the |
side. When a rule affects the sending side, it prevents files from | hide (H) and show (S) rules, which are an alternate way to specify |
being transferred. The default is for a rule to affect both sides | sending-side includes/excludes. |
unless \fB\-\-delete\-excluded\fP was specified, in which case default rules | .IP o |
become sender\-side only. See also the hide (H) and show (S) rules, | An \fBr\fP is used to indicate that the rule applies to the receiving side. When |
which are an alternate way to specify sending\-side includes/excludes. | a rule affects the receiving side, it prevents files from being deleted. See |
.IP o | the \fBs\fP modifier for more info. See also the protect (P) and risk (R) rules, |
An \fBr\fP is used to indicate that the rule applies to the receiving | which are an alternate way to specify receiver-side includes/excludes. |
side. When a rule affects the receiving side, it prevents files from | .IP o |
being deleted. See the \fBs\fP modifier for more info. See also the | A \fBp\fP indicates that a rule is perishable, meaning that it is ignored in |
protect (P) and risk (R) rules, which are an alternate way to | directories that are being deleted. For instance, the \fB\-C\fP option's default |
specify receiver\-side includes/excludes. | rules that exclude things like "CVS" and "\fB*.o\fP" are marked as perishable, |
.IP o | and will not prevent a directory that was removed on the source from being |
A \fBp\fP indicates that a rule is perishable, meaning that it is | deleted on the destination. |
ignored in directories that are being deleted. For instance, the \fB\-C\fP | .IP o |
option\(cq\&s default rules that exclude things like \(dq\&CVS\(dq\& and \(dq\&*.o\(dq\& are | An \fBm(CHMOD)\fP on an include rule tweaks the permissions of matching |
marked as perishable, and will not prevent a directory that was removed | source files in the same way as \fB\-\-chmod\fP. This happens before any tweaks |
on the source from being deleted on the destination. | requested via \fB\-\-chmod\fP options. |
| .IP o |
.PP | An \fBo(USER)\fP on an include rule pretends that matching source files are |
.SH "MERGE\-FILE FILTER RULES" | owned by \fBUSER\fP (a name or numeric uid). This happens before any uid mapping |
| by name or \fB\-\-usermap\fP. |
.PP | .IP o |
You can merge whole files into your filter rules by specifying either a | A \fBg(GROUP)\fP on an include rule pretends that matching source files are |
merge (.) or a dir\-merge (:) filter rule (as introduced in the FILTER RULES | owned by \fBGROUP\fP (a name or numeric gid). This happens before any gid |
section above). | mapping by name or \fB\-\-groupmap\fP. |
.PP | .IP o |
There are two kinds of merged files \-\- single\-instance (\(cq\&.\(cq\&) and | An \fBx\fP indicates that a rule affects xattr names in xattr copy/delete |
per\-directory (\(cq\&:\(cq\&). A single\-instance merge file is read one time, and | operations (and is thus ignored when matching file/dir names). If no |
its rules are incorporated into the filter list in the place of the \(dq\&.\(dq\& | xattr-matching rules are specified, a default xattr filtering rule is used |
rule. For per\-directory merge files, rsync will scan every directory that | (see the \fB\-\-xattrs\fP option). |
it traverses for the named file, merging its contents when the file exists | .P |
into the current list of inherited rules. These per\-directory rule files | .SH "MERGE-FILE FILTER RULES" |
must be created on the sending side because it is the sending side that is | .P |
being scanned for the available files to transfer. These rule files may | You can merge whole files into your filter rules by specifying either a merge |
also need to be transferred to the receiving side if you want them to | (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES section |
affect what files don\(cq\&t get deleted (see PER\-DIRECTORY RULES AND DELETE | above). |
below). | .P |
.PP | There are two kinds of merged files\ \-\- single-instance ('.') and per-directory |
| (':'). A single-instance merge file is read one time, and its rules are |
| incorporated into the filter list in the place of the "." rule. For |
| per-directory merge files, rsync will scan every directory that it traverses |
| for the named file, merging its contents when the file exists into the current |
| list of inherited rules. These per-directory rule files must be created on the |
| sending side because it is the sending side that is being scanned for the |
| available files to transfer. These rule files may also need to be transferred |
| to the receiving side if you want them to affect what files don't get deleted |
| (see PER-DIRECTORY RULES AND DELETE below). |
| .P |
Some examples: |
Some examples: |
.PP | .RS 4 |
.RS | .P |
\f(CWmerge /etc/rsync/default.rules\fP | .nf |
.br | merge /etc/rsync/default.rules |
\f(CW. /etc/rsync/default.rules\fP | \&. /etc/rsync/default.rules |
.br | dir-merge .per-dir-filter |
\f(CWdir\-merge .per\-dir\-filter\fP | dir-merge,n- .non-inherited-per-dir-excludes |
.br | :n- .non-inherited-per-dir-excludes |
\f(CWdir\-merge,n\- .non\-inherited\-per\-dir\-excludes\fP | .fi |
.br | |
\f(CW:n\- .non\-inherited\-per\-dir\-excludes\fP | |
.br | |
.RE |
.RE |
| .P |
.PP | The following modifiers are accepted after a merge or dir-merge rule: |
The following modifiers are accepted after a merge or dir\-merge rule: | .P |
.PP | .IP o |
.IP o | A \fB\-\fP specifies that the file should consist of only exclude patterns, with |
A \fB\-\fP specifies that the file should consist of only exclude | no other rule-parsing except for in-file comments. |
patterns, with no other rule\-parsing except for in\-file comments. | .IP o |
.IP o | A \fB+\fP specifies that the file should consist of only include patterns, with |
A \fB+\fP specifies that the file should consist of only include | no other rule-parsing except for in-file comments. |
patterns, with no other rule\-parsing except for in\-file comments. | .IP o |
.IP o | A \fBC\fP is a way to specify that the file should be read in a CVS-compatible |
A \fBC\fP is a way to specify that the file should be read in a | manner. This turns on 'n', 'w', and '\-', but also allows the list-clearing |
CVS\-compatible manner. This turns on \(cq\&n\(cq\&, \(cq\&w\(cq\&, and \(cq\&\-\(cq\&, but also | token (!) to be specified. If no filename is provided, ".cvsignore" is |
allows the list\-clearing token (!) to be specified. If no filename is | assumed. |
provided, \(dq\&.cvsignore\(dq\& is assumed. | .IP o |
.IP o | A \fBe\fP will exclude the merge-file name from the transfer; e.g. "dir-merge,e |
A \fBe\fP will exclude the merge\-file name from the transfer; e.g. | \&.rules" is like "dir-merge .rules" and "\- .rules". |
\(dq\&dir\-merge,e .rules\(dq\& is like \(dq\&dir\-merge .rules\(dq\& and \(dq\&\- .rules\(dq\&. | .IP o |
.IP o | |
An \fBn\fP specifies that the rules are not inherited by subdirectories. |
An \fBn\fP specifies that the rules are not inherited by subdirectories. |
.IP o | .IP o |
A \fBw\fP specifies that the rules are word\-split on whitespace instead | A \fBw\fP specifies that the rules are word-split on whitespace instead of the |
of the normal line\-splitting. This also turns off comments. Note: the | normal line-splitting. This also turns off comments. Note: the space that |
space that separates the prefix from the rule is treated specially, so | separates the prefix from the rule is treated specially, so "\- foo + bar" is |
\(dq\&\- foo + bar\(dq\& is parsed as two rules (assuming that prefix\-parsing wasn\(cq\&t | parsed as two rules (assuming that prefix-parsing wasn't also disabled). |
also disabled). | .IP o |
.IP o | You may also specify any of the modifiers for the "+" or "\-" rules (above) in |
You may also specify any of the modifiers for the \(dq\&+\(dq\& or \(dq\&\-\(dq\& rules | order to have the rules that are read in from the file default to having that |
(above) in order to have the rules that are read in from the file | modifier set (except for the \fB!\fP modifier, which would not be useful). For |
default to having that modifier set (except for the \fB!\fP modifier, which | instance, "merge,\-/ .excl" would treat the contents of .excl as absolute-path |
would not be useful). For instance, \(dq\&merge,\-/ .excl\(dq\& would | excludes, while "dir-merge,s .filt" and ":sC" would each make all their |
treat the contents of .excl as absolute\-path excludes, | per-directory rules apply only on the sending side. If the merge rule |
while \(dq\&dir\-merge,s .filt\(dq\& and \(dq\&:sC\(dq\& would each make all their | specifies sides to affect (via the \fBs\fP or \fBr\fP modifier or both), then the |
per\-directory rules apply only on the sending side. If the merge rule | rules in the file must not specify sides (via a modifier or a rule prefix |
specifies sides to affect (via the \fBs\fP or \fBr\fP modifier or both), | such as \fBhide\fP). |
then the rules in the file must not specify sides (via a modifier or | .P |
a rule prefix such as \fBhide\fP). | The attribute-affecting modifiers \fBm\fP, \fBo\fP, and \fBg\fP work only in client filters |
| (not in daemon filters), and only the modifiers of the first matching rule are |
.PP | applied. As an example, assuming \fB\-\-super\fP is enabled, the rule |
Per\-directory rules are inherited in all subdirectories of the directory | "\fB+o(root),g(root),m(go=)\ *~\fP" would ensure that all "backup" |
where the merge\-file was found unless the \(cq\&n\(cq\& modifier was used. Each | files belong to root and are not accessible to anyone else. |
subdirectory\(cq\&s rules are prefixed to the inherited per\-directory rules | .P |
from its parents, which gives the newest rules a higher priority than the | Per-directory rules are inherited in all subdirectories of the directory where |
inherited rules. The entire set of dir\-merge rules are grouped together in | the merge-file was found unless the 'n' modifier was used. Each subdirectory's |
the spot where the merge\-file was specified, so it is possible to override | rules are prefixed to the inherited per-directory rules from its parents, which |
dir\-merge rules via a rule that got specified earlier in the list of global | gives the newest rules a higher priority than the inherited rules. The entire |
rules. When the list\-clearing rule (\(dq\&!\(dq\&) is read from a per\-directory | set of dir-merge rules are grouped together in the spot where the merge-file |
file, it only clears the inherited rules for the current merge file. | was specified, so it is possible to override dir-merge rules via a rule that |
.PP | got specified earlier in the list of global rules. When the list-clearing rule |
Another way to prevent a single rule from a dir\-merge file from being inherited is to | ("!") is read from a per-directory file, it only clears the inherited rules for |
anchor it with a leading slash. Anchored rules in a per\-directory | the current merge file. |
merge\-file are relative to the merge\-file\(cq\&s directory, so a pattern \(dq\&/foo\(dq\& | .P |
would only match the file \(dq\&foo\(dq\& in the directory where the dir\-merge filter | Another way to prevent a single rule from a dir-merge file from being inherited |
| is to anchor it with a 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 where the dir-merge filter |
file was found. |
file was found. |
.PP | .P |
Here\(cq\&s an example filter file which you\(cq\&d specify via \fB\-\-filter=\(dq\&. file\(dq\&:\fP | Here's an example filter file which you'd specify via \fB\-\-filter=".\ file":\fP |
.PP | .RS 4 |
.RS | .P |
\f(CWmerge /home/user/.global\-filter\fP | .nf |
.br | merge /home/user/.global-filter |
\f(CW\- *.gz\fP | - *.gz |
.br | dir-merge .rules |
\f(CWdir\-merge .rules\fP | + *.[ch] |
.br | - *.o |
\f(CW+ *.[ch]\fP | - foo* |
.br | .fi |
\f(CW\- *.o\fP | |
.br | |
.RE |
.RE |
| .P |
.PP | This will merge the contents of the /home/user/.global-filter file at the start |
This will merge the contents of the /home/user/.global\-filter file at the | of the list and also turns the ".rules" filename into a per-directory filter |
start of the list and also turns the \(dq\&.rules\(dq\& filename into a per\-directory | file. All rules read in prior to the start of the directory scan follow the |
filter file. All rules read in prior to the start of the directory scan | global anchoring rules (i.e. a leading slash matches at the root of the |
follow the global anchoring rules (i.e. a leading slash matches at the root | transfer). |
of the transfer). | .P |
.PP | If a per-directory merge-file is specified with a path that is a parent |
If a per\-directory merge\-file is specified with a path that is a parent | directory of the first transfer directory, rsync will scan all the parent dirs |
directory of the first transfer directory, rsync will scan all the parent | from that starting point to the transfer directory for the indicated |
dirs from that starting point to the transfer directory for the indicated | per-directory file. For instance, here is a common filter (see \fB\-F\fP): |
per\-directory file. For instance, here is a common filter (see \fB\-F\fP): | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CW\-\-filter='\&: /.rsync\-filter'\&\fP | --filter=': /.rsync-filter' |
| .fi |
.RE |
.RE |
| .P |
.PP | That rule tells rsync to scan for the file .rsync-filter in all directories |
That rule tells rsync to scan for the file .rsync\-filter in all | from the root down through the parent directory of the transfer prior to the |
directories from the root down through the parent directory of the | start of the normal directory scan of the file in the directories that are sent |
transfer prior to the start of the normal directory scan of the file in | as a part of the transfer. (Note: for an rsync daemon, the root is always the |
the directories that are sent as a part of the transfer. (Note: for an | same as the module's "path".) |
rsync daemon, the root is always the same as the module\(cq\&s \(dq\&path\(dq\&.) | .P |
.PP | Some examples of this pre-scanning for per-directory files: |
Some examples of this pre\-scanning for per\-directory files: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWrsync \-avF /src/path/ /dest/dir\fP | rsync -avF /src/path/ /dest/dir |
.br | rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir |
\f(CWrsync \-av \-\-filter='\&: ../../.rsync\-filter'\& /src/path/ /dest/dir\fP | rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir |
.br | .fi |
\f(CWrsync \-av \-\-filter='\&: .rsync\-filter'\& /src/path/ /dest/dir\fP | |
.br | |
.RE |
.RE |
| .P |
.PP | The first two commands above will look for ".rsync-filter" in "/" and "/src" |
The first two commands above will look for \(dq\&.rsync\-filter\(dq\& in \(dq\&/\(dq\& and | before the normal scan begins looking for the file in "/src/path" and its |
\(dq\&/src\(dq\& before the normal scan begins looking for the file in \(dq\&/src/path\(dq\& | subdirectories. The last command avoids the parent-dir scan and only looks for |
and its subdirectories. The last command avoids the parent\-dir scan | the ".rsync-filter" files in each directory that is a part of the transfer. |
and only looks for the \(dq\&.rsync\-filter\(dq\& files in each directory that is | .P |
a part of the transfer. | If you want to include the contents of a ".cvsignore" in your patterns, you |
.PP | should use the rule ":C", which creates a dir-merge of the .cvsignore file, but |
If you want to include the contents of a \(dq\&.cvsignore\(dq\& in your patterns, | parsed in a CVS-compatible manner. You can use this to affect where the |
you should use the rule \(dq\&:C\(dq\&, which creates a dir\-merge of the .cvsignore | \fB\-\-cvs-exclude\fP (\fB\-C\fP) option's inclusion of the per-directory .cvsignore file |
file, but parsed in a CVS\-compatible manner. You can | gets placed into your rules by putting the ":C" wherever you like in your |
use this to affect where the \fB\-\-cvs\-exclude\fP (\fB\-C\fP) option\(cq\&s inclusion of the | filter rules. Without this, rsync would add the dir-merge rule for the |
per\-directory .cvsignore file gets placed into your rules by putting the | \&.cvsignore file at the end of all your other rules (giving it a lower priority |
\(dq\&:C\(dq\& wherever you like in your filter rules. Without this, rsync would | than your command-line rules). For example: |
add the dir\-merge rule for the .cvsignore file at the end of all your other | .RS 4 |
rules (giving it a lower priority than your command\-line rules). For | .P |
example: | .nf |
.PP | cat <<EOT | rsync -avC --filter='. -' a/ b |
.RS | + foo.o |
\f(CWcat <<EOT | rsync \-avC \-\-filter='\&. \-'\& a/ b\fP | :C |
.br | - *.old |
\f(CW+ foo.o\fP | EOT |
.br | rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b |
\f(CW:C\fP | .fi |
.br | |
\f(CW\- *.old\fP | |
.br | |
\f(CWEOT\fP | |
.br | |
\f(CWrsync \-avC \-\-include=foo.o \-f :C \-\-exclude='\&*.old'\& a/ b\fP | |
.br | |
.RE |
.RE |
| .P |
.PP | Both of the above rsync commands are identical. Each one will merge all the |
Both of the above rsync commands are identical. Each one will merge all | per-directory .cvsignore rules in the middle of the list rather than at the |
the per\-directory .cvsignore rules in the middle of the list rather than | end. This allows their dir-specific rules to supersede the rules that follow |
at the end. This allows their dir\-specific rules to supersede the rules | the :C instead of being subservient to all your rules. To affect the other CVS |
that follow the :C instead of being subservient to all your rules. To | exclude rules (i.e. the default list of exclusions, the contents of |
affect the other CVS exclude rules (i.e. the default list of exclusions, | $HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the \fB\-C\fP |
the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should | command-line option and instead insert a "\-C" rule into your filter rules; e.g. |
omit the \fB\-C\fP command\-line option and instead insert a \(dq\&\-C\(dq\& rule into | "\fB\-\-filter=\-C\fP". |
your filter rules; e.g. \(dq\&\fB\-\-filter=\-C\fP\(dq\&. | .P |
.PP | .SH "LIST-CLEARING FILTER RULE" |
.SH "LIST\-CLEARING FILTER RULE" | .P |
| You can clear the current include/exclude list by using the "!" filter rule (as |
.PP | introduced in the FILTER RULES section above). The "current" list is either |
You can clear the current include/exclude list by using the \(dq\&!\(dq\& filter | the global list of rules (if the rule is encountered while parsing the filter |
rule (as introduced in the FILTER RULES section above). The \(dq\¤t\(dq\& | options) or a set of per-directory rules (which are inherited in their own |
list is either the global list of rules (if the rule is encountered while | sub-list, so a subdirectory can use this to clear out the parent's rules). |
parsing the filter options) or a set of per\-directory rules (which are | .P |
inherited in their own sub\-list, so a subdirectory can use this to clear | |
out the parent\(cq\&s rules). | |
.PP | |
.SH "ANCHORING INCLUDE/EXCLUDE PATTERNS" |
.SH "ANCHORING INCLUDE/EXCLUDE PATTERNS" |
| .P |
.PP | As mentioned earlier, global include/exclude patterns are anchored at the "root |
As mentioned earlier, global include/exclude patterns are anchored at the | of the transfer" (as opposed to per-directory patterns, which are anchored at |
\(dq\&root of the transfer\(dq\& (as opposed to per\-directory patterns, which are | the merge-file's directory). If you think of the transfer as a subtree of |
anchored at the merge\-file\(cq\&s directory). If you think of the transfer as | names that are being sent from sender to receiver, the transfer-root is where |
a subtree of names that are being sent from sender to receiver, the | the tree starts to be duplicated in the destination directory. This root |
transfer\-root is where the tree starts to be duplicated in the destination | governs where patterns that start with a / match. |
directory. This root governs where patterns that start with a / match. | .P |
.PP | Because the matching is relative to the transfer-root, changing the trailing |
Because the matching is relative to the transfer\-root, changing the | slash on a source path or changing your use of the \fB\-\-relative\fP option affects |
trailing slash on a source path or changing your use of the \fB\-\-relative\fP | the path you need to use in your matching (in addition to changing how much of |
option affects the path you need to use in your matching (in addition to | the file tree is duplicated on the destination host). The following examples |
changing how much of the file tree is duplicated on the destination | demonstrate this. |
host). The following examples demonstrate this. | .P |
.PP | Let's say that we want to match two source files, one with an absolute |
Let\(cq\&s say that we want to match two source files, one with an absolute | path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz". |
path of \(dq\&/home/me/foo/bar\(dq\&, and one with a path of \(dq\&/home/you/bar/baz\(dq\&. | Here is how the various command choices differ for a 2-source transfer: |
Here is how the various command choices differ for a 2\-source transfer: | .RS 4 |
.PP | .P |
.RS | .nf |
Example cmd: rsync \-a /home/me /home/you /dest | Example cmd: rsync -a /home/me /home/you /dest |
.br | +/- pattern: /me/foo/bar |
+/\- pattern: /me/foo/bar | +/- pattern: /you/bar/baz |
.br | Target file: /dest/me/foo/bar |
+/\- pattern: /you/bar/baz | Target file: /dest/you/bar/baz |
.br | .fi |
Target file: /dest/me/foo/bar | |
.br | |
Target file: /dest/you/bar/baz | |
.br | |
.RE |
.RE |
| .RS 4 |
.PP | .P |
.RS | .nf |
Example cmd: rsync \-a /home/me/ /home/you/ /dest | Example cmd: rsync -a /home/me/ /home/you/ /dest |
.br | +/- pattern: /foo/bar (note missing "me") |
+/\- pattern: /foo/bar (note missing \(dq\&me\(dq\&) | +/- pattern: /bar/baz (note missing "you") |
.br | Target file: /dest/foo/bar |
+/\- pattern: /bar/baz (note missing \(dq\&you\(dq\&) | Target file: /dest/bar/baz |
.br | .fi |
Target file: /dest/foo/bar | |
.br | |
Target file: /dest/bar/baz | |
.br | |
.RE |
.RE |
| .RS 4 |
.PP | .P |
.RS | .nf |
Example cmd: rsync \-a \-\-relative /home/me/ /home/you /dest | Example cmd: rsync -a --relative /home/me/ /home/you /dest |
.br | +/- pattern: /home/me/foo/bar (note full path) |
+/\- pattern: /home/me/foo/bar (note full path) | +/- pattern: /home/you/bar/baz (ditto) |
.br | Target file: /dest/home/me/foo/bar |
+/\- pattern: /home/you/bar/baz (ditto) | Target file: /dest/home/you/bar/baz |
.br | .fi |
Target file: /dest/home/me/foo/bar | |
.br | |
Target file: /dest/home/you/bar/baz | |
.br | |
.RE |
.RE |
| .RS 4 |
.PP | .P |
.RS | .nf |
Example cmd: cd /home; rsync \-a \-\-relative me/foo you/ /dest | Example cmd: cd /home; rsync -a --relative me/foo you/ /dest |
.br | +/- pattern: /me/foo/bar (starts at specified path) |
+/\- pattern: /me/foo/bar (starts at specified path) | +/- pattern: /you/bar/baz (ditto) |
.br | Target file: /dest/me/foo/bar |
+/\- pattern: /you/bar/baz (ditto) | Target file: /dest/you/bar/baz |
.br | .fi |
Target file: /dest/me/foo/bar | |
.br | |
Target file: /dest/you/bar/baz | |
.br | |
.RE |
.RE |
| .P |
.PP | |
The easiest way to see what name you should filter is to just |
The easiest way to see what name you should filter is to just |
look at the output when using \fB\-\-verbose\fP and put a / in front of the name |
look at the output when using \fB\-\-verbose\fP and put a / in front of the name |
(use the \fB\-\-dry\-run\fP option if you\(cq\&re not yet ready to copy any files). | (use the \fB\-\-dry-run\fP option if you're not yet ready to copy any files). |
.PP | .P |
.SH "PER\-DIRECTORY RULES AND DELETE" | .SH "PER-DIRECTORY RULES AND DELETE" |
| .P |
.PP | Without a delete option, per-directory rules are only relevant on the sending |
Without a delete option, per\-directory rules are only relevant on the | side, so you can feel free to exclude the merge files themselves without |
sending side, so you can feel free to exclude the merge files themselves | affecting the transfer. To make this easy, the 'e' modifier adds this exclude |
without affecting the transfer. To make this easy, the \(cq\&e\(cq\& modifier adds | for you, as seen in these two equivalent commands: |
this exclude for you, as seen in these two equivalent commands: | .RS 4 |
.PP | .P |
.RS | .nf |
\f(CWrsync \-av \-\-filter='\&: .excl'\& \-\-exclude=.excl host:src/dir /dest\fP | rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest |
.br | rsync -av --filter=':e .excl' host:src/dir /dest |
\f(CWrsync \-av \-\-filter='\&:e .excl'\& host:src/dir /dest\fP | .fi |
.br | |
.RE |
.RE |
| .P |
.PP | |
However, if you want to do a delete on the receiving side AND you want some |
However, if you want to do a delete on the receiving side AND you want some |
files to be excluded from being deleted, you\(cq\&ll need to be sure that the | files to be excluded from being deleted, you'll need to be sure that the |
receiving side knows what files to exclude. The easiest way is to include | receiving side knows what files to exclude. The easiest way is to include the |
the per\-directory merge files in the transfer and use \fB\-\-delete\-after\fP, | per-directory merge files in the transfer and use \fB\-\-delete-after\fP, because |
because this ensures that the receiving side gets all the same exclude | this ensures that the receiving side gets all the same exclude rules as the |
rules as the sending side before it tries to delete anything: | sending side before it tries to delete anything: |
.PP | .RS 4 |
.RS | .P |
\f(CWrsync \-avF \-\-delete\-after host:src/dir /dest\fP | .nf |
| rsync -avF --delete-after host:src/dir /dest |
| .fi |
.RE |
.RE |
| .P |
.PP | However, if the merge files are not a part of the transfer, you'll need to |
However, if the merge files are not a part of the transfer, you\(cq\&ll need to | either specify some global exclude rules (i.e. specified on the command line), |
either specify some global exclude rules (i.e. specified on the command | or you'll need to maintain your own per-directory merge files on the receiving |
line), or you\(cq\&ll need to maintain your own per\-directory merge files on | side. An example of the first is this (assume that the remote .rules files |
the receiving side. An example of the first is this (assume that the | exclude themselves): |
remote .rules files exclude themselves): | .RS 4 |
.PP | .P |
.nf | .nf |
rsync \-av \-\-filter=\(cq\&: .rules\(cq\& \-\-filter=\(cq\&. /my/extra.rules\(cq\& | rsync -av --filter=': .rules' --filter='. /my/extra.rules' |
\-\-delete host:src/dir /dest | --delete host:src/dir /dest |
.fi | .fi |
| .RE |
.PP | .P |
In the above example the extra.rules file can affect both sides of the |
In the above example the extra.rules file can affect both sides of the |
transfer, but (on the sending side) the rules are subservient to the rules |
transfer, but (on the sending side) the rules are subservient to the rules |
merged from the .rules files because they were specified after the |
merged from the .rules files because they were specified after the |
per\-directory merge rule. | per-directory merge rule. |
.PP | .P |
In one final example, the remote side is excluding the .rsync\-filter | In one final example, the remote side is excluding the .rsync-filter files from |
files from the transfer, but we want to use our own .rsync\-filter files | the transfer, but we want to use our own .rsync-filter files to control what |
to control what gets deleted on the receiving side. To do this we must | gets deleted on the receiving side. To do this we must specifically exclude |
specifically exclude the per\-directory merge files (so that they don\(cq\&t get | the per-directory merge files (so that they don't get deleted) and then put |
deleted) and then put rules into the local files to control what else | rules into the local files to control what else should not get deleted. Like |
should not get deleted. Like one of these commands: | one of these commands: |
.PP | .RS 4 |
.nf | .P |
rsync \-av \-\-filter='\&:e /.rsync\-filter'\& \-\-delete \e | .nf |
host:src/dir /dest | rsync -av --filter=':e /.rsync-filter' --delete \\ |
rsync \-avFF \-\-delete host:src/dir /dest | host:src/dir /dest |
.fi | rsync -avFF --delete host:src/dir /dest |
| .fi |
.PP | .RE |
| .P |
.SH "BATCH MODE" |
.SH "BATCH MODE" |
| .P |
.PP | 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 | systems. Suppose one has a tree which is replicated on a number of hosts. Now |
identical systems. Suppose one has a tree which is replicated on a | suppose some changes have been made to this source tree and those changes need |
number of hosts. Now suppose some changes have been made to this | to be propagated to the other hosts. In order to do this using batch mode, |
source tree and those changes need to be propagated to the other | rsync is run with the write-batch option to apply the changes made to the |
hosts. In order to do this using batch mode, rsync is run with the | source tree to one of the destination trees. The write-batch option causes the |
write\-batch option to apply the changes made to the source tree to one | rsync client to store in a "batch file" all the information needed to repeat |
of the destination trees. The write\-batch option causes the rsync | |
client to store in a \(dq\&batch file\(dq\& all the information needed to repeat | |
this operation against other, identical destination trees. |
this operation against other, identical destination trees. |
.PP | .P |
Generating the batch file once saves having to perform the file | Generating the batch file once saves having to perform the file status, |
status, checksum, and data block generation more than once when | checksum, and data block generation more than once when updating multiple |
updating multiple destination trees. Multicast transport protocols can | destination trees. Multicast transport protocols can be used to transfer the |
be used to transfer the batch update files in parallel to many hosts | batch update files in parallel to many hosts at once, instead of sending the |
at once, instead of sending the same data to every host individually. | same data to every host individually. |
.PP | .P |
To apply the recorded changes to another destination tree, run rsync | To apply the recorded changes to another destination tree, run rsync with the |
with the read\-batch option, specifying the name of the same batch | read-batch option, specifying the name of the same batch file, and the |
file, and the destination tree. Rsync updates the destination tree | destination tree. Rsync updates the destination tree using the information |
using the information stored in the batch file. | stored in the batch file. |
.PP | .P |
For your convenience, a script file is also created when the write\-batch | For your convenience, a script file is also created when the write-batch option |
option is used: it will be named the same as the batch file with \(dq\&.sh\(dq\& | is used: it will be named the same as the batch file with ".sh" appended. This |
appended. This script file contains a command\-line suitable for updating a | script file contains a command-line suitable for updating a destination tree |
destination tree using the associated batch file. It can be executed using | using the associated batch file. It can be executed using a Bourne (or |
a Bourne (or Bourne\-like) shell, optionally passing in an alternate | Bourne-like) shell, optionally passing in an alternate destination tree |
destination tree pathname which is then used instead of the original | pathname which is then used instead of the original destination path. This is |
destination path. This is useful when the destination tree path on the | useful when the destination tree path on the current host differs from the one |
current host differs from the one used to create the batch file. | used to create the batch file. |
.PP | .P |
Examples: |
Examples: |
.PP | .RS 4 |
.RS | .P |
\f(CW$ rsync \-\-write\-batch=foo \-a host:/source/dir/ /adest/dir/\fP | .nf |
.br | $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/ |
\f(CW$ scp foo* remote:\fP | $ scp foo* remote: |
.br | $ ssh remote ./foo.sh /bdest/dir/ |
\f(CW$ ssh remote ./foo.sh /bdest/dir/\fP | .fi |
.br | |
.RE |
.RE |
| .RS 4 |
.PP | .P |
.RS | .nf |
\f(CW$ rsync \-\-write\-batch=foo \-a /source/dir/ /adest/dir/\fP | $ rsync --write-batch=foo -a /source/dir/ /adest/dir/ |
.br | $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo |
\f(CW$ ssh remote rsync \-\-read\-batch=\- \-a /bdest/dir/ <foo\fP | .fi |
.br | |
.RE |
.RE |
| .P |
.PP | In these examples, rsync is used to update /adest/dir/ from /source/dir/ and |
In these examples, rsync is used to update /adest/dir/ from /source/dir/ | the information to repeat this operation is stored in "foo" and "foo.sh". The |
and the information to repeat this operation is stored in \(dq\&foo\(dq\& and | host "remote" is then updated with the batched data going into the directory |
\(dq\&foo.sh\(dq\&. The host \(dq\&remote\(dq\& is then updated with the batched data going | /bdest/dir. The differences between the two examples reveals some of the |
into the directory /bdest/dir. The differences between the two examples | flexibility you have in how you deal with batches: |
reveals some of the flexibility you have in how you deal with batches: | .P |
.PP | .IP o |
.IP o | The first example shows that the initial copy doesn't have to be local\ \-\- you |
The first example shows that the initial copy doesn\(cq\&t have to be | can push or pull data to/from a remote host using either the remote-shell |
local \-\- you can push or pull data to/from a remote host using either the | syntax or rsync daemon syntax, as desired. |
remote\-shell syntax or rsync daemon syntax, as desired. | .IP o |
.IP o | The first example uses the created "foo.sh" file to get the right rsync |
The first example uses the created \(dq\&foo.sh\(dq\& file to get the right | options when running the read-batch command on the remote host. |
rsync options when running the read\-batch command on the remote host. | .IP o |
.IP o | The second example reads the batch data via standard input so that the batch |
The second example reads the batch data via standard input so that | file doesn't need to be copied to the remote machine first. This example |
the batch file doesn\(cq\&t need to be copied to the remote machine first. | avoids the foo.sh script because it needed to use a modified \fB\-\-read-batch\fP |
This example avoids the foo.sh script because it needed to use a modified | option, but you could edit the script file if you wished to make use of it |
\fB\-\-read\-batch\fP option, but you could edit the script file if you wished to | (just be sure that no other option is trying to use standard input, such as |
make use of it (just be sure that no other option is trying to use | the "\fB\-\-exclude-from=\-\fP" option). |
standard input, such as the \(dq\&\fB\-\-exclude\-from=\-\fP\(dq\& option). | .P |
| |
.PP | |
Caveats: |
Caveats: |
.PP | .P |
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 be |
to be identical to the destination tree that was used to create the | identical to the destination tree that was used to create the batch update |
batch update fileset. When a difference between the destination trees | fileset. When a difference between the destination trees is encountered the |
is encountered the update might be discarded with a warning (if the file | update might be discarded with a warning (if the file appears to be up-to-date |
appears to be up\-to\-date already) or the file\-update may be attempted | already) or the file-update may be attempted and then, if the file fails to |
and then, if the file fails to verify, the update discarded with an | verify, the update discarded with an error. This means that it should be safe |
error. This means that it should be safe to re\-run a read\-batch operation | to re-run a read-batch operation if the command got interrupted. If you wish |
if the command got interrupted. If you wish to force the batched\-update to | to force the batched-update to always be attempted regardless of the file's |
always be attempted regardless of the file\(cq\&s size and date, use the \fB\-I\fP | size and date, use the \fB\-I\fP option (when reading the batch). If an error |
option (when reading the batch). | occurs, the destination tree will probably be in a partially updated state. In |
If an error occurs, the destination tree will probably be in a | that case, rsync can be used in its regular (non-batch) mode of operation to |
partially updated state. In that case, rsync can | fix up the destination tree. |
be used in its regular (non\-batch) mode of operation to fix up the | .P |
destination tree. | The rsync version used on all destinations must be at least as new as the one |
.PP | used to generate the batch file. Rsync will die with an error if the protocol |
The rsync version used on all destinations must be at least as new as the | version in the batch file is too new for the batch-reading rsync to handle. |
one used to generate the batch file. Rsync will die with an error if the | See also the \fB\-\-protocol\fP option for a way to have the creating rsync generate |
protocol version in the batch file is too new for the batch\-reading rsync | a batch file that an older rsync can understand. (Note that batch files |
to handle. See also the \fB\-\-protocol\fP option for a way to have the | changed format in version 2.6.3, so mixing versions older than that with newer |
creating rsync generate a batch file that an older rsync can understand. | versions will not work.) |
(Note that batch files changed format in version 2.6.3, so mixing versions | .P |
older than that with newer versions will not work.) | When reading a batch file, rsync will force the value of certain options to |
.PP | match the data in the batch file if you didn't set them to the same as the |
When reading a batch file, rsync will force the value of certain options | batch-writing command. Other options can (and should) be changed. For |
to match the data in the batch file if you didn\(cq\&t set them to the same | instance \fB\-\-write-batch\fP changes to \fB\-\-read-batch\fP, \fB\-\-files-from\fP is dropped, |
as the batch\-writing command. Other options can (and should) be changed. | and the \fB\-\-filter\fP / \fB\-\-include\fP / \fB\-\-exclude\fP options are not needed unless |
For instance \fB\-\-write\-batch\fP changes to \fB\-\-read\-batch\fP, | |
\fB\-\-files\-from\fP is dropped, and the | |
\fB\-\-filter\fP/\fB\-\-include\fP/\fB\-\-exclude\fP options are not needed unless | |
one of the \fB\-\-delete\fP options is specified. |
one of the \fB\-\-delete\fP options is specified. |
.PP | .P |
The code that creates the BATCH.sh file transforms any filter/include/exclude |
The code that creates the BATCH.sh file transforms any filter/include/exclude |
options into a single list that is appended as a \(dq\&here\(dq\& document to the | options into a single list that is appended as a "here" document to the shell |
shell script file. An advanced user can use this to modify the exclude | script file. An advanced user can use this to modify the exclude list if a |
list if a change in what gets deleted by \fB\-\-delete\fP is desired. A normal | change in what gets deleted by \fB\-\-delete\fP is desired. A normal user can ignore |
user can ignore this detail and just use the shell script as an easy way | this detail and just use the shell script as an easy way to run the appropriate |
to run the appropriate \fB\-\-read\-batch\fP command for the batched data. | \fB\-\-read-batch\fP command for the batched data. |
.PP | .P |
The original batch mode in rsync was based on \(dq\&rsync+\(dq\&, but the latest | The original batch mode in rsync was based on "rsync+", but the latest |
version uses a new implementation. |
version uses a new implementation. |
.PP | .P |
.SH "SYMBOLIC LINKS" |
.SH "SYMBOLIC LINKS" |
| .P |
.PP | |
Three basic behaviors are possible when rsync encounters a symbolic |
Three basic behaviors are possible when rsync encounters a symbolic |
link in the source directory. |
link in the source directory. |
.PP | .P |
By default, symbolic links are not transferred at all. A message | By default, symbolic links are not transferred at all. A message "skipping |
\(dq\&skipping non\-regular\(dq\& file is emitted for any symlinks that exist. | non-regular" file is emitted for any symlinks that exist. |
.PP | .P |
If \fB\-\-links\fP is specified, then symlinks are recreated with the same | If \fB\-\-links\fP is specified, then symlinks are recreated with the same target on |
target on the destination. Note that \fB\-\-archive\fP implies | the destination. Note that \fB\-\-archive\fP implies \fB\-\-links\fP. |
\fB\-\-links\fP. | .P |
.PP | If \fB\-\-copy-links\fP is specified, then symlinks are "collapsed" by |
If \fB\-\-copy\-links\fP is specified, then symlinks are \(dq\&collapsed\(dq\& by | |
copying their referent, rather than the symlink. |
copying their referent, rather than the symlink. |
.PP | .P |
Rsync can also distinguish \(dq\&safe\(dq\& and \(dq\&unsafe\(dq\& symbolic links. An | Rsync can also distinguish "safe" and "unsafe" symbolic links. An example |
example where this might be used is a web site mirror that wishes to | where this might be used is a web site mirror that wishes to ensure that the |
ensure that the rsync module that is copied does not include symbolic links to | rsync module that is copied does not include symbolic links to \fB/etc/passwd\fP in |
\fB/etc/passwd\fP in the public section of the site. Using | the public section of the site. Using \fB\-\-copy-unsafe-links\fP will cause any |
\fB\-\-copy\-unsafe\-links\fP will cause any links to be copied as the file | links to be copied as the file they point to on the destination. Using |
they point to on the destination. Using \fB\-\-safe\-links\fP will cause | \fB\-\-safe-links\fP will cause unsafe links to be omitted altogether. (Note that you |
unsafe links to be omitted altogether. (Note that you must specify | must specify \fB\-\-links\fP for \fB\-\-safe-links\fP to have any effect.) |
\fB\-\-links\fP for \fB\-\-safe\-links\fP to have any effect.) | .P |
.PP | |
Symbolic links are considered unsafe if they are absolute symlinks |
Symbolic links are considered unsafe if they are absolute symlinks |
(start with \fB/\fP), empty, or if they contain enough \(dq\&..\(dq\& | (start with \fB/\fP), empty, or if they contain enough ".." |
components to ascend from the directory being copied. |
components to ascend from the directory being copied. |
.PP | .P |
Here\(cq\&s a summary of how the symlink options are interpreted. The list is | Here's a summary of how the symlink options are interpreted. The list is in |
in order of precedence, so if your combination of options isn\(cq\&t mentioned, | order of precedence, so if your combination of options isn't mentioned, use the |
use the first line that is a complete subset of your options: | first line that is a complete subset of your options: |
.PP | .P |
.IP "\fB\-\-copy\-links\fP" | .IP "\fB\-\-copy-links\fP" |
Turn all symlinks into normal files (leaving no | Turn all symlinks into normal files (leaving no symlinks for |
symlinks for any other options to affect). | any other options to affect). |
.PP | .IP "\fB\-\-links\ \-\-copy-unsafe-links\fP" |
.IP "\fB\-\-links \-\-copy\-unsafe\-links\fP" | Turn all unsafe symlinks into files and |
Turn all unsafe symlinks into files | duplicate all safe symlinks. |
and duplicate all safe symlinks. | .IP "\fB\-\-copy-unsafe-links\fP" |
.PP | Turn all unsafe symlinks into files, noisily skip all |
.IP "\fB\-\-copy\-unsafe\-links\fP" | safe symlinks. |
Turn all unsafe symlinks into files, noisily | .IP "\fB\-\-links\ \-\-safe-links\fP" |
skip all safe symlinks. | Duplicate safe symlinks and skip unsafe ones. |
.PP | |
.IP "\fB\-\-links \-\-safe\-links\fP" | |
Duplicate safe symlinks and skip unsafe | |
ones. | |
.PP | |
.IP "\fB\-\-links\fP" |
.IP "\fB\-\-links\fP" |
Duplicate all symlinks. |
Duplicate all symlinks. |
.PP | .P |
.SH "DIAGNOSTICS" |
.SH "DIAGNOSTICS" |
| .P |
.PP | rsync occasionally produces error messages that may seem a little cryptic. The |
rsync occasionally produces error messages that may seem a little | one that seems to cause the most confusion is "protocol version mismatch\ \-\- is |
cryptic. The one that seems to cause the most confusion is \(dq\&protocol | your shell clean?". |
version mismatch \-\- is your shell clean?\(dq\&. | .P |
.PP | This message is usually caused by your startup scripts or remote shell facility |
This message is usually caused by your startup scripts or remote shell | producing unwanted garbage on the stream that rsync is using for its transport. |
facility producing unwanted garbage on the stream that rsync is using | The way to diagnose this problem is to run your remote shell like this: |
for its transport. The way to diagnose this problem is to run your | .RS 4 |
remote shell like this: | .P |
.PP | .nf |
.RS | ssh remotehost /bin/true > out.dat |
\f(CWssh remotehost /bin/true > out.dat\fP | .fi |
.RE |
.RE |
| .P |
.PP | then look at out.dat. If everything is working correctly then out.dat should |
then look at out.dat. If everything is working correctly then out.dat | be a zero length file. If you are getting the above error from rsync then you |
should be a zero length file. If you are getting the above error from | will probably find that out.dat contains some text or data. Look at the |
rsync then you will probably find that out.dat contains some text or | contents and try to work out what is producing it. The most common cause is |
data. Look at the contents and try to work out what is producing | incorrectly configured shell startup scripts (such as .cshrc or .profile) that |
it. The most common cause is incorrectly configured shell startup | contain output statements for non-interactive logins. |
scripts (such as .cshrc or .profile) that contain output statements | .P |
for non\-interactive logins. | If you are having trouble debugging filter patterns, then try specifying the |
.PP | \fB\-vv\fP option. At this level of verbosity rsync will show why each individual |
If you are having trouble debugging filter patterns, then | file is included or excluded. |
try specifying the \fB\-vv\fP option. At this level of verbosity rsync will | .P |
show why each individual file is included or excluded. | |
.PP | |
.SH "EXIT VALUES" |
.SH "EXIT VALUES" |
| .P |
.PP | |
.IP "\fB0\fP" |
.IP "\fB0\fP" |
Success |
Success |
.IP "\fB1\fP" |
.IP "\fB1\fP" |
Line 3849 Protocol incompatibility
|
Line 4477 Protocol incompatibility
|
.IP "\fB3\fP" |
.IP "\fB3\fP" |
Errors selecting input/output files, dirs |
Errors selecting input/output files, dirs |
.IP "\fB4\fP" |
.IP "\fB4\fP" |
Requested action not supported: an attempt | Requested action not supported: an attempt was made to manipulate |
was made to manipulate 64\-bit files on a platform that cannot support | 64-bit files on a platform that cannot support them; or an option was |
them; or an option was specified that is supported by the client and | specified that is supported by the client and not by the server. |
not by the server. | |
.IP "\fB5\fP" |
.IP "\fB5\fP" |
Error starting client\-server protocol | Error starting client-server protocol |
.IP "\fB6\fP" |
.IP "\fB6\fP" |
Daemon unable to append to log\-file | Daemon unable to append to log-file |
.IP "\fB10\fP" |
.IP "\fB10\fP" |
Error in socket I/O |
Error in socket I/O |
.IP "\fB11\fP" |
.IP "\fB11\fP" |
Line 3870 Error in IPC code
|
Line 4497 Error in IPC code
|
.IP "\fB20\fP" |
.IP "\fB20\fP" |
Received SIGUSR1 or SIGINT |
Received SIGUSR1 or SIGINT |
.IP "\fB21\fP" |
.IP "\fB21\fP" |
Some error returned by | Some error returned by \fBwaitpid()\fP |
\f(CWwaitpid()\fP | |
.IP "\fB22\fP" |
.IP "\fB22\fP" |
Error allocating core memory buffers |
Error allocating core memory buffers |
.IP "\fB23\fP" |
.IP "\fB23\fP" |
Line 3879 Partial transfer due to error
|
Line 4505 Partial transfer due to error
|
.IP "\fB24\fP" |
.IP "\fB24\fP" |
Partial transfer due to vanished source files |
Partial transfer due to vanished source files |
.IP "\fB25\fP" |
.IP "\fB25\fP" |
The \-\-max\-delete limit stopped deletions | The \-\-max-delete limit stopped deletions |
.IP "\fB30\fP" |
.IP "\fB30\fP" |
Timeout in data send/receive |
Timeout in data send/receive |
.IP "\fB35\fP" |
.IP "\fB35\fP" |
Timeout waiting for daemon connection |
Timeout waiting for daemon connection |
| .P |
.PP | |
.SH "ENVIRONMENT VARIABLES" |
.SH "ENVIRONMENT VARIABLES" |
| .P |
.PP | |
.IP "\fBCVSIGNORE\fP" |
.IP "\fBCVSIGNORE\fP" |
The CVSIGNORE environment variable supplements any | The CVSIGNORE environment variable supplements any ignore patterns in |
ignore patterns in .cvsignore files. See the \fB\-\-cvs\-exclude\fP option for | \&.cvsignore files. See the \fB\-\-cvs-exclude\fP option for more details. |
more details. | |
.IP "\fBRSYNC_ICONV\fP" |
.IP "\fBRSYNC_ICONV\fP" |
Specify a default \fB\-\-iconv\fP setting using this | Specify a default \fB\-\-iconv\fP setting using this environment variable. (First |
environment variable. (First supported in 3.0.0.) | supported in 3.0.0.) |
.IP "\fBRSYNC_PROTECT_ARGS\fP" |
.IP "\fBRSYNC_PROTECT_ARGS\fP" |
Specify a non\-zero numeric value if you want the | Specify a non-zero numeric value if you want the \fB\-\-protect-args\fP option to |
\fB\-\-protect\-args\fP option to be enabled by default, or a zero value to make | be enabled by default, or a zero value to make sure that it is disabled by |
sure that it is disabled by default. (First supported in 3.1.0.) | default. (First supported in 3.1.0.) |
.IP "\fBRSYNC_RSH\fP" |
.IP "\fBRSYNC_RSH\fP" |
The RSYNC_RSH environment variable allows you to | The RSYNC_RSH environment variable allows you to override the default shell |
override the default shell used as the transport for rsync. Command line | used as the transport for rsync. Command line options are permitted after |
options are permitted after the command name, just as in the \fB\-e\fP option. | the command name, just as in the \fB\-e\fP option. |
.IP "\fBRSYNC_PROXY\fP" |
.IP "\fBRSYNC_PROXY\fP" |
The RSYNC_PROXY environment variable allows you to | The RSYNC_PROXY environment variable allows you to redirect your rsync |
redirect your rsync client to use a web proxy when connecting to a | client to use a web proxy when connecting to a rsync daemon. You should |
rsync daemon. You should set RSYNC_PROXY to a hostname:port pair. | set RSYNC_PROXY to a hostname:port pair. |
.IP "\fBRSYNC_PASSWORD\fP" |
.IP "\fBRSYNC_PASSWORD\fP" |
Setting RSYNC_PASSWORD to the required | Setting RSYNC_PASSWORD to the required password allows you to run |
password allows you to run authenticated rsync connections to an rsync | authenticated rsync connections to an rsync daemon without user |
daemon without user intervention. Note that this does not supply a | intervention. Note that this does not supply a password to a remote shell |
password to a remote shell transport such as ssh; to learn how to do that, | transport such as ssh; to learn how to do that, consult the remote shell's |
consult the remote shell\(cq\&s documentation. | documentation. |
.IP "\fBUSER\fP or \fBLOGNAME\fP" |
.IP "\fBUSER\fP or \fBLOGNAME\fP" |
The USER or LOGNAME environment variables | The USER or LOGNAME environment variables are used to determine the default |
are used to determine the default username sent to an rsync daemon. | username sent to an rsync daemon. If neither is set, the username defaults |
If neither is set, the username defaults to \(dq\&nobody\(dq\&. | to "nobody". |
.IP "\fBHOME\fP" |
.IP "\fBHOME\fP" |
The HOME environment variable is used to find the user\(cq\&s | The HOME environment variable is used to find the user's default .cvsignore |
default .cvsignore file. | file. |
| .P |
.PP | |
.SH "FILES" |
.SH "FILES" |
| .P |
.PP | |
/etc/rsyncd.conf or rsyncd.conf |
/etc/rsyncd.conf or rsyncd.conf |
.PP | .P |
.SH "SEE ALSO" |
.SH "SEE ALSO" |
| .P |
.PP | \fBrsync-ssl\fP(1), \fBrsyncd.conf\fP(5) |
\fBrsyncd.conf\fP(5) | .P |
.PP | |
.SH "BUGS" |
.SH "BUGS" |
| .P |
.PP | |
times are transferred as *nix time_t values |
times are transferred as *nix time_t values |
.PP | .P |
When transferring to FAT filesystems rsync may re\-sync | When transferring to FAT filesystems rsync may re-sync |
unmodified files. |
unmodified files. |
See the comments on the \fB\-\-modify\-window\fP option. | See the comments on the \fB\-\-modify-window\fP option. |
.PP | .P |
file permissions, devices, etc. are transferred as native numerical |
file permissions, devices, etc. are transferred as native numerical |
values |
values |
.PP | .P |
see also the comments on the \fB\-\-delete\fP option |
see also the comments on the \fB\-\-delete\fP option |
.PP | .P |
Please report bugs! See the web site at | Please report bugs! See the web site at https://rsync.samba.org/. |
http://rsync.samba.org/ | .P |
.PP | |
.SH "VERSION" |
.SH "VERSION" |
| .P |
.PP | This man page is current for version 3.2.3 of rsync. |
This man page is current for version 3.1.2 of rsync. | .P |
.PP | |
.SH "INTERNAL OPTIONS" |
.SH "INTERNAL OPTIONS" |
| .P |
.PP | The options \fB\-\-server\fP and \fB\-\-sender\fP are used internally by rsync, and should |
The options \fB\-\-server\fP and \fB\-\-sender\fP are used internally by rsync, | never be typed by a user under normal circumstances. Some awareness of these |
and should never be typed by a user under normal circumstances. Some | options may be needed in certain scenarios, such as when setting up a login |
awareness of these options may be needed in certain scenarios, such as | that can only run an rsync command. For instance, the support directory of the |
when setting up a login that can only run an rsync command. For instance, | rsync distribution has an example script named rrsync (for restricted rsync) |
the support directory of the rsync distribution has an example script | that can be used with a restricted ssh login. |
named rrsync (for restricted rsync) that can be used with a restricted | .P |
ssh login. | |
.PP | |
.SH "CREDITS" |
.SH "CREDITS" |
| .P |
.PP | |
rsync is distributed under the GNU General Public License. See the file |
rsync is distributed under the GNU General Public License. See the file |
COPYING for details. |
COPYING for details. |
.PP | .P |
A WEB site is available at | A web site is available at https://rsync.samba.org/. The site includes an |
http://rsync.samba.org/. The site | FAQ-O-Matic which may cover questions unanswered by this manual page. |
includes an FAQ\-O\-Matic which may cover questions unanswered by this | .P |
manual page. | We would be delighted to hear from you if you like this program. Please |
.PP | contact the mailing-list at rsync@lists.samba.org. |
The primary ftp site for rsync is | .P |
ftp://rsync.samba.org/pub/rsync. | This program uses the excellent zlib compression library written by Jean-loup |
.PP | Gailly and Mark Adler. |
We would be delighted to hear from you if you like this program. | .P |
Please contact the mailing\-list at rsync@lists.samba.org. | |
.PP | |
This program uses the excellent zlib compression library written by | |
Jean\-loup Gailly and Mark Adler. | |
.PP | |
.SH "THANKS" |
.SH "THANKS" |
| .P |
.PP | |
Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, |
Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, |
David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our |
David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our |
gone\-but\-not\-forgotten compadre, J.W. Schultz. | gone-but-not-forgotten compadre, J.W. Schultz. |
.PP | .P |
Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell | Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and |
and David Bell. I\(cq\&ve probably missed some people, my apologies if I have. | David Bell. I've probably missed some people, my apologies if I have. |
.PP | .P |
.SH "AUTHOR" |
.SH "AUTHOR" |
| .P |
.PP | rsync was originally written by Andrew Tridgell and Paul Mackerras. Many |
rsync was originally written by Andrew Tridgell and Paul Mackerras. | people have later contributed to it. It is currently maintained by Wayne |
Many people have later contributed to it. It is currently maintained | Davison. |
by Wayne Davison. | .P |
.PP | |
Mailing lists for support and development are available at |
Mailing lists for support and development are available at |
http://lists.samba.org | https://lists.samba.org/. |