28.2.4 Imenu

The Imenu facility offers a way to find the major definitions in a file by name. It is useful both in programming-language major modes, where the definitions are variables, functions, etc., and in text formatter major modes, where it treats each chapter, section, etc., as a definition. (See Find Identifier References, for a more powerful feature that handles multiple files together.)

If you type M-g i (imenu), it reads the name of a definition using the minibuffer, then moves point to that definition. You can use completion to specify the name; the command displays the list of matching valid names in the completions buffer. If the index is hierarchical, then by default the completion candidates are also shown hierarchically, as a nested list: first you need to choose a section, then a subsection, etc., and finally the name of the definition. However, if you set imenu-flatten to a non-nil value, then instead of the nested menu you can select a completion candidate from a flattened list of definitions. How the sections and subsections are shown in the flattened list of completion candidates depends on the value of imenu-flatten, which can be one of the following:

prefix

This shows each candidate prefixed by names of its section, subsection, subsubsection, etc., with each level separated from the next by the string that is the value of imenu-level-separator, by default ‘:’.

annotation

This shows the section names as annotations, following each definition name.

group

This shows the completion candidates grouped by their sections.

Alternatively, you can bind the command imenu to a mouse click. Then it displays mouse menus for you to select a definition name. You can also add the buffer’s index to the menu bar by calling imenu-add-menubar-index. If you want to have this menu bar item available for all buffers in a certain major mode, you can do this by adding imenu-add-menubar-index to its mode hook. But if you have done that, you will have to wait a little while each time you visit a file in that mode, while Emacs finds all the definitions in that buffer.

When you change the contents of a buffer, if you add or delete definitions, you can update the buffer’s index based on the new contents by invoking the ‘*Rescan*’ item in the menu. Rescanning happens automatically if you set imenu-auto-rescan to a non-nil value. There is no need to rescan because of small changes in the text.

imenu-auto-rescan will be disabled in buffers that are larger than imenu-auto-rescan-maxout in bytes, and scanning is stopped if it takes more than imenu-max-index-time seconds.

You can customize the way the menus are sorted by setting the variable imenu-sort-function. By default, names are ordered as they occur in the buffer; if you want alphabetic sorting, use the symbol imenu--sort-by-name as the value. You can also define your own comparison function by writing Lisp code.

You can also customize how Imenu completions are sorted by changing the variable completion-category-overrides and setting its display-sort-function for the category imenu.

If Eglot is activated for the current buffer’s project (see Working with Projects) and the current buffer’s major mode, Eglot provides its own facility for producing the buffer’s index based on the analysis of the program source by the language-server which manages the current buffer. See Eglot Features in Eglot: The Emacs LSP Client.

Imenu provides the information to guide Which Function mode (see Which Function Mode). The Speedbar can also use it (see Speedbar Frames).