{"id":28576826,"url":"https://github.com/samuelschlesinger/revtool","last_synced_at":"2026-03-13T20:33:27.196Z","repository":{"id":160649752,"uuid":"633946460","full_name":"SamuelSchlesinger/revtool","owner":"SamuelSchlesinger","description":"A version control system implemented from scratch in Rust.","archived":false,"fork":false,"pushed_at":"2025-05-29T03:42:25.000Z","size":179,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-06-09T01:01:53.271Z","etag":null,"topics":["cli","command-line-interface","command-line-tool","content-addressable-storage","object-storage","rust","rust-lang","version-control"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamuelSchlesinger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-28T16:39:58.000Z","updated_at":"2025-06-03T20:22:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"05c8cd04-f9db-45d6-be80-0861b8acb183","html_url":"https://github.com/SamuelSchlesinger/revtool","commit_stats":null,"previous_names":["samuelschlesinger/revtool","samuelschlesinger/version-control"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelSchlesinger%2Frevtool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelSchlesinger%2Frevtool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelSchlesinger%2Frevtool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelSchlesinger%2Frevtool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamuelSchlesinger","download_url":"https://codeload.github.com/SamuelSchlesinger/revtool/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelSchlesinger%2Frevtool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259172953,"owners_count":22816556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line-interface","command-line-tool","content-addressable-storage","object-storage","rust","rust-lang","version-control"],"created_at":"2025-06-11T00:04:59.615Z","updated_at":"2026-03-13T20:33:27.151Z","avatar_url":"https://github.com/SamuelSchlesinger.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RevTool: A Modern Version Control System\n\n[![Rust](https://github.com/SamuelSchlesinger/version-control/actions/workflows/rust.yml/badge.svg)](https://github.com/SamuelSchlesinger/version-control/actions/workflows/rust.yml)\n\nRevTool is a lightweight, approachable version control system implemented from scratch in Rust. It focuses on simplicity, performance, and modern content-addressable storage principles while providing a familiar workflow for developers used to Git. \n\nThe project aims to deliver a more understandable and transparent approach to version control, making it both a practical tool and an educational resource for understanding how version control systems work.\n\n**Why RevTool?**\n- **Simplicity**: Clear conceptual model with straightforward commands\n- **Modern design**: Built using Rust and BLAKE3 cryptographic hashing\n- **Approachable code**: Well-organized architecture for learning and extending\n- **Interactive workflows**: Guided operations for complex tasks like merges\n- **Familiar feel**: Git-like concepts with more intuitive naming and behavior\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Key Differences from Git](#key-differences-from-git)\n- [Installation](#installation)\n- [Feature Highlights](#feature-highlights)\n- [Command Reference](#command-reference)\n- [Common Workflows](#common-workflows)\n- [Advanced Features](#advanced-features)\n- [Architecture](#architecture)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Quick Start\n\nGet up and running with RevTool in minutes:\n\n```bash\n# Install RevTool\ngit clone https://github.com/SamuelSchlesinger/version-control.git\ncd version-control\ncargo build --release\nexport PATH=\"$PATH:$(pwd)/target/release\"  # Add to your path\n\n# Start your project\nmkdir my-project\ncd my-project\nrevtool init\necho \"# My Project\" \u003e README.md\nrevtool status\nrevtool snap -m \"Initial commit\"\n\n# Create and use a feature branch\nrevtool branch feature\nrevtool checkout feature\n# Make changes...\nrevtool status\nrevtool snap -m \"Add new functionality\"\n\n# Merge changes back to main branch\nrevtool checkout dev\nrevtool merge feature -m \"Merge feature branch\"\n```\n\n## Key Differences from Git\n\nRevTool builds on Git's concepts while simplifying and modernizing several aspects:\n\n| Aspect | Git | RevTool | Benefit |\n|--------|-----|---------|---------|\n| **Terminology** | \"commit\" | \"snapshot\" | More intuitive naming |\n| **Hashing** | SHA-1 | BLAKE3 | Faster, more secure hashing |\n| **Default Branch** | main/master | dev | Modern naming convention |\n| **Merge Resolution** | Various tools | Built-in interactive | Guided conflict resolution |\n| **Repository** | .git | .rev | Fresh implementation |\n| **Object Model** | Complex | Simplified | Easier to understand |\n| **Implementation** | C | Rust | Memory safety, modern language |\n\nWhile Git offers more advanced features and widespread adoption, RevTool provides a cleaner, more approachable design that's ideal for:\n- Learning how version control works\n- Personal projects where simplicity is valued\n- Educational environments\n- Projects that benefit from interactive merge resolution\n\n## Installation\n\n### From Source\n\nClone the repository and build with Cargo:\n\n```bash\ngit clone https://github.com/SamuelSchlesinger/version-control.git\ncd version-control\ncargo build --release\n```\n\nThe binary will be available at `target/release/revtool`.\n\nFor convenience, you can add it to your PATH:\n\n```bash\n# Temporary (current session only)\nexport PATH=\"$PATH:$(pwd)/target/release\"\n\n# Permanent (add to your .bashrc, .zshrc, etc.)\necho 'export PATH=\"$PATH:/path/to/version-control/target/release\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n### Prerequisites\n\n- Rust (1.54 or later recommended)\n- Cargo\n\n### Verifying Installation\n\nTo verify the installation:\n\n```bash\nrevtool --version\n```\n\n## Feature Highlights\n\nRevTool offers a range of powerful features designed for modern version control workflows:\n\n### Core Features\n\n- **Content-addressable storage** with BLAKE3 cryptographic hashing\n  - Efficient storage with automatic deduplication\n  - Cryptographic verification of content integrity\n  - Fast object retrieval\n\n- **Branch-based workflow** with intuitive semantics\n  - Simple branch creation and switching\n  - Support for multiple development lines\n  - Familiar mental model for Git users\n\n- **Snapshot-based versioning** with complete history\n  - Directed acyclic graph (DAG) for history tracking\n  - Support for merge commits with multiple parents\n  - Efficient storage that only tracks changes\n\n- **Flexible file ignoring** with gitignore-compatible patterns\n  - Use familiar glob syntax\n  - Automatically ignore common build artifacts\n  - Interactive pattern management\n\n- **Comprehensive diffing capabilities**\n  - Structural diffs (files added/removed/modified)\n  - Content-level diffs (line-by-line changes)\n  - Rich formatting with context\n\n### Advanced Features\n\n- **Robust merge capabilities**\n  - Three-way merging with conflict detection\n  - Interactive conflict resolution\n  - Multiple automatic merge strategies\n  - Custom editor support for conflict resolution\n\n- **Flexible snapshot references**\n  - Support for branch names, direct IDs\n  - Relative references like `HEAD~N`\n  - Shortened hash prefixes\n\n- **Interactive mode** for guided operations\n  - Simplified workflows for complex tasks\n  - Clear conflict resolution interfaces\n  - Friendly confirmation prompts\n\n## Command Reference\n\n```\nUsage: revtool [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  usage     Display help information and usage examples\n  ignore    Manage the ignore patterns\n  init      Initialize a brand new revision control repository\n  diff      Check the difference between snapshots\n  changes   Shows files and directories changed since the latest snapshot\n  status    Show working tree status\n  snap      Take a new snapshot (similar to git commit)\n  merge     Merge changes from another branch into the current branch\n  checkout  Switch to a branch\n  branch    Create or list branches\n  reset     Reset all files to the last snapshot on this branch\n  log       Show commit logs\n  help      Print this message or the help of the given subcommand(s)\n\nOptions:\n  -i, --interactive  Use interactive mode with prompts and confirmations\n  -h, --help         Print help\n  -V, --version      Print version\n```\n\n### Key Commands\n\n#### Initialize a Repository\n```bash\nrevtool init\n```\nCreates a new `.rev` directory to track your files.\n\n#### Checking Status\n```bash\nrevtool status\nrevtool status --content  # Shows content-level changes\n```\nShows which files have been added, modified, or deleted.\n\n#### Taking Snapshots (Committing)\n```bash\nrevtool snap -m \"Your commit message\"\nrevtool snap -i  # Interactive mode with guided prompts\n```\nRecords the current state of your files.\n\n#### Branch Management\n```bash\nrevtool branch                 # List branches\nrevtool branch feature-name    # Create a new branch\nrevtool checkout feature-name  # Switch to a branch\n```\n\n#### Comparing Versions\n```bash\nrevtool diff main feature      # Compare two branches\nrevtool diff HEAD~1            # Compare with previous snapshot\nrevtool diff --content main    # Show content-level differences\n```\n\n#### Viewing History\n```bash\nrevtool log         # Show recent snapshots\nrevtool log -l 5    # Show 5 most recent snapshots\n```\n\n#### Ignoring Files\n```bash\nrevtool ignore                # List current patterns\nrevtool ignore \"*.log\"        # Add a pattern\nrevtool ignore --remove \"*.log\"  # Remove a pattern\nrevtool ignore -i             # Interactive pattern management\n```\n\n#### Resetting Files\n```bash\nrevtool reset                 # Reset to last snapshot\nrevtool reset --delete-absent # Reset and delete untracked files\n```\n\n## Common Workflows\n\n### Starting a New Project\n\n```bash\n# Initialize a repository\nrevtool init\n\n# Create initial files\necho \"# My Project\" \u003e README.md\n\n# Check status\nrevtool status\n\n# Create first snapshot\nrevtool snap -m \"Initial commit\"\n```\n\n### Making Changes\n\n```bash\n# Edit files...\n\n# Check what's changed\nrevtool status\nrevtool status --content  # See the actual content changes\n\n# Record the changes\nrevtool snap -m \"Add feature X\"\n```\n\n### Working with Branches\n\n```bash\n# Create and switch to a feature branch\nrevtool branch new-feature\nrevtool checkout new-feature\n\n# Make changes and commit them\n# ... edit files ...\nrevtool snap -m \"Work on new feature\"\n\n# Compare with main branch\nrevtool diff main\n\n# Switch back to main\nrevtool checkout main\n```\n\n### Merging Branches\n\n```bash\n# Work on feature branch\nrevtool checkout feature-branch\n# ... make changes and create snapshots ...\n\n# Switch to target branch and merge\nrevtool checkout main\nrevtool merge feature-branch -m \"Merge feature-branch into main\"\n\n# If there are conflicts, you'll be prompted to resolve them\n# After resolving conflicts manually\nrevtool merge --continue\n\n# If you want to abort a merge with conflicts\nrevtool merge --abort\n```\n\n## Advanced Features\n\n### Merge Strategies\n\nRevTool provides several advanced merge capabilities to handle different scenarios:\n\n```bash\n# Automatically resolve all conflicts by taking our (current branch) version\nrevtool merge feature-branch --strategy ours\n\n# Automatically resolve all conflicts by taking their (merging branch) version\nrevtool merge feature-branch --strategy theirs\n\n# Default behavior, requires manual resolution\nrevtool merge feature-branch --strategy normal\n```\n\nIn interactive mode (`-i`), even with a strategy specified, you'll still be shown the conflicts that were automatically resolved.\n\n### Custom Editor for Conflict Resolution\n\nSpecify your preferred editor for resolving merge conflicts:\n\n```bash\n# Use vim to edit conflict files\nrevtool merge feature-branch --editor vim\n\n# Use VS Code to edit conflict files\nrevtool merge feature-branch --editor \"code -w\"\n```\n\nThe editor will be launched automatically when you choose to manually edit a conflict.\n\n### Interactive Mode\n\nMost commands support an interactive mode with `-i` that guides you through the process:\n\n```bash\nrevtool snap -i       # Interactive snapshot creation\nrevtool checkout -i   # Interactive branch selection\nrevtool ignore -i     # Interactive ignore management\n```\n\n## Architecture\n\nRevTool follows a design philosophy centered on simplicity, understandability, and functional purity. Core principles include:\n\n- **Content-addressable storage** as the foundation\n- **Immutable objects** for reliability\n- **Clean separation of concerns** in modular components\n- **Type safety** through Rust's strong typing system\n- **Explicit over implicit** in operations and commands\n\n### Core Components\n\n1. **`ObjectId` (`object_id.rs`)**\n   - Unique identifier based on content hash (BLAKE3)\n   - Used to address all content in the system\n\n2. **`ObjectStore` (`object_store.rs`)**\n   - Content-addressable storage interface\n   - Provides filesystem (`DirectoryObjectStore`) and in-memory implementations\n   - Automatically deduplicates identical content\n\n3. **`Directory` (`directory.rs`)**\n   - Represents a directory tree structure\n   - Maps file paths to their content hashes\n   - Includes diffing capabilities for comparing directories\n\n4. **`SnapShot` (`snapshot.rs`)**\n   - Represents a point-in-time version of the repository\n   - Links to a directory structure and parent snapshot(s)\n   - Forms nodes in the version history graph\n\n5. **`DotRev` (`dot_rev.rs`)**\n   - Manages the `.rev` directory structure\n   - Provides repository metadata operations\n   - Handles branch management\n\n6. **Content Diffing (`content_diff.rs`)**\n   - Implements line-based diffing for text files\n   - Uses a simplified Myers diff algorithm\n\n7. **Snapshot References (`snapshot_ref.rs`)**\n   - Flexible syntax for referencing snapshots\n   - Supports branch names, HEAD, relative refs (HEAD~1), and direct IDs\n\n### Repository Structure\n\nThe `.rev` directory contains:\n\n```\n.rev/\n  ├── store/         # Content-addressable object store\n  │   └── xx/        # Two-digit prefix subdirectories for efficient lookup\n  │       └── yy...  # Object contents stored by remaining hash digits\n  ├── branches/      # Branch references\n  │   ├── main       # Each file contains a snapshot ID\n  │   └── dev        # ...for the tip of the branch\n  ├── branch         # Text file containing current branch name\n  └── ignores        # JSON file with patterns for ignored files\n```\n\nAll objects (files, directories, snapshots) are stored in the content-addressable store and referenced by their hash, ensuring integrity and deduplication.\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue**: \"Repository not initialized\" error\n**Solution**: Run `revtool init` in the root directory of your project.\n\n**Issue**: Changes not showing up in status\n**Solution**: Check if the files are in the ignore list with `revtool ignore`. Files matching ignore patterns won't appear in status.\n\n**Issue**: Failed merge with conflicts\n**Solution**: \n1. Resolve conflicts in the marked files\n2. Run `revtool merge --continue`\n3. If you want to start over, use `revtool merge --abort`\n\n**Issue**: \"Branch not found\" error\n**Solution**: List available branches with `revtool branch` and check spelling. If needed, create the branch first.\n\n### Debugging Tips\n\n- Use `revtool status --content` for detailed change information\n- Examine the `.rev` directory structure for troubleshooting repository issues\n- Try interactive mode (`-i`) for complex operations to see more information\n\n### Getting Help\n\n- Use `revtool usage \u003ccommand\u003e` for detailed help on a specific command\n- Review this README for workflow guidance\n- Submit issues via GitHub for bugs or feature requests\n\n## Contributing\n\nContributions are welcome! To get started:\n\n1. Fork the repository\n2. Create a new branch for your feature or fix\n3. Make your changes\n4. Submit a pull request\n\nPlease ensure your code follows the existing style patterns and includes appropriate tests.\n\n### Development Workflow\n\n1. Clone your fork: `git clone https://github.com/your-username/version-control.git`\n2. Add upstream: `git remote add upstream https://github.com/SamuelSchlesinger/version-control.git`\n3. Create branch: `git checkout -b my-feature`\n4. Make changes and test\n5. Commit: `git commit -am \"Add new feature\"`\n6. Push: `git push origin my-feature`\n7. Create PR through GitHub\n\n## License\n\nSee the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelschlesinger%2Frevtool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelschlesinger%2Frevtool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelschlesinger%2Frevtool/lists"}