X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/e8b155a3bef9531f14b7fcca8b6e81fbdd3b9fba..65e4cda05976751030ccf280c96edb627584a496:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 589545ac..77f462ad 100644 --- a/rsync.yo +++ b/rsync.yo @@ -318,7 +318,8 @@ verb( --backup-dir make backups into this directory --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) - --inplace update the destination files inplace + --inplace update the destination files in-place + -k, --keep-dirs transfer a directory without recursing -K, --keep-dirlinks treat symlinked dir on receiver as dir -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of all symlinks @@ -341,14 +342,14 @@ verb( --existing only update files that already exist --ignore-existing ignore files that already exist on receiver --delete delete files that don't exist on sender - --delete-excluded also delete excluded files on receiver --delete-after receiver deletes after transfer, not before + --delete-excluded also delete excluded files on receiver --ignore-errors delete even if there are I/O errors + --force force deletion of dirs even if not empty --max-delete=NUM don't delete more than NUM files --max-size=SIZE don't transfer any file larger than SIZE --partial keep partially transferred files --partial-dir=DIR put a partially transferred file into DIR - --force force deletion of dirs even if not empty --numeric-ids don't map uid/gid values by user/group name --timeout=TIME set I/O timeout in seconds -I, --ignore-times turn off mod time & file size quick check @@ -458,8 +459,7 @@ finding multiply-linked files is expensive. You must separately specify bf(-H). dit(bf(-r, --recursive)) This tells rsync to copy directories -recursively. If you don't specify this then rsync won't copy -directories at all. +recursively. See also --keep-dirs (-k). dit(bf(-R, --relative)) Use relative paths. This means that the full path names specified on the command line are sent to the server rather than @@ -529,29 +529,38 @@ symlink where the destination has a file, the transfer would occur regardless of the timestamps. This might change in the future (feel free to comment on this on the mailing list if you have an opinion). +dit(bf(-k, --keep-dirs)) Tell the sending side to keep any directories that +are encountered. Unlike --recursive, a directory's contents are not copied +unless the directory was specified on the command-line as either "." or a +name with a trailing slash (e.g. "foo/"). Without this option or the +--recursive option, rsync will skip all directories it encounters (and +output a message to that effect for each one). + dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is pointing to a directory, it will be treated as matching a directory from the sender. dit(bf(--inplace)) This causes rsync not to create a new copy of the file and then move it into place. Instead rsync will overwrite the existing -file, meaning that the rsync algorithm can't extract the full amount of -network reduction it might otherwise (since it does not yet try to sort -data matches -- a future version may improve this). +file, meaning that the rsync algorithm can't accomplish the full amount of +network reduction it might be able to otherwise (since it does not yet try +to sort data matches). One exception to this is if you combine the option +with --backup, since rsync is smart enough to use the backup file as the +basis file for the transfer. This option is useful for transfer of large files with block-based changes or appended data, and also on systems that are disk bound, not network bound. The option implies --partial (since an interrupted transfer does not delete -the file), but conflicts with --partial-dir, --compare-dest, --copy-dest, and ---link-dest (a future rsync version will hopefully update the protocol to -remove some of these restrictions). +the file), but conflicts with --partial-dir. Prior to rsync 2.6.4 +--inplace was also incompatible with --compare-dest, --copy-dest, and +--link-dest. WARNING: The file's data will be in an inconsistent state during the transfer (and possibly afterward if the transfer gets interrupted), so you should not use this option to update files that are in use. Also note that -rsync will be unable to update a file inplace that is not writable by the +rsync will be unable to update a file in-place that is not writable by the receiving user. dit(bf(-l, --links)) When symlinks are encountered, recreate the @@ -667,7 +676,7 @@ by the shell and rsync thus gets a request to transfer those files, not the files' parent directory. Files that are excluded from transfer are excluded from being deleted unless you use --delete-excluded. -This option has no effect if directory recursion is not selected. +This option has no effect unless directory recursion is enabled. This option can be dangerous if used incorrectly! It is a very good idea to run first using the --dry-run option (-n) to see what files would be @@ -679,11 +688,6 @@ prevent temporary filesystem failures (such as NFS errors) on the sending side causing a massive deletion of files on the destination. You can override this with the --ignore-errors option. -dit(bf(--delete-excluded)) In addition to deleting the files on the -receiving side that are not on the sending side, this tells rsync to also -delete any files on the receiving side that are excluded (see --exclude). -Implies --delete. - dit(bf(--delete-after)) By default rsync does file deletions on the receiving side before transferring files to try to ensure that there is sufficient space on the receiving filesystem. If you want to delete @@ -693,6 +697,11 @@ One reason to use --delete-after is to avoid a delay before the start of the transfer (while the receiving side is scanned for deletions) as this delay might cause the transfer to timeout. +dit(bf(--delete-excluded)) In addition to deleting the files on the +receiving side that are not on the sending side, this tells rsync to also +delete any files on the receiving side that are excluded (see --exclude). +Implies --delete. + dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files even when there are I/O errors. @@ -873,8 +882,8 @@ See also --compare-dest and --copy-dest. Note that rsync versions prior to 2.6.1 had a bug that could prevent --link-dest from working properly for a non-root user when -o was specified -(or implied by -a). If the receiving rsync is not new enough, you can work -around this bug by avoiding the -o option. +(or implied by -a). You can work-around this bug by avoiding the -o option +when sending to an old rsync. dit(bf(-z, --compress)) With this option, rsync compresses any data from the files that it sends to the destination machine. This @@ -1170,7 +1179,8 @@ look at the output when using --verbose and put a / in front of the name Note that, when using the --recursive (-r) option (which is implied by -a), every subcomponent of every path is visited from the top down, so include/exclude patterns get -applied recursively to each subcomponent. +applied recursively to each subcomponent's full name (e.g. to include +"/foo/bar/baz" the subcomponents "/foo" and "/foo/bar" must not be excluded). The exclude patterns actually short-circuit the directory traversal stage when rsync finds the files to send. If a pattern excludes a particular parent directory, it can render a deeper include pattern ineffectual