Yellow Sea Diamonds 🔶🔶🔶 theme for Zsh/Oh My Zsh

See this README on GitHub.

Description of output and selective discussion of rationales

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
• 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

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.

Examples of output

Current working directory (CWD) only—no git, no venv, no error return code

CWD plus activated virtual environment

CWD plus git (with no uncommitted changes, i.e., “clean”)

CWD plus git (with uncommitted changes, i.e., “dirty”)

CWD plus nonzero return code

Install Yellow Sea Diamonds

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 

Usage note: Prevent duplication of the “(venv)” virtual-environment prompt

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:

Some tips for customizing Yellow Sea Diamonds, or any theme, to your liking

Good resources to learn about customizing themes

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.

Changing colors

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].

Deleting a component or rearranging components

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. 😉

Look out for: does the commit hash continue to update automatically?

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.

Version History

• 1.0.0 6/13/2022

License

This project is licensed under the MIT License - see the LICENSE.md file for details.