# dotfiles

This repository contains my personal dotfiles, managed using [GNU Stow](https://www.gnu.org/software/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:
```bash
./scripts/install_dependencies.sh
```

Alternatively, you can manually install the required tool:

- [GNU Stow](https://www.gnu.org/software/stow/)

To install Stow on macOS, use [Homebrew](https://brew.sh/):
```bash
brew install stow
```

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

**Ubuntu / Debian**
```bash
sudo apt install stow
```

**Arch Linux**
```bash
sudo pacman -S stow
```

## Installation

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

```bash
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:

```bash
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:

```text
.
├── 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.