We’ve all been there. You get a new machine, or your OS crashes, and you spend the next three days trying to remember that specific .zshrc alias or that one Neovim LSP setting that made everything work.

I decided to end the "Mystery State" of my machine. I built a dotfile management system that turns "Setup" into a single command.

My Philosophy: One Repo to Rule Them All

I wanted a setup that followed three rules:

1. No Manual Copying: Everything is symlinked. If I change a config, it’s already in the git repo.
2. Idempotent: Running the install script twice shouldn’t break anything.
3. Health Checks: A script that tells me if a symlink is broken or if I’m missing a dependency like ripgrep or fzf.

The Architecture

My repository

Zayan-Mohamed / dot_files

Personal Linux dotfiles managed in a single repo with symlinks for a fully reproducible setup. Includes terminal configs, Zsh + Powerlevel10k, Neovim (80+ plugins), helper scripts, health checks, and detailed documentation.

dot_files

A fully reproducible Linux development environment built around symlinks.

This repository manages everything in ~/.config and essential dotfiles in ~, all tracked in one place and safely symlinked back to the system. The goal is simple: clone the repo, run one script, and get your exact setup every time.

No manual copying. No drift. No mystery state.

---

What this repo gives you

• A clean, versioned ~/.config
• Predictable dotfiles in ~
• Idempotent install and update scripts
• Health checks to catch broken symlinks
• A heavily tuned Neovim setup with documentation
• A Zsh environment that feels fast, safe, and modern

Structure

dot_files/
│
├── config/                 # mirrors ~/.config
│   ├── alacritty/
│   ├── kitty/
│   ├── wezterm/
│   ├── ghostty/
│   ├── nvim/
│   └── ...                     # other app configs
│
├── home/                       # dotfiles in ~ (not ~/.config)
│   ├── .bashrc
│   ├── .zshrc
│   ├── .p10k.zsh
│   ├── .gitconfig

…

uses a clean separation of concerns:

• /config: Mirrors ~/.config (Alacritty, Kitty, Neovim).
• /home: Essential dotfiles that live in the root (like .zshrc or .gitconfig).
• /scripts: The engine room. Includes health_check.sh and update.sh.

Key Features

1. The "Health Check" Script

Most dotfile repos just link files and walk away. I added a health_check.sh that verifies every symlink and checks if my favorite CLI tools (bat, eza, fd) are actually installed. No more "Command not found" surprises.

2. A 6-Week Neovim Mastery Path

My Neovim setup has 80+ plugins, which can be overwhelming. To solve this, I wrote a full NVIM_STUDY_GUIDE.md inside the repo. It’s not just a config; it’s a curriculum for learning LSP, Telescope, and Git integration.

3. Modern Tooling

The shell environment is built for speed:

• Zsh + Powerlevel10k for the UI.
• FZF-lua for lightning-fast searches.
• Ghostty/Alacritty/Kitty support built-in.

How to use it

If you want to try it out or fork it for your own needs:

git clone git@github.com:Zayan-Mohamed/dot_files.git ~/dot_files
cd ~/dot_files
./scripts/install.sh

Conclusion

Managing your system as code isn’t just for DevOps—it’s for anyone who values their time. By version-controlling your ~/.config, you treat your development environment with the same respect as your production code.

Check out the full repository here: Zayan-Mohamed/dot_files

I’d love to hear from you: Do you use a manager like GNU Stow or Chezmoi, or do you prefer custom bash scripts like I do? Let’s discuss in the comments!