From 0d950e608f1c3e9d0c803f46c2ec2064798b9702 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 1 Aug 2026 16:16:30 +0000
Subject: [PATCH] docs: document branch-per-OS structure and fix clone path

README was byte-identical across all 6 branches with no explanation of
the layout. Document the branch table, note master as the canonical
source for shared dotfiles, and switch the clone command to the
correct ~/gitRepos/settingfiles path with a -b <branch> flag.
---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 872a514..724a8a7 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,45 @@
 # settingFiles
+
+Personal dotfiles and OS setup scripts. This repository separates OS/target
+environments by **branch** instead of by directory — clone the branch that
+matches your target machine, not `master` directly.
+
+## Branches
+
+| Branch | Purpose | Notes |
+|---|---|---|
+| `master` | Common base | Shared dotfiles only; starting point for new OS branches |
+| `arch` | Arch Linux (x86_64) | GNOME desktop, Steam, hibernate support |
+| `macOS` | macOS | Homebrew, Karabiner-Elements |
+| `ubuntu` | Ubuntu | |
+| `alpine` | Alpine Linux | Docker container use |
+| `raspi` | Raspberry Pi OS (Debian-based, `apt`) | Headless/CLI |
+| `raspi-arch` | Arch Linux ARM on Raspberry Pi | Headless/CLI |
+
+`.vimrc` is identical on every branch, and the bulk of `.zshrc` is shared too —
+branches only differ in a small OS-specific tail (PATH entries, keychain/GPG
+setup, plugin list, etc.). `master` holds the canonical copies of these
+shared files. When editing the shared portions, port the same change to the
+other branches by hand; there is no symlink/build step tying the branches
+together, so nothing will warn you if they drift.
+
 ## Installation
-Install zsh, tmux, neovim, git curl with your package manager.
 
-Then,
+Install `zsh`, `tmux`, `neovim`, `git`, and `curl` with your package manager
+first.
+
+Then clone the branch matching your target OS (see the table above):
+
+```
+git clone -b <branch> https://github.com/LJLee37/settingfiles.git ~/gitRepos/settingfiles
+```
+
+and run `set.sh` from inside the repo.
 
-`git clone https://github.com/LJLee37/settingfiles.git ~/gitRepos/settingfiles`
+After running `set.sh`, enter `nvim`, then run `:call coc#util#install()` if
+you hit a coc error.
 
-And run `set.sh` in the repo.
+## macOS notes
 
-After running `set.sh` file, enter `nvim` to enter neovim, then enter `:call coc#util#install()` if you encounter coc error.
+`set.sh` installs GUI apps via Homebrew (including Casks) and copies
+`karabiner.json` into place for Karabiner-Elements.