--- category: tool tool: emacs filename: emacs.txt contributors: - ["Joseph Riad", "https://github.com/Joseph-Riad"] --- Emacs started its life as ["the extensible, customizable display editor"](https://www.gnu.org/software/emacs/emacs-paper.html) and grew over the years into a full-blown ecosystem. Many tasks, usually relegated to a diverse set of tools can be accomplished from within Emacs in a consistent, familiar interface. Examples include directory management, viewing PDF documents, editing files over SSH, managing git repos,… (the list is quite long). In short, Emacs is yours to make of it what you will: the spectrum of users varies from those who use it to edit text files to extreme purists who use it to virtually replace their operating system. Emacs is extensible via a specialized dialect of Lisp known as Emacs Lisp (Elisp) which has a lot of macros geared towards editing text and managing text buffers. Any key (combination) you use in Emacs is bound to an Emacs Lisp function and may be remapped to any other function, including ones you write yourself. # Key Notation ```text The Emacs manual and the community in general uses a convention to refer to different key combinations used within Emacs. Specifically, Emacs has the notion of a "modifier key" that is pressed along with another key to modify its action. An example of this notation is "C-c". In this key combination "C" is the modifier and stands for the "Ctrl" key and "c" is the key whose action is being modified (the literal character "c"). The modifier shorthand: "C-" --> The "CTRL" key "M-" --> The "Meta" key (usually, the "Alt" key) "s-" --> The "Super" key (the "Cmd" key on Macs and the "Windows" key on PCs) There are other, less commonly used modifiers that I will not get into here. The key combination "C-x C-s" means you press "Ctrl+x" followed by "Ctrl+s" In addition to the above modifiers, the special keys "Esc", "Return (Enter)" and "Shift" are denoted by "ESC", "RET" and "S", respectively. ``` # Basic Emacs Concepts Here, I discuss some basic Emacs concepts and terminology that may be confusing to newcomers (especially to people used to Vim terminology) - A bunch of text that Emacs is editing is known as a **buffer** - A buffer does not necessarily correspond to an actual file on disk. It may be just a bunch of text in memory. - When a buffer corresponds to a file on disk, we say that the buffer is **visiting** that file. - Emacs typically has many buffers open at once. - The display of Emacs may be split into different **windows** (not to be confused with your operating system's windows: the operating system window for Emacs can have multiple Emacs windows inside it). - An operating system window for Emacs is called an Emacs **frame**. Thus, when the Emacs manual talks about opening a new frame, this essentially means opening a new OS *window* containing an(other) instance of Emacs. - The concepts conventionally known as cutting and pasting are referred to as **killing** and **yanking**, respectively in Emacs parlance. - The current position of the cursor is called the **point** in Emacs. Technically, **point** is defined as the position right before the character where the cursor currently is. - Finally, each buffer may have several **modes** associated with it: a **major mode** and possibly several **minor modes**. - The **major mode** defines the main behavior of Emacs in the currently selected buffer. This can be roughly thought of as the file type. For example, if you're editing a Python file, the major mode is (by default) `python-mode` which causes Emacs to highlight Python syntax and automatically indent and outdent your code blocks as syntactically required by your Python code. - **Minor modes** define subtle changes in behavior and several minor modes may be active at once in the same buffer. An example minor mode is `flyspell-mode` which automatically highlights spelling errors in your buffer. # Navigation Basics ```text The GUI version of Emacs can be navigated with the mouse like you would expect from a conventional GUI text editor. The aim here is to focus on navigation solely using the keyboard as this enhances productivity immensely. * Line movement C-n --> Next line C-p --> Previous line * Character movement C-f --> Go forward one character C-b --> Go backward one character * Word movement M-f --> Go forward one word M-b --> Go backward one word * Sentence movement M-a --> Move to the beginning of the sentence M-e --> Move to the end of the sentence * Beginning and end of line C-a --> Move to the beginning of the line C-e --> Move to the end of the line * Beginning and end of buffer M-< ("Meta+Shift+,") --> Go to the beginning of the buffer M-> ("Meta+Shift+.") --> Go to the end of the buffer * Screen movement C-v --> Scroll down by one screen-full (the last two lines of the previous screen are kept as overlap for a smoother transition) M-v --> Scroll up by one screen-full (same as above but with the first two lines) * Centering the screen C-l --> Move current line to the screen's center The above key combination actually cycles through different states depending on how many times it's been pressed. C-l --> Move current line to the screen's center C-l C-l --> Move current line to the top of the screen C-l C-l C-l --> Restore the position of the current line to where it was before the first C-l was pressed If you press "C-l" a 4th time, it cycles back to centering the current line. * Repeating movement commands Most movement commands take a numerical prefix argument that says "repeat the following command that many times". Example: C-u 3 C-p --> Go up 3 lines C-u 5 C-f --> Go forward 5 characters One notable exception are the screen scrolling commands: C-u 3 C-v --> Scroll downward 3 lines (maintaining the position of the cursor) ``` Bonus: many of the above navigation commands are the default navigation commands in Bash (e.g. pressing "C-b" while entering a Bash command takes you back one character). # File editing basics ```text * Quitting Emacs [ Now you can't say you don't know how to quit Emacs :-) ] C-x C-c --> Quit Emacs and get prompted to save any unsaved files (buffers not visiting a file will simply be discarded unless you're running in client-server mode) * Saving a buffer C-x C-s --> Save the current buffer. If not visiting a file, it will prompt you for a file name to use to save the buffer. * Searching within a buffer C-s --> Search forwards within the buffer. Search is incremental and case-insensitive by default. Press C-s to move to the next match. If you press "RET", point is moved to the currently highlighted word and the search ends. C-r --> Same as C-s except it searches backward C-_ or C-/ --> Undo the last action. Keep pressing it to move up the undo tree. C-? or M-_ --> Redo the previous change The "undo" and "redo" commands can take prefix numerical arguments to undo or redo that many actions: C-u 3 C-_ --> Undo the last 3 changes. ``` # Executing Elisp Functions ```text You can execute any currently loaded Elisp functions (including ones you have written yourself) via "M-x" M-x RET --> Prompts you for name of function to execute (Tab completion is available). Example: M-x RET search-forward-regexp RET --> Prompts you for a regular expression and searches forward in the buffer for it ``` # Emacs Configuration Emacs is configured using Elisp. On startup, it looks for a configuration file either in `~/.emacs` or `~/.emacs.d/init.el` where `~` refers to your home directory. If you're on Windows, consult [this article](https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Location-of-init-file.html) for the appropriate location of your configuration file. # Vim inside Emacs If you are considering the transition from Vim to Emacs and you're put off by the non-modal nature of Emacs editing, there is an Emacs extension known as `evil-mode` which lets you have many Vim concepts inside Emacs. Here are some things added to Emacs by `evil-mode`: - Modal editing: you get normal, insert, visual and block visual modes like Vim. In addition, you get an "Emacs" mode where movement and navigation follow the Emacs bindings. - Same movement keys as Vim in normal mode - Leader key combinations - Pressing ":" in normal mode allows you to execute commands (including system commands) In my own experience, `evil-mode` helps make the transition seamless and allows you to blend the arguably more intuitive and ergonomic keybindings of Vim with the unbridled power of Emacs for a truly superior editing experience. # Discoverable Help Emacs features a pretty powerful help system that allows you to discover new functionality all the time. ```text Obtaining help on specific topics. Tab completion is available for function and variable names. C-h f RET --> Prompts you for the name of an elisp function and displays help text on it along with a clickable link to its source code. C-h v RET --> Same as above with variables C-h k RET --> Allows you to enter a key combination and displays the name of the elisp function bound to it. Searching for help: C-h a --> Prompts you for a string to search for a command in the help system. Similar to the 'apropos' or 'man -k' commands in Unix systems. Starting a tutorial: C-h C-t --> Starts a tutorial designed to familiarize you with basic Emacs functionality. ``` # Emacs "Killer Apps" As I hinted above, Emacs functionality goes way beyond being a mere text editor. I will list here a couple of Emacs "apps" that are fairly powerful and popular and may interest you in and of themselves. ## Org Technically, `org-mode`, a major mode for buffer editing that provides organizational tools. It is very difficult to succinctly describe what Org can do because it's a behemoth of a tool that has many diverse uses to different people. I will attempt to describe the main features I use briefly. - Divide your file into sections and sub-sections for easy outlining and organizing of concepts. - Different headings in the outline are foldable/expandable so that you can focus on what you need to focus on and eliminate distractions. - You can maintain a TODO list within Org - You can compile TODO lists from many files into an agenda - Track the time you spend on each TODO task - Manage tables in plain text (including spreadsheet-like capabilities) - Using the extension `org-babel`, write and execute code blocks in your file. The results are captured and are re-usable within the file itself. Think Jupyter notebook for any language. - Display inline images and LaTeX formulas as images within your file (makes for a great note-taking system and/or personal wiki) - Export your file into many different formats (LaTeX, PDF, html,…) Org mode is a very powerful tool to add to your productivity arsenal and, on a personal note, was the reason that caused me to start using Emacs after years of using Vim. ## Magit This is a frontend to `git` from within Emacs. It features a very intuitive and discoverable interface, yet exposes very powerful functionality that allows you to manage commits at the chunk level, inspect diffs, rebase, cherry-pick, … all from within the comfort of your own editor. # A Word of Advice If you are considering using Emacs, a common trap that beginning users fall into is to copy someone else's configuration file and use it as is. I highly recommend against doing this for several reasons: - It will discourage you from learning and finding things out for yourself - Someone else's configuration will probably contain many things relevant to them that you won't need or ever use. - It defeats the purpose of having a customizable text editor that can fit your own needs. What I encourage you to do is to look at other people's configurations and seek to understand them and adapt only what makes sense to you. You can find out about new features of Emacs through many YouTube videos, screencasts or blog posts and then learn for yourself how to add them to your configuration and workflow. This way, you grow your configuration incrementally while increasing your knowledge of Emacs along the way. # Additional Resources - [The GNU Emacs Manual](https://www.gnu.org/software/emacs/manual/emacs.html) - [Emacs Stack Exchange](https://emacs.stackexchange.com/) - [Emacs Wiki](https://www.emacswiki.org/emacs/EmacsWiki)