Badges

WARNING: This document is for an older version of iTerm2.

A badge is a large text label that appears in the top right of a terminal session to provide dynamic status, such as the current host name or git branch. Its initial value is defined in Preferences>Profiles>General>Badge and it can be changed by an iTerm2-proprietary escape sequence. It may also reference iTerm2- and user-defined variables.

Here is an example of a session with a badge indicating the current user and host name.

Availability

Support for badges is available in version 2.9 and later, currently distributed in the nightly builds and is in the master branch of the GitHub repo. It is not in version 2.1.1.

Variables

A badge may reference variables. There are two kinds of variables: user-defined variables and iTerm2-defined variables. User-defined variables may be set by an escape sequence described below.

The syntax for referencing a variable is to place the variable name between \( and ). For example:

\(session.username)@\(session.hostname)

Undefined variables evaluate to an empty string.

iTerm2-Defined Variables

The following variables are defined by iTerm2:

User-Defined Variables

You can provide additional information in the form of user-defined variables. To create a user-defined variable you must modify your shell's rc script by defining a function named iterm2_print_user_vars that calls iterm2_set_user_var one or more times. See the example below.

Here's an example that sets a user-defined variable called "gitBranch" to the git branch of the current directory. Pick your shell to see the version you need: bash | fish | tcsh | zsh

# bash: Place this in .bashrc.
function iterm2_print_user_vars() {
  iterm2_set_user_var gitBranch $((git branch 2> /dev/null) | grep \* | cut -c3-)
}

# fish: Place this in ~/.config/fish/config.fish after the line
# "source ~/.iterm2_shell_integration.fish".
function iterm2_print_user_vars
  set -l git_branch (git branch ^/dev/null | sed -n '/\* /s///p')
  iterm2_set_user_var gitBranch "$git_branch"
end

# tcsh: Place this in .tcshrc
alias get_current_branch "bash -c '((git branch 2> /dev/null) | grep \* | cut -c3-)'"
alias _iterm2_user_defined_vars \
    'iterm2_set_user_var gitBranch `get_current_branch | base64`'

# Note: you always need to manually base64 encode the second argument to
# iterm2_set_user_var. If you want to define more than one variable,
# use the pattern:
# alias _iterm2_user_defined_vars \
#   '(iterm2_set_user_var key1 value1; iterm2_set_user_var key2 value2; ...)'

# zsh: Place this in .zshrc after "source /Users/georgen/.iterm2_shell_integration.zsh".
iterm2_print_user_vars() {
  iterm2_set_user_var gitBranch $((git branch 2> /dev/null) | grep \* | cut -c3-)
}

To reference a user-defined variable, refer to it as \(user.variableName). For example, to use the example above, you could set your profile's badge to:

Current git branch on \(session.hostname) is \(user.gitBranch)

Escape Sequences

User-defined variables may be set with the following escape sequence:

OSC 1337 ; SetUserVar=name=Base64-encoded value ST

This is what iterm2_set_user_var sends. Generally you should use the iterm2_print_user_vars mechanism described above instead of sending this escape sequence directly.

The badge itself may be set with the following escape sequence:

OSC 1337 ; SetBadgeFormat=Base-64 encoded badge format ST

Here's an example that works in bash:

# Set badge to show the current session name and git branch, if any is set.
printf "\e]1337;SetBadgeFormat=%s\a" \
  $(echo -n "\(session.name) \(user.gitBranch)" | base64)

Color

The badge's color may be set in Preferences>Profiles>Colors.