dotfiles

This repository contains my personal dotfiles, managed using GNU Stow.

Using stow ensures that all configuration files are cleanly symlinked into your home directory, mirroring the structure of this repository.

Requirements

A script is provided to help install the core dependencies across macOS and common Linux distributions (Ubuntu/Debian, Arch, Fedora).

To run the installation script:

./scripts/install_dependencies.sh

Alternatively, you can manually install the required tool:

• GNU Stow

To install Stow on macOS, use Homebrew:

brew install stow

To install Stow on Linux, use your distribution's package manager:

Ubuntu / Debian

sudo apt install stow

Arch Linux

sudo pacman -S stow

Installation

To install all configurations at once, navigate to the root of this repository and run:

stow */

(Note: Using stow */ prevents the shell from passing pure files like README.md to Stow, ensuring only directory packages are stowed).

This will automatically create the necessary symlinks in your $HOME directory.

Removing Configurations

If you want to remove the symlinks created by Stow, use the -D flag:

stow -D */

Directory Structure & Branching Strategy

This repository uses a Folder-Per-App structure combined with a Git Branching Strategy to flawlessly handle different machines (Mac, Work, Linux) without any if/else logic.

1. Folder Structure

The root directories represent individual applications:

.
├── bash/                        # Stowed to ~ (contains .bashrc)
├── nvim/                        # Stowed to ~/.config/nvim/
├── tmux/                        # Stowed to ~ (contains .tmux.conf)
├── zsh/                         # Stowed to ~ (contains .zshrc)
└── ...

2. The Git Branch Workflow

This repository has zero conditional logic. Configurations are managed purely via branches.

• master branch: Contains the 95% common base configurations shared across all machines.
• mac, work, linux branches: Machine-specific branches derived from master.

How to manage machine-specific settings:

1. Check out your machine's branch (e.g., git checkout work).
2. Statically write your overrides (e.g., adding a Work-only plugin to nvim/).
3. Commit and push: git push origin work.

How to update shared settings:

1. Switch to the base branch: git checkout master.
2. Update the shared configuration and commit.
3. Switch back to your local branch: git checkout work.
4. Pull the updates in by rebasing: git rebase master (then git push origin work -f).

Adding New Configurations

When you want to add a new tool:

1. Create a new folder matching the application's name (e.g., mkdir alacritty).
2. Replicate the target directory structure inside it (e.g., alacritty/.config/alacritty/alacritty.toml).
3. Run stow */ from the root of this repository to link the new package.