2.2.1 Bootstrapping using a seed

To get started clone the repository of the emacs.g collective. A "collective" is a starter-kit and/or configuration seed that relies on Borg as the package manager. Most users end up using emacs.g merely as a bootstrapping seed and do not merge upstream changes after that.

This collective already assimilates a few drones in addition to borg itself, namely magit, epkg, use-package, auto-compile, git-modes and diff-hl, as well as their dependencies. These drones are not required by borg but their use is highly recommended.

Clone the emacs.g repository to either ~/.config/emacs, or for testing purposes to any other location. This repository contains a Makefile that imports lib/borg/borg.mk and defines an additional target whose purpose is to make that file and lib/borg/borg.sh available. Run make bootstrap-borg to clone the borg repository. That does not completely setup borg but it makes the latest version of the mentioned files available.

Now that these files are available you can run make bootstrap to get and configure all submodules (including the borg submodule) and to build all drones.

git clone git@github.com:emacscollective/emacs.g.git ~/.config/emacs
cd ~/.config/emacs
make bootstrap-borg
make bootstrap

If you have assimilated many packages, you might want to use make bootstrap | tee bootstrap.log.

The last command run during bootstrap is git submodule status, which prints one line per module. If a line is prefixed with ‘+’, that means that it was not possible to checkout the recorded commit, and - means that the module could not be cloned. Even if some module could not be cloned, that usually does not render a configuration unusable, so just run emacs now, and then investigate any issues from the comfort of Magit.

If you cloned to somewhere other than ~/.config/emacs, then you can use that configuration using emacs --init-directory /path/to/emacs.g/, provided you are using Emacs 29 or later. Otherwise you have to resort to emacs -Q -l /path/to/emacs.g/early-init.el -l /path/to/emacs.g/init.el.

For drones whose upstream repositories are located on Github or Gitlab the emacs.g collective uses the ssh protocol by default, which is a problem if you don’t have accounts there and have not properly setup your keys. See Using https URLs.

During package compilation you may notice the submodules relating to those packages become dirty due to the compilation outputs not being ignored in those submodules. For this reason it is useful to ignore these outputs globally, for example in your ~/.config/git/ignore file:

*.elc
*-autoloads.el
dir

You may discover more things that you’ll want to ignore this way as you use borg.