How nbbaier/dotfiles works
1. This repository is a personal workstation dotfiles setup, not an application runtime. Its job is to bootstrap a macOS/dev environment by installing packages, wiring configs into the right locations, and customizing shells, editors, and OS behavior.
2. The top-level entry point is install.sh, which the README says to run after cloning with submodules. That implies the repo’s main flow is: clone → install dependencies/configs → create links or apply settings → use the machine normally.
3. The repo is organized by target boundary rather than by language:
- config/ holds app and tool configs that map to XDG-style config locations.
- apps/ holds app-specific overrides and plugin/snippet content.
- system/ holds shell-wide behavior shared across terminals and CLI tools.
- packages/ defines package-manager input files.
- macos/ contains machine-level defaults and integration scripts.
- bin/ contains custom helper commands used during setup and daily use.
4. system/ is the core shell layer. It includes zsh-related initialization, aliases, completions, prompt setup, and plugin directories such as fzf-tab, autosuggestions, syntax highlighting, and autopairing. This is the main command-line UX layer that every shell session inherits.
5. config/zsh/.zshrc and config/zsh/.zprofile, plus the top-level zshenv/.zshenv, form the shell startup boundary. zshenv is likely for universal environment variables, while zshrc/zprofile handle interactive/login behavior and plugin loading.
6. config/ is the broad application configuration area. It includes configs for terminal/UI and CLI tools such as ghostty, aerospace, bat, fastfetch, gh, git, karabiner, micro, litecli, pandoc, twtxtr, and topgrade. This is where most tool behavior is defined.
7. The editor/IDE layer is split across dedicated app folders:
- apps/vscode with keybindings, settings, and snippets.
- apps/cursor with Cursor settings.
- apps/smallweb with plugin folders like choose, edit, open, and status.
- apps/tex/personal with custom LaTeX class/style files.
This suggests the repo treats editors and authoring tools as first-class, separately maintained subsystems.
8. packages/ is the dependency declaration layer. Separate files exist for different ecosystems and installers: Brew, Bun, Code, Cursor, npm, Rust, and uv. That indicates package installation is centralized but segmented by package manager rather than managed in one monolith.
9. macos/ contains OS-specific post-install customization. Files like defaults.sh, dock.sh, and duti.sh suggest this repo applies system preferences, Dock layout, and file-type associations after the base packages/configs are in place.
10. bin/ is a utilities layer for repository automation and personal workflow commands. Names like link_config, link_home, link_ides, install_extensions, is_installed, and dump_packages indicate these scripts are used to connect repo content to the home directory and manage environment setup.
11. The repo also includes support files for individual CLI tools and workflows: curl/.curlrc, jq/.jq, and configs for gh, bat, fastfetch, micro, and pandoc. These are isolated so each tool can be updated independently without affecting the rest of the environment.
12. There are documentation files comparing dotfile management approaches (dotfiles-with-chezmoi.md, dotfiles-with-stow.md), which suggests the repo itself is a hand-rolled or custom-managed dotfiles system rather than being fully delegated to those tools.
13. Important architectural boundary: this repo does not appear to run a single service or build artifact. Its “output” is a configured machine state created by linking files, installing packages, and applying OS/editor/shell settings across many small, independent targets.
14. For an architecture diagram, the central nodes should be:
- repository checkout,
- bootstrap/install scripts,
- package-manager manifests,
- shell/system config,
- app/editor configs,
- macOS customization,
- custom helper scripts.
The main data flow is from version-controlled files into the user’s home directory, system preferences, and installed package state.
Main entry points: install.sh install.sh · aliases System shell · config Tool configs · brewfile Package manifests
Components 20
Bootstrap
Entry points and repository-to-machine setup flow
- install.sh · Top-level install flow for cloning, linking, and applying settings
install.sh
Shell layer
Universal shell startup, aliases, completions, and prompt
- System shell · Shared aliases, completions, plugins, and prompt for every shell session
system/aliases - zshenv · Universal shell environment variables and startup setup
zshenv/.zshenv - zsh rc/profile · Interactive and login shell behavior and plugin loading
config/zsh/.zshrc - Shell plugins · fzf-tab, autosuggestions, syntax highlighting, completions, and autopairing
system/plugins/fzf-tab - Prompt setup · Custom prompt initialization and presentation
system/prompt/prompt_custom_setup
Tool config
Shared application and CLI configuration files
- Git config · Core git configuration and ignore rules
config/git/config - Terminal config · Ghostty terminal settings
config/ghostty/config - GH config · GitHub CLI configuration and host state
config/gh/config.yml - Tool configs · Configs for bat, fastfetch, karabiner, micro, pandoc, litecli, twtxtr, topgrade, aerospace
config/bat/config
App configs
Editor, authoring, and app-specific overrides
- VS Code · Keybindings, settings, and snippets for VS Code
apps/vscode/settings.json - Cursor · Cursor settings and editor-specific overrides
apps/cursor/settings.json - Smallweb · Smallweb plugin commands and extensions
apps/smallweb/plugins/choose - LaTeX bundle · Personal class and style files for TeX authoring
apps/tex/personal/baier.cls
Packages
Package-manager manifests for installing dependencies
- Package manifests · Brew, Bun, Code, Cursor, npm, Rust, and uv manifests
packages/brewfile
macOS
Machine-specific defaults and integrations
- macOS defaults · System preference and Dock customization scripts
macos/defaults.sh - File associations · Default app and file-type association setup
macos/duti.sh
Utilities
Helper scripts used by setup and daily workflow
- Link scripts · Repository scripts that connect files into the home/config locations
bin/link_config - Install tools · Scripts for installing extensions and checking local dependencies
bin/install_extensions - Repo utilities · Miscellaneous automation for package dumping, remotes, and symlinks
bin/dump_packages
Connections 24
- install.sh → Package manifests: installs · Reads package manifests and installs dependencies
- install.sh → Link scripts: links · Uses helper scripts to place repo files into target locations
- install.sh → Install tools: configures · Runs extension and dependency installation helpers
- install.sh → macOS defaults: applies · Runs machine-specific defaults after base setup
- install.sh → File associations: sets · Applies default application associations
- install.sh → System shell: enables · Wires shell-wide behavior into the user environment
- Link scripts → zshenv: links · Installs universal shell environment file
- Link scripts → zsh rc/profile: links · Installs login/interactive shell startup files
- System shell → Shell plugins: loads · Provides plugin directories and completions
- System shell → Prompt setup: loads · Configures the custom shell prompt
- zshenv → zsh rc/profile: feeds · Provides environment used by interactive and login shells
- System shell → Git config: uses · Shares CLI defaults that support shell workflows
- System shell → GH config: uses · Integrates GitHub CLI behavior into the shell environment
- Tool configs → Terminal config: includes · Tool-specific configuration set under config/
- Tool configs → Git config: includes · Tool-specific configuration set under config/
- Tool configs → GH config: includes · Tool-specific configuration set under config/
- Tool configs → Tool configs · Representative shared config boundary for multiple tools
- VS Code → LaTeX bundle: supports · Editor snippets and authoring assets support text/LaTeX workflows
- Cursor → VS Code: mirrors · Separate editor config with similar personal preferences
- Smallweb → Repo utilities: used by · App plugin workflow relies on local helper scripts and automation
- Package manifests → Install tools: drives · Package declarations are consumed by install helpers
- Package manifests → VS Code: installs · Includes editor-related package manifests and extensions
- Package manifests → Cursor: installs · Includes Cursor-related package manifests
- macOS defaults → File associations: pairs with · System preference changes and app associations form the OS layer