45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## What is notfiles?
|
||
|
|
|
||
|
|
A modern dotfiles manager written in Rust — a pure Rust alternative to GNU Stow. It symlinks (or copies) files from organized "package" directories into a target location (typically `~`).
|
||
|
|
|
||
|
|
## Build & Test Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo build # build
|
||
|
|
cargo test # run all tests (unit + integration)
|
||
|
|
cargo test --lib # unit tests only
|
||
|
|
cargo test --test integration # integration tests only
|
||
|
|
cargo test <test_name> # run a single test by name
|
||
|
|
cargo clippy # lint
|
||
|
|
cargo fmt --check # check formatting
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The binary has four subcommands: `init`, `link`, `unlink`, `status`. CLI parsing uses clap derive in `src/cli.rs`; command dispatch happens in `src/main.rs`.
|
||
|
|
|
||
|
|
**Core flow for `link`:** `main` → `resolve_packages` (discover subdirs or validate requested names) → `collect_files` (recursive walk with ignore filtering) → `linker::link_package` (create symlinks or copies, record in state).
|
||
|
|
|
||
|
|
Key modules:
|
||
|
|
- **linker** — Creates/removes symlinks or copies. Manages `State` (serialized to `.notfiles-state.toml` in the dotfiles dir) which tracks every linked file with source, target, method, and timestamp. Handles conflict detection, `--force` backups, and empty-parent cleanup on unlink.
|
||
|
|
- **config** — Parses `notfiles.toml`. Provides per-package overrides for method (symlink/copy), target directory, and ignore patterns. Falls back to `[defaults]` section values.
|
||
|
|
- **package** — Discovers packages (non-hidden subdirectories of the dotfiles dir) and recursively collects files, filtering through `IgnoreMatcher`.
|
||
|
|
- **ignore** — Glob-based ignore matching using `globset`. Matches both full relative paths and individual path components.
|
||
|
|
- **paths** — `expand_tilde` utility.
|
||
|
|
- **status** — Compares expected state (files on disk + config) against actual state (symlinks/copies + state file) to report linked/copied/missing/conflict/orphan.
|
||
|
|
- **error** — `NotfilesError` enum via `thiserror`.
|
||
|
|
|
||
|
|
Integration tests (`tests/integration.rs`) run the compiled binary against temp directories using `tempfile`.
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
The config file is `notfiles.toml` at the dotfiles directory root. Each subdirectory of the dotfiles dir is a "package". Per-package config can override the link method (`symlink` or `copy`), target directory, and additional ignore patterns.
|
||
|
|
|
||
|
|
## Edition
|
||
|
|
|
||
|
|
Uses Rust edition 2024.
|