Hometown: A Dynamic, Highly Configurable Git-Focused Zsh Theme

What I want in my prompt are the time, the directory I’m in, whether I’m logged in as a user that isn’t my usual user, whether I’m on a host that isn’t my usual host, whether the previous command errored, and lots of Git info.

That’s what my zsh theme Hometown shows.

Which Git data points to include is configurable. The Git data points you do include can appear, disappear, and change colors based on the Git status.

You can configure certain users and hosts as hidden — use that to only show user and/or host if they aren’t your usual.

How much of the directory’s path to show is configurable.

I don’t want to be stuck in the same thing always, and wanted it to be flexible enough for other users to enjoy, so every color and symbol is customizable; there are one-line, two-line, and three-line layout options; and there’s a spot for you insert any arbitrary prompt code you’re missing.

A lot of information, but the presentation is compact. Here’s a screenshot of Hometown with its default configuration:

That little thing packs in a lot of information:

• the user is one I’ve configured as hidden (otherwise the user would be shown)
• the host is one I’ve configured as hidden (otherwise the host would be shown)
• the current directory is the root of the Git repo hometown-prompt, which is in the olets directory
• the working tree is dirty (if it weren’t, the branch name would not be colorized)
• the branch main is checked out (if HEAD were detached, the checked-out commit’s SHA would be shown)
• main has an upstream (if it didn’t, the word “local” would be shown)
  • main’s the upstream is origin/main (if the upstream branch name were different, it would be show; if the upstream’s remote were not origin, it would be shown too)
  • main is zero commits behind its upstream (if it were the “behind” count would be shown)
  • main is fifteen commits ahead of its upstream
• main has not be set up for a triangular workflow (if it were the push remote would be shown)
• there is no tag at the checked-out commit (if there were any the first would be shown)
• there are seven stashes, and three staged new files
• there are no untracked files, no conflicted files, no unstaged deleted files, no unstaged modified files, no staged deleted files, and no staged modified files (if there were, those symbols would have number and would be colorized and not dimmed)
• no files are marked as skip-worktree (if there were, the skip-worktree symbol and count would be shown)
• no files are marked as assume-unchanged (if there were, the assume-unchanged symbol and count would be shown)
• there is no ongoing action (e.g. rebase, cherry-pick, etc; if there were it would be shown)
• the previous command did not error (green prompt character)
• the user is not root (prompt character is %)

Not the look you want? Change it!

• Layout, every color, every symbol, the hidden users, the hidden hosts, the default remote, and the default push remote can be configured.
• If you prefer words over symbols —e.g. “stashes” instead of “⇲”— that’s just one toggle away, and the words can be customized too (you don’t even have to make them words— you could have two symbol sets to switch between)
• You can disable some content entirely, and custom content can be inserted.

Here’s a screenshot of the same scenario but with Hometown configured to take up three lines, to use words instead of symbols, and to hide inactive status info rather than dimming it.

Here’s a screenshot Hometown configured to put everything on one line, and to hide rather than dim inactive status info and inactive behind/ahead.

Here’s on one more screenshot showing custom colors, and custom symbols

That’s just a few of the possibilities: you can mix and match layout customization, color customization, and symbol/word customization. And it’s only one scenario: what is shown changes with the Git status.

Learn more in the Hometown docs.

If you like it, or just feel like saying “nice work”, let me know by starring the GitHub repo.