Dotfiles

This is my ZSH configuration and personal dotfiles. Please review everything before you attempt to use this. Some things might be macOS-specific, but I try to keep everything as platform-agnostic as possible. This is a public repository mostly for easy installs on additional machines, but feel free to take a look!

Prerequisites

• ZSH configured as the default shell (it is by default on macOS)
• Git is installed (on macOS, install using xcode-select --install)
• Homebrew is installed (install from brew.sh)

Installation

1. Make sure zsh is the default shell: echo $SHELL (if not, set it as default using chsh -s [path_to_zsh])
2. Optionally, fork this project and use your own repo below (best so you can customize it and push your changes back)
3. Install and select a Nerd Font in Terminal (see "Font" below)
4. Install homebrew (also required on Linux for many tools that are very boilerplatey to install on various distros otherwise)
5. Install chezmoi using brew
6. Run chezmoi init --force --apply [this_repos_url]
7. Open a new shell to view the results

Main Moving Parts

• chezmoi (dotfiles manager, applies the files in this repo to your $HOME)
• antidote (ZSH plugin manager, reads plugins from dot_config/zsh/antidote/plugins.txt)
• starship (modern customizable prompt)

Extras

• zoxide (z directory jumper command)
• zellij (pane-based terminal multiplexer)
• eza (replaces ls with an alias)
• rg (ripgrep, fast search)
• fzf (fuzzy finder) + fzf-tab plugin (fzf-enhanced tab completion)
• bat (replaces cat with an alias)
• btop (top alternative)
• tlrc (modern tldr client with quick cheat sheets)
• lazygit (git TUI)
• jq (JSON processor and URI encoding/decoding helper)
• Some other ZSH plugins and niceties (installed using antidote)
• A few aliases and tools to make life easier (mkcd, uuid, url-encode, url-decode, escape-json, unescape-json, escape-xml, unescape-xml, escape-js, unescape-js, base64-encode, base64-decode, md5-file, sha256-file, reveal, git and ripgrep shorthands, etc.)

Keeping Stuff Updated

These commands can be used instead of the chezmoi and antidote commands in most cases.

• dot-update pulls the latest changes, applies them, and updates ZSH plugins in one go via chezmoi
• dot-apply applies the working copy's state to your home directory and updates ZSH plugins
• dot-push pushes local dotfiles commits from the chezmoi source repo to upstream
• dot-status shows local-only and remote-only dotfiles commits relative to upstream
• dot-log shows the chezmoi source repo history as a decorated graph

Modifying Your Setup

Use chezmoi commands such as chezmoi edit or open ~/.local/share/chezmoi (which contains the dotfiles working copy) in your editor of choice. Make any changes you want, commit them, then run chezmoi apply to apply those changes to your home folder. Make sure to push the changes back to the remote for backup and sharing with your other machines!

Extension Points

• ~/.zshrc_local is sourced during shell startup and can be used for machine-specific exports, PATH additions, and tool initialization that should stay out of the shared dotfiles
• PROMPT_HOST_COLOR can be set in ~/.zshrc_local to give that machine a distinct first Starship prompt capsule color, for example export PROMPT_HOST_COLOR='#5e8ffb'

Customizations

• Ctrl-X Ctrl-E opens the current command in $VISUAL or $EDITOR
• Ctrl-J inserts a literal newline into the current shell buffer so multiline commands can be edited as one buffer without triggering PS2

Secrets

This repository is public, so secrets should never be committed here in plain text.

• Use ~/.zshrc_local for machine-local configuration
• Do not store API keys, tokens, private certificates, passwords, or similar sensitive values in tracked dotfiles.

Font

To get nice glyphs in the pre-configured Starship prompt, install a Nerd Font. You can choose any font that has been patched with the Nerd Fonts patcher (many options here), but I recommend using SF Mono Nerd Font which is derived from the SF Mono font by Apple (the Mac's default Terminal font).

Install it through homebrew: brew tap epk/epk && brew install font-sf-mono-nerd-font then select the regular weight in your Terminal profile.

Implementation Details

SSH Clipboard Support in Terminal.app

This setup integrates fortinmike/osc52pty (an updated fork of roy2220/osc52pty) so supported terminal editors such as micro can copy text to the local Mac clipboard from a remote host while running in SSH sessions in Terminal.app which normally does not support that.

This requires the remote host to also have these dotfiles installed OR alias micro=micro -clipboard terminal in its ZSH config OR manually running micro with the -clipboard terminal flag, otherwise the clipboard won't propagate to the local Mac. The keyboard shortcuts are the same as micro running locally:

• Ctrl-C: copy selected text in the editor to your local Mac clipboard
• Cmd-V: paste from your local Mac clipboard

Ctrl-V is not implemented in our osc52pty fork because it would allow remote processes to grab the local clipboard without user interaction at any time.