X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d9f46544a3f7553e034084a21c6b76c7ce5bafe7..1c60d219472b3de0080cda807b014d011e3b5ccb:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 4abea313..e9d1e20d 100644 --- 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 - -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 @@ -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 + -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) @@ -464,7 +466,7 @@ by the client at the start of a daemon transfer. This suppresses the message-of-the-day (MOTD) text, but it also affects the list of modules that the daemon sends in response to the "rsync host::" request (due to a limitation in the rsync protocol), so omit this option if you want to -request the list of modules from the deamon. +request the list of modules from the daemon. dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are already the same size and have the same modification time-stamp. @@ -486,20 +488,26 @@ transferring to or from an MS Windows FAT filesystem (which represents times with a 2-second resolution), bf(--modify-window=1) is useful (allowing times to differ by up to 1 second). -dit(bf(-c, --checksum)) This forces the sender to checksum em(every) -regular file using a 128-bit MD4 checksum. It does this during the initial -file-system scan as it builds the list of all available files. The receiver -then checksums its version of each file (if it exists and it has the same -size as its sender-side counterpart) in order to decide which files need to -be updated: files with either a changed size or a changed checksum are -selected for transfer. Since this whole-file checksumming of all files on -both sides of the connection occurs in addition to the automatic checksum -verifications that occur during a file's transfer, this option can be quite -slow. - -Note that rsync always verifies that each em(transferred) file was correctly -reconstructed on the receiving side by checking its whole-file checksum, but -that automatic after-the-transfer verification has nothing to do with this +dit(bf(-c, --checksum)) This changes the way rsync checks if the files have +been changed and are in need of a transfer. Without this option, rsync +uses a "quick check" that (by default) checks if each file's size and time +of last modification match between the sender and receiver. This option +changes this to compare a 128-bit MD4 checksum for each file that has a +matching size. Generating the checksums means that both sides will expend +a lot of disk I/O reading all the data in the files in the transfer (and +this is prior to any reading that will be done to transfer changed files), +so this can slow things down significantly. + +The sending side generates its checksums while it is doing the file-system +scan that builds the list of the available files. The receiver generates +its checksums when it is scanning for changed files, and will checksum any +file that has the same size as the corresponding sender's file: files with +either a changed size or a changed checksum are selected for transfer. + +Note that rsync always verifies that each em(transferred) file was +correctly reconstructed on the receiving side by checking a whole-file +checksum that is generated when as the file is transferred, but that +automatic after-the-transfer verification has nothing to do with this option's before-the-transfer "Does this file need to be updated?" check. dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick @@ -543,11 +551,11 @@ bf(--files-from) list). It is also only possible when both ends of the transfer are at least version 3.0.0. Some options require rsync to know the full file list, so these options -disable the incremental recusion mode. These include: bf(--delete-before), -bf(--delete-after), bf(--delay-updates), and (currently) bf(--hard-links). +disable the incremental recursion mode. These include: bf(--delete-before), +bf(--delete-after), bf(--prune-empty-dirs), bf(--delay-updates), and bf(--hard-links). Because of this, the default delete mode when you specify bf(--delete) is now -bf(--delete-during) (when both ends of the connection are at least 3.0.0; -use bf(--del) or bf(--delete-during) to request this improved deletion mode +bf(--delete-during) when both ends of the connection are at least 3.0.0 +(use bf(--del) or bf(--delete-during) to request this improved deletion mode explicitly). See also the bf(--delete-delay) option that is a better choice than using bf(--delete-after). @@ -628,7 +636,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 -(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 @@ -724,7 +732,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. -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). @@ -771,7 +779,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 - 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. )) @@ -802,9 +812,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 -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 @@ -822,6 +834,15 @@ quote(itemization( 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 @@ -941,7 +962,7 @@ combined with the bf(--ignore-existing) option, no files will be updated dit(bf(--ignore-existing)) This tells rsync to skip updating files that already exist on the destination (this does em(not) ignore existing -directores, or nothing would get done). See also bf(--existing). +directories, or nothing would get done). See also bf(--existing). dit(bf(--remove-source-files)) This tells rsync to remove from the sending side the files (meaning non-directories) that are a part of the transfer @@ -1113,7 +1134,7 @@ communicate. One tricky example is to set a different default directory on the remote machine for use with the bf(--relative) option. For instance: -quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/)) +quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/)) dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a broad range of files that you often don't want to transfer between @@ -1346,6 +1367,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. +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 @@ -1426,8 +1453,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). -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. @@ -1476,7 +1503,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). - 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 @@ -1613,7 +1644,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 -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 @@ -1655,7 +1686,7 @@ each file's destination directory, but if you've specified the bf(--partial-dir) option, that directory will be used instead. See the comments in the bf(--partial-dir) section for a discussion of how this ".~tmp~" dir will be excluded from the transfer, and what you can do if -you wnat rsync to cleanup old ".~tmp~" dirs that might be lying around. +you want rsync to cleanup old ".~tmp~" dirs that might be lying around. Conflicts with bf(--inplace) and bf(--append). This option uses more memory on the receiving side (one bit per file