The improved --xattrs option is landing on the trunk.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 60e1c17..55c372a 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -301,7 +301,7 @@ to the detailed description below for a complete description.  verb(
  -q, --quiet                 suppress non-error messages
      --no-motd               suppress daemon-mode MOTD (see caveat)
  -c, --checksum              skip based on checksum, not mod-time & size
  -q, --quiet                 suppress non-error messages
      --no-motd               suppress daemon-mode MOTD (see caveat)
  -c, --checksum              skip based on checksum, not mod-time & size

- -a, --archive               archive mode; same as -rlptgoD (no -H)
+ -a, --archive               archive mode; equals -rlptgoD (no -H,-A,-X)

      --no-OPTION             turn off an implied OPTION (e.g. --no-D)
  -r, --recursive             recurse into directories
  -R, --relative              use relative path names
      --no-OPTION             turn off an implied OPTION (e.g. --no-D)
  -r, --recursive             recurse into directories
  -R, --relative              use relative path names


@@ -323,6 +323,8 @@ to the detailed description below for a complete description.  verb(
  -p, --perms                 preserve permissions
  -E, --executability         preserve executability
      --chmod=CHMOD           affect file and/or directory permissions
  -p, --perms                 preserve permissions
  -E, --executability         preserve executability
      --chmod=CHMOD           affect file and/or directory permissions

+ -A, --acls                  preserve ACLs (implies -p)
+ -X, --xattrs                preserve extended attrs (implies -p)

  -o, --owner                 preserve owner (super-user only)
  -g, --group                 preserve group
      --devices               preserve device files (super-user only)
  -o, --owner                 preserve owner (super-user only)
  -g, --group                 preserve group
      --devices               preserve device files (super-user only)


@@ -628,7 +630,7 @@ Note that if you don't specify bf(--backup-dir), (1) the
 bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is
 also in effect (without bf(--delete-excluded)), rsync will add a "protect"
 filter-rule for the backup suffix to the end of all your existing excludes
 bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is
 also in effect (without bf(--delete-excluded)), rsync will add a "protect"
 filter-rule for the backup suffix to the end of all your existing excludes

-(e.g. bf(-f "P *~")).  This will prevent previously backed-up files from being
+(e.g. bf(-f "Pp *~")).  This will prevent previously backed-up files from being

 deleted.  Note that if you are supplying your own filter rules, you may
 need to manually insert your own exclude/protect rule somewhere higher up
 in the list so that it has a high enough priority to be effective (e.g., if
 deleted.  Note that if you are supplying your own filter rules, you may
 need to manually insert your own exclude/protect rule somewhere higher up
 in the list so that it has a high enough priority to be effective (e.g., if


@@ -724,7 +726,7 @@ which point outside the copied tree. All absolute symlinks are
 also ignored. Using this option in conjunction with bf(--relative) may
 give unexpected results.
 
 also ignored. Using this option in conjunction with bf(--relative) may
 give unexpected results.
 

-dit(bf(-K, --copy-dirlinks)) This option causes the sending side to treat
+dit(bf(-k, --copy-dirlinks)) This option causes the sending side to treat

 a symlink to a directory as though it were a real directory.  This is
 useful if you don't want symlinks to non-directories to be affected, as
 they would be using bf(--copy-links).
 a symlink to a directory as though it were a real directory.  This is
 useful if you don't want symlinks to non-directories to be affected, as
 they would be using bf(--copy-links).


@@ -771,7 +773,9 @@ quote(itemization(
   permissions, though the bf(--executability) option might change just
   the execute permission for the file.
   it() New files get their "normal" permission bits set to the source
   permissions, though the bf(--executability) option might change just
   the execute permission for the file.
   it() New files get their "normal" permission bits set to the source

-  file's permissions masked with the receiving end's umask setting, and
+  file's permissions masked with the receiving directory's default
+  permissions (either the receiving process's umask, or the permissions
+  specified via the destination directory's default ACL), and

   their special permission bits disabled except in the case where a new
   directory inherits a setgid bit from its parent directory.
 ))
   their special permission bits disabled except in the case where a new
   directory inherits a setgid bit from its parent directory.
 ))


@@ -802,9 +806,11 @@ 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
 versions erroneously preserved the three special permission bits for
 newly-created files when bf(--perms) was off, while overriding the
 directories when bf(--perms) is off was added in rsync 2.6.7.  Older rsync
 versions erroneously preserved the three special permission bits for
 newly-created files when bf(--perms) was off, while overriding the

-destination's setgid bit setting on a newly-created directory.  (Keep in
-mind that it is the version of the receiving rsync that affects this
-behavior.)
+destination's setgid bit setting on a newly-created directory.  Default ACL
+observance was added to the ACL patch for rsync 2.6.7, so older (or
+non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
+(Keep in mind that it is the version of the receiving rsync that affects
+these behaviors.)

 
 dit(bf(-E, --executability)) This option causes rsync to preserve the
 executability (or non-executability) of regular files when bf(--perms) is
 
 dit(bf(-E, --executability)) This option causes rsync to preserve the
 executability (or non-executability) of regular files when bf(--perms) is


@@ -822,6 +828,15 @@ quote(itemization(
 
 If bf(--perms) is enabled, this option is ignored.
 
 
 If bf(--perms) is enabled, this option is ignored.
 

+dit(bf(-A, --acls)) This option causes rsync to update the destination
+ACLs to be the same as the source ACLs.  This nonstandard option only
+works if the remote rsync also supports it.  bf(--acls) implies bf(--perms).
+
+dit(bf(-X, --xattrs)) This option causes rsync to update the remote
+extended attributes to be the same as the local ones.  This will work
+only if the remote machine's rsync supports this option also. This is
+a non-standard option.
+

 dit(bf(--chmod)) This option tells rsync to apply one or more
 comma-separated "chmod" strings to the permission of the files in the
 transfer.  The resulting value is treated as though it was the permissions
 dit(bf(--chmod)) This option tells rsync to apply one or more
 comma-separated "chmod" strings to the permission of the files in the
 transfer.  The resulting value is treated as though it was the permissions


@@ -1346,6 +1361,12 @@ and the attributes updated.
 If a match is not found, a basis file from one of the em(DIR)s will be
 selected to try to speed up the transfer.
 
 If a match is not found, a basis file from one of the em(DIR)s will be
 selected to try to speed up the transfer.
 

+This option works best when copying into an empty destination hierarchy, as
+rsync treats existing files as definitive (so it never looks in the link-dest
+dirs when a destination file already exists), and as malleable (so it might
+change the attributes of a destination file, which affects all the hard-linked
+versions).
+

 Note that if you combine this option with bf(--ignore-times), rsync will not
 link any files together because it only links identical files together as a
 substitute for transferring the file, never as an additional check after the
 Note that if you combine this option with bf(--ignore-times), rsync will not
 link any files together because it only links identical files together as a
 substitute for transferring the file, never as an additional check after the


@@ -1426,8 +1447,8 @@ if the receiving rsync is at least version 2.6.7 (you can use bf(-vv)
 with older versions of rsync, but that also turns on the output of other
 verbose messages).
 
 with older versions of rsync, but that also turns on the output of other
 verbose messages).
 

-The "%i" escape has a cryptic output that is 9 letters long.  The general
-format is like the string bf(YXcstpogz), where bf(Y) is replaced by the
+The "%i" escape has a cryptic output that is 11 letters long.  The general
+format is like the string bf(YXcstpoguax), where bf(Y) is replaced by the

 type of update being done, bf(X) is replaced by the file-type, and the
 other letters represent attributes that may be output if they are being
 modified.
 type of update being done, bf(X) is replaced by the file-type, and the
 other letters represent attributes that may be output if they are being
 modified.


@@ -1476,7 +1497,11 @@ quote(itemization(
   sender's value (requires bf(--owner) and super-user privileges).
   it() A bf(g) means the group is different and is being updated to the
   sender's value (requires bf(--group) and the authority to set the group).
   sender's value (requires bf(--owner) and super-user privileges).
   it() A bf(g) means the group is different and is being updated to the
   sender's value (requires bf(--group) and the authority to set the group).

-  it() The bf(z) slot is reserved for future use.
+  it() The bf(u) slot is reserved for reporting update (access) time changes
+  (a feature that is not yet released).
+  it() The bf(a) means that the ACL information changed.
+  it() The bf(x) slot is reserved for reporting extended attribute changes
+  (a feature that is not yet released).

 ))
 
 One other output is possible:  when deleting files, the "%i" will output
 ))
 
 One other output is possible:  when deleting files, the "%i" will output


@@ -1613,7 +1638,7 @@ rule at the end of all your existing excludes.  This will prevent the
 sending of any partial-dir files that may exist on the sending side, and
 will also prevent the untimely deletion of partial-dir items on the
 receiving side.  An example: the above bf(--partial-dir) option would add
 sending of any partial-dir files that may exist on the sending side, and
 will also prevent the untimely deletion of partial-dir items on the
 receiving side.  An example: the above bf(--partial-dir) option would add

-the equivalent of "bf(--exclude=.rsync-partial/)" at the end of any other
+the equivalent of "bf(-f '-p .rsync-partial/')" at the end of any other

 filter rules.
 
 If you are supplying your own exclude rules, you may need to add your own
 filter rules.
 
 If you are supplying your own exclude rules, you may need to add your own