home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / rsync221.zip / rsync.yo < prev    next >
Text File  |  1999-03-04  |  31KB  |  748 lines
  1. mailto(rsync-bugs@samba.org)
  2. manpage(rsync)(1)(24 Nov 1998)()()
  3. manpagename(rsync)(faster, flexible replacement for rcp)
  4. manpagesynopsis()
  5.  
  6. rsync [options] [user@]host:path path
  7.  
  8. rsync [options] path [user@]host:path
  9.  
  10. rsync [options] path path
  11.  
  12. rsync [options] [user@]host::module[/path] path
  13.  
  14. rsync [options] path [user@]host::module[/path]
  15.  
  16. rsync [options] rsync://[user@]host[:port]/module/path path
  17.  
  18. manpagedescription()
  19.  
  20. rsync is a program that behaves in much the same way that rcp does,
  21. but has many more options and uses the rsync remote-update protocol to
  22. greatly speedup file transfers when the destination file already
  23. exists.
  24.  
  25. The rsync remote-update protocol allows rsync to transfer just the
  26. differences between two sets of files across the network link, using
  27. an efficient checksum-search algorithm described in the technical
  28. report that accompanies this package.
  29.  
  30. Some of the additional features of rsync are:
  31.  
  32. itemize(
  33.   it() support for copying links, devices, owners, groups and permissions
  34.   it() exclude and exclude-from options similar to GNU tar
  35.   it() a CVS exclude mode for ignoring the same files that CVS would ignore
  36.   it() can use any transparent remote shell, including rsh or ssh
  37.   it() does not require root privileges
  38.   it() pipelining of file transfers to minimize latency costs
  39.   it() support for anonymous or authenticated rsync servers (ideal for
  40.        mirroring)
  41. )
  42.  
  43. manpagesection(GENERAL)
  44.  
  45. There are six different ways of using rsync. They are:
  46.  
  47. itemize(
  48.     it() for copying local files. This is invoked when neither
  49.          source nor destination path contains a : separator
  50.  
  51.     it() for copying from the local machine to a remote machine using
  52.     a remote shell program as the transport (such as rsh or
  53.     ssh). This is invoked when the destination path contains a
  54.     single : separator.
  55.  
  56.     it() for copying from a remote machine to the local machine
  57.     using a remote shell program. This is invoked when the local path
  58.     contains a : separator.
  59.  
  60.     it() for copying from a remote rsync server to the local
  61.     machine. This is invoked when the source path contains a ::
  62.     separator or a rsync:// URL.
  63.  
  64.     it() for copying from the local machine to a remote rsync
  65.     server. This is invoked when the destination path contains a ::
  66.     separator. 
  67.  
  68.     it() for listing files on a remote machine. This is done the
  69.     same way as rsync transfers except that you leave off the
  70.     local destination.  
  71. )
  72.  
  73. Note that in all cases (other than listing) at least one of the source
  74. and destination paths must be local.
  75.  
  76. manpagesection(SETUP)
  77.  
  78. See the file README for installation instructions.
  79.  
  80. Once installed you can use rsync to any machine that you can use rsh
  81. to.  rsync uses rsh for its communications, unless both the source and
  82. destination are local.
  83.  
  84. You can also specify an alternative to rsh, by either using the -e
  85. command line option, or by setting the RSYNC_RSH environment variable.
  86.  
  87. One common substitute is to use ssh, which offers a high degree of
  88. security.
  89.  
  90. Note that rsync must be installed on both the source and destination
  91. machines. 
  92.  
  93. manpagesection(USAGE)
  94.  
  95. You use rsync in the same way you use rcp. You must specify a source
  96. and a destination, one of which may be remote.
  97.  
  98. Perhaps the best way to explain the syntax is some examples:
  99.  
  100. quote(rsync *.c foo:src/)
  101.  
  102. this would transfer all files matching the pattern *.c from the
  103. current directory to the directory src on the machine foo. If any of
  104. the files already exist on the remote system then the rsync
  105. remote-update protocol is used to update the file by sending only the
  106. differences. See the tech report for details.
  107.  
  108. quote(rsync -avz foo:src/bar /data/tmp)
  109.  
  110. this would recursively transfer all files from the directory src/bar on the
  111. machine foo into the /data/tmp/bar directory on the local machine. The
  112. files are transferred in "archive" mode, which ensures that symbolic
  113. links, devices, attributes, permissions, ownerships etc are preserved
  114. in the transfer.  Additionally, compression will be used to reduce the
  115. size of data portions of the transfer.
  116.  
  117. quote(rsync -avz foo:src/bar/ /data/tmp)
  118.  
  119. a trailing slash on the source changes this behavior to transfer
  120. all files from the directory src/bar on the machine foo into the
  121. /data/tmp/.  A trailing / on a source name means "copy the
  122. contents of this directory".  Without a trailing slash it means "copy
  123. the directory". This difference becomes particularly important when
  124. using the --delete option.
  125.  
  126. You can also use rsync in local-only mode, where both the source and
  127. destination don't have a ':' in the name. In this case it behaves like
  128. an improved copy command.
  129.  
  130. quote(rsync somehost.mydomain.com::)
  131.  
  132. this would list all the anonymous rsync modules available on the host
  133. somehost.mydomain.com.  (See the following section for more details.)
  134.  
  135.  
  136. manpagesection(CONNECTING TO AN RSYNC SERVER)
  137.  
  138. It is also possible to use rsync without using rsh or ssh as the
  139. transport. In this case you will connect to a remote rsync server
  140. running on TCP port 873. 
  141.  
  142. Using rsync in this way is the same as using it with rsh or ssh except
  143. that:
  144.  
  145. itemize(
  146.     it() you use a double colon :: instead of a single colon to
  147.     separate the hostname from the path. 
  148.  
  149.     it() the remote server may print a message of the day when you
  150.     connect.
  151.  
  152.     it() if you specify no path name on the remote server then the
  153.     list of accessible paths on the server will be shown.
  154.  
  155.     it() if you specify no local destination then a listing of the
  156.     specified files on the remote server is provided.
  157. )
  158.  
  159. Some paths on the remote server may require authentication. If so then
  160. you will receive a password prompt when you connect. You can avoid the
  161. password prompt by setting the environment variable RSYNC_PASSWORD to
  162. the password you want to use. This may be useful when scripting rsync.
  163.  
  164. manpagesection(RUNNING AN RSYNC SERVER)
  165.  
  166. An rsync server is configured using a config file which by default is
  167. called /etc/rsyncd.conf. Please see the rsyncd.conf(5) man page for more
  168. information. 
  169.  
  170. manpagesection(EXAMPLES)
  171.  
  172. Here are some examples of how I use rsync.
  173.  
  174. To backup my wife's home directory, which consists of large MS Word
  175. files and mail folders, I use a cron job that runs
  176.  
  177. quote(rsync -Cavz . arvidsjaur:backup)
  178.  
  179. each night over a PPP link to a duplicate directory on my machine
  180. "arvidsjaur".
  181.  
  182. To synchronize my samba source trees I use the following Makefile
  183. targets:
  184.  
  185. quote(      get:nl()
  186.        rsync -avuzb --exclude '*~' samba:samba/ .
  187.  
  188.       put:nl()
  189.        rsync -Cavuzb . samba:samba/
  190.  
  191.       sync: get put)
  192.  
  193. this allows me to sync with a CVS directory at the other end of the
  194. link. I then do cvs operations on the remote machine, which saves a
  195. lot of time as the remote cvs protocol isn't very efficient.
  196.  
  197. I mirror a directory between my "old" and "new" ftp sites with the
  198. command
  199.  
  200. quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
  201.  
  202. this is launched from cron every few hours.
  203.  
  204. manpagesection(OPTIONS SUMMARY)
  205.  
  206. Here is a short summary of the options available in rsync. Please refer
  207. to the detailed description below for a complete description.
  208.  
  209. verb(
  210. Usage: rsync [OPTION]... SRC [USER@]HOST:DEST
  211.   or   rsync [OPTION]... [USER@]HOST:SRC DEST
  212.   or   rsync [OPTION]... SRC DEST
  213.   or   rsync [OPTION]... [USER@]HOST::SRC [DEST]
  214.   or   rsync [OPTION]... SRC [USER@]HOST::DEST
  215.   or   rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
  216.  
  217. Options
  218.  -v, --verbose               increase verbosity
  219.  -c, --checksum              always checksum
  220.  -a, --archive               archive mode
  221.  -r, --recursive             recurse into directories
  222.  -R, --relative              use relative path names
  223.  -b, --backup                make backups (default ~ extension)
  224.  -u, --update                update only (don't overwrite newer files)
  225.  -l, --links                 preserve soft links
  226.  -L, --copy-links            treat soft links like regular files
  227.      --safe-links            ignore links outside the destination tree
  228.  -H, --hard-links            preserve hard links
  229.  -p, --perms                 preserve permissions
  230.  -o, --owner                 preserve owner (root only)
  231.  -g, --group                 preserve group
  232.  -D, --devices               preserve devices (root only)
  233.  -t, --times                 preserve times
  234.  -S, --sparse                handle sparse files efficiently
  235.  -n, --dry-run               show what would have been transferred
  236.  -W, --whole-file            copy whole files, no incremental checks
  237.  -x, --one-file-system       don't cross filesystem boundaries
  238.  -B, --block-size=SIZE       checksum blocking size
  239.  -e, --rsh=COMMAND           specify rsh replacement
  240.      --rsync-path=PATH       specify path to rsync on the remote machine
  241.  -C, --cvs-exclude           auto ignore files in the same way CVS does
  242.      --delete                delete files that don't exist on the sending side
  243.      --partial               keep partially transferred files
  244.      --force                 force deletion of directories even if not empty
  245.      --numeric-ids           don't map uid/gid values by user/group name
  246.      --timeout=TIME          set IO timeout in seconds
  247.  -I, --ignore-times          don't exclude files that match length and time
  248.  -T  --temp-dir=DIR          create temporary files in directory DIR
  249.      --compare-dest=DIR      also compare destination files relative to DIR
  250.  -z, --compress              compress file data
  251.      --exclude=PATTERN       exclude files matching PATTERN
  252.      --exclude-from=FILE     exclude files listed in FILE
  253.      --include=PATTERN       don't exclude files matching PATTERN
  254.      --include-from=FILE     don't exclude files listed in FILE
  255.      --suffix=SUFFIX         override backup suffix
  256.      --version               print version number
  257.      --daemon                run as a rsync daemon
  258.      --config=FILE           specify alternate rsyncd.conf file
  259.      --port=PORT             specify alternate rsyncd port number
  260.      --stats                 give some file transfer stats
  261.      --progress              show progress during transfer
  262.      --log-format=FORMAT     log file transfers using specified format
  263.  -h, --help                  show this help screen
  264. )
  265.  
  266. manpageoptions()
  267.  
  268. rsync uses the GNU long options package. Many of the command line
  269. options have two variants, one short and one long.  These are shown
  270. below, separated by commas. Some options only have a long variant.
  271.  
  272. startdit()
  273. dit(bf(-h, --help)) Print a short help page describing the options
  274. available in rsync
  275.  
  276. dit(bf(--version)) print the rsync version number and exit
  277.  
  278. dit(bf(-v, --verbose)) This option increases the amount of information you
  279. are given during the transfer.  By default, rsync works silently. A
  280. single -v will give you information about what files are being
  281. transferred and a brief summary at the end. Two -v flags will give you
  282. information on what files are being skipped and slightly more
  283. information at the end. More than two -v flags should only be used if
  284. you are debugging rsync.
  285.  
  286. dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
  287. already the same length and have the same time-stamp. This option turns
  288. off this behavior.
  289.  
  290. dit(bf(-c, --checksum)) This forces the sender to checksum all files using
  291. a 128-bit MD4 checksum before transfer. The checksum is then
  292. explicitly checked on the receiver and any files of the same name
  293. which already exist and have the same checksum and size on the
  294. receiver are skipped.  This option can be quite slow.
  295.  
  296. dit(bf(-a, --archive)) This is equivalent to -rlptDg. It is a quick way
  297. of saying you want recursion and want to preserve everything.
  298.  
  299. Note: if the user launching rsync is root then the -o option (preserve
  300. uid) is also implied.
  301.  
  302. dit(bf(-r, --recursive)) This tells rsync to copy directories recursively.
  303.  
  304. dit(bf(-R, --relative)) Use relative paths. This means that the full path
  305. names specified on the command line are sent to the server rather than
  306. just the last parts of the filenames. This is particularly useful when
  307. you want to send several different directories at the same time. For
  308. example, if you used the command
  309.  
  310. verb(rsync foo/bar/foo.c remote:/tmp/)
  311.  
  312. then this would create a file called foo.c in /tmp/ on the remote
  313. machine. If instead you used
  314.  
  315. verb(rsync -R foo/bar/foo.c remote:/tmp/)
  316.  
  317. then a file called /tmp/foo/bar/foo.c would be created on the remote
  318. machine. The full path name is preserved.
  319.  
  320. dit(bf(-b, --backup)) With this option preexisting destination files are
  321. renamed with a ~ extension as each file is transferred.  You can
  322. control the backup suffix using the --suffix option.
  323.  
  324. dit(bf(-u, --update)) This forces rsync to skip any files for which the
  325. destination file already exists and has a date later than the source
  326. file.
  327.  
  328. dit(bf(-l, --links)) This tells rsync to recreate symbolic links on the
  329. remote system  to  be the same as the local system. Without this
  330. option, all symbolic links are skipped.
  331.  
  332. dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just
  333. like  ordinary files.
  334.  
  335. dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
  336. which point outside the destination tree. All absolute symlinks are
  337. also ignored. Using this option in conjunction with --relative may
  338. give unexpected results. 
  339.  
  340. dit(bf(-H, --hard-links)) This tells rsync to recreate hard  links  on
  341. the  remote system  to  be the same as the local system. Without this
  342. option hard links are treated like regular files.
  343.  
  344. Note that rsync can only detect hard links if both parts of the link
  345. are in the list of files being sent.
  346.  
  347. This option can be quite slow, so only use it if you need it.
  348.  
  349. dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
  350. is  not used  and  the whole file is sent as-is instead. This may be
  351. useful when using rsync with a local machine.
  352.  
  353. dit(bf(--partial)) By default, rsync will delete any partially
  354. transferred file if the transfer is interrupted. In some circumstances
  355. it is more desirable to keep partially transferred files. Using the
  356. --partial option tells rsync to keep the partial file which should
  357. make a subsequent transfer of the rest of the file much faster.
  358.  
  359. dit(bf(-p, --perms)) This option causes rsync to update the remote
  360. permissions to be the same as the local permissions.
  361.  
  362. dit(bf(-o, --owner)) This option causes rsync to update the  remote  owner
  363. of the  file to be the same as the local owner. This is only available
  364. to the super-user.  Note that if the source system is a daemon using chroot,
  365. the --numeric-ids option is implied because the source system cannot get
  366. access to the usernames.
  367.  
  368. dit(bf(-g, --group)) This option causes rsync to update the  remote  group
  369. of the file to be the same as the local group.  Note that if the source
  370. system is a daemon using chroot, the --numeric-ids option is implied because
  371. the source system cannot get access to the group names.
  372.  
  373. dit(bf(-D, --devices)) This option causes rsync to transfer character and
  374. block device information to the remote system to recreate these
  375. devices. This option is only available to the super-user.
  376.  
  377. dit(bf(-t, --times)) This tells rsync to transfer modification times along
  378. with the files and update them on the remote system.  Note that if this
  379. option is not used, the optimization that excludes files that have not been
  380. modified cannot be effective; in other words, a missing -t or -a will
  381. cause the next transfer to behave as if it used -I, and all files will have
  382. their checksums compared and show up in log messages even if they haven't
  383. changed.
  384.  
  385. dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
  386. instead it will just report the actions it would have taken.
  387.  
  388. dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
  389. up less space on the destination.
  390.  
  391. NOTE: Don't use this option when the destination is a Solaris "tmpfs"
  392. filesystem. It doesn't seem to handle seeks over null regions
  393. correctly and ends up corrupting the files.
  394.  
  395. dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
  396. boundaries  when recursing.  This  is useful for transferring the
  397. contents of only one filesystem.
  398.  
  399. dit(bf(--delete)) This tells rsync to delete any files on the receiving
  400. side that aren't on the sending side. This option can be dangerous if
  401. used incorrectly!
  402.  
  403. It is a very good idea to run first using the dry run option (-n) to
  404. see what files would be deleted to make sure important files aren't
  405. listed.
  406.  
  407. rsync 1.6.4 changed the behavior of --delete to make it less
  408. dangerous.  rsync now only scans directories on the receiving side
  409. that are explicitly transferred from the sending side.  Only files in
  410. these directories are deleted.
  411.  
  412. Still, it is probably easy to get burnt with this option.  The moral
  413. of the story is to use the -n option until you get used to the
  414. behavior of --delete.
  415.  
  416. If the sending side detects any IO errors then the deletion of any
  417. files at the destination will be automatically disabled. This is to
  418. prevent temporary filesystem failures (such as NFS errors) on the
  419. sending side causing a massive deletion of files on the
  420. destination. 
  421.  
  422. dit(bf(--force)) This options tells rsync to delete directories even if
  423. they are not empty.  This applies to both the --delete option and to
  424. cases where rsync tries to copy a normal file but the destination
  425. contains a directory of the same name. Normally rsync will refuse to
  426. do a recursive directory deletion in such cases, by using --force
  427. the recursive deletion will be done.
  428.  
  429. Use this option with caution!
  430.  
  431. dit(bf(-B , --block_size BLOCKSIZE)) This controls the block size used in
  432. the rsync algorithm. See the technical report for details.
  433.  
  434. dit(bf(-e, --rsh COMMAND)) This option allows you to choose an alternative
  435. remote shell program to use for communication between the local and
  436. remote copies of rsync. By default, rsync will use rsh, but you may
  437. like to instead use ssh because of its high security.
  438.  
  439. You can also choose the remote shell program using the RSYNC_RSH
  440. environment variable.
  441.  
  442. dit(bf(--rsync-path PATH)) Use this to specify the path to the copy of
  443. rsync on the remote machine. Useful when it's not in your path.
  444.  
  445. dit(bf(--exclude pattern)) This option allows you to selectively exclude
  446. certain files from the list of files to be transferred. This is most
  447. useful in combination with a recursive transfer.
  448.  
  449. You may use as many --exclude options on the command line as you like
  450. to build up the list of files to exclude.
  451.  
  452. See the section on exclude patterns for information on the syntax of 
  453. this option.
  454.  
  455. dit(bf(--exclude-from FILE)) This option is similar to the --exclude
  456. option, but instead it adds all filenames listed in the file FILE to
  457. the exclude list.
  458.  
  459. dit(bf(--include pattern)) This option tells rsync to not exclude the
  460. specified pattern of filenames. This is useful as it allows you to
  461. build up quite complex exclude/include rules.
  462.  
  463. See the section of exclude patterns for information on the syntax of 
  464. this option.
  465.  
  466. dit(bf(--include-from FILE)) This specifies a list of include patterns
  467. from a file.
  468.  
  469. dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
  470. broad range of files that you often don't want to transfer between
  471. systems. It uses the same algorithm that CVS uses to determine if
  472. a file should be ignored.
  473.  
  474. The exclude list is initialized to:
  475.  
  476. quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
  477. .nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
  478. *.a *.o *.obj *.so *.Z *.elc *.ln core)
  479.  
  480. then files listed in a $HOME/.cvsignore are added to the list and any
  481. files listed in the CVSIGNORE environment variable (space delimited).
  482.  
  483. Finally in each directory any files listed in the .cvsignore file in
  484. that directory are added to the list.
  485.  
  486. dit(bf(--suffix SUFFIX)) This option allows you to override the default
  487. backup suffix used with the -b option. The default is a ~.
  488.  
  489. dit(bf(--csum-length LENGTH)) By default the primary checksum used in
  490. rsync is a very strong 16 byte MD4 checksum. In most cases you will
  491. find that a truncated version of this checksum is quite efficient, and
  492. this will decrease the size of the checksum data sent over the link,
  493. making things faster. 
  494.  
  495. You can choose the number of bytes in the truncated checksum using the
  496. --csum-length option. Any value less than or equal to 16 is valid.
  497.  
  498. Note that if you use this option then you run the risk of ending up
  499. with an incorrect target file. The risk with a value of 16 is
  500. microscopic and can be safely ignored (the universe will probably end
  501. before it fails) but with smaller values the risk is higher.
  502.  
  503. Current versions of rsync actually use an adaptive algorithm for the
  504. checksum length by default, using a 16 byte file checksum to determine
  505. if a 2nd pass is required with a longer block checksum. Only use this
  506. option if you have read the source code and know what you are doing.
  507.  
  508. dit(bf(-T, --temp-dir DIR)) This option instructs rsync to use DIR as a
  509. scratch directory when creating temporary copies of the files
  510. transferred on the receiving side.  The default behavior is to create
  511. the temporary files in the receiving directory.
  512.  
  513. dit(bf(--compare-dest DIR)) This option instructs rsync to use DIR as an
  514. additional directory to compare destination files against when doing
  515. transfers.  This is useful for doing transfers to a new destination while
  516. leaving existing files intact, and then doing a flash-cutover when all
  517. files have been successfully transferred (for example by moving directories
  518. around and removing the old directory, although this requires also doing
  519. the transfer with -I to avoid skipping files that haven't changed).  This
  520. option increases the usefulness of --partial because partially transferred
  521. files will remain in the new temporary destination until they have a chance
  522. to be completed.  If DIR is a relative path, it is relative to the
  523. destination directory.
  524.  
  525. dit(bf(-z, --compress)) With this option, rsync compresses any data from
  526. the source file(s) which it sends to the destination machine.  This
  527. option is useful on slow links.  The compression method used is the
  528. same method that gzip uses.
  529.  
  530. Note this this option typically achieves better compression ratios
  531. that can be achieved by using a compressing remote shell, or a
  532. compressing transport, as it takes advantage of the implicit
  533. information sent for matching data blocks.
  534.  
  535. dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
  536. and user ids rather than using user and group names and mapping them
  537. at both ends.
  538.  
  539. By default rsync will use the user name and group name to determine
  540. what ownership to give files. The special uid 0 and the special group
  541. 0 are never mapped via user/group names even if the --numeric-ids
  542. option is not specified.
  543.  
  544. If the source system is a daemon using chroot, or if a user or group name
  545. does not exist on the destination system, then the numeric id from the
  546. source system is used instead.
  547.  
  548. dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
  549. timeout in seconds. If no data is transferred for the specified time
  550. then rsync will exit. The default is 0, which means no timeout.
  551.  
  552. dit(bf(--daemon)) This tells rsync that it is to run as a rsync
  553. daemon. If standard input is a socket then rsync will assume that it
  554. is being run via inetd, otherwise it will detach from the current
  555. terminal and become a background daemon. The daemon will read the
  556. config file (/etc/rsyncd.conf) on each connect made by a client and
  557. respond to requests accordingly. See the rsyncd.conf(5) man page for more
  558. details. 
  559.  
  560. dit(bf(--config FILE)) This specifies an alternate config file than
  561. the default /etc/rsyncd.conf. This is only relevant when --daemon is
  562. specified. 
  563.  
  564. dit(bf(--port PORT)) This specifies an alternate TCP port number to use
  565. rather than the default port 873.
  566.  
  567. dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
  568. rsync client logs to stdout on a per-file basis. The log format is
  569. specified using the same format conventions as the log format option in
  570. rsyncd.conf.
  571.  
  572. dit(bf(--stats)) This tells rsync to print a verbose set of statistics
  573. on the file transfer, allowing you to tell how effective the rsync
  574. algorithm is for your data. This option only works in conjunction with
  575. the -v (verbose) option.
  576.  
  577. dit(bf(--progress)) This option tells rsync to print information
  578. showing the progress of the transfer. This gives a bored user
  579. something to watch.
  580.  
  581. enddit()
  582.  
  583. manpagesection(EXCLUDE PATTERNS)
  584.  
  585. The exclude and include patterns specified to rsync allow for flexible
  586. selection of which files to transfer and which files to skip.
  587.  
  588. rsync builds a ordered list of include/exclude options as specified on
  589. the command line. When a filename is encountered, rsync checks the
  590. name against each exclude/include pattern in turn. The first matching
  591. pattern is acted on. If it is an exclude pattern than that file is
  592. skipped. If it is an include pattern then that filename is not
  593. skipped. If no matching include/exclude pattern is found then the
  594. filename is not skipped.
  595.  
  596. The patterns can take several forms. The rules are:
  597.  
  598. itemize(
  599.   it() if the pattern starts with a / then it is matched against the
  600.   start of the filename, otherwise it is matched against the end of
  601.   the filename. Thus /foo would match a file called foo
  602.   at the base of the tree whereas foo would match any file
  603.   called foo anywhere in the tree.
  604.  
  605.   it() if the pattern ends with a / then it will only match a
  606.   directory, not a file, link or device.
  607.  
  608.   it() if the pattern contains a wildcard character from the set
  609.   *?[ then regular expression matching is applied using the
  610.   normal shell filename matching rules. Otherwise a simple string
  611.   match is used.
  612.  
  613.   it() if the pattern contains a / (not counting a trailing /) then it
  614.   is matched against the full filename, including any leading
  615.   directory. If the pattern doesn't contain a / then it is matched
  616.   only against the final component of the filename.
  617.  
  618.   it() if the pattern starts with "+ " (a plus followed by a space)
  619.   then it is always considered a include pattern, even if specified as
  620.   part of an exclude option. The "+ " part is discarded before matching.
  621.  
  622.   it() if the pattern starts with "- " (a minus followed by a space)
  623.   then it is always considered a exclude pattern, even if specified as
  624.   part of an include option. The "- " part is discarded before matching.
  625.  
  626.   it() if the pattern is a single exclamation mark ! then the current
  627.   exclude list is reset, removing all previous exclude patterns.
  628. )
  629.  
  630. The +/- rules are most useful in exclude lists, allowing you to have a
  631. single exclude list that contains both include and exclude options.
  632.  
  633. Here are some examples:
  634.  
  635. itemize(
  636.   it() --exclude "*.o" would exclude all filenames matching *.o
  637.   it() --exclude "/foo" would exclude a file in the base directory called foo
  638.   it() --exclude "foo/" would exclude any directory called foo
  639.   it() --include "*/" --include "*.c" --exclude "*" would include all 
  640.   directories and C source files
  641.   it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
  642.   only foo/bar.c (the foo/ directory must be explicitly included or
  643.   it would be excluded by the "*")
  644. )
  645.  
  646. manpagesection(DIAGNOSTICS)
  647.  
  648. rsync occasionally produces error messages that may seem a little
  649. cryptic. The one that seems to cause the most confusion is "protocol
  650. version mismatch - is your shell clean?".
  651.  
  652. This message is usually caused by your startup scripts or remote shell
  653. facility producing unwanted garbage on the stream that rsync is using
  654. for its transport. The way to diagnose this problem is to run your
  655. remote shell like this:
  656.  
  657. verb(
  658.    rsh remotehost /bin/true > out.dat
  659. )
  660.        
  661. then look at out.dat. If everything is working correctly then out.dat
  662. should be a zero length file. You you are getting the above error from
  663. rsync then you will probably find that out.dat contains some text or
  664. data. Look at the contents and try to work out what is producing
  665. it. The most common cause is incorrectly configured shell startup
  666. scripts (such as .cshrc or .profile) that contain output statements
  667. for non-interactive logins.
  668.  
  669. manpagesection(ENVIRONMENT VARIABLES)
  670.  
  671. startdit()
  672.  
  673. dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
  674. ignore patterns in .cvsignore files. See the --cvs-exclude option for
  675. more details.
  676.  
  677. dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
  678. override the default shell used as the transport for rsync. This can
  679. be used instead of the -e option.
  680.  
  681. dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
  682. password allows you to run authenticated rsync connections to a rsync
  683. daemon without user intervention. Note that this does not supply a
  684. password to a shell transport such as ssh.
  685.  
  686. dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
  687. are used to determine the default username sent to a rsync server.
  688.  
  689. dit(bf(HOME)) The HOME environment variable is used to find the user's
  690. default .cvsignore file.
  691.  
  692. enddit()
  693.  
  694. manpagefiles()
  695.  
  696. /etc/rsyncd.conf
  697.  
  698. manpageseealso()
  699.  
  700. rsyncd.conf(5)
  701.  
  702. manpagediagnostics()
  703.  
  704. manpagebugs()
  705.  
  706. times are transferred as unix time_t values
  707.  
  708. file permissions, devices etc are transferred as native numerical
  709. values
  710.  
  711. see also the comments on the --delete option
  712.  
  713. Please report bugs! The rsync bug tracking system is online at
  714. url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/)
  715.  
  716. manpagesection(VERSION)
  717. This man page is current for version 2.0 of rsync
  718.  
  719. manpagesection(CREDITS)
  720.  
  721. rsync is distributed under the GNU public license.  See the file
  722. COPYING for details.
  723.  
  724. A WEB site is available at
  725. url(http://rsync.samba.org/)(http://rsync.samba.org/)
  726.  
  727. The primary ftp site for rsync is
  728. url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
  729.  
  730. We would be delighted to hear from you if you like this program.
  731.  
  732. This program uses the excellent zlib compression library written by
  733. Jean-loup Gailly and Mark Adler.
  734.  
  735. manpagesection(THANKS)
  736.  
  737. Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
  738. and David Bell for helpful suggestions and testing of rsync. I've
  739. probably missed some people, my apologies if I have.
  740.  
  741.  
  742. manpageauthor()
  743.  
  744. rsync was written by Andrew Tridgell and Paul Mackerras.  They may be
  745. contacted via email at tridge@samba.org and
  746. Paul.Mackerras@cs.anu.edu.au
  747.  
  748.