Jovial

A lovely zsh theme with responsive-design, it's pretty fast, keep simple but useful

Glance

That's for people who don't want make trouble out of nothing in zsh, and just look for a handy theme.

So we make everything easy to use, even if you're new to zsh.

First, quick install is convenient with only a simple one-line command:

curl -sSL https://github.com/zthxxx/jovial/raw/master/installer.sh | sudo -E bash -s ${USER:=`whoami`}

for more install details see the Install section; (manually install or without oh-my-zsh is okay)

custom colors/symbols is easy, see Customization section;

TOC

　·　 Features 　/　 Plugins 　/　 Install 　/　 Customization 　/　 Benchmark 　/　 Migration 　·　

Features & Preview

whole ability

As mentioned above, jovial theme has many useful abilities, its full display likes:

The description of each parts:

responsive design

Each parts of prompt is "responsive" with terminal windows width, so you can safely use it in narrow terminal.

jovial-responsive-desigin.mp4

git actions state

In addition to the basic git state (branch / tag / hash, dirty or clean),

there are also some prompts to hint that you are in merge / rebase / cherry-pick now with conflict or not.

Note that all git state will be update in asynchronous, so that this theme is pretty fast even in a huge git repo.

development env detecting

It will detect to show your development programming language and version in current working directory, such as:

show execute elapsed

Plugins Integration

These integrated plugins below will be auto setup by the install script, you can see the install.zsh-plugins function in installer.sh

• jovial: jovial plugin defined some utils functions and alias, you can see in jovial.plugin.zsh
• git: some short alias for commonly used command
• autojump: make you can use j <keyword> to jump to the full path folder
• bgnotify: background notifications for long running commands
• zsh-history-enquirer: widget for history searching, enhance Ctrl+R
• zsh-autosuggestions: shell auto-completion
• zsh-syntax-highlighting: user input syntax highlighting

Install

Just run the simple one-line install command:

curl -sSL https://github.com/zthxxx/jovial/raw/master/installer.sh | sudo -E bash -s ${USER:=`whoami`}

Note: The install script is designed to be "Idempotent", so you can safely execute it multiple times.

Tips: you may want to use some http proxy, just export proxy variables before run install command,

　　like: export all_proxy=http://127.0.0.1:1086

　　(it's equal to export http_proxy=http://127.0.0.1:1086 http_proxys=http://127.0.0.1:1086)

Here are what the install command and script do:

• Explain the command:

  • sudo: make sure script run with access for install packages and change default login shell
  • -E: passthrough env variables while use sudo, for receive like http_proxy
  • -s $USER: pass the params to script, which is the real target user for install

• The script do these steps:

  • if zsh or oh-my-zsh not found, will install them
  • change default login shell to zsh
  • download the jovial theme/plugin files in oh-my-zsh custom folder
  • install integrated plugins via local package manager
  • auto rewrite ZSH_THEME and plugins variables in user's .zshrc

install with Antigen

Antigen is a theme/plugin manager for zsh that uses simple declarative configuration.

With Antigen, installing Jovial without sudo permission is easy.

Just download antigen and copy the example below into your ~/.zshrc, reload zsh, and Antigen will automatically download everything only during initialization.

Download antigen:

mkdir -p ~/.antigen && curl -SL https://github.com/zsh-users/antigen/raw/develop/bin/antigen.zsh -o ~/.antigen/antigen.zsh

Example for ~/.zshrc with antigen:

You can manually copy this below into your ~/.zshrc file, or using command to download and append:

curl -SL https://github.com/zthxxx/jovial/raw/master/antigen.zshrc >> ~/.zshrc

# ~/.zshrc

# [Antigen](https://github.com/zsh-users/antigen), 
# a theme/plugin manager for zsh that uses simple declarative configuration.

# Load Antigen
source ~/.antigen/antigen.zsh

# Basic recommended for antigen
antigen use oh-my-zsh
antigen bundle git
antigen bundle autojump
antigen bundle colored-man-pages
antigen bundle zsh-users/zsh-completions
antigen bundle zsh-users/zsh-autosuggestions
antigen bundle zsh-users/zsh-syntax-highlighting

# Load the Jovial theme and plugins
antigen theme zthxxx/jovial
antigen bundle zthxxx/jovial
antigen bundle zthxxx/zsh-history-enquirer


# Any other plugins needs set before `antigen apply`

# After all, tell Antigen that you're done, then antigen will start
antigen apply

Then reload zsh to load antigen with Jovial theme:

exec zsh -il

Note that you also need to manually install other plugin bin files like:

sudo apt install -y autojump terminal-notifier source-highlight

install with Fig

Fig adds apps, shortcuts, and autocomplete to your existing terminal.

Install jovial theme in just one click.

manually install without oh-my-zsh

First, you need download the jovial.zsh-theme file manually. For example, use curl will like:

curl -sSL "https://github.com/zthxxx/jovial/raw/master/jovial.zsh-theme" -o ~/.config/jovial.zsh-theme

Then, add these zsh setting code in your ~/.zshrc and load theme file:

# ~/.zshrc

source ~/.config/jovial.zsh-theme

Finally, don't forget to change the default login shell to zsh, maybe you can use chsh command:

sudo chsh -s `command -v zsh` $USER

upgrade

use antigen

With used antigen, it's simple for update jovial theme by use antigen update:

antigen update zthxxx/jovial

But note that it's ONLY update the jovial theme, without any other plugins,

to update other plugins, you need to use antigen update command on other plugin name again.

use install script

Due to the install script is designed to be "Idempotent", if you want to upgrade the jovial theme, run the install command again.

If you want to upgrade manually without the install command, just download and override jovial.zsh-theme file again.

Changelogs you can see in CHANGELOG.md, and current version you used can be see by run echo ${JOVIAL_VERSION}.

NOTE: pay attention to the tips of Migration / BreakingChange

Customization

All the elements / symbols / colors can be easily customized by override theme variables in ~/.zshrc

Thses variables designed for customization:

• JOVIAL_SYMBOL
• JOVIAL_PALETTE
• JOVIAL_PROMPT_ORDER
• JOVIAL_PROMPT_PRIORITY
• JOVIAL_AFFIXES
• JOVIAL_EXEC_THRESHOLD_SECONDS
• JOVIAL_DEV_ENV_DETECT_FUNCS

You can find them default values in jovial.zsh-theme (~/.oh-my-zsh/custom/themes/jovial.zsh-theme)

symbols

All the default symbols defined list that:

JOVIAL_SYMBOL=(
    corner.top    '╭─'
    corner.bottom '╰─'

    git.dirty '✘✘✘'
    git.clean '✔'

    arrow '─➤'
    arrow.git-clean '(๑˃̵ᴗ˂̵)و'
    arrow.git-dirty '(ﾉ˚Д˚)ﾉ'
)

You can override symbols by assign the variable with key in JOVIAL_SYMBOL, such as arrows:

# ~/.zshrc

JOVIAL_SYMBOL[arrow]='->'
JOVIAL_SYMBOL[arrow.git-clean]='->'
JOVIAL_SYMBOL[arrow.git-dirty]='->'

colors

Override keys in JOVIAL_PALETTE like JOVIAL_SYMBOL above,

All the default symbols defined list that:

# jovial theme colors mapping
# use `sheet:color` plugin function to see color table
# https://zsh.sourceforge.io/Doc/Release/Prompt-Expansion.html#Visual-effects
JOVIAL_PALETTE=(
    # hostname
    host '%F{157}'

    # common user name
    user '%F{253}'

    # only root user
    root '%B%F{203}'

    # current work dir path
    path '%B%F{228}%}'

    # git status info (dirty or clean / rebase / merge / cherry-pick)
    git '%F{159}'

    # virtual env activate prompt for python
    venv '%F{159}'

    # current time when prompt render, pin at end-of-line
    time '%F{254}'

    # elapsed time of last command executed
    elapsed '%F{222}'

    # exit code of last command
    exit.mark '%F{246}'
    exit.code '%B%F{203}'

    # 'conj.': short for 'conjunction', like as, at, in, on, using
    conj. '%F{102}'

    # shell typing area pointer
    typing '%F{252}'

    # for other common case text color
    normal '%F{252}'

    success '%F{040}'
    error '%F{203}'
)

🧐 Feeling mess with those variables and numbers?

Well, %B is set font to bold style,

and %F{xxx} / %K{xxx} is color sheet of font / background.

Such as %F{015} is set font color to "white", and %F{123} is set font color close to "cyan"

Quickref:

%F{xxx}    => foreground color (text color)
%K{xxx}    => background color (color-block)
%B         => **bold**
%U         => underline

🤓 So, where is the color sheet?

You can run sheet:color function which in jovial.plugin.zsh to display color sheet in your terminal,

it will looks like:

order of parts

Prompt parts dispaly order can be config with JOVIAL_PROMPT_ORDER, items means from left to right of jovial theme at the first line.

Defaults are:

JOVIAL_PROMPT_ORDER=( host user path dev-env git-info )

priority of parts

In the responsive design, prompt parts can be set priority list with JOVIAL_PROMPT_PRIORITY,

items means priority from high to low, for decide whether to still keep dispaly while terminal width is no enough;

Defaults are:

JOVIAL_PROMPT_PRIORITY=(
    path
    git-info
    user
    host
    dev-env
)

The highest priority element will always keep dispaly;

current-time will always auto detect rest spaces, it's lowest priority

You can change order of them to obtain different effects of responsive design.

If you want to disable some part, just remove it from the priority list.

affixes

Prefixes and suffixes of jovial prompt part, override them same as above.

Defaults are:

JOVIAL_AFFIXES=(
    host.prefix            '${JOVIAL_PALETTE[normal]}['
    # hostname/username use `Prompt-Expansion` syntax in default
    # but you can override it with simple constant string
    hostname               '${(%):-%m}'
    host.suffix            '${JOVIAL_PALETTE[normal]}] ${JOVIAL_PALETTE[conj.]}as'

    user.prefix            ' '
    username               '${(%):-%n}'
    user.suffix            ' ${JOVIAL_PALETTE[conj.]}in'

    path.prefix            ' '
    current-dir            '%~'
    path.suffix            ''

    dev-env.prefix         ' '
    dev-env.suffix         ''

    git-info.prefix        ' ${JOVIAL_PALETTE[conj.]}on ${JOVIAL_PALETTE[normal]}('
    git-info.suffix        '${JOVIAL_PALETTE[normal]})'

    venv.prefix            '${JOVIAL_PALETTE[normal]}('
    venv.suffix            '${JOVIAL_PALETTE[normal]}) '

    exec-elapsed.prefix    ' ${JOVIAL_PALETTE[elapsed]}~'
    exec-elapsed.suffix    ' '

    exit-code.prefix       ' ${JOVIAL_PALETTE[exit.mark]}exit:'
    exit-code.suffix       ' '

    current-time.prefix    ' '
    current-time.suffix    ' '
)

Note that all JOVIAL_AFFIXES variable values wrapped in ${...} will be subject to shell Prompt-Expansion once at first load as zsh prompt,

so keep Single Quotes which you want override value in your .zshrc file,

# ~/.zshrc
JOVIAL_AFFIXES[user.suffix]=' ${JOVIAL_PALETTE[conj.]}in'

and you can use Double Quotes in your terminal to see effect immediately for adjust theme.

# in terminal
$ JOVIAL_AFFIXES[user.suffix]=" ${JOVIAL_PALETTE[conj.]}in"

execute elapsed

Default is:

JOVIAL_EXEC_THRESHOLD_SECONDS=4

This threshold is seconds for last command execute elapsed time, will pin the info if the threshold is reached,

set to -1 if you want to disable display time.

detect development env

Each item in JOVIAL_DEV_ENV_DETECT_FUNCS is name of function to detect development env,

you can append some custom functions for other programming language (such as Erlang), like this:

# ~/.zshrc

JOVIAL_DEV_ENV_DETECT_FUNCS+=( your-function-name )

Or disable it by set empty list:

# ~/.zshrc

JOVIAL_DEV_ENV_DETECT_FUNCS=()

Font Recommended

(no need to install any specify fonts, these usually come with the OS)

• Monaco in iTerm2
• Menlo in VSCode
• JetBrains Mono in JetBrains IDEs

Just the most common monospaced fonts, no need any special font.

NOTE: also remember to set font line-height to 1.0

Benchmark

By asynchronous update git status, it's so fast in render and interaction.

Average: jovial theme only takes 4ms per render.

Run jovial theme 10 times in benchmark.zsh, you can get like this:

$ zsh -il dev/benchmark.zsh

( for i in {1..10}; do; theme.render; done; )  0.01s user 0.02s system 95% cpu 0.039 total

Changelog

see in CHANGELOG.md

Migration

run echo ${JOVIAL_VERSION} in terminal to see what version you used now.

from v1 to v2

There are some breaking changes for customization,

some customized variables and functions renamed:

• variable JOVIAL_ARROW => JOVIAL_SYMBOL[arrow]
• function _jov_type_tip_pointer => @jov.typing-pointer,
• and now, arrows could replace with variables JOVIAL_SYMBOL[arrow.git-clean] and JOVIAL_SYMBOL[arrow.git-dirty]
• some keys in JOVIAL_PROMPT_PRIORITY renamed, git_info => git-info, dev_env => dev-env

Author

jovial © zthxxx, Released under the MIT License.

Blog @zthxxx · GitHub @zthxxx