# @git-stunts/plumbing 中文文档

规范地址：https://npmcn.com/package/%40git-stunts/plumbing/

版本：3\.3\.3
npm 元数据更新时间：2026-11-01T22:54:09.266Z
中文译文更新时间：2026-11-16T10:34:03.300Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40git-stunts/plumbing
原文对照：https://npmcn.com/package/%40git-stunts/plumbing/?lang=original
项目主页：https://github.com/git-stunts/plumbing#readme
源码仓库：https://github.com/git-stunts/plumbing

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：187 kB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- 首次发布：2026-01-08T01:38:51.620Z
- 最新版本发布：2026-11-01T22:54:08.902Z
- 近 30 天下载量：8192（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

勃起后,流出第一吉特水管,用于节点,邦和德诺.

## 安装

```sh
npm install @git-stunts/plumbing
```

也可以使用：`pnpm add @git-stunts/plumbing`、`yarn add @git-stunts/plumbing`、`bun add @git-stunts/plumbing`

## README

# @ git- stunts/ 发声

[![npm version](https://img.shields.io/npm/v/@git-stunts/plumbing.svg)](https://www.npmjs.com/package/@git-stunts/plumbing) [![License](https://img.shields.io/npm/l/@git-stunts/plumbing.svg)](https://npmcn.com/package/%40git-stunts/plumbing/LICENSE) [![CI](https://github.com/git-stunts/plumbing/actions/workflows/ci.yml/badge.svg)](https://github.com/git-stunts/plumbing/actions/workflows/ci.yml)

> **基建子系统工业基金会.**

`@git-stunts/plumbing` 是一个低水平,环境不可知的Git管道库,为现代JavaScript生态系统所设计. 建造在 **六边形建筑** 财务报告和审定财务报表 **域驱动设计( DDD)** 原理,它为 Git 操作提供了安全、流畅、第一和类型安全的接口 **节点Js、Bun和德诺**。 。 。 .

![Tux Plumber](https://github.com/user-attachments/assets/22e0e7e3-0587-48a8-aec5-6ec51e3d7fa6)

## 为什么是水管?

大多数Git库要么是泄露执行细节的高层次包装,要么是被运行时锁定的低层次绑定. `plumbing` 把吉特当作一个 **正式子系统**,将您的应用与弹壳执行、运行时间差异和安全风险的复杂性隔离开来.

-   **环境不可知论**:一个API用于节点,邦和德诺.
-   **Async- 第一架构**: 为v3.0而实现现代化,每个初始化和执行路径都是同步而非阻塞.
-   **默认流**: 使用统一流对所有运行时间进行内存高效数据处理.
-   **防御工程**:已建入OOM保护,论证消毒,并锁取回取.
-   **数学完整性**: 电源 **佐德语Name** 验证以确保每个SHA,Ref,和Object在被触摸到磁盘之前结构上的声音.

## 安全性: Docker任务

为了保护你的主机系统免受意外腐败 并确保可复制的处决, **严格禁止执行主机.** 这个项目使用 `@git-stunts/docker-guard` 强制隔离.

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

## \* 安装

```bash
npm install @git-stunts/plumbing
```

## QQ 快速启动

### 启动

现代 Git管道需要同步初始化,以安全地验证环境和工作目录.

```javascript
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}`);
```

### 原子提交流量

创建blobs, 树, 并按程序执行, 而不受手动外壳脚本的脆弱性 .

```javascript
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: 'james@flyingrobots.dev' },
  committer: { name: 'James Ross', email: 'james@flyingrobots.dev' },
  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]) },
  ],
});
```

### 不混合的泥浆检查

流出 Git 认为比 Canonial UTC 年长的松散无法到达的对象 断取. 这个API总是引用 Git 的 `--dry-run --no-progress`· ; 非限制性 `git prune` 仍由指挥部消毒器禁止.

```javascript
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;
```

### 持久性 Git 协议会话

重复的对象操作可以共享一个 stock Git 进程. 键入会话 包装器处理协议框架,同时保留明确的生命周期所有权:

```javascript
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` 是一个累积的内容预算 `readMany()`. 反应 超过剩余预算,不保留,操作 失败 `OBJECT_BUFFER_LIMIT_EXCEEDED`,本届会议仍与 后请. 默认预算为10 MiB.

可通过 `openMktreeSession()` 财务报告和审定财务报表 `openFastImportSession()`. 供应给 `write()` 仍然可以持续 或连结而成河,而不筑起一整棵树 缓冲. `writeMany()` 组装最多为 256 个边框的书写 独立树,而 `writeBlobs()` 组装一个边框协议写入 最多256个blobs 在一个可调用内容选择的预算 上限为64米B. `infoMany()` 在64 KiB命令预算下接受最多1000个对象名称。 全体 批量结果保存输入顺序.

`openUpdateRefSession()` 重用一个 `git update-ref --stdin` 跨进程 明确更新-ref交易。 内容 `update()` 方法执行一个 无条件更新当 `expectedOldOid` 实值 `undefined`· ; `null` 表示 只创建和 OID 表示比较和扫描。 它验证了吉特的命令 开始/准备/承诺确认。 被拒绝或不当的交易 毒害会议. `noDeref` (b) 消费者必须保留任何 需要单独进行象征性的安全检查.

会话没有隐含的超时. 他们的主人必须打电话 `close()` 用于有序 完成或替换 `terminate()`编号 :`abort()` 放弃工作的时候 水管拥有 进程和只使用 Git 协议机制; 调用器, 如 `@git-stunts/git-cas` 拥有集合,分块,缓存,留置,驱逐政策.

仅多克的微分基准将一次性操作与定界操作进行比较 批量窗口或针对新 SHA-256 存储器的连续反读会话. 它记录了时间流逝, Git 进程地形学, stdin 写数,和精确 对象识别证人:

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

## 深潜

-   [**标准指南**](https://npmcn.com/package/%40git-stunts/plumbing/GUIDE.md) - 从零到原子承诺.
-   [**高级指南**](https://npmcn.com/package/%40git-stunts/plumbing/ADVANCED_GUIDE.md) - 自定义跑道,流出内部和性能调谐.
-   [**建筑**](https://npmcn.com/package/%40git-stunts/plumbing/ARCHITECTURE.md) - 六角形设计的蓝图.
-   [**食谱**](https://npmcn.com/package/%40git-stunts/plumbing/docs/RECIPES.md) - Git应用的共同模式.
-   [**自定义运行器**](https://npmcn.com/package/%40git-stunts/plumbing/docs/CUSTOM_RUNNERS.md) - 一发和可选的双人跑道合同.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @git-stunts/plumbing 是什么？

勃起后,流出第一吉特水管,用于节点,邦和德诺\.

### 如何安装 @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 和提交记录判断。

