@git-stunts/plumbing

中文文档
3.3.3发布于 2026/11/02Apache-2.0ES Module构建来源已验证近 30 天下载 8192

Robust async, stream-first Git plumbing for Node, Bun, and Deno.

原始使用文档
文档目录10 节
  1. 🪠 Why Plumbing?
  2. 🛡️ Safety: Docker Mandate
  3. 📦 Installation
  4. 🛠️ Quick Start
  5. Async Initialization
  6. Atomic Commit Flow
  7. Non-Mutating Prune Inspection
  8. Persistent Git Protocol Sessions
  9. 📖 Deep Dives
  10. 📄 License

@git-stunts/plumbing

npm version License CI

The Industrial Foundation for Git-Based Subsystems.

@git-stunts/plumbing is a low-level, environment-agnostic Git plumbing library designed for the modern JavaScript ecosystem. Built on Hexagonal Architecture and Domain-Driven Design (DDD) principles, it provides a secure, streaming-first, and type-safe interface for Git operations across Node.js, Bun, and Deno.

Tux Plumber

🪠 Why Plumbing?

Most Git libraries are either high-level wrappers that leak implementation details or low-level bindings that are runtime-locked. plumbing treats Git as a formal subsystem, isolating your application from the complexities of shell execution, runtime differences, and security risks.

  • Environment Agnostic: One API for Node, Bun, and Deno.
  • Async-First Architecture: Modernized for v3.0, every initialization and execution path is asynchronous and non-blocking.
  • Streaming by Default: Memory-efficient data handling using unified streams for all runtimes.
  • Defensive Engineering: Built-in OOM protection, argument sanitization, and lock-contention retries.
  • Mathematical Integrity: Powered by Zod validation to ensure every SHA, Ref, and Object is structurally sound before it touches the disk.

🛡️ Safety: Docker Mandate

To protect your host system from accidental corruption and ensure reproducible execution, execution on the host is strictly prohibited. This project uses @git-stunts/docker-guard to enforce isolation.

# Run the industrial test suite
docker-compose run --rm node-test

📦 Installation

npm install @git-stunts/plumbing

🛠️ Quick Start

Async Initialization

Modern Git plumbing requires asynchronous initialization to safely validate the environment and working directory.

import GitPlumbing from '@git-stunts/plumbing';

// Safely open a repository (Async factory)
const git = await GitPlumbing.createRepository({ cwd: './my-assets' });

// Execute a command with full telemetry and OOM protection
const status = await git.execute({ args: ['rev-parse', '--is-inside-work-tree'] });
console.log(`Ready: ${status}`);

Atomic Commit Flow

Create blobs, trees, and commits programmatically without the fragility of manual shell scripts.

import GitPlumbing, { GitSha } from '@git-stunts/plumbing';

const git = await GitPlumbing.createRepository({ cwd: './my-repo' });

const commitSha = await git.createCommitFromFiles({
  branch: 'refs/heads/main',
  message: 'Feat: immutable asset storage',
  author: { name: 'James Ross', email: '[email protected]' },
  committer: { name: 'James Ross', email: '[email protected]' },
  parents: [GitSha.from(await git.revParse({ revision: 'HEAD' }))],
  files: [
    { path: 'manifest.json', content: JSON.stringify({ version: '1.0' }) },
    { path: 'data.bin', content: new Uint8Array([0xde, 0xad, 0xbe, 0xef]) },
  ],
});

Non-Mutating Prune Inspection

Stream loose unreachable objects that Git considers older than a canonical UTC cutoff. This API always invokes Git with --dry-run --no-progress; unrestricted git prune remains prohibited by the command sanitizer.

const plumbing = await GitPlumbing.createDefault({ cwd: './my-repo' });
const stream = await plumbing.inspectPrunableObjects({
  expiresBefore: '2026-07-01T00:00:00.000Z',
});

for await (const chunk of stream) {
  // Parse Git's `<object-id> <type>` records incrementally.
}
await stream.finished;

Persistent Git Protocol Sessions

Repeated object operations can share one stock Git process. The typed session wrappers handle protocol framing while preserving explicit lifecycle ownership:

const plumbing = await GitPlumbing.createDefault({ cwd: './my-repo' });
const objects = await plumbing.openCatFileSession();

try {
  const metadata = await objects.infoMany([firstOid, secondOid]);
  const values = await objects.readMany([firstOid, secondOid], {
    maxBytes: 8 * 1024 * 1024,
  });
  for (const { oid, type, content } of values) {
    consume(oid, type, content);
  }
} finally {
  await objects.close();
}

maxBytes is a cumulative content budget for readMany(). A response that exceeds the remaining budget is drained without being retained, the operation fails with OBJECT_BUFFER_LIMIT_EXCEEDED, and the session remains aligned for later requests. The default budget is 10 MiB.

Additional typed protocols are available through openMktreeSession() and openFastImportSession(). A single tree supplied to write() remains iterable or async iterable and is streamed without constructing a second whole-tree buffer. writeMany() assembles one bounded framed write for up to 256 independent trees, while writeBlobs() assembles one bounded protocol write for up to 256 blobs under a caller-selectable content budget capped at 64 MiB. infoMany() accepts up to 1,000 object names under a 64 KiB command budget. All batch results preserve input order.

openUpdateRefSession() reuses one git update-ref --stdin process across explicit update-ref transactions. Its update() method performs an unconditional update when expectedOldOid is undefined; null means create-only and an OID means compare-and-swap. It validates Git's ordered start/prepare/commit acknowledgements. A rejected or malformed transaction poisons the session. noDeref is explicit; on the minimum supported Git, consumers must retain any separate symbolic-ref safety check they require.

Sessions have no implicit timeout. Their owner must call close() for orderly completion or terminate()/abort() when abandoning work. Plumbing owns the process and Git protocol mechanics only; callers such as @git-stunts/git-cas own pooling, chunking, caching, retention, and eviction policy.

The Docker-only microbenchmark compares one-at-a-time operations with bounded batch windows or a persistent ref session against fresh SHA-256 repositories. It records elapsed time, Git process topology, stdin write count, and exact object-identity witnesses:

docker compose run --build --rm node-test npm run benchmark:protocol-sessions

📖 Deep Dives

📄 License

Apache-2.0

版本与发布记录

@git-stunts/plumbing 共发布 9 个版本,首次发布于 2026/01/08;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.3.3latest2026/11/0214 天前
3.3.22026/10/021 个月前
3.3.12026/09/082 个月前
3.3.02026/08/242 个月前
3.2.02026/07/193 个月前
3.1.02026/07/144 个月前

关于 @git-stunts/plumbing 的常见问题

@git-stunts/plumbing 是什么?

Robust async, stream-first Git plumbing for Node, Bun, and Deno.

如何安装 @git-stunts/plumbing?

在项目目录运行 npm install @git-stunts/plumbing,或使用 pnpm add / yarn add / bun add。

@git-stunts/plumbing 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/git-stunts__plumbing 是否存在。

@git-stunts/plumbing 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@git-stunts/plumbing 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@git-stunts/plumbing 可以商用吗?

@git-stunts/plumbing 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@git-stunts/plumbing 的下载量有多少?

根据 npm 官方下载统计,@git-stunts/plumbing 在 2026/10/17 – 2026/11/15 这 30 天内被下载 8,192 次,日均约 273 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@git-stunts/plumbing 还在维护吗?

最新版本 3.3.3 发布于 2026/11/02(14 天前);至今共发布 9 个版本,其中过去 12 个月发布了 9 个;首次发布于 2026/01/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。