Command line: BorgBackup

Synopsis
Options
- Repositories and archives
Environment variables
Examples

BorgBackup is a deduplicating archiver with compression and encryption. In other words, this is the best backup tool (as of 2021-05-30).

In this note, we'll be covering the following v1.1.16 and above.

For more information, you can view borg.1 manual page. It has all of the information you can possibly know about the tool, making it a perfect reference. This note rips off a few relevant pages from there.

Synopsis

borg [options...] [subcommand [subcommand_options...] [subcommand_positional_args...]]

Borg recommends to pass the options before the positional arguments. It can be picky with certain subcommands output being affected from the order of the arguments but you should be safe when you do the recommended practice.

Options

Borg uses a Git-style command-line interface with subcommands and some common options to choose from.

You can set the log level of the program with --debug, --info, --warning, --error, and --critical.
-v, --verbose is an alias for --info
-p, --progress shows progress information; will be slower on certain operations due to additional passing of the metadata

Keep in mind, Borg doesn't have global configuration files, only per-repo configurations. You can create configurations with a little hard work and shell scripts. But if you want a tool that already does that, you have Borgmatic as an option with plain-text files in YAML format.

Repositories and archives

Most of the subcommands take the repository path with a certain format.

${REPOSITORY_URL}::${ARCHIVE_NAME}

# Points to an repo
/home/foo-dogsquared/backup

# Points to an archive named '2021-03-02' from the previous repo.
/home/foo-dogsquared/backup::2021-03-02

You can also refer to a name dynamically with placeholders.

/home/{user}/backup::{hostname}-{user}-{now}

For more information, you can see the related section for Borg placeholders. Or you can run borg help placeholders.

Environment variables

Borg will also take environment variables being used by most (if not all) of the subcommands. Very useful for scripting and saving time not repeating the same arguments.

BORG_REPO - the repo URL
BORG_PASSPHRASE - the repo passphrase, if it has encryption enabled
BORG_PASSCOMMAND - the command used to get the passphrase

Examples

Borg is a comprehensive tool for a comprehensive backup system. Here are some of the real-life examples of using the program.

Quickstart

Just from how I imagined I would start using this tool, anyway.

# Initialize the Borg repo in the specified path with a simple passphrase.
borg init --encryption repokey ${REPO_PATH}

# Create an archive in the repo and save the documents, pictures, and videos folder.
# This will prompt you into entering the passphrase.
borg create --verbose --progress ${REPO_PATH}::{hostname}-{now:%F-%T-%z} ~/Documents ~/Pictures ~/Videos

# Entering the passphrase can be annoying so let's save that into a variable.
# Luckily, Borg already handles this by setting BORG_PASSPHRASE.
# Thus, it will not bother us again.
BORG_PASSPHRASE='gum cavity cabinet auditorium'

# List all of the archives saved so far.
borg list ${REPO_PATH}

# List the files in the specified archive.
borg list ${REPO_PATH}::${ARCHIVE_NAME}

# Extract only the documents folder.
borg extract --verbose --progress ${REPO_PATH}::{hostname}-{now:%F-%T-%z} ~/Documents

Practicing safe backup script

Better be safe than sorry. Here's the safe backup in all of its glory in Bash.

if $# -eq 1; then echo "No directories and files to be saved." && exit 1; fi

locations=$@

borg create --verbose --stats --compression lz4 --exclude '**/.node_modules' ::{hostname}-{now:%F-%H-%M-%S-%z} ${locations[@]}
borg check --verbose --verify-data
borg prune --verbose --keep-daily 7 --keep-hourly 7 --keep-weekly 6 --keep-monthly 6

Since the script only lets you enter arguments used for saving into the archive, you have to use environment variables.

BORG_REPO="$HOME/backups" BORG_PASSCOMMAND='gopass show misc/personal-borgbackup-repo' safe-borg-backup ~/projects ~/library ~/writings

An interactive interface for extracting archives

All-time favorite fzf (see Command line: fzf) is required.

export BORG_PASSPHRASE="oral hygiene"
export BORG_REPO="${REPO_PATH}"

borg list --format="{name}{NL}" \
    | fzf \
    | xargs --replace="{}" borg extract --verbose --progress ::{}

5.0 KiB Raw Permalink Blame History