dotfiles
No description available
Ask AI about dotfiles
Powered by Claude Β· Grounded in docs
I know everything about dotfiles. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Matthew's Dotfiles
Personal dotfiles for ZSH, Git, Starship, and various development tools.
Multi-OS Support: macOS, Linux, and Windows (WSL)
π₯οΈ Systems
- Primary: M4 Mac Mini (mmm4) - macOS, external home on SSD
- Linux Desktop
- Windows Laptop (WSL)
- Various servers and Raspberry Pis
Note: The M4 Mac Mini uses an external SSD for the home directory. See docs/HOME_MIGRATION.md for details.
π Quick Start
First Time Setup
git clone https://github.com/mjbeatty89/dotfiles.git ~/dotfiles
cd ~/dotfiles
chmod +x install.sh
./install.sh
After Installation
- Restart your shell or run:
source ~/.zshrc - Ensure
~/.env.aiexists for API-driven tooling (see Secrets Management below) - Customize machine-specific settings if needed
π¦ What's Included
Shell Configuration (ZSH)
- Starship prompt with git integration
- Modern CLI tools:
eza- colorful ls replacementbat- syntax-highlighted catfzf- fuzzy finder (Ctrl+R, Ctrl+T)zoxide- smart cdripgrep- fast grepthefuck- command correction
- Autocomplete: zsh-autocomplete with smart suggestions
- History: 50K commands with deduplication
- Colors: everywhere!
Git Configuration
- Beautiful diffs with
git-delta - Helpful aliases (
gs,ga,gc,glog) - Color-coded output
Tools & Aliases
- Git shortcuts
- Python/development aliases
- Network utilities
- Archive extraction function
- Directory navigation helpers
π Secrets Management
API keys and secrets are managed via ~/.env.ai and loaded on demand with the withai helper alias.
Create your env file:
touch ~/.env.ai
chmod 600 ~/.env.ai
Add your API keys:
export GEMINI_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
# Add more as needed
Use them with:
withai gh auth status
withai openai api models.list
π― Machine-Specific Configuration
Each machine can have custom settings in zsh/machines/<hostname>.zsh
Current machines:
mmm4.zsh- M4 Mac Mini (external home on SSD)
To create a config for a new machine:
hostname -s # Find your hostname
touch ~/dotfiles/zsh/machines/<hostname>.zsh
π External Home Directory (macOS)
The M4 Mac Mini uses an external SSD (/Volumes/mm2ssd/mjb) as the home directory for more storage space.
Quick Setup
- Change home directory in System Settings β Users & Groups β Advanced Options
- Run the setup script:
cd ~/dotfiles
./scripts/setup-external-home.sh /Users/mjb /Volumes/mm2ssd/mjb
Structure
/Volumes/mm2ssd/mjb/ # $HOME
βββ dotfiles/ # This repo (git-managed)
βββ dotfiles2/ # Extended app configs (NOT git-managed)
βββ Library/ # macOS app data
βββ .zshrc -> dotfiles/... # Symlinks to this repo
For full documentation, see docs/HOME_MIGRATION.md.
π OS-Specific Features
The configuration automatically detects your OS and adjusts:
macOS:
- Homebrew package manager (
brewup,brewclean) - macOS-specific paths (LM Studio, etc.)
- 1Password CLI plugin integration
localipshows WiFi IP address
Linux:
- APT/DNF/Pacman package managers auto-detected
- Linux-specific paths (
~/.local/bin) localipshows first network interface IP- Compatible with Ubuntu, Fedora, Arch, etc.
Package Manager Aliases:
- macOS:
brewup,brewclean - Ubuntu/Debian:
aptup,aptclean - Fedora/RHEL:
dnfup - Arch:
pacup,pacclean
π Keeping Things Updated
Update Dotfiles from Repo
cd ~/dotfiles
git pull
Update Repo with Local Changes
Easy way (recommended):
dotfiles-update # Automatically commits and pushes your changes
Manual way:
cd ~/dotfiles
git add .
git commit -m "Update configs from $(hostname)"
git push
Update Installed Packages
brewup # Alias for: brew update && brew upgrade && brew cleanup
π Brewfile
The Brewfile tracks all Homebrew packages. To restore on a new machine:
cd ~/dotfiles
brew bundle install
To update the Brewfile after installing new packages:
cd ~/dotfiles
brew bundle dump --force
git add Brewfile
git commit -m "Update Brewfile"
git push
π¨ Customization
Colors & Theme
- Starship prompt: Edit
starship/starship.toml - Terminal theme: Using Dracula-inspired colors
Add New Aliases
- Common aliases: Add to main
.zshrc - Machine-specific: Add to
zsh/machines/<hostname>.zsh
Add New Functions
Add to the "Custom Functions" section in .zshrc
π οΈ Structure
dotfiles/
βββ README.md # This file
βββ install.sh # Installation script
βββ Brewfile # Homebrew packages
βββ .gitignore # Excludes secrets
βββ ansible/ # Ansible automation
β βββ inventory/hosts.yml # Machine inventory
β βββ playbooks/setup-macos.yml # macOS setup playbook
β βββ roles/macos-external-home/ # External home role
βββ docs/
β βββ HOME_MIGRATION.md # External home setup guide
βββ zsh/
β βββ .zshrc # Main ZSH config
β βββ .zprofile # Homebrew initialization
β βββ machines/ # Machine-specific configs
β βββ mmm4.zsh # M4 Mac Mini (external home)
βββ git/
β βββ .gitconfig # Git configuration
βββ starship/
β βββ starship.toml # Prompt configuration
βββ scripts/
βββ setup-external-home.sh # External home migration script
π€ Ansible Automation
Automated setup for machines using Ansible playbooks.
# Install Ansible
brew install ansible
# Run macOS setup
cd ~/dotfiles/ansible
ansible-playbook -i inventory/hosts.yml playbooks/setup-macos.yml
See ansible/README.md for full documentation.
π‘ Useful Commands
| Command | Description |
|---|---|
ll | List files with icons and details |
cat file | View file with syntax highlighting |
z project | Jump to frequently used directory |
fuck / fk | Fix last command |
Ctrl+R | Fuzzy search command history |
Ctrl+T | Fuzzy find files |
glog | Beautiful git log |
gcm "msg" | Quick git commit |
brewup | Update all Homebrew packages |
π Links
π Notes
- Secrets are never committed to this repo
- Backups of replaced files are created automatically with timestamps
- Machine configs allow customization without breaking other systems
- Symlinks mean editing local files updates the repo (don't forget to commit!)
π¨βπ» Author
Matthew Beatty
- Email: mjbeatty89@gmail.com
- GitHub: @mjbeatty89
- Role: Chemical Engineer & AI Champion @ General Motors
Last updated: April 2026
