# @fomantic/gulp-git 中文文档

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

版本：3\.0\.0
npm 元数据更新时间：2025-03-01T21:47:12.295Z
中文译文更新时间：2026-11-15T04:12:55.076Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：55.5 kB，30 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.18
- 运行依赖：7 个
- 首次发布：2024-05-05T21:08:36.465Z
- 最新版本发布：2025-03-01T21:47:12.101Z
- 近 30 天下载量：22441（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

Gulp (gulpjs.com) 的 Git 插件

## 安装

```sh
npm install @fomantic/gulp-git
```

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

## README

# 粘贴

> ### 使用更新的依赖关系伪造版本
> 
> 原始重播时间 [https://github.com/stephenlacy/gulp-git 页面存档备份,存于互联网档案馆](https://github.com/stephenlacy/gulp-git)

[![Build Status](https://travis-ci.org/stevelacy/gulp-git.png?branch=master)](https://travis-ci.org/stevelacy/gulp-git) [![NPM version](https://badge.fury.io/js/@fomantic%2Fgulp-git.png)](https://badge.fury.io/js/@fomantic%2Fgulp-git)

<table><tbody><tr><td>软件包</td><td>粘贴</td></tr><tr><td>说明</td><td>Gulp (gulpjs.com) 的 Git 插件</td></tr><tr><td>节点版本</td><td>页:1</td></tr><tr><td>Gulp 版本</td><td>4.x (中文(简体) )</td></tr></tbody></table>

## 使用量

### 安装

```
npm install gulp-git --save
```

#### 0:4.0 推出"突破变"!!

不需要进行 [维尼](https://github.com/wearefractal/vinyl) 文件已重构 . 请审查以下修改文件: □ 实例

```javascript
var gulp = require('gulp');
var git = require('gulp-git');

// Run git init
// src is the root folder for git to initialize
gulp.task('init', function(){
  git.init(function (err) {
    if (err) throw err;
  });
});

// Run git init with options
gulp.task('init', function(){
  git.init({args: '--quiet --bare'}, function (err) {
    if (err) throw err;
  });
});

// Run git add
// src is the file(s) to add (or ./*)
gulp.task('add', function(){
  return gulp.src('./git-test/*')
    .pipe(git.add());
});

// Run git add with options
gulp.task('add', function(){
  return gulp.src('./git-test/*')
    .pipe(git.add({args: '-f -i -p'}));
});

// Run git commit
// src are the files to commit (or ./*)
gulp.task('commit', function(){
  return gulp.src('./git-test/*')
    .pipe(git.commit('initial commit'));
});

// Run git commit with a computed commit message
gulp.task('commit', function(){
  let newVersion;
  function computeNewVersion() { newVersion = /* ... */ }
  return gulp.src('./git-test/*')
    .pipe(computeNewVersion())
    .pipe(git.commit(() => `Bumps to version ${newVersion}`));
});

// Run git commit with options
gulp.task('commit', function(){
  return gulp.src('./git-test/*')
    .pipe(git.commit('initial commit', {args: '-A --amend -s'}));
});

// Run git commit without checking for a message using raw arguments
gulp.task('commit', function(){
  return gulp.src('./git-test/*')
    .pipe(git.commit(undefined, {
      args: '-m "initial commit"',
      disableMessageRequirement: true
    }));
});

// Run git commit without appending a path to the commits
gulp.task('commit', function(){
  return gulp.src('./git-test/*')
    .pipe(git.commit('initial commit', {
      disableAppendPaths: true
    }));
});

// Run git commit, passing multiple messages as if calling
// git commit -m "initial commit" -m "additional message"
gulp.task('commit', function(){
  return gulp.src('./git-test/*')
    .pipe(git.commit(['initial commit', 'additional message']));
});

// Run git commit, emiting 'data' event during progress
// This is useful when you have long running githooks
// and want to show progress to your users on screen
gulp.task('commit', function(){
  return gulp.src('./git-test/*')
    .pipe(git.commit('initial commit', {emitData:true}))
    .on('data',function(data) {
      console.log(data);
    });
});

// Run git remote add
// remote is the remote repo
// repo is the https url of the repo
gulp.task('addremote', function(){
  git.addRemote('origin', 'https://github.com/stevelacy/git-test', function (err) {
    if (err) throw err;
  });
});

// Run git remote remove
// remote is the remote repo
gulp.task('removeremote', function(){
  git.removeRemote('origin', function (err) {
    if (err) throw err;
  });
});

// Run git push
// remote is the remote repo
// branch is the remote branch to push to
gulp.task('push', function(){
  git.push('origin', 'master', function (err) {
    if (err) throw err;
  });
});

// Run git push
// branch is the current branch & remote branch to push to
gulp.task('push', function(){
  git.push('origin', function (err) {
    if (err) throw err;
  });
});

// Run git push with options
// branch is the remote branch to push to
gulp.task('push', function(){
  git.push('origin', 'master', {args: " -f"}, function (err) {
    if (err) throw err;
  });
});

// Run git push with multiple branches and tags
gulp.task('push', function(){
  git.push('origin', ['master', 'develop'], {args: " --tags"}, function (err) {
    if (err) throw err;
  });
});

// Run git pull
// remote is the remote repo
// branch is the remote branch to pull from
gulp.task('pull', function(){
  git.pull('origin', 'master', {args: '--rebase'}, function (err) {
    if (err) throw err;
  });
});

// Run git pull from multiple branches
gulp.task('pull', function(){
  git.pull('origin', ['master', 'develop'], function (err) {
    if (err) throw err;
  });
});

// Run git fetch
// Fetch refs from all remotes
gulp.task('fetch', function(){
  git.fetch('', '', {args: '--all'}, function (err) {
    if (err) throw err;
  });
});

// Run git fetch
// Fetch refs from origin
gulp.task('fetch', function(){
  git.fetch('origin', '', function (err) {
    if (err) throw err;
  });
});

// Clone a remote repo
gulp.task('clone', function(){
  git.clone('https://github.com/stevelacy/gulp-git', function (err) {
    if (err) throw err;
  });
});

// Clone remote repo to sub folder ($CWD/sub/folder/git-test)
gulp.task('clonesub', function() {
  git.clone('https://github.com/stevelacy/git-test', {args: './sub/folder'}, function(err) {
    // handle err
  });
});

// Tag the repo with a version
gulp.task('tag', function(){
  git.tag('v1.1.1', 'Version message', function (err) {
    if (err) throw err;
  });
});

// Tag the repo with a version and empty message
gulp.task('tag', function(){
  git.tag('v1.1.1', '', function (err) {
    if (err) throw err;
  });
});

// Tag the repo With signed key
gulp.task('tagsec', function(){
  git.tag('v1.1.1', 'Version message with signed key', {signed: true}, function (err) {
    if (err) throw err;
  });
});

// Create a git branch
gulp.task('branch', function(){
  git.branch('newBranch', function (err) {
    if (err) throw err;
  });
});

// Checkout a git branch
gulp.task('checkout', function(){
  git.checkout('branchName', function (err) {
    if (err) throw err;
  });
});

// Create and switch to a git branch
gulp.task('checkout', function(){
  git.checkout('branchName', {args:'-b'}, function (err) {
    if (err) throw err;
  });
});

// Merge branches to master
gulp.task('merge', function(){
  git.merge('branchName', function (err) {
    if (err) throw err;
  });
});

// Reset a commit
gulp.task('reset', function(){
  git.reset('SHA', function (err) {
    if (err) throw err;
  });
});

// Show the formatted git diff
gulp.task('diff', function(){
  gulp.src('./*')
    .pipe(git.diff('master', {log: true}))
    .pipe(gulp.dest('./diff.out'));
});

// Git rm a file or folder
gulp.task('rm', function(){
  return gulp.src('./gruntfile.js')
    .pipe(git.rm());
});

gulp.task('addSubmodule', function(){
  git.addSubmodule('https://github.com/stevelacy/git-test', 'git-test', { args: '-b master'});
});

gulp.task('updateSubmodules', function(){
  git.updateSubmodule({ args: '--init' });
});

// Working tree status
gulp.task('status', function(){
  git.status({args: '--porcelain'}, function (err, stdout) {
    if (err) throw err;
  });
});

// Other actions that do not require a Vinyl
gulp.task('log', function(){
  git.exec({args : 'log --follow index.js'}, function (err, stdout) {
    if (err) throw err;
  });
});

// Git clean files
gulp.task('clean', function() {
  git.clean({ args: '-f' }, function (err) {
    if(err) throw err;
  });
});

// Get the current branch name

git.revParse({args:'--abbrev-ref HEAD'}, function (err, branch) {
  console.log('current git branch: ' + branch);
});

// Run gulp's default task
gulp.task('default',['add']);
```

^ API (英语)

### git.init( 选项, cb)

`git init`

创建空的 git repo

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.init({args:'options'}, function (err) {
  //if (err) ...
});
```

### git.clone( 远程、 选择、 cb)

`git clone <remote> <options>`

克隆首次远程重播

`remote`: 字符串、 远程 URL

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.clone('https://remote.git', function (err) {
  //if (err) ...
});
```

可设置脱去文件夹或子文件夹 `args: '<destination>'`

```
git.clone('https://remote.git', {args: './sub/folder'}, function (err) {
  //if (err) ...
});
```

### git.add( 选项)

`git add <files>`

添加文件到 repo

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024, maxFiles: Infinity}`

```js
gulp.src('./*')
  .pipe(git.add());
});
```

### git.commit( 消息, 选择)

`git commit -m <message> <files>`

提交更改为 repo

`message`: 字符串或字符串数组,承诺消息

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', maxBuffer: 200 * 1024, quiet: true, disableMessageRequirement: false, disableAppendPaths: false, multiline: false}`

```js
gulp.src('./*')
  .pipe(git.commit('commit message'));
});
```

### git.add 远程( 远程、 url、 选择、 cb)

`git remote add <remote> <repo https url>`

添加远程 repo url

`remote`:字符串,远程名称,默认: `origin`

`url`: 字符串、 URL 远程

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.addRemote('origin', 'git-repo-url', function (err) {
  //if (err) ...
});
```

### git.remove 远程( 远程, 选择, cb)

`git remote remove <remote>`

删除远程重播

`remote`: 字符串, 远程名称

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.removeRemote('origin', function (err) {
  //if (err) ...
});
```

### git.fetch( 远程, 分支, 选择, cb)

`git fetch <remote> <branch>`

从远程 Repo 获取 refs 和对象

`remote`:字符串,远程名称,默认: `origin`

`branch`:字符串,分支,默认值:"

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.fetch('origin', '', function (err) {
  //if (err) ...
});
```

### git.pul( 远程, 分支, 选择, cb)

`git pull <remote> <branch>`

从远程 Repo 调取更改

`remote`:字符串,远程名称,默认: `undefined`

`branch`: 字符串QQ阵列, 分支, 默认 : `undefined`

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.pull('origin', 'master', function (err) {
  //if (err) ...
});

// without any remote or branches
git.pull(function(err){
  //if (err) ...
});

// with only a remote
git.pull('upstream', function(err){
  //if (err) ...
});

// with remote and an array of branches
git.pull('upstream' ['dev', 'master'], function(err){
  //if (err) ...
});
```

### git.push( 远程, 分支, 选择, cb)

`git push <remote> <branch>`

推动更改到远程 Repo

`remote`:字符串,远程名称,默认: `origin`

`branch`: 字符串( 可能是) `null`),分支,默认值: `master`

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true}`

`cb`: 函数,如果有错误,则通过

```js
git.push('origin', 'master', function (err) {
  //if (err) ...
});
```

### git.tag( 版本、 消息、 选择、 cb)

`git tag -a/s <version> -m <message>`

带有发布版本的标签重播, 在没有参数的情况下返回所有标签

`version`: 字符串(可选),标签名称

`message`: 字符串或字符串数组( 可选), 标签消息

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.tag('v1.1.1', 'Version message', function (err) {
  //if (err) ...
});
```

如果选项。 签名为真, 标记将使用 git 安全密钥 : `git.tag('v1.1.1', 'Version message with signed key', {signed: true});`

### git.branch(分支,选择,cb)

`git branch <new branch name>`

创建新分行但不切换到它

(想要切换 当你创建? 使用 `git.checkout({args:'-b'})`. ) (中文(简体) )

`branch`: 字符串,分支

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.branch('development', function (err) {
  //if (err) ...
});
```

### git.showBranch( 选择, cb)

`git show-branch <opt>`

显示分枝及其承诺

`opt`对象(可选) `{args: 'options'}`

`cb`: 函数,如果有错误,则通过

```js
git.showBranch({'args': '--list -a'}, function (err) {
  //if (err) ...
});
```

### git.checkout (分支, 选择, cb)

`git checkout <new branch name>`

检查带有文件的新分支

`branch`: 字符串,分支

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.checkout('development', function (err) {
  //if (err) ...
});
```

如果您想要创建分支并切换到它:

```js
git.checkout('development', {args:'-b'}, function (err) {
  //if (err) ...
});
```

如果您想要检查出文件( 如还原文件) , 请使用 git. checkoutFiles :

```js
gulp.src('./*')
  .pipe(git.checkoutFiles());
```

### git. checkout Files( 选择)

`git checkout <list of files>`

退出( 如重设) 文件

`opt`对象(可选) `{args: 'options', quiet: true, maxBuffer: 200 * 1024}`

```js
gulp.src('./*')
  .pipe(git.checkoutFiles());
```

### git.commerce(分支,选择,cb)

`git merge <branch name> <options>`

将分支合并到当前分支

`branch`: 字符串,源分支

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.merge('development', function (err) {
  //if (err) ...
});
```

### git.rm () (中文(简体) )

`git rm <file> <options>`

从 git 删除一个文件并删除它

`opt`对象(可选) `{args: 'options', quiet: true, maxBuffer: 200 * 1024}`

```js
gulp.src('./*')
  .pipe(git.commit('commit message'));
});
```

### git.reset( 承诺、 选择、 cb)

`git reset <SHA> <options>`

将工作目录重新设置为指定任务散列

`commit`: 字符串、 承诺散列或引用

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数,如果有错误,则通过

```js
git.reset('HEAD' {args:'--hard'}, function (err) {
  //if (err) ...
});
```

### git.revParse( opt, cb) (中文(简体) )

`git rev-parse <options>`

获取仓库的细节

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数, 如果有错误, 或命令 stdout

```js
git.revParse({args:'--short HEAD'}, function (err, hash) {
  //if (err) ...
  console.log('current git hash: '+hash);
});
```

### git.add 子模块 ()

`git submodule add <options> <repository> <path>`

选项: 对象

`.addSubmodule('https://repository.git', 'path', {args: "options", quiet: true})`

### git.update 子模块 ()

`git submodule update <options>`

选项: 对象

`.updateSubmodule({args: "options", quiet: true})`

### git. status( 选择, cb)

`git status <options>`

显示工作树状态

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', maxBuffer: 200 * 1024, quiet: true}`

`cb`: 函数( 可选), 通过错误和命令 stdout

```js
git.status({args : '--porcelain'}, function (err, stdout) {
  // if (err) ...
});
```

### git.exec( 选择, cb)

`git <options>`

运行其他不需要Vinyl的 git 动作 .

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', maxBuffer: 200 * 1024, quiet: true}`

`cb`: 函数( 可选), 通过错误和命令 stdout

```js
git.exec({args : 'log --follow index.js'}, function (err, stdout) {
  //if (err) ...
});
```

### git. clean( 路径, 选择, cb)

`git clean <options>`

从工作树上删除未跟踪的文件

`paths`: 字符串( 可选), 受清洁操作影响的路径

`opt`: 对象(可选), `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

`cb`: 函数(可选),如果有错误,则通过

### git.diff( 分支, 选择)

`git diff master <options>`

Git 对象之间的diffs

`branch`: 字符串、分支名称、承诺名称或 git 标记

`opt`对象(可选) `{args: 'options', cwd: '/cwd/path', quiet: true, maxBuffer: 200 * 1024}`

```js
gulp.task('diff', function(){
  gulp.src('./*')
    .pipe(git.diff('develop', {log: true}))
    .pipe(gulp.dest('./diff.out'));
});
```

#### 您可以在 [示例文件夹.](https://github.com/stevelacy/gulp-git/tree/master/examples)

  
  

### 可能的错误 :

#### 最大强度超过

已报告 [这里](https://github.com/stevelacy/gulp-git/issues/68)。 。 。 .

如果你得到这个错误,这意味着git进程没有足够的内存.

每个函数都有一个附加选项: `maxBuffer`。 。 。 .

```js
gulp.task('pull', function(){
  git.pull('origin', 'master', {args: '--rebase', maxBuffer: Infinity}, function (err) {
    if (err) throw err;
  });
});
```

#### 命令线太长了.

已报告 [这里](https://github.com/stevelacy/gulp-git/issues/201)。 。 。 .

如果 `git add` 命令超过 [Windows 上的8191个字符](https://docs.microsoft.com/en-us/troubleshoot/windows-client/shell-experience/command-line-string-limitation#more-information) 你会得到这个错误.

这个 `add` 函数有附加选项: `maxFiles`。 。 。 .

```js
gulp.task('add', function(){
  return gulp.src('./git-test/*')
    .pipe(git.add({maxFiles: 8}));
});
```

## 自由主义

(麻省理工学院执照)

版权 (c) 2015 Steve Lacy [我@ slacy. me](mailto:me@slacy.me) 斯莱西. 我

特此免费准许任何人获得 该软件和相关文件文件的副本(第2条) “软件”,在软件中不受限制地处理,包括 不限制使用、复制、修改、合并、出版、, 软件的分发、分版和/或销售,以及 允许获得软件的人这样做,但须符合下列条件: 下述条件:

上述版权通知和本许可通知应为: 列入软件的所有副本或大部分.

软件是提供的"是", 没有任何种类的恐惧, ,包括但不受限制的 紧迫性,特别目的和 无所不入。 连警察或警察都没有 B. 任何索赔、救济或其他负债的赔偿责任 合同、合同或其他事项,产生于、产生于或产生于 与软件或使用 或其他交易在软件.

## 常见问题

### @fomantic/gulp-git 是什么？

Gulp \(gulpjs\.com\) 的 Git 插件

### 如何安装 @fomantic/gulp-git？

在项目目录运行 npm install @fomantic/gulp-git，或使用 pnpm add / yarn add / bun add。

### @fomantic/gulp-git 支持 TypeScript 吗？

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

### @fomantic/gulp-git 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @fomantic/gulp-git 需要什么版本的 Node\.js？

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

### @fomantic/gulp-git 可以商用吗？

@fomantic/gulp-git 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fomantic/gulp-git 的下载量有多少？

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

### @fomantic/gulp-git 还在维护吗？

最新版本 3\.0\.0 发布于 2025/03/02（1\.7 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。