Table of Contents
Using the emacs text editor
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 thewhich
command. There is a good chance thatemacs
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
On a computer configured at LSCE, use your .\admin
account
- Use
winget
to installemacs
for Windows (optional winget details, for people who want to learn more):- Just type the folllowing, in a windows
cmd
,PowerShell
orTerminal
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 startemacs
- 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)
- 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
- Download the Complete package, except sources
Setup
installer (diffutils-2.8.7-1.exe
as of August 2024) 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 tellingemacs
where to find thediffutils
binaries it needs for comparing text files(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 2024…- diffutils-3.10 is available (released in May 2023)
- The
2.8.7-1
Win32 binaries are dated May 2004, but work perfectly fine!
emacs for Windows technical notes
Just follow exactly the windows related instructions on this page!
- Emacs and Microsoft Windows/MS-DOS (Appendix H of the The Emacs Editor manual)
- 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
C-g
(CTRL
+g
) to abort or interrupt something in emacs
e.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
meansCTRL-x
followed byCTRL-c
, and will exit emacs- Same result as using
File
⇒Quit
, just faster
C-s
meansCTRL-s
, and will Search forward- Hint: look for
Incremental Search
in the Reference Card for more information on searching!
C-g
meansCTRL-G
and will abort the current emacs command/action (e.g. exit a forward search started withC-s
)C-z
will iconify the emacs window!- Use
C-x u
(CTRL-x
followed byu
) orEdit
⇒Undo
for undoing the previous action!
M-f
meansAlt-f
(orEsc
followed byf
if the keyboard has noAlt
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
andC-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
- 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:
- 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 selectOptions
⇒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 (withemacs
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 theserver
directory (c:/Users/your_login/AppData/Roaming/.emacs.d/server
) by hand and restartemacs
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
orCascadia Code
fonts, with size12
, 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
size12
orCascadia Code
+Regular
size10
- 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 lineShift Left_Arrow
andShift Right_Arrow
: go to the beginning/end of a line
Same behavior asC-a
andC-e
, and theHome
andEnd
keyboard keysShift Up_Arrow
andShift 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 appropriatecomment 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 thetramp
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 existingmylogin_server
session defined inPuTTY
- 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 existingmylogin_server
session defined inPuTTY
- More details:
- Hint: if you use the recommended configuration file or have activated the
'(recentf-mode t)
mode, you can easily access recent files inFile
⇒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
- 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 versionsPS 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- 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 ]