- M-EMACS
- About EMACS
- About M-EMACS
- Startup
- Package Management
- Global Functionalities
- User Interface Enhancements
- General Programming
- Programming
- Web Development
- Miscellaneous
Emacs changes how you think about programming.
Emacs is totally introspectable. You can always find out ‘what code runs when I press this button?’.
Emacs is an incremental programming environment. There’s no edit-compile-run cycle. There isn’t even an edit-run cycle. You can execute snippets of code and gradually turn them into a finished project. There’s no distinction between your editor and your interpreter.
Emacs is a mutable environment. You can set variables, tweak functions with advice, or redefine entire functions. Nothing is off-limits.
Emacs provides functionality without applications. Rather than separate applications, functionality is all integrated into your Emacs instance. Amazingly, this works. Ever wanted to use the same snippet tool for writing C++ classes as well as emails?
Emacs is full of incredible software concepts that haven’t hit the mainstream yet. For example:
- Many platforms have a single item clipboard. Emacs has an infinite clipboard.
- If you undo a change, and then continue editing, you can’t redo the original change. Emacs allows undoing to any historical state, even allowing tree-based exploration of history.
- Emacs supports a reverse variable search: you can find variables with a given value.
- You can perform structural editing of code, allowing you to make changes without breaking syntax. This works for lisps (paredit) and non-lisps (smartparens).
- Many applications use a modal GUI: for example, you can’t do other edits during a find-and-replace operation. Emacs provides recursive editing that allow you to suspend what you’re currently doing, perform other edits, then continue the original task.
Emacs has a documentation culture. Emacs includes a usage manual, a lisp programming manual, pervasive docstrings and even an interactive tutorial.
Emacs has a broad ecosystem. If you want to edit code in a niche language, there’s probably an Emacs package for it.
Emacs doesn’t have a monopoly on good ideas, and there are other great tools out there. Nonetheless, we believe the Emacs learning curve pays off.
This beautifully written *About EMACS* section credits to Remacs.
M-EMACS is a custom GNU Emacs setup and configurations that aims not only to enhance the default Emacs experience, and hopefully be a sample that everyone can easily navigate and reference through a highly detailed README that contains 99% of the entire configuration code.
As a young EMACSer, I have experienced the struggle to find a detailed configuration that is loosely coupled and highly readable. This mostly due to the nature of source codes, sometimes comments are harder to notice or simply not enough. Therefore I decided to construct this README and present any human-readable explanation in a much more human-friendly way. Anyone, particularly Emacs beginners who have no idea where to start with their personal config, is more than welcome to read through this document and copy/paste any part to use it on their own.
This configuration is designed and tested for GNU Emacs 26.1 and above only. However, it is suggested to use emacs27, the latest version currently available.
This README is originated from init.org that is generated using M-x org-gfm-export-to-markdown. Every block of code is generated through this function - it exports sections of code from the elisp/ directory. You will not see their presence in init.org.
- Install GNU Emacs.
- (Optional) On Ubuntu,
emacs-snapshotis a great way to get latest version of Emacs.sudo add-apt-repository -y ppa:ubuntu-elisp sudo apt-get update sudo apt-get install emacs-snapshot - (Optional) Build latest Emacs from source.
# Install essential build tools sudo apt-get install build-essential texinfo libx11-dev libxpm-dev libjpeg-dev libpng-dev libgif-dev libtiff-dev libgtk2.0-dev libncurses-dev gnutls-dev libgtk-3-dev git autoconf # Clone source git clone --depth=1 https://github.com/emacs-mirror/emacs.git # Go to source cd emacs/ # Build Emacs ./autogen.sh ./configure --with-mailutils make # Install (optional) sudo make install
- (Optional) On Ubuntu,
- Clone this repo to
HOMEor~/path using git and update all the submodules.cd ~ git clone --recurse-submodules -j8 https://github.com/MatthewZMD/.emacs.d.git cd .emacs.d
- Ensure a stable connection to Melpa Packages, then open Emacs.
- Enter
ywhen prompted withAuto-update packages now?, wait for all packages to install. - In your favorite browser,
Ctrl-f Prerequisitethrough this README and follow the Prerequisite instructions. - Restart Emacs.
I will be updating M-EMACS from time to time, it is best to git pull once a while to stay up to date.
Please also execute git submodule update --recursive --remote to sync with all the submodules.
You have the permission to use, modify, distribute in any way you want.
However, what is free stays free. After all, this is GPL.
Remember you must manually sync this README with all the new changes you made by:
- Please do NOT edit this
README.mdfile, editinit.orginstead! - If you add a new mode, create a new
<file-name>.elfile inelisp/directory. - Put
(require '<file-name>)in init.el accordingly. - Add
#+INCLUDE: "~/.emacs.d/elisp/<place-holder>.el" src emacs-lisp :range-begin "<start-line-wrapper-exclusive>" :range-end "<end-line-wrapper-exclusive>"in the appropriate section ininit.org. - Enter
C-x C-sto save and update:lines. (if you don’t see the updated effect, runM-x save-and-update-includesmanually) - Call
M-x org-gfm-export-to-markdownto updateREADME.mdautomatically.
If you spotted a bug or you have any suggestions, please fill in an issue. If you have something to fix, feel free to create a pull request.
Everyone starts somewhere, and I started here.
Use lexical-binding. Why?
Until Emacs 24.1 (June 2012), Elisp only had dynamically scoped variables, a feature, mostly by accident, common to old lisp dialects. While dynamic scope has some selective uses, it’s widely regarded as a mistake for local variables, and virtually no other languages have adopted it.
Emacs27 introduces early-init.el, which is run before init.el, before package and UI initialization happens.
Ensure emacs-version>=26, manually require early-init configurations if emacs-version<27.
Defer garbage collection further back in the startup process, according to hlissner.
The GC eats up quite a bit of time, easily doubling startup time. The trick is to turn up the memory threshold as early as possible.
Package initialize occurs automatically, before user-init-file is loaded, but after early-init-file.
We handle package initialization, so we must prevent Emacs from doing it early!
Every file opened and loaded by Emacs will run through this list to check for a proper handler for the file, but during startup, it won’t need any of them.
It will be faster to disable them here before they’ve been initialized.
A large gc-cons-threshold may cause freezing and stuttering during long-term interactive use.
If you experience freezing, decrease this amount, if you increase stuttering, increase this amount.
Garbage Collect when Emacs is out of focus and avoid garbage collection when using minibuffer.
Since all the configuration files are stored in elisp/ folder, they need to be added to load-path now.
Some packages are disabled with the :disabled tag, because I don’t use them very often. You can disable packages similarly yourself too:
(use-package foo
:disabled)Configure package archives, where to install online packages and add them to load-path.
Add packages contained in site-elisp/ to load-path too.
cd site-elisp/
git submodule add https://github.com/foo/bar.gitVerify /.gitmodules file that the newly added package exist.
git submodule init
git submodule updateMy Emacs configuration is almost entirely dependant on use-package.
The
use-packagemacro allows you to isolate package configuration in your .emacs file in a way that is both performance-oriented and, well, tidy. I created it because I have over 80 packages that I use in Emacs, and things were getting difficult to manage. Yet with this utility my total load time is around 2 seconds, with no loss of functionality!
Auto package update automatically updates installed packages if at least auto-package-update-interval days have passed since the last update.
Diminish, a feature that removes certain minor modes from mode-line.
Prerequisite: Please update this file your personal info.
Avy, a nice way to move around text.
Crux, a Collection of Ridiculously Useful eXtensions for Emacs.
Ivy, a generic completion mechanism for Emacs. It utilizes Amx, Counsel and Swiper.
Color rg, a search and refactoring tool based on ripgrep that is used to search text.
Prerequisite: Ensure ripgrep and ensure rg is in PATH.
Find File In Project, quick access to project files in Emacs.
Prerequisite: Ensure GNU Find is in PATH. Install Gow or Cygwin or MYSYS2 on Windows.
Snails, a fuzzy search framework. It utilizes exec-path-from-shell if you are using Mac.
Dired, the directory editor.
Disk Usage, a file system analyzer that offers a tabulated view of file listings sorted by size.
Winner, a mode to restore previous window layouts.
Which Key, a feature that displays the key bindings following the incomplete command.
Popup Kill Ring, a feature that provides the ability to browse Emacs kill ring in autocomplete style popup menu.
Undo tree, a feature that provides a visualization of the undos in a file.
Discover my major, a feature that discovers key bindings and their meaning for the current Emacs major mode.
Ace Window, a package for selecting windows to switch to.
Aweshell, shell extension base on eshell with better features.
Shell Here, a tool that opens a shell buffer in (or relative to) default-directory.
Multi Term, a mode based on term.el, for managing multiple terminal buffers in Emacs.
Term Keys, a lossless keyboard input for Emacs in terminal emulators.
Sudo Edit, an utility for opening files with sudo.
Ibuffer, an advanced replacement for BufferMenu, which lets you operate on buffers much in the same manner as Dired.
It uses IBuffer VC that group buffers by git project and show file state.
Some essential configs that make my life a lot easier.
Use UTF-8 as much as possible with unix line endings.
Important functions.
Update Org Mode INCLUDE Statements Automatically from Artur Malabarba.
Doom Themes, an UI plugin and pack of themes.
Doom Modeline, a modeline from DOOM Emacs, but more powerful and faster.
Dashboard, an extensible Emacs startup screen.
Use either KEC_Dark_BK.png or KEC_Light_BK.png depends on the backgrond theme.
Page-break-lines, a feature that displays ugly form feed characters as tidy horizontal rules.
Prerequisite: Install all the available fonts and icons from fonts/.
Function to switch between fonts.
All The Icons, a utility package to collect various Icon Fonts. Enable only in GUI Emacs.
Configurations to smooth scrolling.
Prettify symbols mode, a built-in mode for displaying sequences of characters as fancy characters or symbols.
Display line numbers, and column numbers in modeline.
Display time and battery information in modeline.
Magit, an interface to the version control system Git.
Projectile, a Project Interaction Library for Emacs.
Prerequisite: Windows OS: Install Gow and ensure it’s in PATH.
Gow is a lightweight installer that installs useful open source UNIX applications compiled as native win32 binaries. Specifically, tr is needed for Projectile alien indexing.
Treemacs, a tree layout file explorer for Emacs.
YASnippet, a programming template system for Emacs. It loads YASnippet Snippets, a collection of yasnippet snippets for many languages.
Flycheck, a syntax checking extension.
Dumb jump, an Emacs “jump to definition” package.
Smartparens, a minor mode for dealing with pairs.
Match and automatically pair parenthesis, and show parenthesis even when it went offscreen from Clemens Radermacher.
Highlight Indent Guides, a feature that highlights indentation levels.
Indentation Configuration
Quickrun, compile and run source code quickly.
Format all, a feature that lets you auto-format source code.
Prerequisite: Read Supported Languages to see which additional tool you need to install for the specific language.
Evil Nerd Commenter, a tool that helps you comment code efficiently.
Iedit, a minor mode that allows editing multiple regions simultaneousy in a buffer or a region.
Awesome Pair, a feature that provides grammatical parenthesis completion.
Conf Mode, a simple major mode for editing conf/ini/properties files.
Delete Block, a feature that deletes block efficiently.
Header2, a support for creation and update of file headers.
Emacs IPython Notebook, a Jupyter (formerly IPython) client in Emacs.
- Execute
M-x ein:runto launch a local Jupyter session. - Login with
M-x ein:loginto a local or remote session. - Open
.ipynbfile and pressC-c C-o.
Language Server Protocol Mode, a client/library for the Language Server Protocol. M-EMACS tries to use lsp-mode whenever possible.
Language Server Protocol UI, provides all the higher level UI modules of lsp-mode, like flycheck support and code lenses.
Note: lsp-ui-doc is too annoying, so it will not be triggered upon hovering. You have to toggle it using M-i.
Debug Adapter Protocol Mode, a client/library for the Debug Adapter Protocol.
Prerequisite: See Configuration to configure DAP appropriately.
Company, a text completion framework for Emacs.
The function smarter-yas-expand-next-field-complete is to smartly resolve TAB conflicts in company and yasnippet packages.
Company TabNine, A company-mode backend for TabNine, the all-language autocompleter.
This is enabled by default, if ever you find it not good enough for a particular completion, simply use M-q to immediately switch to default backends.
Prerequisite: Execute M-x company-tabnine-install-binary to install the TabNine binary for your system.
Company Box, a company front-end with icons.
LSP Java, Emacs Java IDE using Eclipse JDT Language Server. Note that this package is dependant on Request.
Prerequisite: Install Maven and ensure it’s in PATH.
Prerequisite: Since all completion features are provided by LSP Mode, it needs to setup.
- Install CMake >= 3.8 for all OS.
- *nix OS:
- Windows OS:
Emacs CCLS, a client for CCLS, a C/C++/Objective-C language server supporting multi-million line C++ code-bases, powered by libclang.
Modern CPP Font Lock, font-locking for “Modern C++”.
Go Mode, an Emacs mode Golang programming.
Prerequisite: gopls is suggested for Golang’s LSP support.
go get golang.org/x/tools/gopls@latestLSP Pyright, a lsp-mode client leveraging Pyright language server.
Haskell Mode, an Emacs mode for Haskell programming.
Emacs Speaks Statistics, short for ESS, it’s designed to support editing of scripts and interaction with various statistical analysis programs such as R, S-Plus, SAS, Stata and OpenBUGS/JAGS.
Prerequisite: Install R to start using ESS with R.
Prerequisite: Please install TeX Live.
AUCTeX, an extensible package for writing and formatting TeX files. It supports many different TeX macro packages, including AMS-TEX, LaTeX, Texinfo, ConTEXt, and docTEX (dtx files).
Org Latex Instant Preview, a package that provides instant preview of LaTeX snippets via MathJax outputed SVG.
Prerequisite: Please install MathJax-node-cli and set org-latex-instant-preview-tex2svg-bin to the location of the executable tex2svg.
npm i -g mathjax-node-cli
which tex2svg # mine is in /usr/bin/tex2svgFinally, invoke with M-x org-latex-instant-preview-start when needed.
Docker, a mode to manage docker from Emacs.
Dockerfile Mode, an Emacs mode for handling Dockerfiles.
Groovy Mode, a groovy major mode, grails minor mode, and a groovy inferior mode.
Prerequisite: Install NodeJS and ensure it’s in PATH. Execute following commands to enable LSP for JavaScript/TypeScript/HTML:
npm i -g typescript
npm i -g typescript-language-serverWeb mode, a major mode for editing web templates.
JS2 mode, a feature that offers improved JavsScript editing mode.
TypeScript mode, a feature that offers TypeScript support for Emacs.
Emmet, a feature that allows writing HTML using CSS selectors along with C-j. See usage for more information.
Instant Rename Tag, a plugin that provides ability to rename html tag pairs instantly.
JSON Mode, a major mode for editing JSON files.
Org, a Emacs built-in tool for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.
Prerequisite: Configure (org-agenda-files (list "~/org/agenda/")) to your agenda folder to use org-agenda.
TOC Org generates table of contents for .org files
HTMLize, a tool that converts buffer text and decorations to HTML.
OX-GFM, a Github Flavored Markdown exporter for Org Mode.
PlantUML Mode, a major mode for editing PlantUML sources.
Prerequisite:
- Install plantuml and configure
(org-plantuml-jar-path (expand-file-name "path/to/plantuml.jar")). - Install Graphviz on your system to support graph visualization. Execute
sudo apt install graphvizin Ubuntu.
Emacs Application Framework, a GUI application framework that revolutionizes Emacs graphical capabilities.
Prerequisite: Please ensure python3 and pip3 are installed, then follow install instructions.
Note that If you are using Debian/Ubuntu, it is possible that QtWebEngine is not working. Install the following:
sudo apt-get install python3-pyqt5.qtwebengine python3-pyqt5.qtmultimediaEmacs Relay Chat, a powerful, modular, and extensible IRC client for Emacs. It utilizes erc-hl-nicks for nickname highlighting and erc-image to fetch and show received images in ERC.
Prerequisite: Put IRC credentials in the file ~/.authinfo and configure my-irc-nick to your IRC nickname.
machine irc.freenode.net login <nickname> password <password> port 6697
Emacs Web Wowser, the HTML-based Emacs Web Browser.
Mu4e, a package that provides an emacs-based e-mail client which uses mu as its backend.
Note: This mu4e configuration is tailored for Gmail.
Prerequisite:
- Configure IMAP using isync/mbsync, put your
.mbsyncrcconfig file in~/.emacs.d/mu4e/. A sample is provided. - Install mu.
- Execute the follwing commands
mkdir -p ~/Maildir/gmail/ mbsync -c ~/.emacs.d/mu4e/.mbsyncrc -Dmn gmail mbsync -c ~/.emacs.d/mu4e/.mbsyncrc -a mu init --maildir=~/Maildir/ --my-address=YOUR_EMAIL1 YOUR_EMAIL2 mu index
- If you are getting
Invalid Credentialserror and you are sure the password is correct, check this link.
- If you are getting
- (Optional) If you want to track meetings using
org-mode, setgnus-icalendar-org-capture-fileto the meeting’s file.
Tramp, short for Transparent Remote Access, Multiple Protocols is a package for editing remote files using a remote shell connection (rlogin, telnet, ssh).
Connect to Google Cloud Platform using the following:
/gssh:some-instance:/path/to/file
PDF Tools, an Emacs support library for PDF files. It works best on non-Windows OS.
Note: You need convert provided from imagemagick to Pick a Link and Jump with F.
LeetCode, an Emacs LeetCode client. Note that this package is dependant on aio and GraphQL.
Pyim, an Emacs Chinese Pinyin Input. It uses posframe package to display candidates.
我已经停止使用作者推荐的无痛中英切换，它对需要同时打英文和中文的情况不是很友好。如需切换输入法，请善用 C-\ 。
Pyim BaseDict, the default Chinese-Pyim dictionary.
Debbugs, a package lets you access the GNU Bug Tracker from within Emacs.
EPaint, a simple paint tool for emacs.
Although Tetris is part of Emacs, but there still could be some configurations.
Speed type, a game to practice touch/speed typing in Emacs.
2048 Game, an implementation of 2048 in Emacs.
Zone, a minor-mode ‘zones’ Emacs out, choosing one of its random modes to obfuscate the current buffer.