Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/softmoth/zsh-prompt-newt

Fat & fast ZSH theme – beautiful inside and out, styled segments done right
https://github.com/softmoth/zsh-prompt-newt

powerline prompt theme zsh zsh-theme zstyle

Last synced: about 1 month ago
JSON representation

Fat & fast ZSH theme – beautiful inside and out, styled segments done right

Host: GitHub
URL: https://github.com/softmoth/zsh-prompt-newt
Owner: softmoth
License: mit
Created: 2018-07-06T04:57:07.000Z (over 6 years ago)
Default Branch: main
Last Pushed: 2021-03-31T19:05:56.000Z (over 3 years ago)
Last Synced: 2024-08-07T18:44:24.119Z (3 months ago)
Topics: powerline, prompt, theme, zsh, zsh-theme, zstyle
Language: Shell
Homepage:
Size: 77.1 KB
Stars: 11
Watchers: 4
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.adoc
- License: LICENSE

Awesome Lists containing this project

README

= Newt ZSH Theme
:toc: preamble
:demo-image: https://gist.githubusercontent.com/softmoth/2910577d28970c80b58f8b55c34d58c1/raw/newt-demo.png
:preview-image: https://gist.githubusercontent.com/softmoth/2910577d28970c80b58f8b55c34d58c1/raw/newt-preview.png
:separators-demo: https://gist.githubusercontent.com/softmoth/2910577d28970c80b58f8b55c34d58c1/raw/separators-demo.png
:issues: https://github.com/softmoth/zsh-prompt-newt/issues

____
“She turned me into a newt!” +
“A newt?” +
“… I got better.” +
____

image::{demo-image}[Newt Theme Demo]

== Installation

This is a sample `.zshrc`. Your plugin manager may have features which
automate integrating prompt themes.

# Optional Newt theme settings
DEFAULT_USER=jdoe
: ${PROMPT_NEWT_LOOK=mono}
zstyle :prompt-theme:newt:\* left time context dir

# This enables promptinit to find prompt_newt_setup
# See PROMPT THEMES in zshcontrib(1)
fpath+=~/path/to/repos/zsh-prompt-newt

autoload -Uz promptinit; promptinit
prompt newt

Please {issues}[open an issue] if you have installation tips that may help
others.

== Looks

Newt comes with these pre-defined looks:
_default, denver, forest, meadow, mono_.

Use a look with `prompt newt meadow`.

image::{preview-image}[Newt Theme Preview]

These looks are simply shorthand for the `zstyle` configuration, as
described in <>. So the look can be used to get most
things as you like, and then individual elements can be refined further.

=== Custom looks

Create an `adhoc` look with `prompt newt adhoc blue white magenta`,
giving a name and a list of colors. Each color can be

- `black`, `red`, `yellow`, `green`, `blue`, `magenta`, `cyan`, `white`, or
- a color number supported by your terminal, or
- a truecolor specification as described in <>, or
- `''` or `_`, meaning the terminal's default background / foreground, or
- `none`, meaning do not set the color, use whatever is already active

=== Colors indexes

The list of colors is

. Primary background
. Primary foreground
. Secondary background
. Secondary foreground
. Alert background
. Alert foreground
. Red
. Green
. Yellow
. Blue
. Magenta
. Cyan
. Black
. White

Since the _forest_ look specifies 4 colors, the following will
change the Alert (colors 5 & 6) to pale yellow on a hot pink
background:

prompt newt forest 161 227

=== Re-running `prompt newt`

When `prompt newt` is run with no arguments, or if the first argument
is `--`, it uses the value of `$PROMPT_NEWT_LOOK` in the environment.
And it always sets `PROMPT_NEWT_LOOK` to the current settings.

It also takes a snapshot of any zstyle settings that have been set.

This means that, for example, `sudo -Es` will inherit the current look.
It is possible to add more colors to the current look by following the
`--` with colors. For example

prompt newt example blue white
prompt newt -- green black
prompt newt -- red yellow

That is equivalent to
`prompt newt example blue white green black red yellow`.

== Styling

This theme uses the ZSH configuration system, called _zstyle_, to specify
the look and behavior of the prompt. It is documented in the `zshmodules(1)`
manual page. Briefly, a _style_ is a configuration setting, which is looked
up in a _context_. In the English phrase "Give me the background color for
the `time` segment in the `default` state, using the `forest` look," the
_style_ being requested is "background color", and the _context_ is the
`forest`, `time` segment, `default` state.

When you specify a style, often the context you provide will be a pattern
with wildcards in it. For example, you can specify the background color
for the time segment's default state in _any_ look with:

zstyle :prompt-theme:newt:*:time:default bg yellow

So, in general, segments can be configured with the context
`:prompt-theme:newt:LOOK:SEGMENT:STATE`.

_Look_ can be any word you like, except for a color name (`red`, `_`,
etc.). You can call `prompt newt LOOK` to use a particular look.

If just `prompt newt` is run, the look is inherited from the
`$PROMPT_NEWT_LOOK` environment variable, or is `default`.

_Segment_ is the name of the segment, e.g., `dir` or `time`.

_State_ is segment-specific, and is `default` for most segments
most of the time.

Run `prompt_newt_defaults` to show the built-in settings.
Your custom overrides can be shown with `zstyle -L ':prompt-theme:newt:*'`.
To remove an override, run
`zstyle -d ':prompt-theme:newt:*:the:pattern' [look]`.

=== Examples

zstyle ':prompt-theme:newt:*:vcs:*' bg blue
zstyle ':prompt-theme:newt:*:vcs:*' fg yellow
zstyle ':prompt-theme:newt:*:vcs:clobbered' bg yellow
zstyle ':prompt-theme:newt:*:vcs:clobbered' fg red
# Revert the first two changes
zstyle -d ':prompt-theme:newt:*:vcs:*'

zstyle ':prompt-theme:newt:forest:dir:*' bg green
zstyle ':prompt-theme:newt:forest:dir:*' fg blue

# Only use the left prompt
zstyle ':prompt-theme:newt:*' left time context status jobs vcs dir
zstyle ':prompt-theme:newt:*' right none

== Segments

The segments used for left and right prompts can be set with:

zstyle ':prompt-theme:newt:*' left history time context dir
zstyle ':prompt-theme:newt:*' right vi_mode status exec_time jobs vcs

This change requires the prompt to be set up again. Run `prompt newt`
for the change to take effect.

The values shown above are default. It is also possible to modify the
default settings, adding or removing individual segments, with:

----
# left gets: time context dir vcs
zstyle ':prompt-theme:newt:*' left -history +vcs

# right gets: prompt_time vi_mode status vcs exec_time
zstyle ':prompt-theme:newt:*' right '+prompt_time -jobs * +exec_time'
----

=== `context`: User and host name

User name is hidden unless it is different from `$DEFAULT_USER`.

Host name is hidden unless `$SSH_CLIENT` is set.

=== `dir`: Current directory

It uses the `'%4~'` zsh format by default, which shows nested directories
to four levels. Set the format with

zstyle :prompt-theme:newt:\*:dir default '%/'

=== `exec_time`: Execution time

The states are `default` and `long`.

The threshold from `default` to `long` can be set with

zstyle ':prompt-theme:newt:*:exec_time' threshold 30

The default is 5 seconds. It can be fractional, for example `0.75`.

The precision can be set with

zstyle ':prompt-theme:newt:*:exec_time' precision 3

The default is 1 if the execution time is below 10 seconds,
and 0 otherwise.

By default, the `long` state shows times in a human-friendly format
like `間1h22m33s`. The `default` state is empty (so times below the
threshold are not shown). The format can be set with:

# %s: seconds
zstyle ':prompt-theme:newt:*:exec_time' long '🕑%s'
# %t: human-friendly
zstyle ':prompt-theme:newt:*:exec_time' default '🕑%t'

=== `history`: History number

=== `jobs`: Background jobs

States are `default` and `zero`. The `zero` state defaults to empty, so
when there are no background jobs, nothing is shown. The `default` state
shows an icon and, if there is more than one job, the number of jobs.
Run `prompt_newt_defaults` to see the full setting.

=== `none`: Placeholder to do nothing

This might be used to disable the right side prompt, for example:

zstyle ':prompt-theme:newt:*' right none

=== `prompt_time`: Prompt time

Displays how long it takes for the prompt itself to be drawn. This
segment is off by default. The precision can be set with

zstyle ':prompt-theme:newt:*:prompt_time' precision 3

=== `status`: Exit status

The `status` segment states are `ok`, `error` and `suspended`. By default
only `error` status is shown. To always show a status, set:

zstyle ':prompt-theme:newt:*:status' ok $'\u2713' # ✓
zstyle ':prompt-theme:newt:*:status' suspended $'\u25c6' # ◆

=== `time`: Time

Shows the current time. The format can be set with

zstyle ':prompt-theme:newt:*:time' default '%*' # HH:MM:SS

=== `vcs`: Version control

States are `clobbered`, `root`, `action`, `dirty` and `default`. Most of
the display is controlled by _`vcs_info`_:

# See zshcontrib(1) for more options related to version control
zstyle ':vcs_info:*' enable git cvs svn bzr hg
zstyle -L ':vcs_info:*'

=== `vi_mode`: Vi mode
:zsh-vim-mode: https://github.com/softmoth/zsh-vim-mode[vim-mode]

States are `viins`, `vicmd`, `replace`, `isearch`, `visual` and `vline`.

NOTE: Only `viins` and `vicmd` states are available by default.
The others require the {zsh-vim-mode} plugin.

Text and colors can be changed. For example:

zstyle ':prompt-theme:newt:*:vi_mode' vicmd NORMAL
zstyle ':prompt-theme:newt:*:vi_mode:vicmd' bg 202
zstyle ':prompt-theme:newt:*:vi_mode:vicmd' fg 235

== Separators
:nerd-fonts: https://nerdfonts.com/

The theme uses Powerline arrows to separate segments by default. It also has
built-in support for separator characters from the {nerd-fonts}[Nerd Fonts]
Powerline Extended set. Request the round half-circle separators with:

zstyle ':prompt-theme:newt:*:*:*' separator nerd-round

The defined separators are: `powerline`, `fade`, `nerd-round`, `nerd-backward`,
`nerd-forward`, `nerd-flame`, `nerd-pixel`, `nerd-waveform`.

image::{separators-demo}[Separators demonstration]

Several of the separators may be drawn as two characters wide. If you are
using the "Mono" version of a Nerd font, this will create a severe gap after
the separator. Turn off the compensatory spacing with:

zstyle ':prompt-theme:newt:*' wide-separators 0

A segment's separator can be reversed, so its arrow points in rather than
out:

# Reverse all segments
zstyle ':prompt-theme:newt:*:*:*' direction reverse
# Or just one
zstyle ':prompt-theme:newt:*:history:*' direction reverse

=== Defining a custom separator

To add your own separator, run `prompt_newt_add_separator` after loading
this theme:

prompt_newt_add_separator nerd-trapezoid \
$'\ue0d2' $'\ue0d2' $'\ue0d4' $'\ue0d4'

The arguments are _name_, _left-to-right thick_, _left-to-right thin_,
_right-to-left thick_, and _right-to-left thin_. Additionally, the options
`--wide`, `--wide-ltr`, and `--wide-rtl` may be given. Each takes a
specification like `1:1` or `0:1`. The left-hand number is 1 if the padding
space from the preceding segment should be removed. The right-hand number is
1 if an extra padding space should be added after the separator. Most wide
separators will want both set to 1.

== Truecolor support
:truecolor: https://gist.github.com/XVilka/8346728

If your terminal {truecolor}[supports Truecolor escape sequences],
then you can use them anywhere a color can be specified. That is,
either in a `zstyle` to set a color, or directly in a `%K{...}` or
`%F{...}` escape in the prompt text. The color must be given as
`rrr;ggg;bbb`. For example:

zstyle ':vcs_info:*' stagedstr '%F{250;128;114}+'
zstyle ':prompt-theme:newt:*:vi_mode:search' bg '199;21;133'

== Miscellaneous settings

# Remove spacing around segments
zstyle ':prompt-theme:newt:*' compact true

# Tell newt what colors the terminal uses; background is used to
# draw the arrow head of the segment separator when the default
# background (bg '') is used.
#
# Also used for the default looks's primary segment colors.
zstyle ':prompt-theme:newt' terminal-background 236
zstyle ':prompt-theme:newt' terminal-foreground 254

# Keep only the latest the right-side prompt
setopt TRANSIENT_RPROMPT

== Bugs

Please {issues}[open an issue] if you run into any bugs or missing features.