A self-documenting GNU Emacs starter kit inspired after Bedrock and Doom.

⚠ This starter kit is bare bones and in rapid development, things may not work, be missing or break in following releases.

This starter kit uses leaf.el as the DSL for the configuration and elpaca as package manager. There are macros and functions that help users defining what they want to use from the starter kit (much like in Doom; except I took some liberty to auto-turn on some features).

Make a backup of your old Emacs configuration. Then, clone this repository either on your $HOME or in your $XDG_CONFIG_HOME:

git clone --recurse-submodules https://github.com/shackra/backpack.git ~/.emacs.d

Be sure to put $HOME/.emacs.d/bin/ in your path, otherwise your shell won’t know where backpack is.

Now that you have the starter kit cloned with its corresponding sub-modules (right?), you need to write your configuration. It has to go on either $HOME/.backpack.d or $XDG_CONFIG_HOME/backpack, in any of those two directories make a file called init.el:

;; -*- no-byte-compile: t; -*-

(gear!
  :ui
  (theme modus-vivendi)
  :editing
  (go -treesit lsp)
  :config
  default)

This will tell Backpack Emacs what stuff you want to use. There are pouches (or categories, :ui for example) that store different gear (or modules, theme is gear). Gear can have extra features you may want to turn on (or off), Backpack Emacs expresses the existence of such additional features as flags (the flag of theme is modus-vivendi, the theme we want to use in the example above).

Some features are turned on by default if some Gear is activated. To turn them off, simply put a dash in front of the flag (-treesit in the go gear, for example). Putting a dash in front of a flag that is activated only when explicitly used by the user does nothing.

Please do the above. It helps speed up the initialization of Emacs and run functions that won’t be called in a normal execution of Emacs. When running backpack ensure you are supposed to see the elpaca information panel, among many other things, and then Emacs exiting.

At the moment of writing, there is no magical function that will show you all pouches, gear and flags available in your backpack, you’ll have to explore the gear/ folder for that.

Hopefully in the future Backpack Emacs will offer something like the help command which should show you all there is.

In short:

• :ui theme: a gorillion thousand themes. Basically the ones from Doom themes and also those included with your Emacs installation. Use their names as the flag to activate it.
• :config default: some defaults.
  • to hide the menu-bar use flag hide-menu-bar.
  • to hide the tool-bar use flag hide-tool-bar.
  • to turn off the splash screen use flag no-splash.
• Tree Sitter support for major modes that we support, turned on by default. Use flag -treesit to turn it off.
• Language Server Protocol for major modes that we support. Use flag lsp to turn it on.
• :editing: different major modes for editing text files
  • go: Go programming language support.
  • emacs-lisp: Emacs lisp… this only is for activating lispy with my favorite defaults.
  • hyprland: For the hyprlang configuration language used in Hyprland.
  • org: For org-mode. Barely anything from the stock configuration changed.
• :tools: a variety of tools
  • whitespaces: White-space trimming with ws-butler, turned on by default globally. Use :tools -whitespaces to turn it off globally.
  • magit: Install and activates Magit :)
    • to activate support for forges, use flag forge.
• :checkers: check for mistakes
  • spellchecking: Enable spellchecking with Jinx in text-mode and prog-mode.
• :email: Email support inside Emacs.
  • mu4e: Use mu4e for your email. mu4e-query is also made available so you can build mu find expression with Emacs Lisp.
    • flag -fix-msg-background-color de-activates fix for emails showing light text over bright backgrounds.
    • you can use backpack/mu4e-easy-context to easily create your email account contexts (taken from mu4e-easy) in your configuration, example:

      	(with-eval-after-load 'mu4e
      	  (setq mu4e-contexts `(,(backpack/mu4e-easy-context
      				  :c-name "example"
      				  :maildir "example-dir"
      				  :mail "[email protected]"
      				  :sig "Example signature")))