fish 4.9 adds descriptions to abbreviation completions

The proposal for abbreviation descriptions started with commands its author used infrequently or in bursts. A terse shortcut was easy to forget, and its expanded command did not always explain its purpose. Pull request 11291, opened in March 2025, proposed adding a short explanation to the completion entry. Fish 4.9.0, released on September 3, includes that capability.

The release notes say abbreviation descriptions now appear in the completion pager. This is a change to discovery. A user who remembers part of a shortcut can see what it is for before accepting it, alongside the command text it represents.

Fish's searchable completion interface is one of the reasons I like it as a personal shell. Omer introduced me to it after years with Bash and Zsh, and the useful defaults were immediately appealing. Descriptions extend that approach to the shortcuts users define themselves. A personal abbreviation can carry a little of the explanation that would otherwise live in a comment in its configuration file.

The description explains the expansion

The 4.9.0 abbreviation reference documents --description=DESCRIPTION. Its value is added to the completion description in the pager. A simple abbreviation can now include both its replacement text and its purpose:

abbr --add --description='Switch Git branches' gco git checkout

The expansion remains git checkout. The description supplies additional language for recognizing the abbreviation. It does not become an argument to Git or alter the operation selected by the replacement. That separation lets the description say what the shortcut is for while the expansion retains the exact command text.

The original proposal used package-management examples to show why this helps. Different abbreviations represented operations such as installation and search. A pager showing only the replacement required the reader to decode those command flags. Adding a description allowed the author to name the intended operation directly.

This is especially useful for a shortcut that has not become habitual. An abbreviation name can be compact enough to type often while remaining poor documentation for someone seeing it after a long interval. The description provides a second way to recognize the intended choice without forcing the name itself to become a sentence.

The tradeoff is maintenance. A description is user-authored text, and changing the expansion does not establish that its explanation remains accurate. A misleading description could make a completion easier to choose for the wrong reason. Keeping the definition and its description together makes that relationship available during ordinary configuration review.

Abbreviations modify the editable command

Fish abbreviations expand typed input after Space or Enter. The reference explicitly says they do not expand in scripts. That makes them part of interactive editing, with behavior distinct from placing a function or executable on the command search path.

After expansion, the longer command is present in the command line. The user can inspect or edit it before execution when expansion occurs through Space. The default Control-Space binding inserts a space without expanding an abbreviation, which provides a way to enter the literal short text when that is the intended argument.

The distinction matters for documentation. A shortcut definition does not make a script containing the short name portable to another fish session. Scripts need the actual command or an explicitly available function. The new description improves the interactive choice, while the existing boundary between abbreviation expansion and script execution remains.

By default, abbreviations match in command position. The reference also supports an anywhere position and command-specific matching. Those settings determine where an abbreviation can expand. A description does not widen its scope, so an explanation in the pager should not imply that the same short token behaves identically in every argument context.

Function-backed abbreviations add another distinction. They invoke a named fish function to produce replacement text. A successful function result supplies the expansion, while an unsuccessful result leaves the token unchanged. For those definitions, a description can explain the transformation even when the final replacement depends on the matched token.

Definitions remain ordinary configuration

The versioned reference recommends storing abbreviation definitions in config.fish or another configuration file. It explains that saving them as universal variables is no longer supported, although existing variables can still be imported. The description option therefore belongs in the maintained definition alongside its matching and expansion rules.

That is a useful place for personal configuration to become more understandable. A reader can inspect the token, its scope, the replacement, and the explanation in the same command. The description should supply purpose that the expansion does not already make obvious. Repeating the expansion word for word would add little to the pager.

I value this form of customization because it keeps the shell's assistance attached to information the user controls. The shell supplies the pager and expansion mechanism. The author of the abbreviation supplies the local meaning of a shorthand name, which the shell cannot reliably infer from its spelling.

Terminal compatibility remains part of completion behavior

Fish 4.9 also stops requesting the kitty keyboard protocol on Konsole to mitigate problems in that terminal's implementation. The release-tag changelog names the affected Konsole version and documents an override through omit-term-workarounds. This is a targeted interoperability decision, independent of how abbreviation descriptions are stored.

The release also fixes slow completion in directories containing symlinks that take a long time to resolve, such as links to network-mounted files. A completion interface needs responsive candidate generation as well as useful descriptions. The two changes address different parts of the interaction, determining how soon choices appear and how well the user can distinguish them once they do.

For abbreviation authors, the new field is an opportunity to document the intended operation in the place where it is selected. A concise description can explain a rarely used flag combination or distinguish similar shortcuts. The expansion remains visible command text, and the description supplies context for deciding which definition to accept.