gprompt/README.md

GPrompt - useless gimmicky prompt for Bash on Linux
====================================================

GPrompt (short for GadgetoPrompt) is a gimmicky Bash prompt generator
that displays sort-of-useful information. It only works on Linux because
that's what I use. It adapts to the terminal's width, showing or hiding
information depending on the conditions.

## Features

GPrompt prompts may consist in one or two lines. The top line is separated
in three areas (left, midddle and right), while the second line (the "input"
line, where the cursor is) only has a single, left-aligned area. Each area
may be configured to display information from one of the generators. In
addition, the script may be configured to generate a terminal title and/or
terminal icon title.

### Session example

![Session example](screenshots/session.png)

### Themes

#### Unthemed (but using custom layout):
![Unthemed](screenshots/theme-unthemed.png)

#### `ascii_yb` theme
![`ascii_yb` theme](screenshots/theme-ascii_yb.png)

#### `ascii_gyr` theme
![`ascii_gyr` theme](screenshots/theme-ascii_gyr.png)

#### `blocks_yb` theme
![`blocks_yb` theme](screenshots/theme-blocks_yb.png)

#### `blocks_gyr` theme
![`blocks_gyr` theme](screenshots/theme-blocks_gyr.png)

#### `powerline_yb` theme

This theme requires a Powerline font.

![`powerline_yb` theme](screenshots/theme-powerline_yb.png)

#### `powerline_gyr` theme

This theme requires a Powerline font.

![`powerline_gyr` theme](screenshots/theme-powerline_gyr.png)

## Installing GPrompt

GPrompt may be installed either at the system level or on a per-user basis.

### User installation

* Copy the script and associated themes to your home directory.

      mkdir -p ~/.local/share/gprompt/themes
      cp gprompt.pl ~/.local/share/gprompt
      chmod +x ~/.local/share/gprompt/gprompt.pl
      cp themes/* ~/.local/share/gprompt/themes/

* Add the following line to your `~/.bashrc`:

      eval "$($HOME/.local/share/gprompt/gprompt.pl init)"

### System-wide installation

* In the case of a system-wide installation, the script and associated themes
  must be copied to some shared location, e.g.

      mkdir -p /usr/share/gprompt/themes
      cp gprompt.pl /usr/share/gprompt
      chmod +x /usr/share/gprompt/gprompt.pl
      cp themes/* /usr/share/gprompt/themes/

* Users may then use GPrompt by adding the following line to their `~/.bashrc`
  files (it could also be added to `/etc/skel/.bashrc` or `/etc/bash.bashrc`):

      eval "$(/usr/share/gprompt/gprompt.pl init)"

## Configuration

GPrompt comes with a minimal (...-ish, this is a gadget after all)
configuration that will work out of the box. However, it can be customised
using both a system-wide configuration file and a per-user configuration file.
Values set in a configuration files override values that were previously
loaded, so it is possible to have a system-wide configuration that replaces
most of the defaults and a per-user configuration that only overrides a few of
the system-wide options. In addition, if the option is enabled from the
configuration files, it is possible to override settings using environment
variables.

The GPrompt configuration is a Perl hash reference, so the general syntax of
the file goes something like this:

    {
        'some_key' => 'some_value' ,
        'other_key' => [ 'list entry 1' , 'list entry 2' ] ,
    }

In order to override a configuration entry using an environment variable,
the variable must be named `GPROMPT_` followed by the uppercase name of
the configuration entry. If the configuration expects a list for the
value in question, the value of the environment variable will be split using
the comma character. If a table is expected, keys and values are expected
to be separated by a colon.

    export GPROMPT_LAYOUT_RIGHT=git,load
    export GPROMPT_LAYOUT_THEME_OVERRIDES=bg_left:230,bg_right:230

### Main configuration

The following variables control the configuration itself:

* `cfg_warn_files` indicates that the script should emit warnings when a file
  (configuration or theme) cannot be loaded due to some error (`0` or `1`,
  default `1`).
* `cfg_from_env` disables or enables configuration overrides from environment
  variables (`0` or `1`, default `0`).
* `cfg_sys_themes` must list system-wide directories which may contain GPrompt
  themes (list; default `/usr/share/gprompt/themes`).
* `cfg_user_themes` lists directories relative to the user's home which may
  contain GPrompt themes (list; default `.local/share/gprompt/themes` and
  `.gprompt-themes`).

The `layout_*` variables control the prompt's layout and general appearance:

* `layout_theme` is the name of the theme to use. The default theme will be used
  if it contains an empty string.
* `layout_theme_overrides` may contain local overrides to the theme's contents
  (table, empty by default).
* `layout_left`, `layout_right` and `layout_input` configure the generators that
  will provide the contents of the top left, top center, top right and bottom
  left sections of the prompt. All 3 variables are lists of generator names; by
  default, the top bar is empty (the script does not render it) and the input
  prompt only uses the `userhost` and `cwd` generators, emulating a rather basic
  `\u@\h:\w` prompt.
* `layout_middle` defines the generator from which the top middle section will
  be displayed. Background colors emitted by the generator are ignored. By
  default this entry contains an empty string.
* `layout_input_always` determines whether the input line should be rendered
  even if no generators are specified (`0` or `1`, default `0`).
* `layout_empty_line` determines how the prompt handles printing an empty line
  before the prompt's top line.
  * When set to `0`, no extra line is drawn, and commands that do not end with
    an EOL will cause the prompt's first line to be displayed incorrectly.
  * When set to `1`, the prompt's top line will always be preceeded with an
    empty line.
  * When set to `2`, the prompt will be preceeded by an empty line unless it
    is being drawn on the terminal's first line.
  * When set to `3`, a newline will be added to the prompt if the last
    command's output didn't end with a newline.

The `term_*` variables control the prompt's ability to change the terminal's
title and/or icon title:

* `term_set_title` controls whether the title or icon title of the terminal
  should be changed. Possible values are `0` (no update), `1` (title), `2`
  (icon title), and `3` (both). By default, only the title is updated.
* `term_generators` contains the list of generators that will produce the title
  string (unicode characters in the generators' output will be removed).
* `term_separator` is a string that will be inserted between the various parts
  of the string.

Generators also require specific configuration variables. These are documented
in the generators' sections below.

### Theme files

Themes are also stored using Perl hashes. The file containing a theme `x` should
be named `x.pm` and located in one of the configured theme directories.

The following entries are used by the script's core :

* `padding` must contain a single character which is used for padding the top
  line's middle area, amongst other things.
* `transition` may contain a list of up to 8 color indices which can be used
  when generating transition strings from templates.
* 5 entries control each section's appearance.
  * The sections are identified by `left`, `middle`, `right` and `input` (top
    left, top middle, top right and bottom left, respectively).
  * Each section uses the following entries (replacing `${section}` with a
    section's identifier):
    * `bg_${section}` is the index of the background color of the section.
    * `fg_${section}` is the index of the foreground color of the section.
    * `${section}_prefix` is the template for the prefix of the section.
    * `${section}_separator` is the template for the separator that is inserted
      between generated areas in the section.
    * `${section}_suffix` is the template for the suffix of the section.
* `bg_ps2` is the index of the background color of the secondary prompt.
* `ps2_suffix` is the template for the suffix of the secondary prompt.

Templates are strings which may contain `\bX` and `\fX` escape sequences, where
`X` is a single digit, and which modify the background or foreground colors,
respectively. Values `0` and `1` correspond to the preceding and following
background color indices, while values between `2` and `9` will refer to the
contents of the `transition` list.

In addition to the entries above, theme definitions contain entries that are
specific to the various generators. These entries are documented below.

A few special values can be used to simplify writing theme definitions.

* The `thref` function may be used to copy values from other elements in the
  current theme definition, for example:

      bg_left   => 1 ,
      bg_middle => 2 ,
      bg_right  => thref 'bg_left' , # Left/right always use the same bg color

* The `TERM_DEFAULT` value may be used for either background or foreground
  color definitions. The terminal's default color will be used for the text in
  question.

* The `SECTION_DEFAULT` value may be used in generator-specific definitions to
  indicate that the current section's foreground or background color should be
  used.

## Generators

### Current working directory

The `cwd` generator will output the current working directory. Its only
configuration variable, `cwd_max_width`, indicates the maximal percentage of the
terminal's width that the path may occupy before truncation occurs. The
following theme entries are required:

* `cwd_trunc` is the string that replaces the part of the path that is truncated
  when it is too long compared to the terminal's width.
* `cwd_fg_color` and `cwd_bg_color` are the foreground and background color
  indices for the section.
* `cwd_missing_fg_color` and `cwd_missing_bg_color` are the foreground and
  background color indices that will be used if the current directory is in
  fact missing.

### Date/time

The `datetime` generator will output the current date, the current time, or
both. It is controlled by the following configuration entries:

* `dt_show_date` controls whether the date should be displayed.
* `dt_show_time` controls whether the time should be displayed.
* `dt_date_fmt` is a `strftime` format that will be used for the date.
* `dt_time_fmt` is a `strftime` format that will be used for the date.

In addition, the following entries must be set in the theme:

* `dt_bg` is the background color for the section.
* `dt_time_fg` is the foreground color for the time.
* `dt_date_fg` is the foreground color for the date.

### Git information

The `git` generator is meant to display information about the Git repository the
current directory is a part of. It is controlled by the following configuration
entries:

* `git_branch_danger` is a list of branch names that will cause the current
  branch to be displayed with the "danger" color set.
* `git_branch_warn` is a list of branch names that will cause the current branch
  to be displayed with the "warning" color set.
* `git_detached_warning` controls the color set that will be used when the head
  is detached: `0` for the normal set, `1` for the "warning" set and `2` for the
  "danger" set.
* `git_show_status` controls whether the status of the current repository should
  be displayed.
* `git_show_stash` controls whether the stash depth should be displayed.

The theme entries belowed control the Git information sections' appearance:

* `git_branch_symbol` is the prefix for the current branch's name.
* The color sets for the branch display section are controlled by entries named
  `git_branch_${set}_fg` and `git_branch_${set}_bg`. The `${set}` must be one of
  `ok`, `warn` or `danger`.
* `git_repstate_bg` / `git_repstate_fg` are the colors of the section that
  indicates special states (e.g. rebase in progress, bare repository...)
* `git_status_pad` is a string that will be inserted between the various parts
  of the status sections.
* Two sets of entries control the sections that correspond to untracked and
  indexed changes. These sections are identified by replacing `${type}` with
  either `untracked` and `indexed` in the names below.
  * `git_${type}_symbol` is the prefix for the section's text,
  * `git_${type}_bg` is the background color for the section,
  * `git_${type}_normal_fg` is the foreground color for the normal text in the
    section,
  * `git_${type}_add_fg`, `git_${type}_mod_fg` and `git_${type}_del_fg` define
    the foreground colors for the symbols that indicate new, modified or removed
    files, respectively.
* `git_add_symbol`, `git_mod_symbol` and `git_del_symbol` define the symbols
  that indicate new, modified or deleted files in the status sections.
* `git_stash_symbol` contains the prefix of the stash indicator,
* `git_stash_fg` and `git_stash_fg` define the background and foreground colors
  for the stash indicator.

### Running jobs

The `jobs` generator will output the amount of background jobs in the current
shell. It is controlled by the following configuration variables:

  * `jobs_always` controls whether the job count should be displayed even when
    it is zero.

The following theme entries control how the jobs section is displayed.

  * `jobs_prefix` and `jobs_suffix` are the text of the prefix and suffix for
    the job count.
  * `jobs_bg` is the section's background color.
  * `jobs_${element}_style` and `jobs_${element}_fg` control the style and
    foreground color of the various parts of the section. `${element}` may be:
    * `count` for the count itself,
    * `prefix` or `suffix`.

### System load

The `load` generator will output the system's load average for the past minute
divided by the host's processor count. It is controlled by the `load_min`
configuration entry which specifies a percentage below which the section is not
displayed at all. The following theme entries are required:

* `load_title` is a string that is prepended to the generator's output.
* `load_low_fg` and `load_low_bg` are the foreground and background colors used
  when the load is beneath 34%.
* `load_med_fg` and `load_med_bg` are the foreground and background colors used
  when the load is between 34% and 66%.
* `load_high_fg` and `load_high_bg` are the foreground and background colors
  used when the load is higher than 66%.

### Previous command state

The `prevcmd` generator will output information about the previous command's
return value. It is controlled by the following configuration entries:

* `pcmd_show_symbol` controls whether a symbol that represents success or
  failure should be displayed.
* `pcmd_show_code` controls whether the return value should be displayed. It
  can be set to the usual `0` and `1` values to disable/enable, or to `2` to
  enable only when the return value indicates failure.
* `pcmd_pad_code` controls padding of the return value. `0` disables padding,
  `1` aligns to the left and `-1` to the right. The global padding character
  is used.
* `pcmd_colors` selects which parts of the output should use the theme's success
  or failure colors (`0` nothing, `1` symbol, `2` value, `3` both).

The following theme entries are needed:

* `pcmd_ok_sym` / `pcmd_err_sym` contain the symbols that represent success or
  failure, respectively.
* `pcmd_ok_fg` and `pcmd_ok_bg` define the foreground and background colors used
  to represent success. The foreground color may or may not be used, depending
  on the configuration.
* `pcmd_err_fg` and `pcmd_err_bg` define the foreground and background colors
  used to represent failure. The foreground color may or may not be used,
  depending on the configuration.
* `pcmd_text_fg` controls the foreground color of the strings that are excluded
  from using success/failure colors by the configuration.

### Python virtual environment

The `pyenv` generator will output the name of the currently active Python
virtual environment if there is one. It is controlled by the following
configuration entry :

* `pyenv_py_version` controls how the Python version is displayed; it can be
  set to `0` (never display the Python version), `1` (display the Python
  version if a virtual environment is active) or `2` (always display the
  Python version).

The following theme entries are needed:

* `pyenv_text` contains the text that is displayed before the name of the
  virtual environment and version.
* `pyenv_sep` is the separator that is displayed between the virtual
  environment's name and the Python version.
* `pyenv_fg` and `pyenv_bg` define the foreground and background colors for the
  section.

### User/host

The `userhost` generator will output the current user and host name. It is
controlled by the following configuration entries:

* `uh_username` controls whether the user name should be displayed.
* `uh_hostname` controls whether the host name should be displayed. It can be
  set to `0` (hidden), `1` (always display) or `2` (display on remote hosts
  only).
* `uh_remote` can be set to `1` in order to display an additional string on
  remote hosts.

In addition, the following entries must be set in the theme:

* `uh_remote_symbol` is the string to append to the section on remote hosts.
* `dt_user_fg` and `dt_user_bg` contain the foreground and background colors
  to use for normal, unprivileged users.
* `dt_root_fg` and `dt_root_bg` contain the foreground and background colors
  to use for the `root` account.
* `uh_host_fg` contains the foreground color for the hostname.