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:
- breaklock:
- check:
- compact:
- compare:
- configs:
- create:
- delete:
- diff:
- due:
- extract:
- help:
- info:
- init:
- list:
- log:
- manifest:
- mount:
- prune:
- restore:
- settings:
- umount:
- 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