Welcome to my $HOME. This repository contains my personal configuration files for Linux and macOS, and a crazy powerful simple methodology to manage them, making setup on new machines, and keeping them in sync on existing ones, very easy.

• The only requirement is Git, and if you're here, then that's obviously covered! ;-)

This repository contains my approach and use of dotfiles, and is organized into two topics:

1. A Methodology:

   • A bare Git repository approach for managing dotfiles—no symlinks, no extra tooling, just Git. This methodology is universal and works with anyone's configuration files.

2. My Implementation:

   • My personal configuration files managed using this methodology (cross-platform bash/zsh, vim, tmux, Starship prompt, XDG compliance, and modern CLI tool integration).

I have these two approaches documented in the docs directory. They can be ready independently, but when read together gives the full picture of my approach. So, if you want the full picture, read METHODOLOGY first. Here's what each doc contains:

📖 METHODOLOGY.md - Learn the bare repository approach for managing dotfiles

• How the methodology works
• Setting up your own dotfiles from scratch
• Daily usage workflows
• Troubleshooting

🔧 IMPLEMENTATION.md - My specific dotfiles configuration

• What's included in my setup
• Installing my dotfiles (as-is or forked)
• Post-installation setup
• Architecture and platform details

Want to learn the methodology with your own dotfiles?

• → Read METHODOLOGY.md
• Jump to Setup from Scratch
  • Best for starting from zero with your existing configs

Want to use my dotfiles as-is?

• → Read IMPLEMENTATION.md
• • Jump to Install As-Is
  • This is where I go anytime I setup a new machine

Want to fork and customize my dotfiles?

• → Read IMPLEMENTATION.md
• • Jump to Fork and Customize
  • Start with my setup, make it yours

⚠️ Critical: Always review files before adding them to your dotfiles repository. Never commit:

• Passwords, API keys, tokens
• Private keys (SSH, GPG)
• Personal information (PII)
• Work credentials
• Browser data

Best Practices:

1. Always review files before dotfiles add
2. Use ~/.gitignore to block sensitive files (see example in this repo)
3. Use environment variables for secrets, not tracked files
4. Consider using git-secrets or pre-commit hooks

For complete security guidelines, including .gitignore setup and removing accidentally committed secrets, see METHODOLOGY.md - Security Considerations

1. Original Methodology: StreakyCobra on Hacker News — The elegant bare repository approach that inspired this setup.

"No extra tooling, no symlinks, files are tracked on a version control system, you can use different branches for different computers, you can replicate your configuration easily on new installation." — StreakyCobra on HN

2. Atlassian Tutorial: The best way to store your dotfiles — Comprehensive guide to this methodology.

If you run into issues not covered in the documentation, feel free to open an issue on GitHub. When reporting problems, please include:

• Your OS and version
• Your shell (bash/zsh) and version
• The specific error message
• What you were trying to do