How spacecabbage/dotfiles works
Project Type and Purpose
• This is a “dotfiles” repository: an open-source toolkit for managing personal shell and editor configurations.
• It contains Neovim configs (in Lua), shell and terminal configs (.bashrc, tmux, starship, ghostty), plus a snapshot/backup folder.
File Structure Overview
• Top-level directories:
• .snapshots/ – backups of previous configs.
• nvim/ & nvim.bak/ – active and backup Neovim setups.
• terminal/ – shell and terminal multiplexer configs.
• Key files:
• nvim/init.lua – entry point for Neovim config.
• nvim/lua/*.lua – individual modules (statusline, LSP, plugins, etc.).
• terminal/.bashrc, .tmux.conf, starship.toml – environment and prompt settings.
• Build & deploy: no compiled artifacts; “deployment” is via ln -s symlinks from your $HOME to these files.
README Insights
• Installation is simply cloning and symlinking.
• Lists external dependencies: bat, exa, fzf, ripgrep, starship, tmux, Neovim, etc.
a. Main Components
• Dotfiles Repo (Git)
• Symlink Manager / Installer Script (manual ln -s steps)
• Shell Environment Loader (reads .bashrc)
• Terminal Multiplexer (tmux, reads .tmux.conf)
• Prompt Engine (starship, reads starship.toml)
• Neovim Core (init.lua + Lua modules)
• Plugin Manager (lazy.nvim + Mason + lspconfig, etc.)
• External CLI tools (bat, fzf, exa, ripgrep, zellij, zoxide)
b. Relationships & Data Flow
1. User clones repo → creates symlinks → config files appear in $HOME.
2. On shell startup → .bashrc is sourced → loads aliases, functions, calls starship.
3. Starting tmux → reads .tmux.conf.
4. Launching Neovim → init.lua loads core modules → invokes plugin manager → plugins lazy-load as needed → LSPs launched via Mason.
5. Plugins and modules call out to external tools (fzf, ripgrep, etc.).
c. Architectural Patterns & Principles
• Modular config: each area (keymaps, options, plugins) is its own Lua module.
• Lazy-loading: plugins are only loaded when invoked.
• Separation of concerns: shell, editor, terminal each in their own subdirectory.
• Versioned backups: .snapshots/ and nvim.bak/ provide rollback.
d. Key Technologies & Libraries
• Lua (Neovim API)
• lazy.nvim (plugin manager)
• Mason & lspconfig (LSP installer/config)
• Bash (shell scripting)
• tmux, starship, ghostty (terminal/UX)
• CLI tools (bat, exa, fzf, ripgrep)