Skip to content

bluz71/bash-seafly-prompt

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

89 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

seafly

seafly is a clean and fast command prompt for the Bash shell heavily inspired by the Pure ZSH prompt.

πŸš€ For maximum repository performance, seafly will use, if available, either the git-status-fly or gitstatus utilities. Note, it is strongly recommened to either utility to accelerate prompt performance.

Screenshot

seafly

The font in use is Iosevka.

Layout

seafly is a prompt that displays the following segments when using the default layout:

<Optional Prefix> <Optional User/Host> <Current Path> <Git Branch> <Git Indicators> <Prompt Symbol>

Note, when SEAFLY_LAYOUT=2 is set the prompt will instead display as:

<Optional Prefix> <Optional User/Host> <Git Branch> <Git Indicators> <Current Path> <Prompt Symbol>

seafly can also display as a multiline prompt when SEAFLY_MULTILINE=1 is set. The layout will be the same as listed above but with additional newlines prior to the prefix and prompt symbol.

Please refer to the configuration section below for more details.

Behaviour

  • When in a Git repository the checked out Git branch will be displayed.

  • When in a Git repository, dirty state, upstream and stash indicators will be displayed. Note, these can individually be disabled if desired.

  • The prompt symbol will change to an alert color, by default red, if the last command did not execute successfully.

Visuals

seafly by default will use Unicode characters for the prompt symbol and certain Git indicators. These symbols will display correctly when using a modern font such as Iosevka.

Also, seafly by default will use colors that favour a dark background.

Both the symbols and colors used by seafly can be overridden, please refer to the configuration section below. As an example, the following configuration will:

  • only use ASCII characters
  • use colors appropriate for a light terminal theme
  • style the Git section to mimic $(__git_ps1) provided by the git-prompt.sh script that ships with Git
SEAFLY_PROMPT_SYMBOL=">"
SEAFLY_PS2_PROMPT_SYMBOL=">"
SEAFLY_GIT_PREFIX="("
SEAFLY_GIT_SUFFIX=")"
SEAFLY_GIT_DIRTY="*"
SEAFLY_GIT_STASH="$"
SEAFLY_GIT_AHEAD=">"
SEAFLY_GIT_BEHIND="<"
SEAFLY_GIT_DIVERGED="<>"
SEAFLY_SUCCESS_COLOR="$(tput setaf 63)"
SEAFLY_ALERT_COLOR="$(tput setaf 202)"
SEAFLY_HOST_COLOR="$(tput setaf 242)"
SEAFLY_GIT_COLOR="$(tput setaf 99)"
SEAFLY_PATH_COLOR="$(tput setaf 70)"
. ~/.bash-seafly-prompt/command_prompt.bash

Requirements

A modern 256 or true color terminal is required.

Please also make sure the TERM environment variable is set to xterm-256color, screen-256color or equivalent terminal setting.

For example setting TERM to xterm-256color is usually done at the terminal level either in a preferences dialog or a related configuration file, if required at all. Note, some modern terminals will automatically set 256 colors by default, for example, modern versions of Gnome Terminal.

Setting TERM to screen-256color should only be done for tmux sessions. If you are a tmux user then please add the following to your ~/.tmux.conf file:

set -g default-terminal "screen-256color"
set -ga terminal-overrides ',xterm-256color:Tc'

Note, modern terminals such as Alacritty and kitty provide their own terminfo definitions which are also supported by seafly prompt.

Installation

Install the seafly prompt script:

git clone --depth 1 https://github.com/bluz71/bash-seafly-prompt ~/.bash-seafly-prompt

Source the seafly prompt script in your ~/.bashrc file:

. ~/.bash-seafly-prompt/command_prompt.bash

Note, to update to the latest version of seafly:

cd ~/.bash-seafly-prompt
git pull

git-status-fly

The git-status-fly utility is a simple Rust implemented git status processor. Parsing the output of git status using shell commands, such as grep and awk, is much slower than using an optimized binary such as git-status-fly.

Install the git-status-fly somewhere in the current $PATH.

gitstatus

The gitstatus utility, a high-performance alternative to the git status command, is designed specifically for low-latency command prompt usage.

Install gitstatus:

git clone --depth 1 https://github.com/romkatv/gitstatus.git ~/.gitstatus

If gitstatus is already installed in an alternate directory then please export its location in an environment variable:

export SEAFLY_GITSTATUS_DIR=/location/of/gitstatus

Be aware, unlike git-status-fly which is just a standard executable run once per prompt update, gitstatus on the other hand is a daemon process that will launch once on shell startup and will then be interacted with via IPC per prompt update. The gitstatus daemon startup will incur a 5 to 10ms cost.

Git Performance

seafly provides three ways to gather Git status, either of the two previous utilities: git-status-fly, gitstatus, or a fallback method which collates details using just the git command.

Which to use? See the following performance results and decide.

Performance metrics are listed for the following four repositories:

  • dotfiles, small repository with 189 managed files
  • rails, medium repository with 4,574 managed files
  • linux, large repository with 79,878 managed files
  • chromium, extra large repository with 413,542 managed files

Listed is the average time to compute the prompt function.

Mid-range Linux desktop Core i5 with SATA SSD:

Repository git-status-fly gitstatus git fallback
dotfiles 16ms 12ms 28ms
rails 21ms 15ms 33ms
linux(*) 61ms 42ms 80ms
chromium (*) 260ms 160ms 305ms

M1 Macbook Air:

Repository git-status-fly gitstatus git fallback
dotfiles 32ms 12ms 61ms
rails 45ms 29ms 73ms
linux (!) 60ms 165ms 105ms
chromium (!) 102ms 2500ms 155ms
  • (*), the git config feature.manyFiles true option was enabled as documented here

  • (!), in addition to enabling manyFiles, the git config core.fsmonitor true file system monitor was also enabled as documented here

Note, as of May 2023 fsmonitor is implemented only for Windows and macOS, it is not available for Linux.

In practise, a prompt startup time under 40ms feels instant.

Configuration

Certain behaviours and visuals of the seafly prompt can be controlled through environment variables.

Note, a dash character denotes an unset default value.

Environment Variables

Option Description Default Value
SEAFLY_LAYOUT Specify the preferred layout.
Layout 1 will display path followed Git details.
Layout 2 will flip the path and Git details.
1
SEAFLY_MULTILINE Specify multiline layout.
SEAFLY_MULTILINE=1 will display the prompt over multiple lines.
0
SEAFLY_SHOW_USER Display the current user in the user/host segment.
Set to 1 to display the user.
Refer to SEAFLY_SHOW_USERHOST_CONNECTED.
0
SEAFLY_SHOW_HOST Display the current hostname in the user/host segment.
Set to 0 to not display the host.
Ref to SEAFLY_SHOW_USERHOST_CONNECTED.
1
SEAFLY_SHOW_USERHOST_CONNECTED Display the user/host segment only when connected to external hosts.
Set to 0 to always the user/host segment.
1
PROMPT_DIRTRIM Shorten the current directory path to a set maximum number of components.
Set to 0 to not shorten the current path.
4
GIT_PS1_SHOWDIRTYSTATE Indicate the presence of Git modifications.
Set to 0 to skip.
1
GIT_PS1_SHOWSTASHSTATE Indicate the presence of Git stashes.
Set to 0 to skip.
1
GIT_PS1_SHOWUPSTREAM Indicate differences exist between HEAD and upstream in a Git remote-tracking branch.
Set to 0 to skip.
1

Hooks

Hook Description Default Value
seafly_pre_command_hook A function hook to run each time the prompt is displayed.
Please make sure the hook is fast.
-
seafly_prompt_prefix_hook A function hook to populate the optional prefix segment.
Please make sure the hook is simple and fast.
-
  • A pre_command_hook example that appends and updates history each time the prompt is executed:

    seafly_pre_command_hook="seafly_pre_command"
    
    seafly_pre_command() {
        history -a && history -n
    }
  • A prompt_prefix_hook example that displays the current Node version if package.json file is present or displays the name of the current Python virtual environment if one is active in the optional prefix segment:

    seafly_prompt_prefix_hook="seafly_prompt_prefix"
    
    seafly_prompt_prefix() {
        if [[ -f package.json ]]; then
            echo "($(nvm current))"
        elif [[ -n $VIRTUAL_ENV ]]; then
            echo "($(basename $VIRTUAL_ENV))"
        fi
    }

Symbols

Option Description Default Value
SEAFLY_PROMPT_SYMBOL The prompt symbol ❯
SEAFLY_PS2_PROMPT_SYMBOL The PS2 secondary prompt symbol ❯
SEAFLY_GIT_PREFIX Symbol to the left of the Git branch ξ‚ 
SEAFLY_GIT_SUFFIX Symbol to the right of the Git indicators -
SEAFLY_GIT_DIRTY Symbol indicating that a Git repository contains modifications βœ—
SEAFLY_GIT_STAGED Symbol indicating that a Git repository contains staged changes βœ“
SEAFLY_GIT_STASH Symbol indicating that a Git repository contains one or more stashes βš‘
SEAFLY_GIT_AHEAD Symbol indicating that a Git remote-tracking branch is ahead of upstream ↑
SEAFLY_GIT_BEHIND Symbol indicating that a Git remote-tracking branch is behind upstream ↓
SEAFLY_GIT_DIVERGED Symbol indicating that a Git remote-tracking branch is both ahead and behind upstream ↕

Colors

The default color values listed below, such as 111 and 203, derive from xterm 256 color values. Please refer to this chart when customizing seafly colors.

Option Description Default Value Color
SEAFLY_PREFIX_COLOR Optional prefix segment 217 normal
SEAFLY_SUCCESS_COLOR Standard prompt and certain Git indicators 111 normal
SEAFLY_ALERT_COLOR Alert prompt and Git dirty indicator 203 normal
SEAFLY_HOST_COLOR Host segment 255 normal
SEAFLY_GIT_COLOR Git branch, stash and optional prefix/suffix 147 normal
SEAFLY_PATH_COLOR Current directory path 114 normal

Sponsor

Ko-fi

License

License: MIT

Releases

No releases published

Sponsor this project

Packages

No packages published

Languages