Emacs transforms your approach to programming.
Emacs is entirely introspectable, allowing you to easily discover, “What code executes when I press this button?” This level of insight promotes an understanding of your work and deepens your engagement with the code.
Emacs serves as an incremental programming environment. You can avoid the traditional edit-compile-run cycle, which often interrupts workflow. Instead, you can write and execute small snippets of code, gradually developing them into a complete project without the need to switch contexts. The lines between your editor and interpreter blur seamlessly.
Emacs offers a mutable environment. You can modify variables, adjust functions with advice, or even redefine entire functions on the fly. This flexibility ensures that everything is open for customization, empowering you to create an environment tailored to your needs.
Emacs delivers integrated functionality without the need for applications. Instead of relying on disparate applications, all features are cohesively bundled within your Emacs instance. This means you can leverage the same snippet tool for writing C++ classes or crafting emails, enhancing efficiency and coherence in your tasks.
Emacs is rich with innovative software concepts that have yet to gain mainstream traction. Highlights include:
- While most platforms are limited to a single-item clipboard, Emacs boasts an infinite clipboard, allowing for more fluid copying and pasting.
- If you undo a change and then keep editing, many applications restrict you from redoing the original change. In contrast, Emacs enables undoing to any historical state, supporting a tree-based exploration of your editing history.
- With Emacs, you can perform a reverse variable search, making it possible to find variables set to a specific value.
- It facilitates structural editing of code, enabling you to make changes without breaking the syntax, effective for both Lisp (using paredit) and non-Lisp languages (using smartparens).
- Many applications employ a modal GUI where certain tasks block other edits, such as during a find-and-replace operation. Emacs, however, provides recursive editing, allowing you to pause your current task, perform other edits, and then return to where you left off.
Emacs fosters a rich documentation culture. It includes an extensive usage manual, a Lisp programming manual, in-depth docstrings, and even an interactive tutorial, ensuring that help is always readily available.
Emacs also boasts a broad ecosystem. Whatever niche programming language you wish to work with, there’s likely an Emacs package available for it, enhancing its versatility.
While Emacs certainly isn’t the only tool with valuable features, we believe that the Emacs learning curve is well worth the investment.
This section was based on Remacs.
M-EMACS is a customized GNU Emacs setup designed to enhance your experience while providing an easily navigable resource. Our detailed README includes nearly the entire configuration code, making it a valuable reference for users.
I remember the challenges of finding a clear and well-organized configuration when I first started using Emacs. Often, source code comments can be hard to notice or insufficiently detailed. That’s why I’ve created this README to offer clear, human-friendly explanations. This guide is perfect for beginners who are unsure where to start with their personal configuration. Feel free to explore this document and copy any part of it for your own use.
This distribution is specifically designed and tested for GNU Emacs 26.1 and higher. However, we recommend using Emacs 29, the latest stable version, due to its significant core improvements that enhance the overall experience beyond 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
$HOME.git clone https://github.com/MatthewZMD/.emacs.d.git ~/.emacs.d - Ensure a stable connection to Github, then open Emacs.
- In your favorite browser,
Ctrl-f Prerequisitethrough this README and follow the Prerequisite instructions. - Restart Emacs.
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.
Enable lexical binding for better variable scoping. Why?
Until Emacs version 24.1 (June 2012), Elisp predominantly utilized dynamically scoped variables, a characteristic common in older Lisp dialects. While dynamic scope has its specific applications, it is generally deemed unsuitable for local variables, and very few modern programming languages embrace it.
Emacs 27 introduces early-init.el, a configuration file that executes prior to init.el, coinciding with package and UI initialization.
Ensure the configuration accommodates both versions by checking if the emacs-version > 26= and manually requiring early-init settings if emacs-version < 27.
Postpone garbage collection earlier in the startup sequence to improve performance, as highlighted by hlissner.
Garbage collection can significantly slow down startup time, often doubling it. The key is to raise the memory threshold as early as possible.
Package initialization occurs automatically before loading the user configuration, which means we need to prevent Emacs from executing it prematurely.
During startup, Emacs doesn’t require specific file handlers for every file it opens or loads; thus, we should unset this list to optimize the startup process.
Disabling unnecessary interfaces at this stage enhances speed before they are initialized.
A excessively high gc-cons-threshold can lead to freezing and stuttering during prolonged interactive sessions. If stuttering occurs, increase the threshold; if freezing happens, decrease it.
Additionally, enabling garbage collection when Emacs loses focus and minimizing it during the use of the minibuffer can enhance responsiveness.
Since all configuration files reside in the elisp/ directory, it is essential to include this path in the load-path to ensure proper loading.
The init-private.el file has been designated within the user-emacs-directory for personal configurations you wish to keep outside source control.
Some packages are disabled using the :disabled tag due to infrequent usage. You can similarly disable packages as needed:
(use-package foo
:disabled)Straight is preferred over package.el for its declarative and reproducible configuration, ensuring reliable package management and easy updates by utilizing Git for version tracking.
Use-package simplifies Emacs package configuration, enhancing performance and clarity. When paired with straight.el, it allows for quick and seamless package management.
Diminish can remove certain minor modes from the mode-line to declutter the interface.
Prerequisite:
- Feel free to update this section with your information
Avy offers an efficient method for navigating text.
Crux is a collection of incredibly useful extensions for Emacs, enhancing functionality and ease of use.
Ivy is a versatile completion mechanism for Emacs. It incorporates tools such as Amx, Counsel, and Swiper to enhance the user experience.
Color rg is a search and refactoring tool built on ripgrep, designed to search text efficiently. Prerequisite: Ensure that ripgrep is installed and the `rg` command is included in your `PATH`.
Find File In Project provides quick access to files within a project in Emacs. Prerequisite: Ensure `GNU Find` is in your `PATH`, and install Gow, Cygwin, or MSYS2 on Windows to use this feature.
Dired serves as the directory editor in Emacs, facilitating file management.
Disk Usage is a file system analyzer that provides a tabulated view of file listings sorted by size, helping you manage disk space.
Winner mode allows you to restore previous window layouts, providing a quick way to manage your workspace.
Which Key displays key bindings that follow an incomplete command, enhancing usability by reminding users of available options.
Undo tree visualizes the history of changes made in a file, making it easier to manage and navigate undo operations.
Discover my major helps you explore key bindings and their meanings for the current Emacs major mode, which enhances the learning experience.
Ace Window enables you to efficiently select and switch between windows in Emacs.
Vterm is fully-fledged terminal emulator inside GNU Emacs based on libvterm, a C library. As a result of using compiled code (instead of elisp), emacs-libvterm is fully capable, fast, and it can seamlessly handle large outputs.
Shell Here opens a shell buffer within the context of the current `default-directory`, providing quick terminal access.
Multi Term is a terminal management mode that allows you to handle multiple terminal buffers conveniently within Emacs.
Term Keys provides seamless keyboard input for Emacs in terminal emulators, ensuring consistent performance.
Exec Path From Shell ensures that environment variables in Emacs match those of the user’s shell, maintaining consistency across different environments.
Sudo Edit allows you to open files with `sudo`, enabling easier access to protected files.
Ibuffer is an advanced alternative to BufferMenu that allows you to manage buffers similarly to how Dired handles files, vastly improving efficiency. It integrates with IBuffer VC, which groups buffers by git project and displays file state.
A collection of essential configurations that greatly enhance usability and productivity.
Configure Emacs to utilize UTF-8 encoding with Unix line endings for optimal compatibility.
This section manages aspects of the editing history to enhance user experience.
A selection of important functions to streamline your workflow.
Automatically updates Org Mode INCLUDE statements based on guidance from Artur Malabarba.
Doom Themes is a powerful UI plugin that provides a comprehensive collection of themes to enhance visual aesthetics in Emacs.
Doom Modeline offers a feature-rich modeline, inspired by DOOM Emacs, that is both faster and more powerful than traditional modelines.
Dashboard is an extensible startup screen for Emacs, providing a customizable interface when launching the application.
Choose either KEC_Dark_BK.png or KEC_Light_BK.png depending on your preferred background theme.
Page-break-lines displays form feed characters as clean, horizontal rules, improving readability.
Prerequisite: Install all available fonts and icons from the `fonts/` directory. Then execute M-x all-the-icons-install-fonts and M-x nerd-icons-install-fonts to apply them.
Function dedicated to switching between installed fonts seamlessly.
All The Icons is a utility package designed to aggregate various icon fonts, specifically for GUI Emacs.
Configuration settings are provided to enable smooth scrolling in Emacs, enhancing reading and navigation comfort.
Prettify symbols mode is a built-in feature that enables the display of character sequences as aesthetically pleasing symbols, improving code readability.
Configure Emacs to display both line and column numbers in the modeline for better code navigation.
This feature displays time and battery statistics in the modeline, providing useful information at a glance.
Pixel scroll precision mode, introduced in Emacs 29.1, enables finer scrolling control within a buffer, displaying content pixel-by-pixel for increased precision.
Aidermacs, Aider AI Pair Programming for Emacs
Magit provides a user-friendly interface for interacting with the Git version control system, streamlining version management tasks.
Projectile is a powerful project interaction library that simplifies navigating and managing projects in Emacs. Prerequisite: For Windows OS users, install Gow and ensure it is added to the `PATH`. Gow is a handy lightweight installer that facilitates the use of various open source UNIX applications compiled as native Win32 binaries. The `tr` command is particularly needed for Projectile’s alien indexing.
YASnippet is a versatile programming template system for Emacs. It can load YASnippet Snippets, which is a rich collection of snippets for a variety of languages.
treesit-auto simplifies installation/management of tree-sitter grammars. Automatically handles grammar compilation/updates for multiple languages.
Prerequisite: Run M-x treesit-auto-install-all to install grammars.
This package is, admittedly, a hack. treesit.el provides an excellent foundation for incremental source code parsing in Emacs 29. Over time this foundation will expand into an improved core editing experience. While this package will likely become obsolete in Emacs 30+ (which may have built-in alternatives), it still provides quality-of-life improvements for Emacs 29 users.
Dumb jump allows for swift navigation to definition within your codebase, enhancing the coding experience.
Smartparens is a minor mode designed for effectively handling paired constructs, streamlining coding involving parentheses and brackets.
This feature ensures that parentheses are matched and automatically paired while providing visual cues even when they are offscreen, enhancing code clarity.
Indent Bars is a customizable indentation guide that provides fast and efficient visual cues for code structure in Emacs.
This section also covers indentation configuration for optimal coding experiences.
Format all provides a convenient feature to auto-format source code, catering to numerous programming languages. Prerequisite: Consult Supported Languages to identify which additional tools are necessary for specific languages.
Ediff enables users to compare differences between pairs of files or buffers simultaneously, streamlining the process of resolving discrepancies.
Evil Nerd Commenter assists users in efficiently commenting out sections of code, enhancing productivity when writing or debugging.
Iedit is a versatile minor mode that facilitates simultaneous editing of multiple regions within a buffer or a selected region, streamlining the editing process.
Delete Block provides an efficient method for deleting blocks of text or code, promoting a smoother editing workflow.
Header2 simplifies the process of creating and updating file headers, automating documentation tasks.
Emacs IPython Notebook serves as a client for Jupyter, previously known as IPython, allowing for interactive coding sessions within Emacs.
- Execute
M-x ein:runto initiate a local Jupyter session. - Login with
M-x ein:loginto connect to a local or remote session. - Open a
.ipynbfile and pressC-c C-o.
Instead of the widely-used Company, I have chosen to use lsp-bridge, which is entirely multi-threaded and adept at handling all completion needs within Emacs.
Prerequisite: Since all completion features are supported by LSP Mode, it needs to be set up correctly.
- Install CMake version 3.8 or higher for all operating systems.
- For Unix-like OS:
- It is recommended to use CCLS as the LSP server. Refer to build instructions for detailed setup.
- Set `ccls-executable` to the directory where your CCLS is built.
- For Windows OS:
Emacs CCLS is a client for CCLS, which is a language server for C/C++/Objective-C. It supports massive codebases, leveraging the capabilities of libclang for enhanced performance.
Modern CPP Font Lock enhances syntax highlighting specifically for modern C++ syntax, improving readability and code comprehension.
Go Mode is an Emacs mode specifically designed for Golang programming, providing syntax highlighting and other essential tools. Prerequisite: Setting up gopls is necessary for Golang’s LSP support.
go get golang.org/x/tools/gopls@latestRust Mode is tailored for Rust programming within Emacs, ensuring robust development support.
Emacs Speaks Statistics (ESS) is designed to facilitate editing scripts and interaction with various statistical analysis programs such as R, S-Plus, SAS, Stata, and OpenBUGS/JAGS. Prerequisite: Ensure R is installed to utilize ESS effectively with R.
Prerequisite: Please ensure you have TeX Live installed on your system.
AUCTeX is a comprehensive package designed for authoring and formatting TeX documents, supporting multiple TeX macro packages such as AMS-TEX, LaTeX, Texinfo, ConTEXt, and docTEX (dtx files).
Yaml mode is the dedicated major mode for editing files in the YAML data serialization format within Emacs.
Yaml-pro contains tools for editing YAML leveraging tree-sitter/parser.
Docker is a mode enabling management of Docker containers directly from Emacs, facilitating container-based workflows.
Dockerfile Mode offers specific features for editing Dockerfiles in Emacs.
Groovy Mode encompasses a comprehensive major mode for Groovy, grails minor mode, and a groovy inferior mode, catering to Groovy developers.
Cmake Mode is a library that provides syntax highlighting and indentation functionalities for CMakeLists.txt and *.cmake files.
Bazel Mode grants major modes for editing Bazel-specific files including BUILD files, WORKSPACE files, and .bazelrc files, as well as Starlark files.
Prerequisite: Install NodeJS and ensure it is included in your `PATH`. Execute the following commands to enable LSP for JavaScript, TypeScript, and HTML:
npm i -g typescript
npm i -g typescript-language-serverWeb mode is a specialized major mode designed for editing web templates and related technologies.
JS2 mode provides an enhanced JavaScript editing experience with features aimed at improving productivity.
TypeScript mode adds dedicated support for TypeScript programming within Emacs, enhancing the development experience.
Vue mode provides specialized major mode for developing applications using Vue.js, improving the coding workflow.
Emmet enables users to write HTML swiftly using CSS-style selectors, enhancing coding efficiency. Refer to usage instructions for further information.
Instant Rename Tag offers the functionality to quickly rename HTML tag pairs, serendipitously speeding up markup editing.
JSON Mode is specifically crafted for editing JSON files, enhancing the formatting and navigation experience.
Org is a powerful built-in tool in Emacs for note-taking, maintaining TODO lists, project planning, and authoring documents in a fast and efficient plain-text format.
Prerequisite: Configure (org-agenda-files (list "~/org/agenda/")) to specify your agenda folder for using org-agenda. Once this is configured, agenda items tagged with DEADLINE or SCHEDULED will show up on the Dashboard, which will be updated to provide detailed insights in the future.
Org Roam is a personal knowledge management system based on plain text, enabling collection and organization of ideas seamlessly.
HTMLize is a powerful tool that converts buffer text and its decorations into HTML format, facilitating web integration.
OX-GFM enables Org Mode to export documents into GitHub Flavored Markdown format, enhancing sharing capabilities.
PlantUML Mode offers a dedicated environment for editing PlantUML sources. Prerequisite:
- Install plantuml and configure
(org-plantuml-jar-path (expand-file-name "path/to/plantuml.jar"))to specify its location. - Additionally, install Graphviz on your system to enable graph visualization. For example, use
sudo apt install graphvizon Ubuntu to install it.
Emacs Application Framework revolutionizes graphical capabilities in Emacs by providing a comprehensive GUI application framework.
Prerequisite: Ensure that python3 and pip3 are installed, then follow the installation instructions to get started.
Emacs Relay Chat is a modular, extensible IRC client for Emacs, supporting various functionalities like nickname highlighting through erc-hl-nicks and image display via erc-image.
Prerequisite: Add your IRC credentials to the file ~/.authinfo and configure my-irc-nick to specify your IRC nickname.
machine irc.freenode.net login <nickname> password <password> port 6697
Mu4e is a robust email client within Emacs powered by mu as its backend. It features Mu4e Thread Folding for managing lengthy email threads efficiently. Note: This mu4e configuration is tailored specifically for Gmail users. Prerequisite:
- Set up IMAP using isync/mbsync and place your
.mbsyncrcconfig in~/.emacs.d/mu4e/. A sample configuration is available. - Install mu for email handling.
- Execute the following commands to initialize your email environment.
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 encounter an
Invalid Credentialserror while confident of your password correctness, consult this guide for troubleshooting.
- If you encounter an
- (Optional) To track meetings using
org-mode, assigngnus-icalendar-org-capture-fileto your designated meeting file.
Tramp allows users to edit remote files seamlessly using various remote shell protocols (such as rlogin, telnet, or ssh).
Connect to instances on Google Cloud Platform using the format:
/gssh:some-instance:/path/to/file
LeetCode is an Emacs client designed for interacting with LeetCode problem sets. Note that it depends on both aio and GraphQL packages.
Debbugs is a package that grants access to the GNU Bug Tracker directly within Emacs, facilitating bug tracking processes.
A straightforward Hacker News client for Emacs, enabling users to stay updated with the latest news from the platform.
Emacs Web Wowser (EWW) is a built-in HTML-based web browser for Emacs, allowing users to browse the web seamlessly.
This section includes packages and configurations tailored for Chinese users. Non-Chinese users can opt to disable these features by adding :disabled tags.
- Pyim is a versatile Chinese Pinyin input method for Emacs, enhancing text input efficiency. It leverages the posframe package for displaying candidate options.
- Pyim BaseDict serves as the default dictionary for Chinese-Pyim input.
I have stopped using the recommended painless Chinese-English switching feature, as it’s not very user-friendly for those needing to type in both languages simultaneously. Please use C-\ for switching input methods if needed.
Youdao provides an interface for leveraging Youdao’s dictionary functionalities within Emacs.