- M-EMACS
- About EMACS
- About M-EMACS
- Startup
- Package Management
- Global Functionalities
- UI Enhancements
- General Programming
- Programming
- Web Development
- Office
- Internet
- 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 configuration distribution 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 distribution is designed and tested for GNU Emacs 26.1 and above only. However, it is always suggested to use Emacs 27, the latest stable version released, for its significant improvement in the core that’s out of the scope of M-EMACS.
Some heartwarming responses from the Emacs community:
- “Actually I understated how much I liked reading through your config… What makes me excited about this config is the readability and possibility of extending in a similar way.” – from u/Orgmonics
- “I have to say Matt’s setup has the best clarity of all emacs setups I have ever tried. It’s really a good template to develop your own emacs config. Thanks again…” – from u/fqye
- “Thanks for the fantastic emacs setup, I love emacs, but trying to get lsp working right was killing me, yours worked out of the box and all I had to do was add some bindings, it’s really a time saver” – from ahonnecke
- “Thank you for helping a guy out and for sharing this. I hope this evolves to be into something really big.” – from d3v-S
- and more… Love you guys! ❤️❤️
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. This not only enables a cleaner organization but also significantly improves Emacs start-up time than the traditional everything in an org file approach.
- 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 experience 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.
An init-private.el file has been designated at user-emacs-directory for you to store personal configurations that you don’t want to source-control.
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.
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.
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.
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.
Exec Path From Shell, a library to ensure environment variables inside Emacs look the same as in the user’s shell.
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/. Execute M-x all-the-icons-install-fonts and M-x nerd-icons-install-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.
Pixel scroll precision mode, introduced in Emacs 29.1, displays text pixel-by-pixel.
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.
YASnippet, a programming template system for Emacs. It loads YASnippet Snippets, a collection of yasnippet snippets for many languages.
Flycheck, a syntax checking extension.
Flyspell enables on-the-fly spell checking in Emacs and uses Flyspell Correct for distraction-free words correction using Ivy.
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.
Indent Bars, a fast, configurable indentation guide-bars for Emacs.
Indentation Configuration
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.
Ediff, a mode to simultaneously browse through the differences between a pair of files or buffers.
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 for Golang programming.
Prerequisite: gopls is required for Golang’s LSP support.
go get golang.org/x/tools/gopls@latestRust Mode, an Emacs mode for Rust programming.
LSP 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).
Yaml mode, the Emacs major mode for editing files in the YAML data serialization format.
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.
Cmake Mode, a library that provides syntax highlighting and indentation for CMakeLists.txt and *.cmake source files.
Bazel Mode, a library that provides major modes for editing Bazel BUILD files, WORKSPACE files, .bazelrc files, as well as Starlark files.
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.
Vue mode, a major mode for Vue.js.
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. Once this is set, the agenda items tagged with DEADLINE or SCHEDULED will be displayed on the Dashboard (hopefully the dashboard will be more detailed in the future).
Org Roam, a plain-text personal knowledge management system.
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.
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.
Emacs Application Framework, a GUI application framework that revolutionizes Emacs graphical capabilities.
Prerequisite: Please ensure python3 and pip3 are installed, then follow install instructions.
Popweb, a lightweight version of EAF that provides multimedia capabilities.
Emacs 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
Mu4e, a package that provides an emacs-based e-mail client which uses mu as its backend. Mu4e Thread Folding is used to toggle between long threads.
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 --my-address=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
LeetCode, an Emacs LeetCode client. Note that this package is dependant on aio and GraphQL.
Debbugs, a package lets you access the GNU Bug Tracker from within Emacs.
A simple Hacker News Emacs client.
Emacs Web Wowser, the HTML-based Emacs Web Browser.
Packages and configurations suitable for Chinese users. Non-Chinese users feel free to add :disabled tags for them.
- Pyim, an Emacs Chinese Pinyin Input. It uses posframe package to display candidates.
- Pyim BaseDict, the default Chinese-Pyim dictionary.
我已经停止使用作者推荐的无痛中英切换，它对需要同时打英文和中文的情况不是很友好。如需切换输入法，请善用 C-\ 。
Youdao interface 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.
Let it snow in Emacs!
EPaint, a simple paint tool for emacs.
Zone, a minor-mode ‘zones’ Emacs out, choosing one of its random modes to obfuscate the current buffer.