Fix stow

.stow-local-ignore

@@ -28,5 +28,5 @@ _darcs
 scripts      # scripts directory to be ignored
 shell        # various shell configurations need not be stowed.
 .DS_store
-README.md
-.*/\.git
+README.md
+.*/\.git

README.md

@@ -0,0 +1,94 @@
+# 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.

scripts/.stow-local-ignore

@@ -0,0 +1 @@
+.*

shell/.stow-local-ignore

@@ -0,0 +1 @@
+.*