PathTrack

PathTrack is a lightweight file tracking and snapshot tool that allows you to create snapshots of your files and restore them to a previous state when needed. Think of it as a simplified version control system for any directory.

Features

• 📸 Create Snapshots: Capture the current state of all files in a directory
• ⏮️ Restore States: Revert your directory and its files to any previous snapshot
• 📜 History Log: View all your snapshots with timestamps
• 💾 Efficient Storage: Uses SHA-based deduplication to save space
• 🚀 Fast: Caching system for quick operations

Installation

PathTrack needs Vibescript, a custom Lua runtime, to be run.

Head over to VibeScript releases page and download the latest version.

Build from source

To build from source you need Darwin Build Tool and VibeScript to run it.

To build it, run:

darwin run_blueprint --target all

To run it:

vibescript release/pathtrack.lua <command>

Usage

PathTrack provides several commands to manage your file snapshots:

Basic Syntax

pathtrack <command> [arguments] [flags]

Available Commands

1. commit

Create a snapshot of the current state of your files.

Commit messages must be unique.

Syntax:

pathtrack commit <commit_msg> --dir <directory> [--database <database_path>] [--cache_dir <cache_path>]

Parameters:

• <commit_msg> (required): A descriptive message for this snapshot
• --dir <directory> (required): The directory to track
• --database <database_path> (optional): Where snapshots will be stored. Default: .pathtrackdb
• --cache_dir <cache_path> (optional): Cache directory for performance. Default: ~/.pathtrackcache

Example:

pathtrack commit "Initial backup" --dir ./myproject
pathtrack commit "Before refactoring" --dir ./myproject --database ./backups

---

2. rebase

Restore your files to a previous snapshot.

Syntax:

pathtrack rebase <commit_msg> --dir <directory> [--database <database_path>] [--cache_dir <cache_path>]

Parameters:

• <commit_msg> (required): The commit message of the snapshot you want to restore
• --dir <directory> (required): The directory to restore files to
• --database <database_path> (optional): Where snapshots are stored. Default: .pathtrackdb
• --cache_dir <cache_path> (optional): Cache directory. Default: ~/.pathtrackcache

Example:

pathtrack rebase "Before refactoring" --dir ./myproject --database ./backups

Warning:

• This command will delete all current files in the target directory (except database and cache)
• Files will be replaced with the snapshot version

---

3. log

Show the history of your snapshots with timestamps and file counts.

Syntax:

pathtrack log [--database <database_path>] [--sort <asc|desc>]

Parameters:

• --database <database_path> (optional): Where snapshots are stored. Default: .pathtrackdb
• --sort <asc|desc> (optional): Sort order by date. Default: desc (newest first)

Example:

pathtrack log
pathtrack log --sort asc
pathtrack log --database ./backups --sort asc

Output format:

Commit: Initial backup
Date:   2026-02-09 14:30:45
Files:  15

Commit: Before refactoring
Date:   2026-02-09 16:20:12
Files:  18

---

4. help

Display help information about available commands.

Syntax:

pathtrack help

---

Workflow Example

Here's a typical workflow using PathTrack:

# 1. Create your first snapshot
pathtrack commit "Project start" --dir ./myapp

# 2. Work on your files...
# ... make changes ...

# 3. Create another snapshot before a major change
pathtrack commit "Before database migration" --dir ./myapp

# 4. View your snapshot history
pathtrack log

# 5. If something goes wrong, restore to a previous state
pathtrack rebase "Project start" --dir ./myapp

Database Structure

PathTrack creates the following structure:

.pathtrackdb/
├── commits/
│   └── <sha_hash_of_commit_msg>  # JSON files with commit metadata
└── files/
    └── <sha_hash_of_file>        # Actual file contents

~/.pathtrackcache/
└── <cached_sha_hashes>           # Cache for faster operations

Notes

• Commit messages must be unique (they're used as identifiers via SHA hash)
• The database and cache directories are automatically excluded from tracking
• Files are deduplicated based on content (identical files share storage)
• Use descriptive commit messages to easily identify snapshots later