🚀 A comprehensive dotfiles management system for macOS development environments

This repository contains my personal development environment configurations, managed through a Go-based CLI with Dotbot for symlink management. It provides a streamlined setup for a complete macOS development workflow.

• dotfiles
  • Features
  • What's Included
  • Getting started
  • Installation
  • Making changes
    • Updating your own dotfiles
    • Updating template dotfiles
    • Tracking configuration for new software
  • Updating
  • Troubleshooting
  • Contribution

• Automated Setup: Single command installation with go run .
• Idempotent: Safe to run multiple times without breaking existing configs
• Backup System: Automatically backs up existing configs to .config.bak
• Template Support: Go-based templating for dynamic configuration
• Modular Structure: Organized configuration by tool in config/ directory
• Version Control: Easy tracking and sharing of configuration changes

• Neovim: LazyVim-based configuration with extensive customization
• Fish Shell: Modern shell with custom functions and abbreviations
• WezTerm: GPU-accelerated terminal emulator
• AeroSpace: Tiling window manager for macOS
• Zellij: Terminal multiplexer with custom layouts and keybindings

• Starship: Fast, customizable shell prompt
• Homebrew: Package management via Brewfile
• Claude Code: AI coding assistant integration

• Support for multiple project paths (Backend, Frontend, Infrastructure)
• Auto-jumping with Zoxide integration
• Project-specific Zellij layouts

1. Install Homebrew (macOS package manager):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install required dependencies:

   brew install gh go jq

3. Install WezTerm terminal definitions (run in bash/zsh):

   tempfile=$(mktemp) \
     && curl -o $tempfile https://raw.githubusercontent.com/wez/wezterm/main/termwiz/data/wezterm.terminfo \
     && tic -x -o ~/.terminfo $tempfile \
     && rm $tempfile

gh auth login

Option A: Create from template (for Tutero team)

GH_USER=$(gh api user | jq -r '.login')
cd ~
gh repo create $GH_USER/dotfiles --private --template=MathGaps/dotfiles
gh repo clone $GH_USER/dotfiles dotfiles
cd dotfiles
git remote add template https://github.com/MathGaps/dotfiles.git
git fetch template
git submodule update --remote

Option B: Fork this repository

gh repo fork rlch/dotfiles --clone
cd dotfiles

Edit config.yaml and set your home directory:

baseDir: "/Users/YOUR_USERNAME"  # No trailing slash

go run .

The installation will:

• Install all Homebrew packages from Brewfile
• Create symbolic links for all configurations
• Back up existing configs to ~/.config.bak/
• Apply system preferences (key repeat rate, etc.)

Simply make changes to <repository clone dir>/config/* or equivalently the symbolic links inside <baseDir>/.config/* and push to git as normal. This will make changes to your own dotfiles repository, not the template.

Once you've made changes as above, you can:

1. Create a new branch based off template/main, inside origin with git fetch template && git checkout -b <new-branch-name> template/main
2. Make changes to this branch / cherry-pick from your other commits in origin.
3. Push your changes to template with git push template HEAD
4. Create a PR to MathGaps/dotfiles with gh pr create -B main -R MathGaps/dotfiles; and follow the process.
5. Once merged, let everyone know via Slack if necessary.

If you want to add and track changes to new software, then:

1. Add your configuration to <repository clone dir>/config/<name>.

2. Add $BASE_DIR/.config/<name>: config/<name> to install.dotfiles.yaml so that the CLI knows to symbolically link these directories.
3. Run go run . to create the symbolic link.
4. If you make a PR to the template, make sure to let everyone know. Anyone wanting these changes should also run go run .

In order to pull updates from this repository when others make improvements, we need to merge your upstream branch with the template branch. We cannot assume equivalent histories given upstream changes can be made.

git fetch template
git merge template/main --allow-unrelated-histories
# Resolve any conflicts

If you have any improvements, features, fixes, or new software that you think benefit everyone in the team,