powerline-go

command module
v0.0.0-...-3da5e8d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: GPL-3.0 Imports: 34 Imported by: 0

README

A Powerline style prompt for your shell

A Powerline like prompt for Bash, ZSH and Fish. Based on Powerline-Shell by @banga.

This is a fork of justjanne/powerline-go, the original Go port by Janne Mareike Koschinski (@justjanne). All credit for the original work goes to them. This fork is maintained at mrevjd/powerline-go, and issues and pull requests for it belong there rather than upstream.

  • Shows some important details about the git/hg branch (see below)
  • Changes color if the last command exited with a failure code
  • If you're too deep into a directory tree, shortens the displayed path with an ellipsis
  • Shows the current Python virtualenv environment
  • Shows the current Ruby version using rbenv or rvm
  • Shows if you are in a nix shell
  • Optionally shows the shell nesting depth ($SHLVL) once you are in a sub-shell
  • It's easy to customize and extend. See below for details.

Table of Contents

Version Control

All of the version control systems supported by powerline shell give you a quick look into the state of your repo:

  • The current branch is displayed and changes background color when the branch is dirty.
  • When the local branch differs from the remote, the difference in number of commits is shown along with ⇡ or ⇣ indicating whether a git push or pull is pending

In addition, git has a few extra symbols:

  • ✎ -- a file has been modified, but not staged for commit
  • ✓ -- a file is staged for commit
  • ✼ -- a file has conflicts
  • + -- untracked files are present
  • ⚑ -- stash is present

Each of these will have a number next to it if more than one file matches.

The ahead/behind counts compare against your last fetch, so they go stale until something runs git fetch. -git-fetch-interval 5 has the git segment start a background fetch at most every 5 minutes per repository, only for a branch with an upstream. The prompt never waits for it: the updated count appears on the next prompt after the fetch lands. The fetch is detached from the terminal and cannot prompt for a password, passphrase or credential-manager login, so it only succeeds for remotes you are already authenticated to (SSH agent, credential helper, gh auth setup-git) and otherwise fails silently. It will not show a login prompt, and a fetch still running after the interval or 10 minutes, whichever is longer, is killed along with any ssh it started, so stalled fetches don't linger. On Windows only the process git was started as is killed; with Git for Windows that is a launcher, so a stalled fetch may keep running. It needs git 2.29 or later.

Installation

Builds with the Go 1.26 toolchain. Go 1.21 through 1.25 will download it automatically on first build, which needs network access to the toolchain proxy; with GOTOOLCHAIN=local, or on any Go below 1.21, install Go 1.26 yourself. macOS binaries published from this fork's own releases require macOS 12 or later, that being Go 1.26's floor. Upstream's releases predate that floor and carry no such requirement.

powerline-go uses ANSI color codes, these should nowadays work everywhere, but you may have to set your $TERM to xterm-256color for it to work.

If you want to use the "patched" mode (which is the default, and provides improved UI), you'll need to install a powerline font, either as fallback, or by patching the font you use for your terminal: see powerline-fonts. Alternatively you can use "compatible" or "flat" mode.

See Fonts, glyphs & terminals below if some symbols render as boxes, question marks, or coloured emoji.

Precompiled Binaries

Precompiled binaries are published in this fork's releases tab

Other Platforms
  • Install (and update) the package with
go install github.com/mrevjd/powerline-go@latest
  • By default it will be in $GOPATH/bin, if you want to change that, you can set your $GOPATH and/or $GOBIN, but will need to change the path in the following scripts, too.
Building from source

With the Go toolchain installed, a Makefile wraps the common tasks (run make help to list them all):

make build     # static x64 Linux binary at ./bin/powerline-go (default target)
make test      # run the test suite
make install   # install a static binary into $GOBIN (or $GOPATH/bin)

make build sets CGO_ENABLED=0 and pins GOOS=linux GOARCH=amd64, so the result is a fully static, dependency-free binary that runs on any x86-64 Linux machine regardless of its libc. Release binaries for every platform are produced with GoReleaser (goreleaser build --clean --snapshot).

Bash

Add the following to your .bashrc:

function _update_ps1() {
    PS1="$($GOPATH/bin/powerline-go -error $? -jobs $(jobs -p | wc -l))"

    # Uncomment the following line to automatically clear errors after showing
    # them once. This not only clears the error for powerline-go, but also for
    # everything else you run in that shell. Don't enable this if you're not
    # sure this is what you want.

    #set "?"
}

if [ "$TERM" != "linux" ] && [ -f "$GOPATH/bin/powerline-go" ]; then
    PROMPT_COMMAND="_update_ps1; $PROMPT_COMMAND"
fi

Currently, right prompt support is not available when using bash.

ZSH

Add the following to your .zshrc:

function powerline_precmd() {
    PS1="$($GOPATH/bin/powerline-go -error $? -jobs ${${(%):%j}:-0})"

    # Uncomment the following line to automatically clear errors after showing
    # them once. This not only clears the error for powerline-go, but also for
    # everything else you run in that shell. Don't enable this if you're not
    # sure this is what you want.

    #set "?"
}

function install_powerline_precmd() {
  for s in "${precmd_functions[@]}"; do
    if [ "$s" = "powerline_precmd" ]; then
      return
    fi
  done
  precmd_functions+=(powerline_precmd)
}

if [ "$TERM" != "linux" ] && [ -f "$GOPATH/bin/powerline-go" ]; then
    install_powerline_precmd
fi
Fish

Redefine fish_prompt in ~/.config/fish/config.fish:

function fish_prompt
    eval $GOPATH/bin/powerline-go -error $status -jobs (count (jobs -p))
end
Nix

When using nix-shell --pure, powerline-go will not be accessible, and your prompt will disappear.

To work around this you can add this snippet to your .bashrc, which should re-enable the prompt in most cases:

# Workaround for nix-shell --pure
if [ "$IN_NIX_SHELL" == "pure" ]; then
    if [ -x "$HOME/.nix-profile/bin/powerline-go" ]; then
        alias powerline-go="$HOME/.nix-profile/bin/powerline-go"
    elif [ -x "/run/current-system/sw/bin/powerline-go" ]; then
        alias powerline-go="/run/current-system/sw/bin/powerline-go"
    fi
fi
Powershell

Redefine prompt function on your profile:

# Load powerline-go prompt
function global:prompt {
    $pwd = $ExecutionContext.SessionState.Path.CurrentLocation
    $startInfo = New-Object System.Diagnostics.ProcessStartInfo
    $startInfo.FileName = "powerline-go"
    $startInfo.Arguments = "-shell bare"
    $startInfo.Environment["TERM"] = "xterm-256color"
    $startInfo.CreateNoWindow = $true
    $startInfo.StandardOutputEncoding = [System.Text.Encoding]::UTF8
    $startInfo.RedirectStandardOutput = $true
    $startInfo.UseShellExecute = $false
    $startInfo.WorkingDirectory = $pwd
    $process = New-Object System.Diagnostics.Process
    $process.StartInfo = $startInfo
    $process.Start() | Out-Null
    $standardOut = $process.StandardOutput.ReadToEnd()
    $process.WaitForExit()
    $standardOut
}

Use ProcessStartInfo is needed to allow fill the enviromnet variables required by powerline-go.

Fonts, glyphs & terminals

powerline-go does not draw graphics; it prints Unicode code points and lets your terminal and font render them. Whether a symbol appears therefore depends on the -mode you pick, the font you have selected, and how well your terminal falls back for code points the primary font is missing. If some glyphs render and others don't, this section is why.

Pick the mode that matches your font
Mode Separators Icons Use when
patched (default) Powerline glyphs (U+E0B0…, Private Use Area) Nerd Font icons for nix-shell, rvm, venv (also PUA) Your terminal font is a Nerd Font (or a powerline-patched font, for separators only).
compatible Standard Unicode triangles (▶ ◀ ❯ ❮) Standard Unicode fallbacks (❄ ◆ π) Your font is a normal font with no powerline/Nerd patching.
flat None Same standard fallbacks You want no separators at all.

Set it with -mode compatible (or flat). The separator arrows, the git branch symbol, the padlock, and the nix-shell/rvm/venv indicators are all Private Use Area glyphs in patched mode. They only exist in a suitable font. A plain powerline-patched font (the powerline-fonts link above) supplies only the separator glyphs, not the nix-shell/rvm/venv icons; those need a full Nerd Font.

Nerd Fonts: Mono vs. regular, and the v3 migration
  • Mono vs. regular variant. Nerd Fonts ship a ... Mono variant that squeezes every icon into a single character cell. That keeps column alignment, but the seamless powerline separators (U+E0B0…) are designed to bleed to the cell edge; when squeezed they can leave a thin gap so the previous segment's background shows through as a hairline "border" around each arrow. If those borders bother you, try the non-Mono variant (wider but edge-to-edge), or a terminal with tighter cell metrics.
  • v3 code-point migration. Nerd Fonts v3 (2023) moved thousands of icons to new code points. If you patched or froze a font before v3, some PUA indicators may point at empty or wrong glyphs. Update to a current Nerd Font.
MobaXterm

MobaXterm renders from the single font you select and does not do rich per-glyph fallback the way modern GPU terminals (WezTerm, kitty, Windows Terminal) do. A code point that isn't in the selected font shows as a box or ? rather than being borrowed from another font. To get powerline/Nerd glyphs:

  1. Install a Nerd Font (e.g. CaskaydiaCove Nerd Font, JetBrainsMono Nerd Font).
  2. In Settings → Terminal → Font, set that Nerd Font as the primary terminal font. Installing it is not enough; it must be the selected font.
  3. If icons still fail, use -mode compatible so powerline-go only emits widely-supported standard-Unicode symbols.
Emoji vs. text presentation

A few code points (notably the git ahead/behind arrows and the staged tick) have a default emoji presentation in some environments, which renders them coloured and/or double-width and makes them ignore your theme colour. powerline-go's defaults use the text-presentation code points (⇡ U+21E1, ⇣ U+21E3, ✓ U+2713) to avoid this. If you override symbols via a config file, prefer text-default code points over emoji ones for the same reason.

Customization

There are a few optional arguments which can be seen by running powerline-go -help. These can be used by changing the command you have set in your shell’s init file.

Usage of powerline-go:
  -alternate-ssh-icon
         Show the older, original icon for SSH connections
  -bold
         Use bold text for segment foregrounds, overriding the theme's own setting. Pass -bold=false to force non-bold.
  -colorize-hostname
         Colorize the hostname based on a hash of itself. Override either colour independently with the PLGO_HOSTNAMEFG and/or PLGO_HOSTNAMEBG env vars (color codes 0-255).
  -condensed
         Remove spacing between segments
  -cwd-max-depth int
         Maximum number of directories to show in path
         (default 5)
  -cwd-max-dir-size int
         Maximum number of letters displayed for each directory in the path
         (default -1)
  -cwd-mode string
         How to display the current directory
         (valid choices: fancy, semifancy, plain, dironly)
         (default "fancy")
  -duration string
         The elapsed clock-time of the previous command
  -duration-low-precision
         Use low precision timing for duration with milliseconds as maximum resolution
  -duration-min string
         The minimal time a command has to take before the duration segment is shown (default "0")
  -east-asian-width
         Use East Asian Ambiguous Widths
  -error int
         Exit code of previously executed command
  -eval
         Output prompt in 'eval' format.
  -fqdn-hostname
         Use the longer fully qualified domain name as the hostname
  -git-assume-unchanged-size int
         Disable checking for changed/edited files in git repositories where the index is larger than this size (in KB), improves performance (default 2048)
  -git-disable-stats string
         Comma-separated list to disable individual git statuses
         (valid choices: ahead, behind, staged, notStaged, untracked, conflicted, stashed)
  -git-fetch-interval int
         Fetch the current branch's remote in the background at most once every N minutes, keeping ahead/behind current (defaults to 0, which is disabled).
         The fetch never prompts for credentials, so it only succeeds where you are already authenticated
  -git-mode string
         How to display git status
         (valid choices: fancy, compact, simple)
         (default "fancy")
  -hostname-only-if-ssh
         Show hostname only for SSH connections
  -ignore-repos string
         A list of git repos to ignore. Separate with ','.
         Repos are identified by their root directory.
  -ignore-warnings
         Ignores all warnings regarding unset or broken variables
  -jobs int
         Number of jobs currently running
  -max-width int
         Maximum width of the shell that the prompt may use, in percent. Setting this to 0 disables the shrinking subsystem.
  -mode string
         The characters used to make separators between segments.
         (valid choices: patched, compatible, flat)
         (default "patched")
  -modules string
         The list of modules to load, separated by ','
         (valid choices: aws, bzr, cwd, direnv, docker, docker-context, dotenv, duration, exit, fossil, gcp, git, gitlite, goenv, hg, host, jobs, kube, load, newline, nix-shell, node, perlbrew, perms, plenv, rbenv, root, rvm, shell-var, shenv, shlvl, ssh, svn, termtitle, terraform-workspace, time, user, venv, vgo, vi-mode, wsl, azure)
         Unrecognized modules will be invoked as 'powerline-go-MODULE' executable plugins and should output a (possibly empty) list of JSON objects that unmarshal to powerline-go's Segment structs.
         (default "venv,user,host,ssh,cwd,perms,git,hg,jobs,exit,root")
  -modules-right string
         The list of modules to load anchored to the right, for shells that support it, separated by ','
         (valid choices: aws, bzr, cwd, direnv, docker, docker-context, dotenv, duration, exit, fossil, gcp, git, gitlite, goenv, hg, host, jobs, kube, load, newline, nix-shell, node, perlbrew, perms, plenv, rbenv, root, rvm, shell-var, shenv, shlvl, ssh, svn, termtitle, terraform-workspace, time, user, venv, vgo, wsl, azure)
         Unrecognized modules will be invoked as 'powerline-go-MODULE' executable plugins and should output a (possibly empty) list of JSON objects that unmarshal to powerline-go's Segment structs.
  -newline
         Show the prompt on a new line
  -numeric-exit-codes
         Shows numeric exit codes for errors.
  -path-aliases string
         One or more aliases from a path to a short name. Separate with ','.
         An alias maps a path like foo/bar/baz to a short name like FBB.
         Specify these as key/value pairs like foo/bar/baz=FBB.
         Use '~' for your home dir. You may need to escape this character to avoid shell substitution.
  -path-aliases-case-insensitive
         Match -path-aliases case-insensitively (useful on case-insensitive filesystems)
  -priority string
         Segments sorted by priority, if not enough space exists, the least priorized segments are removed first. Separate with ','
         (valid choices: aws, bzr, cwd, direnv, docker, docker-context, dotenv, duration, exit, fossil, gcp, git, gitlite, goenv, hg, host, jobs, kube, load, newline, nix-shell, node, perlbrew, perms, plenv, rbenv, root, rvm, shell-var, shenv, shlvl, ssh, svn, termtitle, terraform-workspace, time, user, venv, vgo, vi-mode, wsl, azure)
         (default "root,cwd,user,host,ssh,perms,git-branch,git-status,hg,jobs,exit,cwd-path")
  -shell string
         Set this to your shell type
         (valid choices: autodetect, bare, bash, zsh)
         (default "autodetect")
  -shell-var string
         A shell variable to add to the segments.
  -shell-var-no-warn-empty
         Disables the warning shown when the shell variable is unset or empty.
  -shlvl-min int
         Minimum $SHLVL before the shlvl module shows the shell nesting depth (default 2)
  -shorten-eks-names
         Shortens names for EKS Kube clusters.
  -shorten-gke-names
         Shortens names for GKE Kube clusters.
  -shorten-openshift-names
         Shortens names for Openshift Kube clusters.
  -static-prompt-indicator
         Always show the prompt indicator with the default color, never with the error color
  -theme string
         Set this to the theme you want to use
         (valid choices: default, low-contrast, gruvbox, solarized-dark16, solarized-light16)
         (default "default")
  -time string
         The layout string how a reference time should be represented.
         The reference time is predefined and not user chosen.
         Consult the golang documentation for details: https://pkg.go.dev/time#example-Time.Format (default "15:04:05")
  -trim-ad-domain
         Trim the Domainname from the AD username.
  -truncate-segment-width int
         Maximum width of a segment, segments longer than this will be shortened if space is limited. Setting this to 0 disables it.
         (default 16)
  -venv-name-size-limit int
         Show indicator instead of virtualenv name if name is longer than this limit (defaults to 0, which is unlimited)
  -version
         Print the current version and exit
  -vi-mode string
         The current vi-mode (eg. KEYMAP for zsh) for vi-module module
Plugins

A module name that powerline-go does not recognise is run as a powerline-go-MODULE executable found on PATH, and its stdout is parsed as a JSON list of segments. A plugin's content and separator are escaped like any other segment's; see Prompt escaping below.

Prompt escaping

What a segment displays is text, not prompt markup. Before writing a segment into the prompt, powerline-go escapes the characters a shell would treat as the start of an expansion: $, a backtick, a backslash, and under zsh also %. So a directory name, a git branch, an environment variable, a Kubernetes context or something a plugin relays cannot inject a command into your prompt, however it is named. Both halves of a segment are covered, its content and its separator.

Three limits are worth knowing:

  • -eval is not covered. The eval wrapper assigns the prompt through a double-quoted PS1="..." / PROMPT="...", and the shell strips one level of quoting as it runs that assignment, which undoes the escaping. Under -eval, treat segment content you do not control as unsafe, and prefer the non-eval setup for a repository that is not yours. The % escaping is unaffected, because % is not special to that parse.
  • Only those characters are escaped. Terminal control sequences in segment content still reach the terminal. They do not run a command, but they can garble a prompt.
  • Under bash, a literal $ displays as # when you are root. \$ is the only escape that survives bash's prompt expansion intact, and bash renders it as # for uid 0.
Eval

Note that the escaping described under Prompt escaping does not survive -eval.

If using eval and -modules-right is desired, the shell setup must be modified slightly, as shown below:

Bash

Add the following to your .bashrc:

function _update_ps1() {
    eval "$($GOPATH/bin/powerline-go -error $? -shell bash -eval -modules-right git)"
}

if [ "$TERM" != "linux" ] && [ -f "$GOPATH/bin/powerline-go" ]; then
    PROMPT_COMMAND="_update_ps1; $PROMPT_COMMAND"
fi
ZSH

Add the following to your .zshrc:

function powerline_precmd() {
    eval "$($GOPATH/bin/powerline-go -error $? -shell zsh -eval -modules-right git)"
}

function install_powerline_precmd() {
  for s in "${precmd_functions[@]}"; do
    if [ "$s" = "powerline_precmd" ]; then
      return
    fi
  done
  precmd_functions+=(powerline_precmd)
}

if [ "$TERM" != "linux" ]; then
    install_powerline_precmd
fi
Fish

Eval mode (and modules-right support) for Fish is not currently available.

Path Aliases

The point of the path aliases feature is to allow you to replace long paths with a shorter string that you can understand more quickly. This is useful if you're often in deep path hierarchies that end up consuming most of your terminal width, even when some portions are replaced by an ellipsis.

For example, you might want to replace the string $GOPATH/src/github.com with @GOPATH-GH. When you're in a directory like $GOPATH/src/github.com/mrevjd/powerline-go, you'll instead see @GOPATH-GH > mrevjd > powerline-go in the shell prompt.

Aliases are defined as comma-separated key value pairs, like this:

powerline-go ... -path-aliases \$GOPATH/src/github.com=@GOPATH-GH,\~/work/projects/foo=@FOO,\~/work/projects/bar=@BAR

Note that you should use ~ instead of /home/username when specifying the path. Also make sure to escape the ~ character. Otherwise your shell will perform interpolation on it before powerline-go can see it!

A comma inside a path can be escaped as \, so it is not treated as the separator between alias definitions (e.g. -path-aliases '/mnt/c/Co\, Inc=@co'). This escaping applies to the -path-aliases flag; in a JSON config file, commas in keys need no escaping.

Pass -path-aliases-case-insensitive to match alias paths regardless of case, which is useful on case-insensitive filesystems such as macOS or Windows.

Aliases match whole path components, and they match in every -cwd-mode including plain: an alias for foo/bar matches that pair of components anywhere in the path, not only at its start. Each alias replaces its first (leftmost) match, and where two aliases could both match, the longer key wins.

Duration

The duration segment requires some assistance from the shell. The shell must have a hook that gets executed immediately before the command.

Bash

Bash 4.4 includes an easy way to get a start-time, using $PS0. However, not all operating systems come with a sufficiently recent version of Bash installed. This example only has seconds precision. Add or modify your .bashrc file to include the following:

INTERACTIVE_BASHPID_TIMER="/tmp/${USER}.START.$$"

PS0='$(echo $SECONDS > "$INTERACTIVE_BASHPID_TIMER")'

function _update_ps1() {
  local __ERRCODE=$?

  local __DURATION=0
  if [ -e $INTERACTIVE_BASHPID_TIMER ]; then
    local __END=$SECONDS
    local __START=$(cat "$INTERACTIVE_BASHPID_TIMER")
    __DURATION="$(($__END - ${__START:-__END}))"
    rm -f "$INTERACTIVE_BASHPID_TIMER"
  fi

  PS1="$($GOPATH/bin/powerline-go -modules duration -duration $__DURATION -error $__ERRCODE -shell bash)"
}

if [ "$TERM" != "linux" ] && [ -f "$GOPATH/bin/powerline-go" ]; then
  PROMPT_COMMAND="_update_ps1; $PROMPT_COMMAND"
fi
Zsh

Using $EPOCHREALTIME requires loading the 'datetime' module in your .zshrc file, for example:

zmodload zsh/datetime

function preexec() {
  __TIMER=$EPOCHREALTIME
}

function powerline_precmd() {
  local __ERRCODE=$?
  local __DURATION=0

  if [ -n $__TIMER ]; then
    local __ERT=$EPOCHREALTIME
    __DURATION="$(($__ERT - ${__TIMER:-__ERT}))"
  fi

  PS1="$(powerline-go -modules duration -duration $__DURATION -error $__ERRCODE -shell zsh)"
  unset __TIMER
}

If the 'datetime' module is unavailable or unwanted, you may replace $EPOCHREALTIME with $SECONDS, at the loss of precision.

Fish

The fish prompt, in ~/.config/fish/config.fish, will require a minimum of changes, as Fish automatically provides $CMD_DURATION, although with only milliseconds accuracy.

function fish_prompt
    set duration (math -s6 "$CMD_DURATION / 1000")
    $GOPATH/bin/powerline-go -modules duration -duration $duration -error $status -shell bare
end

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL