How hidehic0/custom-completion-zsh works
Project type and purpose
• This is a small, single-binary CLI tool (“custom-completion-zsh”) written in Go.
• Purpose: read a user’s TOML configuration, generate Zsh completion scripts, and write them into the user’s Zsh fpath so that custom completions are available.
File structure
• Top-level files:
• main.go – entry point, sets up the CLI with cobra
• defaultconfig.toml – a template for a user’s config
• aqua.yaml, .goreleaser.yaml – delivery/publishing configs
• go.mod/go.sum – Go module/dependency config
• No subdirectories—everything lives in main.go and imported packages.
README insights
• Config file lives at $XDG_CONFIG_HOME/custom-completion-zsh/config.toml
• Output completes go to $XDG_DATA_HOME/zsh/custom-completion-zsh for Zsh to consume.
• Two user-facing commands:
• completion zsh – prints the completion script
• build – writes completion files to the data directory
Main components & interactions
a. Components
1. User shell (Zsh)
2. File system (XDG_CONFIG_HOME, XDG_DATA_HOME)
3. CLI binary (custom-completion-zsh)
4. Cobra command layer (build, completion zsh)
5. TOML parser (reads user config)
6. Completion-script generator (uses cobra’s built-in capabilities)
7. Output writer (writes files to the data directory)
8. Build & release pipeline (Go toolchain, goreleaser, aqua)
b. Relationships / Data Flow
• User invokes custom-completion-zsh <command>.
• Cobra parses the command, dispatches to the appropriate handler.
• Handler reads config.toml from $XDG_CONFIG_HOME.
• BurntSushi/toml parses config into Go structs.
• Based on config, the generator produces a Zsh completion script.
• If build, the script is written into $XDG_DATA_HOME/zsh/custom-completion-zsh/.
• User adds that directory to Zsh’s fpath and reloads the shell.
• For developers: Go modules resolve dependencies; goreleaser and aqua.yaml define packaging & distribution.
Architectural patterns & design principles
• Command pattern (cobra commands)
• Separation of concerns: CLI parsing, config parsing, script generation, file I/O
• Single responsibility modules (each library handles a specific task)
• Declarative configuration (TOML)
• Standard XDG directory conventions for config & data