The values of the following variables are set at startup and should not be changed by the user.
The value of this constant is the directory beneath which drone
submodules are placed. The value is set based on the location of
borg library and should not be changed.
The value of this constant is the directory beneath which additional
per-user Emacs-specific files are placed. The value is set based on
the location of the
borg library and should not be changed. The
value is usually the same as that of
when Emacs is started with
emacs -q -l /path/to/init.el.
The value of this constant is the ".gitmodules" file of the super-repository.
The values of the borg-specific Git variables have to be set in the
~/.emacs.d/.gitmodules. The variables
submodule.DRONE.remote are described in Patching drones.
This variable specifies the name used for remotes that reference a repository that has been patched by the collective. If a NAME matches REMOTE, then it is configured as the upstream of the current branch of the respective DRONE.
If the file ".hive-maint" exists, then this variable has the same effect as "borg.pushDefault". This special case is only useful for maintainers of the collective (but not for maintainers of individual drones).
Because most repositories used to maintain Emacs packages follow some
common-sense conventions, Borg usually does not have to be told how to
build a given drone. Building is done using
borg-build, which in turn
usually does its work using
However some packages don’t follow the conventions either because they are too complex to do so, or for the sake of doing it differently. But in either case resistance is futile; by using the following variables you can tell Borg how to build such packages.
By default drones are built using the lisp functions
if this variable has one or more values, then DRONE is built using
these COMMANDs instead.
Each COMMAND can be one of the default steps, an S-expression, or a shell command. The COMMANDs are executed in the specified order.
If a COMMAND matches one of default steps, then it is evaluated with
the appropriate arguments. Otherwise if the COMMAND begins with a
parenthesis, then it is evaluated as an Elisp expression. Otherwise
it is assumed to be a shell command and executed with
[submodule "mu4e"] path = lib/mu4e url = firstname.lastname@example.org:djcb/mu.git build-step = test -e ./configure || autoreconf -i build-step = ./configure build-step = make -C mu4e > /dev/null build-step = borg-update-autoloads load-path = mu4e
To skip generating "autoloads" (e.g. using
use-package to create
"autoloads" on the fly), just provide the required build steps to
build the package, omitting
borg-update-autoloads. Borg silently
ignores a missing "autoloads" file during initialization
[submodule "multiple-cursors"] path = lib/multiple-cursors url = email@example.com:magnars/multiple-cursors.el.git build-step = borg-byte-compile
Note that just because a package provides a
Makefile, you do not
necessarily have to use it.
make generates the Info file, you might still have to add
borg-makeinfo as an additional build-step because the former might
not generate an Info index file (named
dir), which Borg relies on.
This variable can be used to change how shell commands specified
submodule.DRONE.build-step are run. The default value is
meaning that each build step is run unchanged using
If the value is a string, then that is combined with each build step
in turn and the results are run using
shell-command. This string
must contain either %s, which is replaced with the unchanged build
step, or %S, which is replaced with the result of quoting the build
If the value is a function, then that is called once with the drone as argument and must return either a string or a function. If the returned value is a string, then that is used as described above.
If the value returned by the first function is another function, then
this second function is called for each build step with the drone and
the build step as arguments. It must return a string or
nil. If the
returned value is a string, then that is used as described above.
Finally the second function may execute the build step at its own
discretion and return
nil to indicate that it has done so.
Notice that if the value of this variable is a function, this
function must a) be defined in a drone; and b) be registered as an
autoload. This is because build happens in a separate Emacs process
-Q --batch, which only receives the name of the function.
This variable instructs
borg-activate to add PATH to the
instead of the directory it would otherwise have added. Likewise it
borg-byte-compile to compile the libraries in that
directory. PATH has to be relative to the top-level of the
repository of the drone named DRONE. This variable can be specified
Normally Borg uses
lisp/ as the drone’s
load-path, if that exists,
or else the top-level directory. If this variable is set, then it
overrides the default location. Therefore, to add an additional
directory, you also have to explicitly specify the default
[submodule "org"] path = lib/org url = git://orgmode.org/org-mode.git build-step = make load-path = lisp load-path = contrib/lisp info-path = doc
This variable instructs
borg-byte-compile to not compile the library
at PATH. PATH has to be relative to the top-level of the repository
of the drone named DRONE. This variable can be specified multiple
Sometimes a drone comes with an optional library which adds support
for some other third-party package, which you don’t want to use.
emacsql comes with a PostgreSQL back-end, which is
implemented in the library
emacsql-pg.el, which requires the
package. The standard Borg collective
for the sake of the
epkg drone, which only requires the SQLite
back-end. To avoid an error about
pg not being available,
instructs Borg to not compile
emacsql-pg.el. (Of course if you want
to use the PostgreSQL back-end and assimilate
pg, then you should
Setting this variable to
borg-byte-compile to compile
DRONE’s directories recursively. This isn’t done by default because
there are more repositories in which doing so would cause issues
than there are repositories that would benefit from doing so.
Unfortunately many packages put problematic test files or (usually
outdated) copies of third-party libraries into subdirectories. The
latter is a highly questionable thing to do, but the former would be
perfectly fine, if only the non-library elisp files did not provide
a feature (which effectively turns them into libraries) and/or if a
.nosearch existed in the subdirectory. That file tells
functions such as
borg-byte-compile to ignore the containing directory.
Setting this variable to a non-nil value instructs
to compile all drones recursively. Doing so is discouraged.
This variable instructs
borg-initialize to add PATH to
Info-directory-list. PATH has to be relative to the top-level of
the repository of the drone named DRONE.
This variable instructs
borg-makeinfo to not create an Info file for
the Texinfo file at PATH. PATH has to be relative to the top-level
of the repository of the drone named DRONE. This variable can be
specified multiple times.
If the value of this variable is
true, then it is skipped by
An alist that can optionally be used to rewrite certain URLs. Each
element has the form
(ORIG . BASE). Each URL that starts with ORIG
is rewritten to start with BASE instead. See Using https URLs.