@ibgib/vcs-gib

Decentralized Version Control System (ibgib VCS) Built on content-addressed, cryptographic Merkle DAG hypergraphs (ib^gib).

vcs-gib provides a zero-dependency, 100% in-band decentralized version control system CLI engine for human developers and autonomous AI coding agents.

🏛️ Architecture Highlights

• Multi-Space Branching (b2s_<branchName>): Every branch lives in its own dedicated local space inside .vcsgib/ibgib/b2s_<branchName>/, eliminating metastone timeline collisions (tjp -> latest) and enabling native space-to-space SyncSaga branch merging (vcs merge).
• Single File-Root Branching & Micro-Repos: Branch individual file timelines (ibgib branch math-opt src/utils/math.js) for parallel AI agent swarm exploration or Gist-like snippet sharing.
• Upward .vcsgib Discovery: Commands run seamlessly from any subfolder or worktree directory (cd b/feature-ui or cd src/), walking parent directories to find the repository root (repoRoot).
• 100% In-Band ibgib Graph Storage: Repository index, active branch pointers, commit comments (CommentIbGib_V1), and binary payloads (BinIbGib_V1) are stored as immutable Merkle graph nodes.
• Zero 3rd-Party Runtime Dependencies: Pure TypeScript/ESM implementation using native Node.js APIs and @ibgib monorepo packages.

🌟 Innovative & Novel Aspects of vcs-gib

1. Single File-Root Branching ("Branching a File")

Traditional Git forces you to branch the entire repository, even if you only want to change a single file. vcs-gib allows branching individual file nodes (ibgib branch math-opt src/utils/math.js):

• Agentic AI Swarms: 5 sub-agents can work on 5 parallel file-branches (b2s_math_dp, b2s_math_simd, b2s_math_heuristic) targeting the exact same file timeline simultaneously.
• Micro-Repos & Gists: Share a single file's timeline over space-gib as a lightweight Gist-like micro-repo without project clutter.

2. Git + Package Manager Unification

In traditional software, Git tracks local source files while npm/cargo/pip fetch remote tarballs into node_modules/. In ibgib:

• Third-party packages, local files, and branch pointers are all content-addressed Merkle DAGs (b2tfs_item).
• Dependency graphs are connected via named edges (rel8ns.dependency), unifying version control and package management into a single Merkle graph engine.

3. Space-to-Space Merging (SyncSagaCoordinator)

Branch initialization, syncing, and merging use SyncSagaCoordinator natively space-to-space (sourceSpace $\longleftrightarrow$ targetBranchSpace). All exchanges produce immutable audit trails (SyncSagaIbGib_V1).

📚 Quickstart & Documentation

For the complete CLI user guide, command reference, worktree branching model, and step-by-step agent walkthroughs, see:

👉 VCS CLI User & Agent Quickstart Guide

⚡ Global CLI Commands

The CLI binary commands are globally available as ibgib and vcs:

# View command help
ibgib --help

# Initialize repository in current directory (creates b2s_main space in .vcsgib/ibgib/)
ibgib init .

# Check working tree status
ibgib status

# Stage untracked and modified files
ibgib add -a

# Commit snapshot with message
ibgib commit -m "My commit message"

# View commit timeline history
ibgib log

# List branches or create a root folder branch
ibgib branch feature-ui

# Branch a single file directly (creates b2s_math-opt targeting src/utils/math.js)
ibgib branch math-opt src/utils/math.js

# Switch active branch and project worktree (b/feature-ui/ or b/math-opt/math.js)
ibgib checkout feature-ui
ibgib checkout math-opt

🏗️ Monorepo Build, Test & Package Workflows

🧪 Unit & Integration Testing

Run the single token-efficient respec test command from the monorepo root:

npm run test:vcs-gib

📦 Isolated Downstream Testing & Hermetic Packaging (build:for:test)

To eliminate global npm link pollution and prepare for hermetic, dockerized downstream CI testing, vcs-gib provides a automated packaging pipeline.

Purpose of Isolated Testing:

• Prevents npm link from contaminating global system state or interfering with monorepo dependencies.
• Bumps the patch version (0.0.x), compiles vcs-gib, generates an npm tarball (.tgz), and deploys it to an isolated downstream testing workspace (test_repos/packages/).

How to Execute:

From the monorepo root:

# Run the test packaging pipeline (or 'npm run build:vcs-gib:test')
npm run build:for:test

Environment Variable Configuration:

The target destination directory can be configured in your root .env file or environment:

VCS_GIB_TEST_PACKAGE_DIR="c:\Users\billm\antigravity\test_repos\packages"

Downstream Execution Note:

💡 Next Step: After executing npm run build:for:test, navigate to your downstream test_repos workspace (c:\Users\billm\antigravity\test_repos\) and execute automated respec-gib integration test suites against vcs-gib-latest.tgz (or specific versioned tarball vcs-gib-0.0.x.tgz) as needed!