Commands

You invoke Emborg from your shell by entering a line of the form:

$ emborg [global-options] <command> [command-options]

Details about the options and commands can be accessed with:

$ emborg help

or:

$ emborg help <command>

The available commands are:

borg:

run a raw borg command

breaklock:

breaks the repository and cache locks

check:

checks the repository and its archives

compact:

compact segment files in the repository

compare:

compare local files with those in an archive

configs:

list available backup configurations

create:

create an archive of the current files

delete:

delete an archive currently contained in the repository

diff:

show the differences between two archives

due:

days since last backup

extract:

recover file or files from archive

help:

give information about commands or other topics

info:

print information about a backup

init:

initialize the repository

list:

list the archives currently contained in the repository

log:

print logfile for the last emborg run

manifest:

list the files contained in an archive

mount:

mount a repository or archive

prune:

prune the repository of excess archives

restore:

recover file or files from archive in place

settings:

list settings of chosen configuration

umount:

un-mount a previously mounted repository or archive

version:

display emborg version

These commands are described in more detail below. Not everything is described here. Run emborg help <cmd> for the details.

Exit Status

Emborg returns with an exit status of 0 if it completes without issue. It returns with an exit status of 1 if was able to terminate normally but some exceptional condition was encountered along the way. For example, if the compare or diff detects a difference or if due command detects the backups are overdue, a 1 is returned. In addition, 1 is returned if Borg detects an error but is able to complete anyway. However, if Emborg or Borg suffers errors and cannot complete, 2 is returned.

Borg

Runs raw Borg commands. Before running the passphrase or passcommand is set. Also, if @repo is found on the command line, it is replaced by the path to the repository.

$ emborg borg key export @repo key.borg
$ emborg borg list @repo::root-2020-04-11T23:38:37

Emborg runs the Borg command from working_dir if it is specified and / if not.

BreakLock

This command breaks the repository and cache locks. Use carefully and only if no Borg process (on any machine) is trying to access the Cache or the Repository.

$ emborg break-lock
$ emborg breaklock

Check

Check the integrity of the repository and its archives. The most recently created archive is checked if one is not specified unless --all is given, in which case all archives are checked.

The --repair option attempts to repair any damage found. Be aware that the –repair option is considered a dangerous operation that might result in the complete loss of corrupt archives. It is recommended that you create a backup copy of your repository and check your hardware for the source of the corruption before using this option.

Compact

This command frees repository space by compacting segments.

Use this regularly to avoid running out of space, however you do not need to it after each Borg command. It is especially useful after deleting archives, because only compaction really frees repository space.

Requires Borg version 1.2 or newer. Prior to version 1.2 the compact functionality was part of the Borg prune command. As of version 1.2 this functionality was split into its own command.

If you set compact_after_delete Emborg automatically runs this command after every use of the delete and prune commands.

Compare

Reports and allows you to manage the differences between your local files and those in an archive. The base command simply reports the differences:

$ emborg compare

The --interactive option allows you to manage those differences. Specifically, it will open an interactive file comparison tool that allows you to compare the contents of your files and copy differences from the files in the archive to your local files:

$ emborg compare -i

You can specify the archive by name or by date or age. If you do not you will use the most recent archive:

$ emborg compare -a continuum-2020-12-04T17:41:28
$ emborg compare -d 2020-12-04
$ emborg compare -d 1w

You can specify a path to a file or directory to compare, if you do not you will compare the files and directories of the current working directory.

$ emborg compare tests
$ emborg compare ~/bin

This command uses external tools to view and manage the differences. Before it can be used it must be configured to use these tools, which is done with the manage_diffs_cmd and report_diffs_cmd settings. In addition, the default_mount_point must be configured. The manage_diffs_cmd is used if the --interactive (or -i) option is given, and report_diffs_cmd otherwise. However, if only one is given it is used in both cases. So, if you find that you only want to use the interactive tool to view and manage your differences, you can simply not specify report_diffs_cmd, which would eliminate the need to specify the -i option.

The command operates by mounting the desired archive, performing the comparison, and then unmounting the directory. Problems sometimes occur that can result in the archive remaining mounted. In this case you will need to resolve any issues that are preventing the unmounting, and then explicitly run the umount command before you can use this Borg repository again.

This command differs from the diff command in that it compares local files to those in an archive where as diff compares the files contained in two archives.

Configs

List the available backup configurations. Each configuration corresponds to a settings file in your configuration directory (~/.config/emborg). Settings common to all your configurations should be placed in ~/.config/emborg/settings. You can see available configurations using:

$ emborg configs

To run a command on a specific configuration, add –config=<cfg> or -c cfg before the command. For example:

$ emborg -c home create

Create

This creates an archive in an existing repository. An archive is a snapshot of your files as they currently exist. Borg is a de-duplicating backup program, so only the changes from the already existing archives are saved.

$ emborg create

Before creating your first archive, you must use the init command to initialize your repository.

This is the default command, so you can create an archive with simply:

$ emborg

If the backup seems to be taking a long time for no obvious reason, run the backup in verbose mode:

$ emborg -v create

This can help you understand what is happening.

Emborg runs the create command from working_dir if it is specified and current directory if not.

Delete

Delete one or more archives currently contained in the repository:

$ emborg delete continuum-2020-12-05T19:23:09

If no archive is specified, the latest is deleted.

The disk space associated with deleted archives is not reclaimed until the compact command is run. You can specify that a compaction is performed as part of the deletion by setting compact_after_delete. If set, the --fast flag causes the compaction to be skipped. If not set, the --fast flag has no effect.

Specifying --repo results in the entire repository being deleted. Unlike with borg itself, no warning is issued and no additional conformation is required.

Diff

Shows the differences between two archives:

$ emborg diff continuum-2020-12-05T19:23:09 continuum-2020-12-04T17:41:28

You can constrain the output listing to only those files in a particular directory by adding that path to the end of the command:

$ emborg diff continuum-2020-12-05T19:23:09 continuum-2020-12-04T17:41:28 .

This command differs from the compare command in that it only reports a list of files that differ between two archives, whereas compare shows how local files differ from those in an archive and can show you the contents of those files and allow you interactively copy changes from the archive to your local files.

Due

When run with no options it indicates when the last backup and squeeze operations were performed. A backup operation is the running of the create command. A squeeze operation is the running of both the prune and compact commands. The time to the latest squeeze operation is the time to the older of the most recent prune or compact commands. For example:

$ emborg due
home: 11 hours since last backup.  2 weeks since last squeeze.

Adding the –backup-days option or –squeeze-days results in the message only being printed if the backup or squeeze has not been performed within the specified number of days. If both are specified and both limits are violated, only the backup violation is reported as it is considered the most urgent.

Adding the –email option results in the message being sent to the specified address rather than printed. This allows you to run the due command from a cron script in order to send your self reminders to do a backup if one has not occurred for a while. It is often run with the –no-log option to avoid replacing the log file with one that is inherently uninteresting:

$ emborg --no-log due --backup-days 1 --backup-days 7 --email me@mydomain.com

You can specify a specific message to be printed with –message. In this case, the following replacements are available:

{action}:

Replaced with the type of operation reported on. It is either backup or squeeze.

{config}:

Replaced with the name of the configuration being reported on.

{cmd}:

Replaced with the name of the command being reported on. It can be create, prune or compact. It will be create if reporting on a backup operation, and either prune or compact if reporting on a squeeze operation, depending on which is older.

{days}:

Replaced by the number of days since the last backup or squeeze. You can add floating-point format codes to specify the resolution used. For example: {days:.1f}.

{elapsed}:

Replaced with a humanized description of how long it has been since the last backup.

So --message '{elapsed} since last {action} of {config}.' might produce something like this:

12 hours since last backup of home.

With composite configurations the message is printed for each component config unless –oldest is specified, in which case only the oldest is displayed.

Extract

You extract a file or directory from an archive using:

$ emborg extract home/shaunte/bin

Use manifest to determine what path you should specify to identify the desired file or directory. You can specify more than one path. Usually, they will be paths that are relative to /, thus the paths should look like absolute paths with the leading slash removed. The paths may point to directories, in which case the entire directory is extracted. It may also be a glob pattern.

By default, the most recent archive is used, however, if desired you can explicitly specify a particular archive. For example:

$ emborg extract --archive continuum-2020-12-05T12:54:26 home/shaunte/bin

Alternatively you can specify a date or date and time. If only the date is given the time is taken to be midnight. The oldest archive that is younger than specified date and time is used. For example:

$ emborg extract --date 2021-04-01 home/shaunte/bin
$ emborg extract --date 2021-04-01T15:30 home/shaunte/bin

Alternatively, you can specify the date in relative terms:

$ emborg extract --date 3d  home/shaunte/bin

In this case 3d means 3 days. You can use s, m, h, d, w, M, and y to represent seconds, minutes, hours, days, weeks, months, and years.

Finally, if you specify a simple number, it is taken to be the index of the desired archive, where 0 represents the most recent, 1 the next most recent, etc.

$ emborg extract --date 3  home/shaunte/bin

The extracted files are placed in the current working directory with the original hierarchy. Thus, the above commands create the directory:

./home/shaunte/bin

See the restore command as an alternative to extract that replaces the existing files rather than simply copying them into the current directory.

Help

Show information about Emborg:

$ emborg help

You can ask for help on a specific command or topic with:

$ emborg help <topic>

For example:

$ emborg help extract

Info

This command prints out the locations of important files and directories.

$ emborg info

You can also get information about a particular archive.

$ emborg info home-2022-11-03T23:07:25

Init

Initializes a Borg repository. This must be done before you create your first archive.

$ emborg init

List

List available archives.

$ emborg list

Log

Show the log from the previous run.

$ emborg log

Most commands save a log file, but some do not. Specifically, configs, due, help, log, settings and version do not. Additionally, no command will save a log file if the --no-log command line option is specified. If you need to debug a command that does not normally generate a log file and would like the extra detail that is normally included in the log, specify the --narrate command line option.

If you wish to access the log files directly, they reside in ~/.local/share/emborg.

Manifest

Once a backup has been performed, you can list the files available in your archive using:

$ emborg manifest

You specify a path. If so, the files listed are those contained within that path. For example:

$ emborg manifest .
$ emborg manifest -R .

The first command lists the files in the archive that were originally contained in the current working directory. The second lists the files that were in specified directory and any sub directories.

If you do not specify an archive, as above, the latest archive is used.

You can explicitly specify an archive:

$ emborg manifest --archive continuum-2021-04-01T12:19:58

Or you choose an archive based on a date and time. The oldest archive that is younger than specified date and time is used.

$ emborg manifest --date 2021-04-01
$ emborg manifest --date 2021-04-01T12:45

You can also specify the date in relative terms:

$ emborg manifest --date 1w

where s, m, h, d, w, M, and y represents seconds, minutes, hours, days, weeks, months, and years.

Finally, if you specify a simple number, it is taken to be the index of the desired archive, where 0 represents the most recent, 1 the next most recent, etc.

$ emborg manifest --date 7

The manifest command provides a variety of sorting and formatting options. The formatting options are under the control of the manifest_formats setting. For example:

$ emborg manifest

This outputs the files in the order and with the format produced by Borg. If a line is green if the corresponding file is healthy, and if red it is broken (see Borg list command for more information on broken files).

$ emborg manifest -l
$ emborg manifest -n

These use the Borg order but change the amount of information shown. With -l the long format is used, which by default contains the size, the date, and the path. With -n the name is used, which by default contains only the path.

Finally:

$ emborg manifest -S
$ emborg manifest -D

The first sorts the files by size. It uses the size format, which by default contains only the size and the path. The second sorts the files by modification date. It uses the date format, which by default contains the day, date, time and the path. More choices are available; run emborg help manifest for the details.

You can use files as an alias for manifest:

$ emborg files

Mount

Once a backup has been performed, you can mount it and then look around as you would a normal read-only filesystem.

$ emborg mount backups

In this example, backups acts as a mount point. If it exists, it must be a directory. If it does not exist, it is created.

If you do not specify a mount point, the value of default_mount_point setting is used if set.

If you do not specify an archive, as above, the most recently created archive is mounted.

You can explicitly specify an archive:

$ emborg mount --archive continuum-2015-04-01T12:19:58 backups

You can mount the files that existed on a particular date using:

$ emborg mount --date 2021-04-01 backups
$ emborg mount --date 2021-04-01T18:30 backups

If the time is not given, it is taken to be midnight.

You can also specify the date in relative terms:

$ emborg mount --date 1w backups

where s, m, h, d, w, M, and y represents seconds, minutes, hours, days, weeks, months, and years.

Finally, if you specify a simple number, it is taken to be the index of the desired archive, where 0 represents the most recent, 1 the next most recent, etc.

$ emborg mount --date 7 backups

When a date is given, the oldest archive that is younger than the specified date or time is used.

Finally, you can mount all the available archives:

$ emborg mount --all backups

You will need to un-mount the repository or archive when you are done with it. To do so, use the umount command.

Prune

Prune the repository of excess archives. You can use the keep_within, keep_last, keep_minutely, keep_hourly, keep_daily, keep_weekly, keep_monthly, and keep_yearly settings to control which archives should be kept. At least one of these settings must be specified to use prune:

$ emborg prune

The prune command deletes archives that are no longer needed as determined by the prune rules. However, the disk space is not reclaimed until the compact command is run. You can specify that a compaction is performed as part of the prune by setting compact_after_delete. If set, the --fast flag causes the compaction to be skipped. If not set, the --fast flag has no effect.

Restore

This command is very similar to the extract command except that it is meant to be run in place. Thus, the paths given are converted to absolute paths and then the borg extract command is run from the root directory (/) so that the existing files are replaced by the extracted files.

For example, the following commands restore your .bashrc file:

$ cd ~
$ emborg restore .bashrc

Emborg runs the restore command from working_dir if it is specified and the current directory if not.

By default, the most recent archive is used, however, if desired you can explicitly specify a particular archive. For example:

$ emborg restore –archive continuum-2020-12-05T12:54:26 resume.doc

Or you choose an archive based on a date and time. The oldest archive that is younger than specified date and time is used.

$ emborg restore –date 2021-04-01 resume.doc $ emborg restore –date 2021-04-01T18:30 resume.doc

Or you can specify the date in relative terms:

$ emborg restore –date 3d resume.doc

In this case 3d means 3 days. You can use s, m, h, d, w, M, and y to represent seconds, minutes, hours, days, weeks, months, and years.

Finally, if you specify a simple number, it is taken to be the index of the desired archive, where 0 represents the most recent, 1 the next most recent, etc.

$ emborg restore --date 7 resume.doc

This command is very similar to the extract command except that it is meant to replace files in place. It also takes similar options.

Settings

This command displays all the settings that affect a backup configuration.

$ emborg settings

Add --all option to list out all available settings and their descriptions rather than the settings actually specified and their values.

Umount

Un-mount a previously mounted repository or archive:

$ emborg umount backups
$ rmdir backups

where backups is the existing mount point.

If you do not specify a mount point, the value of default_mount_point setting is used if set.

Version

Prints the Emborg version.

$ emborg version