{"id":42219062,"url":"https://github.com/statewalker/vcs","last_synced_at":"2026-01-27T01:36:29.778Z","repository":{"id":331933390,"uuid":"1101184404","full_name":"statewalker/vcs","owner":"statewalker","description":"Git-compatible version control system in pure TypeScript for browsers and servers","archived":false,"fork":false,"pushed_at":"2026-01-25T09:51:43.000Z","size":13449,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T00:37:34.326Z","etag":null,"topics":["content-addressable-storage","delta-compression","dvcs","git","typescript","vcs","version-control"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statewalker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T10:08:49.000Z","updated_at":"2026-01-25T09:51:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/statewalker/vcs","commit_stats":null,"previous_names":["statewalker/vcs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/statewalker/vcs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fvcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fvcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fvcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fvcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statewalker","download_url":"https://codeload.github.com/statewalker/vcs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fvcs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28795469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T01:07:07.743Z","status":"ssl_error","status_checked_at":"2026-01-27T01:07:06.974Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["content-addressable-storage","delta-compression","dvcs","git","typescript","vcs","version-control"],"created_at":"2026-01-27T01:36:29.161Z","updated_at":"2026-01-27T01:36:29.768Z","avatar_url":"https://github.com/statewalker.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StateWalker VCS\n\nA TypeScript implementation of Git-compatible version control, designed for content-addressable storage with delta compression. This library enables reading and writing Git repositories directly in JavaScript environments, including browsers.\n\n## Goal\n\nStateWalker VCS provides a portable, streaming-oriented implementation of Git's core object model. It allows applications to work with Git repositories without relying on native Git binaries or specific file system APIs.\n\nThe library focuses on three main capabilities:\n\n**Content-Addressable Storage** - Store and retrieve objects by their SHA-1 hash. Identical content automatically deduplicates, making storage efficient for version control workloads.\n\n**Delta Compression** - Reduce storage requirements by computing and storing differences between similar objects. The implementation supports multiple delta strategies including rsync-style rolling checksums and Myers diff algorithm.\n\n**Git Compatibility** - Read and write standard Git pack files, loose objects, and refs. Repositories created with StateWalker VCS work with native Git tools and vice versa.\n\n## Package Structure\n\nThe monorepo contains packages organized by responsibility:\n\n### Core Packages\n\n**[@statewalker/vcs-core](packages/core)** provides the foundational layer for building Git-compatible version control systems. It defines the core object model (blobs, trees, commits, tags), storage interfaces, and high-level operations. Includes Git file storage for reading and writing the standard `.git` directory structure.\n\n**[@statewalker/vcs-utils](packages/utils)** provides foundational algorithms including zlib compression/decompression, SHA-1 hashing with streaming support, and diff algorithms for computing deltas between binary content.\n\n**[@statewalker/vcs-commands](packages/commands)** offers a high-level Git command API. Rather than working directly with low-level stores, you interact through familiar commands like `add`, `commit`, `push`, and `merge`.\n\n**[@statewalker/vcs-transport](packages/transport)** implements the Git wire protocol (v1/v2), HTTP transport, and push/pull negotiation for communicating with remote repositories.\n\n### Storage Adapters\n\n**[@statewalker/vcs-store-mem](packages/store-mem)** provides in-memory storage for testing and development scenarios with no persistence.\n\n**[@statewalker/vcs-store-sql](packages/store-sql)** provides SQL-based storage using better-sqlite3. Objects, refs, and metadata persist in SQLite tables.\n\n**[@statewalker/vcs-store-kv](packages/store-kv)** bridges VCS storage interfaces to key-value stores like IndexedDB, LocalStorage, or LevelDB.\n\n### Development Utilities\n\n**[@statewalker/vcs-testing](packages/testing)** contains shared test utilities and fixtures used across packages.\n\n**[@statewalker/vcs-sandbox](packages/sandbox)** provides sandbox utilities for isolated testing environments.\n\n## Installation\n\n```bash\n# Install all dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run all tests\npnpm test\n```\n\n## Usage\n\n### Basic Repository Operations\n\nThe example application in [apps/example-git-cycle](apps/example-git-cycle) demonstrates the complete Git workflow. Here's a condensed version:\n\n```typescript\nimport { FilesApi, MemFilesApi } from \"@statewalker/webrun-files\";\nimport { createGitRepository, FileMode } from \"@statewalker/vcs-core\";\n\n// Initialize an in-memory repository\nconst files = new FilesApi(new MemFilesApi());\nconst repository = await createGitRepository(files, \".git\", {\n  create: true,\n  defaultBranch: \"main\"\n});\n\n// Store a file as a blob\nconst content = new TextEncoder().encode(\"Hello, World!\");\nconst blobId = await repository.blobs.store([content]);\n\n// Create a tree (directory snapshot)\nconst treeId = await repository.trees.storeTree([\n  { mode: FileMode.REGULAR_FILE, name: \"README.md\", id: blobId }\n]);\n\n// Create a commit\nconst commitId = await repository.commits.storeCommit({\n  tree: treeId,\n  parents: [],\n  author: { name: \"Alice\", email: \"alice@example.com\", timestamp: Date.now() / 1000, tzOffset: \"+0000\" },\n  committer: { name: \"Alice\", email: \"alice@example.com\", timestamp: Date.now() / 1000, tzOffset: \"+0000\" },\n  message: \"Initial commit\"\n});\n\n// Update the branch reference\nawait repository.refs.set(\"refs/heads/main\", commitId);\n```\n\n\u003e **Runnable example:** [apps/example-readme-scripts/src/basic-repository-operations.ts](apps/example-readme-scripts/src/basic-repository-operations.ts)\n\n### Working with Pack Files\n\nFor performance benchmarks and pack file operations, see [apps/example-git-perf](apps/example-git-perf). This example clones the Git source repository and demonstrates traversing commit history and reading delta-compressed objects.\n\n### Using the Commands API\n\nFor a higher-level API, use `@statewalker/vcs-commands` which provides Git-like commands:\n\n```typescript\nimport { Git, createGitStore } from \"@statewalker/vcs-commands\";\nimport { createGitRepository } from \"@statewalker/vcs-core\";\nimport { MemoryStagingStore } from \"@statewalker/vcs-store-mem\";\n\n// Create repository and staging\nconst repository = await createGitRepository();\nconst staging = new MemoryStagingStore();\nconst store = createGitStore({ repository, staging });\nconst git = Git.wrap(store);\n\n// Stage and commit (like git add \u0026\u0026 git commit)\nawait git.add().addFilepattern(\".\").call();\nawait git.commit().setMessage(\"Initial commit\").call();\n\n// Check status\nconst status = await git.status().call();\nconsole.log(\"Clean:\", status.isClean());\n\n// Create branches, merge, push, and more\nawait git.branchCreate().setName(\"feature\").call();\nawait git.checkout().setName(\"feature\").call();\n```\n\n\u003e **Runnable example:** [apps/example-readme-scripts/src/commands-api.ts](apps/example-readme-scripts/src/commands-api.ts)\n\u003e Note: The `git.add()` command requires a working tree iterator. The runnable example demonstrates an in-memory approach using direct staging manipulation.\n\n### Delta Compression\n\nThe library uses format-agnostic delta storage for efficient pack files:\n\n```typescript\nimport { applyDelta, createDelta, createDeltaRanges } from \"@statewalker/vcs-utils/diff\";\n\nconst baseContent = new TextEncoder().encode(\"Original file content\");\nconst newContent = new TextEncoder().encode(\"Original file content with additions\");\n\n// Step 1: Compute delta ranges (identifies copy vs insert regions)\nconst ranges = [...createDeltaRanges(baseContent, newContent)];\n\n// Step 2: Create delta instructions from ranges\nconst delta = [...createDelta(baseContent, newContent, ranges)];\n\n// Step 3: Apply delta to reconstruct new content\nconst chunks = [...applyDelta(baseContent, delta)];\nconst reconstructed = new Uint8Array(chunks.reduce((sum, c) =\u003e sum + c.length, 0));\nlet offset = 0;\nfor (const chunk of chunks) {\n  reconstructed.set(chunk, offset);\n  offset += chunk.length;\n}\n```\n\n\u003e **Runnable example:** [apps/example-readme-scripts/src/delta-compression.ts](apps/example-readme-scripts/src/delta-compression.ts)\n\n## Example Applications\n\nThe `apps/` directory contains several examples. See [docs/example-applications.md](docs/example-applications.md) for detailed documentation.\n\n| Application | Description |\n|-------------|-------------|\n| [example-readme-scripts](apps/example-readme-scripts) | Runnable versions of all README code examples |\n| [example-git-cycle](apps/example-git-cycle) | Complete Git workflow demonstration |\n| [example-git-lifecycle](apps/example-git-lifecycle) | Full Git lifecycle: init, commits, GC, packing, checkout |\n| [example-git-perf](apps/example-git-perf) | Performance benchmarks with real repositories |\n| [example-git-push](apps/example-git-push) | Push operations demonstration |\n| [example-vcs-http-roundtrip](apps/example-vcs-http-roundtrip) | Full HTTP clone/push workflow using VCS |\n| [example-pack-gc](apps/example-pack-gc) | Pack file garbage collection |\n| [examples-git](apps/examples-git) | Various Git format examples |\n| [perf-bench](apps/perf-bench) | Micro-benchmarks |\n\nRun any example:\n\n```bash\npnpm --filter @statewalker/vcs-example-git-cycle start\n```\n\n## Development\n\n```bash\n# Build a specific package\npnpm --filter @statewalker/vcs-core build\n\n# Run tests for a specific package\npnpm --filter @statewalker/vcs-core test\n\n# Lint and format\npnpm lint\npnpm format\n```\n\nThe project uses:\n- **pnpm** for package management with workspaces\n- **Turborepo** for build orchestration\n- **Rolldown** for bundling\n- **Vitest** for testing\n- **Biome** for linting and formatting\n\n## Requirements\n\n- Node.js 18 or later\n- pnpm 9.15.0 or later\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatewalker%2Fvcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatewalker%2Fvcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatewalker%2Fvcs/lists"}