A third-party package is assimilated by adding it as a submodule and,
if necessary, by configuring it in
packages are assimilated merely by configuring them.
To begin the assimilation of a third-party package use the command
borg-assimilate, which adds the package’s repository as a submodule
and attempts to build the drone.
A safer alternative is to first clone the package without assimilating
borg-clone. This gives you an opportunity to inspect the
cloned package for broken or malicious code before it gets a chance to
run arbitrary code. Later you can proceed with the assimilation using
borg-assimilate, or remove the clone using
Building the drone can fail, for example due to missing dependencies.
Failure to build a drone is not considered as a failure to assimilate.
If a build fails, then a buffer containing information about the
issue pops up. If the failure is due to unsatisfied dependencies,
then assimilate those too, and then build any drone which previously
couldn’t be built by using the Emacs command
lib/DRONE. Alternatively you can just rebuild everything using
If you wish to avoid such complications, you should use the command
epkg-describe-package before assimilating a package. Among other
useful information, it also provides a dependency tree.
Once the packages have been added as submodules and the drones have been built, the assimilation is completed by creating an assimilation commit.
If you assimilate a single package, then it is recommended that you use a message similar to this:
Assimilate foo v1.0.0
Or if one or more dependencies had to be assimilated, something like:
Assimilate foo and dependencies Assimilate foo v1.0.0 Assimilate bar v1.1.0 Assimilate baz v0.1.0
It’s usually a good idea not to assimilate unrelated packages in the same commit, but something like this might make sense:
Assimilate ido and extensions Assimilate flx v0.6.1-3-gae0981b Assimilate ido-at-point v1.0.0 Assimilate ido-ubiquitious v3.12-2-g7354d98 Assimilate ido-vertical-mode v0.1.6-33-gb42e422 Assimilate smex 3.0-13-g55aaebe
Version strings as those shown above can be obtained using
describe --tags, or by looking inside the "Modules" section of the
Magit status buffer of the
This command assimilates the package named PACKAGE from URL.
epkg is available, then only the name of the package is read in
the minibuffer and the url stored in the Epkg database is used. If
epkg is unavailable, the package is not in the database, or if a
prefix argument is used, then the url too is read in the minibuffer.
If a negative prefix argument is used, then the submodule is added
but the build and activation steps are skipped. This is useful when
assimilating a package that require special build steps. After
configuring the build steps use
borg-build to complete the
This command clones the package named PACKAGE from URL, without assimilating it. This is useful when you want to inspect the package before potentially executing malicious or broken code.
Interactively, when the
epkg package is available, then the name
is read in the minibuffer and the url stored in the Epkg database
is used. If
epkg is unavailable, the package is unknown, or when
a prefix argument is used, then the url is also read in the
This command removes the cloned or assimilated package named CLONE,
by removing the working tree from
of whether that repository belongs to an assimilated package or a
package that has only been cloned for review using
Git directory is not removed.
This command builds the clone named CLONE. Interactively, or when
optional ACTIVATE is non-nil, then also activate the drone using
This function updates the autoload file for the libraries belonging to the clone named CLONE in the directories in PATH. PATH can be omitted or contain file-names that are relative to the top-level of CLONE’s repository.
This function compiles the libraries for the clone named CLONE in the directories in PATH. PATH can be omitted or contain file-names that are relative to the top-level of CLONE’s repository.
This function generates the Info manuals and the Info index for the clone named CLONE.
This function rebuilds all assimilated drones in alphabetic order,
except for Org which is rebuilt first. It also rebuilds
This function is not intended for interactive use, but used to
make targets described in the following section.
When optional QUICK is non-nil, then do not build drones for which
submodule.DRONE.build-step is set, assuming that those are the drones
that take longer to be built.
This function rebuilds
USER-REAL-LOGIN-NAME.el. It is
not intended for interactive use.