Ecosyste.ms: Awesome

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

https://github.com/bwpge/zcmder

A Cmder inspired zsh theme with git prompt features
https://github.com/bwpge/zcmder

Last synced: about 2 months ago
JSON representation

A Cmder inspired zsh theme with git prompt features

Lists

README 

        
# zcmder



A `zsh` theme inspired by [Cmder](https://cmder.app/) with some additional `git` related prompt features.






## Installation



### Oh My Zsh



Clone this repository into your `.oh-my-zsh/custom/themes` directory:



```sh

git clone https://github.com/bwpge/zcmder "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/zcmder"

```



Set the theme in your `.zshrc`:



```sh

ZSH_THEME=zcmder/zcmder

```



### Manual



Clone this repository to your machine (e.g., `~/.zsh`):



```sh

git clone https://github.com/bwpge/zcmder ~/.zsh/zcmder

```



Source the theme in your `.zshrc`:



```sh

source ~/.zsh/zcmder/zcmder.zsh-theme

```



## Updating



To update, pull any new commits from this repository:



```sh

cd "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/zcmder" && git pull

```



Be sure to reload (e.g., `omz reload`) or source the new file (e.g., `source zcmder.zsh-theme`) for any active sessions.



## Configuration



Environment variables used by this theme are always prefixed with `ZCMDER_`. This theme uses following associative arrays:



- [`ZCMDER_COMPONENTS`](#zcmder_components)

- [`ZCMDER_STYLES`](#zcmder_styles)

- [`ZCMDER_OPTIONS`](#zcmder_options)

- [`ZCMDER_STRINGS`](#zcmder_strings)



When the theme is sourced, these variables are reset to ensure proper declaration and initial values. To customize them, set your desired values *after* sourcing the theme (or `oh-my-zsh.sh`).



Example `.zshrc`:



```sh

ZSH_THEME=zcmder/zcmder

source $ZSH/oh-my-zsh.sh



# zcmder options

ZCMDER_STYLES[cwd]="fg=green,underline" # use green fg and underline effect on cwd

ZCMDER_STYLES[git_branch_default]='fg=blue'  # use blue for default git branch color

ZCMDER_STYLES[git_new_repo]='bg=#2277ff,standout'  # use RGB value for new repo bg color

ZCMDER_COMPONENTS[python_env]=false  # disable python env component

ZCMDER_STRINGS[git_separator]=''  # don't print 'on ' before git prompt

ZCMDER_STRINGS[git_prefix]='â–  '  # use different branch icon

```



The following tables explains each option and usage.



### `ZCMDER_COMPONENTS`



Controls which components or segments of the prompt are printed.



| Key | Type | Usage |

| --- | ---- | ----- |

| `cwd` | bool | Print the current working directory in the prompt |

| `git_status` | bool | Print a git status (if in a git repo) in the prompt |

| `hostname` | bool | Print the hostname (zsh expanded `%M`) in the prompt |

| `python_env` | bool | Print the current python environment (`conda`or `venv`) in the prompt |

| `username` | bool | Print the username (zsh expanded `%n`) in the prompt |



### `ZCMDER_STYLES`



Controls colors and text effects of the various items in the prompt.



This associative array uses very similar syntax as "types of highlighting" in [`zshzle(1)`](https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting):



- Values must be a string

- Tokens are separated by commas (without leading or trailing spaces)



Valid style tokens:



- `fg=`: see below for color formats

- `bg=`: same as `fg`

- `bold`: render bold or "intense" text (some terminals render this with "bright" colors and no font weight)

- `dim`: render faint text (some terminals treat this as bold)

- `italic`: render italicized text (some terminals treat this as inverse or blink effect)

- `underline`: render underlined text

- `standout`: uses zsh's `%S` prompt expansion for the terminal's standout mode, typically "reverse video" (see `invert`)

- `invert`: explicitly writes `\x1b[7m` for reverse video (not supported by all terminals)

    - Note: prefer using `standout`

    - If both `standout` and `invert` are specified in a style, `invert` is ignored



Valid colors have the following form (see [`fg` section of *Character Highlighting* in `zshzle(1)`](https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting) for more information):



- Common name (`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white`)

- 256-color integer value (e.g., `8` for "bright black" or `142` for `Gold3`, see [this reference](https://ss64.com/bash/syntax-colors.html))

- Hex RGB string `#RRGGBB`



Example usage:



```sh

# green and bold text, inverted (green/default-bg swapped)

ZCMDER_STYLES[cwd]='fg=2,bold,standout'

# white on black in italic/underline

ZCMDER_STYLES[cwd]='fg=#ffffff,bg=#000000,italic,underline'

```



Git status styles have the following priority:



- `git_staged`

- `git_unmerged`

- `git_untracked`

- `git_modified`

- `git_repo_new`

- `git_branch_default`



| Key | Type | Usage |

| --- | ---- | ----- |

| `caret` | style | Default caret style |

| `caret_error` | style | Caret style when the last exit code was non-zero |

| `cwd` | style | style of the current working directory |

| `cwd_readonly` | style | style when the current working directory is read-only |

| `git_branch_default` | style | Default git status style |

| `git_modified` | style | Git status style when only tracked files are modified |

| `git_new_repo` | style | Git status style when in a new repository |

| `git_staged` | style | Git status style when all local changes are staged |

| `git_unmerged` | style | Git status when there are unmerged changes |

| `git_untracked` | style | Git status when untracked (dirty) files are present |

| `python_env` | style | The style for current python environment name |

| `user_and_host` | style | style for both username and hostname components |



### `ZCMDER_OPTIONS`



Controls general behavior of the prompt.



| Key | Type | Usage |

| --- | ---- | ----- |

| `git_show_remote` | bool | Show the remote with git status (e.g., `main:origin/main`) |

| `newline_before_prompt` | bool | Print an empty line before the next prompt (excluding the first prompt) |



### `ZCMDER_STRINGS`



Controls values or tokens in each component that are printed.



| Key | Type | Usage |

| --- | ---- | ----- |

|`caret`| string | Prompt string (the value printed directly before user input area) |

|`caret_root`| string | Prompt string when running with elevated permissions |

|`git_ahead_postfix`| string | Printed when repo is ahead of upstream (initialized with `$ZSH_THEME_GIT_PROMPT_AHEAD`) |

|`git_behind_postfix`| string | Printed when repo is behind upstream (initialized with `$ZSH_THEME_GIT_PROMPT_BEHIND`) |

|`git_clean_postfix`| string | Printed when repo has no local changes (initialized with `$ZSH_THEME_GIT_PROMPT_CLEAN`) |

|`git_dirty_postfix`| string | Printed when repo contains unstaged changes (initialized with `$ZSH_THEME_GIT_PROMPT_DIRTY`) |

|`git_diverged_postfix`| string | Printed when repo is both ahead and behind (diverged from) upstream (initialized with `$ZSH_THEME_GIT_PROMPT_DIVERGED`) |

|`git_label_new`| string | Label to use for a new repository |

|`git_prefix`| string | Prefix always printed for git status e.g., a branch icon or `git(` (initialized with `$ZSH_THEME_GIT_PROMPT_PREFIX`) |

|`git_separator`| string | A separator or preamble before the git status is printed e.g., `' on '` |

|`git_stashed_modifier`| string | Printed when repo contains stashes (initialized with `$ZSH_THEME_GIT_PROMPT_STASHED`) |

|`git_suffix`| string | Suffix always printed for git status e.g., `)` (initialized with `$ZSH_THEME_GIT_PROMPT_SUFFIX`) |

|`readonly_prefix`| string | Printed before current working directory when read-only (see `man test`, `-w` flag) |



### Prevent Modifying `ZSH_THEME_GIT_PROMPT_*`



By default, this theme will set/change several `ZSH_THEME_GIT_PROMPT_*` environment variables since `ZCMDER_STRINGS` initializes values from these variables. Changes to these variables will persist through `omz reload`, so this behavior may not be desireable.



To disable this behavior, set `ZCMDER_NO_MODIFY_ZSH_THEME` prior to loading `oh-my-zsh` or sourcing the theme.



Example `.zshrc`:



```sh

# ...



ZSH_THEME=zcmder/zcmder

ZCMDER_NO_MODIFY_ZSH_THEME=1

source $ZSH/oh-my-zsh.sh



# ... zcmder config

```



To use the `zcmder` git status style without modifying `ZSH_THEME_GIT_PROMPT_*` variables, use the following options after sourcing this theme:



```sh

ZSH_THEME=zcmder/zcmder

ZCMDER_NO_MODIFY_ZSH_THEME=1

source $ZSH/oh-my-zsh.sh



# zcmder config

ZCMDER_STRINGS[git_ahead_postfix]=" ↑"

ZCMDER_STRINGS[git_behind_postfix]=" ↓"

ZCMDER_STRINGS[git_clean_postfix]=" ✓"

ZCMDER_STRINGS[git_dirty_postfix]=" *"

ZCMDER_STRINGS[git_diverged_postfix]=" ↑↓"

ZCMDER_STRINGS[git_prefix]="î‚  "

ZCMDER_STRINGS[git_stashed_modifier]=" âš‘"

ZCMDER_STRINGS[git_suffix]=""

```