Mention files-to-excludes.
[rsync/rsync.git] / rsync.yo
CommitLineData
9e3c856a 1mailto(rsync-bugs@samba.org)
9ec8bd87 2manpage(rsync)(1)(28 Jul 2005)()()
41059f75
AT
3manpagename(rsync)(faster, flexible replacement for rcp)
4manpagesynopsis()
5
868676dc
WD
6rsync [OPTION]... SRC [SRC]... DEST
7
9ef53907 8rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
41059f75 9
868676dc 10rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
41059f75 11
868676dc 12rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
41059f75 13
868676dc 14rsync [OPTION]... [USER@]HOST:SRC [DEST]
41059f75 15
868676dc 16rsync [OPTION]... [USER@]HOST::SRC [DEST]
41059f75 17
9ef53907 18rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
039faa86 19
41059f75
AT
20manpagedescription()
21
22rsync is a program that behaves in much the same way that rcp does,
23but has many more options and uses the rsync remote-update protocol to
675ef1aa
WD
24greatly speed up file transfers when the destination file is being
25updated.
41059f75
AT
26
27The rsync remote-update protocol allows rsync to transfer just the
f39281ae 28differences between two sets of files across the network connection, using
41059f75
AT
29an efficient checksum-search algorithm described in the technical
30report that accompanies this package.
31
32Some of the additional features of rsync are:
33
34itemize(
b9f592fb 35 it() support for copying links, devices, owners, groups, and permissions
41059f75
AT
36 it() exclude and exclude-from options similar to GNU tar
37 it() a CVS exclude mode for ignoring the same files that CVS would ignore
43cd760f 38 it() can use any transparent remote shell, including ssh or rsh
d38772e0 39 it() does not require super-user privileges
41059f75 40 it() pipelining of file transfers to minimize latency costs
5a727522 41 it() support for anonymous or authenticated rsync daemons (ideal for
41059f75
AT
42 mirroring)
43)
44
45manpagesection(GENERAL)
46
15997547
WD
47Rsync copies files either to or from a remote host, or locally on the
48current host (it does not support copying files between two remote hosts).
49
50There are two different ways for rsync to contact a remote system: using a
51remote-shell program as the transport (such as ssh or rsh) or contacting an
52rsync daemon directly via TCP. The remote-shell transport is used whenever
53the source or destination path contains a single colon (:) separator after
54a host specification. Contacting an rsync daemon directly happens when the
55source or destination path contains a double colon (::) separator after a
ba3542cf 56host specification, OR when an rsync:// URL is specified (see also the
754a080f 57"USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for
ba3542cf 58an exception to this latter rule).
15997547
WD
59
60As a special case, if a remote source is specified without a destination,
61the remote files are listed in an output format similar to "ls -l".
62
63As expected, if neither the source or destination path specify a remote
64host, the copy occurs locally (see also the bf(--list-only) option).
65
41059f75
AT
66manpagesection(SETUP)
67
68See the file README for installation instructions.
69
1bbf83c0
WD
70Once installed, you can use rsync to any machine that you can access via
71a remote shell (as well as some that you can access using the rsync
43cd760f 72daemon-mode protocol). For remote transfers, a modern rsync uses ssh
1bbf83c0 73for its communications, but it may have been configured to use a
43cd760f 74different remote shell by default, such as rsh or remsh.
41059f75 75
faa82484 76You can also specify any remote shell you like, either by using the bf(-e)
41059f75
AT
77command line option, or by setting the RSYNC_RSH environment variable.
78
8e987130 79Note that rsync must be installed on both the source and destination
faa82484 80machines.
8e987130 81
41059f75
AT
82manpagesection(USAGE)
83
84You use rsync in the same way you use rcp. You must specify a source
85and a destination, one of which may be remote.
86
4d888108 87Perhaps the best way to explain the syntax is with some examples:
41059f75 88
faa82484 89quote(tt(rsync -t *.c foo:src/))
41059f75 90
8a97fc2e 91This would transfer all files matching the pattern *.c from the
41059f75
AT
92current directory to the directory src on the machine foo. If any of
93the files already exist on the remote system then the rsync
94remote-update protocol is used to update the file by sending only the
95differences. See the tech report for details.
96
faa82484 97quote(tt(rsync -avz foo:src/bar /data/tmp))
41059f75 98
8a97fc2e 99This would recursively transfer all files from the directory src/bar on the
41059f75
AT
100machine foo into the /data/tmp/bar directory on the local machine. The
101files are transferred in "archive" mode, which ensures that symbolic
b5accaba 102links, devices, attributes, permissions, ownerships, etc. are preserved
14d43f1f 103in the transfer. Additionally, compression will be used to reduce the
41059f75
AT
104size of data portions of the transfer.
105
faa82484 106quote(tt(rsync -avz foo:src/bar/ /data/tmp))
41059f75 107
8a97fc2e
WD
108A trailing slash on the source changes this behavior to avoid creating an
109additional directory level at the destination. You can think of a trailing
110/ on a source as meaning "copy the contents of this directory" as opposed
111to "copy the directory by name", but in both cases the attributes of the
112containing directory are transferred to the containing directory on the
113destination. In other words, each of the following commands copies the
114files in the same way, including their setting of the attributes of
115/dest/foo:
116
faa82484
WD
117quote(
118tt(rsync -av /src/foo /dest)nl()
119tt(rsync -av /src/foo/ /dest/foo)nl()
120)
41059f75 121
c4833b02
WD
122Note also that host and module references don't require a trailing slash to
123copy the contents of the default directory. For example, both of these
124copy the remote directory's contents into "/dest":
125
126quote(
127tt(rsync -av host: /dest)nl()
128tt(rsync -av host::module /dest)nl()
129)
130
41059f75
AT
131You can also use rsync in local-only mode, where both the source and
132destination don't have a ':' in the name. In this case it behaves like
133an improved copy command.
134
bb9bdba4
WD
135Finally, you can list all the (listable) modules available from a
136particular rsync daemon by leaving off the module name:
137
faa82484 138quote(tt(rsync somehost.mydomain.com::))
14d43f1f 139
bb9bdba4 140See the following section for more details.
14d43f1f 141
675ef1aa
WD
142manpagesection(ADVANCED USAGE)
143
144The syntax for requesting multiple files from a remote host involves using
145quoted spaces in the SRC. Some examples:
146
faa82484 147quote(tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
675ef1aa
WD
148
149This would copy file1 and file2 into /dest from an rsync daemon. Each
150additional arg must include the same "modname/" prefix as the first one,
151and must be preceded by a single space. All other spaces are assumed
152to be a part of the filenames.
153
faa82484 154quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest))
675ef1aa
WD
155
156This would copy file1 and file2 into /dest using a remote shell. This
157word-splitting is done by the remote shell, so if it doesn't work it means
158that the remote shell isn't configured to split its args based on
159whitespace (a very rare setting, but not unknown). If you need to transfer
160a filename that contains whitespace, you'll need to either escape the
161whitespace in a way that the remote shell will understand, or use wildcards
162in place of the spaces. Two examples of this are:
163
faa82484
WD
164quote(
165tt(rsync -av host:'file\ name\ with\ spaces' /dest)nl()
166tt(rsync -av host:file?name?with?spaces /dest)nl()
167)
675ef1aa
WD
168
169This latter example assumes that your shell passes through unmatched
170wildcards. If it complains about "no match", put the name in quotes.
171
5a727522 172manpagesection(CONNECTING TO AN RSYNC DAEMON)
41059f75 173
754a080f
WD
174It is also possible to use rsync without a remote shell as the transport.
175In this case you will directly connect to a remote rsync daemon, typically
176using TCP port 873. (This obviously requires the daemon to be running on
177the remote system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT
178CONNECTIONS section below for information on that.)
4c3b4b25 179
1bbf83c0 180Using rsync in this way is the same as using it with a remote shell except
41059f75
AT
181that:
182
183itemize(
62f27e3c
WD
184 it() you either use a double colon :: instead of a single colon to
185 separate the hostname from the path, or you use an rsync:// URL.
2c64b258 186 it() the first word of the "path" is actually a module name.
5a727522 187 it() the remote daemon may print a message of the day when you
14d43f1f 188 connect.
5a727522
WD
189 it() if you specify no path name on the remote daemon then the
190 list of accessible paths on the daemon will be shown.
f7632fc6 191 it() if you specify no local destination then a listing of the
5a727522 192 specified files on the remote daemon is provided.
2c64b258 193 it() you must not specify the bf(--rsh) (bf(-e)) option.
41059f75
AT
194)
195
754a080f
WD
196An example that copies all the files in a remote module named "src":
197
198verb( rsync -av host::src /dest)
199
200Some modules on the remote daemon may require authentication. If so,
4c3d16be
AT
201you will receive a password prompt when you connect. You can avoid the
202password prompt by setting the environment variable RSYNC_PASSWORD to
faa82484 203the password you want to use or using the bf(--password-file) option. This
65575e96 204may be useful when scripting rsync.
4c3d16be 205
3bc67f0c 206WARNING: On some systems environment variables are visible to all
faa82484 207users. On those systems using bf(--password-file) is recommended.
3bc67f0c 208
754a080f
WD
209You may establish the connection via a web proxy by setting the
210environment variable RSYNC_PROXY to a hostname:port pair pointing to
211your web proxy. Note that your web proxy's configuration must support
212proxy connections to port 873.
bef49340 213
754a080f
WD
214manpagesection(USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION)
215
216It is sometimes useful to use various features of an rsync daemon (such as
217named modules) without actually allowing any new socket connections into a
218system (other than what is already required to allow remote-shell access).
219Rsync supports connecting to a host using a remote shell and then spawning
220a single-use "daemon" server that expects to read its config file in the
221home dir of the remote user. This can be useful if you want to encrypt a
222daemon-style transfer's data, but since the daemon is started up fresh by
223the remote user, you may not be able to use features such as chroot or
224change the uid used by the daemon. (For another way to encrypt a daemon
225transfer, consider using ssh to tunnel a local port to a remote machine and
226configure a normal rsync daemon on that remote host to only allow
227connections from "localhost".)
228
229From the user's perspective, a daemon transfer via a remote-shell
230connection uses nearly the same command-line syntax as a normal
231rsync-daemon transfer, with the only exception being that you must
232explicitly set the remote shell program on the command-line with the
233bf(--rsh=COMMAND) option. (Setting the RSYNC_RSH in the environment
234will not turn on this functionality.) For example:
235
236verb( rsync -av --rsh=ssh host::module /dest)
237
238If you need to specify a different remote-shell user, keep in mind that the
239user@ prefix in front of the host is specifying the rsync-user value (for a
240module that requires user-based authentication). This means that you must
241give the '-l user' option to ssh when specifying the remote-shell:
242
243verb( rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest)
bef49340
WD
244
245The "ssh-user" will be used at the ssh level; the "rsync-user" will be
754a080f 246used to log-in to the "module".
bef49340 247
754a080f 248manpagesection(STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS)
bef49340 249
754a080f
WD
250In order to connect to an rsync daemon, the remote system needs to have a
251daemon already running (or it needs to have configured something like inetd
252to spawn an rsync daemon for incoming connections on a particular port).
253For full information on how to start a daemon that will handling incoming
254socket connections, see the rsyncd.conf(5) man page -- that is the config
255file for the daemon, and it contains the full details for how to run the
256daemon (including stand-alone and inetd configurations).
bef49340 257
754a080f
WD
258If you're using one of the remote-shell transports for the transfer, there is
259no need to manually start an rsync daemon.
bef49340 260
41059f75
AT
261manpagesection(EXAMPLES)
262
263Here are some examples of how I use rsync.
264
14d43f1f
DD
265To backup my wife's home directory, which consists of large MS Word
266files and mail folders, I use a cron job that runs
41059f75 267
faa82484 268quote(tt(rsync -Cavz . arvidsjaur:backup))
41059f75 269
f39281ae 270each night over a PPP connection to a duplicate directory on my machine
41059f75
AT
271"arvidsjaur".
272
273To synchronize my samba source trees I use the following Makefile
274targets:
275
faa82484
WD
276verb( get:
277 rsync -avuzb --exclude '*~' samba:samba/ .
278 put:
279 rsync -Cavuzb . samba:samba/
280 sync: get put)
41059f75
AT
281
282this allows me to sync with a CVS directory at the other end of the
ae283632
WD
283connection. I then do CVS operations on the remote machine, which saves a
284lot of time as the remote CVS protocol isn't very efficient.
41059f75
AT
285
286I mirror a directory between my "old" and "new" ftp sites with the
faa82484 287command:
41059f75 288
faa82484 289tt(rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge")
41059f75 290
faa82484 291This is launched from cron every few hours.
41059f75 292
c95da96a
AT
293manpagesection(OPTIONS SUMMARY)
294
14d43f1f 295Here is a short summary of the options available in rsync. Please refer
faa82484 296to the detailed description below for a complete description. verb(
c95da96a 297 -v, --verbose increase verbosity
44d98d61 298 -q, --quiet suppress non-error messages
44d98d61
WD
299 -c, --checksum skip based on checksum, not mod-time & size
300 -a, --archive archive mode; same as -rlptgoD (no -H)
f40aa6fb 301 --no-OPTION turn off an implied OPTION (e.g. --no-D)
c95da96a
AT
302 -r, --recursive recurse into directories
303 -R, --relative use relative path names
f40aa6fb 304 --no-implied-dirs don't send implied dirs with --relative
915dd207 305 -b, --backup make backups (see --suffix & --backup-dir)
44d98d61 306 --backup-dir=DIR make backups into hierarchy based in DIR
915dd207 307 --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
44d98d61
WD
308 -u, --update skip files that are newer on the receiver
309 --inplace update destination files in-place
94f20a9f 310 --append append data onto shorter files
09ed3099 311 -d, --dirs transfer directories without recursing
eb06fa95 312 -l, --links copy symlinks as symlinks
44d98d61
WD
313 -L, --copy-links transform symlink into referent file/dir
314 --copy-unsafe-links only "unsafe" symlinks are transformed
315 --safe-links ignore symlinks that point outside the tree
c95da96a 316 -H, --hard-links preserve hard links
09ed3099 317 -K, --keep-dirlinks treat symlinked dir on receiver as dir
c95da96a 318 -p, --perms preserve permissions
d38772e0 319 -o, --owner preserve owner (super-user only)
c95da96a 320 -g, --group preserve group
d38772e0 321 --devices preserve device files (super-user only)
4e7d07c8
WD
322 --specials preserve special files
323 -D same as --devices --specials
c95da96a 324 -t, --times preserve times
54e66f1d 325 -O, --omit-dir-times omit directories when preserving times
d38772e0 326 --super receiver attempts super-user activities
9e8ea423 327 --chmod=CHMOD change destination permissions
c95da96a
AT
328 -S, --sparse handle sparse files efficiently
329 -n, --dry-run show what would have been transferred
98bf61c8 330 -W, --whole-file copy files whole (without rsync algorithm)
c95da96a 331 -x, --one-file-system don't cross filesystem boundaries
3ed8eb3f 332 -B, --block-size=SIZE force a fixed checksum block-size
44d98d61 333 -e, --rsh=COMMAND specify the remote shell to use
68e169ab 334 --rsync-path=PROGRAM specify the rsync to run on remote machine
9639c718 335 --existing ignore non-existing files on receiving side
915dd207 336 --ignore-existing ignore files that already exist on receiver
96110304 337 --remove-sent-files sent files/symlinks are removed from sender
ae76a740 338 --del an alias for --delete-during
915dd207 339 --delete delete files that don't exist on sender
598c409e 340 --delete-before receiver deletes before transfer (default)
ae76a740
WD
341 --delete-during receiver deletes during xfer, not before
342 --delete-after receiver deletes after transfer, not before
866925bf 343 --delete-excluded also delete excluded files on receiver
b5accaba 344 --ignore-errors delete even if there are I/O errors
866925bf 345 --force force deletion of dirs even if not empty
0b73ca12 346 --max-delete=NUM don't delete more than NUM files
3610c458 347 --max-size=SIZE don't transfer any file larger than SIZE
59dd6786 348 --min-size=SIZE don't transfer any file smaller than SIZE
c95da96a 349 --partial keep partially transferred files
44cad59f 350 --partial-dir=DIR put a partially transferred file into DIR
44d98d61 351 --delay-updates put all updated files into place at end
a272ff8c 352 -m, --prune-empty-dirs prune empty directory chains from file-list
c95da96a 353 --numeric-ids don't map uid/gid values by user/group name
b5accaba 354 --timeout=TIME set I/O timeout in seconds
44d98d61
WD
355 -I, --ignore-times don't skip files that match size and time
356 --size-only skip files that match in size
357 --modify-window=NUM compare mod-times with reduced accuracy
abce74bb 358 -T, --temp-dir=DIR create temporary files in directory DIR
5b483755 359 -y, --fuzzy find similar file for basis if no dest file
915dd207 360 --compare-dest=DIR also compare received files relative to DIR
2f03ce67 361 --copy-dest=DIR ... and include copies of unchanged files
b127c1dc 362 --link-dest=DIR hardlink to files in DIR when unchanged
32a5edf4 363 -z, --compress compress file data during the transfer
bad01106 364 --compress-level=NUM explicitly set compression level
44d98d61 365 -C, --cvs-exclude auto-ignore files in the same way CVS does
16e5de84 366 -f, --filter=RULE add a file-filtering RULE
8a6f3fea 367 -F same as --filter='dir-merge /.rsync-filter'
16e5de84 368 repeated: --filter='- .rsync-filter'
2acf81eb 369 --exclude=PATTERN exclude files matching PATTERN
44d98d61 370 --exclude-from=FILE read exclude patterns from FILE
2acf81eb 371 --include=PATTERN don't exclude files matching PATTERN
44d98d61
WD
372 --include-from=FILE read include patterns from FILE
373 --files-from=FILE read list of source-file names from FILE
fa92818a 374 -0, --from0 all *from/filter files are delimited by 0s
3ae5367f 375 --address=ADDRESS bind address for outgoing socket to daemon
c259892c 376 --port=PORT specify double-colon alternate port number
04f48837 377 --sockopts=OPTIONS specify custom TCP options
b5accaba 378 --blocking-io use blocking I/O for the remote shell
44d98d61 379 --stats give some file-transfer stats
955c3145 380 -h, --human-readable output numbers in a human-readable format
3b4ecc6b 381 --si like human-readable, but use powers of 1000
eb86d661 382 --progress show progress during transfer
44d98d61 383 -P same as --partial --progress
b78296cb 384 -i, --itemize-changes output a change-summary for all updates
81c453b1 385 --log-format=FORMAT output filenames using the specified format
44d98d61 386 --password-file=FILE read password from FILE
09ed3099 387 --list-only list the files instead of copying them
44d98d61 388 --bwlimit=KBPS limit I/O bandwidth; KBytes per second
faa82484 389 --write-batch=FILE write a batched update to FILE
326bb56e 390 --only-write-batch=FILE like --write-batch but w/o updating dest
44d98d61 391 --read-batch=FILE read a batched update from FILE
0b941479 392 --protocol=NUM force an older protocol version to be used
44d98d61 393 --checksum-seed=NUM set block/file checksum seed (advanced)
abce74bb
WD
394 -4, --ipv4 prefer IPv4
395 -6, --ipv6 prefer IPv6
81c453b1 396 --version print version number
955c3145 397 --help show this help screen)
6902ed17 398
faa82484
WD
399Rsync can also be run as a daemon, in which case the following options are
400accepted: verb(
bdf278f7
WD
401 --daemon run as an rsync daemon
402 --address=ADDRESS bind to the specified address
44d98d61 403 --bwlimit=KBPS limit I/O bandwidth; KBytes per second
bdf278f7
WD
404 --config=FILE specify alternate rsyncd.conf file
405 --no-detach do not detach from the parent
c259892c 406 --port=PORT listen on alternate port number
04f48837 407 --sockopts=OPTIONS specify custom TCP options
24b0922b 408 -v, --verbose increase verbosity
abce74bb
WD
409 -4, --ipv4 prefer IPv4
410 -6, --ipv6 prefer IPv6
955c3145 411 --help show this help screen)
c95da96a 412
41059f75
AT
413manpageoptions()
414
415rsync uses the GNU long options package. Many of the command line
416options have two variants, one short and one long. These are shown
14d43f1f 417below, separated by commas. Some options only have a long variant.
b5679335
DD
418The '=' for options that take a parameter is optional; whitespace
419can be used instead.
41059f75
AT
420
421startdit()
955c3145
WD
422dit(bf(--help)) Print a short help page describing the options
423available in rsync and exit. For backward-compatibility with older
424versions of rsync, the same help output can also be requested by using
425the bf(-h) option without any other args.
41059f75 426
bdf278f7 427dit(bf(--version)) print the rsync version number and exit.
41059f75
AT
428
429dit(bf(-v, --verbose)) This option increases the amount of information you
14d43f1f 430are given during the transfer. By default, rsync works silently. A
faa82484
WD
431single bf(-v) will give you information about what files are being
432transferred and a brief summary at the end. Two bf(-v) flags will give you
41059f75 433information on what files are being skipped and slightly more
faa82484 434information at the end. More than two bf(-v) flags should only be used if
14d43f1f 435you are debugging rsync.
41059f75 436
4f90eb43
WD
437Note that the names of the transferred files that are output are done using
438a default bf(--log-format) of "%n%L", which tells you just the name of the
81c453b1 439file and, if the item is a link, where it points. At the single bf(-v)
4f90eb43
WD
440level of verbosity, this does not mention when a file gets its attributes
441changed. If you ask for an itemized list of changed attributes (either
442bf(--itemize-changes) or adding "%i" to the bf(--log-format) setting), the
443output (on the client) increases to mention all items that are changed in
444any way. See the bf(--log-format) option for more details.
445
b86f0cef
DD
446dit(bf(-q, --quiet)) This option decreases the amount of information you
447are given during the transfer, notably suppressing information messages
448from the remote server. This flag is useful when invoking rsync from
449cron.
450
41059f75 451dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
915dd207
WD
452already the same size and have the same modification time-stamp.
453This option turns off this "quick check" behavior.
41059f75 454
a03a9f4e 455dit(bf(--size-only)) Normally rsync will not transfer any files that are
915dd207 456already the same size and have the same modification time-stamp. With the
faa82484 457bf(--size-only) option, files will not be transferred if they have the same size,
f83f0548
AT
458regardless of timestamp. This is useful when starting to use rsync
459after using another mirroring system which may not preserve timestamps
460exactly.
461
4f1f94d1
WD
462dit(bf(--modify-window)) When comparing two timestamps, rsync treats the
463timestamps as being equal if they differ by no more than the modify-window
464value. This is normally 0 (for an exact match), but you may find it useful
465to set this to a larger value in some situations. In particular, when
466transferring to or from an MS Windows FAT filesystem (which represents
467times with a 2-second resolution), bf(--modify-window=1) is useful
468(allowing times to differ by up to 1 second).
5b56cc19 469
41059f75
AT
470dit(bf(-c, --checksum)) This forces the sender to checksum all files using
471a 128-bit MD4 checksum before transfer. The checksum is then
472explicitly checked on the receiver and any files of the same name
473which already exist and have the same checksum and size on the
a03a9f4e 474receiver are not transferred. This option can be quite slow.
41059f75 475
faa82484 476dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
e7bf3e5e 477way of saying you want recursion and want to preserve almost
f40aa6fb
WD
478everything (with -H being a notable omission).
479The only exception to the above equivalence is when bf(--files-from) is
5dd97ab9 480specified, in which case bf(-r) is not implied.
e7bf3e5e 481
faa82484 482Note that bf(-a) bf(does not preserve hardlinks), because
e7bf3e5e
MP
483finding multiply-linked files is expensive. You must separately
484specify bf(-H).
41059f75 485
f40aa6fb
WD
486dit(--no-OPTION) You may turn off one or more implied options by prefixing
487the option name with "no-". Not all options may be prefixed with a "no-":
488only options that are implied by other options (e.g. bf(--no-D),
489bf(--no-perms)) or have different defaults in various circumstances
490(e.g. bf(--no-whole-file), bf(--no-blocking-io), bf(--no-dirs)). You may
491specify either the short or the long option name after the "no-" prefix
492(e.g. bf(--no-R) is the same as bf(--no-relative)).
493
494For example: if you want to use bf(-a) (bf(--archive)) but don't want
495bf(-o) (bf(--owner)), instead of converting bf(-a) into bf(-rlptgD), you
496could specify bf(-a --no-o) (or bf(-a --no-owner)).
497
498The order of the options is important: if you specify bf(--no-r -a), the
499bf(-r) option would end up being turned on, the opposite of bf(-a --no-r).
500Note also that the side-effects of the bf(--files-from) option are NOT
a9af5d8e 501positional, as it affects the default state of several options and slightly
f40aa6fb
WD
502changes the meaning of bf(-a) (see the bf(--files-from) option for more
503details).
504
24986abd 505dit(bf(-r, --recursive)) This tells rsync to copy directories
faa82484 506recursively. See also bf(--dirs) (bf(-d)).
41059f75
AT
507
508dit(bf(-R, --relative)) Use relative paths. This means that the full path
509names specified on the command line are sent to the server rather than
510just the last parts of the filenames. This is particularly useful when
14d43f1f 511you want to send several different directories at the same time. For
1dc42d12 512example, if you used this command:
41059f75 513
1dc42d12 514quote(tt( rsync -av /foo/bar/baz.c remote:/tmp/))
41059f75 515
1dc42d12 516... this would create a file called baz.c in /tmp/ on the remote
41059f75
AT
517machine. If instead you used
518
1dc42d12 519quote(tt( rsync -avR /foo/bar/baz.c remote:/tmp/))
41059f75 520
1dc42d12 521then a file called /tmp/foo/bar/baz.c would be created on the remote
9bef934c 522machine -- the full path name is preserved. To limit the amount of
1dc42d12
WD
523path information that is sent, you have a couple options: (1) With
524a modern rsync on the sending side (beginning with 2.6.7), you can
525insert a dot dir into the source path, like this:
526
527quote(tt( rsync -avR /foo/./bar/baz.c remote:/tmp/))
528
529That would create /tmp/bar/baz.c on the remote machine. (Note that the
530dot dir must followed by a slash, so "/foo/." would not be abbreviated.)
531(2) For older rsync versions, you would need to use a chdir to limit the
532source path. For example, when pushing files:
533
53cf0b8b 534quote(tt( (cd /foo; rsync -avR bar/baz.c remote:/tmp/) ))
1dc42d12 535
53cf0b8b
WD
536(Note that the parens put the two commands into a sub-shell, so that the
537"cd" command doesn't remain in effect for future commands.)
538If you're pulling files, use this idiom (which doesn't work with an
539rsync daemon):
9bef934c 540
faa82484 541quote(
1dc42d12
WD
542tt( rsync -avR --rsync-path="cd /foo; rsync" \ )nl()
543tt( remote:bar/baz.c /tmp/)
faa82484 544)
9bef934c 545
faa82484 546dit(bf(--no-implied-dirs)) When combined with the bf(--relative) option, the
f177b7cc
WD
547implied directories in each path are not explicitly duplicated as part
548of the transfer. This makes the transfer more optimal and also allows
549the two sides to have non-matching symlinks in the implied part of the
faa82484 550path. For instance, if you transfer the file "/path/foo/file" with bf(-R),
f177b7cc
WD
551the default is for rsync to ensure that "/path" and "/path/foo" on the
552destination exactly match the directories/symlinks of the source. Using
faa82484 553the bf(--no-implied-dirs) option would omit both of these implied dirs,
f177b7cc
WD
554which means that if "/path" was a real directory on one machine and a
555symlink of the other machine, rsync would not try to change this.
41059f75 556
b19fd07c
WD
557dit(bf(-b, --backup)) With this option, preexisting destination files are
558renamed as each file is transferred or deleted. You can control where the
559backup file goes and what (if any) suffix gets appended using the
faa82484 560bf(--backup-dir) and bf(--suffix) options.
4c72f27d
WD
561
562Note that if you don't specify bf(--backup-dir), (1) the
563bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is
564also in effect (without bf(--delete-excluded)), rsync will add a protect
565filter-rule for the backup suffix to the end of all your existing excludes
566(e.g. -f "P *~"). This will prevent previously backed-up files from being
567deleted. Note that if you are supplying your own filter rules, you may
568need to manually insert your own exclude/protect rule somewhere higher up
569in the list so that it has a high enough priority to be effective (e.g., if
570your rules specify a trailing inclusion/exclusion of '*', the auto-added
571rule would never be reached).
41059f75 572
faa82484 573dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
66203a98 574tells rsync to store all backups in the specified directory. This is
759ac870 575very useful for incremental backups. You can additionally
faa82484 576specify a backup suffix using the bf(--suffix) option
759ac870
DD
577(otherwise the files backed up in the specified directory
578will keep their original filenames).
66203a98 579
b5679335 580dit(bf(--suffix=SUFFIX)) This option allows you to override the default
faa82484
WD
581backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~
582if no -bf(-backup-dir) was specified, otherwise it is an empty string.
9ef53907 583
4539c0d7
WD
584dit(bf(-u, --update)) This forces rsync to skip any files which exist on
585the destination and have a modified time that is newer than the source
586file. (If an existing destination file has a modify time equal to the
587source file's, it will be updated if the sizes are different.)
41059f75 588
faa82484 589In the current implementation of bf(--update), a difference of file format
4539c0d7 590between the sender and receiver is always
adddd075
WD
591considered to be important enough for an update, no matter what date
592is on the objects. In other words, if the source has a directory or a
593symlink where the destination has a file, the transfer would occur
594regardless of the timestamps. This might change in the future (feel
595free to comment on this on the mailing list if you have an opinion).
596
a3221d2a
WD
597dit(bf(--inplace)) This causes rsync not to create a new copy of the file
598and then move it into place. Instead rsync will overwrite the existing
eb162f3b
WD
599file, meaning that the rsync algorithm can't accomplish the full amount of
600network reduction it might be able to otherwise (since it does not yet try
601to sort data matches). One exception to this is if you combine the option
faa82484 602with bf(--backup), since rsync is smart enough to use the backup file as the
eb162f3b 603basis file for the transfer.
a3221d2a 604
183150b7
WD
605This option is useful for transfer of large files with block-based changes
606or appended data, and also on systems that are disk bound, not network
607bound.
608
faa82484
WD
609The option implies bf(--partial) (since an interrupted transfer does not delete
610the file), but conflicts with bf(--partial-dir) and bf(--delay-updates).
b7c24819
WD
611Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest)
612and bf(--link-dest).
a3221d2a 613
399371e7 614WARNING: The file's data will be in an inconsistent state during the
98f51bfb 615transfer (and possibly afterward if the transfer gets interrupted), so you
399371e7 616should not use this option to update files that are in use. Also note that
eb162f3b 617rsync will be unable to update a file in-place that is not writable by the
75b243a5 618receiving user.
a3221d2a 619
94f20a9f
WD
620dit(bf(--append)) This causes rsync to update a file by appending data onto
621the end of the file, which presumes that the data that already exists on
622the receiving side is identical with the start of the file on the sending
623side. If that is not true, the file will fail the checksum test, and the
d37d1c44
WD
624resend will do a normal bf(--inplace) update to correct the mismatched data.
625Only files on the receiving side that are shorter than the corresponding
626file on the sending side (as well as new files) are sent.
a8cbb57c
WD
627Implies bf(--inplace), but does not conflict with bf(--sparse) (though the
628bf(--sparse) option will be auto-disabled if a resend of the already-existing
629data is required).
94f20a9f 630
09ed3099 631dit(bf(-d, --dirs)) Tell the sending side to include any directories that
faa82484 632are encountered. Unlike bf(--recursive), a directory's contents are not copied
57b66a24
WD
633unless the directory name specified is "." or ends with a trailing slash
634(e.g. ".", "dir/.", "dir/", etc.). Without this option or the
faa82484 635bf(--recursive) option, rsync will skip all directories it encounters (and
f40aa6fb 636output a message to that effect for each one). If you specify both
6e6cc163 637bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence.
09ed3099 638
eb06fa95
MP
639dit(bf(-l, --links)) When symlinks are encountered, recreate the
640symlink on the destination.
41059f75 641
eb06fa95 642dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
ef855d19
WD
643they point to (the referent) is copied, rather than the symlink. In older
644versions of rsync, this option also had the side-effect of telling the
645receiving side to follow symlinks, such as symlinks to directories. In a
faa82484 646modern rsync such as this one, you'll need to specify bf(--keep-dirlinks) (bf(-K))
ef855d19 647to get this extra behavior. The only exception is when sending files to
faa82484
WD
648an rsync that is too old to understand bf(-K) -- in that case, the bf(-L) option
649will still have the side-effect of bf(-K) on that older receiving rsync.
b5313607 650
eb06fa95 651dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
7af4227a 652symbolic links that point outside the copied tree. Absolute symlinks
eb06fa95 653are also treated like ordinary files, and so are any symlinks in the
faa82484 654source path itself when bf(--relative) is used.
41059f75 655
d310a212 656dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
7af4227a 657which point outside the copied tree. All absolute symlinks are
faa82484
WD
658also ignored. Using this option in conjunction with bf(--relative) may
659give unexpected results.
d310a212 660
41059f75
AT
661dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
662the remote system to be the same as the local system. Without this
663option hard links are treated like regular files.
664
665Note that rsync can only detect hard links if both parts of the link
666are in the list of files being sent.
667
668This option can be quite slow, so only use it if you need it.
669
09ed3099
WD
670dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
671pointing to a directory, it will be treated as matching a directory
672from the sender.
673
41059f75 674dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
a1a440c2
DD
675is not used and the whole file is sent as-is instead. The transfer may be
676faster if this option is used when the bandwidth between the source and
6eb770bb 677destination machines is higher than the bandwidth to disk (especially when the
4d888108 678"disk" is actually a networked filesystem). This is the default when both
6eb770bb 679the source and destination are specified as local paths.
41059f75 680
8dc74608
WD
681dit(bf(-p, --perms)) This option causes rsync to set the destination
682permissions to be the same as the source permissions.
683
79db59d1
WD
684Without this option, all existing files (including updated files) retain
685their existing permissions, while each new file gets its permissions set
686based on the source file's permissions, but masked by the receiving end's
687umask setting
8dc74608 688(which is the same behavior as other file-copy utilities, such as cp).
41059f75 689
eb06fa95 690dit(bf(-o, --owner)) This option causes rsync to set the owner of the
d38772e0
WD
691destination file to be the same as the source file. By default, the
692preservation is done by name, but may fall back to using the ID number
693in some circumstances (see the bf(--numeric-ids) option for a full
694discussion).
695This option has no effect if the receiving rsync is not run as the
696super-user and bf(--super) is not specified.
41059f75 697
eb06fa95
MP
698dit(bf(-g, --group)) This option causes rsync to set the group of the
699destination file to be the same as the source file. If the receiving
d38772e0
WD
700program is not running as the super-user (or with the bf(--no-super)
701option), only groups that the
a2b0471f
WD
702receiver is a member of will be preserved. By default, the preservation
703is done by name, but may fall back to using the ID number in some
faa82484 704circumstances. See the bf(--numeric-ids) option for a full discussion.
41059f75 705
4e7d07c8 706dit(bf(--devices)) This option causes rsync to transfer character and
d38772e0
WD
707block device files to the remote system to recreate these devices.
708This option has no effect if the receiving rsync is not run as the
709super-user and bf(--super) is not specified.
41059f75 710
4e7d07c8
WD
711dit(bf(--specials)) This option causes rsync to transfer special files
712such as named sockets and fifos.
713
714dit(bf(-D)) The bf(-D) option is equivalent to bf(--devices) bf(--specials).
715
41059f75 716dit(bf(-t, --times)) This tells rsync to transfer modification times along
baf3e504
DD
717with the files and update them on the remote system. Note that if this
718option is not used, the optimization that excludes files that have not been
faa82484
WD
719modified cannot be effective; in other words, a missing bf(-t) or bf(-a) will
720cause the next transfer to behave as if it used bf(-I), causing all files to be
d0bc3520 721updated (though the rsync algorithm will make the update fairly efficient
faa82484 722if the files haven't actually changed, you're much better off using bf(-t)).
41059f75 723
54e66f1d 724dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
faa82484
WD
725it is preserving modification times (see bf(--times)). If NFS is sharing
726the directories on the receiving side, it is a good idea to use bf(-O).
fbe5eeb8 727This option is inferred if you use bf(--backup) without bf(--backup-dir).
54e66f1d 728
d38772e0
WD
729dit(bf(--super)) This tells the receiving side to attempt super-user
730activities even if the receiving rsync wasn't run by the super-user. These
731activities include: preserving users via the bf(--owner) option, preserving
732all groups (not just the current user's groups) via the bf(--groups)
733option, and copying devices via the bf(--devices) option. This is useful
734for systems that allow such activities without being the super-user, and
735also for ensuring that you will get errors if the receiving side isn't
736being running as the super-user. To turn off super-user activities, the
737super-user can use bf(--no-super).
738
facdce2c 739dit(bf(--chmod)) This option tells rsync to apply the listed "chmod" pattern
9e8ea423
WD
740to the permission of the files on the destination. In addition to the normal
741parsing rules specified in the chmod manpage, you can specify an item that
742should only apply to a directory by prefixing it with a 'D', or specify an
743item that should only apply to a file by prefixing it with a 'F'. For example:
744
745quote(--chmod=Dg+s,ug+w,Fo-w,+X)
746
57b66a24
WD
747It is also legal to specify multiple bf(--chmod) options.
748
41059f75
AT
749dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
750instead it will just report the actions it would have taken.
751
752dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
a8cbb57c
WD
753up less space on the destination. Conflicts with bf(--inplace) because it's
754not possible to overwrite data in a sparse fashion.
41059f75 755
d310a212
AT
756NOTE: Don't use this option when the destination is a Solaris "tmpfs"
757filesystem. It doesn't seem to handle seeks over null regions
758correctly and ends up corrupting the files.
759
4e5baafe
WD
760dit(bf(-x, --one-file-system)) This tells rsync to avoid crossing a
761filesystem boundary when recursing. This does not limit the user's ability
762to specify items to copy from multiple filesystems, just rsync's recursion
763through the hierarchy of each directory that the user specified, and also
764the analogous recursion on the receiving side during deletion. Also keep
765in mind that rsync treats a "bind" mount to the same device as being on the
766same filesystem.
767
768If this option is repeated, rsync omits all mount-point directories from
769the copy. Otherwise, it includes an empty directory at each mount-point it
770encounters (using the attributes of the mounted directory because those of
771the underlying mount-point directory are inaccessible).
772
773If rsync has been told to collapse symlinks (via bf(--copy-links) or
774bf(--copy-unsafe-links)), a symlink to a directory on another device is
49140b27
WD
775treated like a mount-point. Symlinks to non-directories are unaffected
776by this option.
6d8c6bdb 777
9639c718
WD
778dit(bf(--existing, --ignore-non-existing)) This tells rsync to skip
779updating files that do not exist yet on the destination. If this option is
780combined with the bf(--ignore-existing) option, no files will be updated
781(which can be useful if all you want to do is to delete missing files).
782
40aaa571
WD
783dit(bf(--ignore-existing)) This tells rsync to skip updating files that
784already exist on the destination. See also bf(--ignore-non-existing).
1347d512 785
96110304
WD
786dit(bf(--remove-sent-files)) This tells rsync to remove from the sending
787side the files and/or symlinks that are newly created or whose content is
788updated on the receiving side. Directories and devices are not removed,
789nor are files/symlinks whose attributes are merely changed.
790
2c0fa6c5 791dit(bf(--delete)) This tells rsync to delete extraneous files from the
e8b155a3
WD
792receiving side (ones that aren't on the sending side), but only for the
793directories that are being synchronized. You must have asked rsync to
794send the whole directory (e.g. "dir" or "dir/") without using a wildcard
795for the directory's contents (e.g. "dir/*") since the wildcard is expanded
ae76a740 796by the shell and rsync thus gets a request to transfer individual files, not
e8b155a3 797the files' parent directory. Files that are excluded from transfer are
0dfffb88
WD
798also excluded from being deleted unless you use the bf(--delete-excluded)
799option or mark the rules as only matching on the sending side (see the
800include/exclude modifiers in the FILTER RULES section).
41059f75 801
505ada14
WD
802Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
803was in effect. Beginning with 2.6.7, deletions will also occur when bf(--dirs)
57b66a24 804(bf(-d)) is in effect, but only for directories whose contents are being copied.
24986abd 805
b33b791e 806This option can be dangerous if used incorrectly! It is a very good idea
faa82484 807to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
b33b791e 808deleted to make sure important files aren't listed.
41059f75 809
e8b155a3 810If the sending side detects any I/O errors, then the deletion of any
3e578a19
AT
811files at the destination will be automatically disabled. This is to
812prevent temporary filesystem failures (such as NFS errors) on the
813sending side causing a massive deletion of files on the
faa82484 814destination. You can override this with the bf(--ignore-errors) option.
41059f75 815
faa82484
WD
816The bf(--delete) option may be combined with one of the --delete-WHEN options
817without conflict, as well as bf(--delete-excluded). However, if none of the
2c0fa6c5 818--delete-WHEN options are specified, rsync will currently choose the
faa82484
WD
819bf(--delete-before) algorithm. A future version may change this to choose the
820bf(--delete-during) algorithm. See also bf(--delete-after).
2c0fa6c5
WD
821
822dit(bf(--delete-before)) Request that the file-deletions on the receiving
faa82484
WD
823side be done before the transfer starts. This is the default if bf(--delete)
824or bf(--delete-excluded) is specified without one of the --delete-WHEN options.
825See bf(--delete) (which is implied) for more details on file-deletion.
2c0fa6c5
WD
826
827Deleting before the transfer is helpful if the filesystem is tight for space
aaca3daa 828and removing extraneous files would help to make the transfer possible.
ae76a740 829However, it does introduce a delay before the start of the transfer,
faa82484 830and this delay might cause the transfer to timeout (if bf(--timeout) was
ae76a740
WD
831specified).
832
2c0fa6c5
WD
833dit(bf(--delete-during, --del)) Request that the file-deletions on the
834receiving side be done incrementally as the transfer happens. This is
ae283632 835a faster method than choosing the before- or after-transfer algorithm,
ae76a740 836but it is only supported beginning with rsync version 2.6.4.
faa82484 837See bf(--delete) (which is implied) for more details on file-deletion.
aaca3daa 838
2c0fa6c5 839dit(bf(--delete-after)) Request that the file-deletions on the receiving
ae76a740
WD
840side be done after the transfer has completed. This is useful if you
841are sending new per-directory merge files as a part of the transfer and
842you want their exclusions to take effect for the delete phase of the
843current transfer.
faa82484 844See bf(--delete) (which is implied) for more details on file-deletion.
e8b155a3 845
866925bf
WD
846dit(bf(--delete-excluded)) In addition to deleting the files on the
847receiving side that are not on the sending side, this tells rsync to also
faa82484 848delete any files on the receiving side that are excluded (see bf(--exclude)).
0dfffb88
WD
849See the FILTER RULES section for a way to make individual exclusions behave
850this way on the receiver, and for a way to protect files from
851bf(--delete-excluded).
faa82484 852See bf(--delete) (which is implied) for more details on file-deletion.
866925bf 853
faa82484 854dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
b5accaba 855even when there are I/O errors.
2c5548d2 856
b3964d1d
WD
857dit(bf(--force)) This option tells rsync to delete a non-empty directory
858when it is to be replaced by a non-directory. This is only relevant if
859deletions are not active (see bf(--delete) for details).
860
861Note for older rsync versions: bf(--force) used to still be required when
862using bf(--delete-after), and it used to be non-functional unless the
863bf(--recursive) option was also enabled.
41059f75 864
e2124620 865dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
3b2ef5b1
WD
866files or directories (NUM must be non-zero).
867This is useful when mirroring very large trees to prevent disasters.
e2124620
WD
868
869dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
870file that is larger than the specified SIZE. The SIZE value can be
926d86d1 871suffixed with a string to indicate a size multiplier, and
e2124620
WD
872may be a fractional value (e.g. "bf(--max-size=1.5m)").
873
bee9df73
WD
874The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024),
875"M" (or "MiB") is a mebibyte (1024*1024), and "G" (or "GiB") is a
876gibibyte (1024*1024*1024).
877If you want the multiplier to be 1000 instead of 1024, use "KB",
878"MB", or "GB". (Note: lower-case is also accepted for all values.)
926d86d1
WD
879Finally, if the suffix ends in either "+1" or "-1", the value will
880be offset by one byte in the indicated direction.
bee9df73
WD
881
882Examples: --max-size=1.5mb-1 is 1499999 bytes, and --max-size=2g+1 is
926d86d1
WD
8832147483649 bytes.
884
59dd6786
WD
885dit(bf(--min-size=SIZE)) This tells rsync to avoid transferring any
886file that is smaller than the specified SIZE, which can help in not
887transferring small, junk files.
888See the bf(--max-size) option for a description of SIZE.
889
3ed8eb3f
WD
890dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
891the rsync algorithm to a fixed value. It is normally selected based on
892the size of each file being updated. See the technical report for details.
41059f75 893
b5679335 894dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
41059f75 895remote shell program to use for communication between the local and
43cd760f
WD
896remote copies of rsync. Typically, rsync is configured to use ssh by
897default, but you may prefer to use rsh on a local network.
41059f75 898
bef49340 899If this option is used with bf([user@]host::module/path), then the
5a727522 900remote shell em(COMMAND) will be used to run an rsync daemon on the
bef49340
WD
901remote host, and all data will be transmitted through that remote
902shell connection, rather than through a direct socket connection to a
754a080f
WD
903running rsync daemon on the remote host. See the section "USING
904RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" above.
bef49340 905
ea7f8108 906Command-line arguments are permitted in COMMAND provided that COMMAND is
5d9530fe
WD
907presented to rsync as a single argument. You must use spaces (not tabs
908or other whitespace) to separate the command and args from each other,
909and you can use single- and/or double-quotes to preserve spaces in an
910argument (but not backslashes). Note that doubling a single-quote
911inside a single-quoted string gives you a single-quote; likewise for
912double-quotes (though you need to pay attention to which quotes your
913shell is parsing and which quotes rsync is parsing). Some examples:
98393ae2 914
5d9530fe
WD
915quote(
916tt( -e 'ssh -p 2234')nl()
917tt( -e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"')nl()
918)
98393ae2
WD
919
920(Note that ssh users can alternately customize site-specific connect
921options in their .ssh/config file.)
922
41059f75 923You can also choose the remote shell program using the RSYNC_RSH
faa82484 924environment variable, which accepts the same range of values as bf(-e).
41059f75 925
faa82484 926See also the bf(--blocking-io) option which is affected by this option.
735a816e 927
68e169ab
WD
928dit(bf(--rsync-path=PROGRAM)) Use this to specify what program is to be run
929on the remote machine to start-up rsync. Often used when rsync is not in
930the default remote-shell's path (e.g. --rsync-path=/usr/local/bin/rsync).
931Note that PROGRAM is run with the help of a shell, so it can be any
932program, script, or command sequence you'd care to run, so long as it does
933not corrupt the standard-in & standard-out that rsync is using to
934communicate.
935
936One tricky example is to set a different default directory on the remote
937machine for use with the bf(--relative) option. For instance:
938
939quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/))
41059f75 940
f177b7cc
WD
941dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
942broad range of files that you often don't want to transfer between
943systems. It uses the same algorithm that CVS uses to determine if
944a file should be ignored.
945
946The exclude list is initialized to:
947
faa82484 948quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
2a383be0 949.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
faa82484 950.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)))
f177b7cc
WD
951
952then files listed in a $HOME/.cvsignore are added to the list and any
2a383be0
WD
953files listed in the CVSIGNORE environment variable (all cvsignore names
954are delimited by whitespace).
955
f177b7cc 956Finally, any file is ignored if it is in the same directory as a
bafa4875
WD
957.cvsignore file and matches one of the patterns listed therein. Unlike
958rsync's filter/exclude files, these patterns are split on whitespace.
2a383be0 959See the bf(cvs(1)) manual for more information.
f177b7cc 960
bafa4875
WD
961If you're combining bf(-C) with your own bf(--filter) rules, you should
962note that these CVS excludes are appended at the end of your own rules,
3753975f 963regardless of where the bf(-C) was placed on the command-line. This makes them
bafa4875
WD
964a lower priority than any rules you specified explicitly. If you want to
965control where these CVS excludes get inserted into your filter rules, you
966should omit the bf(-C) as a command-line option and use a combination of
967bf(--filter=:C) and bf(--filter=-C) (either on your command-line or by
968putting the ":C" and "-C" rules into a filter file with your other rules).
969The first option turns on the per-directory scanning for the .cvsignore
970file. The second option does a one-time import of the CVS excludes
971mentioned above.
972
16e5de84
WD
973dit(bf(-f, --filter=RULE)) This option allows you to add rules to selectively
974exclude certain files from the list of files to be transferred. This is
975most useful in combination with a recursive transfer.
41059f75 976
faa82484 977You may use as many bf(--filter) options on the command line as you like
41059f75
AT
978to build up the list of files to exclude.
979
16e5de84
WD
980See the FILTER RULES section for detailed information on this option.
981
faa82484 982dit(bf(-F)) The bf(-F) option is a shorthand for adding two bf(--filter) rules to
16e5de84
WD
983your command. The first time it is used is a shorthand for this rule:
984
78be8e0f 985quote(tt( --filter='dir-merge /.rsync-filter'))
16e5de84
WD
986
987This tells rsync to look for per-directory .rsync-filter files that have
988been sprinkled through the hierarchy and use their rules to filter the
faa82484 989files in the transfer. If bf(-F) is repeated, it is a shorthand for this
16e5de84
WD
990rule:
991
78be8e0f 992quote(tt( --filter='exclude .rsync-filter'))
16e5de84
WD
993
994This filters out the .rsync-filter files themselves from the transfer.
995
996See the FILTER RULES section for detailed information on how these options
997work.
998
999dit(bf(--exclude=PATTERN)) This option is a simplified form of the
faa82484 1000bf(--filter) option that defaults to an exclude rule and does not allow
16e5de84
WD
1001the full rule-parsing syntax of normal filter rules.
1002
1003See the FILTER RULES section for detailed information on this option.
41059f75 1004
78be8e0f
WD
1005dit(bf(--exclude-from=FILE)) This option is related to the bf(--exclude)
1006option, but it specifies a FILE that contains exclude patterns (one per line).
1007Blank lines in the file and lines starting with ';' or '#' are ignored.
1008If em(FILE) is bf(-), the list will be read from standard input.
f8a94f0d 1009
16e5de84 1010dit(bf(--include=PATTERN)) This option is a simplified form of the
faa82484 1011bf(--filter) option that defaults to an include rule and does not allow
16e5de84 1012the full rule-parsing syntax of normal filter rules.
43bd68e5 1013
16e5de84 1014See the FILTER RULES section for detailed information on this option.
43bd68e5 1015
78be8e0f
WD
1016dit(bf(--include-from=FILE)) This option is related to the bf(--include)
1017option, but it specifies a FILE that contains include patterns (one per line).
1018Blank lines in the file and lines starting with ';' or '#' are ignored.
1019If em(FILE) is bf(-), the list will be read from standard input.
f8a94f0d 1020
f177b7cc 1021dit(bf(--files-from=FILE)) Using this option allows you to specify the
78be8e0f 1022exact list of files to transfer (as read from the specified FILE or bf(-)
c769702f 1023for standard input). It also tweaks the default behavior of rsync to make
faa82484
WD
1024transferring just the specified files and directories easier:
1025
1026quote(itemize(
1027 it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
1028 information that is specified for each item in the file (use
f40aa6fb 1029 bf(--no-relative) or bf(--no-R) if you want to turn that off).
faa82484
WD
1030 it() The bf(--dirs) (bf(-d)) option is implied, which will create directories
1031 specified in the list on the destination rather than noisily skipping
f40aa6fb 1032 them (use bf(--no-dirs) or bf(--no-d) if you want to turn that off).
faa82484
WD
1033 it() The bf(--archive) (bf(-a)) option's behavior does not imply bf(--recursive)
1034 (bf(-r)), so specify it explicitly, if you want it.
f40aa6fb
WD
1035 it() These side-effects change the default state of rsync, so the position
1036 of the bf(--files-from) option on the command-line has no bearing on how
1037 other options are parsed (e.g. bf(-a) works the same before or after
1038 bf(--files-from), as does bf(--no-R) and all other options).
faa82484 1039))
f177b7cc
WD
1040
1041The file names that are read from the FILE are all relative to the
1042source dir -- any leading slashes are removed and no ".." references are
1043allowed to go higher than the source dir. For example, take this
1044command:
1045
faa82484 1046quote(tt( rsync -a --files-from=/tmp/foo /usr remote:/backup))
f177b7cc
WD
1047
1048If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
51cc96e4
WD
1049directory will be created as /backup/bin on the remote host. If it
1050contains "bin/" (note the trailing slash), the immediate contents of
1051the directory would also be sent (without needing to be explicitly
1052mentioned in the file -- this began in version 2.6.4). In both cases,
1053if the bf(-r) option was enabled, that dir's entire hierarchy would
1054also be transferred (keep in mind that bf(-r) needs to be specified
1055explicitly with bf(--files-from), since it is not implied by bf(-a)).
1056Also note
faa82484 1057that the effect of the (enabled by default) bf(--relative) option is to
f177b7cc
WD
1058duplicate only the path info that is read from the file -- it does not
1059force the duplication of the source-spec path (/usr in this case).
1060
faa82484 1061In addition, the bf(--files-from) file can be read from the remote host
f177b7cc
WD
1062instead of the local host if you specify a "host:" in front of the file
1063(the host must match one end of the transfer). As a short-cut, you can
1064specify just a prefix of ":" to mean "use the remote end of the
1065transfer". For example:
1066
faa82484 1067quote(tt( rsync -a --files-from=:/path/file-list src:/ /tmp/copy))
f177b7cc
WD
1068
1069This would copy all the files specified in the /path/file-list file that
1070was located on the remote "src" host.
1071
fa92818a 1072dit(bf(-0, --from0)) This tells rsync that the rules/filenames it reads from a
f177b7cc 1073file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
faa82484
WD
1074This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any
1075merged files specified in a bf(--filter) rule.
1076It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore
f01b6368 1077file are split on whitespace).
41059f75 1078
b5679335 1079dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
a9af5d8e
WD
1080scratch directory when creating temporary copies of the files transferred
1081on the receiving side. The default behavior is to create each temporary
1082file in the same directory as the associated destination file.
41059f75 1083
9ec1ef25
WD
1084This option is most often used when the receiving disk partition does not
1085have enough free space to hold a copy of the largest file in the transfer.
1086In this case (i.e. when the scratch directory in on a different disk
1087partition), rsync will not be able to rename each received temporary file
1088over the top of the associated destination file, but instead must copy it
1089into place. Rsync does this by copying the file over the top of the
1090destination file, which means that the destination file will contain
a9af5d8e
WD
1091truncated data during this copy. If this were not done this way (even if
1092the destination file were first removed, the data locally copied to a
1093temporary file in the destination directory, and then renamed into place)
1094it would be possible for the old file to continue taking up disk space (if
1095someone had it open), and thus there might not be enough room to fit the
1096new version on the disk at the same time.
9ec1ef25
WD
1097
1098If you are using this option for reasons other than a shortage of disk
1099space, you may wish to combine it with the bf(--delay-updates) option,
a0d9819f
WD
1100which will ensure that all copied files get put into subdirectories in the
1101destination hierarchy, awaiting the end of the transfer. If you don't
1102have enough room to duplicate all the arriving files on the destination
1103partition, another way to tell rsync that you aren't overly concerned
1104about disk space is to use the bf(--partial-dir) option with a relative
1105path; because this tells rsync that it is OK to stash off a copy of a
1106single file in a subdir in the destination hierarchy, rsync will use the
1107partial-dir as a staging area to bring over the copied file, and then
1108rename it into place from there. (Specifying a bf(--partial-dir) with
1109an absolute path does not have this side-effect.)
9ec1ef25 1110
5b483755
WD
1111dit(bf(-y, --fuzzy)) This option tells rsync that it should look for a
1112basis file for any destination file that is missing. The current algorithm
1113looks in the same directory as the destination file for either a file that
1114has an identical size and modified-time, or a similarly-named file. If
1115found, rsync uses the fuzzy basis file to try to speed up the transfer.
1116
1117Note that the use of the bf(--delete) option might get rid of any potential
1118fuzzy-match files, so either use bf(--delete-after) or specify some
1119filename exclusions if you need to prevent this.
1120
b127c1dc 1121dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on
e49f61f5
WD
1122the destination machine as an additional hierarchy to compare destination
1123files against doing transfers (if the files are missing in the destination
1124directory). If a file is found in em(DIR) that is identical to the
1125sender's file, the file will NOT be transferred to the destination
1126directory. This is useful for creating a sparse backup of just files that
1127have changed from an earlier backup.
1128
faa82484 1129Beginning in version 2.6.4, multiple bf(--compare-dest) directories may be
99eb41b2
WD
1130provided, which will cause rsync to search the list in the order specified
1131for an exact match.
2f03ce67
WD
1132If a match is found that differs only in attributes, a local copy is made
1133and the attributes updated.
99eb41b2
WD
1134If a match is not found, a basis file from one of the em(DIR)s will be
1135selected to try to speed up the transfer.
e49f61f5
WD
1136
1137If em(DIR) is a relative path, it is relative to the destination directory.
2f03ce67 1138See also bf(--copy-dest) and bf(--link-dest).
b127c1dc 1139
2f03ce67
WD
1140dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but
1141rsync will also copy unchanged files found in em(DIR) to the destination
1142directory using a local copy.
1143This is useful for doing transfers to a new destination while leaving
1144existing files intact, and then doing a flash-cutover when all files have
1145been successfully transferred.
1146
1147Multiple bf(--copy-dest) directories may be provided, which will cause
1148rsync to search the list in the order specified for an unchanged file.
1149If a match is not found, a basis file from one of the em(DIR)s will be
1150selected to try to speed up the transfer.
1151
1152If em(DIR) is a relative path, it is relative to the destination directory.
1153See also bf(--compare-dest) and bf(--link-dest).
1154
1155dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but
e49f61f5
WD
1156unchanged files are hard linked from em(DIR) to the destination directory.
1157The files must be identical in all preserved attributes (e.g. permissions,
1158possibly ownership) in order for the files to be linked together.
8429aa9e
WD
1159An example:
1160
faa82484 1161quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
59c95e42 1162
99eb41b2
WD
1163Beginning in version 2.6.4, multiple bf(--link-dest) directories may be
1164provided, which will cause rsync to search the list in the order specified
1165for an exact match.
2f03ce67
WD
1166If a match is found that differs only in attributes, a local copy is made
1167and the attributes updated.
99eb41b2
WD
1168If a match is not found, a basis file from one of the em(DIR)s will be
1169selected to try to speed up the transfer.
e49f61f5
WD
1170
1171If em(DIR) is a relative path, it is relative to the destination directory.
2f03ce67 1172See also bf(--compare-dest) and bf(--copy-dest).
b127c1dc 1173
e0204f56 1174Note that rsync versions prior to 2.6.1 had a bug that could prevent
d38772e0
WD
1175bf(--link-dest) from working properly for a non-super-user when bf(-o) was
1176specified (or implied by bf(-a)). You can work-around this bug by avoiding
1177the bf(-o) option when sending to an old rsync.
e0204f56 1178
32a5edf4
WD
1179dit(bf(-z, --compress)) With this option, rsync compresses the file data
1180as it is sent to the destination machine, which reduces the amount of data
1181being transmitted -- something that is useful over a slow connection.
41059f75 1182
32a5edf4
WD
1183Note this this option typically achieves better compression ratios that can
1184be achieved by using a compressing remote shell or a compressing transport
1185because it takes advantage of the implicit information in the matching data
1186blocks that are not explicitly sent over the connection.
41059f75 1187
bad01106
WD
1188dit(bf(--compress-level=NUM)) Explicitly set the compression level to use
1189(see bf(--compress)) instead of letting it default. If NUM is non-zero,
1190the bf(--compress) option is implied.
1191
41059f75 1192dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
4d888108 1193and user IDs rather than using user and group names and mapping them
41059f75
AT
1194at both ends.
1195
4d888108 1196By default rsync will use the username and groupname to determine
41059f75 1197what ownership to give files. The special uid 0 and the special group
faa82484 11980 are never mapped via user/group names even if the bf(--numeric-ids)
41059f75
AT
1199option is not specified.
1200
ec40899b
WD
1201If a user or group has no name on the source system or it has no match
1202on the destination system, then the numeric ID
1203from the source system is used instead. See also the comments on the
a2b0471f
WD
1204"use chroot" setting in the rsyncd.conf manpage for information on how
1205the chroot setting affects rsync's ability to look up the names of the
1206users and groups and what you can do about it.
41059f75 1207
b5accaba 1208dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
de2fd20e
AT
1209timeout in seconds. If no data is transferred for the specified time
1210then rsync will exit. The default is 0, which means no timeout.
41059f75 1211
3ae5367f
WD
1212dit(bf(--address)) By default rsync will bind to the wildcard address when
1213connecting to an rsync daemon. The bf(--address) option allows you to
1214specify a specific IP address (or hostname) to bind to. See also this
1215option in the bf(--daemon) mode section.
1216
c259892c
WD
1217dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
1218rather than the default of 873. This is only needed if you are using the
1219double-colon (::) syntax to connect with an rsync daemon (since the URL
1220syntax has a way to specify the port as a part of the URL). See also this
faa82484 1221option in the bf(--daemon) mode section.
c259892c 1222
04f48837
WD
1223dit(bf(--sockopts)) This option can provide endless fun for people
1224who like to tune their systems to the utmost degree. You can set all
1225sorts of socket options which may make transfers faster (or
1226slower!). Read the man page for the setsockopt() system call for
1227details on some of the options you may be able to set. By default no
1228special socket options are set. This only affects direct socket
1229connections to a remote rsync daemon. This option also exists in the
1230bf(--daemon) mode section.
1231
b5accaba 1232dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching
314a74d7
WD
1233a remote shell transport. If the remote shell is either rsh or remsh,
1234rsync defaults to using
b5accaba
WD
1235blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
1236ssh prefers non-blocking I/O.)
64c704f0 1237
0cfdf226 1238dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
4f90eb43 1239changes that are being made to each file, including attribute changes.
ea67c715 1240This is exactly the same as specifying bf(--log-format='%i %n%L').
14cbb645
WD
1241If you repeat the option, unchanged files will also be output, but only
1242if the receiving rsync is at least version 2.6.7 (you can use bf(-vv)
1243with older versions of rsync, but that also turns on the output of other
1244verbose messages).
ea67c715 1245
a314f7c1 1246The "%i" escape has a cryptic output that is 9 letters long. The general
669302a1 1247format is like the string bf(UXcstpog)), where bf(U) is replaced by the
a314f7c1
WD
1248kind of update being done, bf(X) is replaced by the file-type, and the
1249other letters represent attributes that may be output if they are being
ee171c6d 1250modified.
ea67c715 1251
a314f7c1 1252The update types that replace the bf(U) are as follows:
ea67c715 1253
a314f7c1 1254quote(itemize(
cc3e0770 1255 it() A bf(<) means that a file is being transferred to the remote host
a314f7c1 1256 (sent).
cc3e0770
WD
1257 it() A bf(>) means that a file is being transferred to the local host
1258 (received).
c48cff9f 1259 it() A bf(c) means that a local change/creation is occurring for the item
ee171c6d 1260 (such as the creation of a directory or the changing of a symlink, etc.).
b4875de4
WD
1261 it() A bf(h) means that the item is a hard-link to another item (requires
1262 bf(--hard-links)).
ee171c6d
WD
1263 it() A bf(.) means that the item is not being updated (though it might
1264 have attributes that are being modified).
a314f7c1 1265))
ea67c715 1266
a314f7c1 1267The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a
4e7d07c8
WD
1268directory, an bf(L) for a symlink, a bf(D) for a device, and a bf(S) for a
1269special file (e.g. named sockets and fifos).
ea67c715 1270
a314f7c1 1271The other letters in the string above are the actual letters that
ea67c715
WD
1272will be output if the associated attribute for the item is being updated or
1273a "." for no change. Three exceptions to this are: (1) a newly created
b9f0ca72
WD
1274item replaces each letter with a "+", (2) an identical item replaces the
1275dots with spaces, and (3) an unknown attribute replaces each letter with
81c453b1 1276a "?" (this can happen when talking to an older rsync).
ea67c715
WD
1277
1278The attribute that is associated with each letter is as follows:
1279
1280quote(itemize(
1281 it() A bf(c) means the checksum of the file is different and will be
c48cff9f 1282 updated by the file transfer (requires bf(--checksum)).
ea67c715
WD
1283 it() A bf(s) means the size of the file is different and will be updated
1284 by the file transfer.
1285 it() A bf(t) means the modification time is different and is being updated
5a727522 1286 to the sender's value (requires bf(--times)). An alternate value of bf(T)
ea67c715
WD
1287 means that the time will be set to the transfer time, which happens
1288 anytime a symlink is transferred, or when a file or device is transferred
1289 without bf(--times).
1290 it() A bf(p) means the permissions are different and are being updated to
5a727522 1291 the sender's value (requires bf(--perms)).
4dc67d5e 1292 it() An bf(o) means the owner is different and is being updated to the
d38772e0 1293 sender's value (requires bf(--owner) and super-user privileges).
4dc67d5e 1294 it() A bf(g) means the group is different and is being updated to the
5a727522 1295 sender's value (requires bf(--group) and the authority to set the group).
ea67c715
WD
1296))
1297
1298One other output is possible: when deleting files, the "%i" will output
ee171c6d 1299the string "*deleting" for each item that is being removed (assuming that
ea67c715
WD
1300you are talking to a recent enough rsync that it logs deletions instead of
1301outputting them as a verbose message).
dc0f2497 1302
3a64ad1f 1303dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
ea67c715
WD
1304rsync client outputs to the user on a per-file basis. The format is a text
1305string containing embedded single-character escape sequences prefixed with
1306a percent (%) character. For a list of the possible escape characters, see
1307the "log format" setting in the rsyncd.conf manpage. (Note that this
1308option does not affect what a daemon logs to its logfile.)
1309
1310Specifying this option will mention each file, dir, etc. that gets updated
1311in a significant way (a transferred file, a recreated symlink/device, or a
1312touched directory) unless the itemized-changes escape (%i) is included in
1313the string, in which case the logging of names increases to mention any
81c453b1 1314item that is changed in any way (as long as the receiving side is at least
7c6ea3d8 13152.6.4). See the bf(--itemize-changes) option for a description of the
ea67c715
WD
1316output of "%i".
1317
1318The bf(--verbose) option implies a format of "%n%L", but you can use
a9af5d8e 1319bf(--log-format) without bf(--verbose) if you like, or you can override
ea67c715
WD
1320the format of its per-file output using this option.
1321
1322Rsync will output the log-format string prior to a file's transfer unless
1323one of the transfer-statistic escapes is requested, in which case the
1324logging is done at the end of the file's transfer. When this late logging
1325is in effect and bf(--progress) is also specified, rsync will also output
1326the name of the file being transferred prior to its progress information
1327(followed, of course, by the log-format output).
b6062654 1328
b72f24c7
AT
1329dit(bf(--stats)) This tells rsync to print a verbose set of statistics
1330on the file transfer, allowing you to tell how effective the rsync
e19452a9 1331algorithm is for your data.
b72f24c7 1332
955c3145 1333dit(bf(-h, --human-readable)) Output numbers in a more human-readable format.
3b4ecc6b
WD
1334Large numbers may be output in larger units, with a K (1024), M (1024*1024),
1335or G (1024*1024*1024) suffix.
1336
1337dit(bf(--si)) Similar to the bf(--human-readable) option, but using powers
1338of 1000 instead of 1024.
1339
d9fcc198
AT
1340dit(bf(--partial)) By default, rsync will delete any partially
1341transferred file if the transfer is interrupted. In some circumstances
1342it is more desirable to keep partially transferred files. Using the
faa82484 1343bf(--partial) option tells rsync to keep the partial file which should
d9fcc198
AT
1344make a subsequent transfer of the rest of the file much faster.
1345
c2582307
WD
1346dit(bf(--partial-dir=DIR)) A better way to keep partial files than the
1347bf(--partial) option is to specify a em(DIR) that will be used to hold the
1348partial data (instead of writing it out to the destination file).
1349On the next transfer, rsync will use a file found in this
9ec1ef25 1350dir as data to speed up the resumption of the transfer and then delete it
c2582307 1351after it has served its purpose.
9ec1ef25 1352
c2582307
WD
1353Note that if bf(--whole-file) is specified (or implied), any partial-dir
1354file that is found for a file that is being updated will simply be removed
1355(since
b90a6d9f 1356rsync is sending files without using the incremental rsync algorithm).
44cad59f 1357
c2582307
WD
1358Rsync will create the em(DIR) if it is missing (just the last dir -- not
1359the whole path). This makes it easy to use a relative path (such as
1360"bf(--partial-dir=.rsync-partial)") to have rsync create the
1361partial-directory in the destination file's directory when needed, and then
1362remove it again when the partial file is deleted.
44cad59f 1363
c2582307 1364If the partial-dir value is not an absolute path, rsync will also add a directory
faa82484 1365bf(--exclude) of this value at the end of all your existing excludes. This
a33857da
WD
1366will prevent partial-dir files from being transferred and also prevent the
1367untimely deletion of partial-dir items on the receiving side. An example:
faa82484 1368the above bf(--partial-dir) option would add an "bf(--exclude=.rsync-partial/)"
16e5de84 1369rule at the end of any other filter rules. Note that if you are
4c72f27d
WD
1370supplying your own exclude rules, you may need to manually insert your own
1371exclude/protect rule somewhere higher up in the list so that
a33857da 1372it has a high enough priority to be effective (e.g., if your rules specify
4c72f27d 1373a trailing inclusion/exclusion of '*', the auto-added rule would never be
c2582307 1374reached).
44cad59f 1375
faa82484 1376IMPORTANT: the bf(--partial-dir) should not be writable by other users or it
b4d1e854
WD
1377is a security risk. E.g. AVOID "/tmp".
1378
1379You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
faa82484
WD
1380variable. Setting this in the environment does not force bf(--partial) to be
1381enabled, but rather it effects where partial files go when bf(--partial) is
1382specified. For instance, instead of using bf(--partial-dir=.rsync-tmp)
1383along with bf(--progress), you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
1384environment and then just use the bf(-P) option to turn on the use of the
9ec1ef25
WD
1385.rsync-tmp dir for partial transfers. The only times that the bf(--partial)
1386option does not look for this environment value are (1) when bf(--inplace) was
1387specified (since bf(--inplace) conflicts with bf(--partial-dir)), and (2) when
faa82484 1388bf(--delay-updates) was specified (see below).
01b835c2 1389
5a727522 1390For the purposes of the daemon-config's "refuse options" setting,
c2582307
WD
1391bf(--partial-dir) does em(not) imply bf(--partial). This is so that a
1392refusal of the bf(--partial) option can be used to disallow the overwriting
1393of destination files with a partial transfer, while still allowing the
1394safer idiom provided by bf(--partial-dir).
1395
01b835c2 1396dit(bf(--delay-updates)) This option puts the temporary file from each
c2582307 1397updated file into a holding directory until the end of the
01b835c2
WD
1398transfer, at which time all the files are renamed into place in rapid
1399succession. This attempts to make the updating of the files a little more
c2582307 1400atomic. By default the files are placed into a directory named ".~tmp~" in
64318670
WD
1401each file's destination directory, but if you've specified the
1402bf(--partial-dir) option, that directory will be used instead.
1403Conflicts with bf(--inplace) and bf(--append).
01b835c2
WD
1404
1405This option uses more memory on the receiving side (one bit per file
1406transferred) and also requires enough free disk space on the receiving
1407side to hold an additional copy of all the updated files. Note also that
5efbddba
WD
1408you should not use an absolute path to bf(--partial-dir) unless (1)
1409there is no
01b835c2
WD
1410chance of any of the files in the transfer having the same name (since all
1411the updated files will be put into a single directory if the path is
5efbddba
WD
1412absolute)
1413and (2) there are no mount points in the hierarchy (since the
1414delayed updates will fail if they can't be renamed into place).
01b835c2
WD
1415
1416See also the "atomic-rsync" perl script in the "support" subdir for an
faa82484 1417update algorithm that is even more atomic (it uses bf(--link-dest) and a
01b835c2 1418parallel hierarchy of files).
44cad59f 1419
a272ff8c 1420dit(bf(-m, --prune-empty-dirs)) This option tells the receiving rsync to get
fb72aaba
WD
1421rid of empty directories from the file-list, including nested directories
1422that have no non-directory children. This is useful for avoiding the
1423creation of a bunch of useless directories when the sending rsync is
1424recursively scanning a hierarchy of files using include/exclude/filter
a272ff8c
WD
1425rules.
1426
1427Because the file-list is actually being pruned, this option also affects
1428what directories get deleted when a delete is active. However, keep in
1429mind that excluded files and directories can prevent existing items from
1430being deleted (because an exclude hides source files and protects
1431destination files).
1432
1433You can prevent the pruning of certain empty directories from the file-list
1434by using a global "protect" filter. For instance, this option would ensure
1435that the directory "emptydir" was kept in the file-list:
1436
1437quote( --filter 'protect emptydir/')
fb72aaba
WD
1438
1439Here's an example that copies all .pdf files in a hierarchy, only creating
1440the necessary destination directories to hold the .pdf files, and ensures
1441that any superfluous files and directories in the destination are removed
a272ff8c
WD
1442(note the hide filter of non-directories being used instead of an exclude):
1443
1444quote( rsync -avm --del --include='*.pdf' -f 'hide! */' src/ dest)
fb72aaba 1445
a272ff8c
WD
1446If you didn't want to remove superfluous destination files, the more
1447time-honored options of "--include='*/' --exclude='*'" would work fine
1448in place of the hide-filter (if that is more natural to you).
fb72aaba 1449
eb86d661
AT
1450dit(bf(--progress)) This option tells rsync to print information
1451showing the progress of the transfer. This gives a bored user
1452something to watch.
c2582307 1453Implies bf(--verbose) if it wasn't already specified.
7b10f91d 1454
68f9910d
WD
1455When the file is transferring, the data looks like this:
1456
faa82484 1457verb( 782448 63% 110.64kB/s 0:00:04)
68f9910d
WD
1458
1459This tells you the current file size, the percentage of the transfer that
1460is complete, the current calculated file-completion rate (including both
1461data over the wire and data being matched locally), and the estimated time
1462remaining in this transfer.
1463
c2c14fa2 1464After a file is complete, the data looks like this:
68f9910d 1465
faa82484 1466verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396))
68f9910d
WD
1467
1468This tells you the final file size, that it's 100% complete, the final
1469transfer rate for the file, the amount of elapsed time it took to transfer
1470the file, and the addition of a total-transfer summary in parentheses.
1471These additional numbers tell you how many files have been updated, and
1472what percent of the total number of files has been scanned.
1473
faa82484 1474dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). Its
183150b7
WD
1475purpose is to make it much easier to specify these two options for a long
1476transfer that may be interrupted.
d9fcc198 1477
65575e96 1478dit(bf(--password-file)) This option allows you to provide a password
5a727522
WD
1479in a file for accessing a remote rsync daemon. Note that this option
1480is only useful when accessing an rsync daemon using the built in
65575e96 1481transport, not when using a remote shell as the transport. The file
fc7952e7
AT
1482must not be world readable. It should contain just the password as a
1483single line.
65575e96 1484
09ed3099
WD
1485dit(bf(--list-only)) This option will cause the source files to be listed
1486instead of transferred. This option is inferred if there is no destination
1487specified, so you don't usually need to use it explicitly. However, it can
15997547 1488come in handy for a user that wants to avoid the "bf(-r --exclude='/*/*')"
09ed3099 1489options that rsync might use as a compatibility kluge when generating a
15997547
WD
1490non-recursive listing, or to list the files that are involved in a local
1491copy (since the destination path is not optional for a local copy, you
1492must specify this option explicitly and still include a destination).
09ed3099 1493
ef5d23eb
DD
1494dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
1495transfer rate in kilobytes per second. This option is most effective when
1496using rsync with large files (several megabytes and up). Due to the nature
1497of rsync transfers, blocks of data are sent, then if rsync determines the
1498transfer was too fast, it will wait before sending the next data block. The
4d888108 1499result is an average transfer rate equaling the specified limit. A value
ef5d23eb
DD
1500of zero specifies no limit.
1501
b9f592fb 1502dit(bf(--write-batch=FILE)) Record a file that can later be applied to
faa82484 1503another identical destination with bf(--read-batch). See the "BATCH MODE"
32c7f91a 1504section for details, and also the bf(--only-write-batch) option.
6902ed17 1505
326bb56e
WD
1506dit(bf(--only-write-batch=FILE)) Works like bf(--write-batch), except that
1507no updates are made on the destination system when creating the batch.
1508This lets you transport the changes to the destination system via some
32c7f91a
WD
1509other means and then apply the changes via bf(--read-batch).
1510
1511Note that you can feel free to write the batch directly to some portable
1512media: if this media fills to capacity before the end of the transfer, you
1513can just apply that partial transfer to the destination and repeat the
1514whole process to get the rest of the changes (as long as you don't mind a
1515partially updated destination system while the multi-update cycle is
1516happening).
1517
1518Also note that you only save bandwidth when pushing changes to a remote
1519system because this allows the batched data to be diverted from the sender
1520into the batch file without having to flow over the wire to the receiver
1521(when pulling, the sender is remote, and thus can't write the batch).
326bb56e 1522
b9f592fb 1523dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
faa82484 1524file previously generated by bf(--write-batch).
78be8e0f 1525If em(FILE) is bf(-), the batch data will be read from standard input.
c769702f 1526See the "BATCH MODE" section for details.
6902ed17 1527
0b941479
WD
1528dit(bf(--protocol=NUM)) Force an older protocol version to be used. This
1529is useful for creating a batch file that is compatible with an older
1530version of rsync. For instance, if rsync 2.6.4 is being used with the
1531bf(--write-batch) option, but rsync 2.6.3 is what will be used to run the
81c453b1
WD
1532bf(--read-batch) option, you should use "--protocol=28" when creating the
1533batch file to force the older protocol version to be used in the batch
1534file (assuming you can't upgrade the rsync on the reading system).
0b941479 1535
e40a46de
WD
1536dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
1537when creating sockets. This only affects sockets that rsync has direct
1538control over, such as the outgoing socket when directly contacting an
faa82484 1539rsync daemon. See also these options in the bf(--daemon) mode section.
e40a46de 1540
c8d895de
WD
1541dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
1542NUM. This 4 byte checksum seed is included in each block and file
1543MD4 checksum calculation. By default the checksum seed is generated
b9f592fb 1544by the server and defaults to the current time(). This option
c8d895de
WD
1545is used to set a specific checksum seed, which is useful for
1546applications that want repeatable block and file checksums, or
1547in the case where the user wants a more random checksum seed.
1548Note that setting NUM to 0 causes rsync to use the default of time()
b9f592fb 1549for checksum seed.
41059f75
AT
1550enddit()
1551
faa82484
WD
1552manpagesection(DAEMON OPTIONS)
1553
bdf278f7
WD
1554The options allowed when starting an rsync daemon are as follows:
1555
1556startdit()
bdf278f7 1557dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
62f27e3c
WD
1558daemon you start running may be accessed using an rsync client using
1559the bf(host::module) or bf(rsync://host/module/) syntax.
bdf278f7
WD
1560
1561If standard input is a socket then rsync will assume that it is being
1562run via inetd, otherwise it will detach from the current terminal and
1563become a background daemon. The daemon will read the config file
1564(rsyncd.conf) on each connect made by a client and respond to
1565requests accordingly. See the rsyncd.conf(5) man page for more
1566details.
1567
3ae5367f
WD
1568dit(bf(--address)) By default rsync will bind to the wildcard address when
1569run as a daemon with the bf(--daemon) option. The bf(--address) option
1570allows you to specify a specific IP address (or hostname) to bind to. This
1571makes virtual hosting possible in conjunction with the bf(--config) option.
1572See also the "address" global option in the rsyncd.conf manpage.
bdf278f7 1573
1f69bec4
WD
1574dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
1575transfer rate in kilobytes per second for the data the daemon sends.
faa82484 1576The client can still specify a smaller bf(--bwlimit) value, but their
1f69bec4
WD
1577requested value will be rounded down if they try to exceed it. See the
1578client version of this option (above) for some extra details.
1579
bdf278f7 1580dit(bf(--config=FILE)) This specifies an alternate config file than
faa82484 1581the default. This is only relevant when bf(--daemon) is specified.
bdf278f7 1582The default is /etc/rsyncd.conf unless the daemon is running over
d38772e0 1583a remote shell program and the remote user is not the super-user; in that case
bdf278f7
WD
1584the default is rsyncd.conf in the current directory (typically $HOME).
1585
1586dit(bf(--no-detach)) When running as a daemon, this option instructs
1587rsync to not detach itself and become a background process. This
1588option is required when running as a service on Cygwin, and may also
1589be useful when rsync is supervised by a program such as
1590bf(daemontools) or AIX's bf(System Resource Controller).
1591bf(--no-detach) is also recommended when rsync is run under a
1592debugger. This option has no effect if rsync is run from inetd or
1593sshd.
1594
c259892c
WD
1595dit(bf(--port=PORT)) This specifies an alternate TCP port number for the
1596daemon to listen on rather than the default of 873. See also the "port"
1597global option in the rsyncd.conf manpage.
bdf278f7 1598
04f48837
WD
1599dit(bf(--sockopts)) This overrides the bf(socket options) setting in the
1600rsyncd.conf file and has the same syntax.
1601
24b0922b
WD
1602dit(bf(-v, --verbose)) This option increases the amount of information the
1603daemon logs during its startup phase. After the client connects, the
1604daemon's verbosity level will be controlled by the options that the client
1605used and the "max verbosity" setting in the module's config section.
1606
bdf278f7
WD
1607dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
1608when creating the incoming sockets that the rsync daemon will use to
1609listen for connections. One of these options may be required in older
1610versions of Linux to work around an IPv6 bug in the kernel (if you see
1611an "address already in use" error when nothing else is using the port,
faa82484 1612try specifying bf(--ipv6) or bf(--ipv4) when starting the daemon).
bdf278f7 1613
faa82484 1614dit(bf(-h, --help)) When specified after bf(--daemon), print a short help
bdf278f7 1615page describing the options available for starting an rsync daemon.
bdf278f7
WD
1616enddit()
1617
16e5de84 1618manpagesection(FILTER RULES)
43bd68e5 1619
16e5de84
WD
1620The filter rules allow for flexible selection of which files to transfer
1621(include) and which files to skip (exclude). The rules either directly
1622specify include/exclude patterns or they specify a way to acquire more
1623include/exclude patterns (e.g. to read them from a file).
43bd68e5 1624
16e5de84
WD
1625As the list of files/directories to transfer is built, rsync checks each
1626name to be transferred against the list of include/exclude patterns in
1627turn, and the first matching pattern is acted on: if it is an exclude
1628pattern, then that file is skipped; if it is an include pattern then that
1629filename is not skipped; if no matching pattern is found, then the
43bd68e5
AT
1630filename is not skipped.
1631
16e5de84
WD
1632Rsync builds an ordered list of filter rules as specified on the
1633command-line. Filter rules have the following syntax:
1634
faa82484 1635quote(
d91de046
WD
1636tt(RULE [PATTERN_OR_FILENAME])nl()
1637tt(RULE,MODIFIERS [PATTERN_OR_FILENAME])nl()
16e5de84
WD
1638)
1639
d91de046
WD
1640You have your choice of using either short or long RULE names, as described
1641below. If you use a short-named rule, the ',' separating the RULE from the
1642MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
1643must come after either a single space or an underscore (_).
1644Here are the available rule prefixes:
16e5de84 1645
faa82484 1646quote(
d91de046
WD
1647bf(exclude, -) specifies an exclude pattern. nl()
1648bf(include, +) specifies an include pattern. nl()
1649bf(merge, .) specifies a merge-file to read for more rules. nl()
1650bf(dir-merge, :) specifies a per-directory merge-file. nl()
0dfffb88
WD
1651bf(hide, H) specifies a pattern for hiding files from the transfer. nl()
1652bf(show, S) files that match the pattern are not hidden. nl()
1653bf(protect, P) specifies a pattern for protecting files from deletion. nl()
1654bf(risk, R) files that match the pattern are not protected. nl()
d91de046 1655bf(clear, !) clears the current include/exclude list (takes no arg) nl()
16e5de84
WD
1656)
1657
d91de046
WD
1658When rules are being read from a file, empty lines are ignored, as are
1659comment lines that start with a "#".
1660
faa82484 1661Note that the bf(--include)/bf(--exclude) command-line options do not allow the
16e5de84 1662full range of rule parsing as described above -- they only allow the
d91de046
WD
1663specification of include/exclude patterns plus a "!" token to clear the
1664list (and the normal comment parsing when rules are read from a file).
1665If a pattern
16e5de84
WD
1666does not begin with "- " (dash, space) or "+ " (plus, space), then the
1667rule will be interpreted as if "+ " (for an include option) or "- " (for
faa82484 1668an exclude option) were prefixed to the string. A bf(--filter) option, on
d91de046
WD
1669the other hand, must always contain either a short or long rule name at the
1670start of the rule.
16e5de84 1671
faa82484 1672Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one
16e5de84 1673rule/pattern each. To add multiple ones, you can repeat the options on
faa82484
WD
1674the command-line, use the merge-file syntax of the bf(--filter) option, or
1675the bf(--include-from)/bf(--exclude-from) options.
16e5de84 1676
16e5de84
WD
1677manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
1678
0dfffb88
WD
1679You can include and exclude files by specifying patterns using the "+",
1680"-", etc. filter rules (as introduced in the FILTER RULES section above).
bb5f4e72
WD
1681The include/exclude rules each specify a pattern that is matched against
1682the names of the files that are going to be transferred. These patterns
1683can take several forms:
16e5de84
WD
1684
1685itemize(
16e5de84
WD
1686 it() if the pattern starts with a / then it is anchored to a
1687 particular spot in the hierarchy of files, otherwise it is matched
1688 against the end of the pathname. This is similar to a leading ^ in
1689 regular expressions.
1690 Thus "/foo" would match a file called "foo" at either the "root of the
1691 transfer" (for a global rule) or in the merge-file's directory (for a
1692 per-directory rule).
1693 An unqualified "foo" would match any file or directory named "foo"
1694 anywhere in the tree because the algorithm is applied recursively from
1695 the
1696 top down; it behaves as if each path component gets a turn at being the
1697 end of the file name. Even the unanchored "sub/foo" would match at
1698 any point in the hierarchy where a "foo" was found within a directory
1699 named "sub". See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for
1700 a full discussion of how to specify a pattern that matches at the root
1701 of the transfer.
16e5de84
WD
1702 it() if the pattern ends with a / then it will only match a
1703 directory, not a file, link, or device.
9639c718
WD
1704
1705 it() rsync chooses between doing a simple string match and wildcard
1706 matching by checking if the pattern contains one of these three wildcard
1707 characters: '*', '?', and '[' .
1708 it() a '*' matches any non-empty path component (it stops at slashes).
1709 it() use '**' to match anything, including slashes.
1710 it() a '?' matches any character except a slash (/).
1711 it() a '[' introduces a character class, such as [a-z] or [[:alpha:]].
1712 it() in a wildcard pattern, a backslash can be used to escape a wildcard
1713 character, but it is matched literally when no wildcards are present.
1714 it() if the pattern contains a / (not counting a trailing /) or a "**",
16e5de84
WD
1715 then it is matched against the full pathname, including any leading
1716 directories. If the pattern doesn't contain a / or a "**", then it is
1717 matched only against the final component of the filename.
1718 (Remember that the algorithm is applied recursively so "full filename"
ae283632 1719 can actually be any portion of a path from the starting directory on
16e5de84 1720 down.)
d3db3eef
WD
1721 it() a trailing "dir_name/***" will match both the directory (as if
1722 "dir_name/" had been specified) and all the files in the directory
1723 (as if "dir_name/**" had been specified). (This behavior is new for
1724 version 2.6.7.)
16e5de84
WD
1725)
1726
faa82484
WD
1727Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by
1728bf(-a)), every subcomponent of every path is visited from the top down, so
16e5de84
WD
1729include/exclude patterns get applied recursively to each subcomponent's
1730full name (e.g. to include "/foo/bar/baz" the subcomponents "/foo" and
1731"/foo/bar" must not be excluded).
1732The exclude patterns actually short-circuit the directory traversal stage
1733when rsync finds the files to send. If a pattern excludes a particular
1734parent directory, it can render a deeper include pattern ineffectual
1735because rsync did not descend through that excluded section of the
1736hierarchy. This is particularly important when using a trailing '*' rule.
1737For instance, this won't work:
1738
faa82484
WD
1739quote(
1740tt(+ /some/path/this-file-will-not-be-found)nl()
1741tt(+ /file-is-included)nl()
1742tt(- *)nl()
16e5de84
WD
1743)
1744
1745This fails because the parent directory "some" is excluded by the '*'
1746rule, so rsync never visits any of the files in the "some" or "some/path"
1747directories. One solution is to ask for all directories in the hierarchy
a5a26484
WD
1748to be included by using a single rule: "+ */" (put it somewhere before the
1749"- *" rule). Another solution is to add specific include rules for all
16e5de84
WD
1750the parent dirs that need to be visited. For instance, this set of rules
1751works fine:
1752
faa82484
WD
1753quote(
1754tt(+ /some/)nl()
1755tt(+ /some/path/)nl()
1756tt(+ /some/path/this-file-is-found)nl()
1757tt(+ /file-also-included)nl()
1758tt(- *)nl()
16e5de84
WD
1759)
1760
1761Here are some examples of exclude/include matching:
1762
1763itemize(
1764 it() "- *.o" would exclude all filenames matching *.o
1765 it() "- /foo" would exclude a file called foo in the transfer-root directory
1766 it() "- foo/" would exclude any directory called foo
1767 it() "- /foo/*/bar" would exclude any file called bar two
1768 levels below a directory called foo in the transfer-root directory
1769 it() "- /foo/**/bar" would exclude any file called bar two
1770 or more levels below a directory called foo in the transfer-root directory
faa82484 1771 it() The combination of "+ */", "+ *.c", and "- *" would include all
16e5de84
WD
1772 directories and C source files but nothing else.
1773 it() The combination of "+ foo/", "+ foo/bar.c", and "- *" would include
1774 only the foo directory and foo/bar.c (the foo directory must be
1775 explicitly included or it would be excluded by the "*")
1776)
1777
1778manpagesection(MERGE-FILE FILTER RULES)
1779
1780You can merge whole files into your filter rules by specifying either a
d91de046
WD
1781merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES
1782section above).
16e5de84
WD
1783
1784There are two kinds of merged files -- single-instance ('.') and
1785per-directory (':'). A single-instance merge file is read one time, and
1786its rules are incorporated into the filter list in the place of the "."
1787rule. For per-directory merge files, rsync will scan every directory that
1788it traverses for the named file, merging its contents when the file exists
1789into the current list of inherited rules. These per-directory rule files
1790must be created on the sending side because it is the sending side that is
1791being scanned for the available files to transfer. These rule files may
1792also need to be transferred to the receiving side if you want them to
1793affect what files don't get deleted (see PER-DIRECTORY RULES AND DELETE
1794below).
1795
1796Some examples:
1797
faa82484 1798quote(
d91de046 1799tt(merge /etc/rsync/default.rules)nl()
faa82484 1800tt(. /etc/rsync/default.rules)nl()
d91de046
WD
1801tt(dir-merge .per-dir-filter)nl()
1802tt(dir-merge,n- .non-inherited-per-dir-excludes)nl()
faa82484 1803tt(:n- .non-inherited-per-dir-excludes)nl()
16e5de84
WD
1804)
1805
d91de046 1806The following modifiers are accepted after a merge or dir-merge rule:
16e5de84
WD
1807
1808itemize(
62bf783f 1809 it() A bf(-) specifies that the file should consist of only exclude
d91de046 1810 patterns, with no other rule-parsing except for in-file comments.
62bf783f 1811 it() A bf(+) specifies that the file should consist of only include
d91de046
WD
1812 patterns, with no other rule-parsing except for in-file comments.
1813 it() A bf(C) is a way to specify that the file should be read in a
1814 CVS-compatible manner. This turns on 'n', 'w', and '-', but also
1815 allows the list-clearing token (!) to be specified. If no filename is
1816 provided, ".cvsignore" is assumed.
1817 it() A bf(e) will exclude the merge-file name from the transfer; e.g.
a5a26484 1818 "dir-merge,e .rules" is like "dir-merge .rules" and "- .rules".
62bf783f
WD
1819 it() An bf(n) specifies that the rules are not inherited by subdirectories.
1820 it() A bf(w) specifies that the rules are word-split on whitespace instead
16e5de84
WD
1821 of the normal line-splitting. This also turns off comments. Note: the
1822 space that separates the prefix from the rule is treated specially, so
d91de046
WD
1823 "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't
1824 also disabled).
1825 it() You may also specify any of the modifiers for the "+" or "-" rules
1826 (below) in order to have the rules that are read-in from the file
a5a26484 1827 default to having that modifier set. For instance, "merge,-/ .excl" would
0dfffb88
WD
1828 treat the contents of .excl as absolute-path excludes,
1829 while "dir-merge,s .filt" and ":sC" would each make all their
5a727522 1830 per-directory rules apply only on the sending side.
16e5de84
WD
1831)
1832
44d60d5f 1833The following modifiers are accepted after a "+" or "-":
dc1488ae
WD
1834
1835itemize(
82360c6b
WD
1836 it() A "/" specifies that the include/exclude rule should be matched
1837 against the absolute pathname of the current item. For example,
a5a26484 1838 "-/ /etc/passwd" would exclude the passwd file any time the transfer
82360c6b
WD
1839 was sending files from the "/etc" directory, and "-/ subdir/foo"
1840 would always exclude "foo" when it is in a dir named "subdir", even
1841 if "foo" is at the root of the current transfer.
44d60d5f
WD
1842 it() A "!" specifies that the include/exclude should take effect if
1843 the pattern fails to match. For instance, "-! */" would exclude all
1844 non-directories.
397a3443
WD
1845 it() A bf(C) is used to indicate that all the global CVS-exclude rules
1846 should be inserted as excludes in place of the "-C". No arg should
1847 follow.
0dfffb88
WD
1848 it() An bf(s) is used to indicate that the rule applies to the sending
1849 side. When a rule affects the sending side, it prevents files from
1850 being transferred. The default is for a rule to affect both sides
1851 unless bf(--delete-excluded) was specified, in which case default rules
1852 become sender-side only. See also the hide (H) and show (S) rules,
5a727522 1853 which are an alternate way to specify sending-side includes/excludes.
0dfffb88
WD
1854 it() An bf(r) is used to indicate that the rule applies to the receiving
1855 side. When a rule affects the receiving side, it prevents files from
1856 being deleted. See the bf(s) modifier for more info. See also the
1857 protect (P) and risk (R) rules, which are an alternate way to
1858 specify receiver-side includes/excludes.
1859)
dc1488ae 1860
16e5de84
WD
1861Per-directory rules are inherited in all subdirectories of the directory
1862where the merge-file was found unless the 'n' modifier was used. Each
1863subdirectory's rules are prefixed to the inherited per-directory rules
1864from its parents, which gives the newest rules a higher priority than the
d91de046 1865inherited rules. The entire set of dir-merge rules are grouped together in
16e5de84 1866the spot where the merge-file was specified, so it is possible to override
d91de046 1867dir-merge rules via a rule that got specified earlier in the list of global
16e5de84
WD
1868rules. When the list-clearing rule ("!") is read from a per-directory
1869file, it only clears the inherited rules for the current merge file.
1870
d91de046 1871Another way to prevent a single rule from a dir-merge file from being inherited is to
16e5de84
WD
1872anchor it with a leading slash. Anchored rules in a per-directory
1873merge-file are relative to the merge-file's directory, so a pattern "/foo"
d91de046 1874would only match the file "foo" in the directory where the dir-merge filter
16e5de84
WD
1875file was found.
1876
faa82484 1877Here's an example filter file which you'd specify via bf(--filter=". file":)
16e5de84 1878
faa82484 1879quote(
d91de046 1880tt(merge /home/user/.global-filter)nl()
faa82484 1881tt(- *.gz)nl()
d91de046 1882tt(dir-merge .rules)nl()
faa82484
WD
1883tt(+ *.[ch])nl()
1884tt(- *.o)nl()
16e5de84
WD
1885)
1886
1887This will merge the contents of the /home/user/.global-filter file at the
1888start of the list and also turns the ".rules" filename into a per-directory
1889filter file. All rules read-in prior to the start of the directory scan
1890follow the global anchoring rules (i.e. a leading slash matches at the root
1891of the transfer).
1892
1893If a per-directory merge-file is specified with a path that is a parent
1894directory of the first transfer directory, rsync will scan all the parent
1895dirs from that starting point to the transfer directory for the indicated
faa82484 1896per-directory file. For instance, here is a common filter (see bf(-F)):
16e5de84 1897
faa82484 1898quote(tt(--filter=': /.rsync-filter'))
16e5de84
WD
1899
1900That rule tells rsync to scan for the file .rsync-filter in all
1901directories from the root down through the parent directory of the
1902transfer prior to the start of the normal directory scan of the file in
1903the directories that are sent as a part of the transfer. (Note: for an
1904rsync daemon, the root is always the same as the module's "path".)
1905
1906Some examples of this pre-scanning for per-directory files:
1907
faa82484
WD
1908quote(
1909tt(rsync -avF /src/path/ /dest/dir)nl()
1910tt(rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir)nl()
1911tt(rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir)nl()
16e5de84
WD
1912)
1913
1914The first two commands above will look for ".rsync-filter" in "/" and
1915"/src" before the normal scan begins looking for the file in "/src/path"
1916and its subdirectories. The last command avoids the parent-dir scan
1917and only looks for the ".rsync-filter" files in each directory that is
1918a part of the transfer.
1919
1920If you want to include the contents of a ".cvsignore" in your patterns,
d91de046
WD
1921you should use the rule ":C", which creates a dir-merge of the .cvsignore
1922file, but parsed in a CVS-compatible manner. You can
faa82484 1923use this to affect where the bf(--cvs-exclude) (bf(-C)) option's inclusion of the
d91de046 1924per-directory .cvsignore file gets placed into your rules by putting the
16e5de84 1925":C" wherever you like in your filter rules. Without this, rsync would
d91de046 1926add the dir-merge rule for the .cvsignore file at the end of all your other
16e5de84
WD
1927rules (giving it a lower priority than your command-line rules). For
1928example:
1929
faa82484
WD
1930quote(
1931tt(cat <<EOT | rsync -avC --filter='. -' a/ b)nl()
1932tt(+ foo.o)nl()
1933tt(:C)nl()
1934tt(- *.old)nl()
1935tt(EOT)nl()
1936tt(rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b)nl()
16e5de84
WD
1937)
1938
1939Both of the above rsync commands are identical. Each one will merge all
1940the per-directory .cvsignore rules in the middle of the list rather than
1941at the end. This allows their dir-specific rules to supersede the rules
bafa4875
WD
1942that follow the :C instead of being subservient to all your rules. To
1943affect the other CVS exclude rules (i.e. the default list of exclusions,
1944the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
1945omit the bf(-C) command-line option and instead insert a "-C" rule into
1946your filter rules; e.g. "--filter=-C".
16e5de84
WD
1947
1948manpagesection(LIST-CLEARING FILTER RULE)
1949
1950You can clear the current include/exclude list by using the "!" filter
1951rule (as introduced in the FILTER RULES section above). The "current"
1952list is either the global list of rules (if the rule is encountered while
1953parsing the filter options) or a set of per-directory rules (which are
1954inherited in their own sub-list, so a subdirectory can use this to clear
1955out the parent's rules).
1956
1957manpagesection(ANCHORING INCLUDE/EXCLUDE PATTERNS)
1958
1959As mentioned earlier, global include/exclude patterns are anchored at the
1960"root of the transfer" (as opposed to per-directory patterns, which are
1961anchored at the merge-file's directory). If you think of the transfer as
1962a subtree of names that are being sent from sender to receiver, the
1963transfer-root is where the tree starts to be duplicated in the destination
1964directory. This root governs where patterns that start with a / match.
a4b6f305
WD
1965
1966Because the matching is relative to the transfer-root, changing the
faa82484 1967trailing slash on a source path or changing your use of the bf(--relative)
a4b6f305
WD
1968option affects the path you need to use in your matching (in addition to
1969changing how much of the file tree is duplicated on the destination
16e5de84 1970host). The following examples demonstrate this.
a4b6f305 1971
b5ebe6d9
WD
1972Let's say that we want to match two source files, one with an absolute
1973path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
1974Here is how the various command choices differ for a 2-source transfer:
a4b6f305 1975
faa82484
WD
1976quote(
1977 Example cmd: rsync -a /home/me /home/you /dest nl()
1978 +/- pattern: /me/foo/bar nl()
1979 +/- pattern: /you/bar/baz nl()
1980 Target file: /dest/me/foo/bar nl()
1981 Target file: /dest/you/bar/baz nl()
1982)
1983
1984quote(
1985 Example cmd: rsync -a /home/me/ /home/you/ /dest nl()
1986 +/- pattern: /foo/bar (note missing "me") nl()
1987 +/- pattern: /bar/baz (note missing "you") nl()
1988 Target file: /dest/foo/bar nl()
1989 Target file: /dest/bar/baz nl()
1990)
1991
1992quote(
1993 Example cmd: rsync -a --relative /home/me/ /home/you /dest nl()
1994 +/- pattern: /home/me/foo/bar (note full path) nl()
1995 +/- pattern: /home/you/bar/baz (ditto) nl()
1996 Target file: /dest/home/me/foo/bar nl()
1997 Target file: /dest/home/you/bar/baz nl()
1998)
1999
2000quote(
2001 Example cmd: cd /home; rsync -a --relative me/foo you/ /dest nl()
2002 +/- pattern: /me/foo/bar (starts at specified path) nl()
2003 +/- pattern: /you/bar/baz (ditto) nl()
2004 Target file: /dest/me/foo/bar nl()
2005 Target file: /dest/you/bar/baz nl()
a4b6f305
WD
2006)
2007
16e5de84 2008The easiest way to see what name you should filter is to just
faa82484
WD
2009look at the output when using bf(--verbose) and put a / in front of the name
2010(use the bf(--dry-run) option if you're not yet ready to copy any files).
d1cce1dd 2011
16e5de84 2012manpagesection(PER-DIRECTORY RULES AND DELETE)
43bd68e5 2013
16e5de84
WD
2014Without a delete option, per-directory rules are only relevant on the
2015sending side, so you can feel free to exclude the merge files themselves
2016without affecting the transfer. To make this easy, the 'e' modifier adds
2017this exclude for you, as seen in these two equivalent commands:
27b9a19b 2018
faa82484
WD
2019quote(
2020tt(rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest)nl()
2021tt(rsync -av --filter=':e .excl' host:src/dir /dest)nl()
43bd68e5
AT
2022)
2023
16e5de84
WD
2024However, if you want to do a delete on the receiving side AND you want some
2025files to be excluded from being deleted, you'll need to be sure that the
2026receiving side knows what files to exclude. The easiest way is to include
faa82484 2027the per-directory merge files in the transfer and use bf(--delete-after),
16e5de84
WD
2028because this ensures that the receiving side gets all the same exclude
2029rules as the sending side before it tries to delete anything:
43bd68e5 2030
faa82484 2031quote(tt(rsync -avF --delete-after host:src/dir /dest))
20af605e 2032
16e5de84
WD
2033However, if the merge files are not a part of the transfer, you'll need to
2034either specify some global exclude rules (i.e. specified on the command
2035line), or you'll need to maintain your own per-directory merge files on
2036the receiving side. An example of the first is this (assume that the
2037remote .rules files exclude themselves):
20af605e 2038
faa82484
WD
2039verb(rsync -av --filter=': .rules' --filter='. /my/extra.rules'
2040 --delete host:src/dir /dest)
20af605e 2041
16e5de84
WD
2042In the above example the extra.rules file can affect both sides of the
2043transfer, but (on the sending side) the rules are subservient to the rules
2044merged from the .rules files because they were specified after the
2045per-directory merge rule.
43bd68e5 2046
16e5de84
WD
2047In one final example, the remote side is excluding the .rsync-filter
2048files from the transfer, but we want to use our own .rsync-filter files
2049to control what gets deleted on the receiving side. To do this we must
2050specifically exclude the per-directory merge files (so that they don't get
2051deleted) and then put rules into the local files to control what else
2052should not get deleted. Like one of these commands:
2053
faa82484
WD
2054verb( rsync -av --filter=':e /.rsync-filter' --delete \
2055 host:src/dir /dest
2056 rsync -avFF --delete host:src/dir /dest)
43bd68e5 2057
6902ed17
MP
2058manpagesection(BATCH MODE)
2059
088aac85
DD
2060Batch mode can be used to apply the same set of updates to many
2061identical systems. Suppose one has a tree which is replicated on a
2062number of hosts. Now suppose some changes have been made to this
2063source tree and those changes need to be propagated to the other
2064hosts. In order to do this using batch mode, rsync is run with the
2065write-batch option to apply the changes made to the source tree to one
2066of the destination trees. The write-batch option causes the rsync
b9f592fb
WD
2067client to store in a "batch file" all the information needed to repeat
2068this operation against other, identical destination trees.
2069
2070To apply the recorded changes to another destination tree, run rsync
2071with the read-batch option, specifying the name of the same batch
2072file, and the destination tree. Rsync updates the destination tree
2073using the information stored in the batch file.
2074
2075For convenience, one additional file is creating when the write-batch
2076option is used. This file's name is created by appending
73e01568 2077".sh" to the batch filename. The .sh file contains
b9f592fb
WD
2078a command-line suitable for updating a destination tree using that
2079batch file. It can be executed using a Bourne(-like) shell, optionally
2080passing in an alternate destination tree pathname which is then used
2081instead of the original path. This is useful when the destination tree
2082path differs from the original destination tree path.
2083
2084Generating the batch file once saves having to perform the file
2085status, checksum, and data block generation more than once when
088aac85 2086updating multiple destination trees. Multicast transport protocols can
b9f592fb
WD
2087be used to transfer the batch update files in parallel to many hosts
2088at once, instead of sending the same data to every host individually.
088aac85 2089
4602eafa 2090Examples:
088aac85 2091
faa82484
WD
2092quote(
2093tt($ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/)nl()
2094tt($ scp foo* remote:)nl()
2095tt($ ssh remote ./foo.sh /bdest/dir/)nl()
4602eafa
WD
2096)
2097
faa82484
WD
2098quote(
2099tt($ rsync --write-batch=foo -a /source/dir/ /adest/dir/)nl()
2100tt($ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo)nl()
4602eafa
WD
2101)
2102
98f51bfb
WD
2103In these examples, rsync is used to update /adest/dir/ from /source/dir/
2104and the information to repeat this operation is stored in "foo" and
2105"foo.sh". The host "remote" is then updated with the batched data going
2106into the directory /bdest/dir. The differences between the two examples
2107reveals some of the flexibility you have in how you deal with batches:
2108
2109itemize(
98f51bfb
WD
2110 it() The first example shows that the initial copy doesn't have to be
2111 local -- you can push or pull data to/from a remote host using either the
2112 remote-shell syntax or rsync daemon syntax, as desired.
98f51bfb
WD
2113 it() The first example uses the created "foo.sh" file to get the right
2114 rsync options when running the read-batch command on the remote host.
98f51bfb
WD
2115 it() The second example reads the batch data via standard input so that
2116 the batch file doesn't need to be copied to the remote machine first.
2117 This example avoids the foo.sh script because it needed to use a modified
faa82484 2118 bf(--read-batch) option, but you could edit the script file if you wished to
98f51bfb 2119 make use of it (just be sure that no other option is trying to use
faa82484 2120 standard input, such as the "bf(--exclude-from=-)" option).
98f51bfb 2121)
088aac85
DD
2122
2123Caveats:
2124
98f51bfb 2125The read-batch option expects the destination tree that it is updating
088aac85
DD
2126to be identical to the destination tree that was used to create the
2127batch update fileset. When a difference between the destination trees
0b941479 2128is encountered the update might be discarded with a warning (if the file
7432ccf4
WD
2129appears to be up-to-date already) or the file-update may be attempted
2130and then, if the file fails to verify, the update discarded with an
2131error. This means that it should be safe to re-run a read-batch operation
59d73bf3 2132if the command got interrupted. If you wish to force the batched-update to
faa82484 2133always be attempted regardless of the file's size and date, use the bf(-I)
59d73bf3
WD
2134option (when reading the batch).
2135If an error occurs, the destination tree will probably be in a
7432ccf4 2136partially updated state. In that case, rsync can
088aac85
DD
2137be used in its regular (non-batch) mode of operation to fix up the
2138destination tree.
2139
b9f592fb 2140The rsync version used on all destinations must be at least as new as the
59d73bf3
WD
2141one used to generate the batch file. Rsync will die with an error if the
2142protocol version in the batch file is too new for the batch-reading rsync
0b941479
WD
2143to handle. See also the bf(--protocol) option for a way to have the
2144creating rsync generate a batch file that an older rsync can understand.
2145(Note that batch files changed format in version 2.6.3, so mixing versions
2146older than that with newer versions will not work.)
088aac85 2147
7432ccf4
WD
2148When reading a batch file, rsync will force the value of certain options
2149to match the data in the batch file if you didn't set them to the same
2150as the batch-writing command. Other options can (and should) be changed.
bb5f4e72
WD
2151For instance bf(--write-batch) changes to bf(--read-batch),
2152bf(--files-from) is dropped, and the
2153bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless
2154one of the bf(--delete) options is specified.
b9f592fb 2155
faa82484 2156The code that creates the BATCH.sh file transforms any filter/include/exclude
98f51bfb
WD
2157options into a single list that is appended as a "here" document to the
2158shell script file. An advanced user can use this to modify the exclude
faa82484 2159list if a change in what gets deleted by bf(--delete) is desired. A normal
98f51bfb 2160user can ignore this detail and just use the shell script as an easy way
faa82484 2161to run the appropriate bf(--read-batch) command for the batched data.
98f51bfb 2162
59d73bf3
WD
2163The original batch mode in rsync was based on "rsync+", but the latest
2164version uses a new implementation.
6902ed17 2165
eb06fa95
MP
2166manpagesection(SYMBOLIC LINKS)
2167
f28bd833 2168Three basic behaviors are possible when rsync encounters a symbolic
eb06fa95
MP
2169link in the source directory.
2170
2171By default, symbolic links are not transferred at all. A message
2172"skipping non-regular" file is emitted for any symlinks that exist.
2173
2174If bf(--links) is specified, then symlinks are recreated with the same
2175target on the destination. Note that bf(--archive) implies
2176bf(--links).
2177
2178If bf(--copy-links) is specified, then symlinks are "collapsed" by
2179copying their referent, rather than the symlink.
2180
2181rsync also distinguishes "safe" and "unsafe" symbolic links. An
2182example where this might be used is a web site mirror that wishes
2183ensure the rsync module they copy does not include symbolic links to
2184bf(/etc/passwd) in the public section of the site. Using
2185bf(--copy-unsafe-links) will cause any links to be copied as the file
2186they point to on the destination. Using bf(--safe-links) will cause
6efe9416
WD
2187unsafe links to be omitted altogether. (Note that you must specify
2188bf(--links) for bf(--safe-links) to have any effect.)
eb06fa95 2189
7bd0cf5b
MP
2190Symbolic links are considered unsafe if they are absolute symlinks
2191(start with bf(/)), empty, or if they contain enough bf("..")
2192components to ascend from the directory being copied.
2193
6efe9416
WD
2194Here's a summary of how the symlink options are interpreted. The list is
2195in order of precedence, so if your combination of options isn't mentioned,
2196use the first line that is a complete subset of your options:
2197
2198dit(bf(--copy-links)) Turn all symlinks into normal files (leaving no
2199symlinks for any other options to affect).
2200
2201dit(bf(--links --copy-unsafe-links)) Turn all unsafe symlinks into files
2202and duplicate all safe symlinks.
2203
2204dit(bf(--copy-unsafe-links)) Turn all unsafe symlinks into files, noisily
2205skip all safe symlinks.
2206
2207dit(bf(--links --safe-links)) Duplicate safe symlinks and skip unsafe
2208ones.
2209
2210dit(bf(--links)) Duplicate all symlinks.
2211
faa82484 2212manpagediagnostics()
d310a212 2213
14d43f1f 2214rsync occasionally produces error messages that may seem a little
d310a212 2215cryptic. The one that seems to cause the most confusion is "protocol
faa82484 2216version mismatch -- is your shell clean?".
d310a212
AT
2217
2218This message is usually caused by your startup scripts or remote shell
2219facility producing unwanted garbage on the stream that rsync is using
14d43f1f 2220for its transport. The way to diagnose this problem is to run your
d310a212
AT
2221remote shell like this:
2222
faa82484
WD
2223quote(tt(ssh remotehost /bin/true > out.dat))
2224
d310a212 2225then look at out.dat. If everything is working correctly then out.dat
2cfeab21 2226should be a zero length file. If you are getting the above error from
d310a212
AT
2227rsync then you will probably find that out.dat contains some text or
2228data. Look at the contents and try to work out what is producing
14d43f1f 2229it. The most common cause is incorrectly configured shell startup
d310a212
AT
2230scripts (such as .cshrc or .profile) that contain output statements
2231for non-interactive logins.
2232
16e5de84 2233If you are having trouble debugging filter patterns, then
faa82484 2234try specifying the bf(-vv) option. At this level of verbosity rsync will
e6c64e79
MP
2235show why each individual file is included or excluded.
2236
55b64e4b
MP
2237manpagesection(EXIT VALUES)
2238
2239startdit()
a73de5f3 2240dit(bf(0)) Success
faa82484
WD
2241dit(bf(1)) Syntax or usage error
2242dit(bf(2)) Protocol incompatibility
a73de5f3
WD
2243dit(bf(3)) Errors selecting input/output files, dirs
2244dit(bf(4)) Requested action not supported: an attempt
8212336a 2245was made to manipulate 64-bit files on a platform that cannot support
f28bd833 2246them; or an option was specified that is supported by the client and
8212336a 2247not by the server.
a73de5f3 2248dit(bf(5)) Error starting client-server protocol
124f349e 2249dit(bf(6)) Daemon unable to append to log-file
faa82484
WD
2250dit(bf(10)) Error in socket I/O
2251dit(bf(11)) Error in file I/O
2252dit(bf(12)) Error in rsync protocol data stream
2253dit(bf(13)) Errors with program diagnostics
2254dit(bf(14)) Error in IPC code
2255dit(bf(20)) Received SIGUSR1 or SIGINT
2256dit(bf(21)) Some error returned by waitpid()
2257dit(bf(22)) Error allocating core memory buffers
3c1e2ad9
WD
2258dit(bf(23)) Partial transfer due to error
2259dit(bf(24)) Partial transfer due to vanished source files
124f349e 2260dit(bf(25)) The --max-delete limit stopped deletions
faa82484 2261dit(bf(30)) Timeout in data send/receive
55b64e4b
MP
2262enddit()
2263
de2fd20e
AT
2264manpagesection(ENVIRONMENT VARIABLES)
2265
2266startdit()
de2fd20e 2267dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
faa82484 2268ignore patterns in .cvsignore files. See the bf(--cvs-exclude) option for
de2fd20e 2269more details.
de2fd20e 2270dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
ea7f8108 2271override the default shell used as the transport for rsync. Command line
faa82484 2272options are permitted after the command name, just as in the bf(-e) option.
4c3b4b25
AT
2273dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
2274redirect your rsync client to use a web proxy when connecting to a
2275rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
de2fd20e 2276dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
bb18e755 2277password allows you to run authenticated rsync connections to an rsync
de2fd20e
AT
2278daemon without user intervention. Note that this does not supply a
2279password to a shell transport such as ssh.
de2fd20e 2280dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
5a727522 2281are used to determine the default username sent to an rsync daemon.
4b2f6a7c 2282If neither is set, the username defaults to "nobody".
14d43f1f 2283dit(bf(HOME)) The HOME environment variable is used to find the user's
de2fd20e 2284default .cvsignore file.
de2fd20e
AT
2285enddit()
2286
41059f75
AT
2287manpagefiles()
2288
30e8c8e1 2289/etc/rsyncd.conf or rsyncd.conf
41059f75
AT
2290
2291manpageseealso()
2292
2293rsyncd.conf(5)
2294
41059f75
AT
2295manpagebugs()
2296
2297times are transferred as unix time_t values
2298
f28bd833 2299When transferring to FAT filesystems rsync may re-sync
38843171 2300unmodified files.
faa82484 2301See the comments on the bf(--modify-window) option.
38843171 2302
b5accaba 2303file permissions, devices, etc. are transferred as native numerical
41059f75
AT
2304values
2305
faa82484 2306see also the comments on the bf(--delete) option
41059f75 2307
38843171
DD
2308Please report bugs! See the website at
2309url(http://rsync.samba.org/)(http://rsync.samba.org/)
41059f75 2310
15997547
WD
2311manpagesection(VERSION)
2312
9ec8bd87 2313This man page is current for version 2.6.6 of rsync.
15997547 2314
41059f75
AT
2315manpagesection(CREDITS)
2316
2317rsync is distributed under the GNU public license. See the file
2318COPYING for details.
2319
41059f75 2320A WEB site is available at
3cd5eb3b
MP
2321url(http://rsync.samba.org/)(http://rsync.samba.org/). The site
2322includes an FAQ-O-Matic which may cover questions unanswered by this
2323manual page.
9e3c856a
AT
2324
2325The primary ftp site for rsync is
2326url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
41059f75
AT
2327
2328We would be delighted to hear from you if you like this program.
2329
9e3c856a
AT
2330This program uses the excellent zlib compression library written by
2331Jean-loup Gailly and Mark Adler.
41059f75
AT
2332
2333manpagesection(THANKS)
2334
2335Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
7ff701e8
MP
2336and David Bell for helpful suggestions, patches and testing of rsync.
2337I've probably missed some people, my apologies if I have.
2338
ce5f2732 2339Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
98f51bfb 2340Martin Pool, Wayne Davison, J.W. Schultz.
41059f75
AT
2341
2342manpageauthor()
2343
ce5f2732
MP
2344rsync was originally written by Andrew Tridgell and Paul Mackerras.
2345Many people have later contributed to it.
3cd5eb3b 2346
a5d74a18 2347Mailing lists for support and development are available at
faa82484 2348url(http://lists.samba.org)(lists.samba.org)