Click on any of the 687 commands below to get a description and list of available options. All links in the command summaries point to the online version of the book on Safari Bookshelf.
Transfer files; used frequently for updating files across a network. File transfer with rsync is fast and efficient because it checks local files against remote files in small chunks, or blocks, and transfers only the blocks that differ between the files.
sources and the final dest are in the form of:
user@host:port/filename
If the file is on the local host, a plain filename can be specified. If the file is on a remote host, the host must also be specified. user can optionally be specified to log in as a different user on the remote site (in which case a password prompt might appear) and port can optionally be specified with a remote host to make rsync use a TCP port other than its default, 873.
Relative filenames (names without initial slashes) are handled relative to the user's home directory. If a source directory is listed with a trailing slash, the whole directory is transferred and will appear under the destination directory; if the directory is listed without the slash, its files and subdirectories will appear directly under the destination directory. Normally, regular directories and files are transferred, but not symbolic links or other special files such as sockets and FIFOs.
Two other formats for sources and dest, which refer to files on an rsync server (rsyncd), are:
Specify that the file specified in options such as --files-from is formatted with null characters to separate the filenames; when this option is not used, the file must include each filename on a separate line.
-a, --archive
Like -r, but reproduce nearly all characteristics of the files and directories being transferred, such as modification times, symbolic links, ownership, and permissions.
--address=addr
Specify the IP address of an rsync server to connect to; useful when multiple servers are running on the same host.
-b, --backup
Preserve existing files at the destination by appending a suffix such as ~ while transferring new versions of those files.
-Bn, --block-size=n
Change block size used for transfers.
--backup-dir
Specify where files created by the --backup option are stored.
--blocking-io
Use blocking I/O when starting the remote shell used for transfer.
--bwlimit=n
Set a limit to the speed of transfer, specified in kilobytes per second.
-c, --checksum
Perform a full checksum on each file transferred.
-C, --cvs-exclude
Don't transfer files that are normally considered temporary or otherwise uninteresting; obeys the same rules for ignoring files as CVS (described in Chapter 1).
--compare-dest=dir
Compare source files to files of the same name in dir as well as the destination directory.
--compress
Use compression during transmission.
--config=configfile
When running as server, take configuration from configfile instead of /etc/rsyncd.conf.
--copy-links
Transfer the files to which symbolic links are made instead of just the pointer information in the links.
--copy-unsafe-links
If files to which symbolic links point are being transferred, copy even those files that exist outside the directories being transferred.
--daemon
Run rsync as server.
-D, --devices
Transfer device (/dev) files; requires superuser permission on both systems.
--delete-after
After transferring files from a source directory, delete any files from the destination directory that do not exist in the source directory.
--delete
Before transferring files from a source directory, delete any files from the destination directory that do not exist in the source directory.
--delete-excluded
Invoke --delete, and additionally delete from the destination directory any files that match exclude options.
--dry-run
Display the names of files that would be transferred and statistics related to a transfer, without performing a transfer.
-eshell
Use shell (which can be a complete command with arguments, enclosed in quotes) to create the connection between two systems for file transfer. rsync uses rsh by default. Nowadays, most users prefer the secure shell ssh. This can be made the default by setting the environment variable RSYNC_RSH=ssh.
--exclude-from=file
Like --exclude, but globbing patterns are taken from file. each pattern on a separate line.
--exclude=glob-pattern
Don't transfer files whose names match glob-pattern. Rules for glob-pattern are complex and are described in the manpage. In general, filenames can include the shell globbing characters * to match everything, ? to match a single character, and [] to enclose a set of matching characters. Furthermore, to specify the beginning of a filename, start the name with a / character (it does not mean the file has to be an absolute pathname).
--existing
Transfer only files that already exist on the destination host.
--files-from=file
Take names of files to transfer from file.
--force
Allow a file to replace a non-empty directory of the same name.
--from0
Synonym for -0.
-g, --group
Set the group (normally identified by name, not number) of the destination file to match that of the source file, instead of using the group running the rsync program.
-H, --hard-links
Set hard links on destination system to match source system.
-h, --help
Display command syntax and options.
--ignore-errors
Delete files even when there are I/O errors.
--ignore-existing
Do not transfer files to replace existing files of the same name.
-I, --ignore-times
Consider files for transfer even if they have the same size and timestamp as destination files.
--include-from=file
Like --include, but globbing patterns are taken from file, which has each pattern listed on a separate line.
--include=glob-pattern
Specify files to be transferred even if further exclude options would cause them to be ignored. rsync processes the include and exclude options in the order they appear on the command line, so earlier include options override later exclude options.
-l, --links
Set symbolic links on destination system to match source system.
-L
Synonym for --copy-links.
--log-format=format
Display information about each file transferred in a format specified by % sequences; see rsyncd.conf manpage for formats.
--max-delete=n
Delete at most n files when deleting from destination host.
-n
Synonym for --dry-run.
--no-blocking-io
Do not use blocking I/O when starting the remote shell used for transfer.
--no-detach
When running as a daemon, do not restart as a background process.
--no-implied-dirs
When preserving directory structures with --relative, do not force the creation of new directories or symbolic links if the destination host is set up differently from the source host.
--no-relative
Transfer only the plain files without preserving the entire directory structure of files whose names include directories; otherwise, --files-from would create the entire directory structure to contain the file.
--no-whole-file
Use rsync's block checks to transfer parts of files where possible.
--numeric-ids
Set user and group IDs on destination files by number rather than name.
-o, --owner
Set the user (normally identified by name, not number) of the destination file to match that of the source file, instead of settng it to the user running the rsync program.
--one-file-system
When traversing directories, do not transfer files on directories that are mounted on other filesystems.
-p, --perms
Set the permissions of the destination file to match that of the source file, instead of using the existing file's permissions or the default umask of the destination user.
-P
Combination of --partial and --progress.
--partial
Preserve partial files transferred if rsync is interrupted.
--password-file=file
Take password for accessing a remote rsync server from file.
--port=n
Use port n instead of default rsync port.
--progress
Display ongoing statistics about the progress of the transfer of each file.
-q, --quiet
Do not display statistics or server error messages.
--read-batch=prefix
Syncronize systems by reading the files whose names start with the prefix specified by a preceding --write-batch option.
-r, --recursive
Copy directories with all their contents.
-R, --relative
Preserve the entire path of a specified source file or directory, instead of creating the file directly under the destination directory. That is, if project/tmp/main.c is specified, create project/tmp/main.c instead of just main.c. Create intermediate directories if needed.
--rsh=shell
Synonym for -e.
--rsync-path=file
Use the rsync binary located in file on the destination system.
--safe-links
Don't copy links that point to absolute paths or to files outside the directories being transferred.
--size-only
Skip files that have the same size on the source and destination hosts, even if their timestamps differ; usually, this check is based on both size and timestamp.
-S, --sparse
Perform special optimizations on sparse files (files that contain holes and actually contain less data than their sizes indicate).
--stats
Like -v, but also prints a number of statistics about each file transferred, such as the number of bytes actually transferred and the number transferred to compare the files on the two hosts.
--suffix=string
Set the suffix placed on backup files to string. Default is a tilde (~).
--timeout=n
Stop rsync if n seconds pass with no data being transferred.
-t, --times
Set the timestamps of the destination file to match those of the source file, instead of using the time of transfer (that is, reflecting the existence of a new file on the destination host).
-Tdir, --temp-dir=dir
Use dir as rsync's temporary directory instead of the destination directory.
-u, --update
Don't change a destination file if it is newer than the source file.
--version
Display rsync's version and compiled-in features.
-v, --verbose
Display the names of files transferred and statistics related to the transfer.
-W, --whole-file
Transfer the entire files, instead of using rsync's block checks to transfer just parts of files where possible.
--write-batch=prefix
Prepare to syncronize systems by writing files, whose names start with prefix, that describe the transfers to take place.
-x
Synonym for --one-file-system.
-z
Synonym for --compress.
Examples
Transfer the entire directory proj to the /planning directory on remote host ourhub:
$ rsync -r proj/ ourhub:/planning
Transfer the files and subdirectories under proj to the /planning directory on remote host ourhub:
$ rsync -r proj ourhub:/planning
Return files from local directory active to the /tmp/active directory on remote host ourhub. Files to be transferred are listed in active/current_work.txt:
$ cat active/current_work.txt
workplan.doc
workplan.sxw
$ rsync -v --files-from=active/current_work.txt active \ourhub:/tmp/active
building file list ... done
workplan.doc
workplan.sxw
...
Copy the source directory's OpenOffice.org (.sxw) files and Kim's status report, but exclude the other status reports.
$ ls proj
conclusion.sxw Status_joem Status_leigh
incentives.sxw Status_kim unified.sxw
$ rsync -rv --include=*kim --exclude=/proj/Status* proj \
ourhub:tmp
building file list ... done
proj/Status_kim
proj/conclusion.sxw
proj/incentives.sxw
proj/unified.sxw
...