Skip to content

A zsh plugin for informative terminal window titles. ~1000 unique cloners as of July '24

License

Notifications You must be signed in to change notification settings

olets/zsh-window-title

Repository files navigation

zsh-window-title GitHub release (latest by date)

A zsh plugin for informative terminal window titles

Requirements

  • Zsh

Installation

Homebrew

brew install olets/tap/zsh-window-title

With a shell plugin manager

  1. Install zsh-window-title with a zsh plugin manager. Each has their own way of doing things. See your package manager's documentation or the zsh plugin manager plugin installation procedures gist.

    After adding the plugin to the manager, restart zsh:

    exec zsh

Manual

  1. Download the latest zsh-window-title binary
  2. Either
    • Put the file zsh-window-title in a directory in your PATH and add source zsh-window-title to your ~/.zshrc file
    • Add source the/path/to/zsh-window-title to your ~/.zshrc file
  3. Restart zsh:
    exec zsh

Usage

Once zsh-window-title is installed, your terminal window title will be

  • <parent dir>/<current dir> when nothing's running
  • <parent dir>/<current dir> - <first word of last run command> when something's running
  • <parent dir>/<current dir> - <first two words of last run command> when something's running and the first word of the last run command is one of the configured prefixes.

For example, after running sleep 2 in the directory ~/olets/zsh-window-title, the window title will be olets/zsh-window-title - sleep. After running sudo sleep 2, it will be olets/zsh-window-title - sudo sleep.

Note that the command is not parsed. If you run echo hello world && sleep 10, the window title will show echo for the duration, not echo for a moment and then sleep.

The number of path segments to show is configurable, and so are the prefixes. See Options.

macOS Terminal.app users

By default macOS's Terminal app will control the window title. Disable that by:

Preferences > Profiles > Window > Title --> uncheck everything.

Oh-My-Zsh users

By default OMZ will control the terminal window title. Disable that by adding

DISABLE_AUTO_TITLE=”true”

to your ~/.zshrc file.

CLI

zwt restore-defaults
    (help | --help | -h)
    (version | --version | -v)
  • zwt restore-defaults Restore options to their defaults in the current session. See Options.
  • zwt (help | --help | -h) Show the manpage.
  • zwt (version | --version | -v) Print the command name and version.

Options

Variable Type Default Use
ZSH_WINDOW_TITLE_COMMAND_PREFIXES array ( sudo ) If the command starts with one of these terms, show it and the following word. (With the default, running sudo sleep 10 will add sudo sleep to the window title.)
ZSH_WINDOW_TITLE_DEBUG integer 0 If non-zero, print hook debugging messages
ZSH_WINDOW_TITLE_DIRECTORY_DEPTH integer 2 How many directory levels to display
ZWT_DEBUG integer 0 If non-zero, print CLI debugging messages

Changelog

See the CHANGELOG file.

Roadmap

See the ROADMAP file.

Contributing

Thanks for your interest. Contributions are welcome!

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Check the Issues to see if your topic has been discussed before or if it is being worked on.

Please read CONTRIBUTING.md before opening a pull request.

License

zsh-window-title by Henry Bley-Vroman is licensed under CC BY-NC-SA 4.0 with a human rights condition from Hippocratic License 2.1. Persons interested in using or adapting this work for commercial purposes should contact the author.

Licensed under Creative CommonsLicensed with an attribution termLicensed with a non-commercial termLicensed with a share-alike term

For the full text of the license, see the LICENSE file.