basemacs

An Emacs base to build on.

About

basemacs is the (mostly) unopinionated start to an Emacs configuration – a base to build on. It contains some sane defaults and uses a minimal set of packages to get you started with your own config.

It is:

Literate, all configuration is done in Org files
Small, only 4 packages and their depeendencies
Reproducable, automatically install specified package versions thanks to straight.el and use-package
Hackable, no batteries included, hack up your own!

basemacs is meant to be simple, so fork it and hack away!

If you want to know a little bit more about why I created this project, see this blog post.

Packages Used

basemacs uses a small set of packages to get started.

straight.el - package management
use-package - package configuration
general.el - configuring custom keys and hooks
which-key - display key combos

Requirements

The only requirements are:

Emacs 27+

I have only tested it on OSX and Linux, but it should have no problems working in other environments.

Using

Besides copying and pasting things from this config, here is how to use it:

Installation

The easiest way to get started is to fork this repository and use it as the start of your own configuration. There should be no real need to keep track of updates.

After that, there are a few ways of using this:

Standard configuration

Backup your current config and clone this into ~/.emacs.d or ~/.config/emacs

After you backup your current config, clone this repo to ~/.emacs.d:

git clone https://github.com/<user>/basemacs.git ~/.emacs.d

Chemacs

Clone this repo to your preferred location and use chemacs.

For example, clone this repo to your preferred folder, e.g. ~/.config/basemacs:

git clone https://github.com/<user>/basemacs.git ~/.config/basemacs

Then add the cloned location to ~/.emacs-profiles.el:

(("default" . ((user-emacs-directory . "~/.emacs.d")))
 ("basemacs" . ((user-emacs-directory . "~/.config/basemacs"))))

First Steps

Now that the config is in the right place, simply start up Emacs! The first time may take a little while as packages install, but subsequent startups will be much faster.

Customization is meant to be done by making changes in config.org and tangling, but it can also be done editing the elisp directly (or any other way you fancy).

To tangle, simply make changes in config.org and run the org-babel-tangle command, it is bound to C-c C-v t by default.

Next Steps

Ok, we’ve got a basic config, now what? Check out the modules! This contains a set of modules for basemacs that provide some extra features, such as: narrowing/completion frameworks (helm, ivy, etc.), making things look a little nicer with some themes, vim emulation, and more!

You can also check out basemacs-core.org which contains the basemacs setup and modify that if you find something you don’t like. (Don’t forget to tangle it!)

FAQ

What is the difference between `basemacs` and all the other Emacs distros/starters out there?

basemacs is intended to be smaller and simpler than the others. There are no “batteries” included. basemacs is meant as a starting point for an Emacs configuration, it can easily be modified to fit a users needs as there is no magic going on here.

Inspired By

This project was inspired by all these other great Emacs starter kits/configurations/distributions/whatever you want to call them:

kwpav/basemacs