See this README on GitHub.
Here’s my theme for Zsh and Oh My Zsh that I developed for my personal workflow that is characterized by:
- git
- Python 3 development
- Consistent use of venv virtual environments
- I am the only person working on my machine
- Therefore I don’t need to be told who the “user” is
- I’m not working with multiple machines/hosts
- Therefore I don’t need to be told the name of the machine
- I know what time it is and can’t think of any reason to have a date or time stamp on the prompt line (though apparently other people do have such needs)
- I work on macOS 12.4 (Monterey) using iTerm and Oh My Zsh
- (Although I use VS Code, too, I almost always use iTerm2 as the terminal app rather than VS Code’s integrated terminal)
- This is the only environment on which Yellow Sea Diamonds has been tested
- Will my diamond emoji with color
“Yellow Sea” (“🔶”) render
correctly and with the the same color on other people’s systems?
- I don’t know!
This theme creates a two-line prompt structure (not including the leading blank line to create some whitespace after the just-previous output):
- Line 1:
- “(venv)” (or whatever the name of your virtual environment directory)
- The presence of this descriptor is conditional on your having an activated virtual environment
- See § Usage note: Prevent duplication of the ‘(venv)’ virtual-environment prompt below to stop virtualenv’s own “(venv)” output from being duplicative
- Current working directory, with “~” replacing $HOME when possible
- Git information (conditional on there being git information to display)
- “ | git: ”
- Branch name
- Clean (✅) or Dirty (❌), depending on whether there are uncommitted changes on your branch.
- The SHA-1 hash of the current commit
- “(venv)” (or whatever the name of your virtual environment directory)
- Line 2 (the actual prompt line):
- Report of return code, ONLY if the return code was nonzero
- Red box with white letters: “ERROR #64”, where here the 64 is an example of a return code I encountered.
- An easy way to test this is just to enter at the prompt:
sh -c 'exit 1' - I rejected including a ✅ or similar for a zero return code, because in my experience that’s not an exceptional event and so adding such would create visual noise not offset by the minimal informativeness of the extra symbol.
- The Yellow Sea Diamond prompt, (“🔶”), after which this theme is named
- Report of return code, ONLY if the return code was nonzero
Packing most of the content into the first line leaves plenty of room on Line 2 for comments with long arguments, particularly long file paths.
You can download this theme from its GitHub repository at:
https://github.com/jimratliff/yellow-sea-diamonds-zsh-theme/archive/refs/heads/main.zip
and unzip the archive to find the Oh My Zsh theme file yellow-sea-diamonds.zsh-theme.
Although that is the file name, the theme name is simply yellow-sea-diamonds.
You can install Yellow Sea Diamonds in either of the following locations
~/.oh-my-zsh/themes
or
~/.oh-my-zsh/custom/themes
Then edit your ~/.zshrc file and change its ZSH_THEME line to be:
ZSH_THEME="yellow-sea-diamonds"
Follow this up with:
source ~/.zshrc
When you activate a venv virtual environment, virtualenv will supply its own “(venv)” line of output. If you don’t prevent that, this will be annoyingly duplicative of Yellow Sea Diamond’s own “(venv)” prompt component. See the screenshot immediately below.
The key to preventing this duplication is issuing the following command before you activate your virtual environment:
export VIRTUAL_ENV_DISABLE_PROMPT=1
(Hat tip to icktoofay’s answer and Marlon Richert’s answer on Stack Overflow. Also, see the documentation for VIRTUAL_ENV_DISABLE_PROMPT: “Any virtualenv activated when this is set to a non-empty value will leave the shell prompt unchanged during processing of the activate script, rather than modifying it to indicate the newly activated environment.” (Emphasis in original.))
See the next screenshot for this method in action:
Of course, you won’t want to have to remember to type this command every time you activate a virtual environment. You’ll probably find it worthwhile to make an alias like the following:
alias activate_venv='export VIRTUAL_ENV_DISABLE_PROMPT=1;source venv/bin/activate'
Then, after cd-ing into the directory in which your venv directory resides, just type activate_venv to
simultaneously activate your virtual environment while also suppressing Zsh’s otherwise duplicative “(venv)” output. See the next screenshot:
An outstanding source to learn about customizing themes is Sarah Port, “Writing ZSH Themes: A Quickref,” CarbonFive, March 3, 2020. In particular the Quick Reference is amazing.
Also see:
- Armin Briegel, “Moving to zsh, part 6 — Customizing the zsh Prompt,” Scripting OS X.
- § “Prompt Expansion” in The Z Shell Manual.
It’s very easy to change the color scheme of Yellow Sea Diamonds.
Yellow Sea Diamonds specifies a color by using an integer 0–255 in, for example, an %{$FG[226]%} command, where FG
stands for “foreground,” as opposed to %{$BG[226]%}, which sets the background color.
[To be honest, I have no idea what all the characters in, for example, %{$FG[226]%}, are doing. If they’re really necessary, somehow I’ve gotten away with simple use of $FG[226], as you’ll see in the code for Yellow Sea Diamonds. (I’d love to be enlightened! 🧐]
If you want to conveniently access the mapping between integers and colors, just use the spectrum_ls command, e.g.,
see the next screenshot:
After you turn on a new color with $FG, you’ll at some point later want to reset it (so that color doesn’t take over the world) with
%f. To reset the background color, use %k. To reset both foreground and background simultaneously, you’ll often
see %{$reset_color%}.
You can also access a handfull of colors by name, rather than number: Black, Red, Green, Yellow, Blue, Magenta, Cyan,
White. If you specify a color by name, you’ll need to use the lowercase version of $FG and $BG, e.g., $fg[red].
The ultimate output of Yellow Sea Diamonds, or any such theme, is the prompt structure itself.
In YSD, this is defined at the very end of the theme:
PROMPT="
╭─$VIRTUALENV_REPORT $CWD $GIT_REPORT $COMMIT_HASH %{$reset_color%}
╰─$REPORT_RETURN_CODE\$(prompt_char) "
I hope that the components are named so transparently that it’ll be fairly obvious how to delete something you don’t want or rearrange the components that are already there.
Each of the components is defined above the prompt structure, and they are defined in the same order that they appear in the prompt structure (L to R, then up to down).
Of course, you can add components, too. But you’re on your own there. 😉
As you modify and refactor, I’d suggest that you continuously test your code.
One thing in particular to watch out for: Does the commit hash continue to update automatically? I’ve had the problem arise where a commit hash would be displayed, but then—after I made a subsequent commit—that hash wouldn’t change. It’s an easy failure to miss, so I suggest—as part of your testing during development—to continuously make a new commit to check whether its hash updates.
- 1.0.0 6/13/2022
This project is licensed under the MIT License - see the LICENSE.md file for details.