mkprompt is a simple, fast and fully customizable prompt generation framework for zsh
The prompt can be one of the most powerful features of your favorite shell, but it is a mess to maintain and most people don't even bother. If you have more than a basic prompt, the $PROMPT and $RPROMPT variables become unreadable and unmaintainable. Quite a few themes out there look nice, but they're a "one-size-fits-all" approach, and there's always something that bothers me.
As such, I decided to create a simple yet powerful framework for building a prompt in a way that is maintainable and easily customizable, mkprompt. Instead of the framework assuming what everyone wants, it just gives you some tools to make customizing and extending your prompt easy and maintainable. mkprompt is in essence a builder for $PROMPT-like variables which allows you to add content to your prompt in sections, and automatically takes care of all the annoying book-keeping such as delimiters and prompt-escaping colors.
mkprompt was developed and tested on zsh 5.4.2.
The vcs_info_async module requires zsh-async to be loaded.
Clone this repository and source mkprompt.zsh, or use your preffered plugin manager (such as zplug).
In your .zshrc, simply add mkprompt_init --default, and that's it! This command will load the default configuration (see mkprompt_default.zsh which is very similar to my personal setup.
To customize, copy that file to your zshrc inbetween a mkprompt_init and mkprompt_finish call. In short, mkprompt_init initializes the mkprompt subsystem, and mkprompt_finish writes the results to the prompt variables.
The first thing you should do is call mkprompt_init. This initializes the mkprompt subsystem and exposes the various methods listed below.
Starts the process of generating a prompt string. Typically, you would use mkprompt_start "PROMPT" or mkprompt_start "RPROMPT", although any variable name is allowed.
By default, prompts are built left-to-right (except $RPROMPT which generates right-to-left). To override, use the -rtl parameter.
Adds a new section to the prompt.
mkprompt_add [<parameters>] [-- <content> | -env <content-variable>], where
| Name | Description |
|---|---|
parameters |
any of the parameters listed below. |
content |
the section content |
content-variable |
environment variable containing the section content (gets expanded every time the prompt is rendered) |
NOTE: -- <content> and -env <content-variable> are exclusive.
| Parameter | Description |
|---|---|
| -d | next delimiter character (equivalent to using mkprompt_set_delim after this command) |
| -s | style escape code (e.g. $fg[red]) NOTE: must be only non-printable characters |
Sets the string that should be used before the next (and only the next) section.
Adds a raw string to the prompt directly, ignoring the delimiter and any escaping necessary.
Creating a module is very simple, since it only requires creating a function which wraps a mkprompt_add call.
A few modules are included with mkprompt:
Name (mkprompt_*) |
Description |
|---|---|
| clock | Shows the current time (HH:MM) |
| cwd | Shows the current working directory. Can be customized with different formatters using -f <formatter>, possible ones are zsh (default), prefix and prefix-unique. A custom formatter function may also be provided. |
| exec_time | Shows the execution time of the last command if it exceeded a certain duration |
| hostname | Shows the host name of the machine |
| jobs | Shows the number of jobs running in the background |
| prompt | Shows the prompt symbol (e.g. %) |
| username | Shows the current username |
| vcs_info | Shows information about the repository in CWD, if any. Local synchronous version |
| vcs_info_async | Asynchronous version of mkprompt_vcs_info with extra functionality. Requires zsh-async plugin. |
| vimode | Shows vi when ZLE is in vimode |
For module usage and documentation, check the comments at the top of each module's file or the default configuration.
mkprompt_finish is responsible for writing the prompt variables to the environment and then cleaning up the mkprompt_* namespace. It should always be called after all other mkprompt_* calls.
mkprompt is licensed under the MIT License.