Guides for

• New Students
• Students
• Faculty
• Staff
• IT Staff

Search the UBIT site

Questions and comments about this should be sent to: cit-webmaster@buffalo.edu
Privacy Accessibility Statement
Last updated:
Copyright © 2006
All Rights Reserved.

Documentation

Emacs

Introduction

GNU Emacs (or Emacs for short) is an advanced, feature-packed, customizable display text editor. Emacs allows you to edit several files simultaneously, open multiple session windows, define keyboard macros, and undo mistakes. Emacs is available on UBUnix. You must have a valid UBITName and Password to access UBUnix.

Initializing Emacs

To use Emacs on the UBUnix system, you must first set the terminal emulation. To do this, enter the following command at your UNIX prompt:
setenv term termtype

termtype is the desired terminal type. For computers in Public Computing Service Areas, the termtype should be set to vt100. If you are a frequent Emacs user, you may wish to add the following line to your .cshrc file:
vt100

If you wish to set Emacs as your default editor, add the following lines to your .cshrc file:
setenv EDITOR /util/bin/emacs
setenv VISUAL /util/bin/emacs
setenv ERROR_EDITOR /util/bin/emacs

Special Keys and Commands

Emacs commands make use of the Ctrl key and the META key (which is usually labeled Esc).

The following notation is used in this document:

If there is no META key on your keyboard, which is likely, press then release Esc, then press chr. If there is no Esc key, then simultaneously press the Ctrl key and the character [ instead.

The Undo Command

You can undo all sequential changes made in the text of a buffer. Pressing Ctrl x, then entering u, or pressing Ctrl _ both perform this function. The first iteration of this command will undo the last change. Repeating the command undoes progressive earlier changes. Any command other than an undo command breaks the sequence of the undo commands.

The Keyboard-Quit Command

Any Emacs command may be interrupted or aborted by pressing Ctrl g.

Repeating Commands

It is possible to repeatedly execute a command in Emacs without explicitly re-entering the command. To do this, press Ctrl u, enter #, then command-name.

command-name is the name of the command you wish to repeat, and # is the number of times you would like to repeat the command. If you wanted to delete five characters after the point, for example, you would press Ctrl u, enter 5, then press Ctrl d.

Starting Emacs

To launch Emacs, enter emacs at your UNIX prompt. Emacs will start up and display the default help message. Enter any key to clear the help message. You are now ready to create a file or modify an existing file.

Opening a File

If you would like to open a specific file with Emacs directly from the shell prompt, you can enter emacs filename.

filename is the name of the file you wish to open. If this file does not already exist in the current directory, Emacs will create it for you.

If you issue the emacs command without specifying a file, Emacs will open a file called *scratch*. This file cannot be saved. To save any work in Emacs, you must either edit an existing file or create a new file.

You can open an existing Emacs file by using the find-file command. This command is invoked by typing Ctrl x, then Ctrl f. Emacs will display the current directory in the mode line. Provide the name and directory of the file you wish to edit and press Return or Enter. You are now able to edit the text of the file. Alternately, you can click File at the top of your screen and select Open to search for readable files through the GUI (Graphical User Interface).

If you wish to edit a different file, whether it is new or existing, press Ctrl x, then Ctrl f again. This same command allows you to create a new file by entering a new filename. Emacs automatically saves the file that was open when you issued the Ctrl x, then Ctrl f command.

You can start up Emacs at a particular place in a file by using the plus command. This command consists of a plus sign (+) followed by a number. This command instructs Emacs to go to the specified line number in the file. The plus command is entered after the command emacs, but before any filenames. To start Emacs at line 150 of a file named fn, for example, you would enter the following at your UNIX prompt:
emacs +150 fn

The Emacs Screen

Emacs divides the session screen into several areas. The largest area contains the text you are editing. You will see a cursor (sometimes referred to as the point) designating your current position in the text. In order to edit text or insert commands, place the cursor so that it highlights the character or space immediately to the right of where you would like to enter or insert text.

Most terminal software programs only have one cursor, but Emacs may have several. If you are editing more than one file, each file wll have its own cursor. When multiple text windows are open, each window has its own cursor.

The mode line is the last line in a text window. It describes what occurs in that window. The mode line display looks like this:
----:---F1 filename (MajorMode)--Ln--%----

filename is the name of the file you are editing, and MajorMode is the current editing mode.

The characters to the left of the mode line indicate whether you have made changes to the file's contents. A series of dashes indicates that no changes have been made. The presence of any asterisks in the sequence indicates that changes have been made to the file.

The characters to the right of the MajorMode indicator simultaneously display the line (Ln) of the file upon which the cursor rests and the depth (%) of the file, measured as the percentage of the file that lies above the current cursor position. If the entire file is currently displayed on the screen, Emacs will display All; if the current buffer contains the beginning of the file, it will display Top; and if the current buffer contains the tail end of the file, the program will display Bottom.

The line at the bottom of the screen is the echo area. It displays small amounts of text, such as error messages or informative messages that explain the results of a command. It also serves as a mini buffer, allowing Emacs to read arguments for commands you have entered.

Buffers and Windows

Buffers

Every time you open a file in Emacs, the contents of that file reside in a buffer. By default, this buffer is given the exact same name as the opened file. Emacs allows you to have more than one buffer open at a time, enabling you to work on multiple files at once. Using the technique described in Starting Emacs, you can proceed to open more than one file at a time, where each file is stored in its own buffer. Opening more than one file does not result in the loss of previously opened buffers. To display a list of open buffers in Emacs, press Ctrl x, then Ctrl b.

A list of open buffers will be displayed. At this point press Ctrl x, then enter b.

You will then be prompted to enter the name of the buffer which you wish to change. Press Return or Enter to open the most recently visited buffer. Repeat this technique to cycle between many open buffers. Issuing the first of the two previously stated commands is not necessary to change buffers, but it is helpful if you do not remember the name of the buffer to which you wish to switch. To close the buffer list displayed by issuing the first command described in this section, read the next section on Windows.

Windows

Each Emacs window displays one buffer at a time. Pressing Ctrl x, then Ctrl b, as described in the previous section, opens a second Emacs window to display the list of available buffers. At any one time, one of the windows is the selected window; the buffer this window is displaying is the current buffer. To switch your selected window, press Ctrl x, then enter o.

You will see the solid black cursor switch windows. To return to a single window, press Ctrl x, then enter 1.

The selected window will once again take up the entire frame. To display a second window, press Ctrl x, then enter 2.

A second window will appear.

Navigating a File

The arrow keys allow you to move the cursor on the screen, but many shortcut commands allow you to navigate a file more quickly and easily than you could using the arrow keys alone.

The following commands are useful for navigating files and screens in Emacs:

In addition to paging through a file manually, you can go to a specific line number. To do this, press META x, then enter goto-line.

Emacs will prompt you with the following:
Goto-line:

Enter the number of the desired line and press Return or Enter.

Editing Text

The primary function of Emacs is the manipulation of text within a file. The following areas of Emacs take advantage of its powerful text editing capabilities and features.

Typing Text

Anything you enter is inserted directly into the text at the cursor's current location. If you wish to edit in typeover or overwrite mode, press META x, then enter overwrite-mode.

Text will now be entered directly over the existing text. Because overwrite mode is a minor mode, it is possible to return to insert mode by re-executing the command.

In Emacs, all of the characters you enter are inserted into the text to the left of the cursor. To delete text you have just inserted, use the Delete or Backspace key, which deletes the character to the left of the cursor.

To end a line and start a new one, press Return or Enter. When this key is used in the middle of a line, the line is broken into two lines at that point.

If you wish to insert a new line before the existing one, the best way is to make a blank line first and enter the text into it. The following are commands used to create and delete blank lines:

If you add too many characters to one line without breaking it by pressing Enter or Return, the line will occupy two (or more) lines on the screen with a backslash (\) at the extreme right margin of all but the last line. The backslash indicates that the following screen line is not really a distinct line in the file, but is the continuation of a line too long to fit the screen.

If you would like Emacs to move automatically to a new line when the text in the current line approaches the right-hand margin, you must invoke the wrap function. To execute it, press META x, then enter auto-fill-mode.

This function eliminates the need to press Return or Enter after each line has filled up with text.

Erasing Text (Killing and Deleting)

The following commands are useful for erasing text:

If you press Ctrl d at the end of a line, the return will be deleted, and that line and the next line will be joined together.

Recovering Text (Yanking)

Whenever you kill a section of text larger than a single character, Emacs stores it for you in a special buffer from which you may recall the section later.

To yank the text back or recover it, use the command Ctrl y. This command can be executed at any location in the file; you do not have to be in the original location to use the Ctrl y command. This is a useful way to move text around in a file.

The Ctrl y command brings back only the most recently killed text. However, previously killed text is lost. You can retrieve it by using the META y command. After you have used the Ctrl y command to recover the most recent kill, pressing META y will replace the yanked text with the previous kill. Pressing META y repeatedly brings back earlier and earlier kills.

Moving Text

Killing text and yanking it to a new position is an easy way to move it. You can yank a section of killed text any number of times to create copies in different places.

Sorting Text

Text may be sorted either alphabetically or in reverse alphabetical order. In both cases, text is sorted by the first letter on each line. This is known as line sorting.

To sort lines, you must first block off a region of text. See the section Setting a Mark (Blocking) for information on blocking. After you have blocked a region, you can execute a forward line sort by pressing META x, then entering sort-lines.

To execute a reverse line sort, block off the text and press ESC, enter 1, press META x, then enter sort-lines.

This executes the sort-lines function with the first parameter, which is reversed.

Searching for a String

Like other editors, Emacs has commands that allow you to search for occurrences of a specific string. The search command is incremental -- it begins to search for the string on a character-by-character basis as you enter it. The commands to search are:

Each command reads in characters, and then positions point at the first occurrence of the indicated character string. For example, if you press Ctrl s and then follow it with f, the cursor will move to the right of the first "f". When you add an i to this sequence, the cursor will move to the right of the first occurrence of the sequence "fi". To find the next occurrence of the indicated character string, enter the search command again (in this case, Ctrl s).

If you are in the middle of an incremental search and press Delete, the last character in the search string is erased, and the cursor position reverts to the last occurrence of the new string. This is a useful way to back up during a search. Alternately, one can use Ctrl s to page forward through a document, and Ctrl r during the same search to work backwards through the text.

A search is terminated by pressing Return or Enter.

Replacing Text

Global search and replace operations are powerful tools in Emacs, as they allow you to replace instances of one string in a file with another string. For example, to replace every instance of "foo" with "bar", press META x, then enter replace-string.

This command prompts you for Replace string: and Replace string with: strings. For example, you can enter foo and bar respectively.

If you wish to replace only some occurrences of foo, you cannot use an ordinary replace command. In addition to the replacement operation found in most editors, Emacs contains a query-replace option that allows you to replace one string sequence with another, prompting you for replacement at every occurrence of the indicated string. To execute this option, press META x, then enter query-replace.

This command prompts you for Query replace: and Query replace with: strings. Since these may contain new lines, you must terminate each string with either Esc or Ctrl d. Once you have entered the strings, Emacs moves the cursor to subsequent occurrences of foo and waits for you to respond. The commands you can enter when you are shown an occurrence of foo are listed below:

It may be necessary to replace line returns in the text. Because Return or Enter is used to end a search condition, there is a control command used to represent a return: pressing Ctrl j.

This command can be used at any point in the search string to represent Return or Enter.

Setting a Mark (Blocking)

It is often useful to work with one block of text at a time. Emacs allows you to set a mark at a particular place in the current document, and move up or down within a file in order to delineate a region of text. The area between the mark and the cursor is called a region.

The following commands are used to mark regions:

Spell Checker

There is an interactive spell checker in Emacs that is invoked according to a specific spell command. The spell checker can check a particular word, a single region, or the entire buffer (file). The following commands invoke the spell checker from within Emacs:

The spell checker offers suggestions, as well as the opportunity to edit errors.

If the spelling for a single word is checked and corrected, Emacs substitutes the corrected spelling for the old one throughout the area checked.

File and Directory Operations

Emacs has extended commands used to perform many operations on files. Some of them are listed below:

You can change the preset working directory by means of the change directory command, pressing Ctrl c, then Ctrl d. After you execute this command, Emacs will prompt you for a directory name. Once you have provided a directory name, your new directory will appear in the second line of the echo area. Some of the more useful directory commands are:

To change to your login directory, press Return or Enter when prompted for a directory name.

Modes

Emacs has both major and minor modes. The major modes are mutually exclusive sets of options, each of which configures Emacs for editing a certain type of text. A minor mode is an optional feature of Emacs that can be switched on or off independently of other modes in operation.

Major Modes

A major mode changes the ways in which Emacs will interpret certain keys in order to help the user conform to a writing standard or program in a particular language. There are major modes for numerous programming languages and writing styles. Some major modes available in Emacs are:

• fundamental
• lisp-interactive
• c-mode
• lisp-mode
• modula-2-mode
• latex-mode
• tex-mode
• HTML
• text-mode

Fundamental mode is the least specialized major mode, and is also the default Emacs mode. It has no variable settings, so each Emacs option is in its default state.

Minor Modes

Minor modes operate independently of other modes and activate some of the more convenient features of Emacs. Some of the minor modes available in Emacs are:

• auto-fill-mode
• auto-save-mode
• overwrite-mode

Selecting Modes

To select a mode in Emacs, press META x, then enter modename-mode.

modename is the name of the mode you wish to invoke. To select the major mode Lisp, for example, press META x, then enter lisp-mode.

You can select a major mode for the current buffer, but Emacs is capable of determining the optimal mode based on the name of the file or some text within the file itself. To turn on a minor mode, simply execute the desired mode command normally. To turn it off, execute the command again.

Customizing Emacs

All features customized during an editing session are lost when the session ends. To make the customization permanent, you must create an initialization file named .emacs to initialize the customization in each session.

Emacs loads the .emacs file found in your home or login directory. The file, if it exists, should contain Lisp code. Each Lisp expression takes the following form:
(function-name A1 A2 ...)

function-name is the name of the function, and A1, A2, etc., are arguments to that function. For example, (setq fill-column 63) calls the function setq, which is used to set the variable fill-column to 63.

The value of a variable can be a constant, another variable, or a function. Most variables are constants, which can be numbers, strings, characters, true, false, or other Lisp objects. Strings are one or more characters in double quotes, including new lines and special characters. For example, the following strings are used to represent common special characters:

Characters are different from strings and denoted by a question mark (?) followed by the character. For example, the sequence ?^ denotes the character ^. In addition, t stands for true and nil stands for false. A single quote (') must precede other Lisp objects to be considered constants rather than commands to interpret.

There are many Lisp expressions that could be included in a .emacs file. Some of the more useful of these expressions are listed below:

• (setq default major-mode 'text-mode)
  Makes text-mode the major mode for new buffers.
• (setq text-mode-hook 'turn-on-auto-fill)
  Turns on auto-fill when text-mode is selected.
• (global-set-key "\Ctrl c\Ctrl t1" 'indented-text-mode)
  Defines a key to start the major mode indented-text-mode.
• (global-unset0key "\Ctrl x\Ctrl v")
  Unsets a key to use the key sequence for another command prefix.

Saving Files

The following commands are used to save your file and exit Emacs:

Note that Ctrl z suspends Emacs, but this does not end your session. To return to a suspended session, use the command fg to bring it back to the foreground.

To recover after a crash by using the auto-save feature, where foo is your filename to be recovered and RET is the return key, press META x, enter recover-file RET foo RET yes RET, press Ctrl x, then Ctrl s.

Emacs implements the auto-save feature by backing up your file to a file of the same name but with a # appended to the front and rear of the file. For instance, a file named foo.c is auto-saved to #foo.c#. An auto-saved file can be opened just like any other file, but will retain this naming convention until changed by the user.

Printing

There are two ways to print from within Emacs. You can either print a region of text or the entire buffer (file).

To print a region of text, first mark the region, and press META x, then enter print-region.

To print the entire buffer, press META x, then enter print-buffer.

In order to use these commands, you must first set the variable known as lpr-switches. To set this variable, press META x, then enter set-variable.

When Emacs prompts you for the variable to set, enter lpr-switches.

Emacs will then ask you what value to set for lpr-switches. Enter '("-Pprinter-name")

printer-name is the name of the printer to which you want your text printed. The default Public Computing Service Area printer is named bell, located in Bell 101. For more information on printing, see the CIT document UNIX Printing.

If you would like these defaults to set up automatically every time you run Emacs, add the following line to your .emacs file:
(setq-default lpr-switches '("-Pprinter-name"))

printer-name is the name of the desired default printer.

Inline Help

The command Ctrl h provides extensive help within Emacs. You can add options to this command to get specific kinds of help.

One help option is Ctrl h. Pressing Ctrl h, then Ctrl h gives you help about using the help command itself by displaying a list of possible options in the echo area. Emacs then asks you to enter the character that corresponds to the kind of help you desire. Pressing a third Ctrl h sequence displays an explanation of each option. At this point, Emacs will wait for you to enter an option.

There are four basic help functions in Emacs. These functions are:

These options are explained below. Try the help options if you want to learn more about Emacs.

To clear a help window, use the press Ctrl x, then enter 1 . You can exit help at any time by pressing Ctrl g.

Tutorial

Pressing Ctrl h, then entering t starts the interactive Emacs tutorial. The tutorial is a file that can be read just like any other file.

To exit the tutorial, press Ctrl x, then Ctrl c, just as you would exit another Emacs file. Emacs gives you the option of marking your place in the tutorial and saving the tutorial in your home directory. You can also print the tutorial for later reference. See the section Printing for information on printing a file.

Key Documentation

The most basic Ctrl h options are c and k. The c option is used to obtain a brief description of a command, while the k option is used to obtain full documentation for a command.

To obtain a brief description for a specific key or key combination, press Ctrl h, enter c, then key.

key is any keyboard key or combination of keys that constitutes an Emacs command. The name of the command represented by key(s) will appear in the echo area. For example, pressing Ctrl h, entering c, then pressing Ctrl f will display the following in the echo area:
Ctrl f runs the command forward-char

Because a command name illustrates the purpose of a command, pressing Ctrl h, entering c, then key is a good way to get a very brief description of what a particular key or key combination does.

To obtain documented online help on a specific key or key combination press Ctrl h, enter k, then key.

This command is similar to pressing Ctrl h, entering c, then key, but gives more information on the command indicated by key. Because this information is too large for the echo area, a second display window will appear. This window will contain the name of the command represented by key, as well as more detailed information on the command.

Command Name Documentation

The f option allows you to obtain information about a command that is not bound to a particular key. Commands that are not bound to a particular key are those that you would normally execute by pressing META x, then entering command-name, where command-name is the name of the command you wish to execute. To obtain information on such a command, press Ctrl h, enter f, then command-name.

command-name is the name of the command you would like information about.

In addition, pressing Ctrl h, enter w, then command-name allows you to discover shortcuts for a command.

This command displays those keys that are bound by the command command-name.

String Documentation (Apropos)

To obtain a list of commands for a particular topic, press Ctrl h, enter a, then string.

string is the topic for which you would like command information. To display a list of commands that contain the string file, for instance, press Ctrl h, enter a, then file.

This command will display a list of command names that contain the string file, including copy-file and find-file.

The a in pressing Ctrl h, then entering a stands for apropos. Pressing Ctrl h, then entering a runs the Lisp function command-apropos. In addition to each command name, Emacs will list a brief description of each command, including the keystroke combinations that will execute it.

Pressing Ctrl h, then entering a searches specifically for those functions that contain the specified string. This can cause problems if you have a command function in mind but do not know the specific command name. For this reason, it is best to search for general terms. If you are looking for commands for killing text backwards, but pressing Ctrl h, entering a, then kill-backwards does not reveal anything, try "kill", "backwards", or just "back" in place of "kill-backwards".

Additional Information

A wide variety of books cover more of Emacs than does this document. If you are looking for one of these books, you should first check the University at Buffalo libraries. You can also purchase introductory Emacs books at most local bookstores with computing sections.

The GNU Emacs manual is available online as a reference at

http://www.gnu.org/software/emacs/manual.

Many newsgroups contain information that can expand your knowledge of Emacs:

• comp.emacs
• gnu.emacs.announce
• gnu.emacs.bug
• gnu.emacs.gnews
• gnu.emacs.gnus
• gnu.emacs.help

CIT also offers a number of tutorial and reference documents at no additional charge on the CIT Documentation web site

http://wings.buffalo.edu/computing/Documentation/.

Document Information