Linux command: rsync

Sooner or later, every Linux user needs to copy a lot of files from one place to another: a website to a server, a home folder to a backup drive, a project between two machines. You can do it with cp or scp, but the moment you run the same copy a second time you feel the waste, because they copy everything again, every time. rsync was built to fix exactly that. It looks at what is already at the destination and transfers only the parts that changed, which makes it the quiet backbone of backups, deployments, and server migrations all over the world.

2. Where the Name Comes From

The name rsync is a blend of remote and sync (short for synchronise). It was designed from the start to keep files in sync between a local and a remote machine, and the name says exactly that.

rsync  =  Remote SYNC

It replaced an older, dumber tool called rcp ("remote copy"), which copied whole files over the network with no cleverness at all. The extra letters in rsync are a small promise: this is not just a remote copy, it is a remote sync that pays attention to what is already there. The name has stuck for nearly thirty years because it still describes the tool perfectly.

4. Simple Use Cases

4.1 The Simplest Possible Sync

Give rsync a source, a destination, and the -a flag, and it copies the source into the destination. In the examples below, the line that starts with $ is what you type; the lines under it are what rsync prints back.

$ rsync -a project/ /backup/project/

Nothing is printed, which is the normal Unix way of saying "it worked". The -a flag (short for archive) is the flag you will use almost every time. It means "copy recursively and keep everything as it is": subfolders, permissions, timestamps, and symbolic links. For now, treat rsync -a as the everyday starting point; section 5 opens it up.

4.2 The Trailing Slash Rule

This is the one rule about rsync that everyone must learn, because it quietly changes where your files land. A trailing slash on the source means "the contents of this directory". No trailing slash means "this directory itself".

$ rsync -a src/ dst/     # copies the CONTENTS of src into dst
$ rsync -a src  dst/     # copies the DIRECTORY src, giving dst/src

You can prove it to yourself in a few seconds:

$ rsync -a src/ dst1/
$ ls dst1
a.txt  b.txt  sub

$ rsync -a src dst2/
$ ls dst2
src

The first command fills dst1 with the files that were inside src. The second one places src as a subfolder inside dst2. When a backup script mysteriously produces backup/project/project, a missing or extra slash is almost always the reason. The slash on the destination does not matter in the same way; it is the source slash that decides the layout.

Here is a trap I ran into myself, backing up my own home folder to an external disk, and it can quietly ruin a backup. It is tempting to reach for a wildcard instead of a trailing slash, which is exactly what I did:

$ rsync -av /home/peter/* /media/peter/writable/    # looks right, is not

The problem is that the * is expanded by the shell, before rsync ever runs, and a plain * does not match names that begin with a dot. So every hidden file and folder in the home directory (.bashrc, .ssh, .config, .gnupg) is silently left out. You can see it happen with echo:

$ echo /home/peter/*
/home/peter/Documents /home/peter/notes.txt     # notice: no .bashrc, no .ssh

What makes this dangerous is that it looks like it worked. The visible files and folders copy across fine, and hidden files inside those folders come along too, because rsync recurses into any directory the shell did hand it. Only the top-level dotfiles disappear, which are exactly the ones that hold your settings, keys, and credentials. In my case the external drive ended up with all my documents but none of my configuration, and I only noticed later. The fix is the trailing-slash form, which passes the directory itself to rsync and lets it walk the whole tree, hidden files and all:

$ rsync -av /home/peter/  /media/peter/writable/   # copies EVERYTHING, dotfiles included

Whenever you copy "a whole folder", prefer source/ over source/*. The trailing slash asks rsync to select the files; the wildcard asks the shell, and the shell hides your dotfiles.

4.3 Looking Before You Leap: -v and -n

Because rsync can delete and overwrite, it is worth seeing what it will do before it does it. Two flags make it talkative and cautious.

The -v flag (short for verbose) lists each file as it is transferred:

$ rsync -av src/ dst/
sending incremental file list
./
a.txt
b.txt
sub/
sub/c.txt

sent 308 bytes  received 88 bytes  792.00 bytes/sec
total size is 17  speedup is 0.04

The -n flag (short for dry-run) is the safety net. It shows exactly what would happen, but changes nothing. Combine it with -v and you get a preview:

$ rsync -avn src/ dst/
sending incremental file list
a.txt
b.txt
sub/c.txt

sent 163 bytes  received 32 bytes  390.00 bytes/sec
total size is 17  speedup is 0.09 (DRY RUN)

Notice the (DRY RUN) marker at the end. Get into the habit of running any new or risky rsync with -avn first, reading the list, and only then removing the n. This single habit prevents most rsync accidents.

4.4 Readable Sizes: -h

Raw byte counts in the summary are hard to read. The -h flag (short for human-readable) turns them into K, M, and G:

$ rsync -ah --stats bigfolder/ /backup/bigfolder/
...
Total file size: 1.42G bytes
Total transferred file size: 12.043M bytes

That second number is the point of rsync in one line: the folder is 1.42 GB, but only 12 MB actually changed, so only 12 MB was sent.

6. Advanced Use Cases

6.1 Leaving Things Out: --exclude

Real projects contain things you do not want to copy: caches, logs, dependency folders, temporary files. The --exclude option skips anything matching a pattern, and you can give it more than once.

$ rsync -a --exclude '*.log' --exclude 'cache/' src/ dst/

For a long list, keep the patterns in a file and read them with --exclude-from:

$ rsync -a --exclude-from='ignore.txt' src/ dst/

The patterns work a lot like .gitignore rules: a trailing slash means "a directory", a leading slash anchors the pattern to the top of the transfer, and * matches within one path level. There is a matching --include for the rarer case where you want to exclude almost everything but keep a few things back.

6.2 Extra Metadata: -A, -X, and -H

The archive flag -a keeps the everyday metadata, but three important things are left out on purpose because they cost extra work.

When you are backing up a whole system or migrating a server and want the copy to be truly faithful, the common recipe is rsync -aAXH. For an ordinary folder of documents, plain -a is enough.

6.3 Comparing by Content, Not Clock: -c

By default rsync decides a file is unchanged when its size and modification time both match. That is fast, but it can be fooled: a file edited and saved back to the same size within the same second, or a file whose timestamp was reset, can slip through. The -c flag (short for checksum) makes rsync read every file on both sides and compare a strong checksum instead.

$ rsync -avc src/ dst/     # compare by checksum, ignore size and time

This is slower, because it has to read all the data, but it is the honest way to answer "are these two folders really identical?" It is worth knowing about for verification runs, though not for everyday syncs.

6.4 Reading the Itemized Output: -i

The -i flag (short for itemize-changes) prints a compact code beside each file that tells you exactly why it was transferred. It looks cryptic at first, but it repays a minute of study.

$ rsync -ain src/ dst/
>f+++++++++ newfile.txt
>f..t...... changed.txt
.d..t...... sub/

Read the string left to right. The first character is the action: > means a file is being received (sent to the destination), and . means the item itself is not being updated, only an attribute. The second character is the type: f for a file, d for a directory. The rest are the reasons: c checksum, s size, t time, p permissions, o owner, g group. A row of +++++++++ means the file is brand new. So >f..t...... reads as "send this file because its time differs", and >f+++++++++ reads as "this file is new".

6.5 Being a Good Neighbour: --bwlimit and --stats

A full-speed rsync can saturate a network link and slow everything else down. The --bwlimit option caps the transfer rate, which is polite on a shared or production connection.

$ rsync -az --bwlimit=5m site/ This email address is being protected from spambots. You need JavaScript enabled to view it.:/var/www/site/  # cap at 5 MB/s

The --stats option prints a detailed report at the end, which is useful in scripts and logs to see how much really moved:

$ rsync -a --stats src/ dst/
Number of files: 5 (reg: 3, dir: 2)
Number of regular files transferred: 3
Total file size: 25 bytes
Total transferred file size: 25 bytes
...

6.6 Writing in Place and Sparse Files: --inplace and -S

By default rsync writes each updated file to a temporary copy and then renames it over the old one. That is safe, because an interrupted transfer never leaves a half-written file, but it needs room for both versions and it breaks any hard links pointing at the original. The --inplace option writes the changes straight into the existing file instead. It saves space, keeps hard links intact, and works well with the delta algorithm for large files that change only a little, such as database dumps, VM images, and append-only logs.

$ rsync -a --inplace bigdb.sql This email address is being protected from spambots. You need JavaScript enabled to view it.:/backups/

The trade-off is safety: if the transfer is interrupted, the destination file is left partly updated, so use --inplace only where that risk is acceptable.

The -S flag (short for sparse) handles files that contain long runs of zero bytes, such as disk images and some database files. It writes those runs as real "holes" in the filesystem rather than as blocks of zeros, so the copy can take far less space than the file's apparent size. (Older rsync versions, before 3.1.3, refused to combine -S with --inplace; current versions allow it.)

6.7 Beyond SSH: The rsync Daemon

SSH is the usual way to reach another machine, but rsync can also talk to a dedicated rsync daemon running on the far side. This is the mode the big public mirrors use to hand out Linux distributions to thousands of people at once. You recognise it by a double colon (or an rsync:// URL) and a module name instead of a filesystem path:

$ rsync -av rsync://mirror.example/debian/ /srv/mirror/debian/
$ rsync -av mirror.example::debian/ /srv/mirror/debian/   # same thing

A single colon (host:path) means "connect over SSH"; a double colon (host::module) means "connect to the rsync daemon". The daemon listens on port 873 and is configured in /etc/rsyncd.conf, where each module maps a name to a directory and its access rules. The daemon can be faster than SSH because it skips the encryption overhead, but that also means the traffic is unencrypted, so it suits public, read-only mirrors far more than private backups. For anything sensitive, stay with SSH.

8. Best Practices

• Preview with -avn first. For any new or risky command, especially with --delete, run it as a dry run, read the list, and only then remove the n.
• Master the trailing slash. src/ means "the contents", src means "the folder itself". This one rule decides where every file lands.
• Use -a as your default, and add -z for remote transfers, -P for large ones, and -AXH when you need a truly faithful system copy.
• Be careful with --delete. It makes the destination match the source exactly, including removing files. A wrong path can erase real data, so dry-run it every time.
• Keep timestamps. Always preserve modification times (part of -a), or rsync will resend everything on the next run and lose its whole advantage.
• Reach for the manual without hesitation. The rsync manual is long because the tool is deep. Typing man rsync the moment a question comes up is the habit that separates beginners from professionals.

$ man rsync            # the full manual page (long, and worth it)
$ rsync --help         # a quick flag summary

10. Summary

The rsync command looks like a fancier cp, but it is really a small synchronisation engine that happens to fit on one command line.

• rsync means "remote sync". It makes a destination match a source and transfers only what changed, which is why repeated syncs are fast.
• It dates from 1996 and carries a differencing algorithm and a network protocol inside a single tool.
• The last argument is the destination. A trailing slash on the source (src/) copies the contents; no slash (src) copies the folder itself. Prefer src/ over src/*, or the shell drops your hidden dotfiles.
• -a (archive) is the everyday flag: it means -rlptgoD, so it copies recursively and keeps links, permissions, times, and ownership.
• Add -z to compress remote transfers, -P to resume and show progress, and -e "ssh ..." to control the SSH connection.
• --delete turns a copy into a true mirror by removing files that no longer exist at the source. Preview it with -avn every time.
• --exclude skips unwanted files; -A, -X, and -H add ACLs, extended attributes, and hard links for a faithful system copy.
• The delta-transfer algorithm sends only the changed pieces of a file over the network, and --link-dest builds space-efficient snapshot backups with hard links.
• Beyond SSH, rsync can talk to a daemon (host::module, port 873) for public mirrors, and --inplace with -S updates large or sparse files efficiently.
• Know where rsync stops: cp and scp for one-off copies, tar for archives, git for history, dd for whole disks, and borg, rclone, or Syncthing for deduplicated, cloud, or two-way sync.
• When in doubt, type man rsync.

This is the quick reference worth keeping:

rsync -a src/ dst/              sync contents of src into dst
rsync -a src  dst/             copy the folder src into dst (dst/src)
rsync -avn src/ dst/           dry run: show what would change
rsync -aP big.iso host:/data/  resume-friendly copy with progress
rsync -a --info=progress2 s/ d/  one overall progress bar for the whole job
rsync -az src/ user@host:/dst/ compressed copy over SSH
rsync -a --delete src/ dst/    mirror: also remove extra files in dst
rsync -a --exclude '*.log' s/ d/   skip files matching a pattern
rsync -aAXH src/ dst/          faithful copy with ACLs, xattrs, hard links
rsync -a --link-dest=/prev src/ /new/   space-saving snapshot backup

Small commands like rsync quietly hold up serious infrastructure: the backups that run every night, the deployments that push a website live, the migration that moves a business to a new server. If your servers matter and you want them backed up, deployed, and maintained by someone who understands what is really happening underneath, that is exactly the kind of work I enjoy helping with.