A variable is a Lisp symbol which has a value. The symbol's
name is also called the name of the variable. A variable name can
contain any characters that can appear in a file, but conventionally
variable names consist of words separated by hyphens. A variable can
have a documentation string which describes what kind of value it should
have and how the value will be used.

Lisp allows any variable to have any kind of value, but most variables
that Emacs uses require a value of a certain type. Often the value should
always be a string, or should always be a number. Sometimes we say that a
certain feature is turned on if a variable is "non-nil," meaning
that if the variable's value is nil, the feature is off, but the
feature is on for any other value. The conventional value to use to
turn on the feature--since you have to pick one particular value when you
set the variable--is t.

Emacs uses many Lisp variables for internal record keeping, as any
Lisp program must, but the most interesting variables for you are the
ones that exist for the sake of customization. Emacs does not (usually)
change the values of these variables; instead, you set the values, and
thereby alter and control the behavior of certain Emacs commands. These
variables are called user options. Most user options are
documented in this manual, and appear in the Variable Index
(Variable Index).

One example of a variable which is a user option is fill-column, which
specifies the position of the right margin (as a number of characters from
the left margin) to be used by the fill commands (Section 23.5).

Display the value and documentation of variable var
(describe-variable).

M-x set-variable RETvarRETvalueRET

Change the value of variable var to value.

To examine the value of a single variable, use C-h v
(describe-variable), which reads a variable name using the
minibuffer, with completion. It displays both the value and the
documentation of the variable. For example,

C-h v fill-column RET

displays something like this:

fill-column's value is 75
Documentation:
*Column beyond which automatic line-wrapping should happen.
Automatically becomes buffer-local when set in any fashion.

The star at the beginning of the documentation indicates that this
variable is a user option. C-h v is not restricted to user
options; it allows any variable name.

The most convenient way to set a specific user option is with M-x
set-variable. This reads the variable name with the minibuffer (with
completion), and then reads a Lisp expression for the new value using
the minibuffer a second time. For example,

M-x set-variable RET fill-column RET 75 RET

sets fill-column to 75.

M-x set-variable is limited to user option variables, but you can
set any variable with a Lisp expression, using the function setq.
Here is a setq expression to set fill-column:

(setq fill-column 75)

To execute an expression like this one, go to the *scratch*
buffer, type in the expression, and then type C-j. Section 25.9.

Setting variables, like all means of customizing Emacs except where
otherwise stated, affects only the current Emacs session.

A convenient way to find the user option variables that you want to
change, and then change them, is with M-x customize. This command
creates a customization buffer with which you can browse through
the Emacs user options in a logically organized structure, then edit and
set their values. You can also use the customization buffer to save
settings permanently. (Not all Emacs user options are included in this
structure as of yet, but we are adding the rest.)

The appearance of the example buffers in the following is typically
different under a window system where faces can be used to indicate the
active fields and other features.

For customization purposes, user options are organized into
groups to help you find them. Groups are collected into bigger
groups, all the way up to a master group called Emacs.

M-x customize creates a customization buffer that shows the
top-level Emacs group and the second-level groups immediately
under it. It looks like this, in part:

/- Emacs group: ---------------------------------------------------\
[State]: visible group members are all at standard settings.
Customization of the One True Editor.
See also [Manual].
Editing group: [Go to Group]
Basic text editing facilities.
External group: [Go to Group]
Interfacing to external utilities.
more second-level groups
\- Emacs group end ------------------------------------------------/

This says that the buffer displays the contents of the Emacs
group. The other groups are listed because they are its contents. But
they are listed differently, without indentation and dashes, because
their contents are not included. Each group has a single-line
documentation string; the Emacs group also has a [State]
line.

Most of the text in the customization buffer is read-only, but it
typically includes some editable fields that you can edit. There
are also active fields; this means a field that does something
when you invoke it. To invoke an active field, either click on it
with Mouse-1, or move point to it and type RET.

For example, the phrase [Go to Group] that appears in a
second-level group is an active field. Invoking the [Go to
Group] field for a group creates a new customization buffer, which
shows that group and its contents. This field is a kind of hypertext
link to another group.

The Emacs group does not include any user options itself, but
other groups do. By examining various groups, you will eventually find
the options and faces that belong to the feature you are interested in
customizing. Then you can use the customization buffer to set them.

You can view the structure of customization groups on a larger scale
with M-x customize-browse. This command creates a special kind of
customization buffer which shows only the names of the groups (and
options and faces), and their structure.

In this buffer, you can show the contents of a group by invoking
[+]. When the group contents are visible, this button changes to
[-]; invoking that hides the group contents.

Each group, option or face name in this buffer has an active field
which says [Group], [Option] or [Face]. Invoking
that active field creates an ordinary customization buffer showing just
that group and its contents, just that option, or just that face.
This is the way to set values in it.

The text following [Hide], 30 in this case, indicates
the current value of the option. If you see [Show] instead of
[Hide], it means that the value is hidden; the customization
buffer initially hides values that take up several lines. Invoke
[Show] to show the value.

The line after the option name indicates the customization state
of the option: in the example above, it says you have not changed the
option yet. The word [State] at the beginning of this line is
active; you can get a menu of various operations by invoking it with
Mouse-1 or RET. These operations are essential for
customizing the variable.

The line after the [State] line displays the beginning of the
option's documentation string. If there are more lines of
documentation, this line ends with [More]; invoke this to show
the full documentation string.

To enter a new value for Kill Ring Max, move point to the value
and edit it textually. For example, you can type M-d, then insert
another number.

When you begin to alter the text, you will see the [State] line
change to say that you have edited the value:

[State]: you have edited the value as text, but not set the option.

Editing the value does not actually set the option variable. To do
that, you must set the option. To do this, invoke the word
[State] and choose Set for Current Session.

The state of the option changes visibly when you set it:

[State]: you have set this option, but not saved it for future sessions.

You don't have to worry about specifying a value that is not valid;
setting the option checks for validity and will not really install an
unacceptable value.

While editing a value or field that is a file name, directory name,
command name, or anything else for which completion is defined, you can
type M-TAB (widget-complete) to do completion.

Some options have a small fixed set of possible legitimate values.
These options don't let you edit the value textually. Instead, an
active field [Value Menu] appears before the value; invoke this
field to edit the value. For a boolean "on or off" value, the active
field says [Toggle], and it changes to the other value.
[Value Menu] and [Toggle] edit the buffer; the changes
take effect when you use the Set for Current Session operation.

Some options have values with complex structure. For example, the
value of file-coding-system-alist is an association list. Here
is how it appears in the customization buffer:

Each association in the list appears on four lines, with several
editable or "active" fields. You can edit the regexps and coding
systems using ordinary editing commands. You can also invoke
[Value Menu] to switch to a kind of value--for instance, to
specify a function instead of a pair of coding systems.

To delete an association from the list, invoke the [DEL] button
for that item. To add an association, invoke [INS] at the
position where you want to add it. There is an [INS] button
between each pair of association, another at the beginning and another
at the end, so you can add the new association at any position in the
list.

Two special commands, TAB and S-TAB, are useful for
moving through the customization buffer. TAB
(widget-forward) moves forward to the next active or editable
field; S-TAB (widget-backward) moves backward to the
previous active or editable field.

Typing RET on an editable field also moves forward, just like
TAB. We set it up this way because people often type RET
when they are finished editing a field. To insert a newline within an
editable field, use C-o or C-q C-j.

Setting the option changes its value in the current Emacs session;
saving the value changes it for future sessions as well. This
works by writing code into your ~/.emacs file so as to set the
option variable again each time you start Emacs. To save the option,
invoke [State] and select the Save for Future Sessions
operation.

You can also restore the option to its standard value by invoking
[State] and selecting the Erase Customization
operation. There are actually three reset operations:

Reset

If you have made some modifications and not yet set the option,
this restores the text in the customization buffer to match
the actual value.

Reset to Saved

This restores the value of the option to the last saved value,
and updates the text accordingly.

Erase Customization

This sets the option to its standard value, and updates the text
accordingly. This also eliminates any saved value for the option,
so that you will get the standard value in future Emacs sessions.

Sometimes it is useful to record a comment about a specific
customization. Use the Add Comment item from the
[State] menu to create a field for entering the comment. The
comment you enter will be saved, and displayed again if you again view
the same option in a customization buffer, even in another session.

The state of a group indicates whether anything in that group has been
edited, set or saved. You can select Set for Current Session,
Save for Future Sessions and the various kinds of Reset
operation for the group; these operations on the group apply to all
options in the group and its subgroups.

Near the top of the customization buffer there are two lines
containing several active fields:

Invoking [Finish] either buries or kills this customization
buffer according to the setting of the option
custom-buffer-done-function; the default is to bury the buffer.
Each of the other fields performs an operation--set, save or
reset--on each of the items in the buffer that could meaningfully be
set, saved or reset.

In addition to user options, some customization groups also include
faces. When you show the contents of a group, both the user options and
the faces in the group appear in the customization buffer. Here is an
example of how a face looks:

Each face attribute has its own line. The [x] field
before the attribute name indicates whether the attribute is
enabled; X means that it is. You can enable or disable the
attribute by invoking that field. When the attribute is enabled, you
can change the attribute value in the usual ways.

On a black-and-white display, the colors you can use for the
background are black, white, gray, gray1,
and gray3. Emacs supports these shades of gray by using
background stipple patterns instead of a color.

Setting, saving and resetting a face work like the same operations for
options (Section 32.2.2.2).

A face can specify different appearances for different types of
display. For example, a face can make text red on a color display, but
use a bold font on a monochrome display. To specify multiple
appearances for a face, select Show Display Types in the menu you
get from invoking [State].

Another more basic way to set the attributes of a specific face is
with M-x modify-face. This command reads the name of a face, then
reads the attributes one by one. For the color and stipple attributes,
the attribute's current value is the default--type just RET if
you don't want to change that attribute. Type none if you want
to clear out the attribute.

Instead of finding the options you want to change by moving down
through the structure of groups, you can specify the particular option,
face or group that you want to customize.

M-x customize-option REToptionRET

Set up a customization buffer with just one option, option.

M-x customize-face RETfaceRET

Set up a customization buffer with just one face, face.

M-x customize-group RETgroupRET

Set up a customization buffer with just one group, group.

M-x customize-apropos RETregexpRET

Set up a customization buffer with all the options, faces and groups
that match regexp.

M-x customize-changed-options RETversionRET

Set up a customization buffer with all the options, faces and groups
whose meaning has changed since Emacs version version.

M-x customize-saved

Set up a customization buffer containing all options and faces that you
have saved with customization buffers.

M-x customize-customized

Set up a customization buffer containing all options and faces that you
have customized but not saved.

If you want to alter a particular user option variable with the
customization buffer, and you know its name, you can use the command
M-x customize-option and specify the option name. This sets up
the customization buffer with just one option--the one that you asked
for. Editing, setting and saving the value work as described above, but
only for the specified option.

Likewise, you can modify a specific face, chosen by name, using
M-x customize-face.

You can also set up the customization buffer with a specific group,
using M-x customize-group. The immediate contents of the chosen
group, including option variables, faces, and other groups, all appear
as well. However, these subgroups' own contents start out hidden. You
can show their contents in the usual way, by invoking [Show].

To control more precisely what to customize, you can use M-x
customize-apropos. You specify a regular expression as argument; then
all options, faces and groups whose names match this regular expression
are set up in the customization buffer. If you specify an empty regular
expression, this includes all groups, options and faces in the
customization buffer (but that takes a long time).

When you upgrade to a new Emacs version, you might want to customize
new options and options whose meanings or default values have changed.
To do this, use M-x customize-changed-options and specify a
previous Emacs version number using the minibuffer. It creates a
customization buffer which shows all the options (and groups) whose
definitions have been changed since the specified version.

If you change option values and then decide the change was a mistake,
you can use two special commands to revisit your previous changes. Use
customize-saved to look at the options and faces that you have
saved. Use M-x customize-customized to look at the options and
faces that you have set but not saved.

Hooks are an important mechanism for customization of Emacs. A
hook is a Lisp variable which holds a list of functions, to be called on
some well-defined occasion. (This is called running the hook.)
The individual functions in the list are called the hook functions
of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
starts up, so the only hook functions in any given hook are the ones you
explicitly put there as customization.

Most major modes run one or more mode hooks as the last step of
initialization. This makes it easy for you to customize the behavior of
the mode, by setting up a hook function to override the local variable
assignments already made by the mode. But hooks are also used in other
contexts. For example, the hook suspend-hook runs just before
Emacs suspends itself (Section 6.1).

Most Emacs hooks are normal hooks. This means that running the
hook operates by calling all the hook functions, unconditionally, with
no arguments. We have made an effort to keep most hooks normal so that
you can use them in a uniform way. Every variable in Emacs whose name
ends in -hook is a normal hook.

There are also a few abnormal hooks. These variables' names end
in -hooks or -functions, instead of -hook. What
makes these hooks abnormal is that there is something peculiar about the
way its functions are called--perhaps they are given arguments, or
perhaps the values they return are used in some way. For example,
find-file-not-found-hooks (Section 16.2) is abnormal because
as soon as one hook function returns a non-nil value, the rest
are not called at all. The documentation of each abnormal hook variable
explains in detail what is peculiar about it.

The recommended way to add a hook function to a hook (either normal or
abnormal) is by calling add-hook. You can use any valid Lisp
function as the hook function, provided it can handle the proper number
of arguments (zero arguments, in the case of a normal hook). Of course,
not every Lisp function is useful in any particular hook.

For example, here's how to set up a hook to turn on Auto Fill mode
when entering Text mode and other modes based on Text mode:

(add-hook 'text-mode-hook 'turn-on-auto-fill)

The next example shows how to use a hook to customize the indentation
of C code. (People often have strong personal preferences for one
format compared to another.) Here the hook function is an anonymous
lambda expression.

It is best to design your hook functions so that the order in which
they are executed does not matter. Any dependence on the order is
"asking for trouble." However, the order is predictable: the most
recently added hook functions are executed first.

Mark variable var so that setting it will make it local to the
buffer that is current at that time.

Almost any variable can be made local to a specific Emacs
buffer. This means that its value in that buffer is independent of its
value in other buffers. A few variables are always local in every
buffer. Every other Emacs variable has a global value which is in
effect in all buffers that have not made the variable local.

M-x make-local-variable reads the name of a variable and makes it
local to the current buffer. Further changes in this buffer will not
affect others, and further changes in the global value will not affect this
buffer.

M-x make-variable-buffer-local reads the name of a variable and
changes the future behavior of the variable so that it will become local
automatically when it is set. More precisely, once a variable has been
marked in this way, the usual ways of setting the variable automatically
do make-local-variable first. We call such variables
per-buffer variables.

Major modes (Chapitre 21) always make variables local to the
buffer before setting the variables. This is why changing major modes
in one buffer has no effect on other buffers. Minor modes also work by
setting variables--normally, each minor mode has one controlling
variable which is non-nil when the mode is enabled (Section 32.1). For most minor modes, the controlling variable is per buffer.

Emacs contains a number of variables that are always per-buffer.
These include abbrev-mode, auto-fill-function,
case-fold-search, comment-column, ctl-arrow,
fill-column, fill-prefix, indent-tabs-mode,
left-margin, mode-line-format, overwrite-mode,
selective-display-ellipses, selective-display,
tab-width, and truncate-lines. Some other variables are
always local in every buffer, but they are used for internal
purposes.

A few variables cannot be local to a buffer because they are always
local to each display instead (Section 19.10). If you try to
make one of these variables buffer-local, you'll get an error message.

M-x kill-local-variable reads the name of a variable and makes
it cease to be local to the current buffer. The global value of the
variable henceforth is in effect in this buffer. Setting the major mode
kills all the local variables of the buffer except for a few variables
specially marked as permanent locals.

To set the global value of a variable, regardless of whether the
variable has a local value in the current buffer, you can use the Lisp
construct setq-default. This construct is used just like
setq, but it sets variables' global values instead of their local
values (if any). When the current buffer does have a local value, the
new global value may not be visible until you switch to another buffer.
Here is an example:

(setq-default fill-column 75)

setq-default is the only way to set the global value of a variable
that has been marked with make-variable-buffer-local.

Lisp programs can use default-value to look at a variable's
default value. This function takes a symbol as argument and returns its
default value. The argument is evaluated; usually you must quote it
explicitly. For example, here's how to obtain the default value of
fill-column:

A file can specify local variable values for use when you edit the
file with Emacs. Visiting the file checks for local variable
specifications; it automatically makes these variables local to the
buffer, and sets them to the values specified in the file.

There are two ways to specify local variable values: in the first
line, or with a local variables list. Here's how to specify them in the
first line:

-*- mode: modename; var: value; … -*-

You can specify any number of variables/value pairs in this way, each
pair with a colon and semicolon as shown above. mode:
modename; specifies the major mode; this should come first in the
line. The values are not evaluated; they are used literally.
Here is an example that specifies Lisp mode and sets two variables with
numeric values:

;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-

You can also specify the coding system for a file in this way: just
specify a value for the "variable" named coding. The "value"
must be a coding system name that Emacs recognizes. Section 20.6.

The eval pseudo-variable, described below, can be specified in
the first line as well.

In shell scripts, the first line is used to identify the script
interpreter, so you cannot put any local variables there. To accomodate
for this, when Emacs visits a shell script, it looks for local variable
specifications in the second line.

A local variables list goes near the end of the file, in the
last page. (It is often best to put it on a page by itself.) The local
variables list starts with a line containing the string Local
Variables:, and ends with a line containing the string End:. In
between come the variable names and values, one set per line, as
variable: value. The values are not
evaluated; they are used literally. If a file has both a local
variables list and a -*- line, Emacs processes everything
in the -*- line first, and everything in the local
variables list afterward.

As you see, each line starts with the prefix ;;; and each line
ends with the suffix ***. Emacs recognizes these as the prefix
and suffix based on the first line of the list, by finding them
surrounding the magic string Local Variables:; then it
automatically discards them from the other lines of the list.

The usual reason for using a prefix and/or suffix is to embed the
local variables list in a comment, so it won't confuse other programs
that the file is intended as input for. The example above is for a
language where comment lines start with ;;; and end with
***; the local values for comment-start and
comment-end customize the rest of Emacs for this unusual syntax.
Don't use a prefix (or a suffix) if you don't need one.

Two "variable names" have special meanings in a local variables
list: a value for the variable mode really sets the major mode,
and a value for the variable eval is simply evaluated as an
expression and the value is ignored. mode and eval are
not real variables; setting variables named mode and eval
in any other context has no special meaning. If mode is used to
set a major mode, it should be the first "variable" in the list.

You can use the mode "variable" to set minor modes as well as
major modes; in fact, you can use it more than once, first to set the
major mode and then to set minor modes which are specific to particular
buffers. But most minor modes should not be specified in the file in
any fashion, because they represent user preferences.

For example, you may be tempted to try to turn on Auto Fill mode with
a local variable list. That is a mistake. The choice of Auto Fill mode
or not is a matter of individual taste, not a matter of the contents of
particular files. If you want to use Auto Fill, set up major mode hooks
with your .emacs file to turn it on (when appropriate) for you
alone (Section 32.7). Don't use a local variable list to impose
your taste on everyone.

The start of the local variables list must be no more than 3000
characters from the end of the file, and must be in the last page if the
file is divided into pages. Otherwise, Emacs will not notice it is
there. The purpose of this rule is so that a stray Local
Variables: not in the last page does not confuse Emacs, and so that
visiting a long file that is all one page and has no local variables
list need not take the time to search the whole file.

Use the command normal-mode to reset the local variables and
major mode of a buffer according to the file name and contents,
including the local variables list if any. Section 21.1.

The variable enable-local-variables controls whether to process
local variables in files, and thus gives you a chance to override them.
Its default value is t, which means do process local variables in
files. If you set the value to nil, Emacs simply ignores local
variables in files. Any other value says to query you about each file
that has local variables, showing you the local variable specifications
so you can judge.

The eval "variable," and certain actual variables, create a
special risk; when you visit someone else's file, local variable
specifications for these could affect your Emacs in arbitrary ways.
Therefore, the option enable-local-eval controls whether Emacs
processes eval variables, as well variables with names that end
in -hook, -hooks, -function or -functions,
and certain other variables. The three possibilities for the option's
value are t, nil, and anything else, just as for
enable-local-variables. The default is maybe, which is
neither t nor nil, so normally Emacs does ask for
confirmation about file settings for these variables.