Learn Borg Backup - Your First Backup: borg create

#Introduction

The repository was born in episode 3. Now it is time for real action: making your first backup. This is an important moment because here you see deduplication working, learn to read the statistics, and build the habit of naming archives well. A bad archive naming choice will haunt you when you search for files in the future — so let us do it right from the start.

#Your First Backup

#The Basic Command

export BORG_REPO=/backup/borg
export BORG_PASSCOMMAND='cat /root/.borg-passphrase'
 
borg create --stats --list /backup/borg::"{hostname}-{now}" /home /etc

Let us break down the parts:

• /backup/borg::"{hostname}-{now}" — after :: is the archive name. {hostname} and {now} are Borg placeholders that are automatically replaced with the hostname and the local timestamp. The result looks like web-01-2026-08-13T10:30:00.
• /home /etc — the source directories being backed up.
• --list — prints every processed file (useful the first time, not always required).
• --stats — shows a summary: number of files, original size, size after dedup, and compression ratio.

#Archive Name Placeholders

Borg provides placeholders that can be combined:

• {hostname} / {fqdn} — the hostname.
• {now} — the local-time timestamp; {utcnow} for UTC.
• {user} — the user running the backup.

The "{hostname}-{now}" pattern is an industry standard: one glance tells you whose data and when. You can also add a suffix for the type of data, for example "{hostname}-{now}-db".

#Excluding Files

#--exclude and --exclude-caches

A full backup of /home will drag in caches, build artifacts, and temporary files — wasting space and slowing down the backup. Clean it up with exclusions:

borg create --stats \
  --exclude '*.pyc' \
  --exclude '*/node_modules/*' \
  --exclude '*/target/*' \
  --exclude-caches \
  /backup/borg::"{hostname}-{now}" /home /etc

• --exclude accepts glob patterns; use * at the start so it matches at any depth.
• --exclude-caches skips directories containing a CACHEDIR.TAG file — a standard used by many tools (including git and build systems) to mark cache directories.

#--exclude-if-present

For marker-based control, use --exclude-if-present <filename>: directories containing the marker file are skipped. This is a neat way to "opt in" on specific files, for example --exclude-if-present .no-backup.

#Dry-run First

Get into the habit of checking what will be copied before executing:

borg create --dry-run --list /backup/borg::"{hostname}-{now}-dry" /home /etc

--dry-run writes nothing — it only shows the files that would be included. Note that the dummy archive name is still created, so add the -dry marker so you are not confused later.

#Managing Archives

#borg list

borg list /backup/borg

The output looks like this:

web-01-2026-08-13T10:30:00   Thu, 2026-08-13 10:30:00  [abc123...]
web-01-2026-08-14T02:00:00   Fri, 2026-08-14 02:00:00  [def456...]

The last two columns are the archive ID (hash) and the creation time.

#borg info

borg info /backup/borg::"web-01-2026-08-13T10:30:00"

borg info shows the numbers you must read:

• Number of files — how many files are in the archive.
• Original size — the total source size before dedup.
• Deduplicated size — the size actually stored in the repo.
• Unique chunks / Total chunks — how many unique chunks vs total references.
• Compression ratio — how well compression is working.

The "Original size" vs "Deduplicated size" numbers are proof that dedup works: if the second backup barely grows the size, dedup is succeeding.

#Common Pitfalls

• Files changing during backup: files written at the same time as the backup process can change mid-flight. For database consistency, use the approach in episode 10.
• Ambiguous archive names: without {hostname}, two hosts sharing a repo will overwrite each other's names. Always include the host identity.
• The repo being backed up itself: do not put the repo inside a source directory — that is the warning from episode 0.
• Forgetting --stats: without stats you are blind to whether the backup was truly efficient and successful. Always include it on manual runs.

#Closing

• borg create --stats /backup/borg::"{hostname}-{now}" /home /etc is your first backup.
• A host-timestamp archive naming pattern keeps your history readable.
• Use --exclude, --exclude-caches, and --exclude-if-present to avoid junk.
• borg list shows all archives; borg info shows the dedup and compression numbers.
• Dedup is clearly visible: the second backup barely grows the repo size.

In episode 5 we learn the side many people forget: restore & extract — restoring data with borg extract, selecting files selectively with --path, browsing archives via borg mount (FUSE), and best practices for restoring to a clean directory with verification.