Annotation of embedaddon/rsync/rsync.1.md, revision 1.1.1.1
1.1 misho 1: # NAME
2:
3: rsync - a fast, versatile, remote (and local) file-copying tool
4:
5: # SYNOPSIS
6:
7: ```
8: Local:
9: rsync [OPTION...] SRC... [DEST]
10:
11: Access via remote shell:
12: Pull:
13: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
14: Push:
15: rsync [OPTION...] SRC... [USER@]HOST:DEST
16:
17: Access via rsync daemon:
18: Pull:
19: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
20: rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
21: Push:
22: rsync [OPTION...] SRC... [USER@]HOST::DEST
23: rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)
24: ```
25:
26: Usages with just one SRC arg and no DEST arg will list the source files instead
27: of copying.
28:
29: # DESCRIPTION
30:
31: Rsync is a fast and extraordinarily versatile file copying tool. It can copy
32: locally, to/from another host over any remote shell, or to/from a remote rsync
33: daemon. It offers a large number of options that control every aspect of its
34: behavior and permit very flexible specification of the set of files to be
35: copied. It is famous for its delta-transfer algorithm, which reduces the
36: amount of data sent over the network by sending only the differences between
37: the source files and the existing files in the destination. Rsync is widely
38: used for backups and mirroring and as an improved copy command for everyday
39: use.
40:
41: Rsync finds files that need to be transferred using a "quick check" algorithm
42: (by default) that looks for files that have changed in size or in last-modified
43: time. Any changes in the other preserved attributes (as requested by options)
44: are made on the destination file directly when the quick check indicates that
45: the file's data does not need to be updated.
46:
47: Some of the additional features of rsync are:
48:
49: - support for copying links, devices, owners, groups, and permissions
50: - exclude and exclude-from options similar to GNU tar
51: - a CVS exclude mode for ignoring the same files that CVS would ignore
52: - can use any transparent remote shell, including ssh or rsh
53: - does not require super-user privileges
54: - pipelining of file transfers to minimize latency costs
55: - support for anonymous or authenticated rsync daemons (ideal for mirroring)
56:
57: # GENERAL
58:
59: Rsync copies files either to or from a remote host, or locally on the current
60: host (it does not support copying files between two remote hosts).
61:
62: There are two different ways for rsync to contact a remote system: using a
63: remote-shell program as the transport (such as ssh or rsh) or contacting an
64: rsync daemon directly via TCP. The remote-shell transport is used whenever the
65: source or destination path contains a single colon (:) separator after a host
66: specification. Contacting an rsync daemon directly happens when the source or
67: destination path contains a double colon (::) separator after a host
68: specification, OR when an rsync:// URL is specified (see also the "USING
69: RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for an exception
70: to this latter rule).
71:
72: As a special case, if a single source arg is specified without a destination,
73: the files are listed in an output format similar to "`ls -l`".
74:
75: As expected, if neither the source or destination path specify a remote host,
76: the copy occurs locally (see also the `--list-only` option).
77:
78: Rsync refers to the local side as the client and the remote side as the server.
79: Don't confuse server with an rsync daemon. A daemon is always a server, but a
80: server can be either a daemon or a remote-shell spawned process.
81:
82: # SETUP
83:
84: See the file README.md for installation instructions.
85:
86: Once installed, you can use rsync to any machine that you can access via a
87: remote shell (as well as some that you can access using the rsync daemon-mode
88: protocol). For remote transfers, a modern rsync uses ssh for its
89: communications, but it may have been configured to use a different remote shell
90: by default, such as rsh or remsh.
91:
92: You can also specify any remote shell you like, either by using the `-e`
93: command line option, or by setting the RSYNC_RSH environment variable.
94:
95: Note that rsync must be installed on both the source and destination machines.
96:
97: # USAGE
98:
99: You use rsync in the same way you use rcp. You must specify a source and a
100: destination, one of which may be remote.
101:
102: Perhaps the best way to explain the syntax is with some examples:
103:
104: > rsync -t *.c foo:src/
105:
106: This would transfer all files matching the pattern `*.c` from the current
107: directory to the directory src on the machine foo. If any of the files already
108: exist on the remote system then the rsync remote-update protocol is used to
109: update the file by sending only the differences in the data. Note that the
110: expansion of wildcards on the command-line (`*.c`) into a list of files is
111: handled by the shell before it runs rsync and not by rsync itself (exactly the
112: same as all other Posix-style programs).
113:
114: > rsync -avz foo:src/bar /data/tmp
115:
116: This would recursively transfer all files from the directory src/bar on the
117: machine foo into the /data/tmp/bar directory on the local machine. The files
118: are transferred in archive mode, which ensures that symbolic links, devices,
119: attributes, permissions, ownerships, etc. are preserved in the transfer.
120: Additionally, compression will be used to reduce the size of data portions of
121: the transfer.
122:
123: > rsync -avz foo:src/bar/ /data/tmp
124:
125: A trailing slash on the source changes this behavior to avoid creating an
126: additional directory level at the destination. You can think of a trailing /
127: on a source as meaning "copy the contents of this directory" as opposed to
128: "copy the directory by name", but in both cases the attributes of the
129: containing directory are transferred to the containing directory on the
130: destination. In other words, each of the following commands copies the files
131: in the same way, including their setting of the attributes of /dest/foo:
132:
133: > rsync -av /src/foo /dest
134: > rsync -av /src/foo/ /dest/foo
135:
136: Note also that host and module references don't require a trailing slash to
137: copy the contents of the default directory. For example, both of these copy
138: the remote directory's contents into "/dest":
139:
140: > rsync -av host: /dest
141: > rsync -av host::module /dest
142:
143: You can also use rsync in local-only mode, where both the source and
144: destination don't have a ':' in the name. In this case it behaves like an
145: improved copy command.
146:
147: Finally, you can list all the (listable) modules available from a particular
148: rsync daemon by leaving off the module name:
149:
150: > rsync somehost.mydomain.com::
151:
152: And, if Service Location Protocol is available, the following will list the
153: available rsync servers:
154:
155: > rsync rsync://
156:
157: See the following section for even more usage details.
158:
159: One more thing, if Service Location Protocol is available, the following will
160: list the available rsync servers:
161:
162: > rsync rsync://
163:
164: See the following section for even more usage details.
165:
166: # ADVANCED USAGE
167:
168: The syntax for requesting multiple files from a remote host is done by
169: specifying additional remote-host args in the same style as the first, or with
170: the hostname omitted. For instance, all these work:
171:
172: > rsync -av host:file1 :file2 host:file{3,4} /dest/
173: > rsync -av host::modname/file{1,2} host::modname/file3 /dest/
174: > rsync -av host::modname/file1 ::modname/file{3,4}
175:
176: Older versions of rsync required using quoted spaces in the SRC, like these
177: examples:
178:
179: > rsync -av host:'dir1/file1 dir2/file2' /dest
180: > rsync host::'modname/dir1/file1 modname/dir2/file2' /dest
181:
182: This word-splitting still works (by default) in the latest rsync, but is not as
183: easy to use as the first method.
184:
185: If you need to transfer a filename that contains whitespace, you can either
186: specify the `--protect-args` (`-s`) option, or you'll need to escape the
187: whitespace in a way that the remote shell will understand. For instance:
188:
189: > rsync -av host:'file\ name\ with\ spaces' /dest
190:
191: # CONNECTING TO AN RSYNC DAEMON
192:
193: It is also possible to use rsync without a remote shell as the transport. In
194: this case you will directly connect to a remote rsync daemon, typically using
195: TCP port 873. (This obviously requires the daemon to be running on the remote
196: system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS section
197: below for information on that.)
198:
199: Using rsync in this way is the same as using it with a remote shell except
200: that:
201:
202: - you either use a double colon :: instead of a single colon to separate the
203: hostname from the path, or you use an rsync:// URL.
204: - the first word of the "path" is actually a module name.
205: - the remote daemon may print a message of the day when you connect.
206: - if you specify no path name on the remote daemon then the list of accessible
207: paths on the daemon will be shown.
208: - if you specify no local destination then a listing of the specified files on
209: the remote daemon is provided.
210: - you must not specify the `--rsh` (`-e`) option (since that overrides the
211: daemon connection to use ssh -- see USING RSYNC-DAEMON FEATURES VIA A
212: REMOTE-SHELL CONNECTION below).
213:
214: An example that copies all the files in a remote module named "src":
215:
216: > rsync -av host::src /dest
217:
218: Some modules on the remote daemon may require authentication. If so, you will
219: receive a password prompt when you connect. You can avoid the password prompt
220: by setting the environment variable RSYNC_PASSWORD to the password you want to
221: use or using the `--password-file` option. This may be useful when scripting
222: rsync.
223:
224: WARNING: On some systems environment variables are visible to all users. On
225: those systems using `--password-file` is recommended.
226:
227: You may establish the connection via a web proxy by setting the environment
228: variable RSYNC_PROXY to a hostname:port pair pointing to your web proxy. Note
229: that your web proxy's configuration must support proxy connections to port 873.
230:
231: You may also establish a daemon connection using a program as a proxy by
232: setting the environment variable RSYNC_CONNECT_PROG to the commands you wish to
233: run in place of making a direct socket connection. The string may contain the
234: escape "%H" to represent the hostname specified in the rsync command (so use
235: "%%" if you need a single "%" in your string). For example:
236:
237: > export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
238: > rsync -av targethost1::module/src/ /dest/
239: > rsync -av rsync://targethost2/module/src/ /dest/
240:
241: The command specified above uses ssh to run nc (netcat) on a proxyhost, which
242: forwards all data to port 873 (the rsync daemon) on the targethost (%H).
243:
244: Note also that if the RSYNC_SHELL environment variable is set, that program
245: will be used to run the RSYNC_CONNECT_PROG command instead of using the default
246: shell of the **system()** call.
247:
248: # USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION
249:
250: It is sometimes useful to use various features of an rsync daemon (such as
251: named modules) without actually allowing any new socket connections into a
252: system (other than what is already required to allow remote-shell access).
253: Rsync supports connecting to a host using a remote shell and then spawning a
254: single-use "daemon" server that expects to read its config file in the home dir
255: of the remote user. This can be useful if you want to encrypt a daemon-style
256: transfer's data, but since the daemon is started up fresh by the remote user,
257: you may not be able to use features such as chroot or change the uid used by
258: the daemon. (For another way to encrypt a daemon transfer, consider using ssh
259: to tunnel a local port to a remote machine and configure a normal rsync daemon
260: on that remote host to only allow connections from "localhost".)
261:
262: From the user's perspective, a daemon transfer via a remote-shell connection
263: uses nearly the same command-line syntax as a normal rsync-daemon transfer,
264: with the only exception being that you must explicitly set the remote shell
265: program on the command-line with the `--rsh=COMMAND` option. (Setting the
266: RSYNC_RSH in the environment will not turn on this functionality.) For example:
267:
268: > rsync -av --rsh=ssh host::module /dest
269:
270: If you need to specify a different remote-shell user, keep in mind that the
271: user@ prefix in front of the host is specifying the rsync-user value (for a
272: module that requires user-based authentication). This means that you must give
273: the '-l user' option to ssh when specifying the remote-shell, as in this
274: example that uses the short version of the `--rsh` option:
275:
276: > rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest
277:
278: The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to
279: log-in to the "module".
280:
281: # STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS
282:
283: In order to connect to an rsync daemon, the remote system needs to have a
284: daemon already running (or it needs to have configured something like inetd to
285: spawn an rsync daemon for incoming connections on a particular port). For full
286: information on how to start a daemon that will handling incoming socket
287: connections, see the **rsyncd.conf**(5) man page -- that is the config file for
288: the daemon, and it contains the full details for how to run the daemon
289: (including stand-alone and inetd configurations).
290:
291: If you're using one of the remote-shell transports for the transfer, there is
292: no need to manually start an rsync daemon.
293:
294: # SORTED TRANSFER ORDER
295:
296: Rsync always sorts the specified filenames into its internal transfer list.
297: This handles the merging together of the contents of identically named
298: directories, makes it easy to remove duplicate filenames, and may confuse
299: someone when the files are transferred in a different order than what was given
300: on the command-line.
301:
302: If you need a particular file to be transferred prior to another, either
303: separate the files into different rsync calls, or consider using
304: `--delay-updates` (which doesn't affect the sorted transfer order, but does
305: make the final file-updating phase happen much more rapidly).
306:
307: # EXAMPLES
308:
309: Here are some examples of how I use rsync.
310:
311: To backup my wife's home directory, which consists of large MS Word files and
312: mail folders, I use a cron job that runs
313:
314: > rsync -Cavz . arvidsjaur:backup
315:
316: each night over a PPP connection to a duplicate directory on my machine
317: "arvidsjaur".
318:
319: To synchronize my samba source trees I use the following Makefile targets:
320:
321: > get:
322: > rsync -avuzb --exclude '*~' samba:samba/ .
323: > put:
324: > rsync -Cavuzb . samba:samba/
325: > sync: get put
326:
327: This allows me to sync with a CVS directory at the other end of the connection.
328: I then do CVS operations on the remote machine, which saves a lot of time as
329: the remote CVS protocol isn't very efficient.
330:
331: I mirror a directory between my "old" and "new" ftp sites with the command:
332:
333: > rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge"
334:
335: This is launched from cron every few hours.
336:
337: # OPTION SUMMARY
338:
339: Here is a short summary of the options available in rsync. Please refer to the
340: detailed description below for a complete description.
341:
342: [comment]: # (help-rsync.h)
343: [comment]: # (Keep these short enough that they'll be under 80 chars when indented by 7 chars.)
344:
345: ```
346: --verbose, -v increase verbosity
347: --info=FLAGS fine-grained informational verbosity
348: --debug=FLAGS fine-grained debug verbosity
349: --stderr=e|a|c change stderr output mode (default: errors)
350: --quiet, -q suppress non-error messages
351: --no-motd suppress daemon-mode MOTD
352: --checksum, -c skip based on checksum, not mod-time & size
353: --sumfiles=MODE use .rsyncsums to speedup --checksum mode
354: --archive, -a archive mode; equals -rlptgoD (no -H,-A,-X)
355: --no-OPTION turn off an implied OPTION (e.g. --no-D)
356: --recursive, -r recurse into directories
357: --relative, -R use relative path names
358: --no-implied-dirs don't send implied dirs with --relative
359: --backup, -b make backups (see --suffix & --backup-dir)
360: --backup-deleted make backups only of deleted files
361: --backup-dir=DIR make backups into hierarchy based in DIR
362: --backup-dir-dels=DIR backup removed files into hierarchy based in DIR
363: --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
364: --suffix-dels=SUFFIX set removed-files suffix (def. --suffix w/o b-d-d)
365: --update, -u skip files that are newer on the receiver
366: --downdate, -w skip files that are older on the receiver
367: --inplace update destination files in-place
368: --append append data onto shorter files
369: --append-verify --append w/old data in file checksum
370: --dirs, -d transfer directories without recursing
371: --mkpath create the destination's path component
372: --links, -l copy symlinks as symlinks
373: --copy-links, -L transform symlink into referent file/dir
374: --copy-unsafe-links only "unsafe" symlinks are transformed
375: --safe-links ignore symlinks that point outside the tree
376: --munge-links munge symlinks to make them safe & unusable
377: --copy-dirlinks, -k transform symlink to dir into referent dir
378: --keep-dirlinks, -K treat symlinked dir on receiver as dir
379: --hard-links, -H preserve hard links
380: --perms, -p preserve permissions
381: --fileflags preserve file-flags (aka chflags)
382: --executability, -E preserve executability
383: --chmod=CHMOD affect file and/or directory permissions
384: --acls, -A preserve ACLs (implies --perms)
385: --xattrs, -X preserve extended attributes
386: --hfs-compression preserve HFS compression if supported
387: --protect-decmpfs preserve HFS compression as xattrs
388: --owner, -o preserve owner (super-user only)
389: --group, -g preserve group
390: --devices preserve device files (super-user only)
391: --copy-devices copy device contents as regular file
392: --specials preserve special files
393: -D same as --devices --specials
394: --times, -t preserve modification times
395: --atimes, -U preserve access (use) times
396: --open-noatime avoid changing the atime on opened files
397: --crtimes, -N preserve create times (newness)
398: --omit-dir-times, -O omit directories from --times
399: --omit-link-times, -J omit symlinks from --times
400: --omit-dir-changes omit directories from any attribute changes
401: --super receiver attempts super-user activities
402: --fake-super store/recover privileged attrs using xattrs
403: --sparse, -S turn sequences of nulls into sparse blocks
404: --sparse-block=SIZE set block size used to handle sparse files
405: --preallocate allocate dest files before writing them
406: --write-devices write to devices as files (implies --inplace)
407: --dry-run, -n perform a trial run with no changes made
408: --whole-file, -W copy files whole (w/o delta-xfer algorithm)
409: --checksum-choice=STR choose the checksum algorithm (aka --cc)
410: --db=CONFIG_FILE specify a CONFIG_FILE for DB checksums
411: --db-only=CONFIG_FILE behave like rsyncdb
412: --db-lax ignore ctime changes (use with CAUTION)
413: --one-file-system, -x don't cross filesystem boundaries
414: --block-size=SIZE, -B force a fixed checksum block-size
415: --rsh=COMMAND, -e specify the remote shell to use
416: --rsync-path=PROGRAM specify the rsync to run on remote machine
417: --existing skip creating new files on receiver
418: --ignore-existing skip updating files that exist on receiver
419: --remove-source-files sender removes synchronized files (non-dir)
420: --source-backup ... and backs up those files
421: --del an alias for --delete-during
422: --delete delete extraneous files from dest dirs
423: --delete-before receiver deletes before xfer, not during
424: --delete-during receiver deletes during the transfer
425: --delete-delay find deletions during, delete after
426: --delete-after receiver deletes after transfer, not during
427: --delete-excluded also delete excluded files from dest dirs
428: --ignore-missing-args ignore missing source args without error
429: --delete-missing-args delete missing source args from destination
430: --ignore-errors delete even if there are I/O errors
431: --force-delete force deletion of directories even if not empty
432: --force-change affect user-/system-immutable files/dirs
433: --force-uchange affect user-immutable files/dirs
434: --force-schange affect system-immutable files/dirs
435: --max-delete=NUM don't delete more than NUM files
436: --max-size=SIZE don't transfer any file larger than SIZE
437: --min-size=SIZE don't transfer any file smaller than SIZE
438: --max-alloc=SIZE change a limit relating to memory alloc
439: --partial keep partially transferred files
440: --partial-dir=DIR put a partially transferred file into DIR
441: --delay-updates put all updated files into place at end
442: --direct-io don't use buffer cache for xfer file I/O
443: --prune-empty-dirs, -m prune empty directory chains from file-list
444: --fsync fsync every written file
445: --numeric-ids don't map uid/gid values by user/group name
446: --usermap=STRING custom username mapping
447: --groupmap=STRING custom groupname mapping
448: --chown=USER:GROUP simple username/groupname mapping
449: --timeout=SECONDS set I/O timeout in seconds
450: --contimeout=SECONDS set daemon connection timeout in seconds
451: --ignore-times, -I don't skip files that match size and time
452: --size-only skip files that match in size
453: --date-only skip files that match in mod-time
454: --modify-window=NUM, -@ set the accuracy for mod-time comparisons
455: --temp-dir=DIR, -T create temporary files in directory DIR
456: --fuzzy, -y find similar file for basis if no dest file
457: --detect-renamed try to find renamed files to speed the xfer
458: --compare-dest=DIR also compare destination files relative to DIR
459: --copy-dest=DIR ... and include copies of unchanged files
460: --link-dest=DIR hardlink to files in DIR when unchanged
461: --clone-dest=DIR clone (reflink) files from DIR when unchanged
462: --compress, -z compress file data during the transfer
463: --compress-choice=STR choose the compression algorithm (aka --zc)
464: --compress-level=NUM explicitly set compression level (aka --zl)
465: --skip-compress=LIST skip compressing files with suffix in LIST
466: --cvs-exclude, -C auto-ignore files in the same way CVS does
467: --filter=RULE, -f add a file-filtering RULE
468: -F same as --filter='dir-merge /.rsync-filter'
469: repeated: --filter='- .rsync-filter'
470: --exclude=PATTERN exclude files matching PATTERN
471: --exclude-from=FILE read exclude patterns from FILE
472: --include=PATTERN don't exclude files matching PATTERN
473: --include-from=FILE read include patterns from FILE
474: --files-from=FILE read list of source-file names from FILE
475: --from0, -0 all *-from/filter files are delimited by 0s
476: --protect-args, -s no space-splitting; wildcard chars only
477: --copy-as=USER[:GROUP] specify user & optional group for the copy
478: --ignore-case ignore case when comparing filenames
479: --address=ADDRESS bind address for outgoing socket to daemon
480: --port=PORT specify double-colon alternate port number
481: --sockopts=OPTIONS specify custom TCP options
482: --diffserv=[0-63] specify diffserv setting
483: --congestion-alg=STRING choose a congestion algo
484: --blocking-io use blocking I/O for the remote shell
485: --outbuf=N|L|B set out buffering to None, Line, or Block
486: --stats give some file-transfer stats
487: --8-bit-output, -8 leave high-bit chars unescaped in output
488: --human-readable, -h output numbers in a human-readable format
489: --progress show progress during transfer
490: -P same as --partial --progress
491: --itemize-changes, -i output a change-summary for all updates
492: --remote-option=OPT, -M send OPTION to the remote side only
493: --out-format=FORMAT output updates using the specified FORMAT
494: --log-file=FILE log what we're doing to the specified FILE
495: --log-file-format=FMT log updates using the specified FMT
496: --password-file=FILE read daemon-access password from FILE
497: --early-input=FILE use FILE for daemon's early exec input
498: --list-only list the files instead of copying them
499: --bwlimit=RATE limit socket I/O bandwidth
500: --slow-down=USECs sleep N usec while creating the filelist
501: --stop-after=MINS Stop rsync after MINS minutes have elapsed
502: --stop-at=y-m-dTh:m Stop rsync at the specified point in time
503: --write-batch=FILE write a batched update to FILE
504: --only-write-batch=FILE like --write-batch but w/o updating dest
505: --read-batch=FILE read a batched update from FILE
506: --source-filter=COMMAND filter file through COMMAND at source
507: --dest-filter=COMMAND filter file through COMMAND at destination
508: --protocol=NUM force an older protocol version to be used
509: --iconv=CONVERT_SPEC request charset conversion of filenames
510: --tr=BAD/GOOD transliterate filenames
511: --checksum-seed=NUM set block/file checksum seed (advanced)
512: --ipv4, -4 prefer IPv4
513: --ipv6, -6 prefer IPv6
514: --version, -V print the version + other info and exit
515: --help, -h (*) show this help (* -h is help only on its own)
516: ```
517:
518: Rsync can also be run as a daemon, in which case the following options are
519: accepted:
520:
521: [comment]: # (help-rsyncd.h)
522:
523: ```
524: --daemon run as an rsync daemon
525: --address=ADDRESS bind to the specified address
526: --bwlimit=RATE limit socket I/O bandwidth
527: --config=FILE specify alternate rsyncd.conf file
528: --dparam=OVERRIDE, -M override global daemon config parameter
529: --no-detach do not detach from the parent
530: --port=PORT listen on alternate port number
531: --log-file=FILE override the "log file" setting
532: --log-file-format=FMT override the "log format" setting
533: --sockopts=OPTIONS specify custom TCP options
534: --verbose, -v increase verbosity
535: --ipv4, -4 prefer IPv4
536: --ipv6, -6 prefer IPv6
537: --help, -h show this help (when used with --daemon)
538: ```
539:
540: # OPTIONS
541:
542: Rsync accepts both long (double-dash + word) and short (single-dash + letter)
543: options. The full list of the available options are described below. If an
544: option can be specified in more than one way, the choices are comma-separated.
545: Some options only have a long variant, not a short. If the option takes a
546: parameter, the parameter is only listed after the long variant, even though it
547: must also be specified for the short. When specifying a parameter, you can
548: either use the form `--option=param` or replace the '=' with whitespace. The
549: parameter may need to be quoted in some manner for it to survive the shell's
550: command-line parsing. Keep in mind that a leading tilde (`~`) in a filename is
551: substituted by your shell, so `--option=~/foo` will not change the tilde into
552: your home directory (remove the '=' for that).
553:
554: [comment]: # (An OL starting at 0 is converted into a DL by the parser.)
555:
556: 0. `--help`, `-h` `(*)`
557:
558: Print a short help page describing the options available in rsync and exit.
559: (*) The `-h` short option will only invoke `--help` when used without other
560: options since it normally means `--human-readable`.
561:
562: 0. `--version`, `-V`
563:
564: Print the rsync version plus other info and exit.
565:
566: The output includes the default list of checksum algorithms, the default
567: list of compression algorithms, a list of compiled-in capabilities, a link
568: to the rsync web site, and some license/copyright info.
569:
570: 0. `--verbose`, `-v`
571:
572: This option increases the amount of information you are given during the
573: transfer. By default, rsync works silently. A single `-v` will give you
574: information about what files are being transferred and a brief summary at
575: the end. Two `-v` options will give you information on what files are
576: being skipped and slightly more information at the end. More than two `-v`
577: options should only be used if you are debugging rsync.
578:
579: In a modern rsync, the `-v` option is equivalent to the setting of groups
580: of `--info` and `--debug` options. You can choose to use these newer
581: options in addition to, or in place of using `--verbose`, as any
582: fine-grained settings override the implied settings of `-v`. Both `--info`
583: and `--debug` have a way to ask for help that tells you exactly what flags
584: are set for each increase in verbosity.
585:
586: However, do keep in mind that a daemon's "`max verbosity`" setting will limit
587: how high of a level the various individual flags can be set on the daemon
588: side. For instance, if the max is 2, then any info and/or debug flag that
589: is set to a higher value than what would be set by `-vv` will be downgraded
590: to the `-vv` level in the daemon's logging.
591:
592: 0. `--info=FLAGS`
593:
594: This option lets you have fine-grained control over the information output
595: you want to see. An individual flag name may be followed by a level
596: number, with 0 meaning to silence that output, 1 being the default output
597: level, and higher numbers increasing the output of that flag (for those
598: that support higher levels). Use `--info=help` to see all the available
599: flag names, what they output, and what flag names are added for each
600: increase in the verbose level. Some examples:
601:
602: > rsync -a --info=progress2 src/ dest/
603: > rsync -avv --info=stats2,misc1,flist0 src/ dest/
604:
605: Note that `--info=name`'s output is affected by the `--out-format` and
606: `--itemize-changes` (`-i`) options. See those options for more information
607: on what is output and when.
608:
609: This option was added to 3.1.0, so an older rsync on the server side might
610: reject your attempts at fine-grained control (if one or more flags needed
611: to be send to the server and the server was too old to understand them).
612: See also the "`max verbosity`" caveat above when dealing with a daemon.
613:
614: 0. `--debug=FLAGS`
615:
616: This option lets you have fine-grained control over the debug output you
617: want to see. An individual flag name may be followed by a level number,
618: with 0 meaning to silence that output, 1 being the default output level,
619: and higher numbers increasing the output of that flag (for those that
620: support higher levels). Use `--debug=help` to see all the available flag
621: names, what they output, and what flag names are added for each increase in
622: the verbose level. Some examples:
623:
624: > rsync -avvv --debug=none src/ dest/
625: > rsync -avA --del --debug=del2,acl src/ dest/
626:
627: Note that some debug messages will only be output when `--stderr=all` is
628: specified, especially those pertaining to I/O and buffer debugging.
629:
630: Beginning in 3.2.0, this option is no longer auto-forwarded to the server
631: side in order to allow you to specify different debug values for each side
632: of the transfer, as well as to specify a new debug option that is only
633: present in one of the rsync versions. If you want to duplicate the same
634: option on both sides, using brace expansion is an easy way to save you some
635: typing. This works in zsh and bash:
636:
637: > rsync -aiv {-M,}--debug=del2 src/ dest/
638:
639: 0. `--stderr=errors|all|client`
640:
641: This option controls which processes output to stderr and if info messages
642: are also changed to stderr. The mode strings can be abbreviated, so feel
643: free to use a single letter value. The 3 possible choices are:
644:
645: - `errors` - (the default) causes all the rsync processes to send an
646: error directly to stderr, even if the process is on the remote side of
647: the transfer. Info messages are sent to the client side via the protocol
648: stream. If stderr is not available (i.e. when directly connecting with a
649: daemon via a socket) errors fall back to being sent via the protocol
650: stream.
651:
652: - `all` - causes all rsync messages (info and error) to get written
653: directly to stderr from all (possible) processes. This causes stderr to
654: become line-buffered (instead of raw) and eliminates the ability to
655: divide up the info and error messages by file handle. For those doing
656: debugging or using several levels of verbosity, this option can help to
657: avoid clogging up the transfer stream (which should prevent any chance of
658: a deadlock bug hanging things up). It also enables the outputting of some
659: I/O related debug messages.
660:
661: - `client` - causes all rsync messages to be sent to the client side
662: via the protocol stream. One client process outputs all messages, with
663: errors on stderr and info messages on stdout. This **was** the default
664: in older rsync versions, but can cause error delays when a lot of
665: transfer data is ahead of the messages. If you're pushing files to an
666: older rsync, you may want to use `--stderr=all` since that idiom has
667: been around for several releases.
668:
669: This option was added in rsync 3.2.3. This version also began the
670: forwarding of a non-default setting to the remote side, though rsync uses
671: the backward-compatible options `--msgs2stderr` and `--no-msgs2stderr` to
672: represent the `all` and `client` settings, respectively. A newer rsync
673: will continue to accept these older option names to maintain compatibility.
674:
675: 0. `--quiet`, `-q`
676:
677: This option decreases the amount of information you are given during the
678: transfer, notably suppressing information messages from the remote server.
679: This option is useful when invoking rsync from cron.
680:
681: 0. `--no-motd`
682:
683: This option affects the information that is output by the client at the
684: start of a daemon transfer. This suppresses the message-of-the-day (MOTD)
685: text, but it also affects the list of modules that the daemon sends in
686: response to the "rsync host::" request (due to a limitation in the rsync
687: protocol), so omit this option if you want to request the list of modules
688: from the daemon.
689:
690: 0. `--ignore-times`, `-I`
691:
692: Normally rsync will skip any files that are already the same size and have
693: the same modification timestamp. This option turns off this "quick check"
694: behavior, causing all files to be updated.
695:
696: 0. `--size-only`
697:
698: This modifies rsync's "quick check" algorithm for finding files that need
699: to be transferred, changing it from the default of transferring files with
700: either a changed size or a changed last-modified time to just looking for
701: files that have changed in size. This is useful when starting to use rsync
702: after using another mirroring system which may not preserve timestamps
703: exactly.
704:
705: 0. `--date-only`
706:
707: Normally rsync will skip any files that are already the same size and have
708: the same modification time-stamp. With the --date-only option, files will
709: be skipped if they have the same timestamp, regardless of size. This may be
710: useful when the remote files have passed through a size-changing filter,
711: e.g. for encryption.
712:
713: 0. `--modify-window=NUM`, `-@`
714:
715: When comparing two timestamps, rsync treats the timestamps as being equal
716: if they differ by no more than the modify-window value. The default is 0,
717: which matches just integer seconds. If you specify a negative value (and
718: the receiver is at least version 3.1.3) then nanoseconds will also be taken
719: into account. Specifying 1 is useful for copies to/from MS Windows FAT
720: filesystems, because FAT represents times with a 2-second resolution
721: (allowing times to differ from the original by up to 1 second).
722:
723: If you want all your transfers to default to comparing nanoseconds, you can
724: create a `~/.popt` file and put these lines in it:
725:
726: > rsync alias -a -a@-1
727: > rsync alias -t -t@-1
728:
729: With that as the default, you'd need to specify `--modify-window=0` (aka
730: `-@0`) to override it and ignore nanoseconds, e.g. if you're copying
731: between ext3 and ext4, or if the receiving rsync is older than 3.1.3.
732:
733: 0. `--checksum`, `-c`
734:
735: This changes the way rsync checks if the files have been changed and are in
736: need of a transfer. Without this option, rsync uses a "quick check" that
737: (by default) checks if each file's size and time of last modification match
738: between the sender and receiver. This option changes this to compare a
739: 128-bit checksum for each file that has a matching size. Generating the
740: checksums means that both sides will expend a lot of disk I/O reading all
741: the data in the files in the transfer, so this can slow things down
742: significantly (and this is prior to any reading that will be done to
743: transfer changed files)
744:
745: The sending side generates its checksums while it is doing the file-system
746: scan that builds the list of the available files. The receiver generates
747: its checksums when it is scanning for changed files, and will checksum any
748: file that has the same size as the corresponding sender's file: files with
749: either a changed size or a changed checksum are selected for transfer.
750:
751: See also the `--sumfiles` option for a way to use cached checksum data.
752:
753: Note that rsync always verifies that each _transferred_ file was correctly
754: reconstructed on the receiving side by checking a whole-file checksum that
755: is generated as the file is transferred, but that automatic
756: after-the-transfer verification has nothing to do with this option's
757: before-the-transfer "Does this file need to be updated?" check.
758:
759: The checksum used is auto-negotiated between the client and the server, but
760: can be overridden using either the `--checksum-choice` (`--cc`) option or an
761: environment variable that is discussed in that option's section.
762:
763: 0. `--sumfiles=MODE`
764:
765: This option tells rsync to make use of any cached checksum information it
766: finds in per-directory .rsyncsums files when the current transfer is using
767: the `--checksum` option. If the checksum data is up-to-date, it is used
768: instead of recomputing it, saving both disk I/O and CPU time. If the
769: checksum data is missing or outdated, the checksum is computed just as it
770: would be if `--sumfiles` was not specified.
771:
772: The MODE value is either "lax", for relaxed checking (which compares size
773: and mtime), "strict" (which also compares ctime and inode), or "none" to
774: ignore any .rsyncsums files ("none" is the default).
775: If you want rsync to create and/or update these files, specify a prefixed
776: plus ("+lax" or "+strict"). Adding a second prefixed '+' causes the
777: checksum-file updates to happen even when the transfer is in `--dry-run`
778: mode ("++lax" or "++strict"). There is also a perl script in the support
779: directory named "rsyncsums" that can be used to update the .rsyncsums
780: files.
781:
782: This option has no effect unless `--checksum`, `-c` was also specified. It
783: also only affects the current side of the transfer, so if you want the
784: remote side to parse its own .rsyncsums files, specify the option via
785: `--remote-option` (`-M`) (e.g. "`-M--sumfiles=lax`").
786:
787: To avoid transferring the system's checksum files, you can use an exclude
788: (e.g. `--exclude=.rsyncsums`). To make this easier to type, you can use a
789: popt alias. For instance, adding the following line in your ~/.popt file
790: defines a `--cs` option that enables lax checksum files and excludes the
791: checksum files:
792:
793: > rsync alias --cs -c --sumfiles=lax -M--sumfiles=lax -f-_.rsyncsums
794:
795: An rsync daemon does not allow the client to control this setting, so see
796: the "checksum files" daemon parameter for information on how to make a
797: daemon use cached checksum data.
798:
799: 0. `--archive`, `-a`
800:
801: This is equivalent to `-rlptgoD`. It is a quick way of saying you want
802: recursion and want to preserve almost everything (with `-H` being a notable
803: omission). The only exception to the above equivalence is when
804: `--files-from` is specified, in which case `-r` is not implied.
805:
806: Note that `-a` **does not preserve hardlinks**, because finding
807: multiply-linked files is expensive. You must separately specify `-H`.
808: Note also that for backward compatibility, `-a` currently does **not**
809: imply the `--fileflags` option.
810:
811: 0. `--no-OPTION`
812:
813: You may turn off one or more implied options by prefixing the option name
814: with "no-". Not all options may be prefixed with a "no-": only options that
815: are implied by other options (e.g. `--no-D`, `--no-perms`) or have
816: different defaults in various circumstances (e.g. `--no-whole-file`,
817: `--no-blocking-io`, `--no-dirs`). You may specify either the short or the
818: long option name after the "no-" prefix (e.g. `--no-R` is the same as
819: `--no-relative`).
820:
821: For example: if you want to use `-a` (`--archive`) but don't want `-o`
822: (`--owner`), instead of converting `-a` into `-rlptgD`, you could specify
823: `-a --no-o` (or `-a --no-owner`).
824:
825: The order of the options is important: if you specify `--no-r -a`, the
826: `-r` option would end up being turned on, the opposite of `-a --no-r`.
827: Note also that the side-effects of the `--files-from` option are NOT
828: positional, as it affects the default state of several options and slightly
829: changes the meaning of `-a` (see the `--files-from` option for more
830: details).
831:
832: 0. `--recursive`, `-r`
833:
834: This tells rsync to copy directories recursively. See also `--dirs` (`-d`).
835:
836: Beginning with rsync 3.0.0, the recursive algorithm used is now an
837: incremental scan that uses much less memory than before and begins the
838: transfer after the scanning of the first few directories have been
839: completed. This incremental scan only affects our recursion algorithm, and
840: does not change a non-recursive transfer. It is also only possible when
841: both ends of the transfer are at least version 3.0.0.
842:
843: Some options require rsync to know the full file list, so these options
844: disable the incremental recursion mode. These include: `--delete-before`,
845: `--delete-after`, `--prune-empty-dirs`, and `--delay-updates`. Because of
846: this, the default delete mode when you specify `--delete` is now
847: `--delete-during` when both ends of the connection are at least 3.0.0 (use
848: `--del` or `--delete-during` to request this improved deletion mode
849: explicitly). See also the `--delete-delay` option that is a better choice
850: than using `--delete-after`.
851:
852: Incremental recursion can be disabled using the `--no-inc-recursive` option
853: or its shorter `--no-i-r` alias.
854:
855: 0. `--relative`, `-R`
856:
857: Use relative paths. This means that the full path names specified on the
858: command line are sent to the server rather than just the last parts of the
859: filenames. This is particularly useful when you want to send several
860: different directories at the same time. For example, if you used this
861: command:
862:
863: > rsync -av /foo/bar/baz.c remote:/tmp/
864:
865: would create a file named baz.c in /tmp/ on the remote machine. If instead
866: you used
867:
868: > rsync -avR /foo/bar/baz.c remote:/tmp/
869:
870: then a file named /tmp/foo/bar/baz.c would be created on the remote
871: machine, preserving its full path. These extra path elements are called
872: "implied directories" (i.e. the "foo" and the "foo/bar" directories in the
873: above example).
874:
875: Beginning with rsync 3.0.0, rsync always sends these implied directories as
876: real directories in the file list, even if a path element is really a
877: symlink on the sending side. This prevents some really unexpected behaviors
878: when copying the full path of a file that you didn't realize had a symlink
879: in its path. If you want to duplicate a server-side symlink, include both
880: the symlink via its path, and referent directory via its real path. If
881: you're dealing with an older rsync on the sending side, you may need to use
882: the `--no-implied-dirs` option.
883:
884: It is also possible to limit the amount of path information that is sent as
885: implied directories for each path you specify. With a modern rsync on the
886: sending side (beginning with 2.6.7), you can insert a dot and a slash into
887: the source path, like this:
888:
889: > rsync -avR /foo/./bar/baz.c remote:/tmp/
890:
891: That would create /tmp/bar/baz.c on the remote machine. (Note that the dot
892: must be followed by a slash, so "/foo/." would not be abbreviated.) For
893: older rsync versions, you would need to use a chdir to limit the source
894: path. For example, when pushing files:
895:
896: > (cd /foo; rsync -avR bar/baz.c remote:/tmp/)
897:
898: (Note that the parens put the two commands into a sub-shell, so that the
899: "cd" command doesn't remain in effect for future commands.) If you're
900: pulling files from an older rsync, use this idiom (but only for a
901: non-daemon transfer):
902:
903: > rsync -avR --rsync-path="cd /foo; rsync" \
904: > remote:bar/baz.c /tmp/
905:
906: 0. `--no-implied-dirs`
907:
908: This option affects the default behavior of the `--relative` option. When
909: it is specified, the attributes of the implied directories from the source
910: names are not included in the transfer. This means that the corresponding
911: path elements on the destination system are left unchanged if they exist,
912: and any missing implied directories are created with default attributes.
913: This even allows these implied path elements to have big differences, such
914: as being a symlink to a directory on the receiving side.
915:
916: For instance, if a command-line arg or a files-from entry told rsync to
917: transfer the file "path/foo/file", the directories "path" and "path/foo"
918: are implied when `--relative` is used. If "path/foo" is a symlink to "bar"
919: on the destination system, the receiving rsync would ordinarily delete
920: "path/foo", recreate it as a directory, and receive the file into the new
921: directory. With `--no-implied-dirs`, the receiving rsync updates
922: "path/foo/file" using the existing path elements, which means that the file
923: ends up being created in "path/bar". Another way to accomplish this link
924: preservation is to use the `--keep-dirlinks` option (which will also affect
925: symlinks to directories in the rest of the transfer).
926:
927: When pulling files from an rsync older than 3.0.0, you may need to use this
928: option if the sending side has a symlink in the path you request and you
929: wish the implied directories to be transferred as normal directories.
930:
931: 0. `--backup`, `-b`
932:
933: With this option, preexisting destination files are renamed as each file is
934: transferred or deleted. You can control where the backup file goes and
935: what (if any) suffix gets appended using the `--backup-dir` and `--suffix`
936: options.
937:
938: Note that if you don't specify `--backup-dir`, (1) the `--omit-dir-times`
939: option will be forced on, and (2) if `--delete` is also in effect (without
940: `--delete-excluded`), rsync will add a "protect" filter-rule for the backup
941: suffix to the end of all your existing excludes (e.g. `-f "P *~"`). This
942: will prevent previously backed-up files from being deleted. Note that if
943: you are supplying your own filter rules, you may need to manually insert
944: your own exclude/protect rule somewhere higher up in the list so that it
945: has a high enough priority to be effective (e.g., if your rules specify a
946: trailing inclusion/exclusion of `*`, the auto-added rule would never be
947: reached).
948:
949: 0. --backup-deleted
950:
951: With this option, deleted destination files are renamed, while modified
952: destination files are not. Otherwise, this option behaves the same as
953: `--backup`, described above. Note that if `--backup` is also specified,
954: whichever option is specified last takes precedence.
955:
956: 0. `--backup-dir=DIR`
957:
958: This implies the `--backup` option, and tells rsync to store all
959: backups in the specified directory on the receiving side. This can be used
960: for incremental backups. You can additionally specify a backup suffix
961: using the `--suffix` option (otherwise the files backed up in the specified
962: directory will keep their original filenames).
963:
964: Note that if you specify a relative path, the backup directory will be
965: relative to the destination directory, so you probably want to specify
966: either an absolute path or a path that starts with "../". If an rsync
967: daemon is the receiver, the backup dir cannot go outside the module's path
968: hierarchy, so take extra care not to delete it or copy into it.
969:
970: 0. `--suffix=SUFFIX`
971:
972: This option allows you to override the default backup suffix used with the
973: `--backup` (`-b`) option. The default suffix is a `~` if no `--backup-dir`
974: was specified, otherwise it is an empty string.
975:
976: 0. `--update`, `-u`
977:
978: This forces rsync to skip any files which exist on the destination and have
979: a modified time that is newer than the source file. (If an existing
980: destination file has a modification time equal to the source file's, it
981: will be updated if the sizes are different.)
982:
983: Note that this does not affect the copying of dirs, symlinks, or other
984: special files. Also, a difference of file format between the sender and
985: receiver is always considered to be important enough for an update, no
986: matter what date is on the objects. In other words, if the source has a
987: directory where the destination has a file, the transfer would occur
988: regardless of the timestamps.
989:
990: This option is a transfer rule, not an exclude, so it doesn't affect the
991: data that goes into the file-lists, and thus it doesn't affect deletions.
992: It just limits the files that the receiver requests to be transferred.
993:
994: 0. `--inplace`
995:
996: This option changes how rsync transfers a file when its data needs to be
997: updated: instead of the default method of creating a new copy of the file
998: and moving it into place when it is complete, rsync instead writes the
999: updated data directly to the destination file.
1000:
1001: This has several effects:
1002:
1003: - Hard links are not broken. This means the new data will be visible
1004: through other hard links to the destination file. Moreover, attempts to
1005: copy differing source files onto a multiply-linked destination file will
1006: result in a "tug of war" with the destination data changing back and
1007: forth.
1008: - In-use binaries cannot be updated (either the OS will prevent this from
1009: happening, or binaries that attempt to swap-in their data will misbehave
1010: or crash).
1011: - The file's data will be in an inconsistent state during the transfer and
1012: will be left that way if the transfer is interrupted or if an update
1013: fails.
1014: - A file that rsync cannot write to cannot be updated. While a super user
1015: can update any file, a normal user needs to be granted write permission
1016: for the open of the file for writing to be successful.
1017: - The efficiency of rsync's delta-transfer algorithm may be reduced if some
1018: data in the destination file is overwritten before it can be copied to a
1019: position later in the file. This does not apply if you use `--backup`,
1020: since rsync is smart enough to use the backup file as the basis file for
1021: the transfer.
1022:
1023: WARNING: you should not use this option to update files that are being
1024: accessed by others, so be careful when choosing to use this for a copy.
1025:
1026: This option is useful for transferring large files with block-based changes
1027: or appended data, and also on systems that are disk bound, not network
1028: bound. It can also help keep a copy-on-write filesystem snapshot from
1029: diverging the entire contents of a file that only has minor changes.
1030:
1031: The option implies `--partial` (since an interrupted transfer does not
1032: delete the file), but conflicts with `--partial-dir` and `--delay-updates`.
1033: Prior to rsync 2.6.4 `--inplace` was also incompatible with
1034: `--compare-dest` and `--link-dest`.
1035:
1036: 0. `--append`
1037:
1038: This special copy mode only works to efficiently update files that are
1039: known to be growing larger where any existing content on the receiving side
1040: is also known to be the same as the content on the sender. The use of
1041: `--append` **can be dangerous** if you aren't 100% sure that all the files
1042: in the transfer are shared, growing files. You should thus use filter
1043: rules to ensure that you weed out any files that do not fit this criteria.
1044:
1045: Rsync updates these growing file in-place without verifying any of the
1046: existing content in the file (it only verifies the content that it is
1047: appending). Rsync skips any files that exist on the receiving side that
1048: are not shorter than the associated file on the sending side (which means
1049: that new files are trasnferred).
1050:
1051: This does not interfere with the updating of a file's non-content
1052: attributes (e.g. permissions, ownership, etc.) when the file does not need
1053: to be transferred, nor does it affect the updating of any directories or
1054: non-regular files.
1055:
1056: 0. `--append-verify`
1057:
1058: This special copy mode works like `--append` except that all the data in
1059: the file is included in the checksum verification (making it much less
1060: efficient but also potentially safer). This option **can be dangerous** if
1061: you aren't 100% sure that all the files in the transfer are shared, growing
1062: files. See the `--append` option for more details.
1063:
1064: Note: prior to rsync 3.0.0, the `--append` option worked like
1065: `--append-verify`, so if you are interacting with an older rsync (or the
1066: transfer is using a protocol prior to 30), specifying either append option
1067: will initiate an `--append-verify` transfer.
1068:
1069: 0. `--dirs`, `-d`
1070:
1071: Tell the sending side to include any directories that are encountered.
1072: Unlike `--recursive`, a directory's contents are not copied unless the
1073: directory name specified is "." or ends with a trailing slash (e.g. ".",
1074: "dir/.", "dir/", etc.). Without this option or the `--recursive` option,
1075: rsync will skip all directories it encounters (and output a message to that
1076: effect for each one). If you specify both `--dirs` and `--recursive`,
1077: `--recursive` takes precedence.
1078:
1079: The `--dirs` option is implied by the `--files-from` option or the
1080: `--list-only` option (including an implied `--list-only` usage) if
1081: `--recursive` wasn't specified (so that directories are seen in the
1082: listing). Specify `--no-dirs` (or `--no-d`) if you want to turn this off.
1083:
1084: There is also a backward-compatibility helper option, `--old-dirs` (or
1085: `--old-d`) that tells rsync to use a hack of `-r --exclude='/*/*'` to get
1086: an older rsync to list a single directory without recursing.
1087:
1088: 0. `--mkpath`
1089:
1090: Create a missing path component of the destination arg. This allows rsync
1091: to create multiple levels of missing destination dirs and to create a path
1092: in which to put a single renamed file. Keep in mind that you'll need to
1093: supply a trailing slash if you want the entire destination path to be
1094: treated as a directory when copying a single arg (making rsync behave the
1095: same way that it would if the path component of the destination had already
1096: existed).
1097:
1098: For example, the following creates a copy of file foo as bar in the sub/dir
1099: directory, creating dirs "sub" and "sub/dir" if either do not yet exist:
1100:
1101: > rsync -ai --mkpath foo sub/dir/bar
1102:
1103: If you instead ran the following, it would have created file foo in the
1104: sub/dir/bar directory:
1105:
1106: > rsync -ai --mkpath foo sub/dir/bar/
1107:
1108: 0. `--links`, `-l`
1109:
1110: When symlinks are encountered, recreate the symlink on the destination.
1111:
1112: 0. `--copy-links`, `-L`
1113:
1114: When symlinks are encountered, the item that they point to (the referent)
1115: is copied, rather than the symlink. In older versions of rsync, this
1116: option also had the side-effect of telling the receiving side to follow
1117: symlinks, such as symlinks to directories. In a modern rsync such as this
1118: one, you'll need to specify `--keep-dirlinks` (`-K`) to get this extra
1119: behavior. The only exception is when sending files to an rsync that is too
1120: old to understand `-K` -- in that case, the `-L` option will still have the
1121: side-effect of `-K` on that older receiving rsync.
1122:
1123: 0. `--copy-unsafe-links`
1124:
1125: This tells rsync to copy the referent of symbolic links that point outside
1126: the copied tree. Absolute symlinks are also treated like ordinary files,
1127: and so are any symlinks in the source path itself when `--relative` is
1128: used. This option has no additional effect if `--copy-links` was also
1129: specified.
1130:
1131: Note that the cut-off point is the top of the transfer, which is the part
1132: of the path that rsync isn't mentioning in the verbose output. If you copy
1133: "/src/subdir" to "/dest/" then the "subdir" directory is a name inside the
1134: transfer tree, not the top of the transfer (which is /src) so it is legal
1135: for created relative symlinks to refer to other names inside the /src and
1136: /dest directories. If you instead copy "/src/subdir/" (with a trailing
1137: slash) to "/dest/subdir" that would not allow symlinks to any files outside
1138: of "subdir".
1139:
1140: 0. `--safe-links`
1141:
1142: This tells rsync to ignore any symbolic links which point outside the
1143: copied tree. All absolute symlinks are also ignored. Using this option in
1144: conjunction with `--relative` may give unexpected results.
1145:
1146: 0. `--munge-links`
1147:
1148: This option tells rsync to (1) modify all symlinks on the receiving side in
1149: a way that makes them unusable but recoverable (see below), or (2) to
1150: unmunge symlinks on the sending side that had been stored in a munged
1151: state. This is useful if you don't quite trust the source of the data to
1152: not try to slip in a symlink to a unexpected place.
1153:
1154: The way rsync disables the use of symlinks is to prefix each one with the
1155: string "/rsyncd-munged/". This prevents the links from being used as long
1156: as that directory does not exist. When this option is enabled, rsync will
1157: refuse to run if that path is a directory or a symlink to a directory.
1158:
1159: The option only affects the client side of the transfer, so if you need it
1160: to affect the server, specify it via `--remote-option`. (Note that in a
1161: local transfer, the client side is the sender.)
1162:
1163: This option has no affect on a daemon, since the daemon configures whether
1164: it wants munged symlinks via its "`munge symlinks`" parameter. See also the
1165: "munge-symlinks" perl script in the support directory of the source code.
1166:
1167: 0. `--copy-dirlinks`, `-k`
1168:
1169: This option causes the sending side to treat a symlink to a directory as
1170: though it were a real directory. This is useful if you don't want symlinks
1171: to non-directories to be affected, as they would be using `--copy-links`.
1172:
1173: Without this option, if the sending side has replaced a directory with a
1174: symlink to a directory, the receiving side will delete anything that is in
1175: the way of the new symlink, including a directory hierarchy (as long as
1176: `--force-delete` or `--delete` is in effect).
1177:
1178: See also `--keep-dirlinks` for an analogous option for the receiving side.
1179:
1180: `--copy-dirlinks` applies to all symlinks to directories in the source. If
1181: you want to follow only a few specified symlinks, a trick you can use is to
1182: pass them as additional source args with a trailing slash, using
1183: `--relative` to make the paths match up right. For example:
1184:
1185: > rsync -r --relative src/./ src/./follow-me/ dest/
1186:
1187: This works because rsync calls **lstat**(2) on the source arg as given, and
1188: the trailing slash makes **lstat**(2) follow the symlink, giving rise to a
1189: directory in the file-list which overrides the symlink found during the
1190: scan of "src/./".
1191:
1192: 0. `--keep-dirlinks`, `-K`
1193:
1194: This option causes the receiving side to treat a symlink to a directory as
1195: though it were a real directory, but only if it matches a real directory
1196: from the sender. Without this option, the receiver's symlink would be
1197: deleted and replaced with a real directory.
1198:
1199: For example, suppose you transfer a directory "foo" that contains a file
1200: "file", but "foo" is a symlink to directory "bar" on the receiver. Without
1201: `--keep-dirlinks`, the receiver deletes symlink "foo", recreates it as a
1202: directory, and receives the file into the new directory. With
1203: `--keep-dirlinks`, the receiver keeps the symlink and "file" ends up in
1204: "bar".
1205:
1206: One note of caution: if you use `--keep-dirlinks`, you must trust all the
1207: symlinks in the copy! If it is possible for an untrusted user to create
1208: their own symlink to any directory, the user could then (on a subsequent
1209: copy) replace the symlink with a real directory and affect the content of
1210: whatever directory the symlink references. For backup copies, you are
1211: better off using something like a bind mount instead of a symlink to modify
1212: your receiving hierarchy.
1213:
1214: See also `--copy-dirlinks` for an analogous option for the sending side.
1215:
1216: 0. `--hard-links`, `-H`
1217:
1218: This tells rsync to look for hard-linked files in the source and link
1219: together the corresponding files on the destination. Without this option,
1220: hard-linked files in the source are treated as though they were separate
1221: files.
1222:
1223: This option does NOT necessarily ensure that the pattern of hard links on
1224: the destination exactly matches that on the source. Cases in which the
1225: destination may end up with extra hard links include the following:
1226:
1227: - If the destination contains extraneous hard-links (more linking than what
1228: is present in the source file list), the copying algorithm will not break
1229: them explicitly. However, if one or more of the paths have content
1230: differences, the normal file-update process will break those extra links
1231: (unless you are using the `--inplace` option).
1232: - If you specify a `--link-dest` directory that contains hard links, the
1233: linking of the destination files against the `--link-dest` files can
1234: cause some paths in the destination to become linked together due to the
1235: `--link-dest` associations.
1236:
1237: Note that rsync can only detect hard links between files that are inside
1238: the transfer set. If rsync updates a file that has extra hard-link
1239: connections to files outside the transfer, that linkage will be broken. If
1240: you are tempted to use the `--inplace` option to avoid this breakage, be
1241: very careful that you know how your files are being updated so that you are
1242: certain that no unintended changes happen due to lingering hard links (and
1243: see the `--inplace` option for more caveats).
1244:
1245: If incremental recursion is active (see `--recursive`), rsync may transfer
1246: a missing hard-linked file before it finds that another link for that
1247: contents exists elsewhere in the hierarchy. This does not affect the
1248: accuracy of the transfer (i.e. which files are hard-linked together), just
1249: its efficiency (i.e. copying the data for a new, early copy of a
1250: hard-linked file that could have been found later in the transfer in
1251: another member of the hard-linked set of files). One way to avoid this
1252: inefficiency is to disable incremental recursion using the
1253: `--no-inc-recursive` option.
1254:
1255: 0. `--perms`, `-p`
1256:
1257: This option causes the receiving rsync to set the destination permissions
1258: to be the same as the source permissions. (See also the `--chmod` option
1259: for a way to modify what rsync considers to be the source permissions.)
1260:
1261: When this option is _off_, permissions are set as follows:
1262:
1263: - Existing files (including updated files) retain their existing
1264: permissions, though the `--executability` option might change just the
1265: execute permission for the file.
1266: - New files get their "normal" permission bits set to the source file's
1267: permissions masked with the receiving directory's default permissions
1268: (either the receiving process's umask, or the permissions specified via
1269: the destination directory's default ACL), and their special permission
1270: bits disabled except in the case where a new directory inherits a setgid
1271: bit from its parent directory.
1272:
1273: Thus, when `--perms` and `--executability` are both disabled, rsync's
1274: behavior is the same as that of other file-copy utilities, such as **cp**(1)
1275: and **tar**(1).
1276:
1277: In summary: to give destination files (both old and new) the source
1278: permissions, use `--perms`. To give new files the destination-default
1279: permissions (while leaving existing files unchanged), make sure that the
1280: `--perms` option is off and use `--chmod=ugo=rwX` (which ensures that all
1281: non-masked bits get enabled). If you'd care to make this latter behavior
1282: easier to type, you could define a popt alias for it, such as putting this
1283: line in the file `~/.popt` (the following defines the `-Z` option, and
1284: includes `--no-g` to use the default group of the destination dir):
1285:
1286: > rsync alias -Z --no-p --no-g --chmod=ugo=rwX
1287:
1288: You could then use this new option in a command such as this one:
1289:
1290: > rsync -avZ src/ dest/
1291:
1292: (Caveat: make sure that `-a` does not follow `-Z`, or it will re-enable the
1293: two `--no-*` options mentioned above.)
1294:
1295: The preservation of the destination's setgid bit on newly-created
1296: directories when `--perms` is off was added in rsync 2.6.7. Older rsync
1297: versions erroneously preserved the three special permission bits for
1298: newly-created files when `--perms` was off, while overriding the
1299: destination's setgid bit setting on a newly-created directory. Default ACL
1300: observance was added to the ACL patch for rsync 2.6.7, so older (or
1301: non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
1302: (Keep in mind that it is the version of the receiving rsync that affects
1303: these behaviors.)
1304:
1305: 0. `--executability`, `-E`
1306:
1307: This option causes rsync to preserve the executability (or
1308: non-executability) of regular files when `--perms` is not enabled. A
1309: regular file is considered to be executable if at least one 'x' is turned
1310: on in its permissions. When an existing destination file's executability
1311: differs from that of the corresponding source file, rsync modifies the
1312: destination file's permissions as follows:
1313:
1314: - To make a file non-executable, rsync turns off all its 'x' permissions.
1315: - To make a file executable, rsync turns on each 'x' permission that has a
1316: corresponding 'r' permission enabled.
1317:
1318: If `--perms` is enabled, this option is ignored.
1319:
1320: 0. `--acls`, `-A`
1321:
1322: This option causes rsync to update the destination ACLs to be the same as
1323: the source ACLs. The option also implies `--perms`.
1324:
1325: The source and destination systems must have compatible ACL entries for
1326: this option to work properly. See the `--fake-super` option for a way to
1327: backup and restore ACLs that are not compatible.
1328:
1329: 0. `--xattrs`, `-X`
1330:
1331: This option causes rsync to update the destination extended attributes to
1332: be the same as the source ones.
1333:
1334: For systems that support extended-attribute namespaces, a copy being done
1335: by a super-user copies all namespaces except system.\*. A normal user only
1336: copies the user.\* namespace. To be able to backup and restore non-user
1337: namespaces as a normal user, see the `--fake-super` option.
1338:
1339: The above name filtering can be overridden by using one or more filter
1340: options with the **x** modifier. When you specify an xattr-affecting
1341: filter rule, rsync requires that you do your own system/user filtering, as
1342: well as any additional filtering for what xattr names are copied and what
1343: names are allowed to be deleted. For example, to skip the system
1344: namespace, you could specify:
1345:
1346: > --filter='-x system.*'
1347:
1348: To skip all namespaces except the user namespace, you could specify a
1349: negated-user match:
1350:
1351: > --filter='-x! user.*'
1352:
1353: To prevent any attributes from being deleted, you could specify a
1354: receiver-only rule that excludes all names:
1355:
1356: > --filter='-xr *'
1357:
1358: Note that the `-X` option does not copy rsync's special xattr values (e.g.
1359: those used by `--fake-super`) unless you repeat the option (e.g. `-XX`).
1360: This "copy all xattrs" mode cannot be used with `--fake-super`.
1361:
1362: 0. `--fileflags` This option causes rsync to update the file-flags to be the
1363: same as the source files and directories (if your OS supports the
1364: **chflags**(2) system call). Some flags can only be altered by the
1365: super-user and some might only be unset below a certain secure-level
1366: (usually single-user mode). It will not make files alterable that are set
1367: to immutable on the receiver. To do that, see `--force-change`,
1368: `--force-uchange`, and `--force-schange`.
1369:
1370: 0. `--force-change` This option causes rsync to disable both user-immutable
1371: and system-immutable flags on files and directories that are being updated
1372: or deleted on the receiving side. This option overrides `--force-uchange`
1373: and `--force-schange`.
1374:
1375: 0. `--force-uchange` This option causes rsync to disable user-immutable flags
1376: on files and directories that are being updated or deleted on the receiving
1377: side. It does not try to affect system flags. This option overrides
1378: `--force-change` and `--force-schange`.
1379:
1380: 0. `--force-schange` This option causes rsync to disable system-immutable
1381: flags on files and directories that are being updated or deleted on the
1382: receiving side. It does not try to affect user flags. This option
1383: overrides `--force-change` and `--force-uchange`.
1384:
1385: 0. `--hfs-compression`
1386:
1387: This option causes rsync to preserve HFS+ compression if the destination
1388: filesystem supports it. If the destination does not support it, rsync will
1389: exit with an error.
1390:
1391: Filesystem compression was introduced to HFS+ in Mac OS 10.6. A file that
1392: is compressed has no data in its data fork. Rather, the compressed data is
1393: stored in an extended attribute named com.apple.decmpfs and a file flag is
1394: set to indicate that the file is compressed (UF_COMPRESSED). HFS+
1395: decompresses this data "on-the-fly" and presents it to the operating system
1396: as a normal file. Normal attempts to copy compressed files (e.g. in the
1397: Finder, via cp, ditto, etc.) will copy the file's decompressed contents,
1398: remove the UF_COMPRESSED file flag, and discard the com.apple.decmpfs
1399: extended attribute. This option will preserve the data in the
1400: com.apple.decmpfs extended attribute and ignore the synthesized data in the
1401: file contents.
1402:
1403: This option implies both `--fileflags` and (--xattrs).
1404:
1405: 0. `--protect-decmpfs`
1406:
1407: The com.apple.decmpfs extended attribute is hidden by default from list/get
1408: xattr calls, therefore normal attempts to copy compressed files will
1409: functionally decompress those files. While this is desirable behavior when
1410: copying files to filesystems that do not support HFS+ compression, it has
1411: serious performance and capacity impacts when backing up or restoring the
1412: Mac OS X filesystem.
1413:
1414: This option will transfer the com.apple.decmpfs extended attribute
1415: regardless of support on the destination. If a source file is compressed
1416: and an existing file on the destination is not compressed, the data fork of
1417: the destination file will be truncated and the com.apple.decmpfs xattr will
1418: be transferred instead. Note that compressed files will not be readable to
1419: the operating system of the destination if that operating system does not
1420: support HFS+ compression. Once restored (with or without this option) to an
1421: operating system that supports HFS+ compression, however, these files will
1422: be accessible as usual.
1423:
1424: This option implies `--fileflags` and `--xattrs`.
1425:
1426: 0. `--chmod=CHMOD`
1427:
1428: This option tells rsync to apply one or more comma-separated "chmod" modes
1429: to the permission of the files in the transfer. The resulting value is
1430: treated as though it were the permissions that the sending side supplied
1431: for the file, which means that this option can seem to have no effect on
1432: existing files if `--perms` is not enabled.
1433:
1434: In addition to the normal parsing rules specified in the **chmod**(1)
1435: manpage, you can specify an item that should only apply to a directory by
1436: prefixing it with a 'D', or specify an item that should only apply to a
1437: file by prefixing it with a 'F'. For example, the following will ensure
1438: that all directories get marked set-gid, that no files are other-writable,
1439: that both are user-writable and group-writable, and that both have
1440: consistent executability across all bits:
1441:
1442: > --chmod=Dg+s,ug+w,Fo-w,+X
1443:
1444: Using octal mode numbers is also allowed:
1445:
1446: > --chmod=D2775,F664
1447:
1448: It is also legal to specify multiple `--chmod` options, as each additional
1449: option is just appended to the list of changes to make. To change
1450: permissions of files matching a pattern, use an include filter with the `m`
1451: modifier, which takes effect before any `--chmod` options.
1452:
1453: See the `--perms` and `--executability` options for how the resulting
1454: permission value can be applied to the files in the transfer.
1455:
1456: 0. `--owner`, `-o`
1457:
1458: This option causes rsync to set the owner of the destination file to be the
1459: same as the source file, but only if the receiving rsync is being run as
1460: the super-user (see also the `--super` and `--fake-super` options). Without
1461: this option, the owner of new and/or transferred files are set to the
1462: invoking user on the receiving side.
1463:
1464: The preservation of ownership will associate matching names by default, but
1465: may fall back to using the ID number in some circumstances (see also the
1466: `--numeric-ids` option for a full discussion).
1467:
1468: 0. `--group`, `-g`
1469:
1470: This option causes rsync to set the group of the destination file to be the
1471: same as the source file. If the receiving program is not running as the
1472: super-user (or if `--no-super` was specified), only groups that the
1473: invoking user on the receiving side is a member of will be preserved.
1474: Without this option, the group is set to the default group of the invoking
1475: user on the receiving side.
1476:
1477: The preservation of group information will associate matching names by
1478: default, but may fall back to using the ID number in some circumstances
1479: (see also the `--numeric-ids` option for a full discussion).
1480:
1481: 0. `--devices`
1482:
1483: This option causes rsync to transfer character and block device files to
1484: the remote system to recreate these devices. This option has no effect if
1485: the receiving rsync is not run as the super-user (see also the `--super`
1486: and `--fake-super` options).
1487:
1488: 0. `--specials`
1489:
1490: This option causes rsync to transfer special files such as named sockets
1491: and fifos.
1492:
1493: 0. `-D`
1494:
1495: The `-D` option is equivalent to `--devices --specials`.
1496:
1497: 0. `--write-devices`
1498:
1499: This tells rsync to treat a device on the receiving side as a regular file,
1500: allowing the writing of file data into a device.
1501:
1502: This option implies the `--inplace` option.
1503:
1504: Be careful using this, as you should know what devices are present on the
1505: receiving side of the transfer, especially if running rsync as root.
1506:
1507: This option is refused by an rsync daemon.
1508:
1509: 0. `--times`, `-t`
1510:
1511: This tells rsync to transfer modification times along with the files and
1512: update them on the remote system. Note that if this option is not used,
1513: the optimization that excludes files that have not been modified cannot be
1514: effective; in other words, a missing `-t` or `-a` will cause the next
1515: transfer to behave as if it used `-I`, causing all files to be updated
1516: (though rsync's delta-transfer algorithm will make the update fairly
1517: efficient if the files haven't actually changed, you're much better off
1518: using `-t`).
1519:
1520: 0. `--atimes`, `-U`
1521:
1522: This tells rsync to set the access (use) times of the destination files to
1523: the same value as the source files.
1524:
1525: If repeated, it also sets the `--open-noatime` option, which can help you
1526: to make the sending and receiving systems have the same access times on the
1527: transferred files without needing to run rsync an extra time after a file
1528: is transferred.
1529:
1530: Note that some older rsync versions (prior to 3.2.0) may have been built
1531: with a pre-release `--atimes` patch that does not imply `--open-noatime`
1532: when this option is repeated.
1533:
1534: 0. `--open-noatime`
1535:
1536: This tells rsync to open files with the O_NOATIME flag (on systems that
1537: support it) to avoid changing the access time of the files that are being
1538: transferred. If your OS does not support the O_NOATIME flag then rsync
1539: will silently ignore this option. Note also that some filesystems are
1540: mounted to avoid updating the atime on read access even without the
1541: O_NOATIME flag being set.
1542:
1543: 0. `--crtimes`, `-N,`
1544:
1545: This tells rsync to set the create times (newness) of the destination
1546: files to the same value as the source files.
1547:
1548: 0. `--omit-dir-times`, `-O`
1549:
1550: This tells rsync to omit directories when it is preserving modification
1551: times (see `--times`). If NFS is sharing the directories on the receiving
1552: side, it is a good idea to use `-O`. This option is inferred if you use
1553: `--backup` without `--backup-dir`.
1554:
1555: This option also has the side-effect of avoiding early creation of
1556: directories in incremental recursion copies. The default `--inc-recursive`
1557: copying normally does an early-create pass of all the sub-directories in a
1558: parent directory in order for it to be able to then set the modify time of
1559: the parent directory right away (without having to delay that until a bunch
1560: of recursive copying has finished). This early-create idiom is not
1561: necessary if directory modify times are not being preserved, so it is
1562: skipped. Since early-create directories don't have accurate mode, mtime,
1563: or ownership, the use of this option can help when someone wants to avoid
1564: these partially-finished directories.
1565:
1566: 0. `--omit-link-times`, `-J`
1567:
1568: This tells rsync to omit symlinks when it is preserving modification times
1569: (see `--times`).
1570:
1571: 0. `--omit-dir-changes`
1572:
1573: This tells rsync to omit directories when applying any preserved attributes
1574: (owner, group, times, permissions) to already existing directories.
1575:
1576: 0. `--super`
1577:
1578: This tells the receiving side to attempt super-user activities even if the
1579: receiving rsync wasn't run by the super-user. These activities include:
1580: preserving users via the `--owner` option, preserving all groups (not just
1581: the current user's groups) via the `--groups` option, and copying devices
1582: via the `--devices` option. This is useful for systems that allow such
1583: activities without being the super-user, and also for ensuring that you
1584: will get errors if the receiving side isn't being run as the super-user.
1585: To turn off super-user activities, the super-user can use `--no-super`.
1586:
1587: 0. `--fake-super`
1588:
1589: When this option is enabled, rsync simulates super-user activities by
1590: saving/restoring the privileged attributes via special extended attributes
1591: that are attached to each file (as needed). This includes the file's owner
1592: and group (if it is not the default), the file's device info (device &
1593: special files are created as empty text files), and any permission bits
1594: that we won't allow to be set on the real file (e.g. the real file gets
1595: u-s,g-s,o-t for safety) or that would limit the owner's access (since the
1596: real super-user can always access/change a file, the files we create can
1597: always be accessed/changed by the creating user). This option also handles
1598: ACLs (if `--acls` was specified) and non-user extended attributes (if
1599: `--xattrs` was specified).
1600:
1601: This is a good way to backup data without using a super-user, and to store
1602: ACLs from incompatible systems.
1603:
1604: The `--fake-super` option only affects the side where the option is used.
1605: To affect the remote side of a remote-shell connection, use the
1606: `--remote-option` (`-M`) option:
1607:
1608: > rsync -av -M--fake-super /src/ host:/dest/
1609:
1610: For a local copy, this option affects both the source and the destination.
1611: If you wish a local copy to enable this option just for the destination
1612: files, specify `-M--fake-super`. If you wish a local copy to enable this
1613: option just for the source files, combine `--fake-super` with `-M--super`.
1614:
1615: This option is overridden by both `--super` and `--no-super`.
1616:
1617: See also the "`fake super`" setting in the daemon's rsyncd.conf file.
1618:
1619: 0. `--sparse`, `-S`
1620:
1621: Try to handle sparse files efficiently so they take up less space on the
1622: destination. If combined with `--inplace` the file created might not end
1623: up with sparse blocks with some combinations of kernel version and/or
1624: filesystem type. If `--whole-file` is in effect (e.g. for a local copy)
1625: then it will always work because rsync truncates the file prior to writing
1626: out the updated version.
1627:
1628: Note that versions of rsync older than 3.1.3 will reject the combination of
1629: `--sparse` and `--inplace`.
1630:
1631: 0. `--preallocate`
1632:
1633: This tells the receiver to allocate each destination file to its eventual
1634: size before writing data to the file. Rsync will only use the real
1635: filesystem-level preallocation support provided by Linux's **fallocate**(2)
1636: system call or Cygwin's **posix_fallocate**(3), not the slow glibc
1637: implementation that writes a null byte into each block.
1638:
1639: Without this option, larger files may not be entirely contiguous on the
1640: filesystem, but with this option rsync will probably copy more slowly. If
1641: the destination is not an extent-supporting filesystem (such as ext4, xfs,
1642: NTFS, etc.), this option may have no positive effect at all.
1643:
1644: If combined with `--sparse`, the file will only have sparse blocks (as
1645: opposed to allocated sequences of null bytes) if the kernel version and
1646: filesystem type support creating holes in the allocated data.
1647:
1648: 0. `--sparse-block=SIZE`
1649:
1650: Change the block size used to handle sparse files to SIZE bytes. This
1651: option only has an effect if the `--sparse` (`-S`) option was also
1652: specified. The default block size used by rsync to detect a file hole is
1653: 1024 bytes; when the receiver writes data to the destination file and
1654: option `--sparse` is used, rsync checks every 1024-bytes chunk to detect if
1655: they are actually filled with data or not. With certain filesystems,
1656: optimized to receive data streams for example, enlarging this block size
1657: can strongly increase performance. The option can be used to tune this
1658: block size.
1659:
1660: 0. `--dry-run`, `-n`
1661:
1662: This makes rsync perform a trial run that doesn't make any changes (and
1663: produces mostly the same output as a real run). It is most commonly used
1664: in combination with the `--verbose`, `-v` and/or `--itemize-changes`, `-i`
1665: options to see what an rsync command is going to do before one actually
1666: runs it.
1667:
1668: The output of `--itemize-changes` is supposed to be exactly the same on a
1669: dry run and a subsequent real run (barring intentional trickery and system
1670: call failures); if it isn't, that's a bug. Other output should be mostly
1671: unchanged, but may differ in some areas. Notably, a dry run does not send
1672: the actual data for file transfers, so `--progress` has no effect, the
1673: "bytes sent", "bytes received", "literal data", and "matched data"
1674: statistics are too small, and the "speedup" value is equivalent to a run
1675: where no file transfers were needed.
1676:
1677: 0. `--whole-file`, `-W`
1678:
1679: This option disables rsync's delta-transfer algorithm, which causes all
1680: transferred files to be sent whole. The transfer may be faster if this
1681: option is used when the bandwidth between the source and destination
1682: machines is higher than the bandwidth to disk (especially when the "disk"
1683: is actually a networked filesystem). This is the default when both the
1684: source and destination are specified as local paths, but only if no
1685: batch-writing option is in effect.
1686:
1687: 0. `--checksum-choice=STR`, `--cc=STR`
1688:
1689: This option overrides the checksum algorithms. If one algorithm name is
1690: specified, it is used for both the transfer checksums and (assuming
1691: `--checksum` is specified) the pre-transfer checksums. If two
1692: comma-separated names are supplied, the first name affects the transfer
1693: checksums, and the second name affects the pre-transfer checksums (`-c`).
1694:
1695: The checksum options that you may be able to use are:
1696:
1697: - `auto` (the default automatic choice)
1698: - `xxh128`
1699: - `xxh3`
1700: - `xxh64` (aka `xxhash`)
1701: - `md5`
1702: - `md4`
1703: - `none`
1704:
1705: Run `rsync --version` to see the default checksum list compiled into your
1706: version (which may differ from the list above).
1707:
1708: If "none" is specified for the first (or only) name, the `--whole-file`
1709: option is forced on and no checksum verification is performed on the
1710: transferred data. If "none" is specified for the second (or only) name,
1711: the `--checksum` option cannot be used.
1712:
1713: The "auto" option is the default, where rsync bases its algorithm choice on
1714: a negotiation between the client and the server as follows:
1715:
1716: When both sides of the transfer are at least 3.2.0, rsync chooses the first
1717: algorithm in the client's list of choices that is also in the server's list
1718: of choices. If no common checksum choice is found, rsync exits with
1719: an error. If the remote rsync is too old to support checksum negotiation,
1720: a value is chosen based on the protocol version (which chooses between MD5
1721: and various flavors of MD4 based on protocol age).
1722:
1723: The default order can be customized by setting the environment variable
1724: RSYNC_CHECKSUM_LIST to a space-separated list of acceptable checksum names.
1725: If the string contains a "`&`" character, it is separated into the "client
1726: string & server string", otherwise the same string
1727: applies to both. If the string (or string portion) contains no
1728: non-whitespace characters, the default checksum list is used. This method
1729: does not allow you to specify the transfer checksum separately from the
1730: pre-transfer checksum, and it discards "auto" and all unknown checksum
1731: names. A list with only invalid names results in a failed negotiation.
1732:
1733: The use of the `--checksum-choice` option overrides this environment list.
1734:
1735: 0. `--one-file-system`, `-x`
1736:
1737: This tells rsync to avoid crossing a filesystem boundary when recursing.
1738: This does not limit the user's ability to specify items to copy from
1739: multiple filesystems, just rsync's recursion through the hierarchy of each
1740: directory that the user specified, and also the analogous recursion on the
1741: receiving side during deletion. Also keep in mind that rsync treats a
1742: "bind" mount to the same device as being on the same filesystem.
1743:
1744: If this option is repeated, rsync omits all mount-point directories from
1745: the copy. Otherwise, it includes an empty directory at each mount-point it
1746: encounters (using the attributes of the mounted directory because those of
1747: the underlying mount-point directory are inaccessible).
1748:
1749: If rsync has been told to collapse symlinks (via `--copy-links` or
1750: `--copy-unsafe-links`), a symlink to a directory on another device is
1751: treated like a mount-point. Symlinks to non-directories are unaffected by
1752: this option.
1753:
1754: 0. `--existing`, `--ignore-non-existing`
1755:
1756: This tells rsync to skip creating files (including directories) that do not
1757: exist yet on the destination. If this option is combined with the
1758: `--ignore-existing` option, no files will be updated (which can be useful
1759: if all you want to do is delete extraneous files).
1760:
1761: This option is a transfer rule, not an exclude, so it doesn't affect the
1762: data that goes into the file-lists, and thus it doesn't affect deletions.
1763: It just limits the files that the receiver requests to be transferred.
1764:
1765: 0. `--ignore-existing`
1766:
1767: This tells rsync to skip updating files that already exist on the
1768: destination (this does _not_ ignore existing directories, or nothing would
1769: get done). See also `--existing`.
1770:
1771: This option is a transfer rule, not an exclude, so it doesn't affect the
1772: data that goes into the file-lists, and thus it doesn't affect deletions.
1773: It just limits the files that the receiver requests to be transferred.
1774:
1775: This option can be useful for those doing backups using the `--link-dest`
1776: option when they need to continue a backup run that got interrupted. Since
1777: a `--link-dest` run is copied into a new directory hierarchy (when it is
1778: used properly), using `--ignore-existing` will ensure that the
1779: already-handled files don't get tweaked (which avoids a change in
1780: permissions on the hard-linked files). This does mean that this option is
1781: only looking at the existing files in the destination hierarchy itself.
1782:
1783: 0. `--remove-source-files`
1784:
1785: This tells rsync to remove from the sending side the files (meaning
1786: non-directories) that are a part of the transfer and have been successfully
1787: duplicated on the receiving side.
1788:
1789: Note that you should only use this option on source files that are
1790: quiescent. If you are using this to move files that show up in a
1791: particular directory over to another host, make sure that the finished
1792: files get renamed into the source directory, not directly written into it,
1793: so that rsync can't possibly transfer a file that is not yet fully written.
1794: If you can't first write the files into a different directory, you should
1795: use a naming idiom that lets rsync avoid transferring files that are not
1796: yet finished (e.g. name the file "foo.new" when it is written, rename it to
1797: "foo" when it is done, and then use the option `--exclude='*.new'` for the
1798: rsync transfer).
1799:
1800: Starting with 3.1.0, rsync will skip the sender-side removal (and output an
1801: error) if the file's size or modify time has not stayed unchanged.
1802:
1803: 0. `--source-backup`
1804:
1805: Makes the sender back up the source files it removes due to
1806: `--remove-source-files`. This option is independent of `--backup` but uses
1807: the same `--backup-dir` and `--suffix` settings, if any. With
1808: `--backup-dir`, rsync looks for each file's backup dir relative to the
1809: source argument the file came from. Consequently, if the `--backup-dir`
1810: path is relative, each source argument gets a separate backup dir at that
1811: path relative to the argument.
1812:
1813: 0. `--delete`
1814:
1815: This tells rsync to delete extraneous files from the receiving side (ones
1816: that aren't on the sending side), but only for the directories that are
1817: being synchronized. You must have asked rsync to send the whole directory
1818: (e.g. "`dir`" or "`dir/`") without using a wildcard for the directory's
1819: contents (e.g. "`dir/*`") since the wildcard is expanded by the shell and
1820: rsync thus gets a request to transfer individual files, not the files'
1821: parent directory. Files that are excluded from the transfer are also
1822: excluded from being deleted unless you use the `--delete-excluded` option
1823: or mark the rules as only matching on the sending side (see the
1824: include/exclude modifiers in the FILTER RULES section).
1825:
1826: Prior to rsync 2.6.7, this option would have no effect unless `--recursive`
1827: was enabled. Beginning with 2.6.7, deletions will also occur when `--dirs`
1828: (`-d`) is enabled, but only for directories whose contents are being
1829: copied.
1830:
1831: This option can be dangerous if used incorrectly! It is a very good idea to
1832: first try a run using the `--dry-run` option (`-n`) to see what files are
1833: going to be deleted.
1834:
1835: If the sending side detects any I/O errors, then the deletion of any files
1836: at the destination will be automatically disabled. This is to prevent
1837: temporary filesystem failures (such as NFS errors) on the sending side from
1838: causing a massive deletion of files on the destination. You can override
1839: this with the `--ignore-errors` option.
1840:
1841: The `--delete` option may be combined with one of the --delete-WHEN options
1842: without conflict, as well as `--delete-excluded`. However, if none of the
1843: `--delete-WHEN` options are specified, rsync will choose the
1844: `--delete-during` algorithm when talking to rsync 3.0.0 or newer, and the
1845: `--delete-before` algorithm when talking to an older rsync. See also
1846: `--delete-delay` and `--delete-after`.
1847:
1848: 0. `--delete-before`
1849:
1850: Request that the file-deletions on the receiving side be done before the
1851: transfer starts. See `--delete` (which is implied) for more details on
1852: file-deletion.
1853:
1854: Deleting before the transfer is helpful if the filesystem is tight for
1855: space and removing extraneous files would help to make the transfer
1856: possible. However, it does introduce a delay before the start of the
1857: transfer, and this delay might cause the transfer to timeout (if
1858: `--timeout` was specified). It also forces rsync to use the old,
1859: non-incremental recursion algorithm that requires rsync to scan all the
1860: files in the transfer into memory at once (see `--recursive`).
1861:
1862: 0. `--delete-during`, `--del`
1863:
1864: Request that the file-deletions on the receiving side be done incrementally
1865: as the transfer happens. The per-directory delete scan is done right
1866: before each directory is checked for updates, so it behaves like a more
1867: efficient `--delete-before`, including doing the deletions prior to any
1868: per-directory filter files being updated. This option was first added in
1869: rsync version 2.6.4. See `--delete` (which is implied) for more details on
1870: file-deletion.
1871:
1872: 0. `--delete-delay`
1873:
1874: Request that the file-deletions on the receiving side be computed during
1875: the transfer (like `--delete-during`), and then removed after the transfer
1876: completes. This is useful when combined with `--delay-updates` and/or
1877: `--fuzzy`, and is more efficient than using `--delete-after` (but can
1878: behave differently, since `--delete-after` computes the deletions in a
1879: separate pass after all updates are done). If the number of removed files
1880: overflows an internal buffer, a temporary file will be created on the
1881: receiving side to hold the names (it is removed while open, so you
1882: shouldn't see it during the transfer). If the creation of the temporary
1883: file fails, rsync will try to fall back to using `--delete-after` (which it
1884: cannot do if `--recursive` is doing an incremental scan). See `--delete`
1885: (which is implied) for more details on file-deletion.
1886:
1887: 0. `--delete-after`
1888:
1889: Request that the file-deletions on the receiving side be done after the
1890: transfer has completed. This is useful if you are sending new
1891: per-directory merge files as a part of the transfer and you want their
1892: exclusions to take effect for the delete phase of the current transfer. It
1893: also forces rsync to use the old, non-incremental recursion algorithm that
1894: requires rsync to scan all the files in the transfer into memory at once
1895: (see `--recursive`). See `--delete` (which is implied) for more details on
1896: file-deletion.
1897:
1898: 0. `--delete-excluded`
1899:
1900: In addition to deleting the files on the receiving side that are not on the
1901: sending side, this tells rsync to also delete any files on the receiving
1902: side that are excluded (see `--exclude`). See the FILTER RULES section for
1903: a way to make individual exclusions behave this way on the receiver, and
1904: for a way to protect files from `--delete-excluded`. See `--delete` (which
1905: is implied) for more details on file-deletion.
1906:
1907: 0. `--ignore-missing-args`
1908:
1909: When rsync is first processing the explicitly requested source files (e.g.
1910: command-line arguments or `--files-from` entries), it is normally an error
1911: if the file cannot be found. This option suppresses that error, and does
1912: not try to transfer the file. This does not affect subsequent
1913: vanished-file errors if a file was initially found to be present and later
1914: is no longer there.
1915:
1916: 0. `--delete-missing-args`
1917:
1918: This option takes the behavior of (the implied) `--ignore-missing-args`
1919: option a step farther: each missing arg will become a deletion request of
1920: the corresponding destination file on the receiving side (should it exist).
1921: If the destination file is a non-empty directory, it will only be
1922: successfully deleted if `--force-delete` or `--delete` are in effect. Other than
1923: that, this option is independent of any other type of delete processing.
1924:
1925: The missing source files are represented by special file-list entries which
1926: display as a "`*missing`" entry in the `--list-only` output.
1927:
1928: 0. `--ignore-errors`
1929:
1930: Tells `--delete` to go ahead and delete files even when there are I/O
1931: errors.
1932:
1933: 0. `--force-delete`
1934:
1935: This option tells rsync to delete a non-empty directory when it is to be
1936: replaced by a non-directory. This is only relevant if deletions are not
1937: active (see `--delete` for details).
1938:
1939: This option can be abbreviated `--force` for backward compatibility. Note
1940: that some older rsync versions used to still require `--force` when using
1941: `--delete-after`, and it used to be non-functional unless the `--recursive`
1942: option was also enabled.
1943:
1944: 0. `--max-delete=NUM`
1945:
1946: This tells rsync not to delete more than NUM files or directories. If that
1947: limit is exceeded, all further deletions are skipped through the end of the
1948: transfer. At the end, rsync outputs a warning (including a count of the
1949: skipped deletions) and exits with an error code of 25 (unless some more
1950: important error condition also occurred).
1951:
1952: Beginning with version 3.0.0, you may specify `--max-delete=0` to be warned
1953: about any extraneous files in the destination without removing any of them.
1954: Older clients interpreted this as "unlimited", so if you don't know what
1955: version the client is, you can use the less obvious `--max-delete=-1` as a
1956: backward-compatible way to specify that no deletions be allowed (though
1957: really old versions didn't warn when the limit was exceeded).
1958:
1959: 0. `--max-size=SIZE`
1960:
1961: This tells rsync to avoid transferring any file that is larger than the
1962: specified SIZE. A numeric value can be suffixed with a string to indicate
1963: the numeric units or left unqualified to specify bytes. Feel free to use a
1964: fractional value along with the units, such as `--max-size=1.5m`.
1965:
1966: This option is a transfer rule, not an exclude, so it doesn't affect the
1967: data that goes into the file-lists, and thus it doesn't affect deletions.
1968: It just limits the files that the receiver requests to be transferred.
1969:
1970: The first letter of a units string can be `B` (bytes), `K` (kilo), `M`
1971: (mega), `G` (giga), `T` (tera), or `P` (peta). If the string is a single
1972: char or has "ib" added to it (e.g. "G" or "GiB") then the units are
1973: multiples of 1024. If you use a two-letter suffix that ends with a "B"
1974: (e.g. "kb") then you get units that are multiples of 1000. The string's
1975: letters can be any mix of upper and lower-case that you want to use.
1976:
1977: Finally, if the string ends with either "+1" or "-1", it is offset by one
1978: byte in the indicated direction. The largest possible value is usually
1979: `8192P-1`.
1980:
1981: Examples: `--max-size=1.5mb-1` is 1499999 bytes, and `--max-size=2g+1` is
1982: 2147483649 bytes.
1983:
1984: Note that rsync versions prior to 3.1.0 did not allow `--max-size=0`.
1985:
1986: 0. `--min-size=SIZE`
1987:
1988: This tells rsync to avoid transferring any file that is smaller than the
1989: specified SIZE, which can help in not transferring small, junk files. See
1990: the `--max-size` option for a description of SIZE and other information.
1991:
1992: Note that rsync versions prior to 3.1.0 did not allow `--min-size=0`.
1993:
1994: 0. `--max-alloc=SIZE`
1995:
1996: By default rsync limits an individual malloc/realloc to about 1GB in size.
1997: For most people this limit works just fine and prevents a protocol error
1998: causing rsync to request massive amounts of memory. However, if you have
1999: many millions of files in a transfer, a large amount of server memory, and
2000: you don't want to split up your transfer into multiple parts, you can
2001: increase the per-allocation limit to something larger and rsync will
2002: consume more memory.
2003:
2004: Keep in mind that this is not a limit on the total size of allocated
2005: memory. It is a sanity-check value for each individual allocation.
2006:
2007: See the `--max-size` option for a description of how SIZE can be specified.
2008: The default suffix if none is given is bytes.
2009:
2010: Beginning in 3.2.3, a value of 0 specifies no limit.
2011:
2012: You can set a default value using the environment variable RSYNC_MAX_ALLOC
2013: using the same SIZE values as supported by this option. If the remote
2014: rsync doesn't understand the `--max-alloc` option, you can override an
2015: environmental value by specifying `--max-alloc=1g`, which will make rsync
2016: avoid sending the option to the remote side (because "1G" is the default).
2017:
2018: 0. `--block-size=SIZE`, `-B`
2019:
2020: This forces the block size used in rsync's delta-transfer algorithm to a
2021: fixed value. It is normally selected based on the size of each file being
2022: updated. See the technical report for details.
2023:
2024: Beginning in 3.2.3 the SIZE can be specified with a suffix as detailed in
2025: the `--max-size` option. Older versions only accepted a byte count.
2026:
2027: 0. `--rsh=COMMAND`, `-e`
2028:
2029: This option allows you to choose an alternative remote shell program to use
2030: for communication between the local and remote copies of rsync. Typically,
2031: rsync is configured to use ssh by default, but you may prefer to use rsh on
2032: a local network.
2033:
2034: If this option is used with `[user@]host::module/path`, then the remote
2035: shell _COMMAND_ will be used to run an rsync daemon on the remote host, and
2036: all data will be transmitted through that remote shell connection, rather
2037: than through a direct socket connection to a running rsync daemon on the
2038: remote host. See the section "USING RSYNC-DAEMON FEATURES VIA A
2039: REMOTE-SHELL CONNECTION" above.
2040:
2041: Beginning with rsync 3.2.0, the RSYNC_PORT environment variable will be set
2042: when a daemon connection is being made via a remote-shell connection. It
2043: is set to 0 if the default daemon port is being assumed, or it is set to
2044: the value of the rsync port that was specified via either the `--port`
2045: option or a non-empty port value in an rsync:// URL. This allows the
2046: script to discern if a non-default port is being requested, allowing for
2047: things such as an SSL or stunnel helper script to connect to a default or
2048: alternate port.
2049:
2050: Command-line arguments are permitted in COMMAND provided that COMMAND is
2051: presented to rsync as a single argument. You must use spaces (not tabs or
2052: other whitespace) to separate the command and args from each other, and you
2053: can use single- and/or double-quotes to preserve spaces in an argument (but
2054: not backslashes). Note that doubling a single-quote inside a single-quoted
2055: string gives you a single-quote; likewise for double-quotes (though you
2056: need to pay attention to which quotes your shell is parsing and which
2057: quotes rsync is parsing). Some examples:
2058:
2059: > -e 'ssh -p 2234'
2060: > -e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"'
2061:
2062: (Note that ssh users can alternately customize site-specific connect
2063: options in their .ssh/config file.)
2064:
2065: You can also choose the remote shell program using the RSYNC_RSH
2066: environment variable, which accepts the same range of values as `-e`.
2067:
2068: See also the `--blocking-io` option which is affected by this option.
2069:
2070: 0. `--rsync-path=PROGRAM`
2071:
2072: Use this to specify what program is to be run on the remote machine to
2073: start-up rsync. Often used when rsync is not in the default remote-shell's
2074: path (e.g. `--rsync-path=/usr/local/bin/rsync`). Note that PROGRAM is run
2075: with the help of a shell, so it can be any program, script, or command
2076: sequence you'd care to run, so long as it does not corrupt the standard-in
2077: & standard-out that rsync is using to communicate.
2078:
2079: One tricky example is to set a different default directory on the remote
2080: machine for use with the `--relative` option. For instance:
2081:
2082: > rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/
2083:
2084: 0. `--remote-option=OPTION`, `-M`
2085:
2086: This option is used for more advanced situations where you want certain
2087: effects to be limited to one side of the transfer only. For instance, if
2088: you want to pass `--log-file=FILE` and `--fake-super` to the remote system,
2089: specify it like this:
2090:
2091: > rsync -av -M --log-file=foo -M--fake-super src/ dest/
2092:
2093: If you want to have an option affect only the local side of a transfer when
2094: it normally affects both sides, send its negation to the remote side. Like
2095: this:
2096:
2097: > rsync -av -x -M--no-x src/ dest/
2098:
2099: Be cautious using this, as it is possible to toggle an option that will
2100: cause rsync to have a different idea about what data to expect next over
2101: the socket, and that will make it fail in a cryptic fashion.
2102:
2103: Note that it is best to use a separate `--remote-option` for each option
2104: you want to pass. This makes your usage compatible with the
2105: `--protect-args` option. If that option is off, any spaces in your remote
2106: options will be split by the remote shell unless you take steps to protect
2107: them.
2108:
2109: When performing a local transfer, the "local" side is the sender and the
2110: "remote" side is the receiver.
2111:
2112: Note some versions of the popt option-parsing library have a bug in them
2113: that prevents you from using an adjacent arg with an equal in it next to a
2114: short option letter (e.g. `-M--log-file=/tmp/foo`). If this bug affects
2115: your version of popt, you can use the version of popt that is included with
2116: rsync.
2117:
2118: 0. `--cvs-exclude`, `-C`
2119:
2120: This is a useful shorthand for excluding a broad range of files that you
2121: often don't want to transfer between systems. It uses a similar algorithm
2122: to CVS to determine if a file should be ignored.
2123:
2124: The exclude list is initialized to exclude the following items (these
2125: initial items are marked as perishable -- see the FILTER RULES section):
2126:
2127: [comment]: # (This list gets used for the default-cvsignore.h file.)
2128:
2129: > `RCS`
2130: > `SCCS`
2131: > `CVS`
2132: > `CVS.adm`
2133: > `RCSLOG`
2134: > `cvslog.*`
2135: > `tags`
2136: > `TAGS`
2137: > `.make.state`
2138: > `.nse_depinfo`
2139: > `*~`
2140: > `#*`
2141: > `.#*`
2142: > `,*`
2143: > `_$*`
2144: > `*$`
2145: > `*.old`
2146: > `*.bak`
2147: > `*.BAK`
2148: > `*.orig`
2149: > `*.rej`
2150: > `.del-*`
2151: > `*.a`
2152: > `*.olb`
2153: > `*.o`
2154: > `*.obj`
2155: > `*.so`
2156: > `*.exe`
2157: > `*.Z`
2158: > `*.elc`
2159: > `*.ln`
2160: > `core`
2161: > `.svn/`
2162: > `.git/`
2163: > `.hg/`
2164: > `.bzr/`
2165:
2166: then, files listed in a $HOME/.cvsignore are added to the list and any
2167: files listed in the CVSIGNORE environment variable (all cvsignore names are
2168: delimited by whitespace).
2169:
2170: Finally, any file is ignored if it is in the same directory as a .cvsignore
2171: file and matches one of the patterns listed therein. Unlike rsync's
2172: filter/exclude files, these patterns are split on whitespace. See the
2173: **cvs**(1) manual for more information.
2174:
2175: If you're combining `-C` with your own `--filter` rules, you should note
2176: that these CVS excludes are appended at the end of your own rules,
2177: regardless of where the `-C` was placed on the command-line. This makes
2178: them a lower priority than any rules you specified explicitly. If you want
2179: to control where these CVS excludes get inserted into your filter rules,
2180: you should omit the `-C` as a command-line option and use a combination of
2181: `--filter=:C` and `--filter=-C` (either on your command-line or by putting
2182: the ":C" and "-C" rules into a filter file with your other rules). The
2183: first option turns on the per-directory scanning for the .cvsignore file.
2184: The second option does a one-time import of the CVS excludes mentioned
2185: above.
2186:
2187: 0. `--filter=RULE`, `-f`
2188:
2189: This option allows you to add rules to selectively exclude certain files
2190: from the list of files to be transferred. This is most useful in
2191: combination with a recursive transfer.
2192:
2193: You may use as many `--filter` options on the command line as you like to
2194: build up the list of files to exclude. If the filter contains whitespace,
2195: be sure to quote it so that the shell gives the rule to rsync as a single
2196: argument. The text below also mentions that you can use an underscore to
2197: replace the space that separates a rule from its arg.
2198:
2199: See the FILTER RULES section for detailed information on this option.
2200:
2201: 0. `-F`
2202:
2203: The `-F` option is a shorthand for adding two `--filter` rules to your
2204: command. The first time it is used is a shorthand for this rule:
2205:
2206: > --filter='dir-merge /.rsync-filter'
2207:
2208: This tells rsync to look for per-directory .rsync-filter files that have
2209: been sprinkled through the hierarchy and use their rules to filter the
2210: files in the transfer. If `-F` is repeated, it is a shorthand for this
2211: rule:
2212:
2213: > --filter='exclude .rsync-filter'
2214:
2215: This filters out the .rsync-filter files themselves from the transfer.
2216:
2217: See the FILTER RULES section for detailed information on how these options
2218: work.
2219:
2220: 0. `--exclude=PATTERN`
2221:
2222: This option is a simplified form of the `--filter` option that defaults to
2223: an exclude rule and does not allow the full rule-parsing syntax of normal
2224: filter rules.
2225:
2226: See the FILTER RULES section for detailed information on this option.
2227:
2228: 0. `--exclude-from=FILE`
2229:
2230: This option is related to the `--exclude` option, but it specifies a FILE
2231: that contains exclude patterns (one per line). Blank lines in the file and
2232: lines starting with '`;`' or '`#`' are ignored. If _FILE_ is '`-`', the
2233: list will be read from standard input.
2234:
2235: 0. `--include=PATTERN`
2236:
2237: This option is a simplified form of the `--filter` option that defaults to
2238: an include rule and does not allow the full rule-parsing syntax of normal
2239: filter rules.
2240:
2241: See the FILTER RULES section for detailed information on this option.
2242:
2243: 0. `--include-from=FILE`
2244:
2245: This option is related to the `--include` option, but it specifies a FILE
2246: that contains include patterns (one per line). Blank lines in the file and
2247: lines starting with '`;`' or '`#`' are ignored. If _FILE_ is '`-`', the
2248: list will be read from standard input.
2249:
2250: 0. `--files-from=FILE`
2251:
2252: Using this option allows you to specify the exact list of files to transfer
2253: (as read from the specified FILE or '`-`' for standard input). It also
2254: tweaks the default behavior of rsync to make transferring just the
2255: specified files and directories easier:
2256:
2257: - The `--relative` (`-R`) option is implied, which preserves the path
2258: information that is specified for each item in the file (use
2259: `--no-relative` or `--no-R` if you want to turn that off).
2260: - The `--dirs` (`-d`) option is implied, which will create directories
2261: specified in the list on the destination rather than noisily skipping
2262: them (use `--no-dirs` or `--no-d` if you want to turn that off).
2263: - The `--archive` (`-a`) option's behavior does not imply `--recursive`
2264: (`-r`), so specify it explicitly, if you want it.
2265: - These side-effects change the default state of rsync, so the position of
2266: the `--files-from` option on the command-line has no bearing on how other
2267: options are parsed (e.g. `-a` works the same before or after
2268: `--files-from`, as does `--no-R` and all other options).
2269:
2270: The filenames that are read from the FILE are all relative to the source
2271: dir -- any leading slashes are removed and no ".." references are allowed
2272: to go higher than the source dir. For example, take this command:
2273:
2274: > rsync -a --files-from=/tmp/foo /usr remote:/backup
2275:
2276: If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
2277: directory will be created as /backup/bin on the remote host. If it
2278: contains "bin/" (note the trailing slash), the immediate contents of the
2279: directory would also be sent (without needing to be explicitly mentioned in
2280: the file -- this began in version 2.6.4). In both cases, if the `-r`
2281: option was enabled, that dir's entire hierarchy would also be transferred
2282: (keep in mind that `-r` needs to be specified explicitly with
2283: `--files-from`, since it is not implied by `-a`). Also note that the
2284: effect of the (enabled by default) `--relative` option is to duplicate only
2285: the path info that is read from the file -- it does not force the
2286: duplication of the source-spec path (/usr in this case).
2287:
2288: In addition, the `--files-from` file can be read from the remote host
2289: instead of the local host if you specify a "host:" in front of the file
2290: (the host must match one end of the transfer). As a short-cut, you can
2291: specify just a prefix of ":" to mean "use the remote end of the transfer".
2292: For example:
2293:
2294: > rsync -a --files-from=:/path/file-list src:/ /tmp/copy
2295:
2296: This would copy all the files specified in the /path/file-list file that
2297: was located on the remote "src" host.
2298:
2299: If the `--iconv` and `--protect-args` options are specified and the
2300: `--files-from` filenames are being sent from one host to another, the
2301: filenames will be translated from the sending host's charset to the
2302: receiving host's charset.
2303:
2304: NOTE: sorting the list of files in the `--files-from` input helps rsync to
2305: be more efficient, as it will avoid re-visiting the path elements that are
2306: shared between adjacent entries. If the input is not sorted, some path
2307: elements (implied directories) may end up being scanned multiple times, and
2308: rsync will eventually unduplicate them after they get turned into file-list
2309: elements.
2310:
2311: 0. `--from0`, `-0`
2312:
2313: This tells rsync that the rules/filenames it reads from a file are
2314: terminated by a null ('\\0') character, not a NL, CR, or CR+LF. This
2315: affects `--exclude-from`, `--include-from`, `--files-from`, and any merged
2316: files specified in a `--filter` rule. It does not affect `--cvs-exclude`
2317: (since all names read from a .cvsignore file are split on whitespace).
2318:
2319: 0. `--protect-args`, `-s`
2320:
2321: This option sends all filenames and most options to the remote rsync
2322: without allowing the remote shell to interpret them. This means that
2323: spaces are not split in names, and any non-wildcard special characters are
2324: not translated (such as `~`, `$`, `;`, `&`, etc.). Wildcards are expanded
2325: on the remote host by rsync (instead of the shell doing it).
2326:
2327: If you use this option with `--iconv`, the args related to the remote side
2328: will also be translated from the local to the remote character-set. The
2329: translation happens before wild-cards are expanded. See also the
2330: `--files-from` option.
2331:
2332: You may also control this option via the RSYNC_PROTECT_ARGS environment
2333: variable. If this variable has a non-zero value, this option will be
2334: enabled by default, otherwise it will be disabled by default. Either state
2335: is overridden by a manually specified positive or negative version of this
2336: option (note that `--no-s` and `--no-protect-args` are the negative
2337: versions). Since this option was first introduced in 3.0.0, you'll need to
2338: make sure it's disabled if you ever need to interact with a remote rsync
2339: that is older than that.
2340:
2341: Rsync can also be configured (at build time) to have this option enabled by
2342: default (with is overridden by both the environment and the command-line).
2343: Run `rsync --version` to check if this is the case, as it will display
2344: "default protect-args" or "optional protect-args" depending on how it was
2345: compiled.
2346:
2347: This option will eventually become a new default setting at some
2348: as-yet-undetermined point in the future.
2349:
2350: 0. `--copy-as=USER[:GROUP]`
2351:
2352: This option instructs rsync to use the USER and (if specified after a
2353: colon) the GROUP for the copy operations. This only works if the user that
2354: is running rsync has the ability to change users. If the group is not
2355: specified then the user's default groups are used.
2356:
2357: This option can help to reduce the risk of an rsync being run as root into
2358: or out of a directory that might have live changes happening to it and you
2359: want to make sure that root-level read or write actions of system files are
2360: not possible. While you could alternatively run all of rsync as the
2361: specified user, sometimes you need the root-level host-access credentials
2362: to be used, so this allows rsync to drop root for the copying part of the
2363: operation after the remote-shell or daemon connection is established.
2364:
2365: The option only affects one side of the transfer unless the transfer is
2366: local, in which case it affects both sides. Use the `--remote-option` to
2367: affect the remote side, such as `-M--copy-as=joe`. For a local transfer,
2368: the lsh (or lsh.sh) support file provides a local-shell helper script that
2369: can be used to allow a "localhost:" or "lh:" host-spec to be specified
2370: without needing to setup any remote shells, allowing you to specify remote
2371: options that affect the side of the transfer that is using the host-spec
2372: (and using hostname "lh" avoids the overriding of the remote directory to
2373: the user's home dir).
2374:
2375: For example, the following rsync writes the local files as user "joe":
2376:
2377: > sudo rsync -aiv --copy-as=joe host1:backups/joe/ /home/joe/
2378:
2379: This makes all files owned by user "joe", limits the groups to those that
2380: are available to that user, and makes it impossible for the joe user to do
2381: a timed exploit of the path to induce a change to a file that the joe user
2382: has no permissions to change.
2383:
2384: The following command does a local copy into the "dest/" dir as user "joe"
2385: (assuming you've installed support/lsh into a dir on your $PATH):
2386:
2387: > sudo rsync -aive lsh -M--copy-as=joe src/ lh:dest/
2388:
2389: 0. `--ignore-case`
2390:
2391: This option tells rsync to ignore upper-/lower-case differences when
2392: comparing filenames. This can avoid problems when sending files to a
2393: filesystem that ignores these differences.
2394:
2395: 0. `--temp-dir=DIR`, `-T`
2396:
2397: This option instructs rsync to use DIR as a scratch directory when creating
2398: temporary copies of the files transferred on the receiving side. The
2399: default behavior is to create each temporary file in the same directory as
2400: the associated destination file. Beginning with rsync 3.1.1, the temp-file
2401: names inside the specified DIR will not be prefixed with an extra dot
2402: (though they will still have a random suffix added).
2403:
2404: This option is most often used when the receiving disk partition does not
2405: have enough free space to hold a copy of the largest file in the transfer.
2406: In this case (i.e. when the scratch directory is on a different disk
2407: partition), rsync will not be able to rename each received temporary file
2408: over the top of the associated destination file, but instead must copy it
2409: into place. Rsync does this by copying the file over the top of the
2410: destination file, which means that the destination file will contain
2411: truncated data during this copy. If this were not done this way (even if
2412: the destination file were first removed, the data locally copied to a
2413: temporary file in the destination directory, and then renamed into place)
2414: it would be possible for the old file to continue taking up disk space (if
2415: someone had it open), and thus there might not be enough room to fit the
2416: new version on the disk at the same time.
2417:
2418: If you are using this option for reasons other than a shortage of disk
2419: space, you may wish to combine it with the `--delay-updates` option, which
2420: will ensure that all copied files get put into subdirectories in the
2421: destination hierarchy, awaiting the end of the transfer. If you don't have
2422: enough room to duplicate all the arriving files on the destination
2423: partition, another way to tell rsync that you aren't overly concerned about
2424: disk space is to use the `--partial-dir` option with a relative path;
2425: because this tells rsync that it is OK to stash off a copy of a single file
2426: in a subdir in the destination hierarchy, rsync will use the partial-dir as
2427: a staging area to bring over the copied file, and then rename it into place
2428: from there. (Specifying a `--partial-dir` with an absolute path does not
2429: have this side-effect.)
2430:
2431: 0. `--fuzzy`, `-y`
2432:
2433: This option tells rsync that it should look for a basis file for any
2434: destination file that is missing. The current algorithm looks in the same
2435: directory as the destination file for either a file that has an identical
2436: size and modified-time, or a similarly-named file. If found, rsync uses
2437: the fuzzy basis file to try to speed up the transfer.
2438:
2439: If the option is repeated, the fuzzy scan will also be done in any matching
2440: alternate destination directories that are specified via `--compare-dest`,
2441: `--copy-dest`, or `--link-dest`.
2442:
2443: Note that the use of the `--delete` option might get rid of any potential
2444: fuzzy-match files, so either use `--delete-after` or specify some filename
2445: exclusions if you need to prevent this.
2446:
2447: 0. ``--detect-renamed-lax` This version of `--detect-renamed` makes rsync
2448: hard-link `dest/D` to `dest/S` without verifying that `src/S` and
2449: `dest/S` have the same data. This poses a significant risk of corrupting
2450: the destination by representing a new source file by an unrelated
2451: destination file that coincidentally passes the quick check with the source
2452: file. Use this option only if you accept the risk and disk I/O is a
2453: bottleneck.
2454:
2455: 0. ``--detect-moved`` A less risky variant of `--detect-renamed-lax` that only
2456: uses a destination file that has the same basename as the new source file.
2457:
2458: 0. `--detect-renamed`
2459:
2460: With this option, for each new source file (call it `src/S`), rsync looks
2461: for a file `dest/D` anywhere in the destination that passes the quick check
2462: with `src/S`. If such a `dest/D` is found, rsync uses it as an alternate
2463: basis for transferring `S`. The idea is that if `src/S` was renamed from
2464: `src/D` (as opposed to `src/S` passing the quick check with `dest/D` by
2465: coincidence), the delta-transfer algorithm will find that all the data
2466: matches between `src/S` and `dest/D`, and the transfer will be really fast.
2467:
2468: By default, alternate-basis files are hard-linked into a directory named
2469: ".~tmp~" in each file's destination directory, but if you've specified the
2470: `--partial-dir` option, that directory will be used instead. These
2471: otential alternate-basis files will be removed as the transfer progresses.
2472: This option conflicts with `--inplace` and `--append`.
2473:
2474: 0. `--compare-dest=DIR`
2475:
2476: This option instructs rsync to use _DIR_ on the destination machine as an
2477: additional hierarchy to compare destination files against doing transfers
2478: (if the files are missing in the destination directory). If a file is
2479: found in _DIR_ that is identical to the sender's file, the file will NOT be
2480: transferred to the destination directory. This is useful for creating a
2481: sparse backup of just files that have changed from an earlier backup. This
2482: option is typically used to copy into an empty (or newly created)
2483: directory.
2484:
2485: Beginning in version 2.6.4, multiple `--compare-dest` directories may be
2486: provided, which will cause rsync to search the list in the order specified
2487: for an exact match. If a match is found that differs only in attributes, a
2488: local copy is made and the attributes updated. If a match is not found, a
2489: basis file from one of the _DIRs_ will be selected to try to speed up the
2490: transfer.
2491:
2492: If _DIR_ is a relative path, it is relative to the destination directory.
2493: See also `--copy-dest` and `--link-dest`.
2494:
2495: NOTE: beginning with version 3.1.0, rsync will remove a file from a
2496: non-empty destination hierarchy if an exact match is found in one of the
2497: compare-dest hierarchies (making the end result more closely match a fresh
2498: copy).
2499:
2500: 0. `--copy-dest=DIR`
2501:
2502: This option behaves like `--compare-dest`, but rsync will also copy
2503: unchanged files found in _DIR_ to the destination directory using a local
2504: copy. This is useful for doing transfers to a new destination while
2505: leaving existing files intact, and then doing a flash-cutover when all
2506: files have been successfully transferred.
2507:
2508: Multiple `--copy-dest` directories may be provided, which will cause rsync
2509: to search the list in the order specified for an unchanged file. If a
2510: match is not found, a basis file from one of the _DIRs_ will be selected to
2511: try to speed up the transfer.
2512:
2513: If _DIR_ is a relative path, it is relative to the destination directory.
2514: See also `--compare-dest` and `--link-dest`.
2515:
2516: 0. `--link-dest=DIR`
2517:
2518: This option behaves like `--copy-dest`, but unchanged files are hard linked
2519: from _DIR_ to the destination directory. The files must be identical in
2520: all preserved attributes (e.g. permissions, possibly ownership) in order
2521: for the files to be linked together. An example:
2522:
2523: > rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
2524:
2525: If file's aren't linking, double-check their attributes. Also check if
2526: some attributes are getting forced outside of rsync's control, such a mount
2527: option that squishes root to a single user, or mounts a removable drive
2528: with generic ownership (such as OS X's "Ignore ownership on this volume"
2529: option).
2530:
2531: Beginning in version 2.6.4, multiple `--link-dest` directories may be
2532: provided, which will cause rsync to search the list in the order specified
2533: for an exact match (there is a limit of 20 such directories). If a match
2534: is found that differs only in attributes, a local copy is made and the
2535: attributes updated. If a match is not found, a basis file from one of the
2536: _DIRs_ will be selected to try to speed up the transfer.
2537:
2538: This option works best when copying into an empty destination hierarchy, as
2539: existing files may get their attributes tweaked, and that can affect
2540: alternate destination files via hard-links. Also, itemizing of changes can
2541: get a bit muddled. Note that prior to version 3.1.0, an
2542: alternate-directory exact match would never be found (nor linked into the
2543: destination) when a destination file already exists.
2544:
2545: Note that if you combine this option with `--ignore-times`, rsync will not
2546: link any files together because it only links identical files together as a
2547: substitute for transferring the file, never as an additional check after
2548: the file is updated.
2549:
2550: If _DIR_ is a relative path, it is relative to the destination directory.
2551: See also `--compare-dest` and `--copy-dest`.
2552:
2553: Note that rsync versions prior to 2.6.1 had a bug that could prevent
2554: `--link-dest` from working properly for a non-super-user when `-o` was
2555: specified (or implied by `-a`). You can work-around this bug by avoiding
2556: the `-o` option when sending to an old rsync.
2557:
2558: 0. `--clone-dest=DIR`
2559:
2560: This option behaves like `--link-dest`, but unchanged files are reflinked
2561: from _DIR_ to the destination directory. The files do not need to match
2562: in attributes, as the data is cloned separately from the attributes.
2563:
2564: If _DIR_ is a relative path, it is relative to the destination directory.
2565: See also `--compare-dest` and `--copy-dest`.
2566:
2567: All non-regular files are hard-linked (when possible).
2568:
2569: 0. `--link-by-hash=DIR`
2570:
2571: This option hard links the destination files into `DIR`, a link farm
2572: arranged by MD5 file hash. The result is that the system will only store
2573: (usually) one copy of the unique contents of each file, regardless of the
2574: file's name (it will use extra files if the links overflow the available
2575: maximum).
2576:
2577: This patch does not take into account file permissions, extended
2578: attributes, or ACLs when linking things together, so you should only use
2579: this if you don't care about preserving those extra file attributes (or if
2580: they are always the same for identical files).
2581:
2582: The DIR is relative to the destination directory, so either specify a full
2583: path to the hash hierarchy, or specify a relative path that puts the links
2584: outside the destination (e.g. "../links").
2585:
2586: Keep in mind that the hierarchy is never pruned, so if you need to reclaim
2587: space, you should remove any files that have just one link (since they are
2588: not linked into any destination dirs anymore):
2589:
2590: > find $DIR -links 1 -delete
2591:
2592: The link farm's directory hierarchy is determined by the file's (32-char)
2593: MD5 hash and the file-length. The hash is split up into directory shards.
2594: For example, if a file is 54321 bytes long, it could be stored like this:
2595:
2596: > $DIR/123/456/789/01234567890123456789012.54321.0
2597:
2598: Note that the directory layout in this patch was modified for version
2599: 3.1.0, so anyone using an older version of this patch should move their
2600: existing link hierarchy out of the way and then use the newer rsync to copy
2601: the saved hierarchy into its new layout. Assuming that no files have
2602: overflowed their link limits, this would work:
2603:
2604: > mv $DIR $DIR.old
2605: > rsync -aiv --link-by-hash=$DIR $DIR.old/ $DIR.tmp/
2606: > rm -rf $DIR.tmp
2607: > rm -rf $DIR.old
2608:
2609: If some of your files are at their link limit, you'd be better of using a
2610: script to calculate the md5 sum of each file in the hierarchy and move it
2611: to its new location.
2612:
2613: 0. `--compress`, `-z`
2614:
2615: With this option, rsync compresses the file data as it is sent to the
2616: destination machine, which reduces the amount of data being transmitted --
2617: something that is useful over a slow connection.
2618:
2619: Rsync supports multiple compression methods and will choose one for you
2620: unless you force the choice using the `--compress-choice` (`--zc`) option.
2621:
2622: Run `rsync --version` to see the default compress list compiled into your
2623: version.
2624:
2625: When both sides of the transfer are at least 3.2.0, rsync chooses the first
2626: algorithm in the client's list of choices that is also in the server's list
2627: of choices. If no common compress choice is found, rsync exits with
2628: an error. If the remote rsync is too old to support checksum negotiation,
2629: its list is assumed to be "zlib".
2630:
2631: The default order can be customized by setting the environment variable
2632: RSYNC_COMPRESS_LIST to a space-separated list of acceptable compression
2633: names. If the string contains a "`&`" character, it is separated into the
2634: "client string & server string", otherwise the same string applies to both.
2635: If the string (or string portion) contains no
2636: non-whitespace characters, the default compress list is used. Any unknown
2637: compression names are discarded from the list, but a list with only invalid
2638: names results in a failed negotiation.
2639:
2640: There are some older rsync versions that were configured to reject a `-z`
2641: option and require the use of `-zz` because their compression library was
2642: not compatible with the default zlib compression method. You can usually
2643: ignore this weirdness unless the rsync server complains and tells you to
2644: specify `-zz`.
2645:
2646: See also the `--skip-compress` option for the default list of file suffixes
2647: that will be transferred with no (or minimal) compression.
2648:
2649: 0. `--compress-choice=STR`, `--zc=STR`
2650:
2651: This option can be used to override the automatic negotiation of the
2652: compression algorithm that occurs when `--compress` is used. The option
2653: implies `--compress` unless "none" was specified, which instead implies
2654: `--no-compress`.
2655:
2656: The compression options that you may be able to use are:
2657:
2658: - `zstd`
2659: - `lz4`
2660: - `zlibx`
2661: - `zlib`
2662: - `none`
2663:
2664: Run `rsync --version` to see the default compress list compiled into your
2665: version (which may differ from the list above).
2666:
2667: Note that if you see an error about an option named `--old-compress` or
2668: `--new-compress`, this is rsync trying to send the `--compress-choice=zlib`
2669: or `--compress-choice=zlibx` option in a backward-compatible manner that
2670: more rsync versions understand. This error indicates that the older rsync
2671: version on the server will not allow you to force the compression type.
2672:
2673: Note that the "zlibx" compression algorithm is just the "zlib" algorithm
2674: with matched data excluded from the compression stream (to try to make it
2675: more compatible with an external zlib implementation).
2676:
2677: 0. `--compress-level=NUM`, `--zl=NUM`
2678:
2679: Explicitly set the compression level to use (see `--compress`, `-z`)
2680: instead of letting it default. The `--compress` option is implied as long
2681: as the level chosen is not a "don't compress" level for the compression
2682: algorithm that is in effect (e.g. zlib compression treats level 0 as
2683: "off").
2684:
2685: The level values vary depending on the checksum in effect. Because rsync
2686: will negotiate a checksum choice by default (when the remote rsync is new
2687: enough), it can be good to combine this option with a `--compress-choice`
2688: (`--zc`) option unless you're sure of the choice in effect. For example:
2689:
2690: > rsync -aiv --zc=zstd --zl=22 host:src/ dest/
2691:
2692: For zlib & zlibx compression the valid values are from 1 to 9 with 6 being
2693: the default. Specifying 0 turns compression off, and specifying -1 chooses
2694: the default of 6.
2695:
2696: For zstd compression the valid values are from -131072 to 22 with 3 being
2697: the default. Specifying 0 chooses the default of 3.
2698:
2699: For lz4 compression there are no levels, so the value is always 0.
2700:
2701: If you specify a too-large or too-small value, the number is silently
2702: limited to a valid value. This allows you to specify something like
2703: `--zl=999999999` and be assured that you'll end up with the maximum
2704: compression level no matter what algorithm was chosen.
2705:
2706: If you want to know the compression level that is in effect, specify
2707: `--debug=nstr` to see the "negotiated string" results. This will report
2708: something like "`Client compress: zstd (level 3)`" (along with the checksum
2709: choice in effect).
2710:
2711: 0. `--skip-compress=LIST`
2712:
2713: Override the list of file suffixes that will be compressed as little as
2714: possible. Rsync sets the compression level on a per-file basis based on
2715: the file's suffix. If the compression algorithm has an "off" level (such
2716: as zlib/zlibx) then no compression occurs for those files. Other
2717: algorithms that support changing the streaming level on-the-fly will have
2718: the level minimized to reduces the CPU usage as much as possible for a
2719: matching file. At this time, only zlib & zlibx compression support this
2720: changing of levels on a per-file basis.
2721:
2722: The **LIST** should be one or more file suffixes (without the dot) separated
2723: by slashes (`/`). You may specify an empty string to indicate that no files
2724: should be skipped.
2725:
2726: Simple character-class matching is supported: each must consist of a list
2727: of letters inside the square brackets (e.g. no special classes, such as
2728: "[:alpha:]", are supported, and '-' has no special meaning).
2729:
2730: The characters asterisk (`*`) and question-mark (`?`) have no special meaning.
2731:
2732: Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules
2733: matches 2 suffixes):
2734:
2735: > --skip-compress=gz/jpg/mp[34]/7z/bz2
2736:
2737: The default file suffixes in the skip-compress list in this version of
2738: rsync are:
2739:
2740: [comment]: # (This list gets used for the default-dont-compress.h file.)
2741:
2742: > 3g2
2743: > 3gp
2744: > 7z
2745: > aac
2746: > ace
2747: > apk
2748: > avi
2749: > bz2
2750: > deb
2751: > dmg
2752: > ear
2753: > f4v
2754: > flac
2755: > flv
2756: > gpg
2757: > gz
2758: > iso
2759: > jar
2760: > jpeg
2761: > jpg
2762: > lrz
2763: > lz
2764: > lz4
2765: > lzma
2766: > lzo
2767: > m1a
2768: > m1v
2769: > m2a
2770: > m2ts
2771: > m2v
2772: > m4a
2773: > m4b
2774: > m4p
2775: > m4r
2776: > m4v
2777: > mka
2778: > mkv
2779: > mov
2780: > mp1
2781: > mp2
2782: > mp3
2783: > mp4
2784: > mpa
2785: > mpeg
2786: > mpg
2787: > mpv
2788: > mts
2789: > odb
2790: > odf
2791: > odg
2792: > odi
2793: > odm
2794: > odp
2795: > ods
2796: > odt
2797: > oga
2798: > ogg
2799: > ogm
2800: > ogv
2801: > ogx
2802: > opus
2803: > otg
2804: > oth
2805: > otp
2806: > ots
2807: > ott
2808: > oxt
2809: > png
2810: > qt
2811: > rar
2812: > rpm
2813: > rz
2814: > rzip
2815: > spx
2816: > squashfs
2817: > sxc
2818: > sxd
2819: > sxg
2820: > sxm
2821: > sxw
2822: > sz
2823: > tbz
2824: > tbz2
2825: > tgz
2826: > tlz
2827: > ts
2828: > txz
2829: > tzo
2830: > vob
2831: > war
2832: > webm
2833: > webp
2834: > xz
2835: > z
2836: > zip
2837: > zst
2838:
2839: This list will be replaced by your `--skip-compress` list in all but one
2840: situation: a copy from a daemon rsync will add your skipped suffixes to its
2841: list of non-compressing files (and its list may be configured to a
2842: different default).
2843:
2844: 0. `--numeric-ids`
2845:
2846: With this option rsync will transfer numeric group and user IDs rather than
2847: using user and group names and mapping them at both ends.
2848:
2849: By default rsync will use the username and groupname to determine what
2850: ownership to give files. The special uid 0 and the special group 0 are
2851: never mapped via user/group names even if the `--numeric-ids` option is not
2852: specified.
2853:
2854: If a user or group has no name on the source system or it has no match on
2855: the destination system, then the numeric ID from the source system is used
2856: instead. See also the comments on the "`use chroot`" setting in the
2857: rsyncd.conf manpage for information on how the chroot setting affects
2858: rsync's ability to look up the names of the users and groups and what you
2859: can do about it.
2860:
2861: 0. `--usermap=STRING`, `--groupmap=STRING`
2862:
2863: These options allow you to specify users and groups that should be mapped
2864: to other values by the receiving side. The **STRING** is one or more
2865: **FROM**:**TO** pairs of values separated by commas. Any matching **FROM**
2866: value from the sender is replaced with a **TO** value from the receiver.
2867: You may specify usernames or user IDs for the **FROM** and **TO** values,
2868: and the **FROM** value may also be a wild-card string, which will be
2869: matched against the sender's names (wild-cards do NOT match against ID
2870: numbers, though see below for why a '`*`' matches everything). You may
2871: instead specify a range of ID numbers via an inclusive range: LOW-HIGH.
2872: For example:
2873:
2874: > --usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1:usr
2875:
2876: The first match in the list is the one that is used. You should specify
2877: all your user mappings using a single `--usermap` option, and/or all your
2878: group mappings using a single `--groupmap` option.
2879:
2880: Note that the sender's name for the 0 user and group are not transmitted to
2881: the receiver, so you should either match these values using a 0, or use the
2882: names in effect on the receiving side (typically "root"). All other
2883: **FROM** names match those in use on the sending side. All **TO** names
2884: match those in use on the receiving side.
2885:
2886: Any IDs that do not have a name on the sending side are treated as having
2887: an empty name for the purpose of matching. This allows them to be matched
2888: via a "`*`" or using an empty name. For instance:
2889:
2890: > --usermap=:nobody --groupmap=*:nobody
2891:
2892: When the `--numeric-ids` option is used, the sender does not send any
2893: names, so all the IDs are treated as having an empty name. This means that
2894: you will need to specify numeric **FROM** values if you want to map these
2895: nameless IDs to different values.
2896:
2897: For the `--usermap` option to have any effect, the `-o` (`--owner`) option
2898: must be used (or implied), and the receiver will need to be running as a
2899: super-user (see also the `--fake-super` option). For the `--groupmap`
2900: option to have any effect, the `-g` (`--groups`) option must be used (or
2901: implied), and the receiver will need to have permissions to set that group.
2902:
2903: If your shell complains about the wildcards, use `--protect-args` (`-s`).
2904:
2905: 0. `--chown=USER:GROUP`
2906:
2907: This option forces all files to be owned by USER with group GROUP. This is
2908: a simpler interface than using `--usermap` and `--groupmap` directly, but
2909: it is implemented using those options internally, so you cannot mix them.
2910: If either the USER or GROUP is empty, no mapping for the omitted user/group
2911: will occur. If GROUP is empty, the trailing colon may be omitted, but if
2912: USER is empty, a leading colon must be supplied.
2913:
2914: If you specify "`--chown=foo:bar`", this is exactly the same as specifying
2915: "`--usermap=*:foo --groupmap=*:bar`", only easier. If your shell complains
2916: about the wildcards, use `--protect-args` (`-s`).
2917:
2918: To change ownership of files matching a pattern, use an include filter with
2919: a `o` or `g` modifier, which take effect before uid/gid mapping and
2920: therefore *can* be mixed with `--usermap` and `--groupmap`.
2921:
2922: 0. `--timeout=SECONDS`
2923:
2924: This option allows you to set a maximum I/O timeout in seconds. If no data
2925: is transferred for the specified time then rsync will exit. The default is
2926: 0, which means no timeout.
2927:
2928: 0. `--contimeout=SECONDS`
2929:
2930: This option allows you to set the amount of time that rsync will wait for
2931: its connection to an rsync daemon to succeed. If the timeout is reached,
2932: rsync exits with an error.
2933:
2934: 0. `--address=ADDRESS`
2935:
2936: By default rsync will bind to the wildcard address when connecting to an
2937: rsync daemon. The `--address` option allows you to specify a specific IP
2938: address (or hostname) to bind to. See also this option in the `--daemon`
2939: mode section.
2940:
2941: 0. `--port=PORT`
2942:
2943: This specifies an alternate TCP port number to use rather than the default
2944: of 873. This is only needed if you are using the double-colon (::) syntax
2945: to connect with an rsync daemon (since the URL syntax has a way to specify
2946: the port as a part of the URL). See also this option in the `--daemon`
2947: mode section.
2948:
2949: 0. `--sockopts=OPTIONS`
2950:
2951: This option can provide endless fun for people who like to tune their
2952: systems to the utmost degree. You can set all sorts of socket options
2953: which may make transfers faster (or slower!). Read the man page for the
2954: `setsockopt()` system call for details on some of the options you may be
2955: able to set. By default no special socket options are set. This only
2956: affects direct socket connections to a remote rsync daemon.
2957:
2958: This option also exists in the `--daemon` mode section.
2959:
2960: 0. `--blocking-io`
2961:
2962: This tells rsync to use blocking I/O when launching a remote shell
2963: transport. If the remote shell is either rsh or remsh, rsync defaults to
2964: using blocking I/O, otherwise it defaults to using non-blocking I/O. (Note
2965: that ssh prefers non-blocking I/O.)
2966:
2967: 0. `--outbuf=MODE`
2968:
2969: This sets the output buffering mode. The mode can be None (aka
2970: Unbuffered), Line, or Block (aka Full). You may specify as little as a
2971: single letter for the mode, and use upper or lower case.
2972:
2973: The main use of this option is to change Full buffering to Line buffering
2974: when rsync's output is going to a file or pipe.
2975:
2976: 0. `--itemize-changes`, `-i`
2977:
2978: Requests a simple itemized list of the changes that are being made to each
2979: file, including attribute changes. This is exactly the same as specifying
2980: `--out-format='%i %n%L'`. If you repeat the option, unchanged files will
2981: also be output, but only if the receiving rsync is at least version 2.6.7
2982: (you can use `-vv` with older versions of rsync, but that also turns on the
2983: output of other verbose messages).
2984:
2985: The "%i" escape has a cryptic output that is 11 letters long. The general
2986: format is like the string `YXcstpoguaxf`, where **Y** is replaced by the type
2987: of update being done, **X** is replaced by the file-type, and the other
2988: letters represent attributes that may be output if they are being modified.
2989:
2990: The update types that replace the **Y** are as follows:
2991:
2992: - A `<` means that a file is being transferred to the remote host (sent).
2993: - A `>` means that a file is being transferred to the local host
2994: (received).
2995: - A `c` means that a local change/creation is occurring for the item (such
2996: as the creation of a directory or the changing of a symlink, etc.).
2997: - A `h` means that the item is a hard link to another item (requires
2998: `--hard-links`).
2999: - A `.` means that the item is not being updated (though it might have
3000: attributes that are being modified).
3001: - A `*` means that the rest of the itemized-output area contains a message
3002: (e.g. "deleting").
3003:
3004: The file-types that replace the **X** are: `f` for a file, a `d` for a
3005: directory, an `L` for a symlink, a `D` for a device, and a `S` for a
3006: special file (e.g. named sockets and fifos).
3007:
3008: The other letters in the string indicate if some attributes of the file
3009: have changed, as follows:
3010:
3011: - "`.`" - the attribute is unchanged.
3012: - "`+`" - the file is newly created.
3013: - "` `" - all the attributes are unchanged (all dots turn to spaces).
3014: - "`?`" - the change is unknown (when the remote rsync is old).
3015: - A letter indicates an attribute is being updated.
3016:
3017: The attribute that is associated with each letter is as follows:
3018:
3019: - A `c` means either that a regular file has a different checksum (requires
3020: `--checksum`) or that a symlink, device, or special file has a changed
3021: value. Note that if you are sending files to an rsync prior to 3.0.1,
3022: this change flag will be present only for checksum-differing regular
3023: files.
3024: - A `s` means the size of a regular file is different and will be updated
3025: by the file transfer.
3026: - A `t` means the modification time is different and is being updated to
3027: the sender's value (requires `--times`). An alternate value of `T` means
3028: that the modification time will be set to the transfer time, which
3029: happens when a file/symlink/device is updated without `--times` and when
3030: a symlink is changed and the receiver can't set its time. (Note: when
3031: using an rsync 3.0.0 client, you might see the `s` flag combined with `t`
3032: instead of the proper `T` flag for this time-setting failure.)
3033: - A `p` means the permissions are different and are being updated to the
3034: sender's value (requires `--perms`).
3035: - An `o` means the owner is different and is being updated to the sender's
3036: value (requires `--owner` and super-user privileges).
3037: - A `g` means the group is different and is being updated to the sender's
3038: value (requires `--group` and the authority to set the group).
3039: - A `u`|`n`|`b` indicates the following information: `u` means the access
3040: (use) time is different and is being updated to the sender's value
3041: (requires `--atimes`); `n` means the create time (newness) is different
3042: and is being updated to the sender's value (requires `--crtimes`); `b`
3043: means that both the access and create times are being updated.
3044: - The `a` means that the ACL information is being changed.
3045: - The `x` means that the extended attribute information is being changed.
3046:
3047: One other output is possible: when deleting files, the "%i" will output the
3048: string "`*deleting`" for each item that is being removed (assuming that you
3049: are talking to a recent enough rsync that it logs deletions instead of
3050: outputting them as a verbose message).
3051:
3052: 0. `--out-format=FORMAT`
3053:
3054: This allows you to specify exactly what the rsync client outputs to the
3055: user on a per-update basis. The format is a text string containing
3056: embedded single-character escape sequences prefixed with a percent (%)
3057: character. A default format of "%n%L" is assumed if either `--info=name`
3058: or `-v` is specified (this tells you just the name of the file and, if the
3059: item is a link, where it points). For a full list of the possible escape
3060: characters, see the "`log format`" setting in the rsyncd.conf manpage.
3061:
3062: Specifying the `--out-format` option implies the `--info=name` option,
3063: which will mention each file, dir, etc. that gets updated in a significant
3064: way (a transferred file, a recreated symlink/device, or a touched
3065: directory). In addition, if the itemize-changes escape (%i) is included in
3066: the string (e.g. if the `--itemize-changes` option was used), the logging
3067: of names increases to mention any item that is changed in any way (as long
3068: as the receiving side is at least 2.6.4). See the `--itemize-changes`
3069: option for a description of the output of "%i".
3070:
3071: Rsync will output the out-format string prior to a file's transfer unless
3072: one of the transfer-statistic escapes is requested, in which case the
3073: logging is done at the end of the file's transfer. When this late logging
3074: is in effect and `--progress` is also specified, rsync will also output the
3075: name of the file being transferred prior to its progress information
3076: (followed, of course, by the out-format output).
3077:
3078: 0. `--log-file=FILE`
3079:
3080: This option causes rsync to log what it is doing to a file. This is
3081: similar to the logging that a daemon does, but can be requested for the
3082: client side and/or the server side of a non-daemon transfer. If specified
3083: as a client option, transfer logging will be enabled with a default format
3084: of "%i %n%L". See the `--log-file-format` option if you wish to override
3085: this.
3086:
3087: Here's a example command that requests the remote side to log what is
3088: happening:
3089:
3090: > rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/
3091:
3092: This is very useful if you need to debug why a connection is closing
3093: unexpectedly.
3094:
3095: 0. `--log-file-format=FORMAT`
3096:
3097: This allows you to specify exactly what per-update logging is put into the
3098: file specified by the `--log-file` option (which must also be specified for
3099: this option to have any effect). If you specify an empty string, updated
3100: files will not be mentioned in the log file. For a list of the possible
3101: escape characters, see the "`log format`" setting in the rsyncd.conf manpage.
3102:
3103: The default FORMAT used if `--log-file` is specified and this option is not
3104: is '%i %n%L'.
3105:
3106: 0. `--stats`
3107:
3108: This tells rsync to print a verbose set of statistics on the file transfer,
3109: allowing you to tell how effective rsync's delta-transfer algorithm is for
3110: your data. This option is equivalent to `--info=stats2` if combined with 0
3111: or 1 `-v` options, or `--info=stats3` if combined with 2 or more `-v`
3112: options.
3113:
3114: The current statistics are as follows:
3115:
3116: - `Number of files` is the count of all "files" (in the generic sense),
3117: which includes directories, symlinks, etc. The total count will be
3118: followed by a list of counts by filetype (if the total is non-zero). For
3119: example: "(reg: 5, dir: 3, link: 2, dev: 1, special: 1)" lists the totals
3120: for regular files, directories, symlinks, devices, and special files. If
3121: any of value is 0, it is completely omitted from the list.
3122: - `Number of created files` is the count of how many "files" (generic
3123: sense) were created (as opposed to updated). The total count will be
3124: followed by a list of counts by filetype (if the total is non-zero).
3125: - `Number of deleted files` is the count of how many "files" (generic
3126: sense) were created (as opposed to updated). The total count will be
3127: followed by a list of counts by filetype (if the total is non-zero).
3128: Note that this line is only output if deletions are in effect, and only
3129: if protocol 31 is being used (the default for rsync 3.1.x).
3130: - `Number of regular files transferred` is the count of normal files that
3131: were updated via rsync's delta-transfer algorithm, which does not include
3132: dirs, symlinks, etc. Note that rsync 3.1.0 added the word "regular" into
3133: this heading.
3134: - `Total file size` is the total sum of all file sizes in the transfer.
3135: This does not count any size for directories or special files, but does
3136: include the size of symlinks.
3137: - `Total transferred file size` is the total sum of all files sizes for
3138: just the transferred files.
3139: - `Literal data` is how much unmatched file-update data we had to send to
3140: the receiver for it to recreate the updated files.
3141: - `Matched data` is how much data the receiver got locally when recreating
3142: the updated files.
3143: - `File list size` is how big the file-list data was when the sender sent
3144: it to the receiver. This is smaller than the in-memory size for the file
3145: list due to some compressing of duplicated data when rsync sends the
3146: list.
3147: - `File list generation time` is the number of seconds that the sender
3148: spent creating the file list. This requires a modern rsync on the
3149: sending side for this to be present.
3150: - `File list transfer time` is the number of seconds that the sender spent
3151: sending the file list to the receiver.
3152: - `Total bytes sent` is the count of all the bytes that rsync sent from the
3153: client side to the server side.
3154: - `Total bytes received` is the count of all non-message bytes that rsync
3155: received by the client side from the server side. "Non-message" bytes
3156: means that we don't count the bytes for a verbose message that the server
3157: sent to us, which makes the stats more consistent.
3158:
3159: 0. `--8-bit-output`, `-8`
3160:
3161: This tells rsync to leave all high-bit characters unescaped in the output
3162: instead of trying to test them to see if they're valid in the current
3163: locale and escaping the invalid ones. All control characters (but never
3164: tabs) are always escaped, regardless of this option's setting.
3165:
3166: The escape idiom that started in 2.6.7 is to output a literal backslash
3167: (`\`) and a hash (`#`), followed by exactly 3 octal digits. For example, a
3168: newline would output as "`\#012`". A literal backslash that is in a
3169: filename is not escaped unless it is followed by a hash and 3 digits (0-9).
3170:
3171: 0. `--human-readable`, `-h`
3172:
3173: Output numbers in a more human-readable format. There are 3 possible
3174: levels: (1) output numbers with a separator between each set of 3 digits
3175: (either a comma or a period, depending on if the decimal point is
3176: represented by a period or a comma); (2) output numbers in units of 1000
3177: (with a character suffix for larger units -- see below); (3) output
3178: numbers in units of 1024.
3179:
3180: The default is human-readable level 1. Each `-h` option increases the
3181: level by one. You can take the level down to 0 (to output numbers as pure
3182: digits) by specifying the `--no-human-readable` (`--no-h`) option.
3183:
3184: The unit letters that are appended in levels 2 and 3 are: `K` (kilo), `M`
3185: (mega), `G` (giga), `T` (tera), or `P` (peta). For example, a 1234567-byte
3186: file would output as 1.23M in level-2 (assuming that a period is your local
3187: decimal point).
3188:
3189: Backward compatibility note: versions of rsync prior to 3.1.0 do not
3190: support human-readable level 1, and they default to level 0. Thus,
3191: specifying one or two `-h` options will behave in a comparable manner in
3192: old and new versions as long as you didn't specify a `--no-h` option prior
3193: to one or more `-h` options. See the `--list-only` option for one
3194: difference.
3195:
3196: 0. `--partial`
3197:
3198: By default, rsync will delete any partially transferred file if the
3199: transfer is interrupted. In some circumstances it is more desirable to
3200: keep partially transferred files. Using the `--partial` option tells rsync
3201: to keep the partial file which should make a subsequent transfer of the
3202: rest of the file much faster.
3203:
3204: 0. `--partial-dir=DIR`
3205:
3206: A better way to keep partial files than the `--partial` option is to
3207: specify a _DIR_ that will be used to hold the partial data (instead of
3208: writing it out to the destination file). On the next transfer, rsync will
3209: use a file found in this dir as data to speed up the resumption of the
3210: transfer and then delete it after it has served its purpose.
3211:
3212: Note that if `--whole-file` is specified (or implied), any partial-dir file
3213: that is found for a file that is being updated will simply be removed
3214: (since rsync is sending files without using rsync's delta-transfer
3215: algorithm).
3216:
3217: Rsync will create the _DIR_ if it is missing (just the last dir -- not the
3218: whole path). This makes it easy to use a relative path (such as
3219: "`--partial-dir=.rsync-partial`") to have rsync create the
3220: partial-directory in the destination file's directory when needed, and then
3221: remove it again when the partial file is deleted. Note that the directory
3222: is only removed if it is a relative pathname, as it is expected that an
3223: absolute path is to a directory that is reserved for partial-dir work.
3224:
3225: If the partial-dir value is not an absolute path, rsync will add an exclude
3226: rule at the end of all your existing excludes. This will prevent the
3227: sending of any partial-dir files that may exist on the sending side, and
3228: will also prevent the untimely deletion of partial-dir items on the
3229: receiving side. An example: the above `--partial-dir` option would add the
3230: equivalent of "`-f '-p .rsync-partial/'`" at the end of any other filter
3231: rules.
3232:
3233: If you are supplying your own exclude rules, you may need to add your own
3234: exclude/hide/protect rule for the partial-dir because (1) the auto-added
3235: rule may be ineffective at the end of your other rules, or (2) you may wish
3236: to override rsync's exclude choice. For instance, if you want to make
3237: rsync clean-up any left-over partial-dirs that may be lying around, you
3238: should specify `--delete-after` and add a "risk" filter rule, e.g.
3239: `-f 'R .rsync-partial/'`. (Avoid using `--delete-before` or
3240: `--delete-during` unless you don't need rsync to use any of the left-over
3241: partial-dir data during the current run.)
3242:
3243: IMPORTANT: the `--partial-dir` should not be writable by other users or it
3244: is a security risk. E.g. AVOID "/tmp".
3245:
3246: You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
3247: variable. Setting this in the environment does not force `--partial` to be
3248: enabled, but rather it affects where partial files go when `--partial` is
3249: specified. For instance, instead of using `--partial-dir=.rsync-tmp` along
3250: with `--progress`, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
3251: environment and then just use the `-P` option to turn on the use of the
3252: .rsync-tmp dir for partial transfers. The only times that the `--partial`
3253: option does not look for this environment value are (1) when `--inplace`
3254: was specified (since `--inplace` conflicts with `--partial-dir`), and (2)
3255: when `--delay-updates` was specified (see below).
3256:
3257: When a modern rsync resumes the transfer of a file in the partial-dir, that
3258: partial file is now updated in-place instead of creating yet another
3259: tmp-file copy (so it maxes out at dest + tmp instead of dest + partial +
3260: tmp). This requires both ends of the transfer to be at least version
3261: 3.2.0.
3262:
3263: For the purposes of the daemon-config's "`refuse options`" setting,
3264: `--partial-dir` does _not_ imply `--partial`. This is so that a refusal of
3265: the `--partial` option can be used to disallow the overwriting of
3266: destination files with a partial transfer, while still allowing the safer
3267: idiom provided by `--partial-dir`.
3268:
3269: 0. `--delay-updates`
3270:
3271: This option puts the temporary file from each updated file into a holding
3272: directory until the end of the transfer, at which time all the files are
3273: renamed into place in rapid succession. This attempts to make the updating
3274: of the files a little more atomic. By default the files are placed into a
3275: directory named `.~tmp~` in each file's destination directory, but if
3276: you've specified the `--partial-dir` option, that directory will be used
3277: instead. See the comments in the `--partial-dir` section for a discussion
3278: of how this `.~tmp~` dir will be excluded from the transfer, and what you
3279: can do if you want rsync to cleanup old `.~tmp~` dirs that might be lying
3280: around. Conflicts with `--inplace` and `--append`.
3281:
3282: This option implies `--no-inc-recursive` since it needs the full file list
3283: in memory in order to be able to iterate over it at the end.
3284:
3285: This option uses more memory on the receiving side (one bit per file
3286: transferred) and also requires enough free disk space on the receiving side
3287: to hold an additional copy of all the updated files. Note also that you
3288: should not use an absolute path to `--partial-dir` unless (1) there is no
3289: chance of any of the files in the transfer having the same name (since all
3290: the updated files will be put into a single directory if the path is
3291: absolute) and (2) there are no mount points in the hierarchy (since the
3292: delayed updates will fail if they can't be renamed into place).
3293:
3294: See also the "atomic-rsync" perl script in the "support" subdir for an
3295: update algorithm that is even more atomic (it uses `--link-dest` and a
3296: parallel hierarchy of files).
3297:
3298: 0. `--direct-io`
3299:
3300: This option opens files with a direct-I/O flag that makes the file I/O
3301: avoid the buffer cache. The option only affects one side of the transfer
3302: (unless the transfer is local). If you want it to affect both sides, use
3303: the `--remote-option` (`-M`) option to specify it for the remote side. For
3304: instance, this specifies it for both sides:
3305:
3306: > rsync -av {,-M}--direct-io /src/ host:/dest/
3307:
3308: 0. `--prune-empty-dirs`, `-m`
3309:
3310: This option tells the receiving rsync to get rid of empty directories from
3311: the file-list, including nested directories that have no non-directory
3312: children. This is useful for avoiding the creation of a bunch of useless
3313: directories when the sending rsync is recursively scanning a hierarchy of
3314: files using include/exclude/filter rules.
3315:
3316: Note that the use of transfer rules, such as the `--min-size` option, does
3317: not affect what goes into the file list, and thus does not leave
3318: directories empty, even if none of the files in a directory match the
3319: transfer rule.
3320:
3321: Because the file-list is actually being pruned, this option also affects
3322: what directories get deleted when a delete is active. However, keep in
3323: mind that excluded files and directories can prevent existing items from
3324: being deleted due to an exclude both hiding source files and protecting
3325: destination files. See the perishable filter-rule option for how to avoid
3326: this.
3327:
3328: You can prevent the pruning of certain empty directories from the file-list
3329: by using a global "protect" filter. For instance, this option would ensure
3330: that the directory "emptydir" was kept in the file-list:
3331:
3332: > --filter 'protect emptydir/'
3333:
3334: Here's an example that copies all .pdf files in a hierarchy, only creating
3335: the necessary destination directories to hold the .pdf files, and ensures
3336: that any superfluous files and directories in the destination are removed
3337: (note the hide filter of non-directories being used instead of an exclude):
3338:
3339: > rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest
3340:
3341: If you didn't want to remove superfluous destination files, the more
3342: time-honored options of `--include='*/' --exclude='*'` would work
3343: fine in place of the hide-filter (if that is more natural to you).
3344:
3345: 0. `--progress`
3346:
3347: This option tells rsync to print information showing the progress of the
3348: transfer. This gives a bored user something to watch. With a modern rsync
3349: this is the same as specifying `--info=flist2,name,progress`, but any
3350: user-supplied settings for those info flags takes precedence (e.g.
3351: "`--info=flist0 --progress`").
3352:
3353: While rsync is transferring a regular file, it updates a progress line that
3354: looks like this:
3355:
3356: > 782448 63% 110.64kB/s 0:00:04
3357:
3358: In this example, the receiver has reconstructed 782448 bytes or 63% of the
3359: sender's file, which is being reconstructed at a rate of 110.64 kilobytes
3360: per second, and the transfer will finish in 4 seconds if the current rate
3361: is maintained until the end.
3362:
3363: These statistics can be misleading if rsync's delta-transfer algorithm is
3364: in use. For example, if the sender's file consists of the basis file
3365: followed by additional data, the reported rate will probably drop
3366: dramatically when the receiver gets to the literal data, and the transfer
3367: will probably take much longer to finish than the receiver estimated as it
3368: was finishing the matched part of the file.
3369:
3370: When the file transfer finishes, rsync replaces the progress line with a
3371: summary line that looks like this:
3372:
3373: > 1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396)
3374:
3375: In this example, the file was 1,238,099 bytes long in total, the average
3376: rate of transfer for the whole file was 146.38 kilobytes per second over
3377: the 8 seconds that it took to complete, it was the 5th transfer of a
3378: regular file during the current rsync session, and there are 169 more files
3379: for the receiver to check (to see if they are up-to-date or not) remaining
3380: out of the 396 total files in the file-list.
3381:
3382: In an incremental recursion scan, rsync won't know the total number of
3383: files in the file-list until it reaches the ends of the scan, but since it
3384: starts to transfer files during the scan, it will display a line with the
3385: text "ir-chk" (for incremental recursion check) instead of "to-chk" until
3386: the point that it knows the full size of the list, at which point it will
3387: switch to using "to-chk". Thus, seeing "ir-chk" lets you know that the
3388: total count of files in the file list is still going to increase (and each
3389: time it does, the count of files left to check will increase by the number
3390: of the files added to the list).
3391:
3392: 0. `-P`
3393:
3394: The `-P` option is equivalent to `--partial --progress`. Its purpose is
3395: to make it much easier to specify these two options for a long transfer
3396: that may be interrupted.
3397:
3398: There is also a `--info=progress2` option that outputs statistics based on
3399: the whole transfer, rather than individual files. Use this flag without
3400: outputting a filename (e.g. avoid `-v` or specify `--info=name0`) if you
3401: want to see how the transfer is doing without scrolling the screen with a
3402: lot of names. (You don't need to specify the `--progress` option in order
3403: to use `--info=progress2`.)
3404:
3405: Finally, you can get an instant progress report by sending rsync a signal
3406: of either SIGINFO or SIGVTALRM. On BSD systems, a SIGINFO is generated by
3407: typing a Ctrl+T (Linux doesn't currently support a SIGINFO signal). When
3408: the client-side process receives one of those signals, it sets a flag to
3409: output a single progress report which is output when the current file
3410: transfer finishes (so it may take a little time if a big file is being
3411: handled when the signal arrives). A filename is output (if needed)
3412: followed by the `--info=progress2` format of progress info. If you don't
3413: know which of the 3 rsync processes is the client process, it's OK to
3414: signal all of them (since the non-client processes ignore the signal).
3415:
3416: CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it.
3417:
3418: 0. `--password-file=FILE`
3419:
3420: This option allows you to provide a password for accessing an rsync daemon
3421: via a file or via standard input if **FILE** is `-`. The file should
3422: contain just the password on the first line (all other lines are ignored).
3423: Rsync will exit with an error if **FILE** is world readable or if a
3424: root-run rsync command finds a non-root-owned file.
3425:
3426: This option does not supply a password to a remote shell transport such as
3427: ssh; to learn how to do that, consult the remote shell's documentation.
3428: When accessing an rsync daemon using a remote shell as the transport, this
3429: option only comes into effect after the remote shell finishes its
3430: authentication (i.e. if you have also specified a password in the daemon's
3431: config file).
3432:
3433: 0. `--early-input=FILE`
3434:
3435: This option allows rsync to send up to 5K of data to the "early exec"
3436: script on its stdin. One possible use of this data is to give the script a
3437: secret that can be used to mount an encrypted filesystem (which you should
3438: unmount in the the "post-xfer exec" script).
3439:
3440: The daemon must be at least version 3.2.1.
3441:
3442: 0. `--list-only`
3443:
3444: This option will cause the source files to be listed instead of
3445: transferred. This option is inferred if there is a single source arg and
3446: no destination specified, so its main uses are: (1) to turn a copy command
3447: that includes a destination arg into a file-listing command, or (2) to be
3448: able to specify more than one source arg (note: be sure to include the
3449: destination). Caution: keep in mind that a source arg with a wild-card is
3450: expanded by the shell into multiple args, so it is never safe to try to
3451: list such an arg without using this option. For example:
3452:
3453: > rsync -av --list-only foo* dest/
3454:
3455: Starting with rsync 3.1.0, the sizes output by `--list-only` are affected
3456: by the `--human-readable` option. By default they will contain digit
3457: separators, but higher levels of readability will output the sizes with
3458: unit suffixes. Note also that the column width for the size output has
3459: increased from 11 to 14 characters for all human-readable levels. Use
3460: `--no-h` if you want just digits in the sizes, and the old column width of
3461: 11 characters.
3462:
3463: Compatibility note: when requesting a remote listing of files from an rsync
3464: that is version 2.6.3 or older, you may encounter an error if you ask for a
3465: non-recursive listing. This is because a file listing implies the `--dirs`
3466: option w/o `--recursive`, and older rsyncs don't have that option. To
3467: avoid this problem, either specify the `--no-dirs` option (if you don't
3468: need to expand a directory's content), or turn on recursion and exclude the
3469: content of subdirectories: `-r --exclude='/*/*'`.
3470:
3471: 0. `--bwlimit=RATE`
3472:
3473: This option allows you to specify the maximum transfer rate for the data
3474: sent over the socket, specified in units per second. The RATE value can be
3475: suffixed with a string to indicate a size multiplier, and may be a
3476: fractional value (e.g. "`--bwlimit=1.5m`"). If no suffix is specified, the
3477: value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had
3478: been appended). See the `--max-size` option for a description of all the
3479: available suffixes. A value of 0 specifies no limit.
3480:
3481: For backward-compatibility reasons, the rate limit will be rounded to the
3482: nearest KiB unit, so no rate smaller than 1024 bytes per second is
3483: possible.
3484:
3485: Rsync writes data over the socket in blocks, and this option both limits
3486: the size of the blocks that rsync writes, and tries to keep the average
3487: transfer rate at the requested limit. Some burstiness may be seen where
3488: rsync writes out a block of data and then sleeps to bring the average rate
3489: into compliance.
3490:
3491: Due to the internal buffering of data, the `--progress` option may not be
3492: an accurate reflection on how fast the data is being sent. This is because
3493: some files can show up as being rapidly sent when the data is quickly
3494: buffered, while other can show up as very slow when the flushing of the
3495: output buffer occurs. This may be fixed in a future version.
3496:
3497: 0. `--stop-after=MINS
3498:
3499: This option tells rsync to stop copying when the specified number of
3500: minutes has elapsed.
3501:
3502: Rsync also accepts an earlier version of this option: `--time-limit=MINS`.
3503:
3504: For maximal flexibility, rsync does not communicate this option to the
3505: remote rsync since it is usually enough that one side of the connection
3506: quits as specified. This allows the option's use even when only one side
3507: of the connection supports it. You can tell the remote side about the time
3508: limit using `--remote-option` (`-M`), should the need arise.
3509:
3510: 0. `--stop-at=y-m-dTh:m
3511:
3512: This option tells rsync to stop copying when the specified point in time
3513: has been reached. The date & time can be fully specified in a numeric
3514: format of year-month-dayThour:minute (e.g. 2000-12-31T23:59) in the local
3515: timezone. You may choose to separate the date numbers using slashes
3516: instead of dashes.
3517:
3518: The value can also be abbreviated in a variety of ways, such as specifying
3519: a 2-digit year and/or leaving off various values. In all cases, the value
3520: will be taken to be the next possible point in time where the supplied
3521: information matches. If the value specifies the current time or a past
3522: time, rsync exits with an error.
3523:
3524: For example, "1-30" specifies the next January 30th (at midnight local
3525: time), "14:00" specifies the next 2 P.M., "1" specifies the next 1st of the
3526: month at midnight, "31" specifies the next month where we can stop on its
3527: 31st day, and ":59" specifies the next 59th minute after the hour.
3528:
3529: For maximal flexibility, rsync does not communicate this option to the
3530: remote rsync since it is usually enough that one side of the connection
3531: quits as specified. This allows the option's use even when only one side
3532: of the connection supports it. You can tell the remote side about the time
3533: limit using `--remote-option` (`-M`), should the need arise. Do keep in
3534: mind that the remote host may have a different default timezone than your
3535: local host.
3536:
3537: 0. `--write-batch=FILE`
3538:
3539: Record a file that can later be applied to another identical destination
3540: with `--read-batch`. See the "BATCH MODE" section for details, and also
3541: the `--only-write-batch` option.
3542:
3543: This option overrides the negotiated checksum & compress lists and always
3544: negotiates a choice based on old-school md5/md4/zlib choices. If you want
3545: a more modern choice, use the `--checksum-choice` (`--cc`) and/or
3546: `--compress-choice` (`--zc`) options.
3547:
3548: 0. `--only-write-batch=FILE`
3549:
3550: Works like `--write-batch`, except that no updates are made on the
3551: destination system when creating the batch. This lets you transport the
3552: changes to the destination system via some other means and then apply the
3553: changes via `--read-batch`.
3554:
3555: Note that you can feel free to write the batch directly to some portable
3556: media: if this media fills to capacity before the end of the transfer, you
3557: can just apply that partial transfer to the destination and repeat the
3558: whole process to get the rest of the changes (as long as you don't mind a
3559: partially updated destination system while the multi-update cycle is
3560: happening).
3561:
3562: Also note that you only save bandwidth when pushing changes to a remote
3563: system because this allows the batched data to be diverted from the sender
3564: into the batch file without having to flow over the wire to the receiver
3565: (when pulling, the sender is remote, and thus can't write the batch).
3566:
3567: 0. `--read-batch=FILE`
3568:
3569: Apply all of the changes stored in FILE, a file previously generated by
3570: `--write-batch`. If _FILE_ is `-`, the batch data will be read from
3571: standard input. See the "BATCH MODE" section for details.
3572:
3573: 0. `--source-filter=COMMAND`
3574:
3575: This option allows the user to specify a filter program that will be
3576: applied to the contents of all transferred regular files before the data is
3577: sent to destination. COMMAND will receive the data on its standard input
3578: and it should write the filtered data to standard output. COMMAND should
3579: exit non-zero if it cannot process the data or if it encounters an error
3580: when writing the data to stdout.
3581:
3582: Example: `--source-filter="gzip -9"` will cause remote files to be
3583: compressed. Use of `--source-filter` automatically enables `--whole-file`.
3584: If your filter does not output the same number of bytes that it received on
3585: input, you should use `--times-only` to disable size and content checks on
3586: subsequent rsync runs.
3587:
3588: 0. `--dest-filter=COMMAND`
3589:
3590: This option allows you to specify a filter program that will be applied to
3591: the contents of all transferred regular files before the data is written to
3592: disk. COMMAND will receive the data on its standard input and it should
3593: write the filtered data to standard output. COMMAND should exit non-zero
3594: if it cannot process the data or if it encounters an error when writing the
3595: data to stdout.
3596:
3597: Example: --dest-filter="gzip -9" will cause remote files to be compressed.
3598: Use of --dest-filter automatically enables --whole-file. If your filter
3599: does not output the same number of bytes that it received on input, you
3600: should use --times-only to disable size and content checks on subsequent
3601: rsync runs.
3602:
3603: 0. `--protocol=NUM`
3604:
3605: Force an older protocol version to be used. This is useful for creating a
3606: batch file that is compatible with an older version of rsync. For
3607: instance, if rsync 2.6.4 is being used with the `--write-batch` option, but
3608: rsync 2.6.3 is what will be used to run the `--read-batch` option, you
3609: should use "--protocol=28" when creating the batch file to force the older
3610: protocol version to be used in the batch file (assuming you can't upgrade
3611: the rsync on the reading system).
3612:
3613: 0. `--iconv=CONVERT_SPEC`
3614:
3615: Rsync can convert filenames between character sets using this option.
3616: Using a CONVERT_SPEC of "." tells rsync to look up the default
3617: character-set via the locale setting. Alternately, you can fully specify
3618: what conversion to do by giving a local and a remote charset separated by a
3619: comma in the order `--iconv=LOCAL,REMOTE`, e.g. `--iconv=utf8,iso88591`.
3620: This order ensures that the option will stay the same whether you're
3621: pushing or pulling files. Finally, you can specify either `--no-iconv` or
3622: a CONVERT_SPEC of "-" to turn off any conversion. The default setting of
3623: this option is site-specific, and can also be affected via the RSYNC_ICONV
3624: environment variable.
3625:
3626: For a list of what charset names your local iconv library supports, you can
3627: run "`iconv --list`".
3628:
3629: If you specify the `--protect-args` option (`-s`), rsync will translate the
3630: filenames you specify on the command-line that are being sent to the remote
3631: host. See also the `--files-from` option.
3632:
3633: Note that rsync does not do any conversion of names in filter files
3634: (including include/exclude files). It is up to you to ensure that you're
3635: specifying matching rules that can match on both sides of the transfer.
3636: For instance, you can specify extra include/exclude rules if there are
3637: filename differences on the two sides that need to be accounted for.
3638:
3639: When you pass an `--iconv` option to an rsync daemon that allows it, the
3640: daemon uses the charset specified in its "charset" configuration parameter
3641: regardless of the remote charset you actually pass. Thus, you may feel
3642: free to specify just the local charset for a daemon transfer (e.g.
3643: `--iconv=utf8`).
3644:
3645: 0. `--tr=BAD/GOOD`
3646:
3647: Transliterates filenames on the receiver, after the iconv conversion (if
3648: any). This can be used to remove characters illegal on the destination
3649: filesystem. If you use this option, consider saving a "find . -ls" listing
3650: of the source in the destination to help you determine the original
3651: filenames in case of need.
3652:
3653: The argument consists of a string of characters to remove, optionally
3654: followed by a slash and a string of corresponding characters with which to
3655: replace them. The second string may be shorter, in which case any leftover
3656: characters in the first string are simply deleted. For example,
3657: `--tr=':\/!'` replaces colons with exclamation marks and deletes
3658: backslashes. Slashes cannot be transliterated because it would cause
3659: havoc.
3660:
3661: If the receiver is invoked over a remote shell, use `--protect-args` to
3662: stop the shell from interpreting any nasty characters in the argument.
3663:
3664: 0. `--ipv4`, `-4` or `--ipv6`, `-6`
3665:
3666: Tells rsync to prefer IPv4/IPv6 when creating sockets or running ssh. This
3667: affects sockets that rsync has direct control over, such as the outgoing
3668: socket when directly contacting an rsync daemon, as well as the forwarding
3669: of the `-4` or `-6` option to ssh when rsync can deduce that ssh is being
3670: used as the remote shell. For other remote shells you'll need to specify
3671: the "`--rsh SHELL -4`" option directly (or whatever ipv4/ipv6 hint options
3672: it uses).
3673:
3674: These options also exist in the `--daemon` mode section.
3675:
3676: If rsync was complied without support for IPv6, the `--ipv6` option will
3677: have no effect. The `rsync --version` output will contain "`no IPv6`" if
3678: is the case.
3679:
3680: 0. `--checksum-seed=NUM`
3681:
3682: Set the checksum seed to the integer NUM. This 4 byte checksum seed is
3683: included in each block and MD4 file checksum calculation (the more modern
3684: MD5 file checksums don't use a seed). By default the checksum seed is
3685: generated by the server and defaults to the current **time**(). This
3686: option is used to set a specific checksum seed, which is useful for
3687: applications that want repeatable block checksums, or in the case where the
3688: user wants a more random checksum seed. Setting NUM to 0 causes rsync to
3689: use the default of **time**() for checksum seed.
3690:
3691: # DAEMON OPTIONS
3692:
3693: The options allowed when starting an rsync daemon are as follows:
3694:
3695: 0. `--daemon`
3696:
3697: This tells rsync that it is to run as a daemon. The daemon you start
3698: running may be accessed using an rsync client using the `host::module` or
3699: `rsync://host/module/` syntax.
3700:
3701: If standard input is a socket then rsync will assume that it is being run
3702: via inetd, otherwise it will detach from the current terminal and become a
3703: background daemon. The daemon will read the config file (rsyncd.conf) on
3704: each connect made by a client and respond to requests accordingly. See the
3705: **rsyncd.conf**(5) man page for more details.
3706:
3707: 0. `--address=ADDRESS`
3708:
3709: By default rsync will bind to the wildcard address when run as a daemon
3710: with the `--daemon` option. The `--address` option allows you to specify a
3711: specific IP address (or hostname) to bind to. This makes virtual hosting
3712: possible in conjunction with the `--config` option. See also the "address"
3713: global option in the rsyncd.conf manpage.
3714:
3715: 0. `--bwlimit=RATE`
3716:
3717: This option allows you to specify the maximum transfer rate for the data
3718: the daemon sends over the socket. The client can still specify a smaller
3719: `--bwlimit` value, but no larger value will be allowed. See the client
3720: version of this option (above) for some extra details.
3721:
3722: 0. `--config=FILE`
3723:
3724: This specifies an alternate config file than the default. This is only
3725: relevant when `--daemon` is specified. The default is /etc/rsyncd.conf
3726: unless the daemon is running over a remote shell program and the remote
3727: user is not the super-user; in that case the default is rsyncd.conf in the
3728: current directory (typically $HOME).
3729:
3730: 0. `--dparam=OVERRIDE`, `-M`
3731:
3732: This option can be used to set a daemon-config parameter when starting up
3733: rsync in daemon mode. It is equivalent to adding the parameter at the end
3734: of the global settings prior to the first module's definition. The
3735: parameter names can be specified without spaces, if you so desire. For
3736: instance:
3737:
3738: > rsync --daemon -M pidfile=/path/rsync.pid
3739:
3740: 0. `--no-detach`
3741:
3742: When running as a daemon, this option instructs rsync to not detach itself
3743: and become a background process. This option is required when running as a
3744: service on Cygwin, and may also be useful when rsync is supervised by a
3745: program such as `daemontools` or AIX's `System Resource Controller`.
3746: `--no-detach` is also recommended when rsync is run under a debugger. This
3747: option has no effect if rsync is run from inetd or sshd.
3748:
3749: 0. `--port=PORT`
3750:
3751: This specifies an alternate TCP port number for the daemon to listen on
3752: rather than the default of 873. See also the "port" global option in the
3753: rsyncd.conf manpage.
3754:
3755: 0. `--log-file=FILE`
3756:
3757: This option tells the rsync daemon to use the given log-file name instead
3758: of using the "`log file`" setting in the config file.
3759:
3760: 0. `--log-file-format=FORMAT`
3761:
3762: This option tells the rsync daemon to use the given FORMAT string instead
3763: of using the "`log format`" setting in the config file. It also enables
3764: "`transfer logging`" unless the string is empty, in which case transfer
3765: logging is turned off.
3766:
3767: 0. `--sockopts`
3768:
3769: This overrides the `socket options` setting in the rsyncd.conf file and has
3770: the same syntax.
3771:
3772: 0. `--verbose`, `-v`
3773:
3774: This option increases the amount of information the daemon logs during its
3775: startup phase. After the client connects, the daemon's verbosity level
3776: will be controlled by the options that the client used and the
3777: "`max verbosity`" setting in the module's config section.
3778:
3779: 0. `--ipv4`, `-4` or `--ipv6`, `-6`
3780:
3781: Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the
3782: rsync daemon will use to listen for connections. One of these options may
3783: be required in older versions of Linux to work around an IPv6 bug in the
3784: kernel (if you see an "address already in use" error when nothing else is
3785: using the port, try specifying `--ipv6` or `--ipv4` when starting the
3786: daemon).
3787:
3788: These options also exist in the regular rsync options section.
3789:
3790: If rsync was complied without support for IPv6, the `--ipv6` option will
3791: have no effect. The `rsync --version` output will contain "`no IPv6`" if
3792: is the case.
3793:
3794: 0. `--help`, `-h`
3795:
3796: When specified after `--daemon`, print a short help page describing the
3797: options available for starting an rsync daemon.
3798:
3799: # FILTER RULES
3800:
3801: The filter rules allow for flexible selection of which files to transfer
3802: (include) and which files to skip (exclude). The rules either directly specify
3803: include/exclude patterns or they specify a way to acquire more include/exclude
3804: patterns (e.g. to read them from a file).
3805:
3806: As the list of files/directories to transfer is built, rsync checks each name
3807: to be transferred against the list of include/exclude patterns in turn, and the
3808: first matching pattern is acted on: if it is an exclude pattern, then that file
3809: is skipped; if it is an include pattern then that filename is not skipped; if
3810: no matching pattern is found, then the filename is not skipped.
3811:
3812: Rsync builds an ordered list of filter rules as specified on the command-line.
3813: Filter rules have the following syntax:
3814:
3815: > RULE [PATTERN_OR_FILENAME]
3816: > RULE,MODIFIERS [PATTERN_OR_FILENAME]
3817:
3818: You have your choice of using either short or long RULE names, as described
3819: below. If you use a short-named rule, the ',' separating the RULE from the
3820: MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
3821: must come after either a single space or an underscore (\_). Here are the
3822: available rule prefixes:
3823:
3824: 0. `exclude, '-'` specifies an exclude pattern.
3825: 0. `include, '+'` specifies an include pattern.
3826: 0. `merge, '.'` specifies a merge-file to read for more rules.
3827: 0. `dir-merge, ':'` specifies a per-directory merge-file.
3828: 0. `hide, 'H'` specifies a pattern for hiding files from the transfer.
3829: 0. `show, 'S'` files that match the pattern are not hidden.
3830: 0. `protect, 'P'` specifies a pattern for protecting files from deletion.
3831: 0. `risk, 'R'` files that match the pattern are not protected.
3832: 0. `clear, '!'` clears the current include/exclude list (takes no arg)
3833:
3834: When rules are being read from a file, empty lines are ignored, as are comment
3835: lines that start with a "#".
3836:
3837: [comment]: # (Remember that markdown strips spaces from start/end of ` ... ` sequences!)
3838: [comment]: # (Thus, the `x ` sequences below use a literal non-breakable space!)
3839:
3840: Note that the `--include` & `--exclude` command-line options do not allow the
3841: full range of rule parsing as described above -- they only allow the
3842: specification of include / exclude patterns plus a "`!`" token to clear the
3843: list (and the normal comment parsing when rules are read from a file). If a
3844: pattern does not begin with "`- `" (dash, space) or "`+ `" (plus, space), then
3845: the rule will be interpreted as if "`+ `" (for an include option) or "`- `"
3846: (for an exclude option) were prefixed to the string. A `--filter` option, on
3847: the other hand, must always contain either a short or long rule name at the
3848: start of the rule.
3849:
3850: Note also that the `--filter`, `--include`, and `--exclude` options take one
3851: rule/pattern each. To add multiple ones, you can repeat the options on the
3852: command-line, use the merge-file syntax of the `--filter` option, or the
3853: `--include-from` / `--exclude-from` options.
3854:
3855: # INCLUDE/EXCLUDE PATTERN RULES
3856:
3857: You can include and exclude files by specifying patterns using the "+", "-",
3858: etc. filter rules (as introduced in the FILTER RULES section above). The
3859: include/exclude rules each specify a pattern that is matched against the names
3860: of the files that are going to be transferred. These patterns can take several
3861: forms:
3862:
3863: - if the pattern starts with a `/` then it is anchored to a particular spot in
3864: the hierarchy of files, otherwise it is matched against the end of the
3865: pathname. This is similar to a leading `^` in regular expressions. Thus
3866: `/foo` would match a name of "foo" at either the "root of the transfer" (for
3867: a global rule) or in the merge-file's directory (for a per-directory rule).
3868: An unqualified `foo` would match a name of "foo" anywhere in the tree because
3869: the algorithm is applied recursively from the top down; it behaves as if each
3870: path component gets a turn at being the end of the filename. Even the
3871: unanchored "sub/foo" would match at any point in the hierarchy where a "foo"
3872: was found within a directory named "sub". See the section on ANCHORING
3873: INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify a pattern
3874: that matches at the root of the transfer.
3875: - if the pattern ends with a `/` then it will only match a directory, not a
3876: regular file, symlink, or device.
3877: - rsync chooses between doing a simple string match and wildcard matching by
3878: checking if the pattern contains one of these three wildcard characters:
3879: '`*`', '`?`', and '`[`' .
3880: - a '`*`' matches any path component, but it stops at slashes.
3881: - use '`**`' to match anything, including slashes.
3882: - a '`?`' matches any character except a slash (`/`).
3883: - a '`[`' introduces a character class, such as `[a-z]` or `[[:alpha:]]`.
3884: - in a wildcard pattern, a backslash can be used to escape a wildcard
3885: character, but it is matched literally when no wildcards are present. This
3886: means that there is an extra level of backslash removal when a pattern
3887: contains wildcard characters compared to a pattern that has none. e.g. if
3888: you add a wildcard to "`foo\bar`" (which matches the backslash) you would
3889: need to use "`foo\\bar*`" to avoid the "`\b`" becoming just "b".
3890: - if the pattern contains a `/` (not counting a trailing /) or a "`**`", then it
3891: is matched against the full pathname, including any leading directories. If
3892: the pattern doesn't contain a `/` or a "`**`", then it is matched only against
3893: the final component of the filename. (Remember that the algorithm is applied
3894: recursively so "full filename" can actually be any portion of a path from the
3895: starting directory on down.)
3896: - a trailing "`dir_name/***`" will match both the directory (as if "dir_name/"
3897: had been specified) and everything in the directory (as if "`dir_name/**`"
3898: had been specified). This behavior was added in version 2.6.7.
3899:
3900: Note that, when using the `--recursive` (`-r`) option (which is implied by
3901: `-a`), every subdir component of every path is visited left to right, with each
3902: directory having a chance for exclusion before its content. In this way
3903: include/exclude patterns are applied recursively to the pathname of each node
3904: in the filesystem's tree (those inside the transfer). The exclude patterns
3905: short-circuit the directory traversal stage as rsync finds the files to send.
3906:
3907: For instance, to include "`/foo/bar/baz`", the directories "`/foo`" and "`/foo/bar`"
3908: must not be excluded. Excluding one of those parent directories prevents the
3909: examination of its content, cutting off rsync's recursion into those paths and
3910: rendering the include for "`/foo/bar/baz`" ineffectual (since rsync can't match
3911: something it never sees in the cut-off section of the directory hierarchy).
3912:
3913: The concept path exclusion is particularly important when using a trailing '`*`'
3914: rule. For instance, this won't work:
3915:
3916: > + /some/path/this-file-will-not-be-found
3917: > + /file-is-included
3918: > - *
3919:
3920: This fails because the parent directory "some" is excluded by the '`*`' rule, so
3921: rsync never visits any of the files in the "some" or "some/path" directories.
3922: One solution is to ask for all directories in the hierarchy to be included by
3923: using a single rule: "`+ */`" (put it somewhere before the "`- *`" rule), and
3924: perhaps use the `--prune-empty-dirs` option. Another solution is to add
3925: specific include rules for all the parent dirs that need to be visited. For
3926: instance, this set of rules works fine:
3927:
3928: > + /some/
3929: > + /some/path/
3930: > + /some/path/this-file-is-found
3931: > + /file-also-included
3932: > - *
3933:
3934: Here are some examples of exclude/include matching:
3935:
3936: - "`- *.o`" would exclude all names matching `*.o`
3937: - "`- /foo`" would exclude a file (or directory) named foo in the transfer-root
3938: directory
3939: - "`- foo/`" would exclude any directory named foo
3940: - "`- /foo/*/bar`" would exclude any file named bar which is at two levels
3941: below a directory named foo in the transfer-root directory
3942: - "`- /foo/**/bar`" would exclude any file named bar two or more levels below a
3943: directory named foo in the transfer-root directory
3944: - The combination of "`+ */`", "`+ *.c`", and "`- *`" would include all
3945: directories and C source files but nothing else (see also the
3946: `--prune-empty-dirs` option)
3947: - The combination of "`+ foo/`", "`+ foo/bar.c`", and "`- *`" would include
3948: only the foo directory and foo/bar.c (the foo directory must be explicitly
3949: included or it would be excluded by the "`*`")
3950:
3951: The following modifiers are accepted after a "`+`" or "`-`":
3952:
3953: - A `/` specifies that the include/exclude rule should be matched against the
3954: absolute pathname of the current item. For example, "`-/ /etc/passwd`" would
3955: exclude the passwd file any time the transfer was sending files from the
3956: "/etc" directory, and "-/ subdir/foo" would always exclude "foo" when it is
3957: in a dir named "subdir", even if "foo" is at the root of the current
3958: transfer.
3959: - A `!` specifies that the include/exclude should take effect if the pattern
3960: fails to match. For instance, "`-! */`" would exclude all non-directories.
3961: - A `C` is used to indicate that all the global CVS-exclude rules should be
3962: inserted as excludes in place of the "-C". No arg should follow.
3963: - An `s` is used to indicate that the rule applies to the sending side. When a
3964: rule affects the sending side, it prevents files from being transferred. The
3965: default is for a rule to affect both sides unless `--delete-excluded` was
3966: specified, in which case default rules become sender-side only. See also the
3967: hide (H) and show (S) rules, which are an alternate way to specify
3968: sending-side includes/excludes.
3969: - An `r` is used to indicate that the rule applies to the receiving side. When
3970: a rule affects the receiving side, it prevents files from being deleted. See
3971: the `s` modifier for more info. See also the protect (P) and risk (R) rules,
3972: which are an alternate way to specify receiver-side includes/excludes.
3973: - A `p` indicates that a rule is perishable, meaning that it is ignored in
3974: directories that are being deleted. For instance, the `-C` option's default
3975: rules that exclude things like "CVS" and "`*.o`" are marked as perishable,
3976: and will not prevent a directory that was removed on the source from being
3977: deleted on the destination.
3978: - An `m(CHMOD)` on an include rule tweaks the permissions of matching
3979: source files in the same way as `--chmod`. This happens before any tweaks
3980: requested via `--chmod` options.
3981: - An `o(USER)` on an include rule pretends that matching source files are
3982: owned by `USER` (a name or numeric uid). This happens before any uid mapping
3983: by name or `--usermap`.
3984: - A `g(GROUP)` on an include rule pretends that matching source files are
3985: owned by `GROUP` (a name or numeric gid). This happens before any gid
3986: mapping by name or `--groupmap`.
3987: - An `x` indicates that a rule affects xattr names in xattr copy/delete
3988: operations (and is thus ignored when matching file/dir names). If no
3989: xattr-matching rules are specified, a default xattr filtering rule is used
3990: (see the `--xattrs` option).
3991:
3992: # MERGE-FILE FILTER RULES
3993:
3994: You can merge whole files into your filter rules by specifying either a merge
3995: (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES section
3996: above).
3997:
3998: There are two kinds of merged files -- single-instance ('.') and per-directory
3999: (':'). A single-instance merge file is read one time, and its rules are
4000: incorporated into the filter list in the place of the "." rule. For
4001: per-directory merge files, rsync will scan every directory that it traverses
4002: for the named file, merging its contents when the file exists into the current
4003: list of inherited rules. These per-directory rule files must be created on the
4004: sending side because it is the sending side that is being scanned for the
4005: available files to transfer. These rule files may also need to be transferred
4006: to the receiving side if you want them to affect what files don't get deleted
4007: (see PER-DIRECTORY RULES AND DELETE below).
4008:
4009: Some examples:
4010:
4011: > merge /etc/rsync/default.rules
4012: > . /etc/rsync/default.rules
4013: > dir-merge .per-dir-filter
4014: > dir-merge,n- .non-inherited-per-dir-excludes
4015: > :n- .non-inherited-per-dir-excludes
4016:
4017: The following modifiers are accepted after a merge or dir-merge rule:
4018:
4019: - A `-` specifies that the file should consist of only exclude patterns, with
4020: no other rule-parsing except for in-file comments.
4021: - A `+` specifies that the file should consist of only include patterns, with
4022: no other rule-parsing except for in-file comments.
4023: - A `C` is a way to specify that the file should be read in a CVS-compatible
4024: manner. This turns on 'n', 'w', and '-', but also allows the list-clearing
4025: token (!) to be specified. If no filename is provided, ".cvsignore" is
4026: assumed.
4027: - A `e` will exclude the merge-file name from the transfer; e.g. "dir-merge,e
4028: .rules" is like "dir-merge .rules" and "- .rules".
4029: - An `n` specifies that the rules are not inherited by subdirectories.
4030: - A `w` specifies that the rules are word-split on whitespace instead of the
4031: normal line-splitting. This also turns off comments. Note: the space that
4032: separates the prefix from the rule is treated specially, so "- foo + bar" is
4033: parsed as two rules (assuming that prefix-parsing wasn't also disabled).
4034: - You may also specify any of the modifiers for the "+" or "-" rules (above) in
4035: order to have the rules that are read in from the file default to having that
4036: modifier set (except for the `!` modifier, which would not be useful). For
4037: instance, "merge,-/ .excl" would treat the contents of .excl as absolute-path
4038: excludes, while "dir-merge,s .filt" and ":sC" would each make all their
4039: per-directory rules apply only on the sending side. If the merge rule
4040: specifies sides to affect (via the `s` or `r` modifier or both), then the
4041: rules in the file must not specify sides (via a modifier or a rule prefix
4042: such as `hide`).
4043:
4044: The attribute-affecting modifiers `m`, `o`, and `g` work only in client filters
4045: (not in daemon filters), and only the modifiers of the first matching rule are
4046: applied. As an example, assuming `--super` is enabled, the rule
4047: "`+o(root),g(root),m(go=) *~`" would ensure that all "backup"
4048: files belong to root and are not accessible to anyone else.
4049:
4050: Per-directory rules are inherited in all subdirectories of the directory where
4051: the merge-file was found unless the 'n' modifier was used. Each subdirectory's
4052: rules are prefixed to the inherited per-directory rules from its parents, which
4053: gives the newest rules a higher priority than the inherited rules. The entire
4054: set of dir-merge rules are grouped together in the spot where the merge-file
4055: was specified, so it is possible to override dir-merge rules via a rule that
4056: got specified earlier in the list of global rules. When the list-clearing rule
4057: ("!") is read from a per-directory file, it only clears the inherited rules for
4058: the current merge file.
4059:
4060: Another way to prevent a single rule from a dir-merge file from being inherited
4061: is to anchor it with a leading slash. Anchored rules in a per-directory
4062: merge-file are relative to the merge-file's directory, so a pattern "/foo"
4063: would only match the file "foo" in the directory where the dir-merge filter
4064: file was found.
4065:
4066: Here's an example filter file which you'd specify via `--filter=". file":`
4067:
4068: > merge /home/user/.global-filter
4069: > - *.gz
4070: > dir-merge .rules
4071: > + *.[ch]
4072: > - *.o
4073: > - foo*
4074:
4075: This will merge the contents of the /home/user/.global-filter file at the start
4076: of the list and also turns the ".rules" filename into a per-directory filter
4077: file. All rules read in prior to the start of the directory scan follow the
4078: global anchoring rules (i.e. a leading slash matches at the root of the
4079: transfer).
4080:
4081: If a per-directory merge-file is specified with a path that is a parent
4082: directory of the first transfer directory, rsync will scan all the parent dirs
4083: from that starting point to the transfer directory for the indicated
4084: per-directory file. For instance, here is a common filter (see `-F`):
4085:
4086: > --filter=': /.rsync-filter'
4087:
4088: That rule tells rsync to scan for the file .rsync-filter in all directories
4089: from the root down through the parent directory of the transfer prior to the
4090: start of the normal directory scan of the file in the directories that are sent
4091: as a part of the transfer. (Note: for an rsync daemon, the root is always the
4092: same as the module's "path".)
4093:
4094: Some examples of this pre-scanning for per-directory files:
4095:
4096: > rsync -avF /src/path/ /dest/dir
4097: > rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
4098: > rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir
4099:
4100: The first two commands above will look for ".rsync-filter" in "/" and "/src"
4101: before the normal scan begins looking for the file in "/src/path" and its
4102: subdirectories. The last command avoids the parent-dir scan and only looks for
4103: the ".rsync-filter" files in each directory that is a part of the transfer.
4104:
4105: If you want to include the contents of a ".cvsignore" in your patterns, you
4106: should use the rule ":C", which creates a dir-merge of the .cvsignore file, but
4107: parsed in a CVS-compatible manner. You can use this to affect where the
4108: `--cvs-exclude` (`-C`) option's inclusion of the per-directory .cvsignore file
4109: gets placed into your rules by putting the ":C" wherever you like in your
4110: filter rules. Without this, rsync would add the dir-merge rule for the
4111: .cvsignore file at the end of all your other rules (giving it a lower priority
4112: than your command-line rules). For example:
4113:
4114: > ```
4115: > cat <<EOT | rsync -avC --filter='. -' a/ b
4116: > + foo.o
4117: > :C
4118: > - *.old
4119: > EOT
4120: > rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
4121: > ```
4122:
4123: Both of the above rsync commands are identical. Each one will merge all the
4124: per-directory .cvsignore rules in the middle of the list rather than at the
4125: end. This allows their dir-specific rules to supersede the rules that follow
4126: the :C instead of being subservient to all your rules. To affect the other CVS
4127: exclude rules (i.e. the default list of exclusions, the contents of
4128: $HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the `-C`
4129: command-line option and instead insert a "-C" rule into your filter rules; e.g.
4130: "`--filter=-C`".
4131:
4132: # LIST-CLEARING FILTER RULE
4133:
4134: You can clear the current include/exclude list by using the "!" filter rule (as
4135: introduced in the FILTER RULES section above). The "current" list is either
4136: the global list of rules (if the rule is encountered while parsing the filter
4137: options) or a set of per-directory rules (which are inherited in their own
4138: sub-list, so a subdirectory can use this to clear out the parent's rules).
4139:
4140: # ANCHORING INCLUDE/EXCLUDE PATTERNS
4141:
4142: As mentioned earlier, global include/exclude patterns are anchored at the "root
4143: of the transfer" (as opposed to per-directory patterns, which are anchored at
4144: the merge-file's directory). If you think of the transfer as a subtree of
4145: names that are being sent from sender to receiver, the transfer-root is where
4146: the tree starts to be duplicated in the destination directory. This root
4147: governs where patterns that start with a / match.
4148:
4149: Because the matching is relative to the transfer-root, changing the trailing
4150: slash on a source path or changing your use of the `--relative` option affects
4151: the path you need to use in your matching (in addition to changing how much of
4152: the file tree is duplicated on the destination host). The following examples
4153: demonstrate this.
4154:
4155: Let's say that we want to match two source files, one with an absolute
4156: path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
4157: Here is how the various command choices differ for a 2-source transfer:
4158:
4159: > ```
4160: > Example cmd: rsync -a /home/me /home/you /dest
4161: > +/- pattern: /me/foo/bar
4162: > +/- pattern: /you/bar/baz
4163: > Target file: /dest/me/foo/bar
4164: > Target file: /dest/you/bar/baz
4165: > ```
4166:
4167: > ```
4168: > Example cmd: rsync -a /home/me/ /home/you/ /dest
4169: > +/- pattern: /foo/bar (note missing "me")
4170: > +/- pattern: /bar/baz (note missing "you")
4171: > Target file: /dest/foo/bar
4172: > Target file: /dest/bar/baz
4173: > ```
4174:
4175: > ```
4176: > Example cmd: rsync -a --relative /home/me/ /home/you /dest
4177: > +/- pattern: /home/me/foo/bar (note full path)
4178: > +/- pattern: /home/you/bar/baz (ditto)
4179: > Target file: /dest/home/me/foo/bar
4180: > Target file: /dest/home/you/bar/baz
4181: > ```
4182:
4183: > ```
4184: > Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
4185: > +/- pattern: /me/foo/bar (starts at specified path)
4186: > +/- pattern: /you/bar/baz (ditto)
4187: > Target file: /dest/me/foo/bar
4188: > Target file: /dest/you/bar/baz
4189: > ```
4190:
4191: The easiest way to see what name you should filter is to just
4192: look at the output when using `--verbose` and put a / in front of the name
4193: (use the `--dry-run` option if you're not yet ready to copy any files).
4194:
4195: # PER-DIRECTORY RULES AND DELETE
4196:
4197: Without a delete option, per-directory rules are only relevant on the sending
4198: side, so you can feel free to exclude the merge files themselves without
4199: affecting the transfer. To make this easy, the 'e' modifier adds this exclude
4200: for you, as seen in these two equivalent commands:
4201:
4202: > rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
4203: > rsync -av --filter=':e .excl' host:src/dir /dest
4204:
4205: However, if you want to do a delete on the receiving side AND you want some
4206: files to be excluded from being deleted, you'll need to be sure that the
4207: receiving side knows what files to exclude. The easiest way is to include the
4208: per-directory merge files in the transfer and use `--delete-after`, because
4209: this ensures that the receiving side gets all the same exclude rules as the
4210: sending side before it tries to delete anything:
4211:
4212: > rsync -avF --delete-after host:src/dir /dest
4213:
4214: However, if the merge files are not a part of the transfer, you'll need to
4215: either specify some global exclude rules (i.e. specified on the command line),
4216: or you'll need to maintain your own per-directory merge files on the receiving
4217: side. An example of the first is this (assume that the remote .rules files
4218: exclude themselves):
4219:
4220: > rsync -av --filter=': .rules' --filter='. /my/extra.rules'
4221: > --delete host:src/dir /dest
4222:
4223: In the above example the extra.rules file can affect both sides of the
4224: transfer, but (on the sending side) the rules are subservient to the rules
4225: merged from the .rules files because they were specified after the
4226: per-directory merge rule.
4227:
4228: In one final example, the remote side is excluding the .rsync-filter files from
4229: the transfer, but we want to use our own .rsync-filter files to control what
4230: gets deleted on the receiving side. To do this we must specifically exclude
4231: the per-directory merge files (so that they don't get deleted) and then put
4232: rules into the local files to control what else should not get deleted. Like
4233: one of these commands:
4234:
4235: > ```
4236: > rsync -av --filter=':e /.rsync-filter' --delete \
4237: > host:src/dir /dest
4238: > rsync -avFF --delete host:src/dir /dest
4239: > ```
4240:
4241: # BATCH MODE
4242:
4243: Batch mode can be used to apply the same set of updates to many identical
4244: systems. Suppose one has a tree which is replicated on a number of hosts. Now
4245: suppose some changes have been made to this source tree and those changes need
4246: to be propagated to the other hosts. In order to do this using batch mode,
4247: rsync is run with the write-batch option to apply the changes made to the
4248: source tree to one of the destination trees. The write-batch option causes the
4249: rsync client to store in a "batch file" all the information needed to repeat
4250: this operation against other, identical destination trees.
4251:
4252: Generating the batch file once saves having to perform the file status,
4253: checksum, and data block generation more than once when updating multiple
4254: destination trees. Multicast transport protocols can be used to transfer the
4255: batch update files in parallel to many hosts at once, instead of sending the
4256: same data to every host individually.
4257:
4258: To apply the recorded changes to another destination tree, run rsync with the
4259: read-batch option, specifying the name of the same batch file, and the
4260: destination tree. Rsync updates the destination tree using the information
4261: stored in the batch file.
4262:
4263: For your convenience, a script file is also created when the write-batch option
4264: is used: it will be named the same as the batch file with ".sh" appended. This
4265: script file contains a command-line suitable for updating a destination tree
4266: using the associated batch file. It can be executed using a Bourne (or
4267: Bourne-like) shell, optionally passing in an alternate destination tree
4268: pathname which is then used instead of the original destination path. This is
4269: useful when the destination tree path on the current host differs from the one
4270: used to create the batch file.
4271:
4272: Examples:
4273:
4274: > $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
4275: > $ scp foo* remote:
4276: > $ ssh remote ./foo.sh /bdest/dir/
4277:
4278: > $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
4279: > $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
4280:
4281: In these examples, rsync is used to update /adest/dir/ from /source/dir/ and
4282: the information to repeat this operation is stored in "foo" and "foo.sh". The
4283: host "remote" is then updated with the batched data going into the directory
4284: /bdest/dir. The differences between the two examples reveals some of the
4285: flexibility you have in how you deal with batches:
4286:
4287: - The first example shows that the initial copy doesn't have to be local -- you
4288: can push or pull data to/from a remote host using either the remote-shell
4289: syntax or rsync daemon syntax, as desired.
4290: - The first example uses the created "foo.sh" file to get the right rsync
4291: options when running the read-batch command on the remote host.
4292: - The second example reads the batch data via standard input so that the batch
4293: file doesn't need to be copied to the remote machine first. This example
4294: avoids the foo.sh script because it needed to use a modified `--read-batch`
4295: option, but you could edit the script file if you wished to make use of it
4296: (just be sure that no other option is trying to use standard input, such as
4297: the "`--exclude-from=-`" option).
4298:
4299: Caveats:
4300:
4301: The read-batch option expects the destination tree that it is updating to be
4302: identical to the destination tree that was used to create the batch update
4303: fileset. When a difference between the destination trees is encountered the
4304: update might be discarded with a warning (if the file appears to be up-to-date
4305: already) or the file-update may be attempted and then, if the file fails to
4306: verify, the update discarded with an error. This means that it should be safe
4307: to re-run a read-batch operation if the command got interrupted. If you wish
4308: to force the batched-update to always be attempted regardless of the file's
4309: size and date, use the `-I` option (when reading the batch). If an error
4310: occurs, the destination tree will probably be in a partially updated state. In
4311: that case, rsync can be used in its regular (non-batch) mode of operation to
4312: fix up the destination tree.
4313:
4314: The rsync version used on all destinations must be at least as new as the one
4315: used to generate the batch file. Rsync will die with an error if the protocol
4316: version in the batch file is too new for the batch-reading rsync to handle.
4317: See also the `--protocol` option for a way to have the creating rsync generate
4318: a batch file that an older rsync can understand. (Note that batch files
4319: changed format in version 2.6.3, so mixing versions older than that with newer
4320: versions will not work.)
4321:
4322: When reading a batch file, rsync will force the value of certain options to
4323: match the data in the batch file if you didn't set them to the same as the
4324: batch-writing command. Other options can (and should) be changed. For
4325: instance `--write-batch` changes to `--read-batch`, `--files-from` is dropped,
4326: and the `--filter` / `--include` / `--exclude` options are not needed unless
4327: one of the `--delete` options is specified.
4328:
4329: The code that creates the BATCH.sh file transforms any filter/include/exclude
4330: options into a single list that is appended as a "here" document to the shell
4331: script file. An advanced user can use this to modify the exclude list if a
4332: change in what gets deleted by `--delete` is desired. A normal user can ignore
4333: this detail and just use the shell script as an easy way to run the appropriate
4334: `--read-batch` command for the batched data.
4335:
4336: The original batch mode in rsync was based on "rsync+", but the latest
4337: version uses a new implementation.
4338:
4339: # SYMBOLIC LINKS
4340:
4341: Three basic behaviors are possible when rsync encounters a symbolic
4342: link in the source directory.
4343:
4344: By default, symbolic links are not transferred at all. A message "skipping
4345: non-regular" file is emitted for any symlinks that exist.
4346:
4347: If `--links` is specified, then symlinks are recreated with the same target on
4348: the destination. Note that `--archive` implies `--links`.
4349:
4350: If `--copy-links` is specified, then symlinks are "collapsed" by
4351: copying their referent, rather than the symlink.
4352:
4353: Rsync can also distinguish "safe" and "unsafe" symbolic links. An example
4354: where this might be used is a web site mirror that wishes to ensure that the
4355: rsync module that is copied does not include symbolic links to `/etc/passwd` in
4356: the public section of the site. Using `--copy-unsafe-links` will cause any
4357: links to be copied as the file they point to on the destination. Using
4358: `--safe-links` will cause unsafe links to be omitted altogether. (Note that you
4359: must specify `--links` for `--safe-links` to have any effect.)
4360:
4361: Symbolic links are considered unsafe if they are absolute symlinks
4362: (start with `/`), empty, or if they contain enough ".."
4363: components to ascend from the directory being copied.
4364:
4365: Here's a summary of how the symlink options are interpreted. The list is in
4366: order of precedence, so if your combination of options isn't mentioned, use the
4367: first line that is a complete subset of your options:
4368:
4369: 0. `--copy-links` Turn all symlinks into normal files (leaving no symlinks for
4370: any other options to affect).
4371: 0. `--links --copy-unsafe-links` Turn all unsafe symlinks into files and
4372: duplicate all safe symlinks.
4373: 0. `--copy-unsafe-links` Turn all unsafe symlinks into files, noisily skip all
4374: safe symlinks.
4375: 0. `--links --safe-links` Duplicate safe symlinks and skip unsafe ones.
4376: 0. `--links` Duplicate all symlinks.
4377:
4378: # DIAGNOSTICS
4379:
4380: rsync occasionally produces error messages that may seem a little cryptic. The
4381: one that seems to cause the most confusion is "protocol version mismatch -- is
4382: your shell clean?".
4383:
4384: This message is usually caused by your startup scripts or remote shell facility
4385: producing unwanted garbage on the stream that rsync is using for its transport.
4386: The way to diagnose this problem is to run your remote shell like this:
4387:
4388: > ssh remotehost /bin/true > out.dat
4389:
4390: then look at out.dat. If everything is working correctly then out.dat should
4391: be a zero length file. If you are getting the above error from rsync then you
4392: will probably find that out.dat contains some text or data. Look at the
4393: contents and try to work out what is producing it. The most common cause is
4394: incorrectly configured shell startup scripts (such as .cshrc or .profile) that
4395: contain output statements for non-interactive logins.
4396:
4397: If you are having trouble debugging filter patterns, then try specifying the
4398: `-vv` option. At this level of verbosity rsync will show why each individual
4399: file is included or excluded.
4400:
4401: # EXIT VALUES
4402:
4403: 0. **0** Success
4404: 0. **1** Syntax or usage error
4405: 0. **2** Protocol incompatibility
4406: 0. **3** Errors selecting input/output files, dirs
4407: 0. **4** Requested action not supported: an attempt was made to manipulate
4408: 64-bit files on a platform that cannot support them; or an option was
4409: specified that is supported by the client and not by the server.
4410: 0. **5** Error starting client-server protocol
4411: 0. **6** Daemon unable to append to log-file
4412: 0. **10** Error in socket I/O
4413: 0. **11** Error in file I/O
4414: 0. **12** Error in rsync protocol data stream
4415: 0. **13** Errors with program diagnostics
4416: 0. **14** Error in IPC code
4417: 0. **20** Received SIGUSR1 or SIGINT
4418: 0. **21** Some error returned by **waitpid()**
4419: 0. **22** Error allocating core memory buffers
4420: 0. **23** Partial transfer due to error
4421: 0. **24** Partial transfer due to vanished source files
4422: 0. **25** The --max-delete limit stopped deletions
4423: 0. **30** Timeout in data send/receive
4424: 0. **35** Timeout waiting for daemon connection
4425:
4426: # ENVIRONMENT VARIABLES
4427:
4428: 0. `CVSIGNORE`
4429:
4430: The CVSIGNORE environment variable supplements any ignore patterns in
4431: .cvsignore files. See the `--cvs-exclude` option for more details.
4432:
4433: 0. `RSYNC_ICONV`
4434:
4435: Specify a default `--iconv` setting using this environment variable. (First
4436: supported in 3.0.0.)
4437:
4438: 0. `RSYNC_PROTECT_ARGS`
4439:
4440: Specify a non-zero numeric value if you want the `--protect-args` option to
4441: be enabled by default, or a zero value to make sure that it is disabled by
4442: default. (First supported in 3.1.0.)
4443:
4444: 0. `RSYNC_RSH`
4445:
4446: The RSYNC_RSH environment variable allows you to override the default shell
4447: used as the transport for rsync. Command line options are permitted after
4448: the command name, just as in the `-e` option.
4449:
4450: 0. `RSYNC_PROXY`
4451:
4452: The RSYNC_PROXY environment variable allows you to redirect your rsync
4453: client to use a web proxy when connecting to a rsync daemon. You should
4454: set RSYNC_PROXY to a hostname:port pair.
4455:
4456: 0. `RSYNC_PASSWORD`
4457:
4458: Setting RSYNC_PASSWORD to the required password allows you to run
4459: authenticated rsync connections to an rsync daemon without user
4460: intervention. Note that this does not supply a password to a remote shell
4461: transport such as ssh; to learn how to do that, consult the remote shell's
4462: documentation.
4463:
4464: 0. `USER` or `LOGNAME`
4465:
4466: The USER or LOGNAME environment variables are used to determine the default
4467: username sent to an rsync daemon. If neither is set, the username defaults
4468: to "nobody".
4469:
4470: 0. `HOME`
4471:
4472: The HOME environment variable is used to find the user's default .cvsignore
4473: file.
4474:
4475: # FILES
4476:
4477: /etc/rsyncd.conf or rsyncd.conf
4478:
4479: # SEE ALSO
4480:
4481: **rsync-ssl**(1), **rsyncd.conf**(5)
4482:
4483: # BUGS
4484:
4485: times are transferred as \*nix time_t values
4486:
4487: When transferring to FAT filesystems rsync may re-sync
4488: unmodified files.
4489: See the comments on the `--modify-window` option.
4490:
4491: file permissions, devices, etc. are transferred as native numerical
4492: values
4493:
4494: see also the comments on the `--delete` option
4495:
4496: Please report bugs! See the web site at <https://rsync.samba.org/>.
4497:
4498: # VERSION
4499:
4500: This man page is current for version @VERSION@ of rsync.
4501:
4502: # INTERNAL OPTIONS
4503:
4504: The options `--server` and `--sender` are used internally by rsync, and should
4505: never be typed by a user under normal circumstances. Some awareness of these
4506: options may be needed in certain scenarios, such as when setting up a login
4507: that can only run an rsync command. For instance, the support directory of the
4508: rsync distribution has an example script named rrsync (for restricted rsync)
4509: that can be used with a restricted ssh login.
4510:
4511: # CREDITS
4512:
4513: rsync is distributed under the GNU General Public License. See the file
4514: COPYING for details.
4515:
4516: A web site is available at <https://rsync.samba.org/>. The site includes an
4517: FAQ-O-Matic which may cover questions unanswered by this manual page.
4518:
4519: We would be delighted to hear from you if you like this program. Please
4520: contact the mailing-list at <rsync@lists.samba.org>.
4521:
4522: This program uses the excellent zlib compression library written by Jean-loup
4523: Gailly and Mark Adler.
4524:
4525: # THANKS
4526:
4527: Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra,
4528: David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
4529: gone-but-not-forgotten compadre, J.W. Schultz.
4530:
4531: Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and
4532: David Bell. I've probably missed some people, my apologies if I have.
4533:
4534: # AUTHOR
4535:
4536: rsync was originally written by Andrew Tridgell and Paul Mackerras. Many
4537: people have later contributed to it. It is currently maintained by Wayne
4538: Davison.
4539:
4540: Mailing lists for support and development are available at
4541: <https://lists.samba.org/>.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rsync.1.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync