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

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.

2.5 KiB Raw Blame History