o

support for copying links, devices, owners, groups, and permissions

o

exclude and exclude-from options similar to GNU tar

o

a CVS exclude mode for ignoring the same files that CVS would ignore

o

can use any transparent remote shell, including ssh or rsh

o

does not require root privileges

o

pipelining of file transfers to minimize latency costs

o

support for anonymous or authenticated rsync servers (ideal for mirroring)

o

for copying local files. This is invoked when neither source nor destination path contains a : separator

o

for copying from the local machine to a remote machine using a remote shell program as the transport (such as ssh or rsh). This is invoked when the destination path contains a single : separator.

o

for copying from a remote machine to the local machine using a remote shell program. This is invoked when the source contains a : separator.

o

for copying from a remote rsync server to the local machine. This is invoked when the source path contains a :: separator or an rsync:// URL.

o

for copying from the local machine to a remote rsync server. This is invoked when the destination path contains a :: separator or an rsync:// URL.

o

for copying from a remote machine using a remote shell program as the transport, using rsync server on the remote machine.  This is invoked when the source path contains a :: separator and the --rsh=COMMAND (aka "-e COMMAND") option is also provided.

o

for copying from the local machine to a remote machine using a remote shell program as the transport, using rsync server on the remote machine.  This is invoked when the destination path contains a :: separator and the --rsh=COMMAND option is also provided.

o

for listing files on a remote machine. This is done the same way as rsync transfers except that you leave off the local destination.

Note that in all cases (other than listing) at least one of the source and destination paths must be local.

o

you either use a double colon :: instead of a single colon to separate the hostname from the path, or you use an rsync:// URL.

o

the remote server may print a message of the day when you connect.

o

if you specify no path name on the remote server then the list of accessible paths on the server will be shown.

o

if you specify no local destination then a listing of the specified files on the remote server is provided.

Some paths on the remote server may require authentication. If so then you will receive a password prompt when you connect. You can avoid the password prompt by setting the environment variable RSYNC_PASSWORD to the password you want to use or using the --password-file option. This may be useful when scripting rsync.

WARNING: On some systems environment variables are visible to all users. On those systems using --password-file is recommended.

 
 
    rsync -av --rsh="ssh -l ssh-user" \ 
        rsync-user@host::module[/path] local-path

 
 
    get:
            rsync -avuzb --exclude '*~' samba:samba/ .
    put:
            rsync -Cavuzb . samba:samba/
    sync: get put

 
 

 -v, --verbose               increase verbosity
 -q, --quiet                 suppress non-error messages
 -c, --checksum              skip based on checksum, not mod-time & size
 -a, --archive               archive mode; same as -rlptgoD (no -H)
 -r, --recursive             recurse into directories
 -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 (see --suffix & --backup-dir)
     --backup-dir=DIR        make backups into hierarchy based in DIR
     --suffix=SUFFIX         backup suffix (default ~ w/o --backup-dir)
 -u, --update                skip files that are newer on the receiver
     --inplace               update destination files in-place
 -d, --dirs                  transfer directories without recursing
 -l, --links                 copy symlinks as symlinks
 -L, --copy-links            transform symlink into referent file/dir
     --copy-unsafe-links     only "unsafe" symlinks are transformed
     --safe-links            ignore symlinks that point outside the tree
 -H, --hard-links            preserve hard links
 -K, --keep-dirlinks         treat symlinked dir on receiver as dir
 -p, --perms                 preserve permissions
 -o, --owner                 preserve owner (root only)
 -g, --group                 preserve group
 -D, --devices               preserve devices (root only)
 -t, --times                 preserve times
 -O, --omit-dir-times        omit directories when preserving times
 -S, --sparse                handle sparse files efficiently
 -n, --dry-run               show what would have been transferred
 -W, --whole-file            copy files whole (without rsync algorithm)
     --no-whole-file         always use incremental rsync algorithm
 -x, --one-file-system       don't cross filesystem boundaries
 -B, --block-size=SIZE       force a fixed checksum block-size
 -e, --rsh=COMMAND           specify the remote shell to use
     --rsync-path=PROGRAM    specify the rsync to run on remote machine
     --existing              only update files that already exist
     --ignore-existing       ignore files that already exist on receiver
     --remove-sent-files     sent files/symlinks are removed from sender
     --del                   an alias for --delete-during
     --delete                delete files that don't exist on sender
     --delete-before         receiver deletes before transfer (default)
     --delete-during         receiver deletes during xfer, not before
     --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
     --delay-updates         put all updated files into place at end
     --numeric-ids           don't map uid/gid values by user/group name
     --timeout=TIME          set I/O timeout in seconds
 -I, --ignore-times          don't skip files that match size and time
     --size-only             skip files that match in size
     --modify-window=NUM     compare mod-times with reduced accuracy
 -T, --temp-dir=DIR          create temporary files in directory DIR
 -y, --fuzzy                 find similar file for basis if no dest file
     --compare-dest=DIR      also compare received files relative to DIR
     --copy-dest=DIR         ... and include copies of unchanged files
     --link-dest=DIR         hardlink to files in DIR when unchanged
 -z, --compress              compress file data during the transfer
 -C, --cvs-exclude           auto-ignore files in the same way CVS does
 -f, --filter=RULE           add a file-filtering RULE
 -F                          same as --filter='dir-merge /.rsync-filter'
                             repeated: --filter='- .rsync-filter'
     --exclude=PATTERN       exclude files matching PATTERN
     --exclude-from=FILE     read exclude patterns from FILE
     --include=PATTERN       don't exclude files matching PATTERN
     --include-from=FILE     read include patterns from FILE
     --files-from=FILE       read list of source-file names from FILE
 -0, --from0                 all *from file lists are delimited by nulls
     --version               print version number
     --port=PORT             specify double-colon alternate port number
     --blocking-io           use blocking I/O for the remote shell
     --no-blocking-io        turn off blocking I/O when it is default
     --stats                 give some file-transfer stats
     --progress              show progress during transfer
 -P                          same as --partial --progress
 -i, --itemize-changes       output a change-summary for all updates
     --log-format=FORMAT     log file-transfers using specified format
     --password-file=FILE    read password from FILE
     --list-only             list the files instead of copying them
     --bwlimit=KBPS          limit I/O bandwidth; KBytes per second
     --write-batch=FILE      write a batched update to FILE
     --read-batch=FILE       read a batched update from FILE
     --protocol=NUM          force an older protocol version to be used
     --checksum-seed=NUM     set block/file checksum seed (advanced)
 -4, --ipv4                  prefer IPv4
 -6, --ipv6                  prefer IPv6
 -h, --help                  show this help screen

 
 

     --daemon                run as an rsync daemon
     --address=ADDRESS       bind to the specified address
     --bwlimit=KBPS          limit I/O bandwidth; KBytes per second
     --config=FILE           specify alternate rsyncd.conf file
     --no-detach             do not detach from the parent
     --port=PORT             listen on alternate port number
 -v, --verbose               increase verbosity
 -4, --ipv4                  prefer IPv4
 -6, --ipv6                  prefer IPv6
 -h, --help                  show this help screen

"-h,

Print a short help page describing the options available in rsync.

"--version"

print the rsync version number and exit.

"-v,

This option increases the amount of information you are given during the transfer.  By default, rsync works silently. A single -v will give you information about what files are being transferred and a brief summary at the end. Two -v flags will give you information on what files are being skipped and slightly more information at the end. More than two -v flags should only be used if you are debugging rsync.

Note that the names of the transferred files that are output are done using a default --log-format of "%n%L", which tells you just the name of the file and, if the item is a symlink, where it points.  At the single -v level of verbosity, this does not mention when a file gets its attributes changed.  If you ask for an itemized list of changed attributes (either --itemize-changes or adding "%i" to the --log-format setting), the output (on the client) increases to mention all items that are changed in any way.  See the --log-format option for more details.

"-q,

This option decreases the amount of information you are given during the transfer, notably suppressing information messages from the remote server. This flag is useful when invoking rsync from cron.

"-I,

Normally rsync will skip any files that are already the same size and have the same modification time-stamp. This option turns off this "quick check" behavior.

"--size-only"

Normally rsync will not transfer any files that are already the same size and have the same modification time-stamp. With the --size-only option, files will not be transferred if they have the same size, regardless of timestamp. This is useful when starting to use rsync after using another mirroring system which may not preserve timestamps exactly.

"--modify-window"

When comparing two timestamps, rsync treats the timestamps as being equal if they differ by no more than the modify-window value.  This is normally 0 (for an exact match), but you may find it useful to set this to a larger value in some situations.  In particular, when transferring to or from an MS Windows FAT filesystem (which represents times with a 2-second resolution), --modify-window=1 is useful (allowing times to differ by up to 1 second).

"-c,

This forces the sender to checksum all files using a 128-bit MD4 checksum before transfer. The checksum is then explicitly checked on the receiver and any files of the same name which already exist and have the same checksum and size on the receiver are not transferred.  This option can be quite slow.

"-a,

This is equivalent to -rlptgoD. It is a quick way of saying you want recursion and want to preserve almost everything.  The only exception to this is if --files-from was specified, in which case -r is not implied.

Note that -a does not preserve hardlinks, because finding multiply-linked files is expensive.  You must separately specify -H.

"-r,

This tells rsync to copy directories recursively.  See also --dirs (-d).

"-R,

Use relative paths. This means that the full path names specified on the command line are sent to the server rather than just the last parts of the filenames. This is particularly useful when you want to send several different directories at the same time. For example, if you used the command

then this would create a file called foo.c in /tmp/ on the remote machine. If instead you used

then a file called /tmp/foo/bar/foo.c would be created on the remote machine -- the full path name is preserved.  To limit the amount of path information that is sent, do something like this:

That would create /tmp/bar/foo.c on the remote machine.

"--no-relative"

Turn off the --relative option.  This is only needed if you want to use --files-from without its implied --relative file processing.

"--no-implied-dirs"

When combined with the --relative option, the implied directories in each path are not explicitly duplicated as part of the transfer.  This makes the transfer more optimal and also allows the two sides to have non-matching symlinks in the implied part of the path.  For instance, if you transfer the file "/path/foo/file" with -R, the default is for rsync to ensure that "/path" and "/path/foo" on the destination exactly match the directories/symlinks of the source.  Using 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.

"-b,

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. Note that if you don't specify --backup-dir, the --omit-dir-times option will be enabled.

"--backup-dir=DIR"

In combination with the --backup option, this tells rsync to store all backups in the specified directory. This is very useful for incremental backups.  You can additionally specify a backup suffix using the --suffix option (otherwise the files backed up in the specified directory will keep their original filenames).

"--suffix=SUFFIX"

This option allows you to override the default 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.

"-u,

This forces rsync to skip any files which exist on the destination and have a modified time that is newer than the source file.  (If an existing destination file has a modify time equal to the source file's, it will be updated if the sizes are different.)

In the current implementation of --update, a difference of file format between the sender and receiver is always considered to be important enough for an update, no matter what date is on the objects.  In other words, if the source has a directory or a 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).

"--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 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 and --delay-updates. Prior to rsync 2.6.4 --inplace was also incompatible with --compare-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 in-place that is not writable by the receiving user.

"-d,

Tell the sending side to include 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).

"-l,

When symlinks are encountered, recreate the symlink on the destination.

"-L,

When symlinks are encountered, the file that they point to (the referent) is copied, rather than the symlink.  In older versions of rsync, this option also had the side-effect of telling the receiving side to follow symlinks, such as symlinks to directories.  In a modern rsync such as this one, you'll need to specify --keep-dirlinks (-K) to get this extra behavior.  The only exception is when sending files to an rsync that is too old to understand -K -- in that case, the -L option will still have the side-effect of -K on that older receiving rsync.

"--copy-unsafe-links"

This tells rsync to copy the referent of symbolic links that point outside the copied tree.  Absolute symlinks are also treated like ordinary files, and so are any symlinks in the source path itself when --relative is used.

"--safe-links"

This tells rsync to ignore any symbolic links which point outside the copied tree. All absolute symlinks are also ignored. Using this option in conjunction with --relative may give unexpected results.

"-H,

This tells rsync to recreate hard  links  on the  remote system  to  be the same as the local system. Without this option hard links are treated like regular files.

Note that rsync can only detect hard links if both parts of the link are in the list of files being sent.

This option can be quite slow, so only use it if you need it.

"-K,

On the receiving side, if a symlink is pointing to a directory, it will be treated as matching a directory from the sender.

"-W,

With this option the incremental rsync algorithm is not used and the whole file is sent as-is instead.  The transfer may be faster if this option is used when the bandwidth between the source and destination machines is higher than the bandwidth to disk (especially when the "disk" is actually a networked filesystem).  This is the default when both the source and destination are specified as local paths.

"--no-whole-file"

Turn off --whole-file, for use when it is the default.

"-p,

This option causes rsync to set the destination permissions to be the same as the source permissions.

Without this option, each new file gets its permissions set based on the source file's permissions and the umask at the receiving end, while all other files (including updated files) retain their existing permissions (which is the same behavior as other file-copy utilities, such as cp).

"-o,

This option causes rsync to set the owner of the destination file to be the same as the source file.  On most systems, only the super-user can set file ownership.  By default, the preservation is done by name, but may fall back to using the ID number in some circumstances.  See the --numeric-ids option for a full discussion.

"-g,

This option causes rsync to set the group of the destination file to be the same as the source file.  If the receiving program is not running as the super-user, only groups that the receiver is a member of will be preserved.  By default, the preservation is done by name, but may fall back to using the ID number in some circumstances.  See the --numeric-ids option for a full discussion.

"-D,

This option causes rsync to transfer character and block device information to the remote system to recreate these devices. This option is only available to the super-user.

"-t,

This tells rsync to transfer modification times along with the files and update them on the remote system.  Note that if this option is not used, the optimization that excludes files that have not been modified cannot be effective; in other words, a missing -t or -a will cause the next transfer to behave as if it used -I, causing all files to be updated (though the rsync algorithm will make the update fairly efficient if the files haven't actually changed, you're much better off using -t).

"-O,

This tells rsync to omit directories when it is preserving modification times (see --times).  If NFS is sharing the directories on the receiving side, it is a good idea to use -O. This option is inferred if you use --backup without --backup-dir.

"-n,

This tells rsync to not do any file transfers, instead it will just report the actions it would have taken.

"-S,

Try to handle sparse files efficiently so they take up less space on the destination.

NOTE: Don't use this option when the destination is a Solaris "tmpfs" filesystem. It doesn't seem to handle seeks over null regions correctly and ends up corrupting the files.

"-x,

This tells rsync not to cross filesystem boundaries  when recursing.  This  is useful for transferring the contents of only one filesystem.

"--existing"

This tells rsync not to create any new files -- only update files that already exist on the destination.

"--ignore-existing"

This tells rsync not to update files that already exist on the destination.

"--remove-sent-files"

This tells rsync to remove from the sending side the files and/or symlinks that are newly created or whose content is updated on the receiving side.  Directories and devices are not removed, nor are files/symlinks whose attributes are merely changed.

"--delete"

This tells rsync to delete extraneous files from the receiving side (ones that aren't on the sending side), but only for the directories that are being synchronized.  You must have asked rsync to send the whole directory (e.g. "dir" or "dir/") without using a wildcard for the directory's contents (e.g. "dir/*") since the wildcard is expanded by the shell and rsync thus gets a request to transfer individual files, not the files' parent directory.  Files that are excluded from transfer are also excluded from being deleted unless you use the --delete-excluded option or mark the rules as only matching on the sending side (see the include/exclude modifiers in the FILTER RULES section).

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 deleted to make sure important files aren't listed.

If the sending side detects any I/O errors, then the deletion of any files at the destination will be automatically disabled. This is to 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.

The --delete option may be combined with one of the --delete-WHEN options without conflict, as well as --delete-excluded.  However, if none of the --delete-WHEN options are specified, rsync will currently choose the --delete-before algorithm.  A future version may change this to choose the --delete-during algorithm.  See also --delete-after.

"--delete-before"

Request that the file-deletions on the receiving side be done before the transfer starts.  This is the default if --delete or --delete-excluded is specified without one of the --delete-WHEN options. See --delete (which is implied) for more details on file-deletion.

Deleting before the transfer is helpful if the filesystem is tight for space and removing extraneous files would help to make the transfer possible. However, it does introduce a delay before the start of the transfer, and this delay might cause the transfer to timeout (if --timeout was specified).

"--delete-during,

Request that the file-deletions on the receiving side be done incrementally as the transfer happens.  This is a faster method than choosing the before- or after-transfer algorithm, but it is only supported beginning with rsync version 2.6.4. See --delete (which is implied) for more details on file-deletion.

"--delete-after"

Request that the file-deletions on the receiving side be done after the transfer has completed.  This is useful if you are sending new per-directory merge files as a part of the transfer and you want their exclusions to take effect for the delete phase of the current transfer. See --delete (which is implied) for more details on file-deletion.

"--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). See the FILTER RULES section for a way to make individual exclusions behave this way on the receiver, and for a way to protect files from --delete-excluded. See --delete (which is implied) for more details on file-deletion.

"--ignore-errors"

Tells --delete to go ahead and delete files even when there are I/O errors.

"--force"

This options tells rsync to delete directories even if they are not empty when they are to be replaced by non-directories.  This is only relevant without --delete because deletions are now done depth-first. Requires the --recursive option (which is implied by -a) to have any effect.

"--max-delete=NUM"

This tells rsync not to delete more than NUM files or directories (NUM must be non-zero). This is useful when mirroring very large trees to prevent disasters.

"--max-size=SIZE"

This tells rsync to avoid transferring any file that is larger than the specified SIZE. The SIZE value can be suffixed with a letter to indicate a size multiplier (K, M, or G) and may be a fractional value (e.g. "--max-size=1.5m").

"-B,

This forces the block size used in the rsync algorithm to a fixed value.  It is normally selected based on the size of each file being updated.  See the technical report for details.

"-e,

This option allows you to choose an alternative remote shell program to use for communication between the local and remote copies of rsync. Typically, rsync is configured to use ssh by default, but you may prefer to use rsh on a local network.

If this option is used with [user@]host::module/path, then the remote shell COMMAND will be used to run an rsync server on the remote host, and all data will be transmitted through that remote shell connection, rather than through a direct socket connection to a running rsync server on the remote host.  See the section "CONNECTING TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM" above.

Command-line arguments are permitted in COMMAND provided that COMMAND is presented to rsync as a single argument.  For example:

(Note that ssh users can alternately customize site-specific connect options in their .ssh/config file.)

You can also choose the remote shell program using the RSYNC_RSH environment variable, which accepts the same range of values as -e.

See also the --blocking-io option which is affected by this option.

"--rsync-path=PROGRAM"

Use this to specify what program is to be run on the remote machine to start-up rsync.  Often used when rsync is not in the default remote-shell's path (e.g. --rsync-path=/usr/local/bin/rsync). Note that PROGRAM is run with the help of a shell, so it can be any program, script, or command sequence you'd care to run, so long as it does not corrupt the standard-in & standard-out that rsync is using to communicate.

One tricky example is to set a different default directory on the remote machine for use with the --relative option.  For instance:

"-C,

This is a useful shorthand for excluding a broad range of files that you often don't want to transfer between systems. It uses the same algorithm that CVS uses to determine if a file should be ignored.

The exclude list is initialized to: