Emacs: Difference between revisions

From ArchWiki
(add)
(→‎Configuration: Fix spacing)
 
(341 intermediate revisions by 87 users not shown)
Line 1: Line 1:
[[Category:Text editors]]
[[Category:Text editors]]
[[sr:Emacs]]
[[Category:Console applications]]
[[zh-CN:Emacs]]
[[Category:GNU]]
{{Article summary start|Summary}}
[[de:Emacs]]
{{Article summary text|Tutorial on acquiring and using the Emacs text editor.}}
[[es:Emacs]]
{{Article summary end}}
[[fr:Emacs]]
 
[[ja:Emacs]]
[[Wikipedia:Emacs|Emacs]] is the extensible, customizable, self-documenting real-time display editor. At the core of Emacs lies an [[Wikipedia:Emacs Lisp|Emacs Lisp]] interpreter, the language in which the majority of Emacs' built-in functionality and extensions are implemented. GTK is the default X toolkit used as of GNU Emacs 22, though it functions equally well within a CLI environment.  The text-editing capabilities of Emacs are often compared to that of [[vim]].
[[pt:Emacs]]
[[Wikipedia:Emacs|Emacs]] is an extensible, customizable, self-documenting real-time display editor. At the core of Emacs lies an [[Wikipedia:Emacs Lisp|Emacs Lisp]] interpreter, the language in which the majority of Emacs' built-in functionality and extensions are implemented. GNU Emacs uses GTK as its X toolkit, though it functions equally well within a CLI environment.


== Installation ==
== Installation ==
Emacs comes in several variants (sometimes referred to as ''emacsen''). The most common of these is [http://www.gnu.org/software/emacs/ GNU Emacs].


[[pacman|Install]] {{Pkg|emacs}}, available in the [[Official Repositories]].
[[Install]] one of the following packages:


Another common variant is {{Pkg|xemacs}}.
* {{Pkg|emacs}} - stable release,
* {{Pkg|emacs-nativecomp}} - with [https://www.emacswiki.org/emacs/GccEmacs native compilation] enabled,
* {{Pkg|emacs-nox}} - without X11 support,
* {{Pkg|emacs-wayland}} - with native compilation and PGTK enabled.


== Quick Start ==
Other variants can be searched for, as an example {{AUR|emacs-git}} provides the development branch of GNU Emacs.
Although Emacs is complex, it will not take long to begin to understand the benefits which the level of customization and extensibility bring. Furthermore, the comprehensive variety of extensions already available allows  it to be transformed into a powerful environment for almost any form of text-editing.


Emacs has an excellent built-in tutorial which can be accessed by clicking the first link on the splash screen; by selecting ''Help->Emacs Tutorial'' from the menu or by pressing 'F1' followed by 't'.  This page is designed to be an additional resource for getting started with Emacs.
== Usage ==


Emacs also includes a set of reference cards, useful for beginners and experts alike, see {{ic|/usr/share/emacs/<version>/etc/refcards/}} (substitute <version> for your version of emacs).
Before launching emacs, you should know how to close it (especially if you run it in a terminal): use the
{{ic|Ctrl+x}}{{ic|Ctrl+c}} key sequence.


===Running Emacs===
====Normal way====
To start Emacs run:
To start Emacs run:


Line 31: Line 32:


  $ emacs -nw
  $ emacs -nw
or, for fast loading (no .emacs) and editing within CLI:
$ emacs -Q -nw
If you installed the nox version, {{ic|emacs}} and {{ic|emacs -nw}} will be the same.


A file name can also be provided to open that file immediately:
A file name can also be provided to open that file immediately:
Line 36: Line 43:
  $ emacs filename.txt
  $ emacs filename.txt


====As a daemon====
=== No colors ===
Emacs can take some time to start since it has to load the .emacs file each time. Since version 23, Emacs is capable to run as a daemon to which users can connect. To run Emacs as a daemon:


  $ emacs --daemon
By default, Emacs starts with a color theme showing hyperlinks in dark blue. To start Emacs on a text terminal without any color theme or scheme:
 
  $ emacs -nw --color=no
 
This will cause all text to appear in the foreground color of the terminal — normally white text on a black background, or black text on a white background.


You are likely to start the daemon at startup time and to connect a window to the daemon. Besides, it is possible to connect ''both'' graphical and console clients to the daemon at the same time and make the GUI to start quickly.
=== As a daemon ===


If you want to connect to the daemon simply use the folowing command (note that it will start a graphical client if called in a graphical environment or a console client if called in a console like a tty):
In order to avoid reloading the Emacs configuration file every time Emacs starts, you can run Emacs as a daemon:


  $ emacsclient
  $ emacs --daemon


If you still want a console client no matter you are in a graphical environment then use:
You may then connect to the daemon by running:  


  $ emacsclient -t
  $ emacsclient -nc


Furthermore, you can add the {{ic|-a ""}} parameter.
Which creates a new frame {{ic|-c}} (use {{ic|-t}} if you prefer to use it in the terminal) and does not hog the terminal {{ic|-n}} ({{ic|--no-wait}}).
Now, the first time you call the command, it will start emacs as a daemon, so that it remains running in background to improve startup time for future calls (and to remember buffers as well).
Note that some programs such as Mutt or Git (for commit messages) wait for the editor to finish, so you cannot use the {{ic|-n}} parameter.
If your default editor is set to use it, you will have to specify an alternate editor (''e.g.'' {{ic|emacsclient -a "" -t}}) for those programs.


In the end, you could use the following alias:
=== As a systemd unit ===


$ alias emacs='emacsclient -t -a ""'
A systemd unit is included in Emacs 26.1. The unit is installed with Emacs, but it must be [[enabled]] as a [[user unit]] (not a system-wide) after installing Emacs.


With xfce, if you want to tell it to use emacsclient -c instead of emacs %f when opening a new file, you can change your /usr/share/applications/emacs.desktop and change the line
After the service is started, Emacs is ready.  


$ Exec=emacs %f
If you want to be able to start graphical emacs frames through {{ic|emacsclient}} on Wayland, a specific [[drop-in snippet]] is needed, as shown in [https://www.emacswiki.org/emacs/EmacsAsDaemon#h5o-17 EmacsWiki].


To
Note that systemd user units do not inherit environment variables from a login shell (like {{ic|~/.bash_profile}}). See [[Systemd/User#Environment variables]] for more information.


$ Exec=emacsclient -c
If you start emacs as a daemon, you may want to set the {{ic|VISUAL}} and {{ic|EDITOR}} environment variables to {{ic|emacsclient}} so that programs that start an editor use emacsclient instead of starting a new full instance of the editor. Programs that use an external editor include email programs (for editing the message), Git (for editing the commit message), and less (the {{ic|v}} command for editing the displayed file). Do not use the {{ic|-n}} ({{ic|--nowait}}) option to emacsclient, since programs typically expect editing to be finished when the editor exits.


This way, a client will be called each time you open up a file and so be very fast!
It is also recommended to change any GUI start menu entries (or equivalent) for Emacs to point to emacsclient instead of emacs, so that the emacs daemon is used instead of starting a new emacs process.


===Basic terminology and convention===
== Getting help ==
Emacs uses some terminology and conventions which may seem unusual at first and will be introduced where appropriate.  However, there is some terminology which should be introduced before-hand, as it is fundamental to working with Emacs.


The one piece of terminology which must be introduced early is the concept of ''buffers''.  A buffer is a representation of data within Emacs.  For example, when a file is opened in Emacs, that file is read from disk and its contents stored in a buffer, which allows it to be edited and saved back to disk later.  Buffers are not limited to text, and can also contain images and widgets.  Work is in progress to allow buffers to even display applications!  Another way to think of it: data available on disk is referred to as a 'file', whereas data available in Emacs is referred to as a 'buffer'.
Emacs has a built-in tutorial which can be accessed by clicking the first link on the splash screen and selecting ''Help>Emacs Tutorial'' from the menu or by pressing {{ic|C-h t}}.


The convention for key sequences in Emacs may be unfamiliar.  Namely:
To read the tutorial in a language other than english, use the command {{ic|Alt x}}, and enter {{ic|help-with-tutorial-spec-language}}


'''C-x''' refers to Control-x
Emacs is self-documenting by design. As such, a great deal of information is available to determine the name of a specific command or its keybinding, for example. See all contextual help bindings with {{ic|C-h C-h}}.


'''M-x''' refers to Meta-x
Emacs also includes a set of reference cards, useful for beginners and experts alike, see {{ic|/usr/share/emacs/''version''/etc/refcards/}}.


{{Note|'Meta' corresponds to the Alt key in most cases.  Alternatively, the Esc key can be used.}}
=== The manuals ===


For example, to exit Emacs use the following key sequence: '''C-x C-c'''.  This can be read as "Hold Control and press 'x'.  Release.  Hold Control and press 'c'."  Although Emacs provides a menu bar, it is recommended practise to focus on learning the key sequences.  This guide will refer to keybindings with the convention used in Emacs from now on.
If you really want to master Emacs, the most recommended source of documentation remains the official manuals:


===Movement===
* Emacs: the complete Emacs user manual.
Cursor movement is very similar to other graphical editors.  The mouse and arrow keys can be used to change the position of the cursor (referred to as ''point'' in Emacs). The standard movement commands performed by the arrow keys also have more accessible bindings in Emacs. To move forward one character, use '''C-f''' and to move one character backward, '''C-b'''.  '''C-n''' and '''C-p''' can be used to move to the next and previous lines, respectively. Again, it is generally recommended to use these key-sequences in preference to the mouse and/or arrow keys.
* Emacs FAQ.
* Emacs Lisp Intro: if you never used any programming language before.
* Elisp: if you are already familiar with a programming language.


As might be expected, Emacs provides more advanced movement commands, including moving by word and sentence.  '''M-f''' moves forward one word and '''M-b''' will move point one word backward. Similarly, '''M-e''' moves point one sentence forward and '''M-a''' one sentence backward.
You can access them as PDFs from [https://www.gnu.org/software/emacs/manual/ GNU.org] or directly from Emacs itself thanks to the embedded 'info' reader: {{ic|C-h i}}. Press {{ic|m}} to choose a book.


Until now, all of the movement commands introduced have been relative to point.  '''M-<''' can be used to move point to the beginning of the buffer, with its counterpart, '''M->''', moving to the end of the buffer. To move point to a specific line number, use '''M-g g'''. '''M-g g''' will prompt for the desired line number.  Also, to move to the start or end of the current line, use '''C-a''' or '''C-e''', respectively.
Some users prefer to read books using 'info' because of its convenient shortcuts, its paragraphs adapting to window width and the font adapted to current screen resolution. Some find it less irritating to the eyes. Finally you can easily copy content from the book to any Emacs buffer, and you can even execute Lisp code snippets directly from the examples.


{{Note|Keybindings for these commands, or indeed any command, may differ ''slightly'' depending on which modes are currently active.  However, it is unusual for the replacement command not to provide equivalent functionality.   See [[Emacs#Modes|Modes]] for more information.}}
You may want to read the '''Info''' book to know more about it: {{ic|C-h i m info <RET>}}.
Press {{ic|?}} while in info mode for a quick list of shortcuts.


===Files and buffers===
== Configuration ==
Emacs provides a series of commands to act upon files, the most common of which will be detailed here.  '''C-x C-f''' is used to open a file (this command is called 'find-file' in Emacs).  Should the file specified not exist, Emacs will open an empty buffer.  Saving a buffer will create the file with the buffer's contents.  '''C-x C-s''' can be used to save a buffer.  To save a buffer with a different filename, use '''C-x C-w''' (this is a mnemonic for the command 'write-file'), which will prompt for the new filename before writing it to disk.  It is also possible to ensure all buffers are saved with '''C-x s''', which, should a buffer be modified since its last save, a prompt will be displayed asking which action to take.


{{Note|'''C-x C-f''' does not read the file from disk again if a buffer corresponding to the file is still opened.  To re-read the file from disk, kill the buffer ('''C-x k''') prior to '''C-x C-f''' or use '''M-x revert-buffer'''.}}
One of Emacs's main features is its extensibility and the ease of configuration. Emacs has a built-in customization engine. You can do {{ic|M-x customize}} which displays a list of customization options. For how to use this interface, see the Easy Customization info node: {{ic|(info "(emacs) Easy Customization")}}. You can set customization opens just for one Emacs session or save them into a configuration file so that they are saved across Emacs sessions. Note that this is what the customization interface does if you select ''Apply and Save''.


Many interactive commands such as "find-file" or "write-file" prompt for input in the bottom-most line of the Emacs window. This line is referred to as the ''minibuffer''. The minibuffer supports many basic editing commands as well as tab-completion similar to that which is available in many *nix shells. '''<TAB>''' can be pressed twice in succession to display a list of completions, and if desired, the mouse can be also be used to select a completion from that list. Completion in the minibuffer is available for many forms of input including commands and filenames.
When Emacs is started, it normally tries to load a Lisp program from an "initialization file", or "init file" for short. This file, if it exists, specifies how to initialize Emacs for you. Emacs looks for your init file at {{ic|~/.emacs}}, {{ic|~/.emacs.el}}, {{ic|~/.emacs.d/init.el}}, or {{ic|~/.config/emacs/init.el}}. See the info node "Init File" for more: {{ic| (info "(emacs) Init File")}}


The minibuffer also provides a history feature.  The previous items entered for a command can be recalled using the '''Up Arrow''' or '''C-p'''.
== Tips and tricks ==


To exit the minibuffer at any time, press '''C-g'''.
=== TRAMP ===


After opening several files, a way to switch between them is needed.  Opening a file corresponding to a buffer already available in Emacs, will cause Emacs to switch to that buffer. But this is not the most effective way.  Emacs provides '''C-x b''', which prompts for the new buffer to be displayed (tab-completion is available here).  By entering the name of a buffer which does not exist, a new buffer with that name will be created.
TRAMP (Transparent Remote Access, Multiple Protocols) is an extension which, as its name suggests, provides transparent access to remote files across a number of protocols. When prompted for a filename, entering a specific form will invoke TRAMP. Some examples:


{{Note|To switch to the previous buffer use '''C-x b <RET>''', as the previous buffer is the default.}}
To prompt for the root password before opening {{ic|/etc/hosts}} with root permissions:


A list of all open buffers can be displayed using '''C-x C-b'''.  Should a buffer no longer be required, it can be removed with '''C-x k'''.
C-x C-f /sudo::/etc/hosts


===Editing===
To connect to 'remotehost' as 'you' via SSH and open the file {{ic|~/example.txt}}:
Many editing commands exist within Emacs.  Perhaps the most important command which has not yet been introduced is 'undo', which can be performed via '''C-_''' or '''C-/'''.  Movement commands generally also have a corresponding delete command.  For example, '''M-<backspace>''' can be used to delete a word backwards, and '''M-d''' to delete a word forwards.  To delete to the end of the line, or the end of the sentence, use '''C-k''' or '''M-k''', respectively.


It is a rule-of-thumb that no line be allowed to exceed 80 characters.  This aids readability, especially in cases where the line wraps at the edge of a window.  Automatically inserting (or removing) line separator(s) is known as ''filling'' in Emacs.  A paragraph can be filled using '''M-q'''.
C-x C-f /ssh:you@remotehost:~/example.txt


Characters and words can be transposed using '''C-t''' and '''M-t''', respectively.  For example: <code>Hello World!</code> → <code>World! Hello</code>
The path for TRAMP is typically of the form '/[protocol]:[[user@]host]:<file>'.


The case of words is also readily adjustable.  '''M-l''' downcases a word from point (<code>HELLO</code> → <code>hello</code>); '''M-u''' upcases a word from point (<code>hello</code> → <code>HELLO</code>) and '''M-c''' capitalizes the first character of a word from point while downcasing the remainder (<code>hElLo</code> → <code>Hello</code>).
To connect to 'myhost' as 'you' and edit {{ic|/etc/hosts}} with ''sudo'':


===Killing, yanking and regions===
  /ssh:you@remotehost|sudo:remotehost:/etc/hosts
A region is a section of text between two positions. One of those positions is referred to as ''mark'', and the other is point.  '''C-<SPC>''' is used to set the position of mark, after which point can be moved to create a region.  Within GNU Emacs 23.1 onwards, this region is visible by default.  There are a number of commands which act upon regions, among the most commonly used are ''killing'' commands.


In Emacs, cut and paste are referred to as ''kill'' and ''yank'', respectively.  Many commands which delete more than one character (including many of those in the above section, such as '''C-k''' and '''M-d''') actually cut the text and append it to what is known as the ''kill-ring''.  The kill-ring is simply a list of killed text.  The kill-ring stores up to the last 60 kills by default.  Successive kills are concatenated and stored at the head of the list.
TRAMP supports much more than the examples above might indicate. For more information refer to the TRAMP info manual, which is distributed with Emacs.


'''C-w''' and '''M-w''' can be used to kill and copy a region, respectively.
=== Using Emacs as git mergetool ===


To insert killed text into a buffer (known as 'yanking'), use '''C-y'''.  '''C-y''' can be used multiple times in succession to yank text repeatedly. As mentioned, previous kills are stored in a list, however '''C-y''' only retrieves the first of them. The earlier kills can be accessed via '''M-y'''.  This will remove the text inserted by 'yank' initially, replacing it with the text killed earlier. '''M-y''' must be used immediately following '''C-y''' and can be used in many times succession to cycle through the kill-ring.
By default, Git provides support for using Emacs' Emerge mode as a merge tool. However you may prefer the Ediff mode. Unfortunately this mode is not supported by git for technical reasons. There is still a way to use it by evaluating some elisp code upon emacs call.


===Search and replace===
{{hc|.gitconfig|<nowiki>
Searching for a string is common practise in text-editing.  This can be performed using '''C-s''' (to search forward) or '''C-r''' (to search backward).  These commands prompt for the string for which to search.  Searching is performed incrementally, and so it will match the next (or previous) occurrence as you type.  To move to the next or previous match, press '''C-s''' or '''C-r''' again, respectively.  Once a match has been found, '''<RET>''' can be used to end the search.  Alternatively, should you wish to return to the location you initiated the search, use '''C-g'''.
[mergetool.ediff]
    cmd = emacs --eval \" (progn (defun ediff-write-merge-buffer () (let ((file ediff-merge-store-file)) (set-buffer ediff-buffer-C) (write-region (point-min) (point-max) file) (message \\\"Merge buffer saved in: %s\\\" file) (set-buffer-modified-p nil) (sit-for 1))) (setq ediff-quit-hook 'kill-emacs ediff-quit-merge-hook 'ediff-write-merge-buffer) (ediff-merge-files-with-ancestor \\\"$LOCAL\\\" \\\"$REMOTE\\\" \\\"$BASE\\\" nil \\\"$MERGED\\\"))\"


Once a search is completed (i.e., was not aborted with '''C-g''' or similar), the string which was searched for will be the default for any following search.  To make use of this, press '''C-s C-s''' or '''C-r C-r''' to search forward or backward again, respectively.
[merge]
tool = ediff
</nowiki>}}


Regular Expression searches behave identically to the searching described above except for the command to initiate the search.  Use '''C-M-s''' or '''C-M-r''' to initiate a regexp search forward or backward, respectively. Once a Regular Expression search has commenced, '''C-s''' and '''C-r''' can be used to search forward or backward, just as with string searches.
Note that the command has to be on a single line.
In the above example, we launch a new instance of Emacs. You might want to use emacsclient for quicker startup; it is not recommended though since the Ediff call is not really clean: it could mess with your current Emacs session.


In addition to searching, it is also possible to perform string and regular expression replacement (via '''M-%''' and '''C-M-%''', respectively). Prompts are provided for both the initial and replacement text, and then another prompt for the action to perform on the highlighted match.  Although many options are available (the full list is available by pressing '''?'''), the most commonly used are '''y''', to perform replacement, '''n''', to skip this match, and '''!''' to replace this, and all following matches.
If you want an instant startup you can use the {{ic|-q}} parameter. If you want to launch Emacs quickly while preserving at least a part of your configuration, you can call Emacs with


===Indentation and prefix arguments===
emacs -q -l ~/.emacs-light
Indentation is usually performed with either '''<TAB>''', to indent a single line, or with '''C-M-\''', to indent a region.


Exactly how text is indented usually depends on the ''major-mode'' which is active.  Major-modes often define indentation styles specialising in indenting a certain type of text.  (See [[Emacs#Modes|Modes]] for more information.)
where the light configuration file loads only what you need for Ediff.


In some cases, a suitable major-mode may not exist for a file type, in which case, manual indentation may be necessary. Create a region (see [[Emacs#Killing, yanking and regions|Killing, yanking and regions]]) then perform indentation with '''C-u <n> C-x <TAB>''' (where '<n>' is the number of columns which the text within the region should be indented). For example:
See [https://web.archive.org/web/20090210145607/http://kerneltrap.org/mailarchive/git/2007/7/1/250424 kerneltrap.org] and [https://stackoverflow.com/questions/1817370/using-ediff-as-git-mergetool stackoverflow] for more details on this trick and the Ediff issue.


Increase the region's indentation by four columns:
=== Using Caps Lock as Control key ===


C-u 4 C-x <TAB>
Some users like this behavior to avoid the so-called "emacs pinky". If you want to try it on X, just run


Decrease the region's indentation by two columns.
$ setxkbmap -option 'ctrl:nocaps'


C-u -2 C-x <TAB>
Alternatively, to '''swap''' these keys, run


{{Note|The trick behind this is '''C-u''', which corresponds to the 'universal-argument' command. Providing a 'universal-argument' is a way to provide more information to a command (this information is referred to as a 'prefix argument').  In this case, we provided the amount of indentation desired to the command invoked by '''C-x <TAB>'''. Without providing an argument, '''C-x <TAB>''' will only increase indentation by 1 column.}}
  $ setxkbmap -option 'ctrl:swapcaps'


===Windows and frames===
To set this permanently, consider adding it to your {{ic|.xinitrc}} file.  
Emacs is designed for convenient editing of many files at a time. This is achieved by dividing the Emacs interface into three levels.  Namely, buffers, which have already been introduced, as well as ''windows'' and ''frames''.


A ''window'' is a viewport used for displaying a buffer.  A window can display only one buffer at a time, however one buffer can be displayed in many windows.  Beneath each window exists a ''mode-line'', which displays information for that buffer.
Now, if you ever need to uppercase a region, just use the default {{ic|C-x C-u}} keybinding, which calls the {{ic|upcase-region}} function.


A ''frame'' is an Emacs "window" (in standard terminology. i.e., 'window' in the sense of the modern desktop paradigm) which contains a title bar, menu bar and one or more 'windows' (in Emacs terminology.  i.e., the above definition of 'window').
See [http://ergoemacs.org/emacs/swap_CapsLock_Ctrl.html] for an alternative approach.


From now on the definition of these terms as they exist in Emacs will be used.
If you are missing your Caps Lock function, map it as both "Shift" at same time.


To split the window vertically or horizontally, use '''C-x 2''' or '''C-x 3''', respectively.  This has the effect of creating another window in the current frame. To cycle between multiple windows, use '''C-x o'''.
  $ setxkbmap -option "shift:both_capslock"


The opposite of splitting a window, is deleting it. To delete the current window, use '''C-x 0''' and '''C-x 1''' to delete all windows except the current.
Some desktop environments include graphical tools to simplify keyboard remappings. For example, in [[Plasma|Plasma 5]] open System Settings and click on Input Devices. Select Keyboard and in the Advanced tab you will find the setting Caps Lock behaviour under which you can select Caps Lock is also a Ctrl.


As with windows, it is also possible to create and delete frames.  '''C-x 5 2''' creates a frame.  With '''C-x 5 0''' to delete the current frame and '''C-x 5 1''' to delete all except the current frame.
=== Multiplexing emacs and emacsclient ===


{{Note|These commands do not affect buffers.  For example, deleting a window does not kill the buffer it displays.}}
Opening a new file in the same {{ic|emacs-session}} requires the use of {{ic|emacsclient}}. {{ic|emacs}} command can be itself wrapped to do the smarter job to open the file if the session exists.


===Getting help===
To start session you need to {{ic|start-server}}. This snippet will create server in first session of emacs. Add this to your {{ic|emacs}} configuration file.
Emacs is self-documenting by design. As such, a great deal of information is available to determine the name of a specific command or its keybinding, for example. The following is a listing of some of the most helpful of these:


'''C-h t'''        Start the Emacs tutorial
{{hc|.emacs or .emacs.d/init.el|
(require 'server)
'''C-h b'''        List all active keybindings
(unless (server-running-p)
  (server-start))
'''C-h k'''        Find which command a key is bound to
}}
'''C-h w'''        Find which key(s) a command is bound to
'''C-h a'''        Find a command matching a description
'''C-h m'''        Display information regarding the currently active modes
'''C-h f'''        Describe the given function


===Modes===
Shell alias method is not adequate for this since you also need to pass variables or start the independent session of your own. Add this to the {{ic|.bashrc}} or any rc file of your shell. This will make your {{ic|emacs}} command behave like emacsclient if the argument is passed.
An Emacs mode is an extension written in Emacs Lisp that controls the behaviour of the buffer it is attached to. Usually it provides indentation, syntax highlighting and keybindings for editing that form of text. Sophisticated modes can turn Emacs into a full-fledged IDE (Integrated Development Environment). Emacs will generally use a file's extension to determine which mode should be loaded.


Useful modes for editing shell scripts are sh-mode, line-number-mode and column-number-mode. They can be used in parallel and are invoked by:
{{bc|<nowiki>
function emacs {
    if [[ $# -eq 0 ]]; then
        /usr/bin/emacs # "emacs" is function, will cause recursion
        return
    fi
    args=($*)
    for ((i=0; i <= ${#args}; i++)); do
        local a=${args[i]}
        # NOTE: -c for creating new frame
        if [[ ${a:0:1} == '-' && ${a} != '-c' && ${a} != '--' ]]; then
            /usr/bin/emacs ${args[*]}
            return
        fi
    done
    setsid emacsclient -n -a /usr/bin/emacs ${args[*]}
}
</nowiki>}}


'''M-x sh-mode <RET>'''
If you want to run it in a new session just do {{ic|emacs ''file'' -}}.


'''M-x column-number-mode <RET>'''
=== Multiple configurations ===


line-number-mode is enabled by default, though, it can be toggled on/off by issuing the command again:
You can use several configurations and tell Emacs to load one or the other.


'''M-x line-number-mode <RET>'''
For example, let us define two configuration files.


sh-mode is a ''major-mode''. Major-modes adjust Emacs, and often also provide a specialised set of commands, for editing a particular type of text. Only one major-mode can be active in each buffer. In addition to syntax highlighting, and indentation support, sh-mode defines several commands to help write shell scripts. The following shows a few of those commands:
{{hc|.emacs|
(load "~/.emacs.d/main" nil t)
(load "~/.emacs.d/functions" nil t)
(load "~/.emacs.d/modes" nil t)
(load "~/.emacs.d/plugins" nil t)
(load "~/.emacs.d/theme" nil t)
}}


  '''C-c (''' Insert a function definition
This is the full configuration we load for the daemon. But the ''plugins'' file is huge and slow to load. If we want to spawn a new Emacs instance that does not need the ''plugins'' features, it can be cumbersome to load it every time in the long run.
'''C-c C-f''' Insert a 'for' loop
'''C-c TAB''' Insert an 'if' statement
'''C-c C-w''' Insert a 'while' loop
'''C-c C-l''' Insert an indexed loop from 1 to n


'line-number-mode' and 'column-number-mode', are ''minor-modes''. Minor-modes can be used to extend a major-mode and any number of minor-modes can be enabled at once.
{{hc|.emacs-light|
(load "~/.emacs.d/main" nil t)
(load "~/.emacs.d/functions" nil t)
(load "~/.emacs.d/modes" nil t)
(load "~/.emacs.d/theme" nil t)
}}


==Tips and tricks==
And now we launch Emacs with
While the previous sections has given an overview of the basic editing commands available, it has not given an indication of the possibilities of Emacs.  This section will cover some more advanced techniques and functionality.


===TRAMP===
  emacs -q -l ~/.emacs-light
TRAMP (Transparent Remote Access, Multiple Protocols) is an extension which, as its name suggests, provides transparent access to remote files across a number of protocols. When prompted for a filename, entering a specific form will invoke TRAMP. Some examples:


To prompt for the root password before opening /etc/hosts with root permissions:
You can create an alias to ease the call.


C-x C-f /su::/etc/hosts
=== Local and custom variables ===


To connect to 'myhost' as 'myuser' via SSH and open the file ~/example.txt:
You can define variables in your configuration file that can be later one modified locally for a file.


  C-x C-f /ssh:myuser@myhost:~/example.txt
  (defcustom my-compiler "gcc" "Some documentation")


The path for TRAMP is typically of the form '/[protocol]:[[user@]host]:<file>'. TRAMP supports much more than the examples above might indicate. For more information refer to the TRAMP info manual, which is distributed with Emacs.
Now in any file you can define local variables in two ways, see [https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html the manual for complete details ]


===Keyboard macros and registers===
* Using {{ic| M-x add-file-local-variable-prop-line}}, which adds a commented line at the beginning similar to:
This section will provide a practical demonstration of the use of a couple of more powerful editing features. Namely, ''keyboard macros'' and ''registers''.
// -*- my-compiler:g++; mode:c++ -*-
* Or you can use {{ic| M-x add-file-local-variable}} to add lines near the end of the file:
// Local Variables:
// my-compiler: g++
// mode: c++
  // End:


The aim will be to produce a listing of a series of characters and their corresponding position in this list.  While it is possible to format each of them by hand, this would be slow and error-prone.  Alternatively, some of Emacs' more powerful editing functionality could be leveraged.  Before describing a solution, some details behind the techniques which will be used follow.
Note that for the values to take effect, you will need to call {{ic|M-x revert-buffer}}.


The first feature which will be introduced is ''registers''. Registers are used to store and retrieve a variety of data types ranging from numbers to window configurations.  Each register is given a name of a single character: this character is used to access the register.
Custom variables are considered unsafe by default. If you try to open a file that contains local variable redefining custom variables, Emacs will ask you for confirmation.


The other which will be demonstrated is ''keyboard macros''. A keyboard macro stores a sequence of commands so they can be easily repeated later.  These changes will now be performed step-by-step.
You can declare the variable as secure, thus removing the Emacs prompt for confirmation. You need to specify a predicate that any new value has to verify so that it can be considered safe.


Starting with a buffer containing our set of characters:
(defcustom my-compiler "gcc" "Some documentation" :safe 'stringp)
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz


Prepare a register by invoking the `number-to-register' command ('''C-x r n''') then storing the number '0' in register 'k':
In the previous example, if you attempt to set anything else than a string, Emacs will consider it insecure.


C-x r n k
=== Custom colors and theme ===


With point at the beginning of the buffer, start a keyboard macro ('''C-x (''') and begin to format the characters:
Colors can be easily customized using the ''face'' facility.


  C-x ( C-f M-4 .
  (set-face-background  'region                "color-17")
(set-face-foreground  'region                "white")
(set-face-bold-p      'font-lock-builtin-face t )


Insert ('''C-x r i''') and increment ('''C-x r +''') the register 'k'. The prefix argument ('''C-u''') is used to leave point positioned after the inserted text:
You can have let Emacs tell you the name of the face where the point is. Use the ''customize-face'' function for that. The facility will show you how to set colors, bold, underline, etc.


C-u C-x r i k C-x r + k
Emacs in console can handle 256 colors, but you will have to use an appropriate terminal for that. For instance URxvt has support for 256 colors. You can use the ''list-colors-display'' for a comprehensive list of supported colors. This is highly terminal-dependent.


Complete the formatting by inserting a newline.  Emacs can then repeat that process, beginning from the point where we started defining the keyboard macro, for the rest of the characters.  '''C-x e''' completes then invokes the keyboard macro.  The prefix argument, '''M-0''', causes the macro to repeat until it comes across an error.  In this case it aborts once it reaches the end of the buffer.
See also:


<RET> M-0 C-x e
* https://www.emacswiki.org/emacs/ColorThemes
* https://www.gnu.org/software/emacs/manual/html_node/emacs/Custom-Themes.html


The result:
=== SyncTeX support ===


  A....0
Emacs is a powerful LaTeX editor. This is mostly due to the fact you can adapt or create a LaTeX mode to fit your needs best.
  B....1
  C....2
  [...]
  x....49
  y....50
  z....51


===Regular expressions===
Still, there might be some challenges, like SyncTeX support. First you need to make sure your TeX distribution has it. If you installed TeX Live manually, you may need to install the ''synctex'' package.
From the Emacs Manual: "A regular expression, or ''regexp'' for short, is a pattern that denotes a (possibly infinite) set of strings."  This section will not go into any detail regarding regular expressions themselves (as there is simply too much to cover). It will however provide a quick demonstration of their power.  See [http://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html#Regular-Expressions Regular Expressions] section in the Emacs Manual for further reading.


Given the same scenario presented above: A list of characters which are to be formatted to represent their respective position in the list. (see [[Emacs#Keyboard macros and registers|Keyboard macros and registers]]).  Again, starting with a buffer containing.
# umask 022 && tlmgr install synctex


ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
SyncTeX support is viewer-dependent. Here we will use Zathura as an example, so the code needs to be adapted if you want to use another PDF viewer.


At the beginning of the buffer, use '''C-M-%''' (if the key-sequence is difficult to perform, it may be more comfortable to use '''M-x query-replace-regexp'''). At the prompt:
{{bc|
\(.\)
(defcustom tex-my-viewer "zathura --fork -s -x \"emacsclient --eval '(progn (switch-to-buffer (file-name-nondirectory \"'\"'\"%{input}\"'\"'\")) (goto-line %{line}))'\""
which simply matches one character.  Then, when prompted for the replacement:
  "PDF Viewer for TeX documents. You may want to fork the viewer
\1....\#^J
so that it detects when the same document is launched twice, and
{{Note|'^J' represents where a newline should be placed, it should not be entered into the prompt.  The newline must instead be inserted literally using '''C-q C-j'''.}}
persists when Emacs gets closed.
The replacement expression reads: "Insert the matched text between the first set of parentheses (in this case, a single character), followed by 4 periods then insert an automatically incremented number followed by a newline.


Finally, press '''!''' to apply this across the entire buffer.  All of the formatting that was performed in the previous section was performed with a single regexp replacement.
Simple command:


===Customization===
  zathura --fork
Emacs can configured by editing '~/.emacs' or using '''M-x customize'''. This section will focus on editing ~/.emacs by hand, and provide some example customizations to demonstrate commonly-configured aspects of Emacs.  The customize command provides a simple interface to make adjustments, though it may become restricting as you grow more familiar with Emacs.


All of the examples here can be performed while Emacs is running.  To evaluate the expression within Emacs, use:
We can use


'''C-M-x''' with point anywhere within the expression.
  emacsclient --eval '(progn (switch-to-buffer  (file-name-nondirectory \"%{input}\")) (goto-line %{line}))'


or
to reverse-search a pdf using SyncTeX. Note that the quotes and double-quotes matter and must be escaped appropriately."
:safe 'stringp)
}}


'''C-x C-e''' with point following the last ')'
Here we define our custom variable. If you are using AucTeX or Emacs default LaTeX-mode, you will have to set the viewer accordingly.


For some users, typing 'yes' and 'no' in prompts can quickly become tiring. To instead use the 'y' and 'n' keys at these prompts:
Now open a LaTeX source file with Emacs, compile the document, and launch the viewer. Zathura will spawn. If you press {{ic|Ctrl+Left click}} Emacs should place the point at the corresponding position.


(defalias 'yes-or-no-p 'y-or-n-p)
=== Syntax highlighting for systemd Files ===


To stop the cursor blinking, use:
You can use [https://elpa.nongnu.org/nongnu/systemd.html systemd-mode].


(blink-cursor-mode -1)
Alternatively, you can simply tell emacs to colour systemd files (services, timer, etc.), by adding this to your init file:


Similarly, to enable column-number-mode, as discussed in the previous section:
{{bc|
(add-to-list 'auto-mode-alist '("\\.service\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.timer\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.target\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.mount\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.automount\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.slice\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.socket\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.path\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.netdev\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.network\\'" . conf-unix-mode))
(add-to-list 'auto-mode-alist '("\\.link\\'" . conf-unix-mode))
}}


(column-number-mode 1)
=== Clipboard support for emacs-nox ===


The similarities between the previous two commands are not a coincidence: blink-cursor-mode and column-number-mode are both minor-modes.  As a rule, minor-modes can be enabled given positive argument or disabled with a negative argument.  Should the argument be omitted, the minor-mode will be toggled on/off.
To use the [[Xorg]] clipboard in emacs-nox, [[install]] {{Pkg|xclip}} and add the following function to {{ic|~/.emacs}} [https://lists.gnu.org/archive/html/help-gnu-emacs/2014-08/msg00189.html]


Here are some more examples of minor-modes.  The following will disable the scroll bars, menu-bar and tool-bar, respectively.
{{bc|1=
;; use xclip to copy/paste in emacs-nox
(unless window-system
  (when (getenv "DISPLAY")
    (defun xclip-cut-function (text &optional push)
      (with-temp-buffer
(insert text)
(call-process-region (point-min) (point-max) "xclip" nil 0 nil "-i" "-selection" "clipboard")))
    (defun xclip-paste-function()
      (let ((xclip-output (shell-command-to-string "xclip -o -selection clipboard")))
(unless (string= (car kill-ring) xclip-output)
  xclip-output )))
    (setq interprogram-cut-function 'xclip-cut-function)
    (setq interprogram-paste-function 'xclip-paste-function)
    ))
}}


(scroll-bar-mode -1)
{{Tip|You may also enable terminal mouse support by adding:
(menu-bar-mode -1)
(tool-bar-mode -1)


The variable, 'auto-mode-alist', can be modified to change the major-mode used by default for certain file names.  The following example will make the default major-mode for '.tut' and '.req' files 'text-mode'.
{{bc|1=
;; xterm mouse support
(require 'mouse)
(xterm-mouse-mode t)
}}


(setq auto-mode-alist
See also [https://www.opensource.apple.com/source/emacs/emacs-51/emacs/lisp/mwheel.el mwheel.el].
  (append
}}
    '(("\\.tut$" . text-mode)
      ("\\.req$" . text-mode))
    auto-mode-alist))


Settings can also be applied on a per-mode basis.  A common method for this is to add a function to a ''hook''. For example, to force indentation to use spaces instead of tabs, but only in text-mode:
== Packages ==


(add-hook 'text-mode-hook (lambda () (setq indent-tabs-mode nil)))
Emacs's functionality can be extended with third-party packages. The built-in package manager {{ic|package.el}} is the officially supported way to do this, though there are several other package managers written by members of the Emacs community. {{ic|package.el}} relies on the variable {{ic|package-archives}} to find packages. By default, this includes the [https://elpa.gnu.org/ Emacs Lisp Package Archive (ELPA)]. {{ic|M-x list-packages}} will create a buffer listing all the packages your Emacs knows about. The manual ({{ic|[https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html (info "(emacs) Packages")]}}) contains much more information.


Similarly, to only use spaces for indentation everywhere:
Third-party package archives can be added. The most widely used of these is [https://melpa.org/ MELPA].


(setq-default indent-tabs-mode nil)
A number of popular extensions are available as packages in the official repositories, and more still, via the [[AUR]]. The name of such packages usually have a 'emacs-' prefix (for example, {{Pkg|emacs-lua-mode}}), though not always (for example, {{AUR|auctex}}).


Keybindings can be adjusted in two ways. The first of which is 'define-key'.  'define-key' creates a keybinding for a command but only in one mode.  The example below will make '''F8''' delete any whitespace from the end of each line of a 'text-mode' buffer:
Some packages may require you to make changes to your configuration file in order to activate them so that their features are available during an Emacs session. For example, if you install {{AUR|auctex}}, you will need to add


(define-key text-mode-map (kbd "<f8>") 'delete-trailing-whitespace)
{{bc|
(load "auctex.el" nil t t)
(load "preview-latex.el" nil t t)
}}


The other method is 'global-set-key'.  This is used to bind a key to a command everywhere. To bind 'query-replace-regexp' ('''C-M-%''') to '<f7>'.
to your configuration file. Other packages should let you know how to activate them in the commentary section of their source code or in their README.


(global-set-key (kbd "<f7>") 'query-replace-regexp)
== Troubleshooting ==


Binding a command to an alternate key does not replace any existing bindings.  Which is to say, 'query-replace-regexp' would be bound to both '''F7''' and '''C-M-%''' after the above example.
=== Emacs fails to start with the error message 'Undefined color: "WINDOW_FOREGROUND"' ===


Almost anything within Emacs can be configured. Browsing through the [http://emacswiki.org/ Emacs Wiki] should give a solid place to start.
You need to install either the {{Pkg|mcpp}} package or the {{Pkg|gcc}} package. The C preprocessor ''cpp'' is used to preprocess [[X resources]] by ''xrdb''. If a C preprocessor is not installed on the system, ''xrdb'' silently skips running the C preprocessor and the symbol WINDOW_FOREGROUND is not expanded to a hexadecimal color code.


=== Extensions ===
=== Emacs systemd service fails to start when using Gccemacs ===


While Emacs includes hundreds of modes, libraries and other extensions, there are many more available to further Emacs' capabilities.  The majority of these come with instructions detailing any changes needed to be made to ~/.emacs.  These instructions are generally found in the comment block at the beginning of an elisp source file, or in a README (or similar) should the extension consist of multiple source files.
When using Gccemacs (either the branch {{ic|emacs-native-comp}} or {{ic|pgtk-nativecomp}}) and trying to start a systemd service for it, an error message informing that a {{ic|.eln}} file was not found might be logged:


A number of popular extensions are available as packages in the 'community' repository, and more still are available via the [[AUR]]. The name of such packages have a 'emacs-' prefix (for example, emacs-lua-mode). In many cases, the changes which need to be made to ~/.emacs are shown during the installation of the package.
{{hc|$ journalctl --user -xb -g eln|<nowiki>
emacs[7507]: emacs: ../native-lisp/28.0.50-x86_64-pc-linux-gnu-fc9c33938bf279333039c28064d363e8/lisp-mode-410874a46ab8852855281f021ca61fe7-1738806322de892570d69dfc55b437c2.eln: cannot open shared object file: No such file or directory
</nowiki>}}


Should instructions describing how to activate a specific extension not be available in the aforementioned location(s), check for a corresponding page in the [http://emacswiki.org/ Emacs Wiki], which will almost certainly provide an example configuration.  The Emacs Wiki is also an excellent resource for discovering even more extensions.
As a workaround, [[edit]] the {{ic|WorkingDirectory}} line of {{ic|emacs.service}} in the {{ic|[Service]}} section.


You can also use the [http://tromey.com/elpa/ Emacs Lisp Package Archive (ELPA)] to automatically install packages. See the website for instructions. ELPA is included with Emacs 24 (the newest version of Emacs); it is an accepted part of the Emacs ecosystem.
{{hc|emacs.service|<nowiki>
[Service]
...
WorkingDirectory=/usr/lib/emacs/28.0.50/x86_64-pc-linux-gnu/
...
</nowiki>}}


== Troubleshooting ==
{{Note|The {{ic|WorkingDirectory}} parameter has to be defined ''before'' a possible existing {{ic|Restart}} parameter.}}
 
=== Colored output issues ===


===Colored output issues===
By default, the Emacs shell will show raw escape sequences used to print colors. In other words, it will display strange symbols in place of the desired colored output.
By default, the Emacs shell will show raw escape sequences used to print colors. In other words, it will display strange symbols in place of the desired colored output.


Including the following into {{ic|~/.emacs}} amends the problem:
Including the following into {{ic|~/.emacs}} amends the problem:
  (add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
  (add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)


===Menus appear empty===
=== Problems displaying characters in X Windows ===
A bug exists in GNU Emacs 23.1 (using the GTK toolkit) which may cause some menus to appear empty.  This appears to be fixed in Emacs' CVS trunk.  The corresponding [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=550541 Debian bug report] contains a workaround.


=== Problems displaying characters in X Windows ===
If when you start emacs in X windows all the characters in the main window are white boxes with black borders (the ones you see if you try to view characters for which you do not have the correct font installed), you need to install {{Pkg|xorg-fonts-75dpi}} and/or {{Pkg|xorg-fonts-100dpi}} and restart X windows.
If when you start emacs in X windows all the characters in the main window are white boxes with black borders (the ones you see if you try to view characters for which you do not have the correct font installed), you need to install {{pkg|xorg-fonts-75dpi}} and/or {{pkg|xorg-fonts-100dpi}} and restart X windows.


=== Slow startup ===
=== Slow startup ===
{{Tip|To eliminate startup time, users may want to consider running Emacs [[#As a systemd unit]].}}
Slow startup times are often caused by one of two things.
Slow startup times are often caused by one of two things.


Line 374: Line 433:
  $ emacs -q
  $ emacs -q


If Emacs still starts slowly, refer to [[Emacs#Incorrect network configuration|Incorrect network configuration]]. If not, it is almost certainly a [[Emacs#Init file loads slowly|problem in your .emacs]].
* Mistakes, particularly in {{ic|/etc/hosts}}, will often result in a 5+ second delay when starting Emacs. Refer to '[[Configuring network#Set the hostname|set the hostname]]' in the network configuration guide for information.
* You may need to monitor any network packets sent from your computer (using a program like Wireshark) to see if there is any strange behavior.
* A simple way to search for the cause is to comment-out (i.e., prefix lines with ';') suspect sections of your {{ic|~/.emacs}} (or {{ic|~/.emacs.d/init.el}}) then start Emacs again to see if there is any change. Keep in mind use of "require" and "load" can slow the startup down, especially when used with larger extensions. They should, as a rule, only be used when their target is either: needed once Emacs starts or provides little more than "autoloads" for an extension. Otherwise, use the 'autoload function directly. For example, instead of: {{bc|(require 'anything)}} you might use: {{bc|(autoload 'anything "anything" "Select anything" t)}}
 
=== Cannot open load file: ... ===
 
The most common cause of this error is the 'load-path' variable not including the path to the directory within which the extension is located. To solve this, add the appropriate path to the list to be searched prior to attempting to load the extension:
 
  (add-to-list 'load-path "''/path/to/directory/''")
 
When attempting to use packages for extensions and Emacs has been configured with a prefix other than {{ic|/usr}}, the load-path will need to be updated. Place the following in {{ic|~/.emacs}} prior to the instructions provided by the package:
 
  (add-to-list 'load-path "/usr/share/emacs/site-lisp")
 
If compiling Emacs by hand, keep in mind that the default prefix is {{ic|/usr/local}}.
 
=== Dead-accent keys problem: '<dead-acute> is undefined' ===
 
Searching about this bug on Google, we find this link: https://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00167.html explaining the problem. The normal way to use accent keys does not work as expected. Trying to accent a word like 'fiancé' will produce the message above.
 
A way to solve it is just put the line below on your startup file, {{ic|~/.emacs}}:
 
  (require 'iso-transl)
 
And no, it is not a bug, but a feature of new Emacs versions. Reading the subsequent messages about it on the mail list, we found it [https://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00179.html]:
 
:It seems that nothing is loaded automatically because there is a choice betwee iso-transl and iso-acc. Both seem to provide an input method with C-x 8 or Alt-<accent> prefix, but what you and I are doing is just pressing a dead key (^, ´, `, ~, ¨) for the accent and then another key to "compose" the accented character. And there is no Alt key used in this! And according to documentation it seems be appropriate for 8-bit encodings, so it should be pretty useless in UTF-8. I reported this bug when it was introduced, but the bug seems to be classified as a feature ... Maybe it's just because the file is auto-loaded though pretty useless.
 
=== C-M-% and some other bindings do not work in emacs nox ===
 
This is because terminals are more limited than Xorg. Some terminals may handle more bindings than other, though. Two solutions:
 
* either use the graphical version,
* or change the binding to a supported one.
 
Example:
 
{{hc|.emacs|(global-set-key (kbd "C-M-y") 'query-replace-regexp)}}
 
=== Emacs hangs ===
 
Due to its single-threaded nature, many operations block Emacs. This could happen in a few ways. For example, Emacs may be waiting for input from you (e.g. you have opened the minibuffer in one frame but are trying to work in another). Alternatively, Emacs could be running code that simply takes a while to finish. Or perhaps you have run across a bug. There are several ways of trying to unblock Emacs without killing the Emacs process.  


====Incorrect network configuration====
* Try pressing {{ic|C-g}}. Depending on what Emacs is doing, you may need to press it multiple times.
* Try pressing {{ic|ESC ESC ESC}}.
* From another terminal, run {{ic|killall -SIGUSR2 emacs}}


Mistakes, particularly in /etc/hosts, will often result in a 5+ second delay when starting Emacs.  Refer to '[[Configuring_network#Set_the_hostname|set the hostname]]' in the network configuration guide for information.
=== Emacs-nox output gets messy ===


====Init file loads slowly====
When working in a terminal, the color, indentation, or anything related to the output might become crazy. This is (probably?) because Emacs was sent a special character at some point which may conflict with the current terminal.
If this happens you can do {{ic|M-x redraw-display}}, which will redraw the terminal's display. If this problem happens frequently, you might want to bind the command to a key, e.g. by putting something like:


A simple way to search for the cause is to comment-out (i.e., prefix lines with ';') suspect sections of your ~/.emacs (or ~/.emacs.d/init.el) then start Emacs again to see if there's any change.  Keep in mind use of "require" and "load" can slow the startup down, especially when used with larger extensions.  They should, as a rule, only be used when their target is either: needed once Emacs starts or provides little more than "autoloads" for an extension.  Otherwise, use the 'autoload function directly.  For example, instead of:
(global-set-key (kbd "<f7>") 'redraw-display)


(require 'anything)
in your {{ic|.emacs}} file.


you might use:
Graphical Emacs does not suffer from this issue.


(autoload 'anything "anything" "Select anything" t)
=== Weird escaped numbers (utf-8) displaying in emacs terminal ===


=== Cannot open load file: ... ===
Export these values in your {{ic|.bashrc}} or {{ic|.zshrc}}:
 
{{hc|$ ~/.bashrc or ~/.zshrc |2=export LANG\='en_US.UTF-8'
export LC_ALL\="en_US.UTF-8"
export TERM\=xterm-256color
}}
 
It can be a source of errors since in Linux distributions the correct values use lowercase utf (e.g. {{ic|en_US.utf-8}})


The most common cause of this error is the 'load-path' variable not including the path to the directory within which the extension is located. To solve this, add the appropriate path to the list to be searched prior to attempting to load the extension:
To view all available locales use {{ic|locale -a}}.


  (add-to-list 'load-path "/path/to/directory/")
=== Shift + Arrow keys not working in emacs within tmux ===


When attempting to use packages for extensions and Emacs has been configured with a prefix other than '/usr', the load-path will need to be updated.  Place the following in ~/.emacs prior to the instructions provided by the package:
Enable xterm-keys in your [[tmux]] configuration:


  (add-to-list 'load-path "/usr/share/emacs/site-lisp")
{{hc|~/.tmux.conf|
setw -g xterm-keys on
}}


If compiling Emacs by hand, keep in mind that the default prefix is '/usr/local'.
Because this will break other key combinations, put the following in your emacs config.


== Alternatives ==
{{hc|~/.emacs|
(defadvice terminal-init-screen
  ;; The advice is named `tmux', and is run before `terminal-init-screen' runs.
  (before tmux activate)
  ;; Docstring. This describes the advice and is made available inside emacs;
  ;; for example when doing C-h f terminal-init-screen RET
  "Apply xterm keymap, allowing use of keys passed through tmux."
  ;; This is the elisp code that is run before `terminal-init-screen'.
  (if (getenv "TMUX")
    (let ((map (copy-keymap xterm-function-map)))
    (set-keymap-parent map (keymap-parent input-decode-map))
(set-keymap-parent input-decode-map map))))
}}


There are numerous implementations of Emacs. GNU/Emacs is probably the most popular. <br>
See [https://github.com/tmux/tmux/wiki/FAQ#how-do-i-make-modified-function-and-arrow-keys-like-c-up-m-pageup-work-inside-tmux tmux FAQ] for details.
Lighter Emacs compatibile alternatives can be found in Arch repositories or in [https://aur.archlinux.org/ AUR].


=== mg ===
=== Improper window resizing in KDE ===


mg (originally called MicroGnuEmacs) is lightweight implementation of Emacs written in C.
{{Merge|KDE|Applicable to other applications}}


It's possible to install mg right away from {{ic|community}}
KDE users may observe that the Emacs window does not resize properly, but rather, the resized portion is transparent and mouse clicks are sent to the underlying window. To correct this behavior, change KDE's GTK3 theme to something other than oxygen-gtk. For instance, use the Emacs theme which is included with {{Pkg|gtk3}}.
# pacman -S mg
or download source from official [http://homepage.boetes.org/software/mg/ page].


=== zile ===
To force Emacs to maximize completely in KDE, click the Emacs icon in the title bar, and select ''More Actions > Special Window Settings''. Then in the ''Size & Position'' tab, select ''Obey geometry restrictions'', choose ''Force'' in the dropdown menu, and select ''No'' from the radio buttons on the right.


According to the offical web [https://www.gnu.org/software/zile/ page] "GNU Zile is a lightweight Emacs clone. Zile is short for Zile Is Lossy Emacs. Zile has been written to be as similar as possible to Emacs; every Emacs user should feel at home.".
== Alternatives ==


zile can be found in {{ic|extra}}
There are numerous "smaller" implementations of Emacs. GNU/Emacs is probably the most popular. Some lightweight Emacs compatible alternatives will be listed here:


# pacman -S zile
* {{App|mg|Lightweight implementation of Emacs written in C. Note that it does not support UTF-8.|https://github.com/hboetes/mg|{{Pkg|mg}}}}
* {{App|Zile|"Zile Is Lossy Emacs", a lightweight clone written to be as similar as possible to Emacs. Zile has no UTF-8 support.|https://www.gnu.org/software/zile/|{{AUR|zile}}}}
* {{App|uemacs|A "Micro-emacs" version customized by Linus Torvalds.|https://git.kernel.org/pub/scm/editors/uemacs/uemacs.git|{{AUR|uemacs-git}}}}
* {{App|emacs-ng|A new approach to Emacs - Including TypeScript, Threading, Async I/O, and WebRender.|https://github.com/emacs-ng/emacs-ng|{{AUR|emacs-ng-git}}}}
* {{App|qemacs|"Quick Emacs", ased on the Emacs Lisp interpreter, but it has a smaller code base and a simplified user interface.|https://bellard.org/qemacs/|{{AUR|qemacs}}}}
* {{App|sxemacs|A fork of xemacs.|http://www.sxemacs.org/|{{AUR|sxemacs}}}}
* {{App|jove|Jonathan's Own Version of Emacs is an Emacs-like editor without Lisp.|https://github.com/jonmacs/jove|{{AUR|jove}}}}


the latest taballs can be found in official GNU [http://ftp.sh.cvut.cz/MIRRORS/gnu/pub/gnu/zile/ mirrors].
=== Emacs distros ===


=== uemacs ===
* [[Spacemacs]] - A community-driven Emacs distribution - The best editor is neither Emacs nor Vim, it's Emacs *and* Vim!
* [https://github.com/doomemacs/doomemacs/ Doom Emacs] - An Emacs framework for the stubborn martian hacker
* [https://github.com/snackon/Witchmacs/ Witchmacs] - The cutest Emacs distribution
* [https://github.com/pprobst/yukimacs/ Yukimacs] - A GNU/Emacs config built from the ground up (no Spacemacs or Doom Emacs), heavily inspired by Uncle Dave’s Emacs and Witchmacs.


uemacs is "Micro-emacs version customized by Linus Torvalds".
More: [https://www.emacswiki.org/emacs/StarterKits Starter Kits]
It can be found in [https://aur.archlinux.org/ AUR] as [https://aur.archlinux.org/packages.php?ID=31502 uemacs].


== See also ==
== See also ==
* [http://www.gnu.org/software/emacs/ GNU Emacs home page]
 
* [http://www.gnu.org/software/emacs/manual/emacs.html GNU Emacs Manual]
* [https://www.gnu.org/software/emacs/ GNU Emacs home page]
* [http://www.emacswiki.org/cgi-bin/wiki/ Emacs Wiki]
* [https://www.gnu.org/software/emacs/manual/emacs.html GNU Emacs manual]
* [http://wikemacs.org WikEmacs - a more readable, but less complete Emacs Wiki]
* [https://www.emacswiki.org/ Emacs Wiki]
* [http://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html Useful introduction to Emacs and its shortcuts]
* [https://wikemacs.org WikEmacs - a more readable, but less complete Emacs wiki]
* [http://www.dina.kvl.dk/~abraham/religion/ The Church of Emacs]
* [https://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html Useful introduction to Emacs and its shortcuts]
* [http://repo.or.cz/w/emacs.git/blob/HEAD:/etc/refcards/refcard.pdf Official reference card]
* [https://web.archive.org/web/20160506064817/https://d0edfcdc0ccc1cd13cdab5eb986fb92e8660dbef.googledrive.com/host/0B6LMD0u8OhYYZEotN2QyR1hwR1k/ The Church of Emacs (via Google drive)]
* [https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf Official reference card]
* [[EXWM]], the Emacs X Window Manager

Latest revision as of 00:22, 20 January 2024

Emacs is an extensible, customizable, self-documenting real-time display editor. At the core of Emacs lies an Emacs Lisp interpreter, the language in which the majority of Emacs' built-in functionality and extensions are implemented. GNU Emacs uses GTK as its X toolkit, though it functions equally well within a CLI environment.

Installation

Install one of the following packages:

Other variants can be searched for, as an example emacs-gitAUR provides the development branch of GNU Emacs.

Usage

Before launching emacs, you should know how to close it (especially if you run it in a terminal): use the Ctrl+xCtrl+c key sequence.

To start Emacs run:

$ emacs

or, to use it from the console:

$ emacs -nw

or, for fast loading (no .emacs) and editing within CLI:

$ emacs -Q -nw

If you installed the nox version, emacs and emacs -nw will be the same.

A file name can also be provided to open that file immediately:

$ emacs filename.txt

No colors

By default, Emacs starts with a color theme showing hyperlinks in dark blue. To start Emacs on a text terminal without any color theme or scheme:

$ emacs -nw --color=no

This will cause all text to appear in the foreground color of the terminal — normally white text on a black background, or black text on a white background.

As a daemon

In order to avoid reloading the Emacs configuration file every time Emacs starts, you can run Emacs as a daemon:

$ emacs --daemon

You may then connect to the daemon by running:

$ emacsclient -nc

Which creates a new frame -c (use -t if you prefer to use it in the terminal) and does not hog the terminal -n (--no-wait). Note that some programs such as Mutt or Git (for commit messages) wait for the editor to finish, so you cannot use the -n parameter. If your default editor is set to use it, you will have to specify an alternate editor (e.g. emacsclient -a "" -t) for those programs.

As a systemd unit

A systemd unit is included in Emacs 26.1. The unit is installed with Emacs, but it must be enabled as a user unit (not a system-wide) after installing Emacs.

After the service is started, Emacs is ready.

If you want to be able to start graphical emacs frames through emacsclient on Wayland, a specific drop-in snippet is needed, as shown in EmacsWiki.

Note that systemd user units do not inherit environment variables from a login shell (like ~/.bash_profile). See Systemd/User#Environment variables for more information.

If you start emacs as a daemon, you may want to set the VISUAL and EDITOR environment variables to emacsclient so that programs that start an editor use emacsclient instead of starting a new full instance of the editor. Programs that use an external editor include email programs (for editing the message), Git (for editing the commit message), and less (the v command for editing the displayed file). Do not use the -n (--nowait) option to emacsclient, since programs typically expect editing to be finished when the editor exits.

It is also recommended to change any GUI start menu entries (or equivalent) for Emacs to point to emacsclient instead of emacs, so that the emacs daemon is used instead of starting a new emacs process.

Getting help

Emacs has a built-in tutorial which can be accessed by clicking the first link on the splash screen and selecting Help>Emacs Tutorial from the menu or by pressing C-h t.

To read the tutorial in a language other than english, use the command Alt x, and enter help-with-tutorial-spec-language

Emacs is self-documenting by design. As such, a great deal of information is available to determine the name of a specific command or its keybinding, for example. See all contextual help bindings with C-h C-h.

Emacs also includes a set of reference cards, useful for beginners and experts alike, see /usr/share/emacs/version/etc/refcards/.

The manuals

If you really want to master Emacs, the most recommended source of documentation remains the official manuals:

  • Emacs: the complete Emacs user manual.
  • Emacs FAQ.
  • Emacs Lisp Intro: if you never used any programming language before.
  • Elisp: if you are already familiar with a programming language.

You can access them as PDFs from GNU.org or directly from Emacs itself thanks to the embedded 'info' reader: C-h i. Press m to choose a book.

Some users prefer to read books using 'info' because of its convenient shortcuts, its paragraphs adapting to window width and the font adapted to current screen resolution. Some find it less irritating to the eyes. Finally you can easily copy content from the book to any Emacs buffer, and you can even execute Lisp code snippets directly from the examples.

You may want to read the Info book to know more about it: C-h i m info <RET>. Press ? while in info mode for a quick list of shortcuts.

Configuration

One of Emacs's main features is its extensibility and the ease of configuration. Emacs has a built-in customization engine. You can do M-x customize which displays a list of customization options. For how to use this interface, see the Easy Customization info node: (info "(emacs) Easy Customization"). You can set customization opens just for one Emacs session or save them into a configuration file so that they are saved across Emacs sessions. Note that this is what the customization interface does if you select Apply and Save.

When Emacs is started, it normally tries to load a Lisp program from an "initialization file", or "init file" for short. This file, if it exists, specifies how to initialize Emacs for you. Emacs looks for your init file at ~/.emacs, ~/.emacs.el, ~/.emacs.d/init.el, or ~/.config/emacs/init.el. See the info node "Init File" for more: (info "(emacs) Init File")

Tips and tricks

TRAMP

TRAMP (Transparent Remote Access, Multiple Protocols) is an extension which, as its name suggests, provides transparent access to remote files across a number of protocols. When prompted for a filename, entering a specific form will invoke TRAMP. Some examples:

To prompt for the root password before opening /etc/hosts with root permissions:

C-x C-f /sudo::/etc/hosts

To connect to 'remotehost' as 'you' via SSH and open the file ~/example.txt:

C-x C-f /ssh:you@remotehost:~/example.txt

The path for TRAMP is typically of the form '/[protocol]:[[user@]host]:<file>'.

To connect to 'myhost' as 'you' and edit /etc/hosts with sudo:

/ssh:you@remotehost|sudo:remotehost:/etc/hosts

TRAMP supports much more than the examples above might indicate. For more information refer to the TRAMP info manual, which is distributed with Emacs.

Using Emacs as git mergetool

By default, Git provides support for using Emacs' Emerge mode as a merge tool. However you may prefer the Ediff mode. Unfortunately this mode is not supported by git for technical reasons. There is still a way to use it by evaluating some elisp code upon emacs call.

.gitconfig
[mergetool.ediff]
    cmd = emacs --eval \" (progn (defun ediff-write-merge-buffer () (let ((file ediff-merge-store-file)) (set-buffer ediff-buffer-C) (write-region (point-min) (point-max) file) (message \\\"Merge buffer saved in: %s\\\" file) (set-buffer-modified-p nil) (sit-for 1))) (setq ediff-quit-hook 'kill-emacs ediff-quit-merge-hook 'ediff-write-merge-buffer) (ediff-merge-files-with-ancestor \\\"$LOCAL\\\" \\\"$REMOTE\\\" \\\"$BASE\\\" nil \\\"$MERGED\\\"))\" 

[merge]
	tool = ediff

Note that the command has to be on a single line. In the above example, we launch a new instance of Emacs. You might want to use emacsclient for quicker startup; it is not recommended though since the Ediff call is not really clean: it could mess with your current Emacs session.

If you want an instant startup you can use the -q parameter. If you want to launch Emacs quickly while preserving at least a part of your configuration, you can call Emacs with

emacs -q -l ~/.emacs-light

where the light configuration file loads only what you need for Ediff.

See kerneltrap.org and stackoverflow for more details on this trick and the Ediff issue.

Using Caps Lock as Control key

Some users like this behavior to avoid the so-called "emacs pinky". If you want to try it on X, just run

$ setxkbmap -option 'ctrl:nocaps'

Alternatively, to swap these keys, run

$ setxkbmap -option 'ctrl:swapcaps'

To set this permanently, consider adding it to your .xinitrc file.

Now, if you ever need to uppercase a region, just use the default C-x C-u keybinding, which calls the upcase-region function.

See [1] for an alternative approach.

If you are missing your Caps Lock function, map it as both "Shift" at same time.

$ setxkbmap -option "shift:both_capslock"

Some desktop environments include graphical tools to simplify keyboard remappings. For example, in Plasma 5 open System Settings and click on Input Devices. Select Keyboard and in the Advanced tab you will find the setting Caps Lock behaviour under which you can select Caps Lock is also a Ctrl.

Multiplexing emacs and emacsclient

Opening a new file in the same emacs-session requires the use of emacsclient. emacs command can be itself wrapped to do the smarter job to open the file if the session exists.

To start session you need to start-server. This snippet will create server in first session of emacs. Add this to your emacs configuration file.

.emacs or .emacs.d/init.el
(require 'server)
(unless (server-running-p)
  (server-start))

Shell alias method is not adequate for this since you also need to pass variables or start the independent session of your own. Add this to the .bashrc or any rc file of your shell. This will make your emacs command behave like emacsclient if the argument is passed.

function emacs {
    if [[ $# -eq 0 ]]; then
        /usr/bin/emacs # "emacs" is function, will cause recursion
        return
    fi
    args=($*)
    for ((i=0; i <= ${#args}; i++)); do
        local a=${args[i]}
        # NOTE: -c for creating new frame
        if [[ ${a:0:1} == '-' && ${a} != '-c' && ${a} != '--' ]]; then
            /usr/bin/emacs ${args[*]}
            return
        fi
    done
    setsid emacsclient -n -a /usr/bin/emacs ${args[*]}
}

If you want to run it in a new session just do emacs file -.

Multiple configurations

You can use several configurations and tell Emacs to load one or the other.

For example, let us define two configuration files.

.emacs
(load "~/.emacs.d/main" nil t)
(load "~/.emacs.d/functions" nil t)
(load "~/.emacs.d/modes" nil t)
(load "~/.emacs.d/plugins" nil t)
(load "~/.emacs.d/theme" nil t)

This is the full configuration we load for the daemon. But the plugins file is huge and slow to load. If we want to spawn a new Emacs instance that does not need the plugins features, it can be cumbersome to load it every time in the long run.

.emacs-light
(load "~/.emacs.d/main" nil t)
(load "~/.emacs.d/functions" nil t)
(load "~/.emacs.d/modes" nil t)
(load "~/.emacs.d/theme" nil t)

And now we launch Emacs with

emacs -q -l ~/.emacs-light

You can create an alias to ease the call.

Local and custom variables

You can define variables in your configuration file that can be later one modified locally for a file.

(defcustom my-compiler "gcc" "Some documentation")

Now in any file you can define local variables in two ways, see the manual for complete details

  • Using M-x add-file-local-variable-prop-line, which adds a commented line at the beginning similar to:
// -*- my-compiler:g++; mode:c++ -*-
  • Or you can use M-x add-file-local-variable to add lines near the end of the file:
// Local Variables:
// my-compiler: g++
// mode: c++
// End:

Note that for the values to take effect, you will need to call M-x revert-buffer.

Custom variables are considered unsafe by default. If you try to open a file that contains local variable redefining custom variables, Emacs will ask you for confirmation.

You can declare the variable as secure, thus removing the Emacs prompt for confirmation. You need to specify a predicate that any new value has to verify so that it can be considered safe.

(defcustom my-compiler "gcc" "Some documentation" :safe 'stringp)

In the previous example, if you attempt to set anything else than a string, Emacs will consider it insecure.

Custom colors and theme

Colors can be easily customized using the face facility.

(set-face-background  'region                 "color-17")
(set-face-foreground  'region                 "white")
(set-face-bold-p      'font-lock-builtin-face t ) 

You can have let Emacs tell you the name of the face where the point is. Use the customize-face function for that. The facility will show you how to set colors, bold, underline, etc.

Emacs in console can handle 256 colors, but you will have to use an appropriate terminal for that. For instance URxvt has support for 256 colors. You can use the list-colors-display for a comprehensive list of supported colors. This is highly terminal-dependent.

See also:

SyncTeX support

Emacs is a powerful LaTeX editor. This is mostly due to the fact you can adapt or create a LaTeX mode to fit your needs best.

Still, there might be some challenges, like SyncTeX support. First you need to make sure your TeX distribution has it. If you installed TeX Live manually, you may need to install the synctex package.

# umask 022 && tlmgr install synctex

SyncTeX support is viewer-dependent. Here we will use Zathura as an example, so the code needs to be adapted if you want to use another PDF viewer.

(defcustom tex-my-viewer "zathura --fork -s -x \"emacsclient --eval '(progn (switch-to-buffer  (file-name-nondirectory \"'\"'\"%{input}\"'\"'\")) (goto-line %{line}))'\"" 
  "PDF Viewer for TeX documents. You may want to fork the viewer
so that it detects when the same document is launched twice, and
persists when Emacs gets closed.

Simple command:

  zathura --fork

We can use

  emacsclient --eval '(progn (switch-to-buffer  (file-name-nondirectory \"%{input}\")) (goto-line %{line}))'

to reverse-search a pdf using SyncTeX. Note that the quotes and double-quotes matter and must be escaped appropriately."
:safe 'stringp)

Here we define our custom variable. If you are using AucTeX or Emacs default LaTeX-mode, you will have to set the viewer accordingly.

Now open a LaTeX source file with Emacs, compile the document, and launch the viewer. Zathura will spawn. If you press Ctrl+Left click Emacs should place the point at the corresponding position.

Syntax highlighting for systemd Files

You can use systemd-mode.

Alternatively, you can simply tell emacs to colour systemd files (services, timer, etc.), by adding this to your init file:

 (add-to-list 'auto-mode-alist '("\\.service\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.timer\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.target\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.mount\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.automount\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.slice\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.socket\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.path\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.netdev\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.network\\'" . conf-unix-mode))
 (add-to-list 'auto-mode-alist '("\\.link\\'" . conf-unix-mode))

Clipboard support for emacs-nox

To use the Xorg clipboard in emacs-nox, install xclip and add the following function to ~/.emacs [2]

;; use xclip to copy/paste in emacs-nox
(unless window-system
  (when (getenv "DISPLAY")
    (defun xclip-cut-function (text &optional push)
      (with-temp-buffer
	(insert text)
	(call-process-region (point-min) (point-max) "xclip" nil 0 nil "-i" "-selection" "clipboard")))
    (defun xclip-paste-function()
      (let ((xclip-output (shell-command-to-string "xclip -o -selection clipboard")))
	(unless (string= (car kill-ring) xclip-output)
	  xclip-output )))
    (setq interprogram-cut-function 'xclip-cut-function)
    (setq interprogram-paste-function 'xclip-paste-function)
    ))
Tip: You may also enable terminal mouse support by adding:
;; xterm mouse support
(require 'mouse)
(xterm-mouse-mode t)

See also mwheel.el.

Packages

Emacs's functionality can be extended with third-party packages. The built-in package manager package.el is the officially supported way to do this, though there are several other package managers written by members of the Emacs community. package.el relies on the variable package-archives to find packages. By default, this includes the Emacs Lisp Package Archive (ELPA). M-x list-packages will create a buffer listing all the packages your Emacs knows about. The manual ((info "(emacs) Packages")) contains much more information.

Third-party package archives can be added. The most widely used of these is MELPA.

A number of popular extensions are available as packages in the official repositories, and more still, via the AUR. The name of such packages usually have a 'emacs-' prefix (for example, emacs-lua-mode), though not always (for example, auctexAUR).

Some packages may require you to make changes to your configuration file in order to activate them so that their features are available during an Emacs session. For example, if you install auctexAUR, you will need to add

(load "auctex.el" nil t t)
(load "preview-latex.el" nil t t)

to your configuration file. Other packages should let you know how to activate them in the commentary section of their source code or in their README.

Troubleshooting

Emacs fails to start with the error message 'Undefined color: "WINDOW_FOREGROUND"'

You need to install either the mcpp package or the gcc package. The C preprocessor cpp is used to preprocess X resources by xrdb. If a C preprocessor is not installed on the system, xrdb silently skips running the C preprocessor and the symbol WINDOW_FOREGROUND is not expanded to a hexadecimal color code.

Emacs systemd service fails to start when using Gccemacs

When using Gccemacs (either the branch emacs-native-comp or pgtk-nativecomp) and trying to start a systemd service for it, an error message informing that a .eln file was not found might be logged:

$ journalctl --user -xb -g eln
emacs[7507]: emacs: ../native-lisp/28.0.50-x86_64-pc-linux-gnu-fc9c33938bf279333039c28064d363e8/lisp-mode-410874a46ab8852855281f021ca61fe7-1738806322de892570d69dfc55b437c2.eln: cannot open shared object file: No such file or directory

As a workaround, edit the WorkingDirectory line of emacs.service in the [Service] section.

emacs.service
[Service]
...
WorkingDirectory=/usr/lib/emacs/28.0.50/x86_64-pc-linux-gnu/
...
Note: The WorkingDirectory parameter has to be defined before a possible existing Restart parameter.

Colored output issues

By default, the Emacs shell will show raw escape sequences used to print colors. In other words, it will display strange symbols in place of the desired colored output.

Including the following into ~/.emacs amends the problem:

(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)

Problems displaying characters in X Windows

If when you start emacs in X windows all the characters in the main window are white boxes with black borders (the ones you see if you try to view characters for which you do not have the correct font installed), you need to install xorg-fonts-75dpi and/or xorg-fonts-100dpi and restart X windows.

Slow startup

Tip: To eliminate startup time, users may want to consider running Emacs #As a systemd unit.

Slow startup times are often caused by one of two things.

To determine which it might be, run Emacs with:

$ emacs -q
  • Mistakes, particularly in /etc/hosts, will often result in a 5+ second delay when starting Emacs. Refer to 'set the hostname' in the network configuration guide for information.
  • You may need to monitor any network packets sent from your computer (using a program like Wireshark) to see if there is any strange behavior.
  • A simple way to search for the cause is to comment-out (i.e., prefix lines with ';') suspect sections of your ~/.emacs (or ~/.emacs.d/init.el) then start Emacs again to see if there is any change. Keep in mind use of "require" and "load" can slow the startup down, especially when used with larger extensions. They should, as a rule, only be used when their target is either: needed once Emacs starts or provides little more than "autoloads" for an extension. Otherwise, use the 'autoload function directly. For example, instead of:
    (require 'anything)
    you might use:
    (autoload 'anything "anything" "Select anything" t)

Cannot open load file: ...

The most common cause of this error is the 'load-path' variable not including the path to the directory within which the extension is located. To solve this, add the appropriate path to the list to be searched prior to attempting to load the extension:

 (add-to-list 'load-path "/path/to/directory/")

When attempting to use packages for extensions and Emacs has been configured with a prefix other than /usr, the load-path will need to be updated. Place the following in ~/.emacs prior to the instructions provided by the package:

 (add-to-list 'load-path "/usr/share/emacs/site-lisp")

If compiling Emacs by hand, keep in mind that the default prefix is /usr/local.

Dead-accent keys problem: '<dead-acute> is undefined'

Searching about this bug on Google, we find this link: https://lists.gnu.org/archive/html/help-gnu-emacs/2009-05/msg00167.html explaining the problem. The normal way to use accent keys does not work as expected. Trying to accent a word like 'fiancé' will produce the message above.

A way to solve it is just put the line below on your startup file, ~/.emacs:

  (require 'iso-transl)

And no, it is not a bug, but a feature of new Emacs versions. Reading the subsequent messages about it on the mail list, we found it [3]:

It seems that nothing is loaded automatically because there is a choice betwee iso-transl and iso-acc. Both seem to provide an input method with C-x 8 or Alt-<accent> prefix, but what you and I are doing is just pressing a dead key (^, ´, `, ~, ¨) for the accent and then another key to "compose" the accented character. And there is no Alt key used in this! And according to documentation it seems be appropriate for 8-bit encodings, so it should be pretty useless in UTF-8. I reported this bug when it was introduced, but the bug seems to be classified as a feature ... Maybe it's just because the file is auto-loaded though pretty useless.

C-M-% and some other bindings do not work in emacs nox

This is because terminals are more limited than Xorg. Some terminals may handle more bindings than other, though. Two solutions:

  • either use the graphical version,
  • or change the binding to a supported one.

Example:

.emacs
(global-set-key (kbd "C-M-y") 'query-replace-regexp)

Emacs hangs

Due to its single-threaded nature, many operations block Emacs. This could happen in a few ways. For example, Emacs may be waiting for input from you (e.g. you have opened the minibuffer in one frame but are trying to work in another). Alternatively, Emacs could be running code that simply takes a while to finish. Or perhaps you have run across a bug. There are several ways of trying to unblock Emacs without killing the Emacs process.

  • Try pressing C-g. Depending on what Emacs is doing, you may need to press it multiple times.
  • Try pressing ESC ESC ESC.
  • From another terminal, run killall -SIGUSR2 emacs

Emacs-nox output gets messy

When working in a terminal, the color, indentation, or anything related to the output might become crazy. This is (probably?) because Emacs was sent a special character at some point which may conflict with the current terminal. If this happens you can do M-x redraw-display, which will redraw the terminal's display. If this problem happens frequently, you might want to bind the command to a key, e.g. by putting something like:

(global-set-key (kbd "<f7>") 'redraw-display)

in your .emacs file.

Graphical Emacs does not suffer from this issue.

Weird escaped numbers (utf-8) displaying in emacs terminal

Export these values in your .bashrc or .zshrc:

$ ~/.bashrc or ~/.zshrc 
export LANG\='en_US.UTF-8'
export LC_ALL\="en_US.UTF-8"
export TERM\=xterm-256color

It can be a source of errors since in Linux distributions the correct values use lowercase utf (e.g. en_US.utf-8)

To view all available locales use locale -a.

Shift + Arrow keys not working in emacs within tmux

Enable xterm-keys in your tmux configuration:

~/.tmux.conf
setw -g xterm-keys on

Because this will break other key combinations, put the following in your emacs config.

~/.emacs
(defadvice terminal-init-screen
  ;; The advice is named `tmux', and is run before `terminal-init-screen' runs.
  (before tmux activate)
  ;; Docstring. This describes the advice and is made available inside emacs;
  ;; for example when doing C-h f terminal-init-screen RET
  "Apply xterm keymap, allowing use of keys passed through tmux."
  ;; This is the elisp code that is run before `terminal-init-screen'.
  (if (getenv "TMUX")
    (let ((map (copy-keymap xterm-function-map)))
    (set-keymap-parent map (keymap-parent input-decode-map))
(set-keymap-parent input-decode-map map))))

See tmux FAQ for details.

Improper window resizing in KDE

This article or section is a candidate for merging with KDE.

Notes: Applicable to other applications (Discuss in Talk:Emacs)

KDE users may observe that the Emacs window does not resize properly, but rather, the resized portion is transparent and mouse clicks are sent to the underlying window. To correct this behavior, change KDE's GTK3 theme to something other than oxygen-gtk. For instance, use the Emacs theme which is included with gtk3.

To force Emacs to maximize completely in KDE, click the Emacs icon in the title bar, and select More Actions > Special Window Settings. Then in the Size & Position tab, select Obey geometry restrictions, choose Force in the dropdown menu, and select No from the radio buttons on the right.

Alternatives

There are numerous "smaller" implementations of Emacs. GNU/Emacs is probably the most popular. Some lightweight Emacs compatible alternatives will be listed here:

  • mg — Lightweight implementation of Emacs written in C. Note that it does not support UTF-8.
https://github.com/hboetes/mg || mg
  • Zile — "Zile Is Lossy Emacs", a lightweight clone written to be as similar as possible to Emacs. Zile has no UTF-8 support.
https://www.gnu.org/software/zile/ || zileAUR
  • uemacs — A "Micro-emacs" version customized by Linus Torvalds.
https://git.kernel.org/pub/scm/editors/uemacs/uemacs.git || uemacs-gitAUR
  • emacs-ng — A new approach to Emacs - Including TypeScript, Threading, Async I/O, and WebRender.
https://github.com/emacs-ng/emacs-ng || emacs-ng-gitAUR
  • qemacs — "Quick Emacs", ased on the Emacs Lisp interpreter, but it has a smaller code base and a simplified user interface.
https://bellard.org/qemacs/ || qemacsAUR
  • sxemacs — A fork of xemacs.
http://www.sxemacs.org/ || sxemacsAUR
  • jove — Jonathan's Own Version of Emacs is an Emacs-like editor without Lisp.
https://github.com/jonmacs/jove || joveAUR

Emacs distros

  • Spacemacs - A community-driven Emacs distribution - The best editor is neither Emacs nor Vim, it's Emacs *and* Vim!
  • Doom Emacs - An Emacs framework for the stubborn martian hacker
  • Witchmacs - The cutest Emacs distribution
  • Yukimacs - A GNU/Emacs config built from the ground up (no Spacemacs or Doom Emacs), heavily inspired by Uncle Dave’s Emacs and Witchmacs.

More: Starter Kits

See also