My everyday terminal environment: shell config, CLI tools, aliases, themes, and dotfiles I use across my machines.

Default macOS Terminal look vs my Ghostty setup

Table of Contents

• 📖 About
• 🖼️ Gallery
• 🧩 Pick A Piece
• 📦 What's Inside
• 🚀 Using The Whole Setup
• 🧪 Platforms Tested
• 🔁 Sync Workflow
• 🔒 Local Overrides
• 📝 Notes

---

📖 About

This repo documents the terminal setup I use. It's part config backup, part setup guide, and part reference for all the little changes that make my terminal unique.

Area	What is included
Shell	zsh, Oh My Zsh, plugin settings, aliases, and path setup
Prompt	My custom itis-compact prompt with a shortened path and status dot
Startup	Fastfetch as a startup screen, first-input clearing, and a quiet dotfiles update hint
Terminal	Ghostty config with blur, opacity, padding, and window sizing
Palette	A Mocha-inspired palette with my own tweaks and accents
Tools	eza, bat, glow, fzf, fzf-tab, zoxide, autosuggestions, and syntax highlighting
Images	chafa for rendering images directly inside the terminal
Sync	Scripts to apply the setup, update it, and recreate plugin installs

My goal with this repo: make one terminal setup feel perfect, then make that setup easy to understand, reuse, and tweak.

---

🖼️ Gallery

Fastfetch Startup Screen

Fastfetch runs when a new shell starts. The first input clears it, so it works like more of a welcome screen to prevent clutter.

Compact Prompt

The prompt keeps long paths short, shows git info, and uses a tiny status dot: green for success, red for failure.

Nice ls

Eza replaces plain ls with a cleaner project listing. The normal view keeps folders easy to scan, while the la view adds permissions, owners, sizes, dates, icons, and git status markers.

Tab Completion Preview

Fzf-tab turns tab completion into a fuzzy picker. Directories can preview with eza, and files can preview with bat.

Markdown In The Terminal

Glow renders Markdown with a custom Catppuccin Mocha based style. The md alias opens Markdown files with glow -p.

---

🧩 Pick A Piece

Feature	What it does	Files to look at
Startup screen	Shows Fastfetch on shell start and clears it after first input	shell/startup-fastfetch.zsh, shell/startup-fastfetch-clear.zsh, config/fastfetch/config.jsonc
Update hint	Quietly checks the dotfiles Git remote and points to the manual update script	shell/update-notifier.zsh, scripts/update.sh
Compact prompt	Custom Oh My Zsh theme with path shortening and status dot	oh-my-zsh/custom/themes/itis-compact.zsh-theme
Plugin setup	Loads git, fzf, fzf-tab, zoxide, eza, autosuggestions, and syntax highlighting	shell/plugins.zsh, packages/oh-my-zsh-plugins.txt
Colors	Custom Mocha palette for shell, completion, Eza, and markdown accents	shell/colors.zsh
Ghostty look	Stock Catppuccin Mocha theme, blur, opacity, padding, and window size	config/ghostty/config.ghostty
Markdown reader	Glow config and custom Catppuccin Mocha based style	config/glow
Terminal images	Renders image files directly in the terminal	packages/Brewfile, packages/debian.txt
CLI shortcuts	Small aliases like cat -> bat and md -> glow -p	shell/aliases.zsh

---

📦 What's Inside

home/                 Files that link directly into $HOME
shell/                Zsh modules sourced by home/.zshrc
config/               App configs for fastfetch, ghostty, glow, and bat
oh-my-zsh/custom/     Custom Oh My Zsh theme files
packages/             Package manifests for rebuilding machines
scripts/              Platform installers, apply/update tools, and validation
docs/                 Notes describing what this setup changes
assets/               README logo and terminal previews

The captured setup is documented in more detail here:

docs/current-setup.md

---

🚀 Using The Whole Setup

For a new machine, clone this repository anywhere and run:

./install.sh

The main installer detects the current environment and launches the matching installer from scripts/install/. It then:

• installs the platform packages
• installs Oh My Zsh and the configured third-party plugins
• links the dotfiles into your home directory
• validates the shell and configuration files
• offers to make Zsh the default shell when needed

Existing files are backed up under ~/.dotfiles-backups/ before being replaced. The linked shell files resolve the repository location automatically, so the checkout does not need to live at a specific path.

Preview what the installer would do without changing the machine:

./install.sh --dry-run

To re-apply an already-installed checkout without installing packages:

./scripts/apply.sh

Platform behavior

• macOS: installs Homebrew when missing, then installs packages/Brewfile.
• Debian/Ubuntu: installs Zsh, Git, curl, and CA certificates through apt, then installs every available package from packages/debian.txt.
• WSL: detects WSL automatically and uses the Debian/Ubuntu installer when the distribution provides apt-get.

Linux package availability varies by distribution release. Optional tools that are absent from the configured apt repositories are reported and skipped; the shell configuration has fallbacks for those tools. On WSL, this installs the shell setup inside the Linux distribution. A terminal application installed on Windows must still be configured on the Windows side.

---

🧪 Platforms Tested

Platform	Status	Notes
macOS	Tested	Primary setup; installs and uses Homebrew.
Debian/Ubuntu	Installer included	Uses apt; availability of optional packages depends on distro release.
WSL	Installer included	Supports Debian/Ubuntu WSL distributions that provide apt-get.
Other Linux	Unsupported	The installer exits with a clear message instead of guessing.

---

🔁 Sync Workflow

After changing config on one machine:

git add .
git commit -m "Update terminal setup"
git push

On another machine:

git pull
./scripts/update.sh

update.sh pulls the repo, re-applies the symlinks, and refreshes Oh My Zsh plugin repos.

Startup update notification

New terminal sessions do a quiet, throttled check to see whether this dotfiles checkout is behind its configured Git remote. It does not pull, install, refresh plugins, or change the repo.

If the cached check says an update is available, the shell prints a short reminder to run:

./scripts/update.sh

Network, remote, and auth errors stay silent. The default check interval is six hours, and the cache lives under:

${XDG_CACHE_HOME:-$HOME/.cache}/itis-dotfiles/update-check

Local controls can go in ~/.zshrc.local:

# Disable the startup check.
ITIS_DOTFILES_UPDATE_CHECK=0

# Check every 12 hours.
ITIS_DOTFILES_UPDATE_CHECK_SECONDS=43200

Oh My Zsh plugin repos are not checked automatically at startup. They are refreshed by the manual ./scripts/update.sh workflow.

---

🔒 Local Overrides

Machine-specific settings stay out of Git. These files are loaded when present:

• ~/.zshrc.local
• ~/.zprofile.local
• ~/.gitconfig.local

Use them for private aliases, work-only paths, tokens, secrets, or anything that should not travel to every machine.

---

📝 Notes

• This repo currently follows my real setup first and generalizes second.
• The gallery uses a real Fastfetch screenshot plus lightweight SVG previews stored in assets/screenshots.
• The live config is not changed just because the repo exists; use ./install.sh on a new machine or ./scripts/apply.sh to refresh an existing installation.

Back to top