super-emacs is an out-of-the-box Emacs configuration with superpowers.
(coming soon…)
Using super-emacs as your Emacs config involves just a little more than linking the provided .emacs.d directory to your local filesystem and it can be done either using the automatic setup or doing it manually.
Simply execute the following command in a terminal:
/bin/bash -c "$(curl https://raw.githubusercontent.com/myTerminal/super-emacs/master/setup)"If everything goes as planned, the next time you start Emacs, super-emacs will be automatically configured.
PS: For macOS, the shell needs to be changed from Zsh to Bash and there needs to be a sudo xcode-select --install before anything else.
Clone this project on your local workspace like:
git clone https://github.com/myTerminal/super-emacs.gitCreate a soft link to .emacs.d under the user’s home directory.
ln -s </path/to/cloned/project>/super-emacs/.emacs.d ~/.emacs.dIf your file system does not support soft links for operating systems like Windows, you may create a copy of .emacs.d under your home directory. An obvious problem with this method would be that updates to super-emacs would need much more than a git pull.
Once done, start Emacs to enjoy new superpowers. The first startup will take a little while to fetch packages from their respective sources.
Emacs 27 comes with XDG support and hence will also work with ~~/.config/emacs~. To be able to use super-emacs that way, you can link it in the following way:
ln -s </path/to/cloned/project>/super-emacs/.emacs.d ~/.config/emacsThe below two fonts have been configured by default:
- Liberation Mono for text modes
- Fira Code for programming modes
For spell-check, you need to have aspell installed on the system for it to work with ispell. Refer to the official site for instructions on how to install it on your operating system.
To be able to interact with LLMs from within super-emacs.
To be able to work with R Markdown files, super-emacs comes pre-configured with all the required packages except for an external dependency on R which needs to be installed on the system.
super-emacs provides the user with a cleaner interface which is most noticeable when running Emacs in a graphical environment where elements like the menubar, the toolbar, and the scrollbar are hidden from sight to provide more space to work with what’s more important: the text. This barely loses any functionality as most of it is still accessible from within Emacs through other alternate means.
When running inside a graphical environment, especially when using the mouse to navigate around, Emacs often uses graphical dialog boxes for prompts and confirmations. super-emacs has this behavior disabled and all user interaction happens through the keyboard.
super-emacs comes with a set of five color themes consisting of light, dark and monochromatic colors. There’s also theme-looper that can help you switch through those themes with the following set of key bindings:
Packages used: theme-looper, material-theme, hemisu-theme, green-phosphor, overcast-theme
| Keys | Action |
|---|---|
| C-c ( | Switches to the previous theme in the list |
| C-c ) | Switches to the next theme in the list |
Whether you’re finding a file, switching between buffers or executing a command from the minibuffer, super-emacs has you covered with a smart completion system that prompts you with a list of possible candidates filtered as you type. This is implemented using a suite of three utilities: ivy, counsel and swiper.
Package used: counsel
The default modeline in Emacs is replaced with a custom (and arguably more functional) modeline using a package named telephone-line. It attempts to display as much information as possible while hiding status symbols for most minor modes.
This modeline is not available when Emacs is not run inside a graphical environment.
Packages used: telephone-line, dim
In order to keep key bindings easier to access and remember, they have been organized into four groups. The keys corresponding to the groups have to be pressed twice quickly in order to bring up the respective menus.
| Keys | Action |
|---|---|
| ~~ | Toggles menu |
| [[ | Tools menu |
| ]] | Editing menu |
| \ | Buffers and Windows menu |
There is a set of quick toggles available at the quick double-press.
Package used: key-chord
From the toggles menu:
| Keys | Action |
|---|---|
| l | Toggles line numbers in the current buffer |
| w | Toggles word-wrap in the current buffer |
| k | Toggles whether to kill line-endings when killing lines with C-k |
| s | Toggles extra line-spacing in the current buffer |
Pausing in-between executing commands shows contextual help in the minibuffer for all possible next keystrokes that can be used at that time alongside their associated commands.
Package used: which-key
Calling the function zone-quotes-set-quotes and passing it a list of quotes displays a random quote one at a time while zoning. You can activate or deactivate zoning with the mentioned key bindings:
Package used: zone-quotes
From the tools menu:
| Keys | Action |
|---|---|
| x | Disables zoning |
| z | Enables zoning |
Fonts for text and programming modes are different, more specifically Liberation Mono and Fira Code. Liberation Mono is easier to read regular text, while Fira code provides a few unique features that can be really helpful while writing and especially reading programs. One of the biggest of them is programming ligatures that combine two or more characters into a single symbol that is more easily identifiable in between other text.
These fonts are also configurable using the file variables.el.
Package used: fira-code
Just as the line number for the cursor position is displayed on the modeline, column numbers are displayed too. While editing files that follow a strict column limit, column-enforce-mode can be used.
Package used: column-enforce-mode
While typing text, all kinds of brackets ((, [, and {) and quotes (', ", and `) are automatically closed. This is implemented using electric-pairs which is included with Emacs since the recent versions.
Visual feedback is also while stepping on balanced and unbalanced brackets.
Text indentation is only performed with spaces instead of tabs, and each indent is made up of four spaces.
Leading and trailing white spaces can be highlighted in a buffer using outer-spaces-mode. It is available under the toggles menu.
Package used: outer-spaces
From the toggles menu:
| Keys | Action |
|---|---|
| SPACE | Toggles outer-spaces-mode |
Unlike a regular search that takes the cursor through the points of occurrences, super-emacs provides an interactive search using swiper. This feature starts with a list of all the lines of text in the current buffer, letting you type in your search criteria to narrow the list down. Selecting a search result takes you to the point of occurrence.
Package used: counsel
From the toggles menu:
| Keys | Action |
|---|---|
| C-c s | Starts swiper to provide an interactive search |
Replacing text is interactive too with the help of anzu, which displays the number of search results found for the current search criteria. Furthermore, while typing the new text to be used in place of searched term, it also displays the new text beside the old one for all occurrences in the buffer.
Package used: anzu
| Keys | Action |
|---|---|
| M-% | Starts search and replace with anzu |
In most modes, a popup menu is presented at the position of the cursor when three or more characters are typed. The list contains auto-completion candidates matching the text that is being typed. This is achieved using company-mode.
Package used: company-mode
Out of the many features the package provides, a few basic ones include scrolling down the list of presented options and selecting one for completion.
| Keys | Action |
|---|---|
| TAB or RET | Chooses the only suggested completion |
| M-p | Scrolls up the list of suggestions |
| M-n | Scrolls down the list of suggestions |
| RET | Chooses the selected suggestion from the list |
When editing text of repetitive nature, repeating the same edit multiple times can get tiring. For such a scenario, one can use multiple-cursors to literally spawn multiple cursors in the current buffer according to the selected pattern. Once started, all edits made to the current line are replicated to the other lines with the temporary cursors and pressing RET brings it back to the original cursor.
Package used: multiple-cursors
| Keys | Action |
|---|---|
| C-} | Spawns an additional cursor for the next text matching the current selection |
| C-{ | Spawns an additional cursor for previous text matching the current selection |
| C-” | Spawns cursors for all text matching the current selection |
Unlike the regular Emacs behavior where when some text is selected and the user starts typing, the text starts getting inserted at the point of the cursor, clearing the selection, in super-emacs one can start typing over a selection to replace it with the text being typed.
Imagine being able to visualize a historical graph of your undo operations. undo-tree does just that by rendering a tree with nodes in another buffer, letting you move between the nodes. When you’re done moving back/forward, pressing q takes it to the default condition.
Package used: undo-tree
| Keys | Action |
|---|---|
| C-| | Shows a graph of states in the current buffer |
| <arrow keys> | Move through the states |
| q | Dismisses the undo tree |
Another quick way to access the kill ring while yanking text is to use counsel.
Package used: counsel
| Keys | Action |
|---|---|
| M-y | Shows a list of items previously yanked |
All text buffers are automatically checked for spelling. This is implemented with ispell, so if the external dependency aspell is installed, spellings will be automatically checked as you type.
When working with colors in a buffer, one can enable rainbow-mode, which will paint all text representing colors in their respective colors.
Package used: rainbow-mode
One can provide text snippets for text and programming constructs and use tab completion to save keystrokes. This has been implemented using yasnippet, so you may refer to the project’s repo to know about its comprehensive usage documentation. The snippets should be placed in the directory ~~/.emacs.d/snippets~.
Package used: yasnippet
While working with LaTex documents, a live preview can be achieved right within Emacs using latex-preview-pane.
Package used: latex-preview-pane
With counsel in place, the regular commands to work with buffers and windows are significantly better.
Package used: counsel
| Keys | Action |
|---|---|
| C-x b | Uses ivy to provide a list of buffers to switch to one from |
| C-x C-f | Uses counsel to find a file |
| C-x C-r | Uses counsel to look for a recent file |
| C-c b | Uses ivy to push the current window layout as a buffer entry |
winner-mode allows moving back and forth between window layouts.
| Keys | Action |
|---|---|
| C-c <left> | Moves back to previous windows layout |
| C-c <right> | Moves to the next windows layout |
One has at least three key bindings to quickly move around specific parts of a buffer using avy.
Package used: avy
From the editing menu:
| Keys | Action |
|---|---|
| k | Jump to a specific character in the buffer |
| j | Jump to a word starting with a specific character |
| l | Jump to a specified line |
Quickly moving focus between windows has been implemented using ace-window. When invoked, it distributes numbers to all the visible windows across all open frames. As it goes without saying, pressing the number corresponding to a window takes focus to that window.
Package used: ace-window
From the buffers & windows menu:
| Keys | Action |
|---|---|
| \ | Shows a menu of all visible windows with numbers |
| S-<left> | Moves to the window to the left |
| S-<right> | Moves to the window to the right |
| S-<up> | Moves to the window above |
| S-<down> | Moves to the window below |
If you’d like to re-arrange buffers among windows, buffer-move can help do that fairly easily.
Package used: buffer-move
From the buffers & windows menu:
| Keys | Action |
|---|---|
| M-<left> | Swap buffer with the one in the left window |
| M-<right> | Swap buffer with the one in the right window |
| M-<up> | Swap buffer with the one in the window above |
| M-<down> | Swap buffer with the one in the window below |
If you’d like to resize windows without moving away from the keyboard, you can use window-shaper.
Package used: window-shaper
From the buffers & windows menu:
| Keys | Action |
|---|---|
| _ | Starts window-shaper-mode to allow resizing the current window vertically or horizontally using the scroll keys |
There’s also the golden-ratio-mode that resizes windows on focus. Every window you move focus to becomes larger than the rest.
Package used: golden-ratio
Working with multiple workspaces is made possible using perspective.
Package used: perspective
| Keys | Action |
|---|---|
| M-s | Switch to a named workspace or create one |
| M-c | Close a specified workspace |
| M-z C-s | Store all workspaces to disk |
| M-z C-l | Load previously-stored workspace |
There are many more commands for you to explore.
A simple directory tree is available using ztree, and it allows to expand and collapse directories to view their contents. One can view a tree using the command ztree-dir and supplying a directory to start at.
Package used: ztree
From the tools menu:
| Keys | Action |
|---|---|
| . | Starts ztree at the specified directory |
Dired has been supplemented with a set of three add-ons: dired-narrow, dired-subtree, and dired-ranger. One can access any of these from within a dired buffer.
Packages used: dired-narrow, dired-subtree, dired-ranger
From a dired buffer:
| Keys | Action |
|---|---|
| / | Helps filter the directory listing |
| ] | Toggles a subtree under the current item if it is a directory |
| [ | Cycles a subtree through various expansion states |
| C-<up> | Navigates to the beginning of a subtree |
| C-<down> | Navigates to the end of a subtree |
| C-<left> | Navigates one level up from the subtree |
| C-<right> | Navigates one level down in the subtree |
| M-<up> | Navigates to the previous sibling in the subtree |
| M-<down> | Navigates to the next sibling in the subtree |
| M-<right> | Mark all items under the current subtree |
| M-<left> | Unmarks all items under the current subtree |
| M-c | Mark the current selection for copy |
| M-m | Move the previously selected items for copy |
| M-v | Paste the previously selected items for copy |
super-emacs has been configured with three package sources in the following priority:
| Priority | Package archive |
|---|---|
| 1 | GNU ELPA |
| 2 | MELPA Stable |
| 3 | MELPA |
Even with this in place, packages are installed directly from GitHub using a package named quelpa.
Using projectile, working with software projects is made easy with all IDE-like features right within Emacs. One can find files, search for text within all files, and do much more with a few easy-to-remember key bindings.
Listing down all the features of a package like projectile would be beyond the scope of this document, so you are suggested to refer to its own official documentation. There are also a few external dependencies that can be installed in order to improve the functionality of projectile.
Packages used: projectile, counsel-projectile, projectile-extras
| Keys | Action |
|---|---|
| C-\ | Starts the projectile menu |
From editing menu:
| Keys | Action |
|---|---|
| s | Prompts for a text to search in the current project |
| r | Searches for the term under cursor in the current project |
Along with the other languages supported by default in Emacs, a few other packages have been installed to add (and sometimes improve) support for more languages. Some of them include markdown-mode, web-mode (for more than just HTML), js2-mode (as an improvement over the default JavaScript mode), less-css-mode, scss-mode, sass-mode, yaml-mode, vue-mode, typescript-mode, rust-mode, and csharp-mode.
Packages used: markdown-mode, web-mode, js2-mode, less-css-mode, scss-mode, sass-mode, yaml-mode, vue-mode, typescript-mode, rust-mode, csharp-mode
Specifically for Common Lisp, slime provides a development environment with a REPL and more.
Package used: slime
A “dumb” alternative to projectile is dumb-jump, at least for jumping to references to symbols within a software project and returning back to its reference.
Package used: dumb-jump
From the editing menu:
| Keys | Action |
|---|---|
| ‘ | Jumps to the definition of the symbol under the cursor |
| “ | Returns back to the reference of the symbol |
For a better programming experience, super-emacs comes with eglot, a language server client that can connect to the language server for a particular language being worked on. eglot is another such package that has a massive list of features that you can learn about at its official documentation.
Basically running eglot in a buffer lets you start a connection to the language server, if one is installed.
Package used: eglot
When needing to evaluate snippets from a buffer, quickrun could be of help. It supports more than just evaluating expressions.
Package used: quickrun
In a programming buffer:
| Keys | Action |
|---|---|
| C-c e | Evaluates the expression to the left of the cursor |
| C-c r | Evaluates the selected region |
| C-c t | Evaluates the selected region and replaces it with the result in the buffer |
restclient allows testing REST APIs from Emacs. One can edit requests on the left and see the results from the response on the right.
Package used: restclient
skewer-mode provides live interaction with JavaScript, CSS, and HTML in a web browser.
Package used: skewer-mode
magit provides a fully-featured text-based interface to git. The menus are very user-friendly, and you can do pretty much everything from a single command named magit-status.
Package used: magit
| Keys | Action |
|---|---|
| C-x g | Shows magit-status and waits for a command. Pressing h or ? shows help around all possible commands |
Information about file changes is displayed in the file buffer or within a dired buffer. This has been implemented using diff-hl, requiring no user interaction for basic features.
Package used: diff-hl
super-emacs also comes with an email client: mew. Feel free to refer to the official documentation for information on how to configure it for your account and about usage.
Package used: mew
super-emacs provides access to statistical computing with ess and polymode.
Packages used: ess, polymode, poly-R, poly-markdown
super-emacs has an integration with large language models that you can interact with in quite a lot of ways.
Packages used: ellama
From tools menu:
| Keys | Action |
|---|---|
| ? | Starts a chat with Ellama |
| l | Prompt for an Ellama action |
Automatic backups are disabled so that your directories are no polluted with temporary files ending with a “~”.
The startup screen displays some useful information about the current Emacs version, date, active config file, etc.
The following actions are available on the startup screen:
| Keys | Action |
|---|---|
| z | Shows a prompt to load a previously saved perspective session |
| ? | Starts a chat with Ellama |
| q | Dismisses the startup screen |
For portable machines with a battery as a power source, the current remaining battery level is displayed in the modeline.
With the right sound volume backend, the volume level can be controlled using volume.el.
Package used: volume
There are the following minor tweaks:
| Keys | Action |
|---|---|
| C-c p | Switches to the previously viewed buffer |
| C-x k | Kills the current buffer instead of prompting from a list |
| M-<down> | Moves the current line down a position |
| M-<up> | Moves the current line up a position |
| C-<backspace> | Deletes the word to the left of the cursor instead of killing it into the kill-ring |
| C-= | Evaluates the expression to the left and replaces it with the result |
From tools menu:
| Keys | Action |
|---|---|
| / | Starts a terminal in the current window |
| i | Prompts to connect to IRC |
From editing menu:
| Keys | Action |
|---|---|
| f | Reloads the file in the current buffer |
From buffers & windows menu:
| Keys | Action |
|---|---|
| + | Toggles split direction of current pair of windows |
There are a lot of other minor tweaks that super-emacs comes with in order to make a complete system.
The recommended way to customize super-emacs is to place your custom configuration scripts under ../.emacs.d/configs/basic-custom.el and ../.emacs.d/configs/standard-custom.el for text and graphical modes respectively. Configuration files will be loaded in the correct order so that your custom configuration will override the ones from super-emacs. This way, whenever there’s an update to the original file, there will be no merge conflicts and life would be so much simpler!
There are also variables in ./..emacs.d/configs/variables.el that you can customize to alter certain things in super-emacs.
(coming soon…)