X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/986066873e17c4152c2bc6e77fe9b83fb65132d9..84c3645cea7607c23f5e70a6ee8a639039ade2bd:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 9b74edb7..f116976a 100644 --- a/rsync.yo +++ b/rsync.yo @@ -115,7 +115,7 @@ Perhaps the best way to explain the syntax is some examples: quote(rsync *.c foo:src/) -this would transfer all files matching the pattern *.c from the +This would transfer all files matching the pattern *.c from the current directory to the directory src on the machine foo. If any of the files already exist on the remote system then the rsync remote-update protocol is used to update the file by sending only the @@ -123,7 +123,7 @@ differences. See the tech report for details. quote(rsync -avz foo:src/bar /data/tmp) -this would recursively transfer all files from the directory src/bar on the +This would recursively transfer all files from the directory src/bar on the machine foo into the /data/tmp/bar directory on the local machine. The files are transferred in "archive" mode, which ensures that symbolic links, devices, attributes, permissions, ownerships etc are preserved @@ -132,12 +132,17 @@ size of data portions of the transfer. quote(rsync -avz foo:src/bar/ /data/tmp) -a trailing slash on the source changes this behavior to transfer -all files from the directory src/bar on the machine foo into the -/data/tmp/. A trailing / on a source name means "copy the -contents of this directory". Without a trailing slash it means "copy -the directory". This difference becomes particularly important when -using the --delete option. +A trailing slash on the source changes this behavior to avoid creating an +additional directory level at the destination. You can think of a trailing +/ on a source as meaning "copy the contents of this directory" as opposed +to "copy the directory by name", but in both cases the attributes of the +containing directory are transferred to the containing directory on the +destination. In other words, each of the following commands copies the +files in the same way, including their setting of the attributes of +/dest/foo: + +quote(rsync -avz /src/foo /dest) +quote(rsync -avz /src/foo/ /dest/foo) You can also use rsync in local-only mode, where both the source and destination don't have a ':' in the name. In this case it behaves like @@ -145,7 +150,7 @@ an improved copy command. quote(rsync somehost.mydomain.com::) -this would list all the anonymous rsync modules available on the host +This would list all the anonymous rsync modules available on the host somehost.mydomain.com. (See the following section for more details.) @@ -290,9 +295,9 @@ verb( -R, --relative use relative path names --no-relative turn off --relative --no-implied-dirs don't send implied dirs with -R - -b, --backup make backups (default ~ suffix) + -b, --backup make backups (see --suffix) --backup-dir make backups into this directory - --suffix=SUFFIX define backup suffix + --suffix=SUFFIX define backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of symlinks @@ -452,9 +457,10 @@ the --no-implied-dirs option would omit both of these implied dirs, which means that if "/path" was a real directory on one machine and a symlink of the other machine, rsync would not try to change this. -dit(bf(-b, --backup)) With this option preexisting destination files are -renamed with a ~ extension as each file is transferred. You can -control the backup suffix using the --suffix option. +dit(bf(-b, --backup)) With this option, preexisting destination files are +renamed as each file is transferred or deleted. You can control where the +backup file goes and what (if any) suffix gets appended using the +--backup-dir and --suffix options. dit(bf(--backup-dir=DIR)) In combination with the --backup option, this tells rsync to store all backups in the specified directory. This is @@ -464,9 +470,8 @@ specify a backup suffix using the --suffix option will keep their original filenames). dit(bf(--suffix=SUFFIX)) This option allows you to override the default -backup suffix used with the -b option. The default is a ~. -If --backup-dir and --suffix are both specified, -the SUFFIX is appended to the filename even in the backup directory. +backup suffix used with the --backup (-b) option. The default suffix is a ~ +if no --backup-dir was specified, otherwise it is an empty string. dit(bf(-u, --update)) This forces rsync to skip any files for which the destination file already exists and has a date later than the source @@ -832,9 +837,7 @@ make a subsequent transfer of the rest of the file much faster. dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. - -This option is normally combined with -v. Using this option without -the -v option will produce weird results on your display. +Implies --verbose without incrementing verbosity. dit(bf(-P)) The -P option is equivalent to --partial --progress. I found myself typing that combination quite often so I created an @@ -916,15 +919,15 @@ itemize( *?[ then expression matching is applied using the shell filename matching rules. Otherwise a simple string match is used. - it() if the pattern includes a double asterisk "**" then all wildcards in - the pattern will match slashes, otherwise they will stop at slashes. + it() the double asterisk pattern "**" will match slashes while a + single asterisk pattern "*" will stop at slashes. it() if the pattern contains a / (not counting a trailing /) or a "**" then it is matched against the full filename, including any leading directory. If the pattern doesn't contain a / or a "**", then it is matched only against the final component of the filename. Again, remember that the algorithm is applied recursively so "full filename" can - actually be any portion of a path. + actually be any portion of a path below the starting directory. it() if the pattern starts with "+ " (a plus followed by a space) then it is always considered an include pattern, even if specified as @@ -1012,9 +1015,9 @@ once, instead of sending the same data to every host individually. Example: verb( -$ rsync --write_batch=pfx -a /source/dir/ /adest/dir/ +$ rsync --write-batch=pfx -a /source/dir/ /adest/dir/ $ rcp pfx.rsync_* remote: -$ rsh remote rsync --read_batch=pfx -a /bdest/dir/ +$ rsh remote rsync --read-batch=pfx -a /bdest/dir/ # or alternatively $ rsh remote ./pfx.rsync_argvs /bdest/dir/ ) @@ -1106,24 +1109,26 @@ show why each individual file is included or excluded. manpagesection(EXIT VALUES) startdit() -dit(bf(RERR_SYNTAX 1)) Syntax or usage error -dit(bf(RERR_PROTOCOL 2)) Protocol incompatibility -dit(bf(RERR_FILESELECT 3)) Errors selecting input/output files, dirs +dit(bf(1)) Syntax or usage error +dit(bf(2)) Protocol incompatibility +dit(bf(3)) Errors selecting input/output files, dirs -dit(bf(RERR_UNSUPPORTED 4)) Requested action not supported: an attempt +dit(bf(4)) Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that cannot support them; or an option was speciifed that is supported by the client and not by the server. -dit(bf(RERR_SOCKETIO 10)) Error in socket IO -dit(bf(RERR_FILEIO 11)) Error in file IO -dit(bf(RERR_STREAMIO 12)) Error in rsync protocol data stream -dit(bf(RERR_MESSAGEIO 13)) Errors with program diagnostics -dit(bf(RERR_IPC 14)) Error in IPC code -dit(bf(RERR_SIGNAL 20)) Received SIGUSR1 or SIGINT -dit(bf(RERR_WAITCHILD 21)) Some error returned by waitpid() -dit(bf(RERR_MALLOC 22)) Error allocating core memory buffers -dit(bf(RERR_TIMEOUT 30)) Timeout in data send/receive +dit(bf(5)) Error starting client-server protocol +dit(bf(10)) Error in socket IO +dit(bf(11)) Error in file IO +dit(bf(12)) Error in rsync protocol data stream +dit(bf(13)) Errors with program diagnostics +dit(bf(14)) Error in IPC code +dit(bf(20)) Received SIGUSR1 or SIGINT +dit(bf(21)) Some error returned by waitpid() +dit(bf(22)) Error allocating core memory buffers +dit(bf(23)) Partial transfer +dit(bf(30)) Timeout in data send/receive enddit() manpagesection(ENVIRONMENT VARIABLES)