1rsync(1)                                                              rsync(1)
2
3
4

NAME

6       rsync - a fast, versatile, remote (and local) file-copying tool
7

SYNOPSIS

9       Local:  rsync [OPTION...] SRC... [DEST]
10
11       Access via remote shell:
12         Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
13         Push: rsync [OPTION...] SRC... [USER@]HOST:DEST
14
15       Access via rsync daemon:
16         Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
17               rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
18         Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
19               rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST
20
21
22       Usages with just one SRC arg and no DEST arg will list the source files
23       instead of copying.
24

DESCRIPTION

26       Rsync is a fast and extraordinarily versatile file  copying  tool.   It
27       can  copy  locally,  to/from  another  host  over  any remote shell, or
28       to/from a remote rsync daemon.  It offers a  large  number  of  options
29       that  control  every  aspect  of  its behavior and permit very flexible
30       specification of the set of files to be copied.  It is famous  for  its
31       delta-transfer  algorithm,  which  reduces the amount of data sent over
32       the network by sending only the differences between  the  source  files
33       and  the  existing  files in the destination.  Rsync is widely used for
34       backups and mirroring and as an improved copy command for everyday use.
35
36       Rsync finds files that need to be transferred  using  a  "quick  check"
37       algorithm  (by  default) that looks for files that have changed in size
38       or  in  last-modified  time.   Any  changes  in  the  other   preserved
39       attributes  (as  requested by options) are made on the destination file
40       directly when the quick check indicates that the file’s data  does  not
41       need to be updated.
42
43       Some of the additional features of rsync are:
44
45       o      support  for copying links, devices, owners, groups, and permis‐
46              sions
47
48       o      exclude and exclude-from options similar to GNU tar
49
50       o      a CVS exclude mode for ignoring the same files  that  CVS  would
51              ignore
52
53       o      can use any transparent remote shell, including ssh or rsh
54
55       o      does not require super-user privileges
56
57       o      pipelining of file transfers to minimize latency costs
58
59       o      support  for anonymous or authenticated rsync daemons (ideal for
60              mirroring)
61
62

GENERAL

64       Rsync copies files either to or from a remote host, or locally  on  the
65       current  host  (it  does  not  support copying files between two remote
66       hosts).
67
68       There are two different ways for rsync  to  contact  a  remote  system:
69       using  a  remote-shell program as the transport (such as ssh or rsh) or
70       contacting an rsync daemon directly via TCP.  The  remote-shell  trans‐
71       port  is used whenever the source or destination path contains a single
72       colon (:) separator after a host specification.   Contacting  an  rsync
73       daemon  directly happens when the source or destination path contains a
74       double colon (::) separator after a  host  specification,  OR  when  an
75       rsync://  URL  is  specified (see also the "USING RSYNC-DAEMON FEATURES
76       VIA A REMOTE-SHELL CONNECTION" section for an exception to this  latter
77       rule).
78
79       As a special case, if a single source arg is specified without a desti‐
80       nation, the files are listed in an output format similar to "ls -l".
81
82       As expected, if neither the source or destination path specify a remote
83       host, the copy occurs locally (see also the --list-only option).
84
85       Rsync  refers  to the local side as the "client" and the remote side as
86       the "server".  Don’t confuse "server" with an rsync daemon -- a  daemon
87       is  always  a  server,  but  a  server  can  be  either  a  daemon or a
88       remote-shell spawned process.
89

SETUP

91       See the file README for installation instructions.
92
93       Once installed, you can use rsync to any machine that  you  can  access
94       via a remote shell (as well as some that you can access using the rsync
95       daemon-mode protocol).  For remote transfers, a modern rsync  uses  ssh
96       for  its  communications, but it may have been configured to use a dif‐
97       ferent remote shell by default, such as rsh or remsh.
98
99       You can also specify any remote shell you like, either by using the  -e
100       command line option, or by setting the RSYNC_RSH environment variable.
101
102       Note  that  rsync  must be installed on both the source and destination
103       machines.
104

USAGE

106       You use rsync in the same way you use rcp. You must  specify  a  source
107       and a destination, one of which may be remote.
108
109       Perhaps the best way to explain the syntax is with some examples:
110
111              rsync -t *.c foo:src/
112
113
114       This would transfer all files matching the pattern *.c from the current
115       directory to the directory src on the machine foo. If any of the  files
116       already  exist on the remote system then the rsync remote-update proto‐
117       col is used to update the file by sending only the differences  in  the
118       data.   Note  that  the expansion of wildcards on the commandline (*.c)
119       into a list of files is handled by the shell before it runs  rsync  and
120       not  by  rsync  itself  (exactly the same as all other posix-style pro‐
121       grams).
122
123              rsync -avz foo:src/bar /data/tmp
124
125
126       This would recursively transfer all files from the directory src/bar on
127       the  machine foo into the /data/tmp/bar directory on the local machine.
128       The files are transferred in "archive" mode, which  ensures  that  sym‐
129       bolic  links,  devices,  attributes,  permissions, ownerships, etc. are
130       preserved in the transfer.  Additionally, compression will be  used  to
131       reduce the size of data portions of the transfer.
132
133              rsync -avz foo:src/bar/ /data/tmp
134
135
136       A  trailing slash on the source changes this behavior to avoid creating
137       an additional directory level at the destination.  You can think  of  a
138       trailing / on a source as meaning "copy the contents of this directory"
139       as opposed to "copy the directory by  name",  but  in  both  cases  the
140       attributes  of the containing directory are transferred to the contain‐
141       ing directory on the destination.  In other words, each of the  follow‐
142       ing  commands copies the files in the same way, including their setting
143       of the attributes of /dest/foo:
144
145              rsync -av /src/foo /dest
146              rsync -av /src/foo/ /dest/foo
147
148
149       Note also that host and module  references  don’t  require  a  trailing
150       slash to copy the contents of the default directory.  For example, both
151       of these copy the remote directory’s contents into "/dest":
152
153              rsync -av host: /dest
154              rsync -av host::module /dest
155
156
157       You can also use rsync in local-only mode, where both  the  source  and
158       destination  don’t have a ’:’ in the name. In this case it behaves like
159       an improved copy command.
160
161       Finally, you can list all the (listable) modules available from a  par‐
162       ticular rsync daemon by leaving off the module name:
163
164              rsync somehost.mydomain.com::
165
166
167       See the following section for more details.
168

ADVANCED USAGE

170       The  syntax for requesting multiple files from a remote host is done by
171       specifying additional remote-host args in the same style as the  first,
172       or with the hostname omitted.  For instance, all these work:
173
174              rsync -av host:file1 :file2 host:file{3,4} /dest/
175              rsync -av host::modname/file{1,2} host::modname/file3 /dest/
176              rsync -av host::modname/file1 ::modname/file{3,4}
177
178
179       Older  versions  of rsync required using quoted spaces in the SRC, like
180       these examples:
181
182              rsync -av host:'dir1/file1 dir2/file2' /dest
183              rsync host::'modname/dir1/file1 modname/dir2/file2' /dest
184
185
186       This word-splitting still works (by default) in the latest  rsync,  but
187       is not as easy to use as the first method.
188
189       If  you  need  to transfer a filename that contains whitespace, you can
190       either specify the --protect-args (-s) option, or you’ll need to escape
191       the  whitespace  in  a  way that the remote shell will understand.  For
192       instance:
193
194              rsync -av host:'file\ name\ with\ spaces' /dest
195
196

CONNECTING TO AN RSYNC DAEMON

198       It is also possible to use rsync without a remote shell as  the  trans‐
199       port.  In this case you will directly connect to a remote rsync daemon,
200       typically using TCP port 873.  (This obviously requires the  daemon  to
201       be running on the remote system, so refer to the STARTING AN RSYNC DAE‐
202       MON TO ACCEPT CONNECTIONS section below for information on that.)
203
204       Using rsync in this way is the same as using it  with  a  remote  shell
205       except that:
206
207       o      you  either  use  a double colon :: instead of a single colon to
208              separate the hostname from the path, or you use an rsync:// URL.
209
210       o      the first word of the "path" is actually a module name.
211
212       o      the remote daemon may print a message of the day when  you  con‐
213              nect.
214
215       o      if  you  specify no path name on the remote daemon then the list
216              of accessible paths on the daemon will be shown.
217
218       o      if you specify no local destination then a listing of the speci‐
219              fied files on the remote daemon is provided.
220
221       o      you must not specify the --rsh (-e) option.
222
223
224       An example that copies all the files in a remote module named "src":
225
226           rsync -av host::src /dest
227
228
229       Some  modules  on  the remote daemon may require authentication. If so,
230       you will receive a password prompt when you connect. You can avoid  the
231       password  prompt  by setting the environment variable RSYNC_PASSWORD to
232       the password you want to use or using the --password-file option.  This
233       may be useful when scripting rsync.
234
235       WARNING:  On  some  systems  environment  variables  are visible to all
236       users. On those systems using --password-file is recommended.
237
238       You may establish the connection via a web proxy by setting  the  envi‐
239       ronment  variable  RSYNC_PROXY to a hostname:port pair pointing to your
240       web proxy.  Note that your web proxy’s configuration must support proxy
241       connections to port 873.
242
243       You  may  also establish a daemon connection using a program as a proxy
244       by setting the environment variable RSYNC_CONNECT_PROG to the  commands
245       you  wish  to  run  in place of making a direct socket connection.  The
246       string may contain the escape "%H" to represent the hostname  specified
247       in  the  rsync  command  (so  use "%%" if you need a single "%" in your
248       string).  For example:
249
250         export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
251         rsync -av targethost1::module/src/ /dest/
252         rsync -av rsync:://targethost2/module/src/ /dest/
253
254
255       The command specified above uses ssh to run nc (netcat) on a proxyhost,
256       which  forwards all data to port 873 (the rsync daemon) on the targeth‐
257       ost (%H).
258

USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION

260       It is sometimes useful to use various features of an rsync daemon (such
261       as  named modules) without actually allowing any new socket connections
262       into  a  system  (other  than  what  is  already  required   to   allow
263       remote-shell  access).   Rsync  supports  connecting  to a host using a
264       remote shell and  then  spawning  a  single-use  "daemon"  server  that
265       expects  to  read  its  config file in the home dir of the remote user.
266       This can be useful if you want to  encrypt  a  daemon-style  transfer’s
267       data,  but since the daemon is started up fresh by the remote user, you
268       may not be able to use features such as chroot or change the  uid  used
269       by the daemon.  (For another way to encrypt a daemon transfer, consider
270       using ssh to tunnel a local port to a remote machine  and  configure  a
271       normal  rsync daemon on that remote host to only allow connections from
272       "localhost".)
273
274       From the user’s perspective, a daemon transfer via a remote-shell  con‐
275       nection uses nearly the same command-line syntax as a normal rsync-dae‐
276       mon transfer, with the only exception being that  you  must  explicitly
277       set the remote shell program on the command-line with the --rsh=COMMAND
278       option.  (Setting the RSYNC_RSH in the environment  will  not  turn  on
279       this functionality.)  For example:
280
281           rsync -av --rsh=ssh host::module /dest
282
283
284       If you need to specify a different remote-shell user, keep in mind that
285       the user@ prefix in front of the  host  is  specifying  the  rsync-user
286       value  (for  a  module  that requires user-based authentication).  This
287       means that you must give the ’-l user’ option to  ssh  when  specifying
288       the remote-shell, as in this example that uses the short version of the
289       --rsh option:
290
291           rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest
292
293
294       The "ssh-user" will be used at the ssh level; the "rsync-user" will  be
295       used to log-in to the "module".
296

STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS

298       In order to connect to an rsync daemon, the remote system needs to have
299       a daemon already running (or it needs to have configured something like
300       inetd to spawn an rsync daemon for incoming connections on a particular
301       port).  For full information on how to start a daemon  that  will  han‐
302       dling  incoming  socket connections, see the rsyncd.conf(5) man page --
303       that is the config file for  the  daemon,  and  it  contains  the  full
304       details for how to run the daemon (including stand-alone and inetd con‐
305       figurations).
306
307       If you’re using one of the remote-shell transports  for  the  transfer,
308       there is no need to manually start an rsync daemon.
309

SORTED TRANSFER ORDER

311       Rsync  always  sorts the specified filenames into its internal transfer
312       list.  This handles the merging together of the contents of identically
313       named directories, makes it easy to remove duplicate filenames, and may
314       confuse someone when the files are transferred  in  a  different  order
315       than what was given on the command-line.
316
317       If  you  need  a  particular  file  to be transferred prior to another,
318       either separate the files into different rsync calls, or consider using
319       --delay-updates  (which  doesn’t  affect the sorted transfer order, but
320       does make the final file-updating phase happen much more rapidly).
321

EXAMPLES

323       Here are some examples of how I use rsync.
324
325       To backup my wife’s home directory, which consists  of  large  MS  Word
326       files and mail folders, I use a cron job that runs
327
328              rsync -Cavz . arvidsjaur:backup
329
330
331       each night over a PPP connection to a duplicate directory on my machine
332       "arvidsjaur".
333
334       To synchronize my samba source trees I use the following Makefile  tar‐
335       gets:
336
337           get:
338                   rsync -avuzb --exclude '*~' samba:samba/ .
339           put:
340                   rsync -Cavuzb . samba:samba/
341           sync: get put
342
343
344       this  allows  me  to  sync with a CVS directory at the other end of the
345       connection. I then do CVS operations on the remote machine, which saves
346       a lot of time as the remote CVS protocol isn’t very efficient.
347
348       I mirror a directory between my "old" and "new" ftp sites with the com‐
349       mand:
350
351       rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge"
352
353       This is launched from cron every few hours.
354

OPTIONS SUMMARY

356       Here is a short summary of the options available in rsync. Please refer
357       to the detailed description below for a complete description.
358
359        -v, --verbose               increase verbosity
360            --info=FLAGS            fine-grained informational verbosity
361            --debug=FLAGS           fine-grained debug verbosity
362            --msgs2stderr           special output handling for debugging
363        -q, --quiet                 suppress non-error messages
364            --no-motd               suppress daemon-mode MOTD (see caveat)
365        -c, --checksum              skip based on checksum, not mod-time & size
366        -a, --archive               archive mode; equals -rlptgoD (no -H,-A,-X)
367            --no-OPTION             turn off an implied OPTION (e.g. --no-D)
368        -r, --recursive             recurse into directories
369        -R, --relative              use relative path names
370            --no-implied-dirs       don't send implied dirs with --relative
371        -b, --backup                make backups (see --suffix & --backup-dir)
372            --backup-dir=DIR        make backups into hierarchy based in DIR
373            --suffix=SUFFIX         backup suffix (default ~ w/o --backup-dir)
374        -u, --update                skip files that are newer on the receiver
375            --inplace               update destination files in-place
376            --append                append data onto shorter files
377            --append-verify         --append w/old data in file checksum
378        -d, --dirs                  transfer directories without recursing
379        -l, --links                 copy symlinks as symlinks
380        -L, --copy-links            transform symlink into referent file/dir
381            --copy-unsafe-links     only "unsafe" symlinks are transformed
382            --safe-links            ignore symlinks that point outside the tree
383            --munge-links           munge symlinks to make them safer
384        -k, --copy-dirlinks         transform symlink to dir into referent dir
385        -K, --keep-dirlinks         treat symlinked dir on receiver as dir
386        -H, --hard-links            preserve hard links
387        -p, --perms                 preserve permissions
388        -E, --executability         preserve executability
389            --chmod=CHMOD           affect file and/or directory permissions
390        -A, --acls                  preserve ACLs (implies -p)
391        -X, --xattrs                preserve extended attributes
392        -o, --owner                 preserve owner (super-user only)
393        -g, --group                 preserve group
394            --devices               preserve device files (super-user only)
395            --copy-devices          copy device contents as regular file
396            --specials              preserve special files
397        -D                          same as --devices --specials
398        -t, --times                 preserve modification times
399        -O, --omit-dir-times        omit directories from --times
400        -J, --omit-link-times       omit symlinks from --times
401            --super                 receiver attempts super-user activities
402            --fake-super            store/recover privileged attrs using xattrs
403        -S, --sparse                turn sequences of nulls into sparse blocks
404            --preallocate           allocate dest files before writing
405        -n, --dry-run               perform a trial run with no changes made
406        -W, --whole-file            copy files whole (w/o delta-xfer algorithm)
407            --checksum-choice=STR   choose the checksum algorithms
408        -x, --one-file-system       don't cross filesystem boundaries
409        -B, --block-size=SIZE       force a fixed checksum block-size
410        -e, --rsh=COMMAND           specify the remote shell to use
411            --rsync-path=PROGRAM    specify the rsync to run on remote machine
412            --existing              skip creating new files on receiver
413            --ignore-existing       skip updating files that exist on receiver
414            --remove-source-files   sender removes synchronized files (non-dir)
415            --del                   an alias for --delete-during
416            --delete                delete extraneous files from dest dirs
417            --delete-before         receiver deletes before xfer, not during
418            --delete-during         receiver deletes during the transfer
419            --delete-delay          find deletions during, delete after
420            --delete-after          receiver deletes after transfer, not during
421            --delete-excluded       also delete excluded files from dest dirs
422            --ignore-missing-args   ignore missing source args without error
423            --delete-missing-args   delete missing source args from destination
424            --ignore-errors         delete even if there are I/O errors
425            --force                 force deletion of dirs even if not empty
426            --max-delete=NUM        don't delete more than NUM files
427            --max-size=SIZE         don't transfer any file larger than SIZE
428            --min-size=SIZE         don't transfer any file smaller than SIZE
429            --partial               keep partially transferred files
430            --partial-dir=DIR       put a partially transferred file into DIR
431            --delay-updates         put all updated files into place at end
432        -m, --prune-empty-dirs      prune empty directory chains from file-list
433            --numeric-ids           don't map uid/gid values by user/group name
434            --usermap=STRING        custom username mapping
435            --groupmap=STRING       custom groupname mapping
436            --chown=USER:GROUP      simple username/groupname mapping
437            --timeout=SECONDS       set I/O timeout in seconds
438            --contimeout=SECONDS    set daemon connection timeout in seconds
439        -I, --ignore-times          don't skip files that match size and time
440            --size-only             skip files that match in size
441        -@, --modify-window=NUM     set the accuracy for mod-time comparisons
442        -T, --temp-dir=DIR          create temporary files in directory DIR
443        -y, --fuzzy                 find similar file for basis if no dest file
444            --compare-dest=DIR      also compare received files relative to DIR
445            --copy-dest=DIR         ... and include copies of unchanged files
446            --link-dest=DIR         hardlink to files in DIR when unchanged
447        -z, --compress              compress file data during the transfer
448            --compress-level=NUM    explicitly set compression level
449            --skip-compress=LIST    skip compressing files with suffix in LIST
450        -C, --cvs-exclude           auto-ignore files in the same way CVS does
451        -f, --filter=RULE           add a file-filtering RULE
452        -F                          same as --filter='dir-merge /.rsync-filter'
453                                    repeated: --filter='- .rsync-filter'
454            --exclude=PATTERN       exclude files matching PATTERN
455            --exclude-from=FILE     read exclude patterns from FILE
456            --include=PATTERN       don't exclude files matching PATTERN
457            --include-from=FILE     read include patterns from FILE
458            --files-from=FILE       read list of source-file names from FILE
459        -0, --from0                 all *from/filter files are delimited by 0s
460        -s, --protect-args          no space-splitting; wildcard chars only
461            --address=ADDRESS       bind address for outgoing socket to daemon
462            --port=PORT             specify double-colon alternate port number
463            --sockopts=OPTIONS      specify custom TCP options
464            --blocking-io           use blocking I/O for the remote shell
465            --outbuf=N|L|B          set out buffering to None, Line, or Block
466            --stats                 give some file-transfer stats
467        -8, --8-bit-output          leave high-bit chars unescaped in output
468        -h, --human-readable        output numbers in a human-readable format
469            --progress              show progress during transfer
470        -P                          same as --partial --progress
471        -i, --itemize-changes       output a change-summary for all updates
472        -M, --remote-option=OPTION  send OPTION to the remote side only
473            --out-format=FORMAT     output updates using the specified FORMAT
474            --log-file=FILE         log what we're doing to the specified FILE
475            --log-file-format=FMT   log updates using the specified FMT
476            --password-file=FILE    read daemon-access password from FILE
477            --list-only             list the files instead of copying them
478            --bwlimit=RATE          limit socket I/O bandwidth
479            --write-batch=FILE      write a batched update to FILE
480            --only-write-batch=FILE like --write-batch but w/o updating dest
481            --read-batch=FILE       read a batched update from FILE
482            --protocol=NUM          force an older protocol version to be used
483            --iconv=CONVERT_SPEC    request charset conversion of filenames
484            --checksum-seed=NUM     set block/file checksum seed (advanced)
485        -4, --ipv4                  prefer IPv4
486        -6, --ipv6                  prefer IPv6
487            --version               print version number
488       (-h) --help                  show this help (see below for -h comment)
489
490
491       Rsync  can also be run as a daemon, in which case the following options
492       are accepted:
493
494            --daemon                run as an rsync daemon
495            --address=ADDRESS       bind to the specified address
496            --bwlimit=RATE          limit socket I/O bandwidth
497            --config=FILE           specify alternate rsyncd.conf file
498        -M, --dparam=OVERRIDE       override global daemon config parameter
499            --no-detach             do not detach from the parent
500            --port=PORT             listen on alternate port number
501            --log-file=FILE         override the "log file" setting
502            --log-file-format=FMT   override the "log format" setting
503            --sockopts=OPTIONS      specify custom TCP options
504        -v, --verbose               increase verbosity
505        -4, --ipv4                  prefer IPv4
506        -6, --ipv6                  prefer IPv6
507        -h, --help                  show this help (if used after --daemon)
508
509

OPTIONS

511       Rsync accepts both long (double-dash + word) and short  (single-dash  +
512       letter)  options.  The full list of the available options are described
513       below.  If an option can be specified in more than one way, the choices
514       are  comma-separated.   Some  options  only  have a long variant, not a
515       short.  If the option takes a parameter, the parameter is  only  listed
516       after  the  long variant, even though it must also be specified for the
517       short.  When specifying a  parameter,  you  can  either  use  the  form
518       --option=param  or  replace the ’=’ with whitespace.  The parameter may
519       need to be quoted in some manner for it to  survive  the  shell’s  com‐
520       mand-line parsing.  Keep in mind that a leading tilde (~) in a filename
521       is substituted by your shell, so --option=~/foo  will  not  change  the
522       tilde into your home directory (remove the ’=’ for that).
523
524       --help Print  a  short  help  page  describing the options available in
525              rsync and exit.  For backward-compatibility with older  versions
526              of  rsync, the help will also be output if you use the -h option
527              without any other args.
528
529       --version
530              print the rsync version number and exit.
531
532       -v, --verbose
533              This option increases the amount of information  you  are  given
534              during the transfer.  By default, rsync works silently. A single
535              -v will give you information about what files are  being  trans‐
536              ferred  and a brief summary at the end. Two -v options will give
537              you information on what files are  being  skipped  and  slightly
538              more  information  at  the  end. More than two -v options should
539              only be used if you are debugging rsync.
540
541              In a modern rsync, the -v option is equivalent to the setting of
542              groups  of  --info  and  --debug options.  You can choose to use
543              these newer options in addition to, or in place of using  --ver‐
544              bose, as any fine-grained settings override the implied settings
545              of -v.  Both --info and --debug have a way to ask for help  that
546              tells  you  exactly what flags are set for each increase in ver‐
547              bosity.
548
549              However, do keep in mind that a daemon’s "max verbosity" setting
550              will  limit how high of a level the various individual flags can
551              be set on the daemon side.  For instance, if the max is 2,  then
552              any  info  and/or  debug flag that is set to a higher value than
553              what would be set by -vv will be downgraded to the -vv level  in
554              the daemon’s logging.
555
556       --info=FLAGS
557              This option lets you have fine-grained control over the informa‐
558              tion output you want to see.  An individual  flag  name  may  be
559              followed  by a level number, with 0 meaning to silence that out‐
560              put, 1 being  the  default  output  level,  and  higher  numbers
561              increasing  the  output  of  that  flag  (for those that support
562              higher levels).  Use --info=help to see all the  available  flag
563              names,  what they output, and what flag names are added for each
564              increase in the verbose level.  Some examples:
565
566                  rsync -a --info=progress2 src/ dest/
567                  rsync -avv --info=stats2,misc1,flist0 src/ dest/
568
569
570              Note that --info=name’s output is affected by  the  --out-format
571              and  --itemize-changes (-i) options.  See those options for more
572              information on what is output and when.
573
574              This option was added to 3.1.0, so an older rsync on the  server
575              side  might reject your attempts at fine-grained control (if one
576              or more flags needed to be send to the server and the server was
577              too  old  to  understand  them).   See  also the "max verbosity"
578              caveat above when dealing with a daemon.
579
580       --debug=FLAGS
581              This option lets you have fine-grained control  over  the  debug
582              output you want to see.  An individual flag name may be followed
583              by a level number, with 0 meaning  to  silence  that  output,  1
584              being  the  default  output level, and higher numbers increasing
585              the output of that flag (for those that support higher  levels).
586              Use  --debug=help to see all the available flag names, what they
587              output, and what flag names are added for each increase  in  the
588              verbose level.  Some examples:
589
590                  rsync -avvv --debug=none src/ dest/
591                  rsync -avA --del --debug=del2,acl src/ dest/
592
593
594              Note   that  some  debug  messages  will  only  be  output  when
595              --msgs2stderr is specified, especially those pertaining  to  I/O
596              and buffer debugging.
597
598              This  option was added to 3.1.0, so an older rsync on the server
599              side might reject your attempts at fine-grained control (if  one
600              or more flags needed to be send to the server and the server was
601              too old to understand  them).   See  also  the  "max  verbosity"
602              caveat above when dealing with a daemon.
603
604       --msgs2stderr
605              This  option  changes  rsync  to send all its output directly to
606              stderr rather than to send messages to the client side  via  the
607              protocol  (which  normally  outputs  info  messages via stdout).
608              This is mainly intended for debugging in order to avoid changing
609              the  data  sent  via the protocol, since the extra protocol data
610              can change what is being tested.  The option does not affect the
611              remote  side of a transfer without using --remote-option -- e.g.
612              -M--msgs2stderr.  Also keep in mind  that  a  daemon  connection
613              does  not  have  a  stderr  channel to send messages back to the
614              client side, so if you are doing any  daemon-transfer  debugging
615              using   this   option,  you  should  start  up  a  daemon  using
616              --no-detach so that you can see the stderr output on the  daemon
617              side.
618
619              This  option  has  the  side-effect  of making stderr output get
620              line-buffered so that the merging of the output  of  3  programs
621              happens in a more readable manner.
622
623       -q, --quiet
624              This  option  decreases  the amount of information you are given
625              during the transfer, notably  suppressing  information  messages
626              from  the  remote  server.  This  option is useful when invoking
627              rsync from cron.
628
629       --no-motd
630              This option affects the information that is output by the client
631              at  the  start  of  a daemon transfer.  This suppresses the mes‐
632              sage-of-the-day (MOTD) text, but it also  affects  the  list  of
633              modules  that the daemon sends in response to the "rsync host::"
634              request (due to a limitation in the  rsync  protocol),  so  omit
635              this  option if you want to request the list of modules from the
636              daemon.
637
638       -I, --ignore-times
639              Normally rsync will skip any files that  are  already  the  same
640              size  and  have  the  same  modification timestamp.  This option
641              turns off this "quick check" behavior, causing all files  to  be
642              updated.
643
644       --size-only
645              This  modifies rsync’s "quick check" algorithm for finding files
646              that need to be transferred, changing it  from  the  default  of
647              transferring  files  with  either  a  changed  size or a changed
648              last-modified time to just looking for files that  have  changed
649              in  size.  This is useful when starting to use rsync after using
650              another mirroring  system  which  may  not  preserve  timestamps
651              exactly.
652
653       -@, --modify-window
654              When  comparing  two  timestamps, rsync treats the timestamps as
655              being equal if they differ by no  more  than  the  modify-window
656              value.   The  default  is 0, which matches just integer seconds.
657              If you specify a negative value (and the receiver  is  at  least
658              version 3.1.3) then nanoseconds will also be taken into account.
659              Specifying 1  is  useful  for  copies  to/from  MS  Windows  FAT
660              filesystems,  because FAT represents times with a 2-second reso‐
661              lution (allowing times to differ from the original by  up  to  1
662              second).
663
664              If  you want all your transfers to default to comparing nanosec‐
665              onds, you can create a ~/.popt file and put these lines in it:
666
667                 rsync alias -a -a@-1
668                 rsync alias -t -t@-1
669
670
671              With that as the default, you’d need  to  specify  --modify-win‐
672              dow=0  (aka  -@0) to override it and ignore nanoseconds, e.g. if
673              you’re copying between ext3 and ext4, or if the receiving  rsync
674              is older than 3.1.3.
675
676       -c, --checksum
677              This changes the way rsync checks if the files have been changed
678              and are in need of a transfer.  Without this option, rsync  uses
679              a "quick check" that (by default) checks if each file’s size and
680              time of last modification match between the sender and receiver.
681              This  option changes this to compare a 128-bit checksum for each
682              file that has a matching size.  Generating the  checksums  means
683              that  both  sides  will expend a lot of disk I/O reading all the
684              data in the files in the transfer (and  this  is  prior  to  any
685              reading  that  will  be done to transfer changed files), so this
686              can slow things down significantly.
687
688              The sending side generates its checksums while it is  doing  the
689              file-system  scan  that  builds the list of the available files.
690              The receiver generates its checksums when  it  is  scanning  for
691              changed files, and will checksum any file that has the same size
692              as the corresponding sender’s file:  files with either a changed
693              size or a changed checksum are selected for transfer.
694
695              Note  that  rsync always verifies that each transferred file was
696              correctly reconstructed on the  receiving  side  by  checking  a
697              whole-file  checksum  that  is  generated  as the file is trans‐
698              ferred, but that automatic after-the-transfer  verification  has
699              nothing  to do with this option’s before-the-transfer "Does this
700              file need to be updated?" check.
701
702              For protocol 30 and  beyond  (first  supported  in  3.0.0),  the
703              checksum used is MD5.  For older protocols, the checksum used is
704              MD4.
705
706       -a, --archive
707              This is equivalent to -rlptgoD. It is a quick way of saying  you
708              want  recursion  and want to preserve almost everything (with -H
709              being a notable omission).  The  only  exception  to  the  above
710              equivalence  is when --files-from is specified, in which case -r
711              is not implied.
712
713              Note that -a does not preserve hardlinks, because finding multi‐
714              ply-linked files is expensive.  You must separately specify -H.
715
716       --no-OPTION
717              You  may  turn  off one or more implied options by prefixing the
718              option name with "no-".  Not all options may be prefixed with  a
719              "no-":  only  options  that  are  implied by other options (e.g.
720              --no-D, --no-perms) or have different defaults in  various  cir‐
721              cumstances  (e.g. --no-whole-file, --no-blocking-io, --no-dirs).
722              You may specify either the short or the long option  name  after
723              the "no-" prefix (e.g. --no-R is the same as --no-relative).
724
725              For example: if you want to use -a (--archive) but don’t want -o
726              (--owner), instead of converting  -a  into  -rlptgD,  you  could
727              specify -a --no-o (or -a --no-owner).
728
729              The  order  of  the options is important:  if you specify --no-r
730              -a, the -r option would end up being turned on, the opposite  of
731              -a  --no-r.  Note also that the side-effects of the --files-from
732              option are NOT positional, as it affects the  default  state  of
733              several  options and slightly changes the meaning of -a (see the
734              --files-from option for more details).
735
736       -r, --recursive
737              This tells rsync to  copy  directories  recursively.   See  also
738              --dirs (-d).
739
740              Beginning  with rsync 3.0.0, the recursive algorithm used is now
741              an incremental scan that uses much less memory than  before  and
742              begins the transfer after the scanning of the first few directo‐
743              ries have been completed.  This incremental  scan  only  affects
744              our  recursion  algorithm,  and  does not change a non-recursive
745              transfer.  It is also only possible when both ends of the trans‐
746              fer are at least version 3.0.0.
747
748              Some  options require rsync to know the full file list, so these
749              options disable the incremental recursion mode.  These  include:
750              --delete-before,    --delete-after,    --prune-empty-dirs,   and
751              --delay-updates.  Because of this, the default delete mode  when
752              you  specify  --delete  is now --delete-during when both ends of
753              the connection are at least 3.0.0 (use --del or  --delete-during
754              to  request  this  improved deletion mode explicitly).  See also
755              the --delete-delay option that is a  better  choice  than  using
756              --delete-after.
757
758              Incremental  recursion can be disabled using the --no-inc-recur‐
759              sive option or its shorter --no-i-r alias.
760
761       -R, --relative
762              Use relative paths. This means that the full path  names  speci‐
763              fied on the command line are sent to the server rather than just
764              the last parts of the filenames.  This  is  particularly  useful
765              when  you want to send several different directories at the same
766              time. For example, if you used this command:
767
768                 rsync -av /foo/bar/baz.c remote:/tmp/
769
770
771              ... this would create a file named baz.c in /tmp/ on the  remote
772              machine. If instead you used
773
774                 rsync -avR /foo/bar/baz.c remote:/tmp/
775
776
777              then  a  file  named  /tmp/foo/bar/baz.c would be created on the
778              remote machine, preserving its full path.  These extra path ele‐
779              ments  are  called "implied directories" (i.e. the "foo" and the
780              "foo/bar" directories in the above example).
781
782              Beginning with rsync 3.0.0, rsync  always  sends  these  implied
783              directories as real directories in the file list, even if a path
784              element is really a symlink on the sending side.  This  prevents
785              some really unexpected behaviors when copying the full path of a
786              file that you didn’t realize had a symlink in its path.  If  you
787              want  to  duplicate a server-side symlink, include both the sym‐
788              link via its path, and referent directory via its real path.  If
789              you’re  dealing with an older rsync on the sending side, you may
790              need to use the --no-implied-dirs option.
791
792              It is also possible to limit the amount of path information that
793              is  sent as implied directories for each path you specify.  With
794              a modern rsync on the sending side (beginning with  2.6.7),  you
795              can insert a dot and a slash into the source path, like this:
796
797                 rsync -avR /foo/./bar/baz.c remote:/tmp/
798
799
800              That  would  create /tmp/bar/baz.c on the remote machine.  (Note
801              that the dot must be followed by a slash, so "/foo/." would  not
802              be  abbreviated.)   For  older rsync versions, you would need to
803              use a chdir to limit the source path.  For example, when pushing
804              files:
805
806                 (cd /foo; rsync -avR bar/baz.c remote:/tmp/)
807
808
809              (Note  that the parens put the two commands into a sub-shell, so
810              that the "cd" command doesn’t remain in effect for  future  com‐
811              mands.)   If  you’re pulling files from an older rsync, use this
812              idiom (but only for a non-daemon transfer):
813
814                 rsync -avR --rsync-path="cd /foo; rsync" \
815                     remote:bar/baz.c /tmp/
816
817
818       --no-implied-dirs
819              This option affects  the  default  behavior  of  the  --relative
820              option.   When  it  is  specified, the attributes of the implied
821              directories from the source names are not included in the trans‐
822              fer.   This  means  that  the corresponding path elements on the
823              destination system are left unchanged if  they  exist,  and  any
824              missing implied directories are created with default attributes.
825              This even allows these implied path elements to have big differ‐
826              ences,  such  as being a symlink to a directory on the receiving
827              side.
828
829              For instance, if a command-line arg or a files-from  entry  told
830              rsync  to  transfer  the  file  "path/foo/file", the directories
831              "path" and "path/foo" are implied when --relative is  used.   If
832              "path/foo"  is a symlink to "bar" on the destination system, the
833              receiving rsync would ordinarily delete "path/foo", recreate  it
834              as  a  directory,  and  receive the file into the new directory.
835              With   --no-implied-dirs,   the    receiving    rsync    updates
836              "path/foo/file"  using  the  existing path elements, which means
837              that the file ends up being created in "path/bar".  Another  way
838              to   accomplish   this   link   preservation   is   to  use  the
839              --keep-dirlinks option  (which  will  also  affect  symlinks  to
840              directories in the rest of the transfer).
841
842              When  pulling files from an rsync older than 3.0.0, you may need
843              to use this option if the sending side has a symlink in the path
844              you  request  and  you wish the implied directories to be trans‐
845              ferred as normal directories.
846
847       -b, --backup
848              With this option, preexisting destination files are  renamed  as
849              each  file is transferred or deleted.  You can control where the
850              backup file goes and what (if any) suffix  gets  appended  using
851              the --backup-dir and --suffix options.
852
853              Note   that   if   you   don’t  specify  --backup-dir,  (1)  the
854              --omit-dir-times option will be forced on, and (2)  if  --delete
855              is  also in effect (without --delete-excluded), rsync will add a
856              "protect" filter-rule for the backup suffix to the  end  of  all
857              your existing excludes (e.g. -f "P *~").  This will prevent pre‐
858              viously backed-up files from being deleted.  Note  that  if  you
859              are  supplying  your  own filter rules, you may need to manually
860              insert your own exclude/protect rule somewhere higher up in  the
861              list  so  that  it  has  a  high enough priority to be effective
862              (e.g., if your rules specify a trailing  inclusion/exclusion  of
863              ’*’, the auto-added rule would never be reached).
864
865       --backup-dir=DIR
866              In  combination  with  the  --backup option, this tells rsync to
867              store all backups in the specified directory  on  the  receiving
868              side.   This can be used for incremental backups.  You can addi‐
869              tionally specify a backup suffix using the --suffix option (oth‐
870              erwise  the files backed up in the specified directory will keep
871              their original filenames).
872
873              Note that if you specify a relative path, the  backup  directory
874              will  be  relative to the destination directory, so you probably
875              want to specify either an absolute path or a  path  that  starts
876              with  "../".  If an rsync daemon is the receiver, the backup dir
877              cannot go outside the module’s path  hierarchy,  so  take  extra
878              care not to delete it or copy into it.
879
880       --suffix=SUFFIX
881              This  option  allows  you  to override the default backup suffix
882              used with the --backup (-b) option. The default suffix is a ~ if
883              no --backup-dir was specified, otherwise it is an empty string.
884
885       -u, --update
886              This  forces rsync to skip any files which exist on the destina‐
887              tion and have a modified time that  is  newer  than  the  source
888              file.   (If an existing destination file has a modification time
889              equal to the source file’s, it will be updated if the sizes  are
890              different.)
891
892              Note that this does not affect the copying of dirs, symlinks, or
893              other special files.  Also, a difference of file format  between
894              the  sender  and  receiver  is always considered to be important
895              enough for an update, no matter what date is on the objects.  In
896              other words, if the source has a directory where the destination
897              has a file, the transfer would occur  regardless  of  the  time‐
898              stamps.
899
900              This  option  is  a transfer rule, not an exclude, so it doesn’t
901              affect the data that goes  into  the  file-lists,  and  thus  it
902              doesn’t  affect  deletions.   It  just limits the files that the
903              receiver requests to be transferred.
904
905       --inplace
906              This option changes how rsync transfers a  file  when  its  data
907              needs to be updated: instead of the default method of creating a
908              new copy of the file and moving it into place when  it  is  com‐
909              plete,  rsync  instead  writes  the updated data directly to the
910              destination file.
911
912              This has several effects:
913
914              o      Hard links are not broken.  This means the new data  will
915                     be  visible  through  other hard links to the destination
916                     file.  Moreover, attempts to copy differing source  files
917                     onto  a multiply-linked destination file will result in a
918                     "tug of war" with the destination data changing back  and
919                     forth.
920
921              o      In-use  binaries  cannot  be  updated (either the OS will
922                     prevent this from happening, or binaries that attempt  to
923                     swap-in their data will misbehave or crash).
924
925              o      The  file’s  data will be in an inconsistent state during
926                     the transfer and will be left that way if the transfer is
927                     interrupted or if an update fails.
928
929              o      A  file  that  rsync  cannot  write to cannot be updated.
930                     While a super user can update any  file,  a  normal  user
931                     needs  to be granted write permission for the open of the
932                     file for writing to be successful.
933
934              o      The efficiency of rsync’s delta-transfer algorithm may be
935                     reduced if some data in the destination file is overwrit‐
936                     ten before it can be copied to a position  later  in  the
937                     file.   This  does  not  apply if you use --backup, since
938                     rsync is smart enough to use the backup file as the basis
939                     file for the transfer.
940
941
942              WARNING: you should not use this option to update files that are
943              being accessed by others, so be careful  when  choosing  to  use
944              this for a copy.
945
946              This   option  is  useful  for  transferring  large  files  with
947              block-based changes or appended data, and also on  systems  that
948              are  disk  bound,  not  network  bound.  It can also help keep a
949              copy-on-write filesystem snapshot from diverging the entire con‐
950              tents of a file that only has minor changes.
951
952              The option implies --partial (since an interrupted transfer does
953              not delete the  file),  but  conflicts  with  --partial-dir  and
954              --delay-updates.  Prior to rsync 2.6.4 --inplace was also incom‐
955              patible with --compare-dest and --link-dest.
956
957       --append
958              This causes rsync to update a file by appending  data  onto  the
959              end  of  the  file,  which  presumes  that the data that already
960              exists on the receiving side is identical with the start of  the
961              file on the sending side.  If a file needs to be transferred and
962              its size on the receiver is the same or longer than the size  on
963              the  sender,  the file is skipped.  This does not interfere with
964              the updating of a file’s non-content  attributes  (e.g.  permis‐
965              sions, ownership, etc.) when the file does not need to be trans‐
966              ferred, nor does it  affect  the  updating  of  any  non-regular
967              files.  Implies --inplace.
968
969              The  use  of  --append  can be dangerous if you aren’t 100% sure
970              that the files that are longer have only grown by the  appending
971              of  data onto the end.  You should thus use include/exclude/fil‐
972              ter rules to ensure that such a transfer is only affecting files
973              that you know to be growing via appended data.
974
975       --append-verify
976              This  works just like the --append option, but the existing data
977              on the receiving side is included in the full-file checksum ver‐
978              ification  step,  which  will  cause  a file to be resent if the
979              final verification step fails (rsync uses a normal,  non-append‐
980              ing --inplace transfer for the resend).
981
982              Note:  prior  to  rsync  3.0.0,  the --append option worked like
983              --append-verify, so if you are interacting with an  older  rsync
984              (or  the  transfer  is using a protocol prior to 30), specifying
985              either append option will initiate an --append-verify transfer.
986
987       -d, --dirs
988              Tell the sending  side  to  include  any  directories  that  are
989              encountered.  Unlike --recursive, a directory’s contents are not
990              copied unless the directory name specified is "." or ends with a
991              trailing  slash (e.g. ".", "dir/.", "dir/", etc.).  Without this
992              option or the --recursive option, rsync will skip  all  directo‐
993              ries it encounters (and output a message to that effect for each
994              one).  If you specify both --dirs and  --recursive,  --recursive
995              takes precedence.
996
997              The  --dirs  option is implied by the --files-from option or the
998              --list-only option (including an implied --list-only  usage)  if
999              --recursive  wasn’t  specified  (so that directories are seen in
1000              the listing).  Specify --no-dirs (or --no-d) if you want to turn
1001              this off.
1002
1003              There is also a backward-compatibility helper option, --old-dirs
1004              (or  --old-d)  that  tells  rsync  to  use   a   hack   of   "-r
1005              --exclude=’/*/*’"  to get an older rsync to list a single direc‐
1006              tory without recursing.
1007
1008       -l, --links
1009              When symlinks are encountered, recreate the symlink on the  des‐
1010              tination.
1011
1012       -L, --copy-links
1013              When  symlinks are encountered, the item that they point to (the
1014              referent) is copied, rather than the symlink.  In older versions
1015              of  rsync,  this  option also had the side-effect of telling the
1016              receiving side to follow symlinks, such as symlinks to  directo‐
1017              ries.   In a modern rsync such as this one, you’ll need to spec‐
1018              ify --keep-dirlinks (-K) to get this extra behavior.   The  only
1019              exception  is  when sending files to an rsync that is too old to
1020              understand -K -- in that case, the -L option will still have the
1021              side-effect of -K on that older receiving rsync.
1022
1023       --copy-unsafe-links
1024              This  tells  rsync  to  copy the referent of symbolic links that
1025              point outside the  copied  tree.   Absolute  symlinks  are  also
1026              treated  like  ordinary  files,  and  so are any symlinks in the
1027              source path itself when --relative is used.  This option has  no
1028              additional effect if --copy-links was also specified.
1029
1030       --safe-links
1031              This  tells  rsync to ignore any symbolic links which point out‐
1032              side the copied tree. All absolute symlinks  are  also  ignored.
1033              Using  this option in conjunction with --relative may give unex‐
1034              pected results.
1035
1036       --munge-links
1037              This option tells rsync  to  (1)  modify  all  symlinks  on  the
1038              receiving side in a way that makes them unusable but recoverable
1039              (see below), or (2) to unmunge symlinks on the sending side that
1040              had  been stored in a munged state.  This is useful if you don’t
1041              quite trust the source of the data to not try to slip in a  sym‐
1042              link to a unexpected place.
1043
1044              The way rsync disables the use of symlinks is to prefix each one
1045              with the string "/rsyncd-munged/".  This prevents the links from
1046              being  used as long as that directory does not exist.  When this
1047              option is enabled, rsync will refuse to run if that  path  is  a
1048              directory or a symlink to a directory.
1049
1050              The  option  only affects the client side of the transfer, so if
1051              you  need  it   to   affect   the   server,   specify   it   via
1052              --remote-option.   (Note  that  in  a local transfer, the client
1053              side is the sender.)
1054
1055              This option has no affect on a daemon, since the daemon  config‐
1056              ures  whether  it wants munged symlinks via its "munge symlinks"
1057              parameter.  See also the "munge-symlinks"  perl  script  in  the
1058              support directory of the source code.
1059
1060       -k, --copy-dirlinks
1061              This  option  causes  the  sending  side to treat a symlink to a
1062              directory as though it were a real directory.  This is useful if
1063              you  don’t  want  symlinks to non-directories to be affected, as
1064              they would be using --copy-links.
1065
1066              Without this option, if the sending side has replaced  a  direc‐
1067              tory  with  a  symlink  to  a directory, the receiving side will
1068              delete anything that is in the way of the new symlink, including
1069              a  directory  hierarchy  (as  long  as --force or --delete is in
1070              effect).
1071
1072              See also --keep-dirlinks for an analogous option for the receiv‐
1073              ing side.
1074
1075              --copy-dirlinks  applies  to  all symlinks to directories in the
1076              source.  If you want to follow only a few specified symlinks,  a
1077              trick you can use is to pass them as additional source args with
1078              a trailing slash, using --relative to make the  paths  match  up
1079              right.  For example:
1080
1081              rsync -r --relative src/./ src/./follow-me/ dest/
1082
1083
1084              This  works  because  rsync  calls lstat(2) on the source arg as
1085              given, and the trailing slash makes lstat(2) follow the symlink,
1086              giving  rise to a directory in the file-list which overrides the
1087              symlink found during the scan of "src/./".
1088
1089       -K, --keep-dirlinks
1090              This option causes the receiving side to treat a  symlink  to  a
1091              directory  as  though  it  were a real directory, but only if it
1092              matches a real directory from the sender.  Without this  option,
1093              the receiver’s symlink would be deleted and replaced with a real
1094              directory.
1095
1096              For example, suppose you transfer a directory  "foo"  that  con‐
1097              tains  a  file "file", but "foo" is a symlink to directory "bar"
1098              on the receiver.  Without --keep-dirlinks, the receiver  deletes
1099              symlink  "foo",  recreates  it  as a directory, and receives the
1100              file into the new directory.  With --keep-dirlinks, the receiver
1101              keeps the symlink and "file" ends up in "bar".
1102
1103              One note of caution:  if you use --keep-dirlinks, you must trust
1104              all the symlinks  in  the  copy!   If  it  is  possible  for  an
1105              untrusted user to create their own symlink to any directory, the
1106              user could then (on a subsequent copy) replace the symlink  with
1107              a  real  directory  and affect the content of whatever directory
1108              the symlink references.  For backup copies, you are  better  off
1109              using something like a bind mount instead of a symlink to modify
1110              your receiving hierarchy.
1111
1112              See also --copy-dirlinks for an analogous option for the sending
1113              side.
1114
1115       -H, --hard-links
1116              This tells rsync to look for hard-linked files in the source and
1117              link together the corresponding files on the destination.  With‐
1118              out  this option, hard-linked files in the source are treated as
1119              though they were separate files.
1120
1121              This option does NOT necessarily ensure that the pattern of hard
1122              links  on  the  destination  exactly matches that on the source.
1123              Cases in which the destination may end up with extra hard  links
1124              include the following:
1125
1126              o      If  the  destination contains extraneous hard-links (more
1127                     linking than what is present in the  source  file  list),
1128                     the  copying  algorithm  will  not break them explicitly.
1129                     However, if one or more of the paths have content differ‐
1130                     ences,  the  normal  file-update process will break those
1131                     extra links (unless you are using the --inplace option).
1132
1133              o      If you specify a --link-dest directory that contains hard
1134                     links,  the  linking of the destination files against the
1135                     --link-dest files can cause some paths in the destination
1136                     to become linked together due to the --link-dest associa‐
1137                     tions.
1138
1139
1140              Note that rsync can only detect hard links  between  files  that
1141              are  inside  the transfer set.  If rsync updates a file that has
1142              extra hard-link connections to files outside the transfer,  that
1143              linkage will be broken.  If you are tempted to use the --inplace
1144              option to avoid this breakage, be very careful that you know how
1145              your  files  are  being  updated so that you are certain that no
1146              unintended changes happen due to lingering hard links  (and  see
1147              the --inplace option for more caveats).
1148
1149              If  incremental recursion is active (see --recursive), rsync may
1150              transfer a missing hard-linked file before it finds that another
1151              link  for that contents exists elsewhere in the hierarchy.  This
1152              does not affect the accuracy of the transfer (i.e.  which  files
1153              are hard-linked together), just its efficiency (i.e. copying the
1154              data for a new, early copy of a hard-linked file that could have
1155              been  found  later  in  the  transfer  in  another member of the
1156              hard-linked set of files).  One way to avoid  this  inefficiency
1157              is to disable incremental recursion using the --no-inc-recursive
1158              option.
1159
1160       -p, --perms
1161              This option causes the receiving rsync to  set  the  destination
1162              permissions to be the same as the source permissions.  (See also
1163              the --chmod option for a way to modify what rsync  considers  to
1164              be the source permissions.)
1165
1166              When this option is off, permissions are set as follows:
1167
1168              o      Existing  files  (including  updated  files) retain their
1169                     existing permissions, though the  --executability  option
1170                     might change just the execute permission for the file.
1171
1172              o      New  files  get their "normal" permission bits set to the
1173                     source  file’s  permissions  masked  with  the  receiving
1174                     directory’s  default  permissions  (either  the receiving
1175                     process’s umask, or the  permissions  specified  via  the
1176                     destination  directory’s  default ACL), and their special
1177                     permission bits disabled except in the case where  a  new
1178                     directory  inherits  a  setgid bit from its parent direc‐
1179                     tory.
1180
1181
1182              Thus,  when  --perms  and  --executability  are  both  disabled,
1183              rsync’s  behavior  is the same as that of other file-copy utili‐
1184              ties, such as cp(1) and tar(1).
1185
1186              In summary: to give destination files (both  old  and  new)  the
1187              source permissions, use --perms.  To give new files the destina‐
1188              tion-default   permissions   (while   leaving   existing   files
1189              unchanged),  make  sure  that  the --perms option is off and use
1190              --chmod=ugo=rwX (which ensures  that  all  non-masked  bits  get
1191              enabled).   If you’d care to make this latter behavior easier to
1192              type, you could define a popt alias for it, such as putting this
1193              line  in  the file ~/.popt (the following defines the -Z option,
1194              and includes --no-g to use the default group of the  destination
1195              dir):
1196
1197                 rsync alias -Z --no-p --no-g --chmod=ugo=rwX
1198
1199
1200              You  could  then  use  this new option in a command such as this
1201              one:
1202
1203                 rsync -avZ src/ dest/
1204
1205
1206              (Caveat: make sure that -a  does  not  follow  -Z,  or  it  will
1207              re-enable the two "--no-*" options mentioned above.)
1208
1209              The  preservation  of the destination’s setgid bit on newly-cre‐
1210              ated directories when --perms is off was added in  rsync  2.6.7.
1211              Older  rsync  versions  erroneously  preserved the three special
1212              permission bits for newly-created files when  --perms  was  off,
1213              while  overriding  the  destination’s  setgid  bit  setting on a
1214              newly-created directory.  Default ACL observance  was  added  to
1215              the  ACL  patch  for  rsync 2.6.7, so older (or non-ACL-enabled)
1216              rsyncs use the umask even if default ACLs are present.  (Keep in
1217              mind  that it is the version of the receiving rsync that affects
1218              these behaviors.)
1219
1220       -E, --executability
1221              This option causes  rsync  to  preserve  the  executability  (or
1222              non-executability) of regular files when --perms is not enabled.
1223              A regular file is considered to be executable if  at  least  one
1224              ’x’  is turned on in its permissions.  When an existing destina‐
1225              tion file’s executability differs from that of the corresponding
1226              source  file,  rsync modifies the destination file’s permissions
1227              as follows:
1228
1229              o      To make a file non-executable, rsync turns  off  all  its
1230                     ’x’ permissions.
1231
1232              o      To  make  a file executable, rsync turns on each ’x’ per‐
1233                     mission that has a corresponding ’r’ permission enabled.
1234
1235
1236              If --perms is enabled, this option is ignored.
1237
1238       -A, --acls
1239              This option causes rsync to update the destination  ACLs  to  be
1240              the same as the source ACLs.  The option also implies --perms.
1241
1242              The  source  and  destination  systems  must have compatible ACL
1243              entries for this option to work properly.  See the  --fake-super
1244              option for a way to backup and restore ACLs that are not compat‐
1245              ible.
1246
1247       -X, --xattrs
1248              This option causes rsync  to  update  the  destination  extended
1249              attributes to be the same as the source ones.
1250
1251              For  systems  that support extended-attribute namespaces, a copy
1252              being done by a super-user copies  all  namespaces  except  sys‐
1253              tem.*.   A  normal user only copies the user.* namespace.  To be
1254              able to backup and restore non-user namespaces as a normal user,
1255              see the --fake-super option.
1256
1257              The  above name filtering can be overridden by using one or more
1258              filter  options  with  the  x  modifier.  When  you  specify  an
1259              xattr-affecting filter rule, rsync requires that you do your own
1260              system/user filtering, as well as any additional  filtering  for
1261              what  xattr  names  are  copied and what names are allowed to be
1262              deleted.  For example, to skip the system namespace,  you  could
1263              specify:
1264
1265              --filter=’-x system.*’
1266
1267
1268              To  skip  all  namespaces  except  the user namespace, you could
1269              specify a negated-user match:
1270
1271              --filter=’-x! user.*’
1272
1273
1274              To prevent any attributes from being deleted, you could  specify
1275              a receiver-only rule that excludes all names:
1276
1277              --filter=’-xr *’
1278
1279
1280              Note that the -X option does not copy rsync’s special xattr val‐
1281              ues (e.g.  those used by --fake-super)  unless  you  repeat  the
1282              option  (e.g.  -XX).  This "copy all xattrs" mode cannot be used
1283              with --fake-super.
1284
1285       --chmod
1286              This option tells rsync to apply  one  or  more  comma-separated
1287              "chmod"  modes  to  the permission of the files in the transfer.
1288              The resulting value is treated as though it were the permissions
1289              that  the  sending  side supplied for the file, which means that
1290              this option can seem to have no  effect  on  existing  files  if
1291              --perms is not enabled.
1292
1293              In  addition  to  the  normal  parsing  rules  specified  in the
1294              chmod(1) manpage, you can specify an item that should only apply
1295              to  a  directory  by prefixing it with a ’D’, or specify an item
1296              that should only apply to a file by prefixing  it  with  a  ’F’.
1297              For  example, the following will ensure that all directories get
1298              marked set-gid, that no files are other-writable, that both  are
1299              user-writable  and group-writable, and that both have consistent
1300              executability across all bits:
1301
1302              --chmod=Dg+s,ug+w,Fo-w,+X
1303
1304
1305              Using octal mode numbers is also allowed:
1306
1307              --chmod=D2775,F664
1308
1309
1310              It is also legal to specify multiple --chmod  options,  as  each
1311              additional  option  is  just  appended to the list of changes to
1312              make.
1313
1314              See the --perms and --executability options for how the  result‐
1315              ing  permission  value can be applied to the files in the trans‐
1316              fer.
1317
1318       -o, --owner
1319              This option causes rsync to set the  owner  of  the  destination
1320              file  to be the same as the source file, but only if the receiv‐
1321              ing rsync is being run as the super-user (see also  the  --super
1322              and  --fake-super  options).   Without this option, the owner of
1323              new and/or transferred files are set to the invoking user on the
1324              receiving side.
1325
1326              The  preservation  of ownership will associate matching names by
1327              default, but may fall back to using the ID number in  some  cir‐
1328              cumstances (see also the --numeric-ids option for a full discus‐
1329              sion).
1330
1331       -g, --group
1332              This option causes rsync to set the  group  of  the  destination
1333              file  to  be the same as the source file.  If the receiving pro‐
1334              gram is not running as the  super-user  (or  if  --no-super  was
1335              specified),  only groups that the invoking user on the receiving
1336              side is a member of will be preserved.  Without this option, the
1337              group  is  set  to the default group of the invoking user on the
1338              receiving side.
1339
1340              The preservation of group information  will  associate  matching
1341              names  by  default,  but may fall back to using the ID number in
1342              some circumstances (see also the --numeric-ids option for a full
1343              discussion).
1344
1345       --devices
1346              This  option causes rsync to transfer character and block device
1347              files to the remote system  to  recreate  these  devices.   This
1348              option  has  no  effect if the receiving rsync is not run as the
1349              super-user (see also the --super and --fake-super options).
1350
1351       --specials
1352              This option causes rsync to transfer special files such as named
1353              sockets and fifos.
1354
1355       -D     The -D option is equivalent to --devices --specials.
1356
1357       -t, --times
1358              This  tells  rsync to transfer modification times along with the
1359              files and update them on the remote system.  Note that  if  this
1360              option  is  not  used, the optimization that excludes files that
1361              have not been modified cannot be effective; in  other  words,  a
1362              missing -t or -a will cause the next transfer to behave as if it
1363              used -I,  causing  all  files  to  be  updated  (though  rsync’s
1364              delta-transfer  algorithm  will make the update fairly efficient
1365              if the files haven’t actually changed, you’re  much  better  off
1366              using -t).
1367
1368       -O, --omit-dir-times
1369              This tells rsync to omit directories when it is preserving modi‐
1370              fication times (see --times).  If NFS is sharing the directories
1371              on the receiving side, it is a good idea to use -O.  This option
1372              is inferred if you use --backup without --backup-dir.
1373
1374              This option also has the side-effect of avoiding early  creation
1375              of  directories  in  incremental  recursion copies.  The default
1376              --inc-recursive copying normally does an  early-create  pass  of
1377              all the sub-directories in a parent directory in order for it to
1378              be able to then set the modify  time  of  the  parent  directory
1379              right away (without having to delay that until a bunch of recur‐
1380              sive copying has finished).  This early-create idiom is not nec‐
1381              essary  if directory modify times are not being preserved, so it
1382              is skipped.  Since early-create directories don’t have  accurate
1383              mode,  mtime, or ownership, the use of this option can help when
1384              someone wants to avoid these partially-finished directories.
1385
1386       -J, --omit-link-times
1387              This tells rsync to omit symlinks when it is preserving  modifi‐
1388              cation times (see --times).
1389
1390       --super
1391              This  tells  the receiving side to attempt super-user activities
1392              even if the receiving rsync wasn’t run by the super-user.  These
1393              activities  include:  preserving  users  via the --owner option,
1394              preserving all groups (not just the current user’s  groups)  via
1395              the  --groups  option,  and  copying  devices  via the --devices
1396              option.  This is useful for systems that allow  such  activities
1397              without  being  the  super-user,  and also for ensuring that you
1398              will get errors if the receiving side isn’t  being  run  as  the
1399              super-user.   To  turn off super-user activities, the super-user
1400              can use --no-super.
1401
1402       --fake-super
1403              When this option is enabled, rsync simulates super-user  activi‐
1404              ties  by  saving/restoring the privileged attributes via special
1405              extended attributes that are attached to each file (as  needed).
1406              This  includes  the  file’s  owner  and  group (if it is not the
1407              default), the file’s device info (device  &  special  files  are
1408              created  as  empty  text files), and any permission bits that we
1409              won’t allow to be set on the real file (e.g.  the real file gets
1410              u-s,g-s,o-t  for  safety) or that would limit the owner’s access
1411              (since the real super-user can always access/change a file,  the
1412              files  we  create can always be accessed/changed by the creating
1413              user).  This option also handles ACLs (if --acls was  specified)
1414              and non-user extended attributes (if --xattrs was specified).
1415
1416              This  is  a  good way to backup data without using a super-user,
1417              and to store ACLs from incompatible systems.
1418
1419              The --fake-super option only affects the side where  the  option
1420              is  used.   To  affect the remote side of a remote-shell connec‐
1421              tion, use the --remote-option (-M) option:
1422
1423                rsync -av -M--fake-super /src/ host:/dest/
1424
1425
1426              For a local copy, this option affects both the  source  and  the
1427              destination.   If  you  wish  a local copy to enable this option
1428              just for the destination files, specify -M--fake-super.  If  you
1429              wish  a  local  copy  to  enable this option just for the source
1430              files, combine --fake-super with -M--super.
1431
1432              This option is overridden by both --super and --no-super.
1433
1434              See also the "fake super" setting in  the  daemon’s  rsyncd.conf
1435              file.
1436
1437       -S, --sparse
1438              Try  to  handle  sparse  files  efficiently so they take up less
1439              space on the destination.  If combined with --inplace  the  file
1440              created  might  not end up with sparse blocks with some combina‐
1441              tions of kernel version and/or filesystem type.  If --whole-file
1442              is  in  effect  (e.g. for a local copy) then it will always work
1443              because rsync truncates  the  file  prior  to  writing  out  the
1444              updated version.
1445
1446              Note  that  versions  of  rsync older than 3.1.3 will reject the
1447              combination of --sparse and --inplace.
1448
1449       --preallocate
1450              This tells the receiver to allocate each destination file to its
1451              eventual  size before writing data to the file.  Rsync will only
1452              use the real filesystem-level preallocation support provided  by
1453              Linux’s fallocate(2) system call or Cygwin’s posix_fallocate(3),
1454              not the slow glibc implementation that writes a null  byte  into
1455              each block.
1456
1457              Without this option, larger files may not be entirely contiguous
1458              on the filesystem, but with this option rsync will probably copy
1459              more  slowly.   If  the  destination is not an extent-supporting
1460              filesystem (such as ext4, xfs, NTFS, etc.), this option may have
1461              no positive effect at all.
1462
1463              If combined with --sparse, the file will only have sparse blocks
1464              (as opposed to allocated sequences of null bytes) if the  kernel
1465              version  and filesystem type support creating holes in the allo‐
1466              cated data.
1467
1468       -n, --dry-run
1469              This makes rsync perform a  trial  run  that  doesn’t  make  any
1470              changes (and produces mostly the same output as a real run).  It
1471              is most commonly used in  combination  with  the  -v,  --verbose
1472              and/or  -i,  --itemize-changes options to see what an rsync com‐
1473              mand is going to do before one actually runs it.
1474
1475              The output of --itemize-changes is supposed to  be  exactly  the
1476              same on a dry run and a subsequent real run (barring intentional
1477              trickery and system call failures); if it isn’t, that’s  a  bug.
1478              Other  output should be mostly unchanged, but may differ in some
1479              areas.  Notably, a dry run does not send  the  actual  data  for
1480              file  transfers,  so --progress has no effect, the "bytes sent",
1481              "bytes received", "literal data", and "matched data"  statistics
1482              are  too  small,  and the "speedup" value is equivalent to a run
1483              where no file transfers were needed.
1484
1485       -W, --whole-file
1486              This option disables  rsync’s  delta-transfer  algorithm,  which
1487              causes all transferred files to be sent whole.  The transfer may
1488              be faster if this option is used when the bandwidth between  the
1489              source  and destination machines is higher than the bandwidth to
1490              disk  (especially  when  the  "disk"  is  actually  a  networked
1491              filesystem).   This is the default when both the source and des‐
1492              tination  are  specified  as  local  paths,  but  only   if   no
1493              batch-writing option is in effect.
1494
1495       --checksum-choice=STR
1496              This  option overrides the checksum algoriths.  If one algorithm
1497              name is specified, it is used for both  the  transfer  checksums
1498              and (assuming --checksum is specifed) the pre-transfer checksum‐
1499              ming. If two comma-separated names are supplied, the first  name
1500              affects  the transfer checksums, and the second name affects the
1501              pre-transfer checksumming.
1502
1503              The algorithm choices are "auto", "md4", "md5", and "none".   If
1504              "none"  is specified for the first name, the --whole-file option
1505              is forced on and no checksum verification is  performed  on  the
1506              transferred  data.   If "none" is specified for the second name,
1507              the --checksum option cannot be used. The "auto" option  is  the
1508              default,  where rsync bases its algorithm choice on the protocol
1509              version (for backward compatibility with older rsync versions).
1510
1511       -x, --one-file-system
1512              This tells rsync to avoid crossing a  filesystem  boundary  when
1513              recursing.   This  does  not limit the user’s ability to specify
1514              items to copy from multiple filesystems, just rsync’s  recursion
1515              through the hierarchy of each directory that the user specified,
1516              and also the analogous recursion on the  receiving  side  during
1517              deletion.  Also keep in mind that rsync treats a "bind" mount to
1518              the same device as being on the same filesystem.
1519
1520              If this option is repeated, rsync omits all mount-point directo‐
1521              ries  from  the copy.  Otherwise, it includes an empty directory
1522              at each mount-point it encounters (using the attributes  of  the
1523              mounted  directory  because  those of the underlying mount-point
1524              directory are inaccessible).
1525
1526              If rsync has been told to collapse symlinks (via --copy-links or
1527              --copy-unsafe-links), a symlink to a directory on another device
1528              is treated like a mount-point.  Symlinks to non-directories  are
1529              unaffected by this option.
1530
1531       --existing, --ignore-non-existing
1532              This  tells rsync to skip creating files (including directories)
1533              that do not exist yet on the destination.   If  this  option  is
1534              combined  with  the  --ignore-existing  option, no files will be
1535              updated (which can be useful if all you want  to  do  is  delete
1536              extraneous files).
1537
1538              This  option  is  a transfer rule, not an exclude, so it doesn’t
1539              affect the data that goes  into  the  file-lists,  and  thus  it
1540              doesn’t  affect  deletions.   It  just limits the files that the
1541              receiver requests to be transferred.
1542
1543       --ignore-existing
1544              This tells rsync to skip updating files that  already  exist  on
1545              the  destination  (this does not ignore existing directories, or
1546              nothing would get done).  See also --existing.
1547
1548              This option is a transfer rule, not an exclude,  so  it  doesn’t
1549              affect  the  data  that  goes  into  the file-lists, and thus it
1550              doesn’t affect deletions.  It just limits  the  files  that  the
1551              receiver requests to be transferred.
1552
1553              This  option  can  be  useful  for those doing backups using the
1554              --link-dest option when they need to continue a backup run  that
1555              got  interrupted.   Since a --link-dest run is copied into a new
1556              directory hierarchy (when it is used properly),  using  --ignore
1557              existing  will  ensure  that the already-handled files don’t get
1558              tweaked (which avoids a change in permissions on the hard-linked
1559              files).   This does mean that this option is only looking at the
1560              existing files in the destination hierarchy itself.
1561
1562       --remove-source-files
1563              This tells rsync to remove  from  the  sending  side  the  files
1564              (meaning  non-directories)  that  are a part of the transfer and
1565              have been successfully duplicated on the receiving side.
1566
1567              Note that you should only use this option on source  files  that
1568              are quiescent.  If you are using this to move files that show up
1569              in a particular directory over to another host, make  sure  that
1570              the  finished  files  get renamed into the source directory, not
1571              directly written into it, so that rsync can’t possibly  transfer
1572              a  file that is not yet fully written.  If you can’t first write
1573              the files into a different directory, you should  use  a  naming
1574              idiom  that lets rsync avoid transferring files that are not yet
1575              finished (e.g. name the  file  "foo.new"  when  it  is  written,
1576              rename  it  to  "foo"  when  it is done, and then use the option
1577              --exclude='*.new' for the rsync transfer).
1578
1579              Starting with 3.1.0, rsync will  skip  the  sender-side  removal
1580              (and  output an error) if the file’s size or modify time has not
1581              stayed unchanged.
1582
1583       --delete
1584              This tells rsync to delete extraneous files from  the  receiving
1585              side  (ones  that  aren’t on the sending side), but only for the
1586              directories that are being synchronized.  You  must  have  asked
1587              rsync to send the whole directory (e.g. "dir" or "dir/") without
1588              using a wildcard for the  directory’s  contents  (e.g.  "dir/*")
1589              since  the wildcard is expanded by the shell and rsync thus gets
1590              a request to transfer individual files, not  the  files’  parent
1591              directory.   Files  that are excluded from the transfer are also
1592              excluded from being deleted unless you use the --delete-excluded
1593              option  or  mark  the rules as only matching on the sending side
1594              (see the include/exclude modifiers in the FILTER RULES section).
1595
1596              Prior to rsync 2.6.7, this option would have  no  effect  unless
1597              --recursive  was  enabled.  Beginning with 2.6.7, deletions will
1598              also occur when --dirs (-d) is enabled, but only for directories
1599              whose contents are being copied.
1600
1601              This  option can be dangerous if used incorrectly!  It is a very
1602              good idea to first try a run using the --dry-run option (-n)  to
1603              see what files are going to be deleted.
1604
1605              If the sending side detects any I/O errors, then the deletion of
1606              any files at the destination  will  be  automatically  disabled.
1607              This  is  to  prevent temporary filesystem failures (such as NFS
1608              errors) on the sending side from causing a massive  deletion  of
1609              files  on  the  destination.   You  can  override  this with the
1610              --ignore-errors option.
1611
1612              The  --delete  option  may  be  combined   with   one   of   the
1613              --delete-WHEN    options    without   conflict,   as   well   as
1614              --delete-excluded.   However,  if  none  of  the   --delete-WHEN
1615              options  are  specified,  rsync  will choose the --delete-during
1616              algorithm  when  talking  to  rsync  3.0.0  or  newer,  and  the
1617              --delete-before  algorithm  when talking to an older rsync.  See
1618              also --delete-delay and --delete-after.
1619
1620       --delete-before
1621              Request that the file-deletions on the receiving  side  be  done
1622              before the transfer starts.  See --delete (which is implied) for
1623              more details on file-deletion.
1624
1625              Deleting before the transfer is helpful  if  the  filesystem  is
1626              tight for space and removing extraneous files would help to make
1627              the transfer possible.   However,  it  does  introduce  a  delay
1628              before the start of the transfer, and this delay might cause the
1629              transfer to timeout  (if  --timeout  was  specified).   It  also
1630              forces rsync to use the old, non-incremental recursion algorithm
1631              that requires rsync to scan all the files in the  transfer  into
1632              memory at once (see --recursive).
1633
1634       --delete-during, --del
1635              Request  that  the  file-deletions on the receiving side be done
1636              incrementally as the transfer happens.  The per-directory delete
1637              scan is done right before each directory is checked for updates,
1638              so it behaves like a more efficient  --delete-before,  including
1639              doing  the  deletions  prior  to  any per-directory filter files
1640              being updated.  This option was first  added  in  rsync  version
1641              2.6.4.   See  --delete  (which  is  implied) for more details on
1642              file-deletion.
1643
1644       --delete-delay
1645              Request that the file-deletions on the receiving  side  be  com‐
1646              puted  during  the  transfer  (like  --delete-during),  and then
1647              removed after the transfer completes.  This is useful when  com‐
1648              bined with --delay-updates and/or --fuzzy, and is more efficient
1649              than using --delete-after (but  can  behave  differently,  since
1650              --delete-after  computes  the deletions in a separate pass after
1651              all updates are done).  If the number of removed files overflows
1652              an  internal  buffer,  a  temporary  file will be created on the
1653              receiving side to hold the names (it is removed while  open,  so
1654              you  shouldn’t  see it during the transfer).  If the creation of
1655              the temporary file fails, rsync will try to fall back  to  using
1656              --delete-after  (which  it  cannot do if --recursive is doing an
1657              incremental scan).  See --delete (which  is  implied)  for  more
1658              details on file-deletion.
1659
1660       --delete-after
1661              Request  that  the  file-deletions on the receiving side be done
1662              after the transfer has completed.  This is  useful  if  you  are
1663              sending  new per-directory merge files as a part of the transfer
1664              and you want their exclusions to  take  effect  for  the  delete
1665              phase  of the current transfer.  It also forces rsync to use the
1666              old, non-incremental recursion algorithm that requires rsync  to
1667              scan  all  the  files  in  the transfer into memory at once (see
1668              --recursive).  See --delete (which is implied) for more  details
1669              on file-deletion.
1670
1671       --delete-excluded
1672              In addition to deleting the files on the receiving side that are
1673              not on the sending side, this tells rsync  to  also  delete  any
1674              files  on  the receiving side that are excluded (see --exclude).
1675              See the FILTER RULES section for a way to make individual exclu‐
1676              sions  behave this way on the receiver, and for a way to protect
1677              files from --delete-excluded.  See --delete (which  is  implied)
1678              for more details on file-deletion.
1679
1680       --ignore-missing-args
1681              When  rsync  is first processing the explicitly requested source
1682              files (e.g. command-line arguments or --files-from entries),  it
1683              is  normally  an error if the file cannot be found.  This option
1684              suppresses that error, and does not try to  transfer  the  file.
1685              This  does  not affect subsequent vanished-file errors if a file
1686              was initially found to be present and later is no longer there.
1687
1688       --delete-missing-args
1689              This option takes the behavior of (the  implied)  --ignore-miss‐
1690              ing-args  option a step farther:  each missing arg will become a
1691              deletion request of the corresponding destination  file  on  the
1692              receiving  side (should it exist).  If the destination file is a
1693              non-empty directory, it will only  be  successfully  deleted  if
1694              --force or --delete are in effect.  Other than that, this option
1695              is independent of any other type of delete processing.
1696
1697              The missing source files are represented  by  special  file-list
1698              entries  which  display as a "*missing" entry in the --list-only
1699              output.
1700
1701       --ignore-errors
1702              Tells --delete to go ahead and delete files even when there  are
1703              I/O errors.
1704
1705       --force
1706              This  option tells rsync to delete a non-empty directory when it
1707              is to be replaced by a non-directory.  This is only relevant  if
1708              deletions are not active (see --delete for details).
1709
1710              Note for older rsync versions: --force used to still be required
1711              when using --delete-after, and  it  used  to  be  non-functional
1712              unless the --recursive option was also enabled.
1713
1714       --max-delete=NUM
1715              This  tells  rsync not to delete more than NUM files or directo‐
1716              ries.  If that limit is  exceeded,  all  further  deletions  are
1717              skipped through the end of the transfer.  At the end, rsync out‐
1718              puts a warning (including a count of the skipped deletions)  and
1719              exits with an error code of 25 (unless some more important error
1720              condition also occurred).
1721
1722              Beginning with version 3.0.0, you may specify --max-delete=0  to
1723              be  warned about any extraneous files in the destination without
1724              removing any of them.  Older clients interpreted this as "unlim‐
1725              ited",  so if you don’t know what version the client is, you can
1726              use the less obvious --max-delete=-1  as  a  backward-compatible
1727              way  to  specify that no deletions be allowed (though really old
1728              versions didn’t warn when the limit was exceeded).
1729
1730       --max-size=SIZE
1731              This tells rsync to avoid transferring any file that  is  larger
1732              than  the  specified SIZE. The SIZE value can be suffixed with a
1733              string to indicate a size multiplier, and may  be  a  fractional
1734              value (e.g. "--max-size=1.5m").
1735
1736              This  option  is  a transfer rule, not an exclude, so it doesn’t
1737              affect the data that goes  into  the  file-lists,  and  thus  it
1738              doesn’t  affect  deletions.   It  just limits the files that the
1739              receiver requests to be transferred.
1740
1741              The suffixes are as  follows:  "K"  (or  "KiB")  is  a  kibibyte
1742              (1024),  "M"  (or  "MiB") is a mebibyte (1024*1024), and "G" (or
1743              "GiB") is a gibibyte (1024*1024*1024).  If you want  the  multi‐
1744              plier  to  be  1000  instead  of  1024, use "KB", "MB", or "GB".
1745              (Note: lower-case is also accepted for all values.)  Finally, if
1746              the suffix ends in either "+1" or "-1", the value will be offset
1747              by one byte in the indicated direction.
1748
1749              Examples:   --max-size=1.5mb-1    is    1499999    bytes,    and
1750              --max-size=2g+1 is 2147483649 bytes.
1751
1752              Note   that   rsync  versions  prior  to  3.1.0  did  not  allow
1753              --max-size=0.
1754
1755       --min-size=SIZE
1756              This tells rsync to avoid transferring any file that is  smaller
1757              than  the  specified  SIZE,  which  can help in not transferring
1758              small, junk files.  See the --max-size option for a  description
1759              of SIZE and other information.
1760
1761              Note   that   rsync  versions  prior  to  3.1.0  did  not  allow
1762              --min-size=0.
1763
1764       -B, --block-size=BLOCKSIZE
1765              This forces the block size used in rsync’s delta-transfer  algo‐
1766              rithm  to  a  fixed value.  It is normally selected based on the
1767              size of each file being updated.  See the technical  report  for
1768              details.
1769
1770       -e, --rsh=COMMAND
1771              This  option  allows  you  to choose an alternative remote shell
1772              program to use for communication between the  local  and  remote
1773              copies  of  rsync.  Typically, rsync is configured to use ssh by
1774              default, but you may prefer to use rsh on a local network.
1775
1776              If this option is used with [user@]host::module/path,  then  the
1777              remote  shell COMMAND will be used to run an rsync daemon on the
1778              remote host, and all  data  will  be  transmitted  through  that
1779              remote  shell  connection,  rather  than through a direct socket
1780              connection to a running rsync daemon on the  remote  host.   See
1781              the section "USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CON‐
1782              NECTION" above.
1783
1784              Command-line arguments are permitted in  COMMAND  provided  that
1785              COMMAND  is  presented  to rsync as a single argument.  You must
1786              use spaces (not tabs or other whitespace) to separate  the  com‐
1787              mand  and  args  from each other, and you can use single- and/or
1788              double-quotes to preserve spaces in an argument (but  not  back‐
1789              slashes).   Note  that  doubling  a  single-quote  inside a sin‐
1790              gle-quoted string gives you a single-quote;  likewise  for  dou‐
1791              ble-quotes  (though  you  need  to pay attention to which quotes
1792              your shell is parsing and which quotes rsync is parsing).   Some
1793              examples:
1794
1795                  -e 'ssh -p 2234'
1796                  -e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"'
1797
1798
1799              (Note  that  ssh  users  can alternately customize site-specific
1800              connect options in their .ssh/config file.)
1801
1802              You can also choose the remote shell program using the RSYNC_RSH
1803              environment  variable, which accepts the same range of values as
1804              -e.
1805
1806              See also the --blocking-io option  which  is  affected  by  this
1807              option.
1808
1809       --rsync-path=PROGRAM
1810              Use  this  to  specify  what  program is to be run on the remote
1811              machine to start-up rsync.  Often used when rsync is not in  the
1812              default            remote-shell’s           path           (e.g.
1813              --rsync-path=/usr/local/bin/rsync).  Note that  PROGRAM  is  run
1814              with  the  help of a shell, so it can be any program, script, or
1815              command sequence you’d care to run, so long as it does not  cor‐
1816              rupt  the standard-in & standard-out that rsync is using to com‐
1817              municate.
1818
1819              One tricky example is to set a different  default  directory  on
1820              the  remote  machine  for  use  with the --relative option.  For
1821              instance:
1822
1823                  rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/
1824
1825
1826       -M, --remote-option=OPTION
1827              This option is used for more advanced situations where you  want
1828              certain  effects to be limited to one side of the transfer only.
1829              For  instance,  if  you  want  to   pass   --log-file=FILE   and
1830              --fake-super to the remote system, specify it like this:
1831
1832                  rsync -av -M --log-file=foo -M--fake-super src/ dest/
1833
1834
1835              If  you  want  to have an option affect only the local side of a
1836              transfer when it normally affects both sides, send its  negation
1837              to the remote side.  Like this:
1838
1839                  rsync -av -x -M--no-x src/ dest/
1840
1841
1842              Be  cautious  using  this, as it is possible to toggle an option
1843              that will cause rsync to have a different idea about  what  data
1844              to  expect next over the socket, and that will make it fail in a
1845              cryptic fashion.
1846
1847              Note that it is best to use a separate --remote-option for  each
1848              option you want to pass.  This makes your useage compatible with
1849              the --protect-args option.  If that option is off, any spaces in
1850              your remote options will be split by the remote shell unless you
1851              take steps to protect them.
1852
1853              When performing a local transfer, the "local" side is the sender
1854              and the "remote" side is the receiver.
1855
1856              Note some versions of the popt option-parsing library have a bug
1857              in them that prevents you from using an  adjacent  arg  with  an
1858              equal   in   it   next   to   a   short   option   letter  (e.g.
1859              -M--log-file=/tmp/foo).  If this bug  affects  your  version  of
1860              popt,  you  can  use  the  version of popt that is included with
1861              rsync.
1862
1863       -C, --cvs-exclude
1864              This is a useful shorthand for excluding a broad range of  files
1865              that you often don’t want to transfer between systems. It uses a
1866              similar algorithm to CVS  to  determine  if  a  file  should  be
1867              ignored.
1868
1869              The  exclude  list is initialized to exclude the following items
1870              (these initial items are marked as perishable -- see the  FILTER
1871              RULES section):
1872
1873                     RCS   SCCS   CVS   CVS.adm   RCSLOG  cvslog.*  tags  TAGS
1874                     .make.state .nse_depinfo *~ #* .#* ,* _$* *$ *.old  *.bak
1875                     *.BAK  *.orig *.rej .del-* *.a *.olb *.o *.obj *.so *.exe
1876                     *.Z *.elc *.ln core .svn/ .git/ .hg/ .bzr/
1877
1878
1879              then, files listed in a $HOME/.cvsignore are added to  the  list
1880              and  any files listed in the CVSIGNORE environment variable (all
1881              cvsignore names are delimited by whitespace).
1882
1883              Finally, any file is ignored if it is in the same directory as a
1884              .cvsignore  file and matches one of the patterns listed therein.
1885              Unlike rsync’s filter/exclude files, these patterns are split on
1886              whitespace.  See the cvs(1) manual for more information.
1887
1888              If  you’re combining -C with your own --filter rules, you should
1889              note that these CVS excludes are appended at the end of your own
1890              rules,  regardless  of  where  the  -C  was  placed  on the com‐
1891              mand-line.  This makes them a lower priority than any rules  you
1892              specified  explicitly.   If  you want to control where these CVS
1893              excludes get inserted into your filter rules,  you  should  omit
1894              the  -C as a command-line option and use a combination of --fil‐
1895              ter=:C and  --filter=-C  (either  on  your  command-line  or  by
1896              putting  the  ":C"  and  "-C" rules into a filter file with your
1897              other rules).  The first option turns on the per-directory scan‐
1898              ning for the .cvsignore file.  The second option does a one-time
1899              import of the CVS excludes mentioned above.
1900
1901       -f, --filter=RULE
1902              This option allows you to add rules to selectively exclude  cer‐
1903              tain  files  from  the  list of files to be transferred. This is
1904              most useful in combination with a recursive transfer.
1905
1906              You may use as many --filter options on the command line as  you
1907              like  to  build  up the list of files to exclude.  If the filter
1908              contains whitespace, be sure to quote it so that the shell gives
1909              the  rule  to  rsync  as a single argument.  The text below also
1910              mentions that you can use an underscore  to  replace  the  space
1911              that separates a rule from its arg.
1912
1913              See  the  FILTER  RULES section for detailed information on this
1914              option.
1915
1916       -F     The -F option is a shorthand for adding two  --filter  rules  to
1917              your command.  The first time it is used is a shorthand for this
1918              rule:
1919
1920                 --filter='dir-merge /.rsync-filter'
1921
1922
1923              This tells rsync to look for per-directory  .rsync-filter  files
1924              that  have  been  sprinkled  through the hierarchy and use their
1925              rules to filter the files in the transfer.  If -F  is  repeated,
1926              it is a shorthand for this rule:
1927
1928                 --filter='exclude .rsync-filter'
1929
1930
1931              This  filters  out  the  .rsync-filter files themselves from the
1932              transfer.
1933
1934              See the FILTER RULES section for  detailed  information  on  how
1935              these options work.
1936
1937       --exclude=PATTERN
1938              This  option  is  a  simplified form of the --filter option that
1939              defaults to  an  exclude  rule  and  does  not  allow  the  full
1940              rule-parsing syntax of normal filter rules.
1941
1942              See  the  FILTER  RULES section for detailed information on this
1943              option.
1944
1945       --exclude-from=FILE
1946              This option is related to the --exclude option, but it specifies
1947              a  FILE  that  contains  exclude patterns (one per line).  Blank
1948              lines in the file  and  lines  starting  with  ’;’  or  ’#’  are
1949              ignored.   If  FILE  is  -,  the list will be read from standard
1950              input.
1951
1952       --include=PATTERN
1953              This option is a simplified form of  the  --filter  option  that
1954              defaults  to  an  include  rule  and  does  not  allow  the full
1955              rule-parsing syntax of normal filter rules.
1956
1957              See the FILTER RULES section for detailed  information  on  this
1958              option.
1959
1960       --include-from=FILE
1961              This option is related to the --include option, but it specifies
1962              a FILE that contains include patterns  (one  per  line).   Blank
1963              lines  in  the  file  and  lines  starting  with  ’;’ or ’#’ are
1964              ignored.  If FILE is -, the list  will  be  read  from  standard
1965              input.
1966
1967       --files-from=FILE
1968              Using  this option allows you to specify the exact list of files
1969              to transfer (as read from the specified FILE or -  for  standard
1970              input).   It  also  tweaks the default behavior of rsync to make
1971              transferring just the specified files and directories easier:
1972
1973              o      The --relative (-R) option is  implied,  which  preserves
1974                     the  path  information that is specified for each item in
1975                     the file (use --no-relative or --no-R if you want to turn
1976                     that off).
1977
1978              o      The  --dirs  (-d)  option  is  implied, which will create
1979                     directories specified in  the  list  on  the  destination
1980                     rather  than  noisily  skipping  them  (use  --no-dirs or
1981                     --no-d if you want to turn that off).
1982
1983              o      The --archive  (-a)  option’s  behavior  does  not  imply
1984                     --recursive  (-r),  so specify it explicitly, if you want
1985                     it.
1986
1987              o      These side-effects change the default state of rsync,  so
1988                     the  position  of  the  --files-from  option  on the com‐
1989                     mand-line has no bearing on how other options are  parsed
1990                     (e.g.  -a works the same before or after --files-from, as
1991                     does --no-R and all other options).
1992
1993
1994              The filenames that are read from the FILE are  all  relative  to
1995              the  source  dir  -- any leading slashes are removed and no ".."
1996              references are allowed to go higher than the  source  dir.   For
1997              example, take this command:
1998
1999                 rsync -a --files-from=/tmp/foo /usr remote:/backup
2000
2001
2002              If  /tmp/foo  contains  the  string  "bin" (or even "/bin"), the
2003              /usr/bin directory will be created as /backup/bin on the  remote
2004              host.   If  it  contains  "bin/"  (note the trailing slash), the
2005              immediate contents of the directory would also be sent  (without
2006              needing  to be explicitly mentioned in the file -- this began in
2007              version 2.6.4).  In both cases, if the -r  option  was  enabled,
2008              that  dir’s  entire hierarchy would also be transferred (keep in
2009              mind that -r needs to be specified explicitly with --files-from,
2010              since  it  is  not implied by -a).  Also note that the effect of
2011              the (enabled by default) --relative option is to duplicate  only
2012              the  path  info  that is read from the file -- it does not force
2013              the duplication of the source-spec path (/usr in this case).
2014
2015              In addition, the --files-from file can be read from  the  remote
2016              host instead of the local host if you specify a "host:" in front
2017              of the file (the host must match one end of the transfer).  As a
2018              short-cut, you can specify just a prefix of ":" to mean "use the
2019              remote end of the transfer".  For example:
2020
2021                 rsync -a --files-from=:/path/file-list src:/ /tmp/copy
2022
2023
2024              This would copy all the files specified in  the  /path/file-list
2025              file that was located on the remote "src" host.
2026
2027              If  the --iconv and --protect-args options are specified and the
2028              --files-from filenames are being sent from one host to  another,
2029              the filenames will be translated from the sending host’s charset
2030              to the receiving host’s charset.
2031
2032              NOTE: sorting the list of files in the --files-from input  helps
2033              rsync  to  be  more  efficient, as it will avoid re-visiting the
2034              path elements that are shared between adjacent entries.  If  the
2035              input  is  not  sorted, some path elements (implied directories)
2036              may end up being scanned multiple times, and rsync will  eventu‐
2037              ally  unduplicate them after they get turned into file-list ele‐
2038              ments.
2039
2040       -0, --from0
2041              This tells rsync that the rules/filenames it reads from  a  file
2042              are  terminated  by  a  null  (’\0’) character, not a NL, CR, or
2043              CR+LF.     This    affects    --exclude-from,    --include-from,
2044              --files-from, and any merged files specified in a --filter rule.
2045              It does not affect --cvs-exclude (since all names  read  from  a
2046              .cvsignore file are split on whitespace).
2047
2048       -s, --protect-args
2049              This  option  sends all filenames and most options to the remote
2050              rsync without allowing the remote shell to interpret them.  This
2051              means  that  spaces are not split in names, and any non-wildcard
2052              special characters are not translated  (such  as  ~,  $,  ;,  &,
2053              etc.).   Wildcards  are  expanded  on  the  remote host by rsync
2054              (instead of the shell doing it).
2055
2056              If you use this option with --iconv, the  args  related  to  the
2057              remote side will also be translated from the local to the remote
2058              character-set.  The translation happens  before  wild-cards  are
2059              expanded.  See also the --files-from option.
2060
2061              You  may  also  control  this  option via the RSYNC_PROTECT_ARGS
2062              environment variable.  If this variable has  a  non-zero  value,
2063              this  option  will  be  enabled by default, otherwise it will be
2064              disabled by default.  Either state is overridden by  a  manually
2065              specified positive or negative version of this option (note that
2066              --no-s and --no-protect-args are the negative versions).   Since
2067              this  option  was first introduced in 3.0.0, you’ll need to make
2068              sure it’s disabled if you ever need to interact  with  a  remote
2069              rsync that is older than that.
2070
2071              Rsync can also be configured (at build time) to have this option
2072              enabled by default (with is overridden by both  the  environment
2073              and the command-line).  This option will eventually become a new
2074              default setting at some as-yet-undetermined point in the future.
2075
2076       -T, --temp-dir=DIR
2077              This option instructs rsync to use DIR as  a  scratch  directory
2078              when  creating  temporary copies of the files transferred on the
2079              receiving side.  The default behavior is to create  each  tempo‐
2080              rary  file  in  the same directory as the associated destination
2081              file.  Beginning with rsync 3.1.1, the  temp-file  names  inside
2082              the specified DIR will not be prefixed with an extra dot (though
2083              they will still have a random suffix added).
2084
2085              This option is most often used when the receiving disk partition
2086              does  not  have  enough free space to hold a copy of the largest
2087              file in the transfer.  In  this  case  (i.e.  when  the  scratch
2088              directory  is  on a different disk partition), rsync will not be
2089              able to rename each received temporary file over the top of  the
2090              associated  destination  file,  but  instead  must  copy it into
2091              place.  Rsync does this by copying the file over the top of  the
2092              destination  file,  which  means  that the destination file will
2093              contain truncated data during this copy.  If this were not  done
2094              this  way  (even if the destination file were first removed, the
2095              data locally copied to  a  temporary  file  in  the  destination
2096              directory, and then renamed into place) it would be possible for
2097              the old file to continue taking up disk space (if someone had it
2098              open),  and  thus  there might not be enough room to fit the new
2099              version on the disk at the same time.
2100
2101              If you are using this option for reasons other than  a  shortage
2102              of   disk   space,   you   may  wish  to  combine  it  with  the
2103              --delay-updates option, which will ensure that all copied  files
2104              get put into subdirectories in the destination hierarchy, await‐
2105              ing the end of the transfer.  If you don’t have enough  room  to
2106              duplicate  all  the arriving files on the destination partition,
2107              another way to tell rsync that you aren’t overly concerned about
2108              disk  space  is  to use the --partial-dir option with a relative
2109              path; because this tells rsync that it is OK to stash off a copy
2110              of a single file in a subdir in the destination hierarchy, rsync
2111              will use the partial-dir as a staging area  to  bring  over  the
2112              copied file, and then rename it into place from there. (Specify‐
2113              ing a --partial-dir with an absolute path  does  not  have  this
2114              side-effect.)
2115
2116       -y, --fuzzy
2117              This option tells rsync that it should look for a basis file for
2118              any destination file that is  missing.   The  current  algorithm
2119              looks in the same directory as the destination file for either a
2120              file that has an identical size and modified-time,  or  a  simi‐
2121              larly-named  file.  If found, rsync uses the fuzzy basis file to
2122              try to speed up the transfer.
2123
2124              If the option is repeated, the fuzzy scan will also be  done  in
2125              any  matching  alternate destination directories that are speci‐
2126              fied via --compare-dest, --copy-dest, or --link-dest.
2127
2128              Note that the use of the --delete option might get  rid  of  any
2129              potential  fuzzy-match  files,  so  either use --delete-after or
2130              specify some filename exclusions if you need to prevent this.
2131
2132       --compare-dest=DIR
2133              This option instructs  rsync  to  use  DIR  on  the  destination
2134              machine  as an additional hierarchy to compare destination files
2135              against doing transfers (if the files are missing in the  desti‐
2136              nation  directory).  If a file is found in DIR that is identical
2137              to the sender’s file, the file will NOT be  transferred  to  the
2138              destination  directory.   This  is  useful for creating a sparse
2139              backup of just files that have changed from an  earlier  backup.
2140              This  option  is  typically used to copy into an empty (or newly
2141              created) directory.
2142
2143              Beginning in version 2.6.4, multiple --compare-dest  directories
2144              may  be  provided,  which will cause rsync to search the list in
2145              the order specified for an exact match.  If  a  match  is  found
2146              that  differs  only  in attributes, a local copy is made and the
2147              attributes updated.  If a match is not found, a basis file  from
2148              one  of  the DIRs will be selected to try to speed up the trans‐
2149              fer.
2150
2151              If DIR is a relative path, it is  relative  to  the  destination
2152              directory.  See also --copy-dest and --link-dest.
2153
2154              NOTE:  beginning  with  version  3.1.0, rsync will remove a file
2155              from a non-empty destination hierarchy  if  an  exact  match  is
2156              found  in  one  of  the compare-dest hierarchies (making the end
2157              result more closely match a fresh copy).
2158
2159       --copy-dest=DIR
2160              This option behaves like --compare-dest,  but  rsync  will  also
2161              copy  unchanged  files found in DIR to the destination directory
2162              using a local copy.  This is useful for doing transfers to a new
2163              destination  while leaving existing files intact, and then doing
2164              a flash-cutover when all files  have  been  successfully  trans‐
2165              ferred.
2166
2167              Multiple  --copy-dest  directories  may  be provided, which will
2168              cause rsync to search the list in the  order  specified  for  an
2169              unchanged  file.  If a match is not found, a basis file from one
2170              of the DIRs will be selected to try to speed up the transfer.
2171
2172              If DIR is a relative path, it is  relative  to  the  destination
2173              directory.  See also --compare-dest and --link-dest.
2174
2175       --link-dest=DIR
2176              This  option  behaves  like --copy-dest, but unchanged files are
2177              hard linked from DIR to the destination  directory.   The  files
2178              must be identical in all preserved attributes (e.g. permissions,
2179              possibly  ownership)  in  order  for  the  files  to  be  linked
2180              together.  An example:
2181
2182                rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
2183
2184
2185              If  file’s  aren’t linking, double-check their attributes.  Also
2186              check if some attributes are getting forced outside  of  rsync’s
2187              control,  such  a  mount  option  that squishes root to a single
2188              user, or mounts a removable drive with generic  ownership  (such
2189              as OS X’s "Ignore ownership on this volume" option).
2190
2191              Beginning in version 2.6.4, multiple --link-dest directories may
2192              be provided, which will cause rsync to search the  list  in  the
2193              order  specified for an exact match (there is a limit of 20 such
2194              directories).   If  a  match  is  found  that  differs  only  in
2195              attributes, a local copy is made and the attributes updated.  If
2196              a match is not found, a basis file from one of the DIRs will  be
2197              selected to try to speed up the transfer.
2198
2199              This  option  works  best when copying into an empty destination
2200              hierarchy, as existing files may get their  attributes  tweaked,
2201              and  that can affect alternate destination files via hard-links.
2202              Also, itemizing of changes can get a  bit  muddled.   Note  that
2203              prior to version 3.1.0, an alternate-directory exact match would
2204              never be found (nor linked into the destination) when a destina‐
2205              tion file already exists.
2206
2207              Note  that if you combine this option with --ignore-times, rsync
2208              will not link any files together because it only links identical
2209              files  together as a substitute for transferring the file, never
2210              as an additional check after the file is updated.
2211
2212              If DIR is a relative path, it is  relative  to  the  destination
2213              directory.  See also --compare-dest and --copy-dest.
2214
2215              Note  that  rsync  versions  prior to 2.6.1 had a bug that could
2216              prevent --link-dest from working properly for  a  non-super-user
2217              when  -o  was specified (or implied by -a).  You can work-around
2218              this bug by avoiding the -o option when sending to an old rsync.
2219
2220       -z, --compress
2221              With this option, rsync compresses the file data as it  is  sent
2222              to  the  destination  machine,  which reduces the amount of data
2223              being transmitted -- something that is useful over a  slow  con‐
2224              nection.
2225
2226              Note  that  this  option  typically  achieves better compression
2227              ratios than can be achieved by using a compressing remote  shell
2228              or  a  compressing  transport  because it takes advantage of the
2229              implicit information in the matching data blocks  that  are  not
2230              explicitly  sent  over  the connection.  This matching-data com‐
2231              pression comes at a cost of CPU, though, and can be disabled  by
2232              repeating  the  -z  option,  but only if both sides are at least
2233              version 3.1.1.
2234
2235              Note that if your version of rsync was compiled with an external
2236              zlib  (instead  of the zlib that comes packaged with rsync) then
2237              it  will  not  support  the  old-style  compression,  only   the
2238              new-style  (repeated-option)  compression.   In  the future this
2239              new-style compression will likely become the default.
2240
2241              The client rsync requests new-style compression  on  the  server
2242              via  the  --new-compress  option,  so  if  you  see  that option
2243              rejected it means that the server is not new enough  to  support
2244              -zz.   Rsync also accepts the --old-compress option for a future
2245              time when new-style compression becomes the default.
2246
2247              See the --skip-compress option for the default list of file suf‐
2248              fixes that will not be compressed.
2249
2250       --compress-level=NUM
2251              Explicitly  set  the  compression  level to use (see --compress)
2252              instead of letting it default.  If NUM is non-zero,  the  --com‐
2253              press option is implied.
2254
2255       --skip-compress=LIST
2256              Override  the list of file suffixes that will not be compressed.
2257              The LIST should be one or more file suffixes (without  the  dot)
2258              separated by slashes (/).
2259
2260              You  may specify an empty string to indicate that no file should
2261              be skipped.
2262
2263              Simple character-class matching is supported: each must  consist
2264              of a list of letters inside the square brackets (e.g. no special
2265              classes, such as "[:alpha:]", are supported, and ’-’ has no spe‐
2266              cial meaning).
2267
2268              The  characters  asterisk (*) and question-mark (?) have no spe‐
2269              cial meaning.
2270
2271              Here’s an example that specifies 6 suffixes to skip (since 1  of
2272              the 5 rules matches 2 suffixes):
2273
2274                  --skip-compress=gz/jpg/mp[34]/7z/bz2
2275
2276
2277              The default list of suffixes that will not be compressed is this
2278              (in this version of rsync):
2279
2280              7z ace avi bz2 deb gpg gz iso jpeg jpg lz lzma lzo mov  mp3  mp4
2281              ogg png rar rpm rzip tbz tgz tlz txz xz z zip
2282
2283              This  list  will be replaced by your --skip-compress list in all
2284              but one situation: a copy from a  daemon  rsync  will  add  your
2285              skipped  suffixes  to its list of non-compressing files (and its
2286              list may be configured to a different default).
2287
2288       --numeric-ids
2289              With this option rsync will transfer numeric group and user  IDs
2290              rather  than using user and group names and mapping them at both
2291              ends.
2292
2293              By default rsync will use the username and groupname  to  deter‐
2294              mine  what  ownership  to  give files. The special uid 0 and the
2295              special group 0 are never mapped via user/group  names  even  if
2296              the --numeric-ids option is not specified.
2297
2298              If a user or group has no name on the source system or it has no
2299              match on the destination system, then the numeric  ID  from  the
2300              source  system  is  used  instead.  See also the comments on the
2301              "use chroot" setting in the rsyncd.conf manpage for  information
2302              on how the chroot setting affects rsync’s ability to look up the
2303              names of the users and groups and what you can do about it.
2304
2305       --usermap=STRING, --groupmap=STRING
2306              These options allow you to specify users and groups that  should
2307              be  mapped to other values by the receiving side.  The STRING is
2308              one or more FROM:TO pairs of values separated  by  commas.   Any
2309              matching  FROM value from the sender is replaced with a TO value
2310              from the receiver.  You may specify usernames or  user  IDs  for
2311              the  FROM  and  TO  values,  and  the  FROM  value may also be a
2312              wild-card string, which will be  matched  against  the  sender’s
2313              names  (wild-cards  do  NOT match against ID numbers, though see
2314              below for why a ’*’ matches everything).  You may instead  spec‐
2315              ify a range of ID numbers via an inclusive range: LOW-HIGH.  For
2316              example:
2317
2318                --usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1:usr
2319
2320
2321              The first match in the list is the one that is used.  You should
2322              specify  all your user mappings using a single --usermap option,
2323              and/or all your group mappings using a single --groupmap option.
2324
2325              Note that the sender’s name for the 0 user  and  group  are  not
2326              transmitted  to  the  receiver, so you should either match these
2327              values using a 0, or use the names in effect  on  the  receiving
2328              side  (typically  "root").   All other FROM names match those in
2329              use on the sending side.  All TO names match those in use on the
2330              receiving side.
2331
2332              Any  IDs that do not have a name on the sending side are treated
2333              as having an empty name  for  the  purpose  of  matching.   This
2334              allows them to be matched via a "*" or using an empty name.  For
2335              instance:
2336
2337                --usermap=:nobody --groupmap=*:nobody
2338
2339
2340              When the --numeric-ids option is used, the sender does not  send
2341              any  names,  so all the IDs are treated as having an empty name.
2342              This means that you will need to specify numeric FROM values  if
2343              you want to map these nameless IDs to different values.
2344
2345              For  the  --usermap  option to have any effect, the -o (--owner)
2346              option must be used (or implied), and the receiver will need  to
2347              be  running  as a super-user (see also the --fake-super option).
2348              For the --groupmap option to have any effect, the -g  (--groups)
2349              option  must be used (or implied), and the receiver will need to
2350              have permissions to set that group.
2351
2352       --chown=USER:GROUP
2353              This option forces all files to be  owned  by  USER  with  group
2354              GROUP.   This  is  a  simpler interface than using --usermap and
2355              --groupmap directly, but it is implemented using  those  options
2356              internally, so you cannot mix them.  If either the USER or GROUP
2357              is empty, no mapping for the omitted user/group will occur.   If
2358              GROUP  is  empty, the trailing colon may be omitted, but if USER
2359              is empty, a leading colon must be supplied.
2360
2361              If you specify "--chown=foo:bar, this is  exactly  the  same  as
2362              specifying "--usermap=*:foo --groupmap=*:bar", only easier.
2363
2364       --timeout=TIMEOUT
2365              This  option allows you to set a maximum I/O timeout in seconds.
2366              If no data is transferred for the specified time then rsync will
2367              exit. The default is 0, which means no timeout.
2368
2369       --contimeout
2370              This option allows you to set the amount of time that rsync will
2371              wait for its connection to an rsync daemon to succeed.   If  the
2372              timeout is reached, rsync exits with an error.
2373
2374       --address
2375              By default rsync will bind to the wildcard address when connect‐
2376              ing to an rsync daemon.  The  --address  option  allows  you  to
2377              specify  a  specific  IP  address (or hostname) to bind to.  See
2378              also this option in the --daemon mode section.
2379
2380       --port=PORT
2381              This specifies an alternate TCP port number to use  rather  than
2382              the  default  of  873.  This is only needed if you are using the
2383              double-colon (::) syntax to connect with an rsync daemon  (since
2384              the  URL  syntax  has a way to specify the port as a part of the
2385              URL).  See also this option in the --daemon mode section.
2386
2387       --sockopts
2388              This option can provide endless fun for people who like to  tune
2389              their  systems  to  the  utmost degree. You can set all sorts of
2390              socket options which may make  transfers  faster  (or  slower!).
2391              Read  the  man page for the setsockopt() system call for details
2392              on some of the options you may be able to  set.  By  default  no
2393              special  socket options are set. This only affects direct socket
2394              connections to a remote rsync daemon.  This option  also  exists
2395              in the --daemon mode section.
2396
2397       --blocking-io
2398              This  tells  rsync  to  use blocking I/O when launching a remote
2399              shell transport.  If the remote shell is either  rsh  or  remsh,
2400              rsync  defaults  to using blocking I/O, otherwise it defaults to
2401              using non-blocking I/O.  (Note  that  ssh  prefers  non-blocking
2402              I/O.)
2403
2404       --outbuf=MODE
2405              This  sets the output buffering mode.  The mode can be None (aka
2406              Unbuffered), Line, or Block (aka Full).  You may specify as lit‐
2407              tle  as  a  single  letter  for the mode, and use upper or lower
2408              case.
2409
2410              The main use of this option is to change Full buffering to  Line
2411              buffering when rsync’s output is going to a file or pipe.
2412
2413       -i, --itemize-changes
2414              Requests  a  simple  itemized list of the changes that are being
2415              made to each file, including attribute changes.  This is exactly
2416              the  same  as  specifying --out-format='%i %n%L'.  If you repeat
2417              the option, unchanged files will also be output, but only if the
2418              receiving  rsync is at least version 2.6.7 (you can use -vv with
2419              older versions of rsync, but that also turns on  the  output  of
2420              other verbose messages).
2421
2422              The  "%i"  escape  has a cryptic output that is 11 letters long.
2423              The general format is like the string YXcstpoguax,  where  Y  is
2424              replaced  by the type of update being done, X is replaced by the
2425              file-type, and the other letters represent attributes  that  may
2426              be output if they are being modified.
2427
2428              The update types that replace the Y are as follows:
2429
2430              o      A  < means that a file is being transferred to the remote
2431                     host (sent).
2432
2433              o      A > means that a file is being transferred to  the  local
2434                     host (received).
2435
2436              o      A  c  means that a local change/creation is occurring for
2437                     the item (such as the creation  of  a  directory  or  the
2438                     changing of a symlink, etc.).
2439
2440              o      A  h  means  that the item is a hard link to another item
2441                     (requires --hard-links).
2442
2443              o      A . means that the item is not being updated  (though  it
2444                     might have attributes that are being modified).
2445
2446              o      A  * means that the rest of the itemized-output area con‐
2447                     tains a message (e.g. "deleting").
2448
2449
2450              The file-types that replace the X are: f for a file, a d  for  a
2451              directory,  an  L for a symlink, a D for a device, and a S for a
2452              special file (e.g. named sockets and fifos).
2453
2454              The other letters in the string above  are  the  actual  letters
2455              that  will be output if the associated attribute for the item is
2456              being updated or a "." for no change.  Three exceptions to  this
2457              are:  (1)  a newly created item replaces each letter with a "+",
2458              (2) an identical item replaces the dots with spaces, and (3)  an
2459              unknown attribute replaces each letter with a "?" (this can hap‐
2460              pen when talking to an older rsync).
2461
2462              The attribute that is associated with each letter is as follows:
2463
2464              o      A c means either that a  regular  file  has  a  different
2465                     checksum (requires --checksum) or that a symlink, device,
2466                     or special file has a changed value.  Note  that  if  you
2467                     are sending files to an rsync prior to 3.0.1, this change
2468                     flag will be present only for checksum-differing  regular
2469                     files.
2470
2471              o      A  s  means  the  size of a regular file is different and
2472                     will be updated by the file transfer.
2473
2474              o      A t means the modification time is different and is being
2475                     updated  to  the  sender’s  value (requires --times).  An
2476                     alternate value of T means  that  the  modification  time
2477                     will  be  set  to the transfer time, which happens when a
2478                     file/symlink/device is updated without --times and when a
2479                     symlink  is  changed and the receiver can’t set its time.
2480                     (Note: when using an rsync 3.0.0 client,  you  might  see
2481                     the  s  flag combined with t instead of the proper T flag
2482                     for this time-setting failure.)
2483
2484              o      A p means the permissions are  different  and  are  being
2485                     updated to the sender’s value (requires --perms).
2486
2487              o      An o means the owner is different and is being updated to
2488                     the sender’s value (requires --owner and super-user priv‐
2489                     ileges).
2490
2491              o      A  g means the group is different and is being updated to
2492                     the sender’s value (requires --group and the authority to
2493                     set the group).
2494
2495              o      The u slot is reserved for future use.
2496
2497              o      The a means that the ACL information changed.
2498
2499              o      The  x  means  that  the  extended  attribute information
2500                     changed.
2501
2502
2503              One other output is possible:  when  deleting  files,  the  "%i"
2504              will  output  the string "*deleting" for each item that is being
2505              removed (assuming that you are talking to a recent enough  rsync
2506              that  it  logs deletions instead of outputting them as a verbose
2507              message).
2508
2509       --out-format=FORMAT
2510              This allows you to specify exactly what the rsync client outputs
2511              to  the user on a per-update basis.  The format is a text string
2512              containing embedded single-character escape  sequences  prefixed
2513              with  a  percent  (%) character.   A default format of "%n%L" is
2514              assumed if either --info=name or -v is specified (this tells you
2515              just  the  name of the file and, if the item is a link, where it
2516              points).  For a full list of the possible escape characters, see
2517              the "log format" setting in the rsyncd.conf manpage.
2518
2519              Specifying  the  --out-format  option  implies  the  --info=name
2520              option, which will  mention  each  file,  dir,  etc.  that  gets
2521              updated  in  a  significant way (a transferred file, a recreated
2522              symlink/device, or a touched directory).  In  addition,  if  the
2523              itemize-changes  escape  (%i) is included in the string (e.g. if
2524              the --itemize-changes option was used),  the  logging  of  names
2525              increases  to  mention  any  item that is changed in any way (as
2526              long as the receiving side is at least 2.6.4).  See the  --item‐
2527              ize-changes option for a description of the output of "%i".
2528
2529              Rsync will output the out-format string prior to a file’s trans‐
2530              fer unless one of the transfer-statistic escapes  is  requested,
2531              in  which  case  the  logging  is  done at the end of the file’s
2532              transfer.  When this late logging is in effect and --progress is
2533              also  specified,  rsync  will  also  output the name of the file
2534              being transferred prior to its progress  information  (followed,
2535              of course, by the out-format output).
2536
2537       --log-file=FILE
2538              This  option  causes  rsync  to  log what it is doing to a file.
2539              This is similar to the logging that a daemon does,  but  can  be
2540              requested  for  the  client  side  and/or  the  server side of a
2541              non-daemon transfer.  If specified as a client option,  transfer
2542              logging will be enabled with a default format of "%i %n%L".  See
2543              the --log-file-format option if you wish to override this.
2544
2545              Here’s a example command that requests the remote  side  to  log
2546              what is happening:
2547
2548                rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/
2549
2550
2551              This  is  very  useful  if you need to debug why a connection is
2552              closing unexpectedly.
2553
2554       --log-file-format=FORMAT
2555              This allows you to specify exactly what  per-update  logging  is
2556              put into the file specified by the --log-file option (which must
2557              also be specified for this option to have any effect).   If  you
2558              specify  an empty string, updated files will not be mentioned in
2559              the log file.  For a list of the possible escape characters, see
2560              the "log format" setting in the rsyncd.conf manpage.
2561
2562              The  default  FORMAT  used  if  --log-file is specified and this
2563              option is not is ’%i %n%L’.
2564
2565       --stats
2566              This tells rsync to print a verbose set  of  statistics  on  the
2567              file  transfer,  allowing  you  to  tell  how  effective rsync’s
2568              delta-transfer algorithm is  for  your  data.   This  option  is
2569              equivalent  to --info=stats2 if combined with 0 or 1 -v options,
2570              or --info=stats3 if combined with 2 or more -v options.
2571
2572              The current statistics are as follows:
2573
2574              o      Number of files is the  count  of  all  "files"  (in  the
2575                     generic  sense),  which  includes  directories, symlinks,
2576                     etc.  The total count will  be  followed  by  a  list  of
2577                     counts by filetype (if the total is non-zero).  For exam‐
2578                     ple: "(reg: 5, dir: 3, link:  2,  dev:  1,  special:  1)"
2579                     lists  the  totals  for  regular files, directories, sym‐
2580                     links, devices, and special files.  If any of value is 0,
2581                     it is completely omitted from the list.
2582
2583              o      Number  of created files is the count of how many "files"
2584                     (generic sense) were created  (as  opposed  to  updated).
2585                     The  total  count will be followed by a list of counts by
2586                     filetype (if the total is non-zero).
2587
2588              o      Number of deleted files is the count of how many  "files"
2589                     (generic  sense)  were  created  (as opposed to updated).
2590                     The total count will be followed by a list of  counts  by
2591                     filetype (if the total is non-zero).  Note that this line
2592                     is only output if deletions are in effect,  and  only  if
2593                     protocol 31 is being used (the default for rsync 3.1.x).
2594
2595              o      Number  of regular files transferred is the count of nor‐
2596                     mal files that were updated  via  rsync’s  delta-transfer
2597                     algorithm,  which  does  not include dirs, symlinks, etc.
2598                     Note that rsync 3.1.0 added the word "regular" into  this
2599                     heading.
2600
2601              o      Total file size is the total sum of all file sizes in the
2602                     transfer.  This does not count any size  for  directories
2603                     or special files, but does include the size of symlinks.
2604
2605              o      Total transferred file size is the total sum of all files
2606                     sizes for just the transferred files.
2607
2608              o      Literal data is how much unmatched  file-update  data  we
2609                     had  to  send  to  the  receiver  for  it to recreate the
2610                     updated files.
2611
2612              o      Matched data is how much data the  receiver  got  locally
2613                     when recreating the updated files.
2614
2615              o      File list size is how big the file-list data was when the
2616                     sender sent it to the receiver.  This is smaller than the
2617                     in-memory  size for the file list due to some compressing
2618                     of duplicated data when rsync sends the list.
2619
2620              o      File list generation time is the number of  seconds  that
2621                     the sender spent creating the file list.  This requires a
2622                     modern rsync on the sending side for this to be present.
2623
2624              o      File list transfer time is the number of seconds that the
2625                     sender spent sending the file list to the receiver.
2626
2627              o      Total bytes sent is the count of all the bytes that rsync
2628                     sent from the client side to the server side.
2629
2630              o      Total bytes received is  the  count  of  all  non-message
2631                     bytes  that  rsync  received  by the client side from the
2632                     server side.  "Non-message" bytes  means  that  we  don’t
2633                     count  the  bytes  for  a verbose message that the server
2634                     sent to us, which makes the stats more consistent.
2635
2636
2637       -8, --8-bit-output
2638              This tells rsync to leave all high-bit characters  unescaped  in
2639              the  output  instead  of  trying  to test them to see if they’re
2640              valid in the current locale and escaping the invalid ones.   All
2641              control  characters (but never tabs) are always escaped, regard‐
2642              less of this option’s setting.
2643
2644              The escape idiom that started in 2.6.7 is to  output  a  literal
2645              backslash  (\)  and a hash (#), followed by exactly 3 octal dig‐
2646              its.  For example, a newline would output as "\#012".  A literal
2647              backslash that is in a filename is not escaped unless it is fol‐
2648              lowed by a hash and 3 digits (0-9).
2649
2650       -h, --human-readable
2651              Output numbers in a more human-readable  format.   There  are  3
2652              possible  levels:   (1)  output numbers with a separator between
2653              each set of 3 digits (either a comma or a period,  depending  on
2654              if the decimal point is represented by a period or a comma); (2)
2655              output numbers in units of 1000 (with  a  character  suffix  for
2656              larger units -- see below); (3) output numbers in units of 1024.
2657
2658              The default is human-readable level 1.  Each -h option increases
2659              the level by one.  You can take the level down to 0  (to  output
2660              numbers  as  pure  digits)  by specifing the --no-human-readable
2661              (--no-h) option.
2662
2663              The unit letters that are appended in levels  2  and  3  are:  K
2664              (kilo),  M  (mega),  G  (giga),  or  T  (tera).   For example, a
2665              1234567-byte file would output as  1.23M  in  level-2  (assuming
2666              that a period is your local decimal point).
2667
2668              Backward  compatibility  note:  versions of rsync prior to 3.1.0
2669              do not support human-readable level 1, and they default to level
2670              0.  Thus, specifying one or two -h options will behave in a com‐
2671              parable manner in old and new versions as  long  as  you  didn’t
2672              specify  a  --no-h  option prior to one or more -h options.  See
2673              the --list-only option for one difference.
2674
2675       --partial
2676              By default, rsync will delete any partially transferred file  if
2677              the  transfer  is  interrupted. In some circumstances it is more
2678              desirable to keep partially transferred files. Using the  --par‐
2679              tial  option  tells  rsync to keep the partial file which should
2680              make a subsequent transfer of the rest of the file much faster.
2681
2682       --partial-dir=DIR
2683              A better way to keep partial files than the --partial option  is
2684              to  specify  a  DIR  that  will be used to hold the partial data
2685              (instead of writing it out to the  destination  file).   On  the
2686              next  transfer,  rsync will use a file found in this dir as data
2687              to speed up the resumption of the transfer and  then  delete  it
2688              after it has served its purpose.
2689
2690              Note  that  if  --whole-file is specified (or implied), any par‐
2691              tial-dir file that is found for a file  that  is  being  updated
2692              will  simply  be  removed  (since rsync is sending files without
2693              using rsync’s delta-transfer algorithm).
2694
2695              Rsync will create the DIR if it is missing (just the last dir --
2696              not  the whole path).  This makes it easy to use a relative path
2697              (such as "--partial-dir=.rsync-partial") to  have  rsync  create
2698              the  partial-directory  in the destination file’s directory when
2699              needed, and then remove  it  again  when  the  partial  file  is
2700              deleted.
2701
2702              If the partial-dir value is not an absolute path, rsync will add
2703              an exclude rule at the end of all your existing excludes.   This
2704              will prevent the sending of any partial-dir files that may exist
2705              on the sending side, and will also prevent the untimely deletion
2706              of  partial-dir  items  on  the receiving side.  An example: the
2707              above --partial-dir option would add the equivalent of  "-f  '-p
2708              .rsync-partial/'" at the end of any other filter rules.
2709
2710              If you are supplying your own exclude rules, you may need to add
2711              your own exclude/hide/protect rule for the  partial-dir  because
2712              (1)  the  auto-added  rule may be ineffective at the end of your
2713              other rules, or (2) you may wish  to  override  rsync’s  exclude
2714              choice.   For  instance,  if you want to make rsync clean-up any
2715              left-over partial-dirs that may  be  lying  around,  you  should
2716              specify --delete-after and add a "risk" filter rule, e.g.  -f 'R
2717              .rsync-partial/'.  (Avoid using --delete-before or --delete-dur‐
2718              ing unless you don’t need rsync to use any of the left-over par‐
2719              tial-dir data during the current run.)
2720
2721              IMPORTANT: the --partial-dir should not  be  writable  by  other
2722              users or it is a security risk.  E.g. AVOID "/tmp".
2723
2724              You  can  also  set  the partial-dir value the RSYNC_PARTIAL_DIR
2725              environment variable.  Setting this in the environment does  not
2726              force  --partial to be enabled, but rather it affects where par‐
2727              tial files  go  when  --partial  is  specified.   For  instance,
2728              instead of using --partial-dir=.rsync-tmp along with --progress,
2729              you could set RSYNC_PARTIAL_DIR=.rsync-tmp in  your  environment
2730              and  then  just  use  the  -P  option  to turn on the use of the
2731              .rsync-tmp dir for partial transfers.  The only times  that  the
2732              --partial  option  does  not look for this environment value are
2733              (1) when --inplace was specified (since --inplace conflicts with
2734              --partial-dir),  and (2) when --delay-updates was specified (see
2735              below).
2736
2737              For the purposes of the daemon-config’s  "refuse  options"  set‐
2738              ting, --partial-dir does not imply --partial.  This is so that a
2739              refusal of the --partial option can  be  used  to  disallow  the
2740              overwriting  of destination files with a partial transfer, while
2741              still allowing the safer idiom provided by --partial-dir.
2742
2743       --delay-updates
2744              This option puts the temporary file from each updated file  into
2745              a holding directory until the end of the transfer, at which time
2746              all the files are renamed into place in rapid succession.   This
2747              attempts to make the updating of the files a little more atomic.
2748              By default the files are placed into a directory named  ".~tmp~"
2749              in  each  file’s  destination directory, but if you’ve specified
2750              the --partial-dir option, that directory will be  used  instead.
2751              See  the  comments in the --partial-dir section for a discussion
2752              of how this ".~tmp~" dir will be excluded from the transfer, and
2753              what  you  can do if you want rsync to cleanup old ".~tmp~" dirs
2754              that might  be  lying  around.   Conflicts  with  --inplace  and
2755              --append.
2756
2757              This  option uses more memory on the receiving side (one bit per
2758              file transferred) and also requires enough free  disk  space  on
2759              the receiving side to hold an additional copy of all the updated
2760              files.  Note also that you should not use an  absolute  path  to
2761              --partial-dir  unless (1) there is no chance of any of the files
2762              in the transfer having the same  name  (since  all  the  updated
2763              files  will  be put into a single directory if the path is abso‐
2764              lute) and (2) there are no mount points in the hierarchy  (since
2765              the  delayed  updates  will  fail  if they can’t be renamed into
2766              place).
2767
2768              See also the "atomic-rsync" perl script in the "support"  subdir
2769              for  an  update  algorithm  that  is  even  more atomic (it uses
2770              --link-dest and a parallel hierarchy of files).
2771
2772       -m, --prune-empty-dirs
2773              This option tells the receiving rsync to get rid of empty direc‐
2774              tories  from  the  file-list,  including nested directories that
2775              have no non-directory children.  This is useful for avoiding the
2776              creation  of  a  bunch  of  useless directories when the sending
2777              rsync  is  recursively  scanning  a  hierarchy  of  files  using
2778              include/exclude/filter rules.
2779
2780              Note  that  the  use  of  transfer rules, such as the --min-size
2781              option, does not affect what goes into the file list,  and  thus
2782              does not leave directories empty, even if none of the files in a
2783              directory match the transfer rule.
2784
2785              Because the file-list is actually being pruned, this option also
2786              affects  what  directories  get deleted when a delete is active.
2787              However, keep in mind that excluded files  and  directories  can
2788              prevent existing items from being deleted due to an exclude both
2789              hiding source files and protecting destination files.   See  the
2790              perishable filter-rule option for how to avoid this.
2791
2792              You  can  prevent  the pruning of certain empty directories from
2793              the file-list by using a global "protect" filter.  For instance,
2794              this  option would ensure that the directory "emptydir" was kept
2795              in the file-list:
2796
2797              --filter ’protect emptydir/’
2798
2799
2800              Here’s an example that copies all .pdf  files  in  a  hierarchy,
2801              only  creating the necessary destination directories to hold the
2802              .pdf files, and ensures that any superfluous files and  directo‐
2803              ries  in  the  destination  are removed (note the hide filter of
2804              non-directories being used instead of an exclude):
2805
2806              rsync -avm --del --include=’*.pdf’ -f ’hide,! */’ src/ dest
2807
2808
2809              If you didn’t want to remove superfluous destination files,  the
2810              more  time-honored  options  of  "--include='*/'  --exclude='*'"
2811              would work fine in place of the hide-filter  (if  that  is  more
2812              natural to you).
2813
2814       --progress
2815              This  option  tells  rsync  to  print  information  showing  the
2816              progress of the transfer. This gives a bored user  something  to
2817              watch.   With  a  modern  rsync  this  is the same as specifying
2818              --info=flist2,name,progress, but any user-supplied settings  for
2819              those   info   flags   takes   precedence  (e.g.  "--info=flist0
2820              --progress").
2821
2822              While rsync  is  transferring  a  regular  file,  it  updates  a
2823              progress line that looks like this:
2824
2825                    782448  63%  110.64kB/s    0:00:04
2826
2827
2828              In  this example, the receiver has reconstructed 782448 bytes or
2829              63% of the sender’s file, which is being reconstructed at a rate
2830              of  110.64 kilobytes per second, and the transfer will finish in
2831              4 seconds if the current rate is maintained until the end.
2832
2833              These statistics can be  misleading  if  rsync’s  delta-transfer
2834              algorithm is in use.  For example, if the sender’s file consists
2835              of the basis file followed by additional data, the reported rate
2836              will  probably  drop  dramatically when the receiver gets to the
2837              literal data, and the transfer will probably take much longer to
2838              finish  than  the  receiver  estimated  as  it was finishing the
2839              matched part of the file.
2840
2841              When the file transfer finishes,  rsync  replaces  the  progress
2842              line with a summary line that looks like this:
2843
2844                    1,238,099 100%  146.38kB/s    0:00:08  (xfr#5, to-chk=169/396)
2845
2846
2847              In this example, the file was 1,238,099 bytes long in total, the
2848              average rate of transfer for the whole file was 146.38 kilobytes
2849              per  second  over the 8 seconds that it took to complete, it was
2850              the 5th transfer of a regular file during the current rsync ses‐
2851              sion, and there are 169 more files for the receiver to check (to
2852              see if they are up-to-date or not)  remaining  out  of  the  396
2853              total files in the file-list.
2854
2855              In  an  incremental  recursion  scan, rsync won’t know the total
2856              number of files in the file-list until it reaches  the  ends  of
2857              the scan, but since it starts to transfer files during the scan,
2858              it will display a line with the text "ir-chk"  (for  incremental
2859              recursion  check)  instead  of  "to-chk" until the point that it
2860              knows the full size of the list, at which point it  will  switch
2861              to using "to-chk".  Thus, seeing "ir-chk" lets you know that the
2862              total count of files in the file list is still going to increase
2863              (and  each  time it does, the count of files left to check  will
2864              increase by the number of the files added to the list).
2865
2866       -P     The -P option is equivalent to --partial --progress.   Its  pur‐
2867              pose  is to make it much easier to specify these two options for
2868              a long transfer that may be interrupted.
2869
2870              There is also a --info=progress2 option that outputs  statistics
2871              based  on the whole transfer, rather than individual files.  Use
2872              this flag without outputting a filename (e.g. avoid -v or  spec‐
2873              ify  --info=name0)  if you want to see how the transfer is doing
2874              without scrolling the screen with a lot of  names.   (You  don’t
2875              need   to   specify  the  --progress  option  in  order  to  use
2876              --info=progress2.)
2877
2878       --password-file=FILE
2879              This option allows you to provide a password  for  accessing  an
2880              rsync daemon via a file or via standard input if FILE is -.  The
2881              file should contain just the password on  the  first  line  (all
2882              other lines are ignored).  Rsync will exit with an error if FILE
2883              is world readable  or  if  a  root-run  rsync  command  finds  a
2884              non-root-owned file.
2885
2886              This  option does not supply a password to a remote shell trans‐
2887              port such as ssh; to learn how to do that,  consult  the  remote
2888              shell’s  documentation.   When accessing an rsync daemon using a
2889              remote shell as the  transport,  this  option  only  comes  into
2890              effect  after the remote shell finishes its authentication (i.e.
2891              if you have also specified a password  in  the  daemon’s  config
2892              file).
2893
2894       --list-only
2895              This  option will cause the source files to be listed instead of
2896              transferred.  This option is  inferred  if  there  is  a  single
2897              source  arg  and no destination specified, so its main uses are:
2898              (1) to turn a copy command that includes a destination arg  into
2899              a  file-listing  command, or (2) to be able to specify more than
2900              one source arg (note: be sure to include the destination).  Cau‐
2901              tion:  keep  in  mind  that  a  source  arg  with a wild-card is
2902              expanded by the shell into multiple args, so it is never safe to
2903              try to list such an arg without using this option.  For example:
2904
2905                  rsync -av --list-only foo* dest/
2906
2907
2908              Starting  with  rsync 3.1.0, the sizes output by --list-only are
2909              affected by the --human-readable option.  By default  they  will
2910              contain  digit separators, but higher levels of readability will
2911              output the sizes with unit suffixes.  Note also that the  column
2912              width for the size output has increased from 11 to 14 characters
2913              for all human-readable levels.  Use --no-h if you want just dig‐
2914              its in the sizes, and the old column width of 11 characters.
2915
2916              Compatibility  note:   when requesting a remote listing of files
2917              from an rsync that is version 2.6.3 or older, you may  encounter
2918              an  error  if  you  ask  for  a  non-recursive listing.  This is
2919              because a file listing implies the --dirs  option  w/o  --recur‐
2920              sive,  and  older  rsyncs don’t have that option.  To avoid this
2921              problem, either specify the --no-dirs option (if you don’t  need
2922              to  expand  a  directory’s  content),  or  turn on recursion and
2923              exclude the content of subdirectories: -r --exclude='/*/*'.
2924
2925       --bwlimit=RATE
2926              This option allows you to specify the maximum transfer rate  for
2927              the  data  sent  over the socket, specified in units per second.
2928              The RATE value can be suffixed with a string to indicate a  size
2929              multiplier,    and    may    be   a   fractional   value   (e.g.
2930              "--bwlimit=1.5m").  If no suffix is specified, the value will be
2931              assumed  to  be  in  units of 1024 bytes (as if "K" or "KiB" had
2932              been appended).  See the --max-size option for a description  of
2933              all the available suffixes. A value of zero specifies no limit.
2934
2935              For  backward-compatibility  reasons,  the  rate  limit  will be
2936              rounded to the nearest KiB unit, so no rate  smaller  than  1024
2937              bytes per second is possible.
2938
2939              Rsync  writes  data  over  the socket in blocks, and this option
2940              both limits the size of the blocks that rsync writes, and  tries
2941              to  keep the average transfer rate at the requested limit.  Some
2942              "burstiness" may be seen where rsync writes out a block of  data
2943              and then sleeps to bring the average rate into compliance.
2944
2945              Due to the internal buffering of data, the --progress option may
2946              not be an accurate reflection on how  fast  the  data  is  being
2947              sent.   This  is because some files can show up as being rapidly
2948              sent when the data is quickly buffered, while other can show  up
2949              as  very  slow  when  the  flushing of the output buffer occurs.
2950              This may be fixed in a future version.
2951
2952       --write-batch=FILE
2953              Record a file that can later be  applied  to  another  identical
2954              destination  with --read-batch. See the "BATCH MODE" section for
2955              details, and also the --only-write-batch option.
2956
2957       --only-write-batch=FILE
2958              Works like --write-batch, except that no updates are made on the
2959              destination  system  when  creating  the  batch.   This lets you
2960              transport the changes to the destination system via  some  other
2961              means and then apply the changes via --read-batch.
2962
2963              Note  that you can feel free to write the batch directly to some
2964              portable media: if this media fills to capacity before  the  end
2965              of the transfer, you can just apply that partial transfer to the
2966              destination and repeat the whole process to get the rest of  the
2967              changes  (as long as you don’t mind a partially updated destina‐
2968              tion system while the multi-update cycle is happening).
2969
2970              Also note that you only save bandwidth when pushing changes to a
2971              remote  system  because  this  allows  the  batched  data  to be
2972              diverted from the sender into the batch file without  having  to
2973              flow  over the wire to the receiver (when pulling, the sender is
2974              remote, and thus can’t write the batch).
2975
2976       --read-batch=FILE
2977              Apply all of the changes stored in FILE, a file previously  gen‐
2978              erated  by  --write-batch.  If FILE is -, the batch data will be
2979              read from standard input.  See  the  "BATCH  MODE"  section  for
2980              details.
2981
2982       --protocol=NUM
2983              Force  an older protocol version to be used.  This is useful for
2984              creating a batch file that is compatible with an  older  version
2985              of  rsync.   For instance, if rsync 2.6.4 is being used with the
2986              --write-batch option, but rsync 2.6.3 is what will  be  used  to
2987              run the --read-batch option, you should use "--protocol=28" when
2988              creating the batch file to force the older protocol  version  to
2989              be  used in the batch file (assuming you can’t upgrade the rsync
2990              on the reading system).
2991
2992       --iconv=CONVERT_SPEC
2993              Rsync can convert filenames between character  sets  using  this
2994              option.   Using a CONVERT_SPEC of "." tells rsync to look up the
2995              default character-set via the locale setting.  Alternately,  you
2996              can  fully specify what conversion to do by giving a local and a
2997              remote   charset   separated   by   a   comma   in   the   order
2998              --iconv=LOCAL,REMOTE,  e.g.   --iconv=utf8,iso88591.  This order
2999              ensures that the option will stay the same whether you’re  push‐
3000              ing   or   pulling  files.   Finally,  you  can  specify  either
3001              --no-iconv or a CONVERT_SPEC of "-" to turn off any  conversion.
3002              The  default  setting  of  this option is site-specific, and can
3003              also be affected via the RSYNC_ICONV environment variable.
3004
3005              For a list of what charset names your local iconv  library  sup‐
3006              ports, you can run "iconv --list".
3007
3008              If you specify the --protect-args option (-s), rsync will trans‐
3009              late the filenames you specify  on  the  command-line  that  are
3010              being  sent  to  the  remote  host.   See  also the --files-from
3011              option.
3012
3013              Note that rsync does not do any conversion of  names  in  filter
3014              files  (including  include/exclude  files).   It is up to you to
3015              ensure that you’re specifying matching rules that can  match  on
3016              both sides of the transfer.  For instance, you can specify extra
3017              include/exclude rules if there are filename differences  on  the
3018              two sides that need to be accounted for.
3019
3020              When  you  pass an --iconv option to an rsync daemon that allows
3021              it, the daemon uses the charset specified in its "charset"  con‐
3022              figuration  parameter regardless of the remote charset you actu‐
3023              ally pass.  Thus, you may feel free to specify  just  the  local
3024              charset for a daemon transfer (e.g. --iconv=utf8).
3025
3026       -4, --ipv4 or -6, --ipv6
3027              Tells  rsync  to  prefer  IPv4/IPv6 when creating sockets.  This
3028              only affects sockets that rsync has direct control over, such as
3029              the  outgoing  socket  when directly contacting an rsync daemon.
3030              See also these options in the --daemon mode section.
3031
3032              If rsync was complied  without  support  for  IPv6,  the  --ipv6
3033              option  will have no effect.  The --version output will tell you
3034              if this is the case.
3035
3036       --checksum-seed=NUM
3037              Set the checksum seed to the integer NUM.  This 4 byte  checksum
3038              seed is included in each block and MD4 file checksum calculation
3039              (the more modern MD5 file  checksums  don’t  use  a  seed).   By
3040              default  the  checksum  seed  is  generated  by  the  server and
3041              defaults to the current time() .  This option is used to  set  a
3042              specific  checksum  seed,  which is useful for applications that
3043              want repeatable block checksums, or in the case where  the  user
3044              wants  a  more  random  checksum  seed.  Setting NUM to 0 causes
3045              rsync to use the default of time() for checksum seed.
3046

DAEMON OPTIONS

3048       The options allowed when starting an rsync daemon are as follows:
3049
3050       --daemon
3051              This tells rsync that it is to run as a daemon.  The daemon  you
3052              start  running  may  be accessed using an rsync client using the
3053              host::module or rsync://host/module/ syntax.
3054
3055              If standard input is a socket then rsync will assume that it  is
3056              being  run  via inetd, otherwise it will detach from the current
3057              terminal and become a background daemon.  The daemon  will  read
3058              the  config  file (rsyncd.conf) on each connect made by a client
3059              and respond to requests accordingly.  See the rsyncd.conf(5) man
3060              page for more details.
3061
3062       --address
3063              By default rsync will bind to the wildcard address when run as a
3064              daemon with the --daemon option.  The  --address  option  allows
3065              you  to  specify a specific IP address (or hostname) to bind to.
3066              This makes virtual hosting  possible  in  conjunction  with  the
3067              --config  option.   See  also the "address" global option in the
3068              rsyncd.conf manpage.
3069
3070       --bwlimit=RATE
3071              This option allows you to specify the maximum transfer rate  for
3072              the data the daemon sends over the socket.  The client can still
3073              specify a smaller --bwlimit value, but no larger value  will  be
3074              allowed.  See the client version of this option (above) for some
3075              extra details.
3076
3077       --config=FILE
3078              This specifies an alternate config file than the default.   This
3079              is  only  relevant  when  --daemon is specified.  The default is
3080              /etc/rsyncd.conf unless the daemon  is  running  over  a  remote
3081              shell program and the remote user is not the super-user; in that
3082              case the default is rsyncd.conf in the current directory  (typi‐
3083              cally $HOME).
3084
3085       -M, --dparam=OVERRIDE
3086              This  option  can  be used to set a daemon-config parameter when
3087              starting up rsync in daemon mode.  It is  equivalent  to  adding
3088              the  parameter  at  the  end of the global settings prior to the
3089              first module’s definition.  The parameter names can be specified
3090              without spaces, if you so desire.  For instance:
3091
3092                  rsync --daemon -M pidfile=/path/rsync.pid
3093
3094
3095       --no-detach
3096              When  running  as  a  daemon, this option instructs rsync to not
3097              detach itself and become a background process.  This  option  is
3098              required  when  running  as a service on Cygwin, and may also be
3099              useful when rsync is supervised by a program such as daemontools
3100              or AIX’s System Resource Controller.  --no-detach is also recom‐
3101              mended when rsync is run under a debugger.  This option  has  no
3102              effect if rsync is run from inetd or sshd.
3103
3104       --port=PORT
3105              This  specifies  an  alternate TCP port number for the daemon to
3106              listen on rather than the default of 873.  See also  the  "port"
3107              global option in the rsyncd.conf manpage.
3108
3109       --log-file=FILE
3110              This  option  tells  the  rsync daemon to use the given log-file
3111              name instead of using the "log file" setting in the config file.
3112
3113       --log-file-format=FORMAT
3114              This option tells the rsync  daemon  to  use  the  given  FORMAT
3115              string  instead  of using the "log format" setting in the config
3116              file.  It also enables "transfer logging" unless the  string  is
3117              empty, in which case transfer logging is turned off.
3118
3119       --sockopts
3120              This  overrides  the  socket  options setting in the rsyncd.conf
3121              file and has the same syntax.
3122
3123       -v, --verbose
3124              This option increases the amount of information the daemon  logs
3125              during  its  startup phase.  After the client connects, the dae‐
3126              mon’s verbosity level will be controlled by the options that the
3127              client used and the "max verbosity" setting in the module’s con‐
3128              fig section.
3129
3130       -4, --ipv4 or -6, --ipv6
3131              Tells rsync to prefer IPv4/IPv6 when creating the incoming sock‐
3132              ets  that  the  rsync daemon will use to listen for connections.
3133              One of these options may be required in older versions of  Linux
3134              to work around an IPv6 bug in the kernel (if you see an "address
3135              already in use" error when nothing else is using the  port,  try
3136              specifying --ipv6 or --ipv4 when starting the daemon).
3137
3138              If  rsync  was  complied  without  support  for IPv6, the --ipv6
3139              option will have no effect.  The --version output will tell  you
3140              if this is the case.
3141
3142       -h, --help
3143              When  specified after --daemon, print a short help page describ‐
3144              ing the options available for starting an rsync daemon.
3145

FILTER RULES

3147       The filter rules allow for flexible selection of which files to  trans‐
3148       fer  (include)  and  which  files  to skip (exclude).  The rules either
3149       directly specify include/exclude patterns or  they  specify  a  way  to
3150       acquire more include/exclude patterns (e.g. to read them from a file).
3151
3152       As  the  list  of  files/directories to transfer is built, rsync checks
3153       each name to be transferred against the list  of  include/exclude  pat‐
3154       terns in turn, and the first matching pattern is acted on:  if it is an
3155       exclude pattern, then that file is skipped; if it is an include pattern
3156       then  that  filename  is  not skipped; if no matching pattern is found,
3157       then the filename is not skipped.
3158
3159       Rsync builds an ordered list of filter rules as specified on  the  com‐
3160       mand-line.  Filter rules have the following syntax:
3161
3162              RULE [PATTERN_OR_FILENAME]
3163              RULE,MODIFIERS [PATTERN_OR_FILENAME]
3164
3165
3166       You  have  your  choice  of  using  either short or long RULE names, as
3167       described below.  If you use a short-named rule, the ’,’ separating the
3168       RULE from the MODIFIERS is optional.  The PATTERN or FILENAME that fol‐
3169       lows (when present) must come after either a single space or an  under‐
3170       score (_).  Here are the available rule prefixes:
3171
3172              exclude, - specifies an exclude pattern.
3173              include, + specifies an include pattern.
3174              merge, . specifies a merge-file to read for more rules.
3175              dir-merge, : specifies a per-directory merge-file.
3176              hide, H specifies a pattern for hiding files from the transfer.
3177              show, S files that match the pattern are not hidden.
3178              protect,  P  specifies a pattern for protecting files from dele‐
3179              tion.
3180              risk, R files that match the pattern are not protected.
3181              clear, ! clears the current include/exclude list (takes no arg)
3182
3183
3184       When rules are being read from a file, empty lines are ignored, as  are
3185       comment lines that start with a "#".
3186
3187       Note that the --include/--exclude command-line options do not allow the
3188       full range of rule parsing as described above -- they  only  allow  the
3189       specification of include/exclude patterns plus a "!" token to clear the
3190       list (and the normal comment parsing when rules are read from a  file).
3191       If  a  pattern  does  not  begin with "- " (dash, space) or "+ " (plus,
3192       space), then the rule will be interpreted as if "+ "  (for  an  include
3193       option) or "- " (for an exclude option) were prefixed to the string.  A
3194       --filter option, on the other hand, must always contain either a  short
3195       or long rule name at the start of the rule.
3196
3197       Note  also that the --filter, --include, and --exclude options take one
3198       rule/pattern each. To add multiple ones, you can repeat the options  on
3199       the  command-line, use the merge-file syntax of the --filter option, or
3200       the --include-from/--exclude-from options.
3201

INCLUDE/EXCLUDE PATTERN RULES

3203       You can include and exclude files by specifying patterns using the "+",
3204       "-",  etc.  filter  rules  (as  introduced  in the FILTER RULES section
3205       above).  The include/exclude rules  each  specify  a  pattern  that  is
3206       matched  against  the  names  of  the files that are going to be trans‐
3207       ferred.  These patterns can take several forms:
3208
3209       o      if the pattern starts with a / then it is anchored to a particu‐
3210              lar  spot  in  the  hierarchy  of files, otherwise it is matched
3211              against the end of the pathname.  This is similar to a leading ^
3212              in regular expressions.  Thus "/foo" would match a name of "foo"
3213              at either the "root of the transfer" (for a global rule)  or  in
3214              the  merge-file’s  directory  (for  a  per-directory  rule).  An
3215              unqualified "foo" would match a name of "foo"  anywhere  in  the
3216              tree  because  the algorithm is applied recursively from the top
3217              down; it behaves as if each path component gets a turn at  being
3218              the  end  of  the filename.  Even the unanchored "sub/foo" would
3219              match at any point in the hierarchy  where  a  "foo"  was  found
3220              within  a  directory  named "sub".  See the section on ANCHORING
3221              INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify
3222              a pattern that matches at the root of the transfer.
3223
3224       o      if  the  pattern  ends with a / then it will only match a direc‐
3225              tory, not a regular file, symlink, or device.
3226
3227       o      rsync chooses between doing a simple string match  and  wildcard
3228              matching  by checking if the pattern contains one of these three
3229              wildcard characters: ’*’, ’?’, and ’[’ .
3230
3231       o      a ’*’ matches any path component, but it stops at slashes.
3232
3233       o      use ’**’ to match anything, including slashes.
3234
3235       o      a ’?’ matches any character except a slash (/).
3236
3237       o      a  ’[’  introduces  a  character  class,  such   as   [a-z]   or
3238              [[:alpha:]].
3239
3240       o      in a wildcard pattern, a backslash can be used to escape a wild‐
3241              card character, but it is matched literally  when  no  wildcards
3242              are  present.   This means that there is an extra level of back‐
3243              slash removal when a pattern contains wildcard  characters  com‐
3244              pared to a pattern that has none.  e.g. if you add a wildcard to
3245              "foo\bar" (which matches the backslash) you would  need  to  use
3246              "foo\\bar*" to avoid the "\b" becoming just "b".
3247
3248       o      if  the  pattern  contains  a / (not counting a trailing /) or a
3249              "**", then it is matched against the  full  pathname,  including
3250              any leading directories. If the pattern doesn’t contain a / or a
3251              "**", then it is matched only against the final component of the
3252              filename.   (Remember  that the algorithm is applied recursively
3253              so "full filename" can actually be any portion of  a  path  from
3254              the starting directory on down.)
3255
3256       o      a  trailing  "dir_name/***" will match both the directory (as if
3257              "dir_name/" had been specified) and everything in the  directory
3258              (as  if  "dir_name/**"  had  been specified).  This behavior was
3259              added in version 2.6.7.
3260
3261
3262       Note that, when using the --recursive (-r) option (which is implied  by
3263       -a),  every  subdir  component  of every path is visited left to right,
3264       with each directory having a chance for exclusion before  its  content.
3265       In  this  way  include/exclude  patterns are applied recursively to the
3266       pathname of each node in the filesystem’s tree (those inside the trans‐
3267       fer).  The exclude patterns short-circuit the directory traversal stage
3268       as rsync finds the files to send.
3269
3270       For instance, to include "/foo/bar/baz",  the  directories  "/foo"  and
3271       "/foo/bar"  must not be excluded.  Excluding one of those parent direc‐
3272       tories prevents the examination of its  content,  cutting  off  rsync’s
3273       recursion into those paths and rendering the include for "/foo/bar/baz"
3274       ineffectual (since rsync can’t match something it  never  sees  in  the
3275       cut-off section of the directory hierarchy).
3276
3277       The  concept  path  exclusion  is  particularly  important when using a
3278       trailing ’*’ rule.  For instance, this won’t work:
3279
3280              + /some/path/this-file-will-not-be-found
3281              + /file-is-included
3282              - *
3283
3284
3285       This fails because the parent directory "some" is excluded by  the  ’*’
3286       rule,  so  rsync  never  visits  any  of  the  files  in  the "some" or
3287       "some/path" directories.  One solution is to ask for all directories in
3288       the  hierarchy  to  be  included by using a single rule: "+ */" (put it
3289       somewhere   before   the   "-   *"   rule),   and   perhaps   use   the
3290       --prune-empty-dirs option.  Another solution is to add specific include
3291       rules for all the parent dirs that need to be visited.   For  instance,
3292       this set of rules works fine:
3293
3294              + /some/
3295              + /some/path/
3296              + /some/path/this-file-is-found
3297              + /file-also-included
3298              - *
3299
3300
3301       Here are some examples of exclude/include matching:
3302
3303       o      "- *.o" would exclude all names matching *.o
3304
3305       o      "-  /foo"  would  exclude a file (or directory) named foo in the
3306              transfer-root directory
3307
3308       o      "- foo/" would exclude any directory named foo
3309
3310       o      "- /foo/*/bar" would exclude any file named bar which is at  two
3311              levels  below  a directory named foo in the transfer-root direc‐
3312              tory
3313
3314       o      "- /foo/**/bar" would exclude any file named  bar  two  or  more
3315              levels  below  a directory named foo in the transfer-root direc‐
3316              tory
3317
3318       o      The combination of "+ */", "+ *.c", and "- *" would include  all
3319              directories  and  C  source files but nothing else (see also the
3320              --prune-empty-dirs option)
3321
3322       o      The combination of "+ foo/", "+  foo/bar.c",  and  "-  *"  would
3323              include  only the foo directory and foo/bar.c (the foo directory
3324              must be explicitly included or it would be excluded by the "*")
3325
3326
3327       The following modifiers are accepted after a "+" or "-":
3328
3329       o      A / specifies that the include/exclude rule  should  be  matched
3330              against the absolute pathname of the current item.  For example,
3331              "-/ /etc/passwd" would exclude the  passwd  file  any  time  the
3332              transfer  was  sending  files from the "/etc" directory, and "-/
3333              subdir/foo" would always exclude "foo" when it is in a dir named
3334              "subdir", even if "foo" is at the root of the current transfer.
3335
3336       o      A ! specifies that the include/exclude should take effect if the
3337              pattern fails to match.  For instance, "-! */" would exclude all
3338              non-directories.
3339
3340       o      A  C  is  used to indicate that all the global CVS-exclude rules
3341              should be inserted as excludes in place of  the  "-C".   No  arg
3342              should follow.
3343
3344       o      An  s  is  used to indicate that the rule applies to the sending
3345              side.  When a rule affects the sending side, it  prevents  files
3346              from  being  transferred.   The  default is for a rule to affect
3347              both sides unless --delete-excluded was specified, in which case
3348              default  rules  become  sender-side only.  See also the hide (H)
3349              and show (S) rules, which are an alternate way to specify  send‐
3350              ing-side includes/excludes.
3351
3352       o      An  r is used to indicate that the rule applies to the receiving
3353              side.  When a rule affects the receiving side, it prevents files
3354              from being deleted.  See the s modifier for more info.  See also
3355              the protect (P) and risk (R) rules, which are an  alternate  way
3356              to specify receiver-side includes/excludes.
3357
3358       o      A  p  indicates  that  a  rule is perishable, meaning that it is
3359              ignored in directories that are being  deleted.   For  instance,
3360              the -C option’s default rules that exclude things like "CVS" and
3361              "*.o" are marked as perishable, and will not prevent a directory
3362              that  was removed on the source from being deleted on the desti‐
3363              nation.
3364
3365       o      An x  indicates  that  a  rule  affects  xattr  names  in  xattr
3366              copy/delete  operations  (and  is  thus  ignored  when  matching
3367              file/dir names). If no xattr-matching  rules  are  specified,  a
3368              default xattr filtering rule is used (see the --xattrs option).
3369
3370

MERGE-FILE FILTER RULES

3372       You can merge whole files into your filter rules by specifying either a
3373       merge (.) or a dir-merge (:) filter rule (as introduced in  the  FILTER
3374       RULES section above).
3375
3376       There  are  two  kinds  of  merged  files  -- single-instance (’.’) and
3377       per-directory (’:’).  A single-instance merge file is  read  one  time,
3378       and its rules are incorporated into the filter list in the place of the
3379       "." rule.  For per-directory merge files, rsync will scan every  direc‐
3380       tory  that  it  traverses for the named file, merging its contents when
3381       the file exists into  the  current  list  of  inherited  rules.   These
3382       per-directory rule files must be created on the sending side because it
3383       is the sending side that is being scanned for the  available  files  to
3384       transfer.   These  rule  files  may  also need to be transferred to the
3385       receiving side if you want them to affect what files don’t get  deleted
3386       (see PER-DIRECTORY RULES AND DELETE below).
3387
3388       Some examples:
3389
3390              merge /etc/rsync/default.rules
3391              . /etc/rsync/default.rules
3392              dir-merge .per-dir-filter
3393              dir-merge,n- .non-inherited-per-dir-excludes
3394              :n- .non-inherited-per-dir-excludes
3395
3396
3397       The following modifiers are accepted after a merge or dir-merge rule:
3398
3399       o      A  - specifies that the file should consist of only exclude pat‐
3400              terns, with no other rule-parsing except for in-file comments.
3401
3402       o      A + specifies that the file should consist of only include  pat‐
3403              terns, with no other rule-parsing except for in-file comments.
3404
3405       o      A  C  is  a  way  to  specify  that the file should be read in a
3406              CVS-compatible manner.  This turns on ’n’,  ’w’,  and  ’-’,  but
3407              also  allows the list-clearing token (!) to be specified.  If no
3408              filename is provided, ".cvsignore" is assumed.
3409
3410       o      A e will exclude the merge-file name  from  the  transfer;  e.g.
3411              "dir-merge,e .rules" is like "dir-merge .rules" and "- .rules".
3412
3413       o      An  n  specifies that the rules are not inherited by subdirecto‐
3414              ries.
3415
3416       o      A w specifies  that  the  rules  are  word-split  on  whitespace
3417              instead  of the normal line-splitting.  This also turns off com‐
3418              ments.  Note: the space that separates the prefix from the  rule
3419              is  treated  specially,  so "- foo + bar" is parsed as two rules
3420              (assuming that prefix-parsing wasn’t also disabled).
3421
3422       o      You may also specify any of the modifiers for  the  "+"  or  "-"
3423              rules  (above)  in order to have the rules that are read in from
3424              the file default to having that modifier set (except for  the  !
3425              modifier,  which  would not be useful).  For instance, "merge,-/
3426              .excl" would  treat  the  contents  of  .excl  as  absolute-path
3427              excludes,  while  "dir-merge,s  .filt" and ":sC" would each make
3428              all their per-directory rules apply only on  the  sending  side.
3429              If the merge rule specifies sides to affect (via the s or r mod‐
3430              ifier or both), then the rules in  the  file  must  not  specify
3431              sides (via a modifier or a rule prefix such as hide).
3432
3433
3434       Per-directory  rules  are inherited in all subdirectories of the direc‐
3435       tory where the merge-file was found unless the ’n’ modifier  was  used.
3436       Each  subdirectory’s  rules are prefixed to the inherited per-directory
3437       rules from its parents, which gives the newest rules a higher  priority
3438       than  the  inherited  rules.   The  entire  set  of dir-merge rules are
3439       grouped together in the spot where the merge-file was specified, so  it
3440       is  possible  to override dir-merge rules via a rule that got specified
3441       earlier in the list of global rules.  When the list-clearing rule ("!")
3442       is  read  from a per-directory file, it only clears the inherited rules
3443       for the current merge file.
3444
3445       Another way to prevent a single rule from a dir-merge file  from  being
3446       inherited  is  to  anchor it with a leading slash.  Anchored rules in a
3447       per-directory merge-file are relative to the merge-file’s directory, so
3448       a pattern "/foo" would only match the file "foo" in the directory where
3449       the dir-merge filter file was found.
3450
3451       Here’s an example filter  file  which  you’d  specify  via  --filter=".
3452       file":
3453
3454              merge /home/user/.global-filter
3455              - *.gz
3456              dir-merge .rules
3457              + *.[ch]
3458              - *.o
3459
3460
3461       This  will  merge the contents of the /home/user/.global-filter file at
3462       the start of the list and also  turns  the  ".rules"  filename  into  a
3463       per-directory filter file.  All rules read in prior to the start of the
3464       directory scan follow the global anchoring rules (i.e. a leading  slash
3465       matches at the root of the transfer).
3466
3467       If a per-directory merge-file is specified with a path that is a parent
3468       directory of the first transfer directory, rsync will scan all the par‐
3469       ent  dirs  from  that  starting point to the transfer directory for the
3470       indicated per-directory file.  For instance, here is  a  common  filter
3471       (see -F):
3472
3473              --filter=': /.rsync-filter'
3474
3475
3476       That  rule tells rsync to scan for the file .rsync-filter in all direc‐
3477       tories from the root down through the parent directory of the  transfer
3478       prior  to  the  start  of  the normal directory scan of the file in the
3479       directories that are sent as a part of the  transfer.   (Note:  for  an
3480       rsync daemon, the root is always the same as the module’s "path".)
3481
3482       Some examples of this pre-scanning for per-directory files:
3483
3484              rsync -avF /src/path/ /dest/dir
3485              rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
3486              rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir
3487
3488
3489       The  first  two commands above will look for ".rsync-filter" in "/" and
3490       "/src"  before  the  normal  scan  begins  looking  for  the  file   in
3491       "/src/path"  and  its subdirectories.  The last command avoids the par‐
3492       ent-dir scan and only looks  for  the  ".rsync-filter"  files  in  each
3493       directory that is a part of the transfer.
3494
3495       If you want to include the contents of a ".cvsignore" in your patterns,
3496       you should use the rule ":C", which creates a dir-merge of the  .cvsig‐
3497       nore  file, but parsed in a CVS-compatible manner.  You can use this to
3498       affect  where  the  --cvs-exclude  (-C)  option’s  inclusion   of   the
3499       per-directory  .cvsignore  file  gets placed into your rules by putting
3500       the ":C" wherever you like in your filter rules.  Without  this,  rsync
3501       would  add the dir-merge rule for the .cvsignore file at the end of all
3502       your other rules (giving it a lower  priority  than  your  command-line
3503       rules).  For example:
3504
3505              cat <<EOT | rsync -avC --filter='. -' a/ b
3506              + foo.o
3507              :C
3508              - *.old
3509              EOT
3510              rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
3511
3512
3513       Both  of  the  above rsync commands are identical.  Each one will merge
3514       all the per-directory .cvsignore rules in the middle of the list rather
3515       than at the end.  This allows their dir-specific rules to supersede the
3516       rules that follow the :C instead  of  being  subservient  to  all  your
3517       rules.  To affect the other CVS exclude rules (i.e. the default list of
3518       exclusions, the contents of $HOME/.cvsignore, and the value of  $CVSIG‐
3519       NORE)  you  should omit the -C command-line option and instead insert a
3520       "-C" rule into your filter rules; e.g. "--filter=-C".
3521

LIST-CLEARING FILTER RULE

3523       You can clear the current include/exclude list by using the "!"  filter
3524       rule  (as introduced in the FILTER RULES section above).  The "current"
3525       list is either the global list of rules (if  the  rule  is  encountered
3526       while  parsing  the  filter  options)  or  a set of per-directory rules
3527       (which are inherited in their own sub-list, so a subdirectory  can  use
3528       this to clear out the parent’s rules).
3529

ANCHORING INCLUDE/EXCLUDE PATTERNS

3531       As  mentioned  earlier, global include/exclude patterns are anchored at
3532       the "root of the transfer" (as opposed to per-directory patterns, which
3533       are  anchored  at  the  merge-file’s  directory).   If you think of the
3534       transfer as a subtree of names that  are  being  sent  from  sender  to
3535       receiver,  the  transfer-root is where the tree starts to be duplicated
3536       in the destination directory.  This root governs  where  patterns  that
3537       start with a / match.
3538
3539       Because  the  matching  is  relative to the transfer-root, changing the
3540       trailing slash on a source path or changing your use of the  --relative
3541       option  affects  the path you need to use in your matching (in addition
3542       to changing how much of the file tree is duplicated on the  destination
3543       host).  The following examples demonstrate this.
3544
3545       Let’s  say that we want to match two source files, one with an absolute
3546       path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
3547       Here is how the various command choices differ for a 2-source transfer:
3548
3549              Example cmd: rsync -a /home/me /home/you /dest
3550              +/- pattern: /me/foo/bar
3551              +/- pattern: /you/bar/baz
3552              Target file: /dest/me/foo/bar
3553              Target file: /dest/you/bar/baz
3554
3555
3556              Example cmd: rsync -a /home/me/ /home/you/ /dest
3557              +/- pattern: /foo/bar               (note missing "me")
3558              +/- pattern: /bar/baz               (note missing "you")
3559              Target file: /dest/foo/bar
3560              Target file: /dest/bar/baz
3561
3562
3563              Example cmd: rsync -a --relative /home/me/ /home/you /dest
3564              +/- pattern: /home/me/foo/bar       (note full path)
3565              +/- pattern: /home/you/bar/baz      (ditto)
3566              Target file: /dest/home/me/foo/bar
3567              Target file: /dest/home/you/bar/baz
3568
3569
3570              Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
3571              +/- pattern: /me/foo/bar      (starts at specified path)
3572              +/- pattern: /you/bar/baz     (ditto)
3573              Target file: /dest/me/foo/bar
3574              Target file: /dest/you/bar/baz
3575
3576
3577       The  easiest  way to see what name you should filter is to just look at
3578       the output when using --verbose and put a / in front of the  name  (use
3579       the --dry-run option if you’re not yet ready to copy any files).
3580

PER-DIRECTORY RULES AND DELETE

3582       Without  a  delete option, per-directory rules are only relevant on the
3583       sending side, so you can feel free to exclude  the  merge  files  them‐
3584       selves without affecting the transfer.  To make this easy, the ’e’ mod‐
3585       ifier adds this exclude for you, as seen in these two  equivalent  com‐
3586       mands:
3587
3588              rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
3589              rsync -av --filter=':e .excl' host:src/dir /dest
3590
3591
3592       However,  if you want to do a delete on the receiving side AND you want
3593       some files to be excluded from being deleted, you’ll need  to  be  sure
3594       that  the  receiving side knows what files to exclude.  The easiest way
3595       is to include the per-directory merge files in  the  transfer  and  use
3596       --delete-after,  because  this ensures that the receiving side gets all
3597       the same exclude rules as the sending side before it  tries  to  delete
3598       anything:
3599
3600              rsync -avF --delete-after host:src/dir /dest
3601
3602
3603       However, if the merge files are not a part of the transfer, you’ll need
3604       to either specify some global exclude rules (i.e. specified on the com‐
3605       mand  line),  or  you’ll  need to maintain your own per-directory merge
3606       files on the receiving side.  An example of the first is  this  (assume
3607       that the remote .rules files exclude themselves):
3608
3609       rsync -av --filter=’: .rules’ --filter=’. /my/extra.rules’
3610          --delete host:src/dir /dest
3611
3612
3613       In  the above example the extra.rules file can affect both sides of the
3614       transfer, but (on the sending side) the rules are  subservient  to  the
3615       rules  merged  from  the .rules files because they were specified after
3616       the per-directory merge rule.
3617
3618       In one final example, the remote side is  excluding  the  .rsync-filter
3619       files from the transfer, but we want to use our own .rsync-filter files
3620       to control what gets deleted on the receiving side.  To do this we must
3621       specifically  exclude the per-directory merge files (so that they don’t
3622       get deleted) and then put rules into the local files  to  control  what
3623       else should not get deleted.  Like one of these commands:
3624
3625           rsync -av --filter=':e /.rsync-filter' --delete \
3626               host:src/dir /dest
3627           rsync -avFF --delete host:src/dir /dest
3628
3629

BATCH MODE

3631       Batch mode can be used to apply the same set of updates to many identi‐
3632       cal systems. Suppose one has a tree which is replicated on a number  of
3633       hosts.  Now suppose some changes have been made to this source tree and
3634       those changes need to be propagated to the other hosts. In order to  do
3635       this  using  batch  mode,  rsync  is run with the write-batch option to
3636       apply the changes made to the source tree to  one  of  the  destination
3637       trees.   The  write-batch  option causes the rsync client to store in a
3638       "batch file" all  the  information  needed  to  repeat  this  operation
3639       against other, identical destination trees.
3640
3641       Generating the batch file once saves having to perform the file status,
3642       checksum, and data block generation more than once when updating multi‐
3643       ple  destination  trees.  Multicast  transport protocols can be used to
3644       transfer the batch update files in parallel  to  many  hosts  at  once,
3645       instead of sending the same data to every host individually.
3646
3647       To  apply  the  recorded changes to another destination tree, run rsync
3648       with the read-batch option, specifying the name of the same batch file,
3649       and the destination tree.  Rsync updates the destination tree using the
3650       information stored in the batch file.
3651
3652       For  your  convenience,  a  script  file  is  also  created  when   the
3653       write-batch  option  is  used:   it will be named the same as the batch
3654       file with ".sh" appended.  This script  file  contains  a  command-line
3655       suitable  for  updating  a  destination tree using the associated batch
3656       file. It can be executed using a Bourne (or Bourne-like) shell, option‐
3657       ally  passing  in  an alternate destination tree pathname which is then
3658       used instead of the original destination path.  This is useful when the
3659       destination  tree path on the current host differs from the one used to
3660       create the batch file.
3661
3662       Examples:
3663
3664              $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
3665              $ scp foo* remote:
3666              $ ssh remote ./foo.sh /bdest/dir/
3667
3668
3669              $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
3670              $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
3671
3672
3673       In  these  examples,  rsync  is  used  to   update   /adest/dir/   from
3674       /source/dir/  and the information to repeat this operation is stored in
3675       "foo" and "foo.sh".  The host "remote" is then updated with the batched
3676       data  going into the directory /bdest/dir.  The differences between the
3677       two examples reveals some of the flexibility you have in how  you  deal
3678       with batches:
3679
3680       o      The first example shows that the initial copy doesn’t have to be
3681              local -- you can push or pull data to/from a remote  host  using
3682              either  the  remote-shell  syntax  or  rsync  daemon  syntax, as
3683              desired.
3684
3685       o      The first example uses the created  "foo.sh"  file  to  get  the
3686              right  rsync  options when running the read-batch command on the
3687              remote host.
3688
3689       o      The second example reads the batch data via  standard  input  so
3690              that  the  batch  file  doesn’t  need to be copied to the remote
3691              machine first.  This example avoids the foo.sh script because it
3692              needed to use a modified --read-batch option, but you could edit
3693              the script file if you wished to make use of it  (just  be  sure
3694              that  no  other  option is trying to use standard input, such as
3695              the "--exclude-from=-" option).
3696
3697
3698       Caveats:
3699
3700       The read-batch option expects the destination tree that it is  updating
3701       to  be  identical  to  the destination tree that was used to create the
3702       batch update fileset.  When a difference between the destination  trees
3703       is  encountered  the  update  might be discarded with a warning (if the
3704       file appears to be  up-to-date  already)  or  the  file-update  may  be
3705       attempted  and  then, if the file fails to verify, the update discarded
3706       with an error.   This  means  that  it  should  be  safe  to  re-run  a
3707       read-batch  operation  if  the command got interrupted.  If you wish to
3708       force the batched-update to  always  be  attempted  regardless  of  the
3709       file’s  size  and date, use the -I option (when reading the batch).  If
3710       an error occurs, the destination tree will probably be in  a  partially
3711       updated  state.  In  that  case,  rsync  can  be  used  in  its regular
3712       (non-batch) mode of operation to fix up the destination tree.
3713
3714       The rsync version used on all destinations must be at least as  new  as
3715       the  one used to generate the batch file.  Rsync will die with an error
3716       if the  protocol  version  in  the  batch  file  is  too  new  for  the
3717       batch-reading  rsync  to  handle.  See also the --protocol option for a
3718       way to have the creating rsync generate a  batch  file  that  an  older
3719       rsync can understand.  (Note that batch files changed format in version
3720       2.6.3, so mixing versions older than that with newer versions will  not
3721       work.)
3722
3723       When  reading  a  batch  file,  rsync  will  force the value of certain
3724       options to match the data in the batch file if you didn’t set  them  to
3725       the  same as the batch-writing command.  Other options can (and should)
3726       be  changed.   For  instance  --write-batch  changes  to  --read-batch,
3727       --files-from  is  dropped, and the --filter/--include/--exclude options
3728       are not needed unless one of the --delete options is specified.
3729
3730       The  code  that  creates  the  BATCH.sh  file   transforms   any   fil‐
3731       ter/include/exclude  options  into  a single list that is appended as a
3732       "here" document to the shell script file.  An  advanced  user  can  use
3733       this  to  modify  the  exclude list if a change in what gets deleted by
3734       --delete is desired.  A normal user can ignore this detail and just use
3735       the  shell  script  as  an easy way to run the appropriate --read-batch
3736       command for the batched data.
3737
3738       The original batch mode in rsync was based on "rsync+", but the  latest
3739       version uses a new implementation.
3740
3742       Three  basic  behaviors  are  possible when rsync encounters a symbolic
3743       link in the source directory.
3744
3745       By default, symbolic links are  not  transferred  at  all.   A  message
3746       "skipping non-regular" file is emitted for any symlinks that exist.
3747
3748       If --links is specified, then symlinks are recreated with the same tar‐
3749       get on the destination.  Note that --archive implies --links.
3750
3751       If --copy-links is specified, then symlinks are "collapsed" by  copying
3752       their referent, rather than the symlink.
3753
3754       Rsync  can  also  distinguish  "safe"  and "unsafe" symbolic links.  An
3755       example where this might be used is a web site mirror  that  wishes  to
3756       ensure  that  the rsync module that is copied does not include symbolic
3757       links to  /etc/passwd  in  the  public  section  of  the  site.   Using
3758       --copy-unsafe-links  will cause any links to be copied as the file they
3759       point to on the destination.   Using  --safe-links  will  cause  unsafe
3760       links  to  be  omitted altogether.  (Note that you must specify --links
3761       for --safe-links to have any effect.)
3762
3763       Symbolic links are considered unsafe  if  they  are  absolute  symlinks
3764       (start  with  /),  empty,  or if they contain enough ".." components to
3765       ascend from the directory being copied.
3766
3767       Here’s a summary of how the symlink options are interpreted.  The  list
3768       is in order of precedence, so if your combination of options isn’t men‐
3769       tioned, use the first line that is a complete subset of your options:
3770
3771       --copy-links
3772              Turn all symlinks into normal files (leaving no symlinks for any
3773              other options to affect).
3774
3775       --links --copy-unsafe-links
3776              Turn  all unsafe symlinks into files and duplicate all safe sym‐
3777              links.
3778
3779       --copy-unsafe-links
3780              Turn all unsafe symlinks into files, noisily skip all safe  sym‐
3781              links.
3782
3783       --links --safe-links
3784              Duplicate safe symlinks and skip unsafe ones.
3785
3786       --links
3787              Duplicate all symlinks.
3788

DIAGNOSTICS

3790       rsync occasionally produces error messages that may seem a little cryp‐
3791       tic. The one that seems to cause the most confusion is  "protocol  ver‐
3792       sion mismatch -- is your shell clean?".
3793
3794       This  message is usually caused by your startup scripts or remote shell
3795       facility producing unwanted garbage on the stream that rsync  is  using
3796       for  its  transport.  The  way  to diagnose this problem is to run your
3797       remote shell like this:
3798
3799              ssh remotehost /bin/true > out.dat
3800
3801
3802       then look at out.dat. If everything is working correctly  then  out.dat
3803       should  be  a zero length file. If you are getting the above error from
3804       rsync then you will probably find that out.dat contains  some  text  or
3805       data.  Look  at  the contents and try to work out what is producing it.
3806       The most common cause is incorrectly configured shell  startup  scripts
3807       (such  as  .cshrc  or  .profile)  that  contain  output  statements for
3808       non-interactive logins.
3809
3810       If you are having trouble debugging filter patterns, then try  specify‐
3811       ing  the  -vv  option.   At this level of verbosity rsync will show why
3812       each individual file is included or excluded.
3813

EXIT VALUES

3815       0      Success
3816
3817       1      Syntax or usage error
3818
3819       2      Protocol incompatibility
3820
3821       3      Errors selecting input/output files, dirs
3822
3823       4      Requested action not supported: an attempt was made  to  manipu‐
3824              late  64-bit files on a platform that cannot support them; or an
3825              option was specified that is supported by the client and not  by
3826              the server.
3827
3828       5      Error starting client-server protocol
3829
3830       6      Daemon unable to append to log-file
3831
3832       10     Error in socket I/O
3833
3834       11     Error in file I/O
3835
3836       12     Error in rsync protocol data stream
3837
3838       13     Errors with program diagnostics
3839
3840       14     Error in IPC code
3841
3842       20     Received SIGUSR1 or SIGINT
3843
3844       21     Some error returned by waitpid()
3845
3846       22     Error allocating core memory buffers
3847
3848       23     Partial transfer due to error
3849
3850       24     Partial transfer due to vanished source files
3851
3852       25     The --max-delete limit stopped deletions
3853
3854       30     Timeout in data send/receive
3855
3856       35     Timeout waiting for daemon connection
3857
3858

ENVIRONMENT VARIABLES

3860       CVSIGNORE
3861              The  CVSIGNORE  environment variable supplements any ignore pat‐
3862              terns in .cvsignore files. See the --cvs-exclude option for more
3863              details.
3864
3865       RSYNC_ICONV
3866              Specify  a  default --iconv setting using this environment vari‐
3867              able. (First supported in 3.0.0.)
3868
3869       RSYNC_PROTECT_ARGS
3870              Specify a non-zero numeric value if you want the  --protect-args
3871              option  to  be  enabled by default, or a zero value to make sure
3872              that it is disabled by default. (First supported in 3.1.0.)
3873
3874       RSYNC_RSH
3875              The RSYNC_RSH environment variable allows you  to  override  the
3876              default  shell  used  as  the transport for rsync.  Command line
3877              options are permitted after the command name, just as in the  -e
3878              option.
3879
3880       RSYNC_PROXY
3881              The RSYNC_PROXY environment variable allows you to redirect your
3882              rsync client to use a web proxy when connecting to a rsync  dae‐
3883              mon. You should set RSYNC_PROXY to a hostname:port pair.
3884
3885       RSYNC_PASSWORD
3886              Setting  RSYNC_PASSWORD  to  the required password allows you to
3887              run authenticated rsync connections to an rsync  daemon  without
3888              user  intervention. Note that this does not supply a password to
3889              a remote shell transport such as ssh; to learn how to  do  that,
3890              consult the remote shell’s documentation.
3891
3892       USER or LOGNAME
3893              The  USER or LOGNAME environment variables are used to determine
3894              the default username sent to an rsync  daemon.   If  neither  is
3895              set, the username defaults to "nobody".
3896
3897       HOME   The HOME environment variable is used to find the user’s default
3898              .cvsignore file.
3899
3900

FILES

3902       /etc/rsyncd.conf or rsyncd.conf
3903

SEE ALSO

3905       rsyncd.conf(5)
3906

BUGS

3908       times are transferred as *nix time_t values
3909
3910       When transferring to  FAT  filesystems  rsync  may  re-sync  unmodified
3911       files.  See the comments on the --modify-window option.
3912
3913       file  permissions,  devices,  etc.  are transferred as native numerical
3914       values
3915
3916       see also the comments on the --delete option
3917
3918       Please report bugs! See the web site at http://rsync.samba.org/
3919

VERSION

3921       This man page is current for version 3.1.3 of rsync.
3922

INTERNAL OPTIONS

3924       The options --server and --sender are used  internally  by  rsync,  and
3925       should  never  be  typed  by  a  user under normal circumstances.  Some
3926       awareness of these options may be needed in certain scenarios, such  as
3927       when  setting  up  a  login  that  can  only run an rsync command.  For
3928       instance, the support directory of the rsync distribution has an  exam‐
3929       ple  script named rrsync (for restricted rsync) that can be used with a
3930       restricted ssh login.
3931

CREDITS

3933       rsync is distributed under the GNU General  Public  License.   See  the
3934       file COPYING for details.
3935
3936       A  WEB site is available at http://rsync.samba.org/.  The site includes
3937       an FAQ-O-Matic which may cover  questions  unanswered  by  this  manual
3938       page.
3939
3940       The primary ftp site for rsync is ftp://rsync.samba.org/pub/rsync.
3941
3942       We  would  be  delighted  to  hear  from  you if you like this program.
3943       Please contact the mailing-list at rsync@lists.samba.org.
3944
3945       This program uses the excellent zlib  compression  library  written  by
3946       Jean-loup Gailly and Mark Adler.
3947

THANKS

3949       Special  thanks  go  out  to: John Van Essen, Matt McCutchen, Wesley W.
3950       Terpstra, David Dykstra, Jos Backus, Sebastian  Krahmer,  Martin  Pool,
3951       and our gone-but-not-forgotten compadre, J.W. Schultz.
3952
3953       Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Roth‐
3954       well and David Bell.  I’ve probably missed some people, my apologies if
3955       I have.
3956

AUTHOR

3958       rsync  was  originally  written  by Andrew Tridgell and Paul Mackerras.
3959       Many people have later contributed to it.  It is  currently  maintained
3960       by Wayne Davison.
3961
3962       Mailing   lists   for   support   and   development  are  available  at
3963       http://lists.samba.org
3964
3965
3966
3967                                  28 Jan 2018                         rsync(1)
Impressum