Learn Rsync - Basic Syntax & Local Mode

#Introduction

After understanding the architecture in episode 2, it's time for your first real action: running rsync in local mode. Episode 3 builds correct syntax habits — because the most common beginner mistake isn't about flags, it's about the trailing slash. We'll cover the difference thoroughly in this episode.

Remember your lab from episode 0: ~/rsync-lab/src and ~/rsync-lab/dest. We'll use them as our practice ground.

#General Syntax

Rsync's syntax is consistent and concise:

General syntax

rsync [OPTIONS] SRC DEST

OPTIONS are flags (we'll dissect the important ones in episode 5), SRC is the source, and DEST is the destination. The direction is always one-way: from left to right. Rsync never syncs bidirectionally — a limitation we'll discuss in episode 11.

#First Practice: Local Copying

Prepare a few source files, then run our first command:

First local rsync practice

cd ~/rsync-lab
mkdir -p src/sub
echo "a" > src/a.txt
echo "b" > src/sub/b.txt
rsync -avh src/ dest/

The output looks roughly like this:

Output of rsync -avh

sending incremental file list
./
a.txt
sub/
sub/b.txt
 
sent 202 bytes  received 44 bytes  492.00 bytes/sec
total size is 6  speedup is 0.03

-avh is the most common combination: -a (archive — recursive plus preserving permissions, timestamps, symlinks, etc.), -v (verbose), -h (human-readable sizes). Details of each flag are in episode 5.

#The Important Slash: `src/` vs `src`

This is the most crucial part and the most common source of confusion. Pay close attention:

Command	Result
`rsync -avh src/ dest/`	Copies the contents of `src` → produces `dest/a.txt`, `dest/sub/b.txt`
`rsync -avh src dest/`	Copies the directory `src` itself → produces `dest/src/a.txt`, `dest/src/sub/b.txt`

The trailing slash on the source determines whether the directory is carried along as a wrapper (src) or only its contents are taken (src/). Let's prove it:

Compare with and without slash

rsync -avh src dest-with-dir/
rsync -avh src/ dest-no-dir/
ls dest-with-dir dest-no-dir

ls will show dest-with-dir/src/ and dest-no-dir/a.txt — real proof that one character changes the resulting structure.

Tip

Rule of thumb: use src/ when you want its contents to go directly into DEST (the most common pattern for backups), and src when you want the DEST/src/ structure — for example when backing up several directories into one place while keeping each neatly separate.

#Trailing Slash on the Destination

The slash on the destination isn't as strict as on the source, but there's still nuance: dest/ and dest generally both mean "this location". What to remember: rsync will create the destination directory if it doesn't exist for a given case — it will create it, but make sure the target name isn't confusing. Example: rsync -avh src/ dest/ with dest not yet existing will create dest/ containing the contents of src.

#Copying Two Sources at Once

Rsync supports multiple sources to one destination — a combination that's prone to misunderstanding with trailing slashes:

Multiple sources, one destination

rsync -avh src/sub/ src/other/ dest/

When there are two sources, each must end with a slash so their contents merge at the destination; without the slash, rsync will wrap them in a directory — or error out due to ambiguous behavior.

#Copying "Exactly" with --delete

Sometimes you want the destination to be an exact mirror of the source — including deleting extra files at the destination. That's what --delete does, but be careful:

Mirroring with --delete

rsync -avh --delete src/ dest/

--delete deletes at the destination every file that doesn't exist at the source. It's powerful and dangerous at the same time — combine it with a misdirected source and you lose data. Always test with a dry-run -n first. We'll fully dissect --delete in episode 5.

Warning

Never combine --delete with a misdirected source (e.g. swapping SRC and DEST). One wrong direction + --delete = your backup is deleted. Safe habit: run -n (dry-run) first, or only put --delete in scripts that have been tested.

#Understanding Verbose Output

When you look at rsync -avh output, those lines are the list of files being considered for synchronization. Run the same command twice and note the difference:

Nothing is transferred the second time

rsync -avh src/ dest/

The second time, rsync detects no changes and prints no new files (just a . line or a short message). That's rsync's core efficiency: re-running a backup is as fast as running it once — only the changes are processed.

#Closing

In this episode you've mastered the basic syntax and your first local-mode practice.

Key takeaways:

Syntax: rsync [OPTIONS] SRC DEST, one-way direction from left to right.
-avh is the standard flag combination for daily backups.
The source trailing slash determines the result: src/ = contents, src = the directory along with its contents.
--delete makes the destination an exact mirror, but it's dangerous if the direction is wrong.
A second transfer is nearly free because rsync only processes changes.

In episode 4 we cross over to remote mode: rsync over SSH (-e ssh, custom port), push vs pull, then daemon mode with rsync://host/module/, [module] configuration in /etc/rsyncd.conf, and secrets file authentication. See you in episode 4!