A comprehensive command-line interface demonstrating all features of the Titor checkpointing library. This CLI provides Git-like version control for any directory with powerful time-travel capabilities.
- Checkpoint Management: Create, list, and restore directory snapshots
- Timeline Navigation: Visualize and navigate through checkpoint history
- Branching: Fork from any checkpoint to create alternative timelines
- Diffing: Compare changes between checkpoints
- Verification: Ensure data integrity with cryptographic verification
- Storage Optimization: Garbage collection and compression
- Progress Tracking: Visual feedback for long operations
Build the CLI from the project root:
# Build in release mode for optimal performance
cargo build --example titor_cli --release
# Copy to your PATH (optional)
cp target/release/examples/titor_cli ~/.local/bin/titor
# Or run directly
cargo run --example titor_cli -- --help# Initialize Titor in current directory
titor init
# Create your first checkpoint
titor checkpoint -m "Initial project state"
# Make some changes to your files...
echo "new content" > file.txt
# Create another checkpoint
titor checkpoint -m "Added new file"
# View your timeline
titor timeline
# Compare checkpoints
titor diff <checkpoint1> <checkpoint2>
# Restore to previous state
titor restore <checkpoint-id>-p, --path <PATH>: Target directory (defaults to current)-s, --storage <PATH>: Storage directory (defaults to .titor)-v, --verbose: Enable debug output--help: Show help information--version: Show version information
Initialize Titor tracking in a directory.
titor init [OPTIONS]
Options:
--compression <MODE> Compression strategy [none, fast, adaptive] (default: adaptive)
-i, --ignore <PATTERN> File patterns to ignore (gitignore syntax)
--force Force initialization even if already initializedExamples:
# Basic initialization
titor init
# Custom compression and ignore patterns
titor init --compression fast -i "*.log" -i "node_modules/"
# Initialize with custom storage location
titor -s /backup/project-titor initCapture the current state of your directory.
titor checkpoint [OPTIONS]
Options:
-m, --message <MESSAGE> Description for the checkpoint
--progress Show progress barExamples:
# Quick checkpoint
titor cp
# With description
titor checkpoint -m "Before major refactoring"
# With progress tracking
titor checkpoint --progress -m "Release v1.0.0"Restore directory to a previous checkpoint state.
titor restore <CHECKPOINT> [OPTIONS]
Options:
--progress Show progress barExamples:
# Restore by checkpoint ID (first 8 chars sufficient)
titor restore abc12345
# Restore with progress
titor restore abc12345 --progressDisplay all checkpoints with metadata.
titor list [OPTIONS]
Options:
-d, --detailed Show detailed information
-l, --limit <NUM> Limit number of resultsExamples:
# Basic list
titor ls
# Detailed view with file counts
titor list --detailed
# Show only last 10 checkpoints
titor list --limit 10Visualize checkpoint history as a tree structure.
titor timeline [OPTIONS]
Options:
--ascii Use ASCII characters for tree drawingExamples:
# Beautiful Unicode tree
titor timeline
# ASCII tree for compatibility
titor timeline --asciiFork from an existing checkpoint to create a new timeline branch.
titor fork <CHECKPOINT> [OPTIONS]
Options:
-m, --message <MESSAGE> Description for the forkExamples:
# Fork from checkpoint
titor fork abc12345 -m "Experimental feature branch"
# Fork from current checkpoint
titor fork HEAD -m "Alternative approach"Show differences between two checkpoints.
titor diff <FROM> <TO> [OPTIONS]
Options:
-l, --lines Show line-level differences (like git diff)
--context <NUM> Number of context lines (default: 3)
--stat Show only statistics
--ignore-whitespace Ignore whitespace changesExamples:
# Basic file-level comparison
titor diff abc12345 def67890
# Line-level diff with git-like output
titor diff abc12345 def67890 --lines
# Custom context lines
titor diff abc12345 def67890 --lines --context 5
# Statistics only
titor diff abc12345 def67890 --stat
# Ignore whitespace changes
titor diff abc12345 def67890 --lines --ignore-whitespaceOutput Format:
With --lines, the output shows unified diff format:
--- a/file.txt
+++ b/file.txt
@@ -1,5 +1,6 @@
context line
-removed line
+added line
another context linePerform cryptographic verification of checkpoint data.
titor verify [CHECKPOINT] [OPTIONS]
Options:
--all Verify all checkpointsExamples:
# Verify current checkpoint
titor verify
# Verify specific checkpoint
titor verify abc12345
# Verify entire timeline
titor verify --allRemove unreferenced objects to free storage space.
titor gc [OPTIONS]
Options:
--dry-run Show what would be deleted without removingExamples:
# Preview cleanup
titor gc --dry-run
# Perform cleanup
titor gcDisplay current repository status and statistics.
titor statusShow detailed information about a specific checkpoint.
titor info <CHECKPOINT>Examples:
# Get checkpoint details
titor info abc12345For directories with many files, use progress tracking:
# Show progress for checkpoint creation
titor checkpoint --progress -m "Large directory snapshot"
# Show progress for restoration
titor restore abc12345 --progressCreate experimental branches without affecting main timeline:
# Create a fork for experimentation
titor fork abc12345 -m "Try new approach"
# Make changes and checkpoint
echo "experimental" > test.txt
titor cp -m "Experimental change"
# If happy, continue on this branch
# If not, restore to original branch
titor restore abc12345The CLI is designed for scripting:
#!/bin/bash
# Auto-checkpoint script
# Create checkpoint with timestamp
titor checkpoint -m "Auto-checkpoint $(date +%Y-%m-%d_%H:%M:%S)"
# Verify integrity
if titor verify; then
echo "Checkpoint verified successfully"
else
echo "Checkpoint verification failed!"
exit 1
fi
# Clean up old objects
titor gc# Example GitHub Actions workflow
name: Checkpoint on Release
on:
release:
types: [created]
jobs:
checkpoint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Titor
run: cargo install --example titor_cli
- name: Create release checkpoint
run: |
titor init
titor checkpoint -m "Release ${{ github.event.release.tag_name }}"
- name: Verify checkpoint
run: titor verify-
Compression Strategy:
- Use
adaptivefor mixed content (default) - Use
fastfor speed priority - Use
nonefor already-compressed files
- Use
-
Ignore Patterns:
- Exclude build artifacts:
-i "target/" -i "dist/" - Exclude dependencies:
-i "node_modules/" -i "vendor/" - Exclude logs:
-i "*.log" -i "*.tmp"
- Exclude build artifacts:
-
Storage Location:
- Use SSD for storage directory when possible
- Consider separate disk for large repositories
- Network storage works but may be slower
"Not a Titor repository"
- Run
titor initfirst - Check you're in the correct directory
- Verify storage directory exists
"Checkpoint not found"
- Use
titor listto see available checkpoints - Check checkpoint ID spelling
- First 8 characters are usually sufficient
"Permission denied"
- Ensure write access to storage directory
- Check file permissions in target directory
- Run with appropriate user privileges
Enable verbose output for troubleshooting:
titor -v <command>Check storage health:
# Show storage statistics
titor status
# Verify all checkpoints
titor verify --all
# Check for orphaned objects
titor gc --dry-runThe CLI demonstrates all major Titor features:
- Content-Addressable Storage: Files stored by content hash
- Merkle Trees: Cryptographic verification of file integrity
- Incremental Snapshots: Only changed files stored
- Compression: LZ4 compression for efficiency
- Deduplication: Identical files stored once
- Atomic Operations: All-or-nothing checkpoint/restore
- Line-Level Diffs: Git-like unified diff output for text files
This CLI serves as a reference implementation. To extend:
- Add new commands in the
Commandsenum - Implement command handler functions
- Update help documentation
- Add tests for new functionality
Same as the Titor library - MIT