diff options
| -rw-r--r-- | CLAUDE.md | 100 | ||||
| -rw-r--r-- | dots/home/Pictures/wallpapers/6768997.jpg | bin | 0 -> 329188 bytes | |||
| -rw-r--r-- | dots/home/Pictures/wallpapers/gentoos.jpg | bin | 0 -> 520389 bytes | |||
| -rw-r--r-- | dots/home/Pictures/wallpapers/southafrican-penguins.jpg | bin | 0 -> 642670 bytes |
4 files changed, 100 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f0e72ae --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,100 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +This is `dots`, a dotfiles manager that combines Jinja2 templating with GNU Stow for symlink management. It enables maintaining a single set of dotfiles across multiple machines by using context-driven templating. + +## Core Architecture + +### Three-Phase Process + +1. **Compile**: Templates in `dots/` (files ending in `.j2`) are rendered using Jinja2 with context from `context.json`, output to `.compiled_dotfiles/` +2. **Stow**: Compiled packages are symlinked to the target directory (default: `$HOME`) using GNU Stow +3. **Clean**: Removes symlinks and clears `.compiled_dotfiles/` + +### Directory Structure + +- `dots/`: Source dotfiles organized as Stow packages (e.g., `nvim/`, `git/`, `sway/`) +- `.compiled_dotfiles/`: Generated output after template compilation (git-ignored) +- `dots_manager/`: Python package implementing the CLI tool +- `context.json`: Configuration variables organized by platform and system + +### Context System + +`context.json` structure: +```json +{ + "_global": { /* shared across all systems */ }, + "osx": { + "_default": { /* defaults for all macOS systems */ }, + "system_name": { /* specific system config */ } + }, + "linux": { /* similar structure */ } +} +``` + +Context merging: `_global` → `platform._default` → `platform.system_name` + +Templates access context variables directly: `{{ env.EDITOR }}`, `{{ window_manager.key.sup }}` + +### Key Modules + +- `cli.py`: Entry point, orchestrates compile/stow/clean operations +- `config.py`: Loads context, detects platform/system via helper scripts in `dots/home/scripts/` +- `template.py`: Jinja2 rendering with parallel processing +- `stow.py`: Wraps GNU Stow commands for symlinking +- `utils.py`: Parallelization and dictionary merging utilities + +## Common Commands + +### Setup +```bash +python -m venv .venv +source .venv/bin/activate +pip install -e . +``` + +### Basic Usage +```bash +# Compile templates only +dots --compile + +# Compile and stow +dots --compile --stow + +# Remove symlinks and clean compiled files +dots --clean + +# Full cycle with verbose output +dots --clean --compile --stow --verbose +``` + +### Development/Testing +```bash +# Test with custom context file +dots --compile --context ./test_context.json + +# Dry-run compilation (templates rendered but not stowed) +dots --compile --output /tmp/test_dots + +# Override platform/system detection +dots --compile --platform linux --system-name test-machine +``` + +## Important Implementation Details + +- Template files must have `.j2` extension; compiled output strips this extension +- Jinja2 uses `StrictUndefined` - missing context variables will error during compilation +- File permissions are preserved from templates to compiled files +- Stow operations use `--no-folding` to prevent directory folding +- Platform detection uses `$OSTYPE`; system name uses hostname or macOS `computername` +- Template compilation is parallelized (workers = CPU count × 2) + +## When Working with Templates + +- Templates are in `dots/` as `<package>/<path>/<file>.j2` +- After compilation, they appear in `.compiled_dotfiles/<package>/<path>/<file>` (no `.j2`) +- Test context changes by running `dots --compile` and checking `.compiled_dotfiles/` +- Never edit files in `.compiled_dotfiles/` directly - they are regenerated on compile diff --git a/dots/home/Pictures/wallpapers/6768997.jpg b/dots/home/Pictures/wallpapers/6768997.jpg Binary files differnew file mode 100644 index 0000000..8c33701 --- /dev/null +++ b/dots/home/Pictures/wallpapers/6768997.jpg diff --git a/dots/home/Pictures/wallpapers/gentoos.jpg b/dots/home/Pictures/wallpapers/gentoos.jpg Binary files differnew file mode 100644 index 0000000..7b89137 --- /dev/null +++ b/dots/home/Pictures/wallpapers/gentoos.jpg diff --git a/dots/home/Pictures/wallpapers/southafrican-penguins.jpg b/dots/home/Pictures/wallpapers/southafrican-penguins.jpg Binary files differnew file mode 100644 index 0000000..e199afb --- /dev/null +++ b/dots/home/Pictures/wallpapers/southafrican-penguins.jpg |
