CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

dot is a CLI dotfiles manager for Unix-like systems, written in Rust. It manages configuration files by moving them into a centralized repository and creating symbolic links at their original locations. Published to crates.io as dot_rust.

Build & Development Commands

cargo build                  # Build debug
cargo build --release        # Build release
cargo test                   # Run all tests (unit + integration)
cargo test --lib             # Run unit tests only
cargo test --test integration # Run integration tests only
cargo test <test_name>       # Run a single test by name
cargo clippy                 # Lint
cargo fmt                    # Format code

Architecture

The crate exposes both a library (src/lib.rs) and a binary (src/main.rs). The binary uses the library's public modules.

Core modules:

• cli — Clap-based CLI definition and run() entry point. Parses subcommands (init, add, remove, sync) and dispatches to the corresponding command struct.
• commands/ — Each command implements the Command trait (execute(self) -> Result<()>). Commands are self-contained structs: InitCommand, AddCommand, RemoveCommand, SyncCommand. Each exposes a static method (e.g., add_to_manifest, sync_manifest) that separates core logic from I/O for testability.
• manifest — Manifest struct wrapping a BTreeMap<PathBuf, PathBuf> serialized as TOML (dot.toml). Maps local filenames to their original paths (stored with ~ prefix). Methods come in pairs: load/load_from, save/save_to, get/get_with_home — the _with_home variants allow injecting a fake home directory for testing.
• path — Tilde expansion/collapse utilities and lexical absolute path resolution. Same _with_home pattern for testability.
• error — thiserror-based Error enum and Result type alias used throughout.

Key pattern: Functions that depend on the home directory have _with_home variants that accept Option<PathBuf> to enable deterministic testing without relying on the actual home directory.

Conventions

• Commits follow conventional commits format (feat:, fix:, refactor:, test:, chore:, etc.).
• Unit tests live alongside their modules in #[cfg(test)] mod tests. Integration tests are in tests/integration.rs and use tempfile::TempDir for isolation.
• The manifest file is always named dot.toml (constant MANIFEST_FILE).