27.2.2.2 Changing an Option

Here is an example of what a user option looks like in the customization buffer:

Kill Ring Max: [Hide] 30
   [State]: this option is unchanged from its standard setting.
Maximum length of kill ring before oldest elements are thrown away.

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 load-path is a list of directories. Here is how it appears in the customization buffer:

Load Path:
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
[INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
[INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
[INS]
   [State]: this item has been changed outside the customization buffer.
List of directories to search for files to load....

Each directory in the list appears on a separate line, and each line has several editable or active fields.

You can edit any of the directory names. To delete a directory from the list, invoke ‘[DEL]’ on that line. To insert a new directory in the list, invoke ‘[INS]’ at the point where you want to insert it.

You can also invoke ‘[Current dir?]’ to switch between including a specific named directory in the path, and including nil in the path. (nil in a search path means “try the current directory.”)

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. The reason for this is that people have a tendency to type RET when they are finished editing a field. If you have occasion to insert a newline in 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 init file so as to set the option variable again each time you start Emacs. See Init File. 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 ‘Reset’ operation. There are actually three reset operations:

‘Reset to Current’

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.

‘Reset to Standard Settings’

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.

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:

 [Set] [Save] [Reset]  [Done]

Invoking ‘[Done]’ buries this customization 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.