How voronenko/dotfiles works
Project Type and Purpose
• This is a “dotfiles” project: a configuration and automation framework for shell environments (zsh/bash), developer tools, and utilities.
• Purpose: clone or bootstrap into ~/dotfiles, create symlinks into $HOME, install/enable plugins and external tools, and provide documented helpers (e.g., MkDocs site under mkdocs/).
File Structure
Top-level components:
• bootstrap scripts: bootstrap.sh, bootstrap_remote.sh, init.sh, init_simple.sh
• configuration directories:
– “bin/”: scripts and binaries symlinked into ~/bin
– “completions/”: shell completion scripts for many CLIs
– “config/”: app and IDE configs (e.g., webide/, lazycli/, kubie/)
– “helpers/”: shared shell functions and plugins
– “adr/”: architectural decision records tooling
• root-level dotfiles: .zshrc, .bashrc, .gitconfig, tmux.conf, etc.
• Makefile: orchestrates “make install-console-fzf”, “make swiss-knife”, etc.
• GitHub workflows, pre-commit config, .chglog for CHANGELOG generation.
Key Insights from README
• README outlines the bootstrap flow: back up existing, symlink dotfiles, clone oh-my-zsh, install shell dependencies, set default shell.
• Describes major features: fzf integration, docker helpers, tmuxinator, direnv, AWS/Cloud tools, MkDocs documentation.
Main Components & Their Relationships
a. Installer / Bootstrapper
– Scripts: bootstrap.sh / init.sh → Creates ~/dotfiles_old, symlinks all root-level dotfiles, clones oh-my-zsh, invokes Makefile targets.
b. Dotfiles Repository
– Holds source config files (.zshrc, .gitconfig, tmux.conf, etc.) and subdirectories.
c. Symlinks in $HOME
– .zshrc → ~/dotfiles/zshrc, .vimrc → ~/dotfiles/vimrc, bin/* → ~/bin/*, config/* → ~/.config/*, completions/* → ~/.completions/*.
d. Shell Initialization
– zsh startup loads .zshrc, which sources helpers/, completions/, and env-specific files (e.g., .zshrc.local).
e. External Dependencies & Plugins
– oh-my-zsh (cloned into ~/.oh-my-zsh)
– fzf, direnv, tmuxinator, asdf, nvm, pyenv, etc. (installed via Makefile)
f. Documentation Site
g. ADR Tooling
– adr/ directory provides a CLI for managing architecture decision records.
Architectural Patterns & Principles
• Modularity: Each category of config (git, shell, tmux, IDEs, cloud tools) lives in its own folder.
• Convention-over-configuration: predictable symlink paths (dotfile name = source in repo).
• Single source of truth: everything under ~/dotfiles.
• Extensibility: Makefile targets install additional tools on demand.