cmc/dotfiles

 1* Overview
 2This repository uses [[https://www.gnu.org/software/stow/][GNU Stow]] to manage dotfiles. Stow creates symbolic links
 3from this directory to your home directory, keeping your configurations
 4organized and version-controlled.
 5
 6* Directory Structure
 7Each top-level directory represents a "package." For example, here's the
 8baseline at the time of writing this README:
 9
10| Program | Description                               |
11|---------+-------------------------------------------|
12| ~doom~    | Emacs configuration                       |
13| ~git~     | Git global configuration                  |
14| ~ispell~  | Dictionary and spellcheck settings        |
15| ~skhd~    | macOS hotkey daemon configuration         |
16| ~yabai~   | macOS tiling window manager configuration |
17| ~zsh~     | Shell configuration and plugins           |
18
19* Quick Start (Bootstrap)
20For a fresh installation, run the provided bootstrap script. It will check for
21Stow and link all packages automatically.
22
23#+begin_src bash
24chmod +x bootstrap.sh ./bootstrap.sh
25#+end_src
26
27* Manual Usage
28** Stow a package
29This creates the symlinks for a specific application.
30#+begin_src bash
31stow <package_name>
32#+end_src
33
34** Unstow a package
35This removes the symlinks.
36#+begin_src bash
37stow -D <package_name>
38#+end_src
39
40** Restow (Update links)
41Useful if you've added new files to a package and need to refresh the links.
42#+begin_src bash
43stow -R <package_name>
44#+end_src
45
46* Troubleshooting
47If you see a conflict error (e.g., ~* existing target is neither a link nor a
48directory~), it means a physical file already exists where Stow is trying to
49place a symlink.
50
511. *Backup* the existing file: ~mv ~/.zshrc ~/.zshrc.bak~
522. *Run* stow again: ~stow zsh~
533. *Verify*: Check the link with ~ls -l ~/.zshrc~