Skip to content
/ IvaldiVCS Public

Ivaldi VCS is a version control system that is being built as an alternative to Git. Currently Managed by Git until complete

1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

javanhut/IvaldiVCS

BranchesTags

Repository files navigation

Ivaldi VCS

A modern version control system designed as a Git alternative with enhanced features like timeline-based branching, content-addressable storage, and seamless GitHub integration.

Video Demo

part1_demo.mp4
part2_demo.mp4
part3_demo.mp4
part4_demo.mp4

Features

  • Timeline-Based Branching: Intuitive branch management with auto-shelving
  • Butterfly Timelines: Experimental sandboxes with bidirectional sync for safe development
  • Interactive Commit Squashing: Clean up history with arrow-key navigation before pushing
  • Interactive Merge Resolution: File-by-file conflict resolution with preview options
  • Hash Prefix Support: Reference commits with short hashes like abc123
  • Modern Cryptography: BLAKE3 hashing for security and performance
  • Content-Addressable Storage: Efficient deduplication and storage
  • GitHub Integration: Seamless clone, push, and pull operations
  • Auto-Shelving: Never lose work when switching branches
  • Submodule Support: Automatic Git submodule detection, conversion, and dual-hash tracking
  • Selective Sync: Download only the branches you need
  • Merkle Mountain Range: Append-only commit history with cryptographic proofs
  • Verbosity Control: --verbose and --quiet flags for output control

Quick Start

Installation

Automated Installation (Recommended)

The easiest way to install Ivaldi VCS is using the automated setup script:

# Install directly using curl
curl -fsSL https://raw.githubusercontent.com/javanhut/IvaldiVCS/main/setup.sh | bash

Or download and run:

# Download the setup script
curl -fsSL https://raw.githubusercontent.com/javanhut/IvaldiVCS/main/setup.sh -o setup.sh
chmod +x setup.sh

# Run the installer
./setup.sh

The setup script will:

  • Detect your operating system (Linux/macOS)
  • Install Go if needed (version 1.19+)
  • Download and build Ivaldi VCS
  • Install the binary to /usr/local/bin
  • Clean up temporary files

After installation, restart your terminal or run:

source ~/.bashrc  # Linux
source ~/.zshrc   # macOS with zsh

Manual Installation

If you prefer to build from source:

# Clone the repository
git clone https://github.com/javanhut/IvaldiVCS
cd IvaldiVCS

# Build and install (requires Go 1.19+)
make install

# Or build locally
make build
./build/ivaldi --help

Verify Installation

ivaldi --version
ivaldi --help

Uninstallation

To remove Ivaldi VCS from your system:

# Download and run the uninstall script
curl -fsSL https://raw.githubusercontent.com/javanhut/IvaldiVCS/main/uninstall.sh | bash

Or if you have the source:

./uninstall.sh

The uninstall script will:

  • Remove the Ivaldi binary from /usr/local/bin
  • Optionally clean up PATH entries from shell configuration files
  • Optionally remove source directory (if present)

You can also uninstall manually:

sudo rm /usr/local/bin/ivaldi

Basic Usage

# Initialize repository
ivaldi forge

# Check status
ivaldi status

# Stage files
ivaldi gather file1.txt file2.js

# Create commit (generates memorable seal name)
ivaldi seal "Add new features"
# Output: Created seal: swift-eagle-flies-high-447abe9b (447abe9b)

# Check current position
ivaldi whereami
# Output: Last Seal: swift-eagle-flies-high-447abe9b (just now)

# List all seals
ivaldi seals list

# Create and switch timeline (branch)
ivaldi timeline create feature-auth
ivaldi timeline switch main

# Create experimental timeline (butterfly)
ivaldi timeline butterfly experiment
# Make changes, test safely
ivaldi timeline butterfly up  # Merge to parent when ready

# Clean up commit history before pushing
ivaldi shift --last 5  # Interactive squash

GitHub Integration

# Authenticate with GitHub (OAuth)
ivaldi auth login

# Check authentication status
ivaldi auth status

# Connect to GitHub repository
ivaldi portal add owner/repo

# Clone from GitHub (auto-converts submodules!)
ivaldi download owner/awesome-project

# Discover remote branches
ivaldi scout

# Download specific branches
ivaldi harvest feature-auth bugfix-db

# Push changes
ivaldi upload

# Force push after squashing
ivaldi upload --force

Core Concepts

Timelines

Timelines are Ivaldi's equivalent to Git branches, but with enhanced features:

  • Auto-shelving: Uncommitted changes are automatically preserved when switching
  • Workspace isolation: Each timeline maintains its own workspace state
  • Butterfly timelines: Experimental sandboxes with bidirectional sync (up/down)
  • Efficient storage: Shared content between timelines via content-addressable storage

Gather and Seal

Ivaldi uses intuitive command names with enhanced user experience:

  • gather: Stage files (like git add)
  • seal: Create commit with auto-generated human-friendly names (like git commit)
  • seals: Manage seals with memorable names like "swift-eagle-flies-high-447abe9b"

Shift (Commit Squashing)

Clean up your commit history before pushing:

  • Interactive selection: Use arrow keys to select commit range
  • Safety confirmations: Multiple steps to prevent accidents
  • Force push warnings: Clear guidance on rewriting history

Scout and Harvest

Remote operations are designed for selective collaboration:

  • scout: Discover available remote branches
  • harvest: Download only the branches you need

Submodules

Automatic Git submodule support:

  • Auto-detection: Finds and converts Git submodules automatically
  • Dual-hash tracking: BLAKE3 for Ivaldi, Git SHA-1 for GitHub compatibility
  • Timeline-aware: Submodules track state per timeline

Documentation

Getting Started

Core Features

Commands

Remote Operations

Command Reference

Repository Management

ivaldi forge                    # Initialize repository
ivaldi status                   # Show working directory status
ivaldi whereami                 # Show current timeline details (alias: wai)
ivaldi config                   # Configure user settings (interactive)
ivaldi config --list            # List all configuration

File Operations

ivaldi gather [files...]        # Stage files for commit
ivaldi seal <message>           # Create commit with staged files (generates unique seal name)
ivaldi seals list               # List all seals with their generated names
ivaldi seals show <name|hash>   # Show detailed information about a seal
ivaldi reset [files...]         # Unstage files
ivaldi reset --hard             # Discard all uncommitted changes

History and Comparison

ivaldi log                      # Show commit history
ivaldi log --oneline            # Concise one-line format
ivaldi log --limit 10           # Show only last 10 commits
ivaldi diff                     # Show working directory changes
ivaldi diff --staged            # Show staged changes
ivaldi diff <seal>              # Compare with specific commit
ivaldi diff --stat              # Show summary statistics

Timeline Management

ivaldi timeline create <name>   # Create new timeline
ivaldi timeline switch <name>   # Switch to timeline
ivaldi timeline list           # List all timelines
ivaldi timeline remove <name>   # Delete timeline
ivaldi fuse <source> to <target> # Merge timelines
ivaldi fuse --continue          # Continue merge after resolving conflicts
ivaldi fuse --abort             # Abort current merge

Remote Operations

ivaldi auth login              # Authenticate with GitHub (OAuth)
ivaldi auth status             # Check authentication status
ivaldi auth logout             # Log out
ivaldi portal add <owner/repo>  # Add GitHub connection
ivaldi portal list             # List connections
ivaldi download <url> [dir]    # Clone repository
ivaldi scout                   # Discover remote timelines
ivaldi harvest [names...]      # Download timelines
ivaldi upload                  # Push to GitHub

Architecture Highlights

Content-Addressable Storage (CAS)

  • All content stored using BLAKE3 hashing
  • Automatic deduplication across the entire repository
  • Efficient storage of large files through chunking

Merkle Mountain Range (MMR)

  • Append-only commit history with cryptographic proofs
  • Efficient verification of commit inclusion
  • Persistent storage using BoltDB

HAMT Directory Trees

  • Hash Array Mapped Trie for efficient directory management
  • Structural sharing between timelines
  • O(log n) updates and lookups

Workspace Management

  • Intelligent file materialization when switching timelines
  • Auto-shelving preserves uncommitted changes
  • Minimal file system operations during switches

Migrating from Git

Here's how to translate a common Git workflow to Ivaldi:

# Git commands → Ivaldi commands

git init                                                             → ivaldi forge
git add README.md                                                    → ivaldi gather README.md
git commit -m "first commit"                                         → ivaldi seal -m "first commit"
git branch -M main                                                   → (not needed - main is default)
git remote add origin https://github.com/javanhut/TestRepoIvaldi.git → ivaldi portal add origin https://github.com/javanhut/TestRepoIvaldi.git
git push -u origin main                                              → ivaldi upload
#Initialize empty repository

ivaldi forge
ivaldi gather README.md
ivaldi seal "first commit"
ivaldi portal add javanhut/TestRepoIvaldi
ivaldi upload

Differences Ivaldi has:

Ivaldi sets main an default branch on initialization Gather can be use specifically or empty for all file added Sealing is like sealing a letter you have the message no need to specific it is. Portals don't need a https://github.com/owner/Repo.git the owner and repo are enough. You upload the code to github with upload keyword not a push.

Comparison with Git

Feature Git Ivaldi
Initialize git init ivaldi forge
Configure git config ivaldi config
Stage files git add ivaldi gather
Unstage git reset ivaldi reset
Commit git commit ivaldi seal
Log git log ivaldi log
Diff git diff ivaldi diff
Branch git branch ivaldi timeline create
Switch branch git checkout ivaldi timeline switch
Experimental branch (manual) ivaldi timeline butterfly
Merge git merge ivaldi fuse
Squash commits git rebase -i ivaldi shift
Clone git clone ivaldi download
Push git push ivaldi upload
Fetch git fetch ivaldi harvest
Submodules git submodule (automatic)

Advantages over Git

  1. Intuitive Commands: Clear, descriptive command names
  2. Human-Friendly Seals: Commits get memorable names like "swift-eagle-flies-high-447abe9b"
  3. Auto-Shelving: Never lose work when switching branches
  4. Butterfly Timelines: Safe experimental sandboxes with easy merge up/down
  5. Interactive Squashing: Arrow-key commit selection vs text editor rebase
  6. Automatic Submodules: Git submodules auto-detected and converted
  7. Selective Sync: Download only branches you need
  8. Modern Hashing: BLAKE3 for better security and performance
  9. Clean Storage: Content-addressable storage with automatic deduplication
  10. GitHub Integration: First-class GitHub support built-in

Development

Building

# Build the project
make build

# Run tests
make test

# Clean build artifacts
make clean

Project Structure

├── cli/                    # Command-line interface
├── internal/              # Internal packages
│   ├── cas/              # Content-addressable storage
│   ├── commit/           # Commit management
│   ├── filechunk/        # File chunking system
│   ├── github/           # GitHub integration
│   ├── hamtdir/          # HAMT directory trees
│   ├── history/          # MMR and timeline history
│   ├── refs/             # Reference management
│   ├── workspace/        # Workspace materialization
│   └── wsindex/          # Workspace indexing
├── docs/                  # Documentation
└── main.go               # Entry point

Contributing

  1. Fork the repository
  2. Create a feature timeline: ivaldi timeline create feature-name
  3. Make your changes and commit: ivaldi gather . && ivaldi seal "Description"
  4. Push to your fork: ivaldi upload
  5. Create a Pull Request

License

[License details to be added]

Acknowledgments

Ivaldi VCS builds upon research in:

  • Content-addressable storage systems
  • Merkle data structures
  • Modern cryptographic hashing
  • Version control system design

Ivaldi VCS - Modern version control for the modern developer

About

Ivaldi VCS is a version control system that is being built as an alternative to Git. Currently Managed by Git until complete

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

Release v0.1.0 Latest
Jan 14, 2026

Packages

No packages published

Contributors 2

  •  
  •  

Languages