Prompt lines configuration

Before starting customization of colors, chars, etc., you will need to configure which segment you want to activate/deactivate and the order in which they are compressed.

This is done by two variables in your configuration files in hosts/ folder:

Exemples are better than long explication, so let us start.

Variable SEGMENT

As this variable is an array, the easiest form is:

SEGMENT=("first line" "second line")

You can see this documentation Arrays on tldp.org if you want to learn more about arrays in bash

In this array, each cell will define which segments are used for each prompt line. Segment should be separated by a comma ,.

Basic prompt

For instance, if you want simple line prompt with only username, hostname and pwd segments with command entry at the end (like default bash prompt), the variable SEGMENT should be:

SEGMENT=("username, hostname, pwd")

• Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

In this example, some segment will never be shown, for instance git informations, provided by git segment, or python virtual environtment, provided by virtualenv segment, will never be displayed !

Basic prompt with command below

If you want simple line prompt with only username, hostname and pwd segments but with command entry below the prompt the variable SEGMENT should be:

SEGMENT=("username, hostname, pwd, hfill")

See the special segment called hfill (see section [hfill][]) which will fill the line with empty char to colorize a complete line of your terminal.

• Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

Default prompt

The default value of SEGMENT, which is also the value used for most exemples in this documentation using most of the supported segments, is :

SEGMENT=(
    "return_code, tmux, pwd, hfill, keepass, username, hostname"
    "vcsh, virtualenv, vcs, kube, openstack, hfill"
)

• Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

Important

If using multine prompt, like the default one, if a line of the prompt does not have any no information to show, for instance when you are in your home folder and there is no specific environment loaded, then the line will not be prompt.

For instance, below are shown prompt in my home folder and in a work folder where lots of segments are loaded, using the default multiline configuration.**

• Basic folder

Prompt v1 (click on image to enlarge)

Prompt v2 (click on image to enlarge)

• When (almost) every segment are loaded

Prompt v1 (click on image to enlarge)

Prompt v2 (click on image to enlarge)

More examples are provided at the end of this page, see section More examples.

Variable SEGMENT_PRIORITY

Finally, let us configure the behaviour of the prompt when it will shrink, when ther is not enough place to print all segment.

Below is exemple of this behaviour:

• The prompt v1 (click on image to enlarge)

• The prompt v2 (click on image to enlarge)

This behaviour is configured through the variable SEGMENT_PRIORITY which defines the order in which segment will be contracted or hidden.

As this variable is an array, the easiest form is:

SEGMENT_PRIORITY=("first line" "second line")

You can see this documentation Arrays on tldp.org if you want to learn more about arrays in bash

In this array, each cell will define the order in which segments will be compressed for each prompt line. Segment should be separated by a comma ,.

For instance, let us use the default 2 lines prompt:

SEGMENT=(
    "tmux, pwd, hfill, keepass, username, hostname"
    "vcsh, virtualenv, vcs, kube, openstack, hfill"
)

By default, the value of SEGMENT_PRIORITY is :

SEGMENT_PRIORITY=(
    "tmux, username, hostname, keepass, pwd, return_code"
    "vcsh, virtualenv, kube, openstack, vcs"
)

This means that the prompt will shrink as follow:

• On first line, segment tmux will be first to shrink, then this will be segment username, then hostname, then keepass, then pwd and finally return_code. When none of these segment can be shrinked anymore, they will disappear in the same order.

• In parallel, second lines will also shrink when needed. First segment vcsh will shrink, then virtualenv, then kube then openstack and finally vcs. Finally, when none of these segment can be shrinked anymore, they will disappear in the same order.

This behaviour is the one illustrated in the GIFs above.

If you want to change this behaviour, you just have to change the order of the segment in SEGMENT_PRIORITY.

SEGMENT_PRIORITY=(
    "username, hostname, pwd, tmux, return_code, keepass"
    "vcsh, kube, openstack, virtualenv, vcs"
)

SEGMENT=(
    "username, hostname, pwd, hfill"
)
SEGMENT_PRIORITY=(
    "hostname, username, pwd"
)

More examples

Here are some other exemples show for v1 and v2. Click on images and GIFs to enlarge them.

Single line not filling terminal with lots of segments (not recommended)

Here is an example when lots (almost all segments) are put in one single line and when they are all loaded.

SEGMENT=(
    "tmux, vcsh, virtualenv, vcs, kube, openstack, keepass, username, hostname, pwd"
)
SEGMENT_PRIORITY=(
    "hostname, username, keepass, openstack, kube, vcs, virtualenv, vcsh, tmux, pwd"
)

• Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

As you can see (or probably not), this configuration is barely readable and so barely usable.

Crazy terminal with 4 lines

Let's go crazy, use 4 lines with all segment reparted on the lines and add some comment in the array to remember why each segment is on its line:

SEGMENT=(
    # Virtualization environment
    "tmux, vcsh"
    # Global variable config environement
    "keepass, kube, openstack"
    # Programation environment
    "vcsh, virtualenv"
    # Classic prompt
    "username, hostname, pwd"
)
SEGMENT_PRIORITY=(
    # Virtualization environment
    "tmux, vcsh"
    # Global variable config environement
    "keepass, kube, openstack"
    # Programation environment
    "vcsh, virtualenv"
    # Classic prompt
    "username, hostname, pwd"
)

• Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

Crazy terminal with 4 lines filling the terminal (not recommended)

Let's go crazy, use 4 lines filling full terminal size with all segment reparted on the lines and add some comment in the array to remember why each segment is on its line:

SEGMENT=(
    # Virtualization environment
    "tmux, hfill, vcsh"
    # Global variable config environement
    "keepass, hfill, kube, openstack"
    # Programation environment
    "vcsh, hfill, virtualenv"
    # Classic prompt
    "username, hostname, pwd, hfill"
)

* Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

Warning

Only the first line of the prompt in multiline configuration will have a full colored line. So if the first line does not show any information, you will not have the colored line.

For instance, below is the behavour of the last examples when in a folder where no environment is loaded.

• Prompt v1 (click on image to enlarge)

• Prompt v2 (click on image to enlarge)

Debugging

There are two variables that can be usefull and should mainly be used only using export command directly from the user input. These variable are DEBUG_MODE and DEBUG_LEVEL.

DEBUG_MODE variable

When this variable is set to any value, then the prompt will automatically activate all used segments. Those which does not have real informations to show will be filled with fake value.

This variable is usefull to see how your prompt look like when all segments are loaded and/or when debugging.

Below is an example of such behaviour.

DEBUG_LEVEL variable

This variable have for possible value:

• ERROR (the default value), print only errors information
• TIME, print errors and the time of computation of the prompt
• WARNING, print errors, the time of computation and warnings.
• INFO, print a lots of informations, errors, time of computation and warnings.
• DEBUG, print a lots more output, debug information, basic information, errors, warning, and time of computation.

When set, computation of the prompt will output some debug information depending on level sets. The more level is close to DEBUG the more informations will be outputed. This is done through the script lib/debug.sh, for more information see Debug Script Documentation.

This variable should not be set to WARNING, INFO nor DEBUG except when debugging because setting these values will prompt lots of information and make your prompt unusable as shown below:

Now, before starting to configure each segment, you will need to setup some General Variables used by both prompt v1 and prompt v2.