Emacs Parlance

With Emacs:

• a frame is actually a regular GUI window
• a window is a subdivision of a frame (hence to be understood as a window pane)
• a buffer is the content shown in a window
• (the) point is the (current) cursor position
• the mark is the beginning of the current selection (typically set by C-SPC at the current point)
• ELPA stands for Emacs Lisp Package Archive (see more package-related explanations):
  • GNU ELPA is ~450 packages, considered part of Emacs
  • NonGNU ELPA contains third-party packages whose copyright has not been assigned to the Free Software Foundation
  • MELPA for Milkypostman’s Emacs Lisp Package Archive; ~6000 packages that can be freely added

Key Bindings

Here C corresponds to the "Ctrl" key, M the "Meta" one (i.e. "Alt", generally), S to the Shift one, and - is just a separator between a modifier (like Ctrl, Meta, etc.) and an actual key to press while the modifier is still held down. RET means the Enter key, SPC the spacebar, M-L_ARROW / M-R_ARROW the left / right arrow keys.

For example C-x C-- means: press and hold the "Ctrl" key, and hit the "x" key, then release all, then press and hold the "Ctrl" key, and hit the "-" key, and release all.

At least based on our (Emacs and French keyboard) base settings (i.e. the ones in init-base.el), the following key bindings trigger the corresponding actions:

• C-a / C-e: move cursor to leftmost / rightmost position
• C-k: kill all characters on the right from cursor (and thus put them in the kill ring)
• C-s PATTERN RET / C-r PATTERN RET: perform direct / reverse case-insensitive search of the specified pattern; then each C-s / C-r will jump direct / reverse to any next occurrence; RET will stop the search
• C-d SEARCH_PATTERN RET REPLACE_PATTERN RET: perform replacements, bound to replace-string (default binding to delete char at cursor - delete-char - not useful enough, as a dedicated key, the Delete one, exists for that)
• C-l LINE_NUMBER: go to the specified line
• C-x C-s: save current buffer
• C-x C-k: kill current buffer
• C-x C-c: exit Emacs
• C-g: cancel command/selection
• C-z: undo last action (or C-x u); to redo, rather than typing C-g C-/ (which would involve a shift, on French keyboards), just perform a non-editing command (such as C-SPC) and then the next C-z commands will go in the opposite direction in the undo chain (they will redo)
• C-SPC: set the mark (begin selection)
• C-w: cut selection in the kill ring (selection is thus removed from the current buffer)
• M-w: copy selection in the kill ring (selection thus remains in the current buffer)
• C-y: yank (paste from kill ring, replacing any current selection)
• M-y: replace text just yanked with an earlier batch of killed text
• C-p: compile, make
• C-x TAB: indent rigidly, moving the whole selection left/right with M-L_ARROW / M-R_ARROW (see also kill-rectangle)
• M-< / : M-S-<: go to beginning / end of the current buffer

• C-x 2: split window horizontally
• C-x 3: split window vertically
• M-R_ARROW / : M-L_ARROW: go to next / previous buffer
• M-q: fill current paragraph (reformat / wordwrap it), i.e. applies fill-paragraph
• M-m: jump to first non-whitespace in the current line
• M-x will allow to enter / select commands from the minibuffer (see our useful commands section below)
• C-o or F8: perform whitespace cleanup (now built-in)

Frequent Actions

• to tune the font size:
  • temporarily: use C-x C-+ to increase, C-x C-- to decrease (or press Shift then click the first mouse button to select a relevant option; or, even better, use C-mousewheel)
  • permanently: one may add in one's Emacs configuration file for example: (set-face-attribute 'default nil :height 100)
• to insert special characters (e.g. tab or newline) as raw characters in commands (e.g. in I-search or replace-string): use for example M-x quoted-insert <tab>, which is often bound (yet not in our conventions) to C-q; note that pasting a tab with the mouse in the minibuffer works as well
• to insert in the current buffer the output of a shell command: C-u then M-!: enter that shell command, whose output will be pasted at the current cursor position
• to prefix all lines of the selected region: C-x then r then t, then type the prefix then type Enter (useful for example to indent a series of lines)
• to sort alphabetically the selected region: M-x sort-lines
• to go to the matching delimiter (parenthesis, bracket, end of word, etc.): to go forward, use C-M-f, and to go backward use C-M-b
• to re-select a region (e.g. to perform multiple substitutions in a row on the same region): C-x C-x
• to abort the current entry in the minibuffer: C-g
• to perform replacements based on regular expressions: M-x replace-regexp RET regexp RET newstring RET, with this REGEXP syntax (more information); for example, to remove, in each line, all characters from the first comma: M-x replace-regexp RET ,.* RET , RET
• to open a file that is very large and/or difficult to parse/display: M-x find-file-literally

Other useful commands to trigger, possibly explicitly with M-x:

• replace-string SEARCH_PATTERN REPLACEMENT; add M-c to set the case-sensitive flag, i.e. to search for the exact string (even if it is lowercase - otherwise uppercase versions thereof will match); the M-% default shortcut requires a shift on French keyboards
• query-replace SEARCH_PATTERN REPLACEMENT
• kill-rectangle (operates on a previous selection)
• indent-region (C-M-\ difficult on French keyboards)

See also our Performing a Merge with Emacs section.

Package Managers

There are at least:

• package.el
• straight.el
• Elpaca: Async Emacs Package Manager (current state of the art, and the one on which we currently rely)

use-package is not a package manager, it is an extensible configuration macro that is specialised by most of the package managers so that it can be used with any.

Refer to this page for a comparison of package managers.

Elisp Hints

Emacs Lisp is a Lisp dialect made for Emacs.

See the GNU Emacs Lisp Reference Manual.

An Emacs init file contains a series of Lisp expressions, each of them consisting of a function name followed by arguments (expressions), all surrounded by parentheses.

For example: (setq fill-column 60) calls the function setq (set quoted) to set the variable fill-column to 60; as setq affects only the current buffer’s local value, in an initialisation file setq-default is generally preferred.

• boolean values: t stands for "true", and nil for "false"
• to display a message: (message "Hello world!")
• a leading single-quote makes a symbol a constant - otherwise it would be treated as a variable name; for example: (setq-default major-mode 'text-mode)

Elisp examples may be the following conditional setting:

(if (boundp 'coding-category-utf-8)
   (set-coding-priority '(coding-category-utf-8)))

Or the next function definition and key binding:

(defun my-split-window-func ()
 (interactive)
 (split-window-below)
 (set-window-buffer (next-window) (other-buffer)))

(global-set-key (kbd "C-x 2") #'my-split-window-func)

If needing to include a configuration file in another:

(load-file "~/elisp/foo.el")

To trigger multiple calls in a single expression, use:

(progn do-this
       do-that)

(defun func (arg1 arg2)
   "Always document your functions."
   <function body>)

(defvar var-name <the value>
   "Always document your variables.")

To concatenate filesystem elements: (file-name-concat "/tmp" "foo") results in "/tmp/foo".

Related Elisp information sources:

• Emergency Elisp
• Learn X in Y minutes Where X=Emacs Lisp
• Emacs Lisp Guide

Handling Errors

Sometimes problems arise due to older packages, for example when a new version of Emacs is used. This may be solved by removing the cache of the package manager (e.g. ~/.emacs.d/straight, ~/.emacs.d/elpaca), relaunching Emacs and waiting for its state (e.g. all related clones) to be downloaded/built again.

To investigate a problem, one may run Emacs with: emacs --debug-init.

Relying a safe, minimal, fallback Emacs

As many software ecosystems, the Emacs one tends to change/break frequently, and then one's init.el cannot be edited anymore with a functional Emacs - and the whole situation quickly degenerates in a mess.

One way of overcoming these issues is to have multiple versions of Emacs' configuration, including a very basic one that is never expected to break - just for the purpose of having at all times a base Emacs to fix the others; this is one of the purposes of our rather minimal init-myriad-base configuration, to be used that way:

$ DIR="${HOME}/.emacs.d/myriad-fallback"
$ mkdir $DIR && cd $DIR
$ ln -s $CEYLAN_MYRIAD/conf/init-myriad-base.el init.el

Then an always-available Emacs may be run with: emacs --init-directory=$DIR, which can made easily available thanks to, in one's shell configuration: alias esafe='emacs --init-directory=${HOME}/.emacs.d/myriad-fallback' (esafe standing for editor safely available).

Alternatively, such a feature can better be implemented thanks to a shell function (to rely as much as possible on a safe emacs, otherwise on gedit, otherwise on nano); see our .bashrc.basics shell file for that.