shell-env · diff
git:20260630.9317dc2 to git:20261007.08a0dc2
58 added, 81 removed. Audit A to A.
---
name: shell-env
description: >-
- Stow-first shell environment editing for zsh, aliases, tmux/sesh, Starship,
- Ghostty, yabai, Git, and dotfiles packages. Use when the user wants to add or
- change terminal config, aliases, shell startup, or Stow-managed symlinks.
- Route Neovim-specific work to neovim and whole-system health checks to audit.
+ Edit the Stow-managed shell and terminal environment in ~/.dotfiles/home,
+ including zsh, aliases, tmux/sesh, Starship, Ghostty, yabai, Git, and link
+ structure. Use for focused terminal configuration changes. Route Neovim work
+ to neovim and whole-system health checks to audit.
---
- # Shell & Terminal Environment
+ # Shell and terminal environment
- All config is managed with **GNU Stow** from `~/.dotfiles`. Never edit files directly in `~` — always edit the source in `~/.dotfiles` and let Stow manage the symlinks.
+ The repository uses one GNU Stow package at `~/.dotfiles/home/`. Edit sources under that directory; `~/.dotfiles/README.md`, `dotfiles --help`, and the current symlink targets are authoritative when layout differs from this document.
- ## Config Locations
+ ## Current source locations
- | Tool | Source path | Symlinked to |
- |---|---|---|
- | Zsh | `~/.dotfiles/zsh/.zshrc` | `~/.zshrc` |
- | Zsh modules | `~/.dotfiles/zsh/zsh.d/` | `~/.zsh.d/` |
- | Ghostty | `~/.dotfiles/.config/ghostty/config` | `~/.config/ghostty/config` |
- | Tmux | `~/.dotfiles/.config/tmux/tmux.conf` | `~/.config/tmux/tmux.conf` |
- | Starship | `~/.dotfiles/.config/starship.toml` | `~/.config/starship.toml` |
- | yabai | `~/.dotfiles/.config/yabai/yabairc` | `~/.config/yabai/yabairc` |
+ | Tool | Source |
+ |---|---|
+ | Zsh | `~/.dotfiles/home/.zshrc` and `~/.dotfiles/home/zsh/zsh.d/` |
+ | Ghostty | `~/.dotfiles/home/.config/ghostty/config` |
+ | Tmux | `~/.dotfiles/home/.config/tmux/tmux.conf` |
+ | Starship | `~/.dotfiles/home/.config/starship.toml` |
+ | yabai | `~/.dotfiles/home/.config/yabai/yabairc` |
+ | Git | `~/.dotfiles/home/.gitconfig*` |
+ Confirm a target with `readlink` or `ls -ld` before structural work.
+
## Stow-first edit loop
- 1. Locate the source file under `~/.dotfiles`.
- 2. Inspect the current config before changing it; do not rely on remembered theme/font values.
- 3. Edit only the source file, never the symlink target in `~`.
- 4. Run the safest verification for the tool:
- - zsh: `zsh -n <file>` or open a new interactive shell
- - tmux: `tmux source ~/.config/tmux/tmux.conf`
- - Starship: `starship explain` or `starship timings`
- - Ghostty: inspect/reload config, then restart or use the app reload command when available
- - yabai: `yabai --restart-service`
- - Stow: `cd ~/.dotfiles && stow -n <package>` before relinking or restructuring
- 5. Report the source path changed, reload command, and verification result.
+ 1. Locate and inspect the source under `~/.dotfiles/home/`.
+ 2. Edit the source rather than the home-directory link.
+ 3. Run the narrowest syntax or behavior check for the changed tool.
+ 4. If link structure changed, run `dotfiles sync --dry-run`, inspect every proposed operation, then run `dotfiles sync`.
+ 5. Reload the smallest affected component.
+ 6. Report the source path, verification result, and reload or remaining manual step.
- Done when the config change is live or the remaining manual reload step is explicit.
+ Done when the source owns the intended home path, syntax and behavior checks pass, and the live configuration is reloaded or the remaining manual action is explicit.
- ## GNU Stow Workflow
+ ## Link workflow
+ Use the repository CLI rather than inventing per-tool Stow packages:
+
```sh
cd ~/.dotfiles
-
- # Symlink a package (creates symlinks in home dir)
- stow zsh
-
- # Remove symlinks for a package (does NOT delete source files)
- stow -D zsh
-
- # Re-stow (unlink + relink, useful after restructuring)
- stow -R zsh
-
- # Dry run — see what would change without doing it
- stow -n zsh
+ dotfiles sync --dry-run
+ dotfiles sync
```
- **When adding a new tool:**
+ For conflicts or unclear behavior, inspect `dotfiles --help`, `README.md`, and the `home/` tree before changing links. The current layout has one `home` package, so link work goes through `dotfiles sync` rather than per-tool Stow commands.
- 1. Create a package directory: `mkdir ~/.dotfiles/<toolname>`.
- 2. Mirror the target directory structure inside it (e.g., `.config/ghostty/` for `~/.config/ghostty/`).
- 3. Add the config file.
- 4. Run `stow -n <toolname>` from `~/.dotfiles`, then `stow <toolname>` if the dry run is clean.
+ ## Tool verification
- ## Zsh: Modular Config
+ ### Zsh
- `~/.dotfiles/zsh/zsh.d/` holds modular files, sourced automatically by `.zshrc`. Add new functionality as separate files rather than growing `.zshrc`:
+ Validate the edited module and then the complete startup path:
- ```text
- zsh.d/
- ├── aliases.zsh # all aliases
- ├── exports.zsh # PATH and environment variables
- ├── functions.zsh # shell functions
- ├── completions.zsh # completion config
- └── tools.zsh # tool-specific init (zoxide, starship, etc.)
+ ```sh
+ zsh -n ~/.dotfiles/home/.zshrc
+ zsh -n ~/.dotfiles/home/zsh/zsh.d/<module>.zsh
+ zsh -i -c exit
```
- ## Ghostty
-
- Config at `~/.dotfiles/.config/ghostty/config`. Inspect the file for current theme and font before changing them.
+ Preserve the numeric module order and inspect dependencies before moving code between files.
- Changes take effect on Ghostty restart (or `Cmd+Shift+,` to reload config on macOS).
+ ### Ghostty
- ## Tmux + sesh
+ Inspect the current config for accepted syntax, theme, and font before editing. Reload through the installed Ghostty version or restart the app, then verify the changed setting visually or through available diagnostics.
- Tmux config at `~/.dotfiles/.config/tmux/tmux.conf`. Session management via **sesh** — creates and attaches to named tmux sessions.
+ ### Tmux and sesh
```sh
- sesh connect <project> # create or attach to a session
- sesh list # list active sessions
+ tmux source-file ~/.config/tmux/tmux.conf
+ sesh list
```
- When editing tmux config, reload without restart: `tmux source ~/.config/tmux/tmux.conf` or prefix + `r` if you have that binding.
-
- ## Starship Prompt
+ Capture reload errors. Preserve the configured TPM directory and ensure the plugin manager initializes once.
- Config at `~/.dotfiles/.config/starship.toml`. Docs: `starship.rs/config`.
+ ### Starship
```sh
- starship explain # shows what each segment in current prompt means
- starship timings # shows how long each module took to render
+ starship explain
+ starship timings
```
- ## yabai
+ Use the current prompt to verify the affected module.
- Window manager config typically at `~/.dotfiles/.config/yabai/yabairc`. Reload after changes:
+ ### yabai
```sh
yabai --restart-service
```
+ Verify the changed rule or behavior after restart rather than treating service restart as sufficient.
+
## References
| Priority | Load when | Reference |
|---|---|---|
- | High | Modern CLI tools or shell aliases: eza, bat, fd, rg, zoxide, fzf, lazygit | `references/modern-cli-tools.md` |
- | High | Terminal emulator, tmux/sesh, Starship, yabai, or theme consistency config | `references/terminal-config.md` |
- | Medium | Git identity setup, multi-config, signing, or git aliases | `references/git-config.md` |
+ | High | Adding aliases or evaluating modern CLI alternatives | `references/modern-cli-tools.md` |
+ | High | Changing Ghostty, tmux/sesh, Starship, yabai, or cross-tool theme configuration | `references/terminal-config.md` |
+ | High | Changing Git identity, signing, conditional includes, pager, or aliases | `references/git-config.md` |
- ## Quick Reference
+ ## Quick checks
```sh
- # Verify a symlink is correctly set up
- ls -la ~/.zshrc # should point to ~/.dotfiles/zsh/.zshrc
-
- # Check all stow packages currently linked
- ls ~/.dotfiles/ # each dir is a stow package
-
- # Find broken symlinks in home dir
+ readlink ~/.zshrc
+ readlink ~/.config/ghostty/config
+ cd ~/.dotfiles && dotfiles sync --dry-run
find ~ -maxdepth 3 -type l ! -e 2>/dev/null
```