X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/2624e005e2c2407c8e108230e6615d2aaba42617..75a1a04847beb40a6fb1ce684562c358843a56fb:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 5f5365aa..c09114eb 100644 --- a/rsync.yo +++ b/rsync.yo @@ -781,7 +781,9 @@ quote(itemization( it() The file's data will be in an inconsistent state during the transfer and will be left that way if the transfer is interrupted or if an update fails. - it() A file that does not have write permissions cannot be updated. + it() A file that rsync cannot write to cannot be updated. While a super user + can update any file, a normal user needs to be granted write permission for + the open of the file for writing to be successful. it() The efficiency of rsync's delta-transfer algorithm may be reduced if some data in the destination file is overwritten before it can be copied to a position later in the file. This does not apply if you use bf(--backup), @@ -794,7 +796,8 @@ accessed by others, so be careful when choosing to use this for a copy. This option is useful for transferring large files with block-based changes or appended data, and also on systems that are disk bound, not network -bound. +bound. It can also help keep a copy-on-write filesystem snapshot from +diverging the entire contents of a file that only has minor changes. The option implies bf(--partial) (since an interrupted transfer does not delete the file), but conflicts with bf(--partial-dir) and bf(--delay-updates). @@ -940,13 +943,14 @@ destination exactly matches that on the source. Cases in which the destination may end up with extra hard links include the following: quote(itemization( - it() If the destination already contains hard links, rsync will not break - them explicitly. However, if one or more of the paths have content - differences, the normal file-update process will break those links, unless - you are using the bf(--inplace) option. + it() If the destination contains extraneous hard-linked files, rsync will not + break them explicitly. However, if one or more of the paths have content + differences, the normal file-update process will break those extra links + (unless you are using the bf(--inplace) option). it() If you specify a bf(--link-dest) directory that contains hard links, - rsync may use the same bf(--link-dest) file multiple times via several of - its paths. + the linking of the destination files against the bf(--link-dest) files can + cause some paths in the destination to become linked together due to the + bf(--link-dest) associations. )) Note that rsync can only detect hard links between files that are inside @@ -960,7 +964,10 @@ see the bf(--inplace) option for more caveats). If incremental recursion is active (see bf(--recursive)), rsync may transfer a missing hard-linked file before it finds that another link for that contents exists elsewhere in the hierarchy. This does not affect the accuracy of -the transfer, just its efficiency. One way to avoid this is to disable +the transfer (i.e. which files are hard-linked together), just its efficiency +(i.e. copying the data for a new, early copy of a hard-linked file that could +have been found later in the transfer in another member of the hard-linked +set of files). One way to avoid this inefficiency is to disable incremental recursion using the bf(--no-inc-recursive) option. dit(bf(-p, --perms)) This option causes the receiving rsync to set the @@ -1051,7 +1058,7 @@ used by bf(--fake-super)) unless you repeat the option (e.g. -XX). This "copy all xattrs" mode cannot be used with bf(--fake-super). dit(bf(--chmod)) This option tells rsync to apply one or more -comma-separated "chmod" strings to the permission of the files in the +comma-separated "chmod" modes to the permission of the files in the transfer. The resulting value is treated as though it were the permissions that the sending side supplied for the file, which means that this option can seem to have no effect on existing files if bf(--perms) is not enabled. @@ -1059,10 +1066,17 @@ can seem to have no effect on existing files if bf(--perms) is not enabled. In addition to the normal parsing rules specified in the bf(chmod)(1) manpage, you can specify an item that should only apply to a directory by prefixing it with a 'D', or specify an item that should only apply to a -file by prefixing it with a 'F'. For example: +file by prefixing it with a 'F'. For example, the following will ensure +that all directories get marked set-gid, that no files are other-writable, +that both are user-writable and group-writable, and that both have +consistent executability across all bits: quote(--chmod=Dg+s,ug+w,Fo-w,+X) +Using octal mode numbers is also allowed: + +quote(--chmod=D2775,F664) + It is also legal to specify multiple bf(--chmod) options, as each additional option is just appended to the list of changes to make. @@ -1163,10 +1177,6 @@ dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take up less space on the destination. Conflicts with bf(--inplace) because it's not possible to overwrite data in a sparse fashion. -NOTE: Don't use this option when the destination is a Solaris "tmpfs" -filesystem. It seems to have problems seeking over null regions, -and ends up corrupting the files. - 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 @@ -1476,7 +1486,7 @@ 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/ .git/ .bzr/))) +*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .hg/ .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 @@ -1606,6 +1616,12 @@ bf(--files-from) filenames are being sent from one host to another, the filenames will be translated from the sending host's charset to the receiving host's charset. +NOTE: sorting the list of files in the --files-from input helps rsync to be +more efficient, as it will avoid re-visiting the path elements that are shared +between adjacent entries. If the input is not sorted, some path elements +(implied directories) may end up being scanned multiple times, and rsync will +eventually unduplicate them after they get turned into file-list elements. + dit(bf(-0, --from0)) This tells rsync that the rules/filenames it reads from a file are terminated by a null ('\0') character, not a NL, CR, or CR+LF. This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any