dotfiles

Category: Tools & Productivity | Uploader: Proteusiq | Downloads: 0 | Version: v1.0（Latest）

Repository knowledge for this dotfiles setup. Use when adding tools, editing shell configs, understanding the architecture, or working with GNU Stow.

Changelog: Source: GitHub https://github.com/Proteusiq/dotfiles

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 docs.yml 1.2 KB
📁 aerospace/
- 📁 .config/
  - 📁 aerospace/
    
    📄 .aerospace.toml 7.8 KB
📁 bin/
- 📄 aliases.py 23.6 KB
- 📄 tools.py 26.8 KB
📁 docs/
- 📁 .vitepress/
  - 📁 theme/
    
    📄 custom.css 2.7 KB
    
    📄 CustomHome.vue 268 B
    
    📄 FoxLogo.vue 3.1 KB
    
    📄 HomeHeroImage.vue 3.1 KB
    
    📄 index.ts 173 B
  - 📄 config.mts 2.2 KB
- 📁 guide/
  - 📄 architecture.md 5.3 KB
  - 📄 getting-started.md 2.1 KB
  - 📄 git.md 3.8 KB
  - 📄 installation.md 4.3 KB
  - 📄 neovim.md 5.1 KB
  - 📄 shell.md 3.8 KB
  - 📄 terminal.md 4.4 KB
- 📁 public/
  - 📁 icons/
    
    📄 code.svg 286 B
    
    📄 package.svg 483 B
    
    📄 palette.svg 614 B
    
    📄 terminal.svg 285 B
    
    📄 wrench.svg 362 B
    
    📄 zap.svg 259 B
  - 📄 fox.svg 1.3 KB
- 📁 reference/
  - 📄 aliases.md 5.2 KB
  - 📄 cli.md 4.1 KB
  - 📄 keybindings.md 5.3 KB
  - 📄 tools.md 10.8 KB
- 📄 index.md 2.7 KB
- 📄 package-lock.json 85.8 KB
- 📄 package.json 260 B
📁 fzf/
- 📁 .fzf/
  - 📄 fzf-git.sh 11.7 KB
  - 📄 fzf.zsh 325 B
📁 ghostty/
- 📁 .config/
  - 📁 ghostty/
    
    📄 config 1.0 KB
📁 git/
- 📄 .gitconfig 1.6 KB
- 📄 .gitignore 586 B
- 📄 .stow-local-ignore 240 B
📁 nvim/
- 📁 .config/
  - 📁 nvim/
    
    📁 lua/
    
    📁 config/
    
    📄 autocmds.lua 1.1 KB
    
    📄 colors.lua 850 B
    
    📄 keymaps.lua 209 B
    
    📄 lazy.lua 1.8 KB
    
    📄 options.lua 1.7 KB
    
    📁 plugins/
    
    📄 atone.lua 71 B
    
    📄 betteresc.lua 111 B
    
    📄 camouflage.lua 946 B
    
    📄 catppucin.lua 67 B
    
    📄 debugging.lua 1.9 KB
    
    📄 extras.lua 715 B
    
    📄 gitconflict.lua 69 B
    
    📄 harpoon.lua 1.9 KB
    
    📄 lazygit.lua 869 B
    
    📄 live_command.lua 185 B
    
    📄 mason.lua 942 B
    
    📄 multicursor.lua 2.3 KB
    
    📄 navbuddy.lua 857 B
    
    📄 opencode.lua 1.8 KB
    
    📄 readme.lua 260 B
    
    📄 snacks.lua 5.0 KB
    
    📄 surround.lua 149 B
    
    📄 telescope.lua 850 B
    
    📄 tinyinlinediagnostic.lua 294 B
    
    📄 treesitter.lua 535 B
    
    📄 typr.lua 114 B
    
    📄 yazi.lua 686 B
    
    📄 .gitignore 51 B
    
    📄 .neoconf.json 183 B
    
    📄 init.lua 72 B
    
    📄 lazy-lock.json 6.8 KB
    
    📄 lazyvim.json 596 B
    
    📄 LICENSE 11.1 KB
    
    📄 README.md 171 B
    
    📄 stylua.toml 58 B
📁 scripts/
- 📄 logging.sh 2.8 KB
- 📄 README.md 22.1 KB
- 📄 ui.sh 3.3 KB
- 📄 versions.sh 24.8 KB
📁 sesh/
- 📁 .config/
  - 📁 sesh/
    
    📄 sesh.toml 189 B
📁 starship/
- 📁 .config/
  - 📁 starship/
    
    📄 starship.toml 134 B
📁 tmux/
- 📄 .tmux.conf 6.2 KB
📁 yazi/
- 📁 .config/
  - 📁 yazi/
    
    📁 plugins/
    
    📁 enter-or-open.yazi/
    
    📄 init.lua 157 B
    
    📁 smart-enter.yazi/
    
    📄 init.lua 173 B
    
    📄 cspell.json 194 B
    
    📄 init.lua 1 B
    
    📄 keymap.toml 2.4 KB
    
    📄 theme.toml 94 B
    
    📄 yazi.toml 2.2 KB
📁 zsh/
- 📄 .aliases 13.4 KB
- 📄 .exports 5.0 KB
- 📄 .zlogin.sh 255 B
- 📄 .zshenv.sh 963 B
- 📄 .zshrc 1.4 KB
- 📄 antigen.zsh 57.1 KB
📄 .editorconfig 205 B
📄 .gitignore 984 B
📄 AGENTS.md 11.1 KB
📄 Brewfile 11.6 KB
📄 Brewfile.lock.json 172.6 KB
📄 install.sh 18.4 KB
📄 LICENSE 1.1 KB
📄 prompts.md 7.1 KB
📄 README.md 48.5 KB
📄 run.sh 1.1 KB
📄 SKILL.md 8.0 KB
📄 Tools.md 54.2 KB

SKILL.md

---
name: dotfiles
description: Repository knowledge for this dotfiles setup. Use when adding tools, editing shell configs, understanding the architecture, or working with GNU Stow.
---

# Dotfiles Repository Knowledge

This document contains repository-specific knowledge for working with this dotfiles setup.

## Adding Tools

**Important:** Never install tools directly (e.g., `brew install`, `cargo install`). Always add to dotfiles first, then run `update`.

### Full Flow for Adding a Tool

1. **Check availability** - Search for the tool (`brew search`, check taps, PyPI, crates.io, etc.)
2. **Add to correct location** - Brewfile (with tap if needed) or install.sh
3. **Add to `Tools.md`** - Full documentation: description, commands, key bindings, use cases
4. **Add to `bin/tools.py`** - Short entry in the appropriate `*_TOOLS` list for `update --info`
5. **Run `update`** - Use `update --only brew`, `update <tool>`, or `update` to install

### Primary: Brewfile (most tools)

Location: `Brewfile`

```ruby
# CLI tools
brew "newtool"

# GUI applications  
cask "newapp"

# Custom repositories (taps)
tap "user/repo"
brew "user/repo/tool"
```

After editing, run: `update --only brew` or `update <toolname>`

### Secondary: install.sh (non-Homebrew tools)

Location: `~/dotfiles/install.sh`

| Tool Type | Where to Add | Pattern |
|-----------|--------------|---------|
| **UV tools** (Python) | `setup_utils()` | Add to `for tool in harlequin sqlit-tui ...` loop |
| **Git repos** | `setup_utils()` | `git_install "name" "url" "path" "description"` |
| **Cargo** | `setup_utils()` | `cargo install <tool>` with `has_cmd` guard |
| **Curl scripts** | Appropriate function | `curl -fsSL <url> \| bash` with existence check |

Example patterns from install.sh:

```bash
# Git-based installation
git_install "tpm" "https://github.com/tmux-plugins/tpm" "$HOME/.tmux/plugins/tpm" "tmux plugin manager"

# UV tool installation
for tool in harlequin sqlit-tui; do
    uv tool list 2>/dev/null | grep -q "^$tool " &&
        uv tool upgrade "$tool" || uv tool install "$tool"
done

# Cargo installation (with guard)
if ! has_cmd rgr && has_cmd cargo; then
    run_quiet cargo install repgrep
fi
```

### Version Tracking

Location: `~/dotfiles/scripts/versions.sh`

Add to `TRACKED_TOOLS` array:

```bash
readonly TRACKED_TOOLS=(
    # ...existing...
    "toolname|version_cmd|type"  # type: cmd|git|uv
)
```

### Tool Descriptions (optional)

Location: `~/dotfiles/bin/tools.py`

Add entry for `update --info <tool>` command:

```python
("toolname", "What it does concisely", "toolname --demo → shows practical example"),
```

---

## CLI Commands

```bash
update                    # Full installation (idempotent)
update -v                 # Verbose output
update --dry-run          # Preview changes

update bat                # Update specific tool (auto-detects package manager)
update --only brew        # Run only Homebrew installation
update --list             # List available functions

update --info <tool>      # Show tool info
update --outdated         # Check for available updates
update --versions         # Show all installed versions
update --versions brew    # Filter by group (brew|cask|uv|cargo|git|other)
```

---

## Architecture

```
dotfiles/
├── Brewfile              # Primary tool manifest (Homebrew)
├── install.sh            # Main installation script, setup functions
├── scripts/
│   ├── logging.sh        # Logging, spinner, execute helpers
│   ├── ui.sh             # Table drawing, formatting
│   └── versions.sh       # Version detection, TRACKED_TOOLS
├── bin/
│   └── tools.py          # Tool catalog for --info command
└── run.sh                # Bootstrap script for initial clone
```

### Installation Pipeline

```
📋 Checking prerequisites
📁 Creating directories
🔨 Installing Xcode CLI
🍺 Installing Homebrew packages    ← Brewfile
📦 Installing Node.js tools        ← n, bun
🐍 Creating Python virtual environments
💻 Installing tmux plugins         ← tpm (git)
🎨 Installing Yazi themes          ← yazi-flavors (git)
🔧 Installing CLI utilities        ← uv tools, cargo
🔗 Linking dotfiles                ← GNU Stow
🧹 Cleaning up
```

### Available Functions

| Flag | Function | Description |
|------|----------|-------------|
| `dirs` | create_dirs | Create ~/Codes and ~/Documents/Screenshots |
| `xcode` | install_xcode_tools | Install Xcode Command Line Tools |
| `brew` | install_brew | Install Homebrew and Brewfile packages |
| `node` | configure_node | Install n (Node version manager) and Bun |
| `venv` | create_virtualenvs | Create Python venvs (neovim, debugpy) |
| `tmux` | install_tmux_plugins | Install tmux plugin manager (tpm) |
| `yazi` | install_yazi_themes | Install Yazi file manager themes |
| `utils` | setup_utils | Install UV tools, LLM, gh-dash, etc. |
| `stow` | stow_dotfiles | Symlink dotfiles with GNU Stow |
| `cleanup` | cleanup | Run Homebrew cleanup and autoremove |

---

## Dotfile Configuration (GNU Stow)

Each directory in the repo is a "stow package" that gets symlinked to `$HOME`:

```bash
stow -d ~/dotfiles -t ~ zsh nvim tmux ghostty ...
```

To add configuration for a new tool:

1. Create directory: `mkdir -p ~/dotfiles/toolname/.config/toolname`
2. Add config files inside
3. Add to stow command in `stow_dotfiles()` function

---

## Sensitive Data

**This repo is public.** Never commit secrets, credentials, or personal identifiers.

### Git Identity

User name, email, and signing key live in `~/.gitconfig.local` (untracked).
The tracked `git/.gitconfig` includes it via:

```ini
[include]
  path = ~/.gitconfig.local
```

On a fresh machine, create `~/.gitconfig.local`:

```ini
[user]
	name = Your Name
	email = your@email.com
	signingkey = ~/.ssh/id_ed25519_signing.pub
```

Without this file, git will prompt for identity on first commit. Everything else (aliases, diff tools, signing config) lives in the tracked `.gitconfig`.

### Secrets in Shell

The `setenv` function in `zsh/.aliases` uses 1Password CLI (`op read`) to resolve secrets at runtime. Never hardcode API keys or tokens in tracked files.

### What NOT to commit

- `.env` files (already in `.gitignore`)
- API keys, tokens, passwords
- Snowflake/cloud account identifiers
- Private SSH/GPG keys
- Connection strings with credentials

---

## Known Issues (non-critical)

These are documented quirks that don't break anything but could be cleaned up:

| Issue | File | Notes |
|-------|------|-------|
| Starship config in `~/.config/starship/starship.toml` | `starship/.config/starship/` | Starship defaults to `~/.config/starship.toml`. Works if `STARSHIP_CONFIG` is set. |
| `python@3.14` not explicit in Brewfile | `Brewfile` | Installed as a dependency. Add `brew "python@3.14"` to be explicit. |
| `GOROOT=/usr/local/go` wrong for Apple Silicon | `zsh/.exports:114` | Should be `/opt/homebrew/opt/go/libexec` |
| `FZF_DEFAULT_OPTS` set twice (overwritten) | `zsh/.exports:53,158` | Catppuccin theme on line 158 wins |
| `FZF_DEFAULT_COMMAND` set twice (overwritten) | `zsh/.exports:42,57` | `fd` version on line 57 wins |
| `%HOME` typo in `.zshrc` bun completions | `zsh/.zshrc:38` | Should be `$HOME`. Dead code (also in `.exports:145`). |
| `.zprofile` brew line appended on every run | `install.sh:301` | Should check if already present |
| `.zshenv.sh` / `.zlogin.sh` never sourced | `zsh/` | Zsh reads `~/.zshenv` not `~/.zshenv.sh`. These files are dead. |
| Duplicate `compinit` calls | `zsh/.zshrc:18,70` | Second call is redundant (~100ms overhead) |
| `n` alias shadows node version manager | `zsh/.aliases:26` | `alias n="nvim"` prevents using `n` for Node |

---

## Key Files by Purpose

| Purpose | File(s) |
|---------|---------|
| Add Homebrew tool | `Brewfile` |
| Add non-brew tool | `install.sh` (setup_utils or appropriate function) |
| Track tool version | `scripts/versions.sh` (TRACKED_TOOLS) |
| Tool descriptions | `bin/tools.py` |
| Shell aliases | `zsh/.aliases` |
| Environment vars | `zsh/.exports` |
| Neovim config | `nvim/.config/nvim/` |

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

dotfiles

Directory Structure

SKILL.md

Report

Notice