Ignore Rules (.chkptignore)
Relevant source files
The following files were used as context for generating this wiki page:
Ignore rules in chkpt define which files and directories are excluded from workspace snapshots during the scanning process. This system ensures that large, redundant, or sensitive data—such as build artifacts and version control internals—do not bloat the content-addressable store. The system utilizes a combination of hardcoded "Always Excluded" paths, default dependency directories, and user-defined patterns via .chkptignore files.
The implementation mirrors the syntax and behavior of .gitignore, allowing developers to use standard glob patterns to manage their snapshots efficiently.
Core Architecture and Components
The ignore system is integrated into the workspace scanner. It operates by checking every path encountered during a directory walk against a set of exclusion criteria.
Logic Flow of Path Validation
When the scanner walks the filesystem, it uses an IgnoreMatcher to decide whether to process a file or descend into a directory. The validation follows a strict hierarchy:
- Hardcoded Exclusions: Internal paths required by
chkptorgit. - Dependency Exclusions: Common package manager directories (can be overridden).
- User Patterns: Custom rules defined in a
.chkptignorefile.
The following diagram illustrates the decision logic within the IgnoreMatcher:
The IgnoreMatcher Structure
The IgnoreMatcher is the primary data structure responsible for exclusion logic. It wraps a Gitignore builder from the ignore crate to handle complex glob matching.
| Component | Description |
|---|---|
ALWAYS_EXCLUDED | Constant list containing .git, .chkpt, and target. These are never overridable. |
DEPENDENCY_DIRS | List of common dependency folders like node_modules and .venv. Excluded by default. |
include_deps | A boolean flag that, when true, allows the scanner to process directories in DEPENDENCY_DIRS. |
gitignore | An optional compiled matcher containing patterns loaded from the .chkptignore file. |
Sources: crates/chkpt-core/src/scanner/matcher.rs:5-24, README.md:120-125
Excluded Directories
Built-in Exclusions
chkpt defines specific directories that are always skipped to prevent recursive storage of the checkpoint store itself or large build artifacts that are easily reproducible.
- Internal:
.chkpt/(the store itself). - Git:
.git/(internal version control state). - Rust:
target/(build output).
Sources: crates/chkpt-core/src/scanner/matcher.rs:6, crates/chkpt-core/tests/scanner_test.rs:40-60
Dependency Management
Directories containing external dependencies are excluded by default to save space. However, users can opt-in to saving these via the --include-deps flag in the CLI.
The hardcoded dependency list includes:
- Node.js:
node_modules - Python:
.venv,venv,__pypackages__,.tox,.nox - Java/JVM:
.gradle,.m2
Sources: crates/chkpt-core/src/scanner/matcher.rs:9-20, crates/chkpt-cli/src/main.rs:26-30
User-Defined Rules (.chkptignore)
Users can create a .chkptignore file in the root of their workspace. This file uses the same syntax as .gitignore.
Pattern Loading
The IgnoreMatcher attempts to load the .chkptignore file during initialization. If the file is missing or contains invalid syntax, the system logs a warning but continues using only the built-in exclusions.
// Initialization of the matcher with pattern loading
pub fn new(chkptignore_path: Option<&Path>, include_deps: bool) -> Self {
let gitignore = chkptignore_path.and_then(|path| {
if path.exists() {
let mut builder = GitignoreBuilder::new(path.parent().unwrap_or(Path::new(".")));
if let Some(err) = builder.add(path) {
tracing::warn!("Error parsing .chkptignore: {}", err);
return None;
}
builder.build().ok()
} else {
None
}
});
// ...
}
Sources: crates/chkpt-core/src/scanner/matcher.rs:32-54
Matching Behavior
Matching is performed against the relative path from the workspace root. The matcher is capable of:
- Recursive matching: Patterns like
build/ignore the entire directory tree. - Extension matching: Patterns like
*.logignore all files with that extension. - Parent matching: If a parent directory is ignored, all children are automatically ignored without individual evaluation.
Sources: crates/chkpt-core/src/scanner/matcher.rs:65-72, crates/chkpt-core/tests/scanner_test.rs:20-30
CLI Usage and Overrides
The behavior of ignore rules can be influenced by command-line arguments during a save operation.
| Command Option | Effect |
|---|---|
chkpt save | Uses standard ignore rules (Built-in + Dependency + .chkptignore). |
chkpt save --include-deps | Bypasses the DEPENDENCY_DIRS list, including folders like node_modules in the snapshot. |
Sources: crates/chkpt-cli/src/main.rs:26-34, crates/chkpt-cli/skills/chkpt/references/cli-commands.md:12-18
Implementation in Scanning
The walk and walk_parallel functions in the core library utilize the IgnoreMatcher inside a filter closure. This ensures that the walker never even allocates metadata or reads files that match an ignore pattern.
Summary
The .chkptignore system provides a robust mechanism for controlling snapshot scope. By combining hardcoded safety exclusions for internal tool data, sensible defaults for heavy dependency folders, and flexible user-defined glob patterns, chkpt balances comprehensive workspace capture with storage efficiency. The system's deterministic behavior is verified through extensive tests covering nested dependencies, symlinks, and custom ignore patterns.