Using the emacs text editor

xkcd & Real Programmers

TODO

Add a screenshot

One process, multiple windows (File ⇒ New Frame), multiple buffers

Emacs server…

Define some concepts:

frame, buffer, region

Parts of an emacs Frame (the graphical window or terminal screen occupied by Emacs is called Frame))

Menu bar

One or more windows displaying a Buffer

The last line of a window is the Mode Line that displays information about the Buffer above (e.g. file name, line/column number, editing mode, …

Echo Area or Mini Buffer, at the very bottom of the frame = Interaction field where informative messages are displayed (echo area) or where you enter information when Emacs asks for it (mini buffer)

Useful keys:

C-Z: iconify a Frame

F11: make frame fullscreen (toggle)

Automatic backup file

TAB key for auto-completion when opening files…

Using menus vs shortcuts

Key + Mouse shortcuts (e.g. CTRL+Left Mouse ⇒ Buffer Menu)

runs locally ⇒ no need for an X server

available on Linux/Win/Mac

highly customizable

splitting windows

WIN: configuring the Cascadia Code font

Installing emacs

Linux installation

Check if emacs is already installed on the Linux computer or servers you are using, e.g with the which command. There is a good chance that emacs is already available on shared servers!

$ which \emacs
/usr/bin/emacs

If emacs is not available:

On shared server: ask your local system administrators

On your Linux desktop/laptop: install the emacs package the following way

$ sudo apt install emacs
[sudo] password for your_login:
Reading package lists... Done
Building dependency tree
Reading state information... Done
emacs is already the newest version (1:26.3+1-1ubuntu2).
0 upgraded, 0 newly installed, 0 to remove and 7 not upgraded.

Mac installation

Install Aquamacs

Windows installation

emacs binaries for Windows

When installing emacs, you will need an account that can get elevated (i.e. administrator) permissions On a computer configured at LSCE, use your .\admin account

Use winget to install emacs for Windows (optional winget details, for people who want to learn more):

Just type the folllowing, in a windows cmd, PowerShell or Terminal

winget install --id GNU.Emacs

if your Windows terminal does not have elevated (i.e. administrator) permissions, a pop-up window will open and ask for confirmation

IF the automated installation with winget does not work, download the most recent Windows installer from a gnu ftp mirror

Go to a gnu emacs for windows ftp mirror

Go to the most recent emacs-XX/ folder (e.g. emacs-29/ as of August 2024)

Download the most recent emacs-XX.YY-installer.exe file (e.g. emacs-29.4-installer.exe as of August 2024) and execute it

If everything went well, you should have a new Start⇒Emacs-XX menu that you can use to start emacs

If the menu shortcuts have not been installed:

Go to the emacs binaries directory: C:\Program Files\Emacs\emacs-XX.YY\bin

Click on the addpm.exe program to (re-)run the program that will create the shortcuts (official page)

You can work with the default emacs settings, but it is highly recommended to start with a nice existing emacs configuration file (if available)

Example configuration file

Note: Emacs is installed in the C:\Program Files\Emacs\emacs-XX.YY\bin directory

Recommended EXTRA binaries for Windows

If you need to work with remote files, emacs can automatically transfer files between your local computer and remote servers, if configured properly
Extremely useful

Install PuTTY, and configure a PuTTY profile for the desired host and user combination, so that emacs can use the PuTTY plink command to connect to remote servers (and transfer files)

Do not use space characters in the predefined PuTTY profile name!

mylogin_server (e.g. me_ssh1) is OK

but mylogin server will not work

Use the plinkx method when opening a remote file with emacs: /plinkx:mylogin_server:/path/to/file

Use exactly the same profile name as an existing PuTTY profile!

More details in

If you need to use the emacs ediff mode to compare text files
Very useful

Install the Windows version of Gnu diffutils

Can be installed with winget: winget install --id=GnuWin32.DiffUtils -e

Otherwise, download the Complete package, except sources Setup installer (diffutils-2.8.7-1.exe as of August 2025) from https://gnuwin32.sourceforge.net/packages/diffutils.htm and execute the installer

This will install the required binaries and reources in C:\Program Files (x86)\GnuWin32\

If you use the recommended .emacs configuration file, it should already include the following section telling emacs where to find the diffutils binaries it needs for comparing text files
…Otherwise add these lines to your .emacs file

(when (eq window-system 'w32)
(setq exec-path (append exec-path '("C:\\Program Files (x86)\\GnuWin32\\bin")))
)

Check if there is a recent compiled for Windows version of diffutils
As of August 2025…

diffutils-3.12 sources are available (released in April 2025)

Only the 2.8.7-1 Win32 binaries are available (dated May 2004), but work perfectly fine!

emacs for Windows technical notes

These notes are only here for finding them easily, but you probably don't need them. Just follow exactly the windows related instructions on this page!

Emacs and Microsoft Windows/MS-DOS (Appendix H of the The Emacs Editor manual)

GNU Emacs FAQ for MS Windows

Extra Windows specific information (optional, read only if you need it): GNU Emacs FAQ for MS Windows

Launching emacs

Linux launch

emacs some_text_file &

or just emacs &

error type if there is no X server, and option for forcing text mode (i.e NO GUI)

Windows launch

Start ⇒ E ⇒ Emacs-XX.Y ⇒ Emacs

Mac launch

Using (and learning) emacs

Use C-g (CTRL+g) to abort or interrupt something in emacse.g. When you are searching forward with C-s, type C-g to exit the search

All the common functions of emacs are available from the pull-down menus at the top, but the real power comes from knowing (a few of) the keyboard shortcuts!

Understanding keyboard shortcuts:

C-x C-c means CTRL-x followed by CTRL-c, and will exit emacs

Same result as using File⇒Quit, just faster

C-s means CTRL-s, and will Search forward

Hint: look for Incremental Search in the Reference Card for more information on searching!

C-g means CTRL-G and will abort the current emacs command/action (e.g. exit a forward search started with C-s)

C-z will iconify the emacs window!

Use C-x u (CTRL-x followed by u) or Edit⇒Undo for undoing the previous action!

M-f means Alt-f (or Esc followed by f if the keyboard has no Alt key), and will Move forward a word

Bonus! Many emacs shortcuts can be used in the shell or in Python, and will also make it possible to use emacs in text mode (if you get lost on a remote server without graphics…)

e.g. C-A and C-E to go to the beginning and end of a line

Copy-Cut-Paste

With a mouse: the usual Linux copy/paste behavior works:

Select and Copy text (at the same time) with the left button

Paste text with the middle button

Delete/Cut text (requires some practice): left-click at the beginning of the text you want to cut, then double-right-click at the end of the text

Using keyboard shortcuts

More stuff

The official Guided Tour of Emacs is a nice web page quickly detailing the major concepts (buffer, region, mark, …) and shortcuts
You can read this page, and later find some time for following the builtin tutorial (details below)

Built-in emacs tutorial, highly recommended! Spend one hour in the tutorial, and save hundreds of hours in the rest of your life!

Help⇒Emacs Tutorial

or Help⇒Emacs Tutorial (choose language)…

Reference cards, available in several languages

The Reference Card and the Survival Card mostly have the same content, just formatted a bit differently. The Reference Card is easier to read.

Emacs 21 Reference Card annotated by JYP (most useful shortcuts for beginners): emacs_jyp.pdf

Other reference cards:

EmacsWiki Reference Sheet by Aaron Hawley (html)

emacs reference card by Mitch Richling (2 page pdf)

Misc documentation:

Regular expressions: Regular expressions, Reg exp help

emacs configuration file

The configuration file is officially known as the Emacs Initialization File (or just init file)

The configuration file (and most of the emacs Packages) is written in Emacs Lisp

You can perfectly survive without knowing anything about lisp! Just don't forget opening and closing parentheses (( and )) when copy/pasting settings you find on the web, and remember that comments start with a ; character

The settings changed with the Options menu appear at the end of the configuration file

Setting are defined in the custom-set-XXXX variables, if you don't forget to select Options⇒Save Options

The easiest way to take changes into account is to restart emacs

Location of the configuration file

Configuration file name: .emacs

emacs knows (of course) where its .emacs configuration file is located! You can open the configuration file just by typing C-x C-f ~/.emacs and you can then check how your Home folder (~/) has been expanded

Related emacs (configuration) files and folders (e.g. .emacs.d/ folder) are located in the same place as the main configuration file

Linux:
~/.emacs: i.e. .emacs (dot-emacs) file in the current user's Home directory

Windows:
If you want to access the emacs configuration files and folders, you will need to be able to see hidden folders and files!

Windows style path: c:\Users\your_login\AppData\Roaming\.emacs

Linux style path: c:/Users/your_login/AppData/Roaming/.emacs (or just ~/.emacs)

Mac

Example configuration file

Recommended emacs configuration file

Download this emacs_jyp_yyyy-mm-dd.txt file to the appropriate configuration directory (for your system)

Copy the emacs_jyp_yyyy-mm-dd.txt file to .emacs

You can possibly edit the .emacs file (with emacs or another editor) to make some changes, but it should theoretically work as is

MS Windows specific section should automatically be executed only on Windows computer, and you don't have to comment them out by hand. You can find them by looking for the following strings: Microsoft, MS, w32

(re)start emacs to take changes made to the .emacs file into account

On MS Windows: if emacs displays the following error message, just create the server directory (c:/Users/your_login/AppData/Roaming/.emacs.d/server) by hand and restart emacs

Warning (initialization): An error occurred while loading ‘c:/Users/your_login/AppData/Roaming/.emacs’:
File is missing: Opening output file, No such file or directory, c:/Users/your_login/AppData/Roaming/.emacs.d/server/server

You may want to change the default font defined in the recommended configuration file, depending on the fonts available on the computer/server where emacs is running, the size of your screen, etc…

The recommended configuration file will probably use the Consolas or Cascadia Code fonts, with size 12, available on Windows.

Changing the default font:

Options⇒Set Default Font…

Select a font and size

Linux: DejaVu Sans Mono, size 12

Windows: Consolas+Normal size 12 or Cascadia Code+Regular size 10

Note: the Cascadia Code font is only available after installing Windows Terminal

Mac:

Options⇒Save Options

Keyboard shortcuts defined by the example configuration file

C-x C-g: go to a specific line

Shift Left_Arrow and Shift Right_Arrow: go to the beginning/end of a line
Same behavior as C-a and C-e, and the Home and End keyboard keys

Shift Up_Arrow and Shift Down_Arrow: go to the beginning/end of the buffer

Function keys

F1: Undo (lots of undos!!)

F2: Search and Replace

Look for Query Replace in the Reference Card to determine what you can do when a match is found

…or read Query Replace page

F3: fill-paragraph (i.e. automatically re-indent text or comments)

F4: indent the selected region (if indenting makes sense for the current buffer mode)

F5: comment out the selected region (comment style depends on the current buffer mode)

M-; can be used for commenting and un-commenting

F12: Repeat complex command (e.g. restart a previous query-replace operation)

Useful shortcuts

M-;: comment out selected lines
This will automatically use the appropriate comment character for the current buffer mode, e.g. # for a Python script

Working with remote text files

Prerequisite

Using the tramp mode

If you use the syntax below when opening a file (C-x C-f), emacs will automatically use the tramp mode to:

copy the remote text file (with scp) to your computer when you open it, so that you can edit the file locally

copy the edited text file (with scp) back to its original remote location when you save it (C-x C-s)

Opening a file on a remote server that you can reach directly:

/ssh:mylogin@server:/path/file

e.g. /ssh:mylogin@ssh1.lsce.ipsl.fr:/home/users/mylogin/my_script.py

Or /plinkx:mylogin_server:/path/file on MS Windows, with an existing mylogin_server session defined in PuTTY

Opening a file on a remote server than you can only access through a gateway (e.g. file in a supercomputing center):

/ssh:user_A@gateway|ssh:user_B@target_server:/path/file

e.g. /ssh:mylogin@ssh1.lsce.ipsl.fr|ssh:user_B@target_server:/path/file

Or /plinkx:mylogin_server|ssh:user_B@target_server:/path/file on MS Windows, with an existing mylogin_server session defined in PuTTY

More details:

The NEW (Emacs 24.3+) ad-hoc multi-hop syntax

Hint: if you use the recommended configuration file or have activated the '(recentf-mode t) mode, you can easily access recent files in File⇒Open Recent without having to type the full access path again!

More: tramp mode on EmacsWiki and tramp user manual

Troubleshooting...

The tramp mode is quite complex and relies on connections to one or more remote computers using external programs and protocols. You may have to experiment a bit till you find the correct syntax and inline method to work with a particular remote server. Make sure you have read the prerequisite section!

Buffer ⇒ *Messages*

If you get stuck (emacs is not responding), there is pr

Try aborting the current emacs command by typing C-g

Having fun with emacs

Use the built-in psychotherapist to solve your scientific problems (with M-x doctor). See also Fun and Games in Emacs

I am the psychotherapist. Please, describe your problems. Each time
you are finished talking, type RET twice.
My climate model does not work
Why do you say your climate model does not work?
I get wrong results
Is it because of your plans that you say you get wrong results?

emacs documentation

EmacsWiki

The Emacs Editor (the official manual)

Other official related GNU Emacs Manuals

Emacs hacking by Nicolas Rougier

Updating emacs

Linux

Mac

Windows

winget list returns a result, after installing Emacs 30.1, so it is possible that winget upgrade will work, at last! > winget list --id GNU.Emacs Nom ID Version Disponible Source -------------------------------------------------- GNU Emacs 30.1 GNU.Emacs Unknown 30.1 winget

Using winget upgrade for updating emacs on Windows unfortunately does not work yet (August 2024). The easiest way to update Emacs is:

Check the version of the installed Emacs

In the Start menu: Start ⇒ E ⇒ Emacs-version (e.g. Emacs 29.3)

In a running Emacs: Help menu ⇒ About Emacs

or M-x version

Use winget show in a PowerShell to determine (all) the available versions

PS C:> winget show --id GNU.Emacs --versions
Found GNU Emacs [GNU.Emacs]
Version
-------
29.4
29.3
29.2
[...]

If you want/need to update Emacs

Make sure Emacs it is not running

Uninstall it with: Start ⇒ E ⇒ Emacs-version ⇒ Uninstall

Your emacs configuration file and other files you have installed will not be removed!

This will remove the C:\Program Files\Emacs directory and its content

Slight bug: this will not remove the shortcuts from the Start menu

e.g. If you uninstalled emacs 29.3 and installed emacs 29.4, you will end up with the following Start Menu:

Just go to the C:\Users\your_login\AppData\Roaming\Microsoft\Windows\Start Menu\Programs directory and remove the old menu/directory (e.g. Emacs-29.3)

Perform a new Emacs for Windows installation

[ PMIP3 Wiki Home ] - [ Help! ] - [ Wiki syntax ]