Next: Minor Modes, Up: Major and Minor Modes   [Contents][Index]

25.1 Major Modes ¶

Every buffer possesses a major mode, which determines the editing behavior of Emacs while that buffer is current. The mode line normally shows the name of the current major mode, in parentheses (see The Mode Line).

The least specialized major mode is called Fundamental mode. This mode has no mode-specific redefinitions or variable settings, so that each Emacs command behaves in its most general manner, and each user option variable is in its default state.

For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you typically use a more specialized major mode, such as Lisp mode or Text mode. Most major modes fall into three major groups. The first group contains modes for normal text, either plain or with mark-up. It includes Text mode, HTML mode, SGML mode, TeX mode and Outline mode. The second group contains modes for specific programming languages. These include Lisp mode (which has several variants), C mode, Fortran mode, and others. The third group consists of major modes that are not associated directly with files; they are used in buffers created for specific purposes by Emacs. Examples include Dired mode for buffers made by Dired (see Dired, the Directory Editor), Message mode for buffers made by C-x m (see Sending Mail), and Shell mode for buffers used to communicate with an inferior shell process (see Interactive Subshell).

Usually, the major mode is automatically set by Emacs, when you first visit a file or create a buffer (see Choosing File Modes). You can explicitly select a new major mode by using an M-x command. Take the name of the mode and add -mode to get the name of the command to select that mode (e.g., M-x lisp-mode enters Lisp mode). Since every buffer has exactly one major mode, there is no way to “turn off” a major mode; instead you must switch to a different one.

The value of the buffer-local variable major-mode is a symbol with the same name as the major mode command (e.g., lisp-mode). This variable is set automatically; you should not change it yourself.

The default value of major-mode determines the major mode to use for files that do not specify a major mode, and for new buffers created with C-x b. Normally, this default value is the symbol fundamental-mode, which specifies Fundamental mode. You can change this default value via the Customization interface (see Easy Customization Interface), or by adding a line like this to your init file (see The Emacs Initialization File):

(setq-default major-mode 'text-mode)

If the default value of major-mode is nil, the major mode is taken from the previously current buffer.

Specialized major modes often change the meanings of certain keys to do something more suitable for the mode. For instance, programming language modes bind TAB to indent the current line according to the rules of the language (see Indentation). The keys that are commonly changed are TAB, DEL, and C-j. Many modes also define special commands of their own, usually bound to key sequences whose prefix key is C-c (see Keys). Major modes can also alter user options and variables; for instance, programming language modes typically set a buffer-local value for the variable comment-start, which determines how source code comments are delimited (see Manipulating Comments).

To view the documentation for the current major mode, including a list of its key bindings, type C-h m (describe-mode). See Other Help Commands.

Every major mode, apart from Fundamental mode, defines a mode hook, a customizable list of Lisp functions to run each time the mode is enabled in a buffer. See Hooks, for more information about hooks. Each mode hook is named after its major mode, e.g., Fortran mode has fortran-mode-hook. Furthermore, all text-based major modes run text-mode-hook, and many programming language modes ¹³ (including all those distributed with Emacs) run prog-mode-hook, prior to running their own mode hooks. Hook functions can look at the value of the variable major-mode to see which mode is actually being entered.

Mode hooks are commonly used to enable minor modes (see Minor Modes). For example, you can put the following lines in your init file to enable Flyspell minor mode in all text-based major modes (see Checking and Correcting Spelling), and ElDoc minor mode in Emacs Lisp mode (see Programming Language Documentation Lookup):

(add-hook 'text-mode-hook 'flyspell-mode)
(add-hook 'emacs-lisp-mode-hook 'eldoc-mode)

Next: Choosing File Modes, Previous: Major Modes, Up: Major and Minor Modes   [Contents][Index]

25.2 Minor Modes ¶

A minor mode is an optional editing mode that alters the behavior of Emacs in some well-defined way. Unlike major modes, any number of minor modes can be in effect at any time. Some minor modes are buffer-local, and can be turned on (enabled) in certain buffers and off (disabled) in others. Other minor modes are global: while enabled, they affect everything you do in the Emacs session, in all buffers. Most minor modes are disabled by default, but a few are enabled by default.

Most buffer-local minor modes say in the mode line when they are enabled, just after the major mode indicator. For example, ‘Fill’ in the mode line means that Auto Fill mode is enabled. See The Mode Line.

Like major modes, each minor mode is associated with a mode command, whose name consists of the mode name followed by ‘-mode’. For instance, the mode command for Auto Fill mode is auto-fill-mode. But unlike a major mode command, which simply enables the mode, the mode command for a minor mode can either enable or disable it:

• If you invoke the mode command directly with no prefix argument (either via M-x, or by binding it to a key and typing that key; see Customizing Key Bindings), that toggles the minor mode. The minor mode is turned on if it was off, and turned off if it was on.
• If you invoke the mode command with a prefix argument, the minor mode is unconditionally turned off if that argument is zero or negative; otherwise, it is unconditionally turned on.
• If the mode command is called via Lisp, the minor mode is unconditionally turned on if the argument is omitted or nil. This makes it easy to turn on a minor mode from a major mode’s mode hook (see Major Modes). A non-nil argument is handled like an interactive prefix argument, as described above.

Most minor modes also have a mode variable, with the same name as the mode command. Its value is non-nil if the mode is enabled, and nil if it is disabled. In general, you should not try to enable or disable the mode by changing the value of the mode variable directly in Lisp; you should run the mode command instead. However, setting the mode variable through the Customize interface (see Easy Customization Interface) will always properly enable or disable the mode, since Customize automatically runs the mode command for you.

The following is a list of some buffer-local minor modes:

• Abbrev mode automatically expands text based on pre-defined abbreviation definitions. See Abbrevs.
• Auto Fill mode inserts newlines as you type to prevent lines from becoming too long. See Filling Text.
• Auto Save mode saves the buffer contents periodically to reduce the amount of work you can lose in case of a crash. See Auto-Saving: Protection Against Disasters.
• Electric Quote mode automatically converts quotation marks. For example, it requotes text typed `like this' to text ‘like this’. You can control what kind of text it operates in, and you can disable it entirely in individual buffers. See Quotation Marks.
• Enriched mode enables editing and saving of formatted text. See Enriched Text.
• Flyspell mode automatically highlights misspelled words. See Checking and Correcting Spelling.
• Font-Lock mode automatically highlights certain textual units found in programs. It is enabled globally by default, but you can disable it in individual buffers. See Text Faces.
• Display Line Numbers mode is a convenience wrapper around display-line-numbers, setting it using the value of display-line-numbers-type. See Customization of Display.
• Outline minor mode provides similar facilities to the major mode called Outline mode. See Outline Mode.
• Overwrite mode causes ordinary printing characters to replace existing text instead of shoving it to the right. For example, if point is in front of the ‘B’ in ‘FOOBAR’, then in Overwrite mode typing a G changes it to ‘FOOGAR’, instead of producing ‘FOOGBAR’ as usual. In Overwrite mode, the command C-q inserts the next character whatever it may be, even if it is a digit—this gives you a way to insert a character instead of replacing an existing character. The mode command, overwrite-mode, is bound to the Insert key.
• Binary Overwrite mode is a variant of Overwrite mode for editing binary files; it treats newlines and tabs like other characters, so that they overwrite other characters and can be overwritten by them. In Binary Overwrite mode, digits after C-q specify an octal character code, as usual.
• Visual Line mode performs word wrapping, causing long lines to be wrapped at word boundaries. See Visual Line Mode.

And here are some useful global minor modes:

• Column Number mode enables display of the current column number in the mode line. See The Mode Line.
• Delete Selection mode causes text insertion to first delete the text in the region, if the region is active. See Operating on the Region.
• Icomplete mode displays an indication of available completions when you are in the minibuffer and completion is active. See Fast minibuffer selection.
• Line Number mode enables display of the current line number in the mode line. It is enabled by default. See The Mode Line.
• Menu Bar mode gives each frame a menu bar. It is enabled by default. See Menu Bars.
• Scroll Bar mode gives each window a scroll bar. It is enabled by default, but the scroll bar is only displayed on graphical terminals. See Scroll Bars.
• Tool Bar mode gives each frame a tool bar. It is enabled by default, but the tool bar is only displayed on graphical terminals. See Tool Bars.
• Window Tool Bar mode gives windows a tool bar. See Window Tool Bar.
• Tab Bar mode gives each frame a tab bar. See Tab Bars.
• Tab Line mode gives each window a tab line. See Window Tab Line.
• Transient Mark mode highlights the region, and makes many Emacs commands operate on the region when the mark is active. It is enabled by default. See The Mark and the Region.

Previous: Minor Modes, Up: Major and Minor Modes   [Contents][Index]

25.3 Choosing File Modes ¶

When you visit a file, Emacs chooses a major mode automatically. Normally, it makes the choice based on the file name—for example, files whose names end in ‘.c’ are normally edited in C mode—but sometimes it chooses the major mode based on special text in the file. This special text can also be used to enable buffer-local minor modes.

Here is the exact procedure:

First, Emacs checks whether the file contains file-local mode variables. See Local Variables in Files. If there is a file-local variable that specifies a major mode, then Emacs uses that major mode, ignoring all other criteria. There are several methods to specify a major mode using a file-local variable; the simplest is to put the mode name in the first nonblank line, preceded and followed by ‘-*-’. Other text may appear on the line as well. For example,

; -*-Lisp-*-

tells Emacs to use Lisp mode. Note how the semicolon is used to make Lisp treat this line as a comment. You could equivalently write

; -*- mode: Lisp;-*-

You can also use file-local variables to specify buffer-local minor modes, by using eval specifications. For example, this first nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode:

; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-

Note, however, that it is usually inappropriate to enable minor modes this way, since most minor modes represent individual user preferences. If you personally want to use a minor mode for a particular file type, it is better to enable the minor mode via a major mode hook (see Major Modes).

Second, Emacs checks whether the file’s extension matches an entry in any directory-local auto-mode-alist. These are found using the .dir-locals.el facility (see Per-Directory Local Variables).

Third, if there is no file variable specifying a major mode, Emacs checks whether the file’s contents begin with ‘#!’. If so, that indicates that the file can serve as an executable shell command, which works by running an interpreter named on the file’s first line (the rest of the file is used as input to the interpreter). Therefore, Emacs tries to use the interpreter name to choose a mode. For instance, a file that begins with ‘#!/usr/bin/perl’ is opened in Perl mode. The variable interpreter-mode-alist specifies the correspondence between interpreter program names and major modes.

When the first line starts with ‘#!’, you usually cannot use the ‘-*-’ feature on the first line, because the system would get confused when running the interpreter. So Emacs looks for ‘-*-’ on the second line in such files as well as on the first line. The same is true for man pages which start with the magic string ‘'\"’ to specify a list of troff preprocessors.

Fourth, Emacs tries to determine the major mode by looking at the text at the start of the buffer, based on the variable magic-mode-alist. By default, this variable is nil (an empty list), so Emacs skips this step; however, you can customize it in your init file (see The Emacs Initialization File). The value should be a list of elements of the form

(regexp . mode-function)

where regexp is a regular expression (see Syntax of Regular Expressions), and mode-function is a major mode command. If the text at the beginning of the file matches regexp, Emacs chooses the major mode specified by mode-function.

Alternatively, an element of magic-mode-alist may have the form

(match-function . mode-function)

where match-function is a Lisp function that is called at the beginning of the buffer; if the function returns non-nil, Emacs set the major mode with mode-function.

Fifth—if Emacs still hasn’t found a suitable major mode—it looks at the file’s name. The correspondence between file names and major modes is controlled by the variable auto-mode-alist. Its value is a list in which each element has this form,

(regexp . mode-function)

or this form,

(regexp mode-function flag)

For example, one element normally found in the list has the form ("\\.c\\'" . c-mode), and it is responsible for selecting C mode for files whose names end in .c. (Note that ‘\\’ is needed in Lisp syntax to include a ‘\’ in the string, which must be used to suppress the special meaning of ‘.’ in regexps.)

If the element has the form (regexp mode-function flag) and flag is non-nil, then after calling mode-function (if it is non-nil), Emacs discards the suffix that matched regexp and searches the list again for another match. This “recursive extension stripping” is used for files which have multiple extensions, and the “outer” extension hides the “inner” one that actually specifies the right mode. For example, backup files and GPG-encrypted files with .gpg extension use this feature.

On GNU/Linux and other systems with case-sensitive file names, Emacs performs a case-sensitive search through auto-mode-alist; if this search fails, it performs a second case-insensitive search through the alist. To suppress the second search, change the variable auto-mode-case-fold to nil. On systems with case-insensitive file names, such as Microsoft Windows, Emacs performs a single case-insensitive search through auto-mode-alist.

Finally, if Emacs still hasn’t found a major mode to use, it compares the text at the start of the buffer to the variable magic-fallback-mode-alist. This variable works like magic-mode-alist, described above, except that it is consulted only after auto-mode-alist. By default, magic-fallback-mode-alist contains forms that check for image files, HTML/XML/SGML files, PostScript files, and Unix style Conf files.

Once a major mode is found, Emacs does a final check to see if the mode has been remapped by major-mode-remap-alist, in which case it uses the remapped mode instead. This is used when several different major modes can be used for the same file type, so you can specify which mode you prefer. Note that this remapping affects the major mode found by all of the methods described above, so, for example, the mode specified by the first line of the file will not necessarily be the mode actually turned on in the buffer visiting the file. (This remapping also affects revert-buffer, see Reverting a Buffer.) When several modes are available for the same file type, you can tell Emacs about your major-mode preferences by customizing major-mode-remap-alist. For example, put this in your ~/.emacs init file (see The Emacs Initialization File)

  (add-to-list 'major-mode-remap-alist '(c-mode . c-ts-mode))

to force Emacs to invoke c-ts-mode when c-mode is specified by auto-mode-alist or by file-local variables. Conversely,

  (add-to-list 'major-mode-remap-alist '(c-mode))

will force Emacs to never remap c-mode to any other mode.

The default value of major-mode-remap-alist is nil, so no remapping takes place. However, loading some Lisp packages or features might introduce mode remapping, because Emacs assumes that loading those means the user prefers using an alternative mode. So for predictable behavior, we recommend that you always customize major-mode-remap-alist to express your firm preferences, because this variable overrides any remapping that Emacs might decide to perform internally.

As a convenience feature for enabling major modes based on the tree-sitter library (see Parsing Program Source in The Emacs Lisp Reference Manual), you can customize the user option treesit-enabled-modes to selectively enable or disable tree-sitter based modes: if the value is t, that enables all the available tree-sitter based modes; if it is a list of mode names, that enables only those modes. Customizing this option adds the corresponding mappings to major-mode-remap-alist such as remapping from c-mode to c-ts-mode (if you enable the latter). By default, this option’s value is nil, so no tree-sitter based modes are enabled.

Enabling a tree-sitter based mode means that visiting files in the corresponding programming language will automatically turn on that mode, instead of any non-tree-sitter based modes for the same language. For example, if you enable c-ts-mode, visiting C source files will turn on c-ts-mode instead of c-mode.

If you have changed the major mode of a buffer, you can return to the major mode Emacs would have chosen automatically, by typing M-x normal-mode. This is the same function that find-file calls to choose the major mode. If the buffer is visiting a file, this command also processes the file’s ‘-*-’ line and file-local variables list (if any). See Local Variables in Files. If the buffer doesn’t visit a file, the command processes only the major mode specification, if any, in the ‘-*-’ line and in the file-local variables list. M-x normal-mode takes the mode remapping into consideration, so if you customized major-mode-remap-alist after the buffer’s major mode was chosen by Emacs, normal-mode could turn on a mode that is different from the one Emacs chose originally.

The commands C-x C-w and set-visited-file-name change to a new major mode if the new file name implies a mode (see Saving Files). (C-x C-s does this too, if the buffer wasn’t visiting a file.) However, this does not happen if the buffer contents specify a major mode, and certain special major modes do not allow the mode to change. You can turn off this mode-changing feature by setting change-major-mode-with-file-name to nil.