Main Content Region

Synchronising files with rsync

The rsync utility is a very useful utility for synchronising files and directories between two different servers.

It is similar in idea to ftp (or sftp), but has the advantage that it will compare the two directory trees on both servers, and only new or updated files are transferred across.

Note that data is normally transferred encrypted using ssh by default, unless rsync was compiled with different options.

Basic rsync syntax

Copying from the local machine to a remote machine:

rsync <options> local_directory remote_server_name:remote_directory

Copying from a remote machine to the local machine:

rsync <options> remote_server_name:remote_directory local_directory 

There are a number of rsync options (see the man page for full details), but the following are a good set to begin with:

rsync -arvxHP local_directory remote_server_name:remote_directory

The main rsync options

-a archive mode
-r recursive over subdirectories
-v verbose
-x don't cross filesystem boundaries
-H preserve hard links
-P show progress
-n no-op, or dry-run

If required, you can specify a different username on the remote server:

rsync -arvxHP local_directory username@remote_server_name:remote_directory

Testing the transfer first

It is a good idea to test what rsync will do, without actually transferring anything - to ensure that it will put the files in the correct place, and that it will copy what you expect.

This is done by adding the -n flag to specify a no-op or a dry-run.

rsync -n -arvxHP local_directory remote_server_name:remote_directory

Using rsync when the folder exists on both servers

You have to be careful when supplying the directory paths, in particular whether or not you include the trailing slash or not. We find that the following syntax works well, by specifying a trailing slash and a trailing dot:

rsync -arvxHP mycode-1.0.0/.

Warning: omitting the trailing "/." won't work correctly

The following will create a subdirectory of mycode-1.0.0, also called mycode-1.0.0

I.e. you will end up with mycode-1.0.0/mycode-1.0.0, which is not what you want!

# warning - this doesn't work because we don't have the trailing "/."
rsync -arvxHP mycode-1.0.0

Using rsync when the folder doesn't exist on the remote server

rsync can also be used to copy a directory tree, even if the destination directory doesn't exist yet. In this case, we omit the trailing slash and dot:

rsync -arvxHP mycode-1.0.0/.

rsync relative to home directory

Much of the time, we want to rsync to a destination folder which is sitting in your home directory. In that case, we can omit the absolute path, and just use a path relative to your home directory:

rsync -arvxHP mycode-1.0.0/.

Deleting files on the destination folder

If your local and remote copies of a folder have gotten out of sync, for example if you have tidied up and deleted files in the local copy, and then would like to synchronise those deletions in the remote copy as well, then you can add the --delete option. Again, it's good to first test with -n as a dry-run, to give you an idea of what would happen:

rsync -n --delete -arvxHP mycode-1.0.0/.

If that matches what you expect should happen, then remove the -n:

rsync --delete -arvxHP mycode-1.0.0/.