Various xattr fixes:

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 64f9758..ec8654f 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
 mailto(rsync-bugs@samba.org)

-manpage(rsync)(1)(11 Oct 2007)()()
+manpage(rsync)(1)(8 Nov 2007)()()

 manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
 manpagesynopsis()
 
 manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
 manpagesynopsis()
 


@@ -225,7 +225,7 @@ verb(  export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
   rsync -av targethost1::module/src/ /dest/
   rsync -av rsync:://targethost2/module/src/ /dest/ )
 
   rsync -av targethost1::module/src/ /dest/
   rsync -av rsync:://targethost2/module/src/ /dest/ )
 

-The command specifed above uses ssh to run nc (netcat) on a proxyhost,
+The command specified above uses ssh to run nc (netcat) on a proxyhost,

 which forwards all data to port 873 (the rsync daemon) on the targethost
 (%H).
 
 which forwards all data to port 873 (the rsync daemon) on the targethost
 (%H).
 


@@ -328,7 +328,7 @@ to the detailed description below for a complete description.  verb(
  -u, --update                skip files that are newer on the receiver
      --inplace               update destination files in-place
      --append                append data onto shorter files
  -u, --update                skip files that are newer on the receiver
      --inplace               update destination files in-place
      --append                append data onto shorter files

-     --append-verify         --append w/old data in file cheksum
+     --append-verify         --append w/old data in file checksum

  -d, --dirs                  transfer directories without recursing
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            transform symlink into referent file/dir
  -d, --dirs                  transfer directories without recursing
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            transform symlink into referent file/dir


@@ -352,7 +352,7 @@ to the detailed description below for a complete description.  verb(
      --super                 receiver attempts super-user activities
      --fake-super            store/recover privileged attrs using xattrs
  -S, --sparse                handle sparse files efficiently
      --super                 receiver attempts super-user activities
      --fake-super            store/recover privileged attrs using xattrs
  -S, --sparse                handle sparse files efficiently

- -n, --dry-run               show what would have been transferred
+ -n, --dry-run               perform a trial run with no changes made

  -W, --whole-file            copy files whole (without rsync algorithm)
  -x, --one-file-system       don't cross filesystem boundaries
  -B, --block-size=SIZE       force a fixed checksum block-size
  -W, --whole-file            copy files whole (without rsync algorithm)
  -x, --one-file-system       don't cross filesystem boundaries
  -B, --block-size=SIZE       force a fixed checksum block-size


@@ -421,7 +421,7 @@ to the detailed description below for a complete description.  verb(
      --only-write-batch=FILE like --write-batch but w/o updating dest
      --read-batch=FILE       read a batched update from FILE
      --protocol=NUM          force an older protocol version to be used
      --only-write-batch=FILE like --write-batch but w/o updating dest
      --read-batch=FILE       read a batched update from FILE
      --protocol=NUM          force an older protocol version to be used

-     --iconv=CONVERT_SPEC    request charset conversion of filesnames
+     --iconv=CONVERT_SPEC    request charset conversion of filenames

      --checksum-seed=NUM     set block/file checksum seed (advanced)
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6
      --checksum-seed=NUM     set block/file checksum seed (advanced)
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6


@@ -747,6 +747,12 @@ bf(--recursive) option, rsync will skip all directories it encounters (and
 output a message to that effect for each one).  If you specify both
 bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence.
 
 output a message to that effect for each one).  If you specify both
 bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence.
 

+This option is implied by the bf(--list-only) option (including an implied
+bf(--list-only) usage) if bf(--recursive) wasn't specified (so that
+directories are seen in the listing).  Specify bf(--no-dirs) (or bf(--no-d))
+if you want to override this.  This option is also implied by
+bf(--files-from).
+

 dit(bf(-l, --links)) When symlinks are encountered, recreate the
 symlink on the destination.
 
 dit(bf(-l, --links)) When symlinks are encountered, recreate the
 symlink on the destination.
 


@@ -795,6 +801,14 @@ directory, and receives the file into the new directory.  With
 bf(--keep-dirlinks), the receiver keeps the symlink and "file" ends up in
 "bar".
 
 bf(--keep-dirlinks), the receiver keeps the symlink and "file" ends up in
 "bar".
 

+One note of caution:  if you use bf(--keep-dirlinks), you must trust all
+the symlinks in the copy!  If it is possible for an untrusted user to
+create their own symlink to any directory, the user could then (on a
+subsequent copy) replace the symlink with a real directory and affect the
+content of whatever directory the symlink references.  For backup copies,
+you are better off using something like a bind mount instead of a symlink
+to modify your receiving hierarchy.
+

 See also bf(--copy-dirlinks) for an analogous option for the sending side.
 
 dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in
 See also bf(--copy-dirlinks) for an analogous option for the sending side.
 
 dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in


@@ -840,17 +854,17 @@ permissions (while leaving existing files unchanged), make sure that the
 bf(--perms) option is off and use bf(--chmod=ugo=rwX) (which ensures that
 all non-masked bits get enabled).  If you'd care to make this latter
 behavior easier to type, you could define a popt alias for it, such as
 bf(--perms) option is off and use bf(--chmod=ugo=rwX) (which ensures that
 all non-masked bits get enabled).  If you'd care to make this latter
 behavior easier to type, you could define a popt alias for it, such as

-putting this line in the file ~/.popt (this defines the bf(-s) option,
+putting this line in the file ~/.popt (the following defines the bf(-Z) option,

 and includes --no-g to use the default group of the destination dir):
 
 and includes --no-g to use the default group of the destination dir):
 

-quote(tt(   rsync alias -s --no-p --no-g --chmod=ugo=rwX))
+quote(tt(   rsync alias -Z --no-p --no-g --chmod=ugo=rwX))

 
 You could then use this new option in a command such as this one:
 
 
 You could then use this new option in a command such as this one:
 

-quote(tt(   rsync -asv src/ dest/))
+quote(tt(   rsync -avZ src/ dest/))

 
 

-(Caveat: make sure that bf(-a) does not follow bf(-s), or it will re-enable
-the "--no-*" options.)
+(Caveat: make sure that bf(-a) does not follow bf(-Z), or it will re-enable
+the two "--no-*" options mentioned above.)

 
 The preservation of the destination's setgid bit on newly-created
 directories when bf(--perms) is off was added in rsync 2.6.7.  Older rsync
 
 The preservation of the destination's setgid bit on newly-created
 directories when bf(--perms) is off was added in rsync 2.6.7.  Older rsync


@@ -981,7 +995,7 @@ files we create can always be accessed/changed by the creating user).
 This option also handles ACLs (if bf(--acls) was specified) and non-user
 extended attributes (if bf(--xattrs) was specified).
 
 This option also handles ACLs (if bf(--acls) was specified) and non-user
 extended attributes (if bf(--xattrs) was specified).
 

-This is a good way to backup data withou using a super-user, and to store
+This is a good way to backup data without using a super-user, and to store

 ACLs from incompatible systems.
 
 The bf(--fake-super) option only affects the side where the option is used.
 ACLs from incompatible systems.
 
 The bf(--fake-super) option only affects the side where the option is used.


@@ -991,7 +1005,7 @@ path:
 quote(tt(  rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
 
 Since there is only one "side" in a local copy, this option affects both
 quote(tt(  rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
 
 Since there is only one "side" in a local copy, this option affects both

-the sending and recieving of files.  You'll need to specify a copy using
+the sending and receiving of files.  You'll need to specify a copy using

 "localhost" if you need to avoid this, possibly using the "lsh" shell
 script (from the support directory) as a substitute for an actual remote
 shell (see bf(--rsh)).
 "localhost" if you need to avoid this, possibly using the "lsh" shell
 script (from the support directory) as a substitute for an actual remote
 shell (see bf(--rsh)).


@@ -1008,8 +1022,20 @@ NOTE: Don't use this option when the destination is a Solaris "tmpfs"
 filesystem. It doesn't seem to handle seeks over null regions
 correctly and ends up corrupting the files.
 
 filesystem. It doesn't seem to handle seeks over null regions
 correctly and ends up corrupting the files.
 

-dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
-instead it will just report the actions it would have taken.
+dit(bf(-n, --dry-run)) This makes rsync perform a trial run that doesn't
+make any changes (and produces mostly the same output as a real run).  It
+is most commonly used in combination with the bf(-v, --verbose) and/or
+bf(-i, --itemize-changes) options to see what an rsync command is going
+to do before one actually runs it.
+
+The output of bf(--itemize-changes) is supposed to be exactly the same on a
+dry run and a subsequent real run (barring intentional trickery and system
+call failures); if it isn't, that's a bug.  Other output is the same to the
+extent practical, but may differ in some areas.  Notably, a dry run does not
+send the actual data for file transfers, so bf(--progress) has no effect,
+the "bytes sent", "bytes received", "literal data", and "matched data"
+statistics are too small, and the "speedup" value is equivalent to a run
+where no file transfers are needed.

 
 dit(bf(-W, --whole-file)) With this option the delta transfer algorithm
 is not used and the whole file is sent as-is instead.  The transfer may be
 
 dit(bf(-W, --whole-file)) With this option the delta transfer algorithm
 is not used and the whole file is sent as-is instead.  The transfer may be


@@ -1073,9 +1099,9 @@ Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
 was enabled.  Beginning with 2.6.7, deletions will also occur when bf(--dirs)
 (bf(-d)) is enabled, but only for directories whose contents are being copied.
 
 was enabled.  Beginning with 2.6.7, deletions will also occur when bf(--dirs)
 (bf(-d)) is enabled, but only for directories whose contents are being copied.
 

-This option can be dangerous if used incorrectly!  It is a very good idea
-to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
-deleted to make sure important files aren't listed.
+This option can be dangerous if used incorrectly!  It is a very good idea to
+first try a run using the bf(--dry-run) option (bf(-n)) to see what files are
+going to be deleted.

 
 If the sending side detects any I/O errors, then the deletion of any
 files at the destination will be automatically disabled. This is to
 
 If the sending side detects any I/O errors, then the deletion of any
 files at the destination will be automatically disabled. This is to


@@ -1237,8 +1263,8 @@ The exclude list is initialized to exclude the following items (these
 initial items are marked as perishable -- see the FILTER RULES section):
 
 quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
 initial items are marked as perishable -- see the FILTER RULES section):
 
 quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state

-.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
-.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .bzr/)))
+.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del-*
+*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .bzr/)))

 
 then, files listed in a $HOME/.cvsignore are added to the list and any
 files listed in the CVSIGNORE environment variable (all cvsignore names
 
 then, files listed in a $HOME/.cvsignore are added to the list and any
 files listed in the CVSIGNORE environment variable (all cvsignore names


@@ -1922,16 +1948,22 @@ dit(bf(--list-only)) This option will cause the source files to be listed
 instead of transferred.  This option is inferred if there is a single source
 arg and no destination specified, so its main uses are: (1) to turn a copy
 command that includes a
 instead of transferred.  This option is inferred if there is a single source
 arg and no destination specified, so its main uses are: (1) to turn a copy
 command that includes a

-destination arg into a file-listing command, (2) to be able to specify more
-than one local source arg (note: be sure to include the destination), or
-(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that
-rsync usually uses as a compatibility kluge when generating a non-recursive
-listing.  Caution: keep in mind that a source arg with a wild-card is expanded
-by the shell into multiple args, so it is never safe to try to list such an arg
+destination arg into a file-listing command, or (2) to be able to specify
+more than one source arg (note: be sure to include the destination).
+Caution: keep in mind that a source arg with a wild-card is expanded by the
+shell into multiple args, so it is never safe to try to list such an arg

 without using this option.  For example:
 
 verb(    rsync -av --list-only foo* dest/)
 
 without using this option.  For example:
 
 verb(    rsync -av --list-only foo* dest/)
 

+Compatibility note:  when requesting a remote listing of files from an rsync
+that is version 2.6.3 or older, you may encounter an error if you ask for a
+non-recursive listing.  This is because a file listing implies the bf(--dirs)
+option w/o bf(--recursive), and older rsyncs don't have that option.  To
+avoid this problem, either specify the bf(--no-dirs) option (if you don't
+need to expand a directory's content), or turn on recursion and exclude
+the content of subdirectories: bf(-r --exclude='/*/*').
+

 dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
 transfer rate in kilobytes per second. This option is most effective when
 using rsync with large files (several megabytes and up). Due to the nature
 dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
 transfer rate in kilobytes per second. This option is most effective when
 using rsync with large files (several megabytes and up). Due to the nature


@@ -2796,7 +2828,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/)
 
 manpagesection(VERSION)
 
 
 manpagesection(VERSION)
 

-This man page is current for version 3.0.0pre2 of rsync.
+This man page is current for version 3.0.0pre5 of rsync.

 
 manpagesection(INTERNAL OPTIONS)
 
 
 manpagesection(INTERNAL OPTIONS)
 


@@ -2822,23 +2854,25 @@ The primary ftp site for rsync is
 url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
 
 We would be delighted to hear from you if you like this program.
 url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
 
 We would be delighted to hear from you if you like this program.

+Please contact the mailing-list at rsync@lists.samba.org.

 
 This program uses the excellent zlib compression library written by
 Jean-loup Gailly and Mark Adler.
 
 manpagesection(THANKS)
 
 
 This program uses the excellent zlib compression library written by
 Jean-loup Gailly and Mark Adler.
 
 manpagesection(THANKS)
 

-Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
-and David Bell for helpful suggestions, patches and testing of rsync.
-I've probably missed some people, my apologies if I have.
+Especial thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra,
+David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
+gone-but-not-forgotten compadre, J.W. Schultz.

 
 

-Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
-Martin Pool, Wayne Davison, J.W. Schultz.
+Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
+and David Bell.  I've probably missed some people, my apologies if I have.

 
 manpageauthor()
 
 rsync was originally written by Andrew Tridgell and Paul Mackerras.
 
 manpageauthor()
 
 rsync was originally written by Andrew Tridgell and Paul Mackerras.

-Many people have later contributed to it.
+Many people have later contributed to it.  It is currently maintained
+by Wayne Davison.

 
 Mailing lists for support and development are available at
 url(http://lists.samba.org)(lists.samba.org)
 
 Mailing lists for support and development are available at
 url(http://lists.samba.org)(lists.samba.org)