simple-git Node.js 中简单易用的Git操作神器

2025年09月13日 22:22:50
4313
git工具 node组件 Git组件

项目结构

📌 git-js steveukx/git-js

Simple-Git 是一个基于 Node.js 的库，它为开发者提供了一种简单而直观的方式来执行 Git 命令。通过使用 Simple-Git，你可以在 Node.js 应用程序中轻松地执行诸如提交、推送、拉取等操作，而无需手动执行 Git 命令行。

项目大小 368.64 undefined
涉及语言 TypeScript 95.07% JavaScript 4.93%
许可协议 MIT License
Gitee Github

Simple Git

NPM version

A lightweight interface 对于 running git 命令s in any node.js 应用。

安装

使用你最喜欢的包管理器:

  • npm: npm install simple-git
  • yarn: yarn add simple-git

系统依赖项

需要 git 到 be installed 并且 that it can be called using the command git.

使用说明

使用 common js 包含到你的 JavaScript 应用中:

1
2
3
4
5
6
7
// require the library, main export 是 a function
const simpleGit = require('simple-git');
simpleGit().clean(simpleGit.CleanOptions.FORCE);
 
// 或者 use named properties
const { simpleGit, CleanOptions } = require('simple-git');
simpleGit().clean(CleanOptions.FORCE);

Include into your JavaScript app 作为 an ES Module:

1
2
3
import { simpleGit, CleanOptions } from 'simple-git';
 
simpleGit().clean(CleanOptions.FORCE);

在TypeScript应用中包含绑定的类型定义:

1
2
3
import { simpleGit, SimpleGit, CleanOptions } from 'simple-git';
 
const git: SimpleGit = simpleGit().clean(CleanOptions.FORCE);

配置

分别配置每个 simple-git 带有属性对象传递给主实例的情况 simpleGit 函数:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { simpleGit, SimpleGit, SimpleGitOptions } from 'simple-git';
 
const 选项s: Partial<SimpleGitOptions> = {
   baseDir: 处理。cwd(),
   二进制: 'git',
   maxConcurrentProcesses: 6,
   trimmed: false,
};
 
// when setting all options in a single 对象
const git: SimpleGit = simpleGit(options);
 
// or split out the baseDir, 支持 for backward compatibility
const git: SimpleGit = simpleGit('/some/path', { binary: 'git' });

The first 论点 can be either a string (representing the working 目录 for git 在运行的命令)
SimpleGitOptions 对象或 undefined第二个参数是可选的 SimpleGitOptions 对象。

所有配置属性都是可选的，示例上方显示了默认值。

按命令配置

用于运行命令的前缀 simple-git 使用自定义配置未保存在git配置中（例如：使用自定义配置未保存在git配置中（例如：
-c 命令) 创建一个 config 实例构建器的选项:

1
2
3
4
5
6
// configure the 实例 with a custom configuration property
const git: SimpleGit = simpleGit('/some/path', { config: ['http.proxy=someproxy'] });
 
// any command executed will be prefixed with this config
// runs: git -c http.proxy=someproxy pull
await git.pull();

配置插件

  • AbortController
    Terminate pending and future tasks in a simple-git instance (requires node >= 16).

  • Custom Binary
    Customise the git 二进制 simple-git 在生成时使用 git 子进程。

  • Completion Detection
    Customise how simple-git 检测到一个的结束 git process.

  • Error Detection
    Customise the detection of errors 从的 underlying git process.

  • Progress Events
    Receive progress events as git 通过长时间运行的过程来工作。

  • Spawned Process Ownership
    Configure the system uid / gid 用于生成的 git 进程。

  • Timeout
    Automatically kill the wrapped git *动超时后的处理流程。

  • Unsafe
    Selectively opt out of simple-git 安全注意事项 - 适用于高级用户和用例。

使用任务承诺

每个 task in the 应用程序接口 returns the simpleGit 用于链接多个任务的实例，每个
链中的每一步也是一个 Promise 那可以是 await 在其中 async 函数或返回在一处
Promise 链式反应。

1
2
3
4
5
6
7
8
const git = simpleGit();
 
// chain together tasks to await final result
await git.init().addRemote('origin', '...remote.git');
 
// or await each step individually
await git.init();
await git.addRemote('origin', '...remote.git');

在异步代码中捕获错误

为了在异步代码中捕获错误，可以将整个链式调用包裹在try/catch语句中:

1
2
3
4
5
6
7
const git = simpleGit();
try {
   await git.init();
   await git.addRemote(name, repoUrl);
} catch (e) {
   /* handle all errors here */
}

或者捕获单个步骤以允许主链继续执行，而不是
跳到最终结果 catch 在第一次出错时:

1
2
3
4
5
6
7
8
9
const git = simpleGit();
try {
   await git.init().catch(ignoreError);
   await git.addRemote(name, repoUrl);
} catch (e) {
   /* handle all errors here */
}
 
function ignoreError() {}

使用任务回调

除了返回一个承诺外，每个方法还可以带有一个尾随的回调参数进行调用
to handle the result 的 task.

1
2
3
4
5
const git = simpleGit();
git.init(onInit).addRemote('origin', 'git@github.com:steveukx/git-js.git', onRemoteAdd);
 
function onInit(err, initResult) {}
function onRemoteAdd(err, addRemoteResult) {}

如果链中的任何步骤出现错误，所有待处理的步骤都将被取消，请参见
parallel tasks 并行执行任务而非串行执行任务的相关信息部分。

任务响应

无论是使用尾随回调还是Promise，任务都会返回原始数据 string or Buffer 来自回应的
git 二进制，或者尽可能对响应进行解析解释。

请参阅每个任务响应的类型详细信息 TypeScript definitions.

从版本2升级

从 v3 of simple-git 你现在可以导入为ES模块、Common JS模块或带类型**的TypeScript模块
升级从v2将对任何不依赖已标记为弃用的API的应用程序无缝进行
在v2版本中（弃用通知被记录到 stdout as console.warn 在 v2)。

API

API 它做什么
.add([fileA, ...], handlerFn) 添加一个或多个文件到源代码控制中
.addAnnotatedTag(tagName, tagMessage, handlerFn) 给当前分支的头部添加一个带注释的标签
.addTag(name, handlerFn) 给当前分支的头部添加一个轻量级标签
.catFile(options, [handlerFn]) 生成 cat-file 详情 options should be an array of strings as supported 参数 to the cat-file command
.checkIgnore([filepath, ...], handlerFn) 检查文件路径是否被.gitignore规则排除
.clearQueue() 立即清空待处理任务队列（注意：任何当前正在进行中的命令仍会调用其完成回调）
.commit(message, handlerFn) 提交当前工作目录的更改，并使用提供的消息，其中消息可以是单个字符串或字符串数组，作为单独的参数传递（该） git 命令行界面将这些转换为用双换行符分隔)
.commit(message, [fileA, ...], options, handlerFn) 提交指定文件的更改，并带有提供的消息。如果提供了可选的选项对象，它可以包含要传递给提交命令的任何其他参数，将属性值设置为字符串将添加 name=value 在命令字符串中，设置其他类型的值只会传递对象中的键（例如：仅传递键） name例如，设置作者的方法如下
.customBinary(gitPath) 设置用于引用git的命令，允许使用不在路径环境变量中的git二进制文件 docs
.env(name, value) 设置要传递给生成的子进程的环境变量， see usage in detail below.
.exec(handlerFn) 在当前步骤中调用一个简单的函数
.fetch([options, ] handlerFn) 更新本地工作副本数据库，将默认远程仓库和分支的更改合并进来, when supplied the options argument can be a standard options object 要么是一个字符串命令数组，如由系统支持的那样 git fetch.
.fetch(remote, branch, handlerFn) 更新本地工作副本数据库与远程仓库中的更改
.fetch(handlerFn) update the local working copy database with changes from the default remote repo and branch
.outputHandler(handlerFn) 附加一个处理程序，该处理程序将在运行命令时被调用，并传递命令的名称以及 stdout and stderr readable streams 由…创作 child process 运行该命令，查看 examples
.raw(args, [handlerFn]) 执行任何由底层 git 二进制文件支持的任意命令序列。 当git进程退出时返回非零信号并且它打印了一些内容到 stderr如果命令中包含逗号，将被视为错误，否则将被视为成功。
.rebase([options,] handlerFn) 重新基于仓库进行操作 options 应该作为支持的字符串参数数组提供 git rebase 命令，或者一个选项对象（有关选项格式的详细信息，请参见下方说明）。
.revert(commit , [options , [handlerFn]]) 撤销工作副本中的一个或多个提交。 该提交可以是任何常规的提交-ish 值（哈希值、名称或偏移量，例如） HEAD~2或者一个提交范围（例如: master~5..master~2当提供以下内容时 options 参数包含任何被接受的选项 git-revert.
.rm([fileA, ...], handlerFn) 从源代码控制中移除任意数量的文件
.rmKeepLocal([fileA, ...], handlerFn) 从版本控制中删除文件但保留它们在磁盘上
.tag(args[], handlerFn) 运行任何支持的 git tag 带参数的命令，参数以字符串数组形式传递。
.tags([options, ] handlerFn) 列出所有标签，使用可选项 options object to 设置 any options allows by the git tag 命令。 Tags will be sorted by semantic version number by default, for git versions 2.7 and above, 使用该 --sort 自定义排序的选项。

git apply

  • .applyPatch(patch, [options]) 应用一个单一的字符串补丁（如由生成的 git diff可选地，使用提供的配置进行配置 options to set any arguments 由…支持 apply 命令。返回未经修改的字符串响应 stdout of the git 二进制。
  • .applyPatch(patches, [options]) 应用一组字符串补丁（如由生成的 git diff), optionally configured 具有 supplied options 用来设置任何由该程序支持的参数 apply command. Returns the unmodified string response from stdout of the git binary.

git branch

  • .branch([options]) 使用提供的 options 运行任何由该支持的参数 branch 命令。要么返回一个 BranchSummaryResult 在列出分支时的示例，或一个 BranchSingleDeleteResult 当选项包含类型对象时 -d, -D or --delete 这会导致它删除一个已命名的分支，而不是列出现有的分支。
  • .branchLocal() 获取本地分支列表 BranchSummaryResult instance
  • .deleteLocalBranch(branchName) 删除一个本地分支 - 将失败的尝试视为错误
  • .deleteLocalBranch(branchName, forceDelete) 删除一个本地分支，可选地显式设置 forceDelete 为 true - 将失败的尝试视为错误
  • .deleteLocalBranches(branchNames) 删除多个本地分支
  • .deleteLocalBranches(branchNames, forceDelete) 删除多个本地分支，可选地显式设置 forceDelete 为 true

git clean

  • .clean(mode) 清理工作树。 模式应为 “n” - 乾运行或 “f” - 强制
  • .clean(cleanSwitches [,options]) set cleanSwitches 转换为包含任何数量的支持单字符选项的字符串，可选地带有标准 options object

git checkout

  • .checkout(checkoutWhat , [options]) - 检查提供的标签、修订版或分支，当其作为字符串提供时
    additional arguments supported by git checkout 可以作为一项提供
    options 对象/数组.

  • .checkout(options) - 使用提供的标签或修订版本进行检查 options

  • .checkoutBranch(branchName, startPoint) - 从提供的起始点检出一个新分支。

  • .checkoutLocalBranch(branchName) - 检查出一个新的本地分支

克隆git

  • .clone(repoPath, [localPath, [options]]) 从远程仓库克隆 repoPath 到本地目录中 localPath可选地，带有标准的 options 附加参数的对象，用于在之间包含 git clone 以及后面的 repo local arguments

  • .clone(repoPath, [options]) clone a remote repo at repoPath 在当前工作目录中同名的目录里

  • mirror(repoPath, [localPath, [options]]) 表现与…相同 .clone 与接口相连 --mirror flag 启用。

git config

  • .addConfig(key, value, append = false, scope = 'local') 添加一个本地配置属性，当 append 即将设定为
    true 该配置设置是追加到本地配置文件中，而不是覆盖。 使用该 scope argument
    to pick where to save the new configuration setting (use the exported GitConfigScope 枚举，或等效字符串
    values - worktree | local | global | system).

  • .getConfig(key) 获取名为键的值（s）作为 a ConfigGetResult

  • .getConfig(key, scope) get the value(s) for a named key as a ConfigGetResult 但限制
    scope of the properties searched to a single specified scope (use the exported GitConfigScope 枚举，或等效项
    string values - worktree | local | global | system)

  • .listConfig() 读取当前配置并返回一个 ConfigListSummary

  • .listConfig(scope: GitConfigScope) 如同 listConfig 但只返回指定范围内的那些项目（请注意，配置值会层层叠加以构建配置） git 将会实际使用 - 用于解决您正在使用的配置 (await listConfig()).all 没有scope参数的情况下

git 统计对象数量

git diff

  • .diff([ options ]) 获取当前仓库与上一次提交的差异，可选择性地包括
    any number of other arguments supported by git diff 作为**的
    options 对象/数组。 Returns the raw diff 作为字符串输出。

  • .diffSummary([ options ]) 创建一个 DiffResult
    to summarise the diff for files in the repo. Uses the --stat 默认格式，可以被覆盖
    by passing in any of the log format commands (eg: --numstat or --name-stat作为可选部分
    options object/array.

git 搜索 examples

  • .grep(searchTerm) 在工作树中的所有文件中搜索单个搜索项，可选地传递一个标准 options 附加参数的对象
  • .grep(grepQueryBuilder(...)) use the grepQueryBuilder 用来创建一个复杂查询以进行搜索，可选择性地传递一个标准 options object of additional arguments

git 哈希对象

  • .hashObject(filePath, write = false) 计算名为文件的内容的对象ID值（该文件可以是）
    outside of the work tree), optionally writing the resulting value to the object database.

git init

  • .init(bare , [options]) 使用布尔值初始化仓库 bare 参数用于初始化一个裸仓库。
    Any number of other arguments supported by git init can be supplied as an
    options object/array.

  • .init([options]) 使用任何支持的参数初始化仓库
    git init 作为**的 options object/array.

git log

  • .log([options]) 列出提交记录之间的差异 options.from and options.to tag或 branch (if not specified will
    show all history)使用该功能 options 反对设置任何对象 options supported by the
    git log 命令或以下任一选项:

    • options.file - 到你仓库中一个文件的路径，仅考虑此路径。
    • options.format - 自定义日志格式对象，键是返回对象中使用的属性名称，值是格式字符串 pretty formats
    • options.from - 设置范围内要返回的最旧的提交，通常与一起使用 options.to 设定一个有限的范围
    • options.mailMap - 默认为true，启用 the use of mail map 在返回的电子邮件和名称值中使用默认格式
    • options.maxCount - 等同于设置的 --max-count option
    • options.multiLine - 启用默认格式中的多行正文值（默认情况下禁用）
    • options.splitter - 用于在日志中分隔字段的字符序列，应是一个在任何日志消息中都不会出现的值（默认值为 ò)
    • options.strictDate - 将编写的日期值从类似ISO 8601的格式转换为严格的ISO 8601格式
    • options.symmetric - defaults to true, enables symmetric revision range 而不是一个两点范围
    • options.to - 设置要返回的范围内新的提交，通常与一起使用 options.from to set a bounded range

    当只有一个的时候 options.from and options.to 在提供时，省略选项的默认值等同于 HEAD对于任何其他提交，请明确指定from和to提交（例如使用 await git.firstCommit() 作为默认值的 from 从仓库的第一个提交开始记录。

git 合并

  • .merge(options) 运行着 merge using any configuration options supported
    by git merge.
    Conflicts during the merge result in an error response, the response is an instance of
    MergeSummary 是错误还是成功。
    When successful, the MergeSummary has all detail from a the PullSummary
    along with summary detail 对于这个 merge.
    当的时候 merge failed, the MergeSummary contains summary detail for why the merge failed and which files
    prevented the merge.

  • .mergeFromTo(remote, branch , [options]) - 从指定的分支合并到当前检出的分支中
    similar to .merge 但是有 remote and branch 分别作为字符串提供给任何附加项
    options.

git mv

  • .mv(from, to) 重命名或移动单个文件 from to to

  • .mv(from, to) 把所有文件移到该目录下 from 数组到的 to directory

git pull

  • .pull([options]) 从默认跟踪的远程仓库拉取所有更新，任何由支持的参数
    git pull 可以作为一项提供 options object/array.

  • .pull(remote, branch, [options]) 从指定的远程分支（例如 ‘origin’/‘master’）拉取所有更新
    with any custom options object/array

git push

  • .push([options]) 推送到名为远程/分支的位置，使用任何支持的方式 options
    from the git push 命令。请注意 simple-git 强制使用
    --verbose --porcelain 按顺序排列的选项以解析响应。 您不需要提供这些选项。

  • .push(remote, branch, [options]) 推送到命名的远程/分支，支持额外的
    options from the git push command.

  • .pushTags(remote, [options]) 将本地标签推送到名为远程（等同于使用） .push([remote, '--tags']))

git 远程

  • .addRemote(name, repo, [options]) 添加一个名为的远程仓库以进行跟踪 name 在小径上 repo可选地，带有任何支持的 options for the git add 呼叫。
  • .getRemotes([verbose]) 获取名为远程的列表，可选地提供 verbose 选项作为 true 包含每个参考文献的网址和用途
  • .listRemote([options]) 列出远程仓库 - 底层存在如此多的可选参数 git ls-remote 调用，只需提供您想要使用的任何可选内容 options 例如: git.listRemote(['--heads', '--tags'], console.log)
  • .remote([options]) runs a git remote 带任意数量的命令 options
  • .removeRemote(name) 删除指定的远程仓库

git reset

  • .reset(resetMode, [resetOptions]) 重置仓库，将重置模式设置为支持的一种类型（使用来自常量的值）
    the exported ResetMode 枚举，或等效的字符串: mixed, soft, hard, merge, keep任意数量的其他参数
    supported by git reset can be supplied as an options object/array.

  • .reset(resetOptions) 用提供的内容重置仓库 options

  • .reset() 将仓库重置为 soft 模式。

git rev-parse / 仓库属性

  • .revparse([options]) 发送提供的 options to git rev-parse 并返回字符串响应 git.

  • .checkIsRepo() 获取当前工作目录是否是某个git仓库的子目录。

  • .checkIsRepo('bare') 判断当前工作目录是否位于一个裸仓库中（参见以下内容） git clone --bare or git init --bare).

  • .checkIsRepo('root') 获取当前工作目录是否为仓库的根目录（子目录将返回false）。

  • .firstCommit() 获取当前仓库中第一次提交的提交哈希值。

git show

  • .show(options) 显示各种类型的对象，例如某个提交中的文件内容。 options 是单个值字符串还是任何其他类型 options 由…支持 git show command.
  • .showBuffer(options) 和相同 .show API，但直接返回缓冲区内容，以便显示二进制文件内容。

git status

  • .status([options]) 获取当前仓库的状态，结果是 StatusResult. 额外参数
    supported by git status can be supplied as an options object/array.

git 子模块

  • .subModule(options) 运行一个 git submodule 带有一个或多个参数的命令 options 数组或对象
  • .submoduleAdd(repo, path) 添加了一个新的子模块
  • .submoduleInit([options] 初始化子模块，可选的 options 参数可以用来传递额外的选项给 git submodule init command.
  • .submoduleUpdate(subModuleName, [options]) 更新子模块，可以带子模块名称调用 options仅选项或无参数

git stash

  • .stash([ options ]) 保存工作目录，可选的第一个参数可以是一个字符串数组或 options 传递给对象的参数 git stash command.

  • .stashList([ options ]) 获取*品列表，可选的第一个参数可以是与在相同格式中使用的对象 git log.

git 版本 examples

  • .version() 获取当前安装的主版本、次版本和补丁版本 git. Use the .installed 结果属性用于确定是否 git 可在路径**问。

更改工作目录 examples

  • .cwd(workingDirectory) 设置所有后续命令的工作目录 - 注意，这将更改根实例的工作目录，任何从根实例创建的链的工作目录也会被更改。
  • .cwd({ path, root = false }) 设置所有未来命令的工作目录，无论是当前命令链中的哪个位置（其中 root 被省略或设置为 false或者在主实例（其中） root is true).

如何指定选项

在任务接受自定义选项的地方（例如: pull or commit这些可以作为对象提供，其键为
所有内容都将作为命令字符串中的尾随参数合并，或者作为字符串的简单数组。

选项作为对象

当选项对象中属性的值是时 string，那个名称值
这对将包含在命令字符串中 name=value例如:

1
2
3
4
5
// results in 'git pull origin master --no-rebase'
git.pull('origin', 'master', { '--no-rebase': null });
 
// results in 'git pull origin master --rebase=true'
git.pull('origin', 'master', { '--rebase': 'true' });

当属性的值是一个数组时 strings or number每个元素都将被
作为单独的部分 name=value 配对:

1
2
// results in 'git log --grep=bug --grep=fix --grep=feature'
git.log({ '--grep': ['bug', 'fix', 'feature'] });

选项作为数组

选项也可以作为字符串数组提供，合并到任务的命令中
以同样的方式，当一个物体被使用时:

1
2
// results in 'git pull origin master --no-rebase'
git.pull('origin', 'master', ['--no-rebase']);

发布历史

主要版本3.x更改了库的打包方式，使其可以作为CommonJS模块、ES模块进行使用
使用TypeScript（见 usage 在上面提到的。该库现在已发布为一个单独的文件，因此请确保您的
应用程序没有通过从子目录路径导入来使用非文档化的API。

看见 also:

并发/并行请求

当方法为时 simple-git 它们被链接在一起，会形成一个依次执行的执行链，非常有用
当任务本身具有顺序依赖性时:

1
simpleGit().init().addRemote('origin', 'https://some-repo.git').fetch();

每个任务在被调用之前都需要确保前一个任务已经成功运行，任何在其中的错误都会导致后续任务无法执行
链条的步骤应防止后续步骤被尝试。

When the methods of simple-git 被称为根实例（即: git = simpleGit()而不是链式连接
在处理另一个任务时，它会启动一个新的链，并且不会受到正在运行的任务中失败的影响。 有用的
当任务彼此**时，例如:

1
2
3
4
5
6
7
8
const git = simpleGit();
const results = await Promise.all([
   git.raw('rev-parse', '--show-cdup').catch(swallow),
   git.raw('rev-parse', '--show-prefix').catch(swallow),
]);
function swallow(err) {
   return null;
}

Each simple-git 实例限制可以同时运行的生成子进程的数量
为您管理待处理任务的队列。 通过传递一个选项对象来配置此值
simpleGit 函数，例如:

1
const git = simpleGit({ maxConcurrentProcesses: 10 });

将根实例上调用的任务视为**链的开始是对行为的一种改变
simple-git 并在版本中添加 2.11.0.

复杂请求

当接口中没有适合的包装器用于创建请求时，直接运行命令
使用 git.raw([...], handler)数组中的命令直接传递给 git binary:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const path = '/path/to/repo';
const commands = ['config', '--global', 'advice.pushNonFastForward', 'false'];
 
// using an array of commands and node-style callback
simpleGit(path).raw(commands, (err, result) => {
   // err is null unless this command failed
   // result is the raw output of this command
});
 
// using a var-args of strings and awaiting rather than using the callback
const result = await simpleGit(path).raw(...commands);
 
// automatically trim trailing white-space in responses
const result = await simpleGit(path, { trimmed: true }).raw(...commands);

认证

向远程主机提供用户名/密码最简单的方法是将它们包含在URL中，例如:

1
2
3
4
5
6
7
8
9
10
const USER = 'something';
const PASS = 'somewhere';
const REPO = 'github.com/username/private-repo';
 
const remote = `https://${USER}:${PASS}@${REPO}`;
 
simpleGit()
   .clone(remote)
   .then(() => console.log('finished'))
   .catch((err) => console.error('failed: ', err));

确保在使用此机制进行身份验证时不要启用调试日志记录
确保密码不会被记录到标准输出中。

环境变量

传递一个或多个环境变量给由其生成的子进程 simple-git with the .env 方法 which
支持传入一个名称=值的键值对对象，或者一次设置一个变量:

1
2
3
4
5
6
7
8
9
10
11
12
13
const GIT_SSH_COMMAND = 'ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no';
 
simpleGit()
   .env('GIT_SSH_COMMAND', GIT_SSH_COMMAND)
   .status((err, status) => {
      /*  */
   });
 
simpleGit()
   .env({ ...process.env, GIT_SSH_COMMAND })
   .status()
   .then((status) => {})
   .catch((err) => {});

注意 - 在将环境变量传递给子进程时，这些变量将替换标准变量 process.env
变量，上面的例子基于创建了一个新对象 process.env but with the GIT_SSH_COMMAND 属性已添加。

异常处理

When the git 进程以非零状态退出（或在某些情况下如） merge git进程以一个退出
成功零代码但合并时存在冲突，任务将拒绝此操作 GitError 当没有的时候
可用的解析器来处理错误或一个
GitResponseError 当有之时。

看看这个 err 回调的属性:

1
2
3
4
5
git.merge((err, mergeSummary) => {
   if (err.git) {
      mergeSummary = err.git; // the failed mergeSummary
   }
});

用try/catch在异步代码中捕获错误:

1
2
3
4
5
6
7
8
9
10
try {
   const mergeSummary = await git.merge();
   console.log(`Merged ${mergeSummary.merges.length} files`);
} catch (err) {
   // err.message - the string summary of the error
   // err.stack - some stack trace detail
   // err.git - where a parser was able to run, this is the parsed content
 
   console.error(`Merge resulted in ${err.git.conflicts.length} conflicts`);
}

用一个来捕获错误 .catch 关于承诺:

1
2
3
4
5
6
7
8
9
10
const mergeSummary = await git.merge().catch((err) => {
   if (err.git) {
      return err.git;
   } // the unsuccessful mergeSummary
   throw err; // some other error, so throw
});
 
if (mergeSummary.failed) {
   console.error(`Merge resulted in ${mergeSummary.conflicts.length} conflicts`);
}

在TypeScript中可用类型错误

1
2
3
4
5
6
7
8
9
10
11
12
13
import { simpleGit, MergeSummary, GitResponseError } from 'simple-git';
try {
   const mergeSummary = await simpleGit().merge();
   console.log(`Merged ${mergeSummary.merges.length} files`);
} catch (err) {
   // err.message - the string summary of the error
   // err.stack - some stack trace detail
   // err.git - where a parser was able to run, this is the parsed content
   const mergeSummary: MergeSummary = (err as GitResponseError<MergeSummary>).git;
   const conflicts = mergeSummary?.conflicts || [];
 
   console.error(`Merge resulted in ${conflicts.length} conflicts`);
}

故障排除 / 常见问题

启用日志记录

See the debug logging guide 用于日志记录的示例和方法
利用 debug 图书馆的程序接口
在您的应用中。

启用详细日志记录

See the debug logging guide for
使用带有完整详细日志记录选项的列表
debug 图书馆。

每个命令都会返回ENOENT错误信息

有几个可能的原因:

  • git 不可用作为运行主程序用户的二进制文件 node 可以使用自定义路径指向二进制文件
    with the .customBinary(...) API选项。

  • 传递给main的当前工作目录 simple-git 函数不可访问，请检查其是否具有读/写权限
    by the user running the node 处理。这个库使用
    @kwsites/file-exists 验证工作目录是否存在
    to output its logs add @kwsites/file-exists 对你 DEBUG 环境变量。 例如:

    DEBUG=@kwsites/file-exists,simple-git node ./your-app.js

日志格式失败

的特性 git log 是通过以下方式获取的 --pretty=format 根据不同的标记支持论点
在版本的方面 git - 例如的 %D 用于显示在git中添加的引用的标记 2.2.3适用于任何版本
在那之前，请确保你提供的格式对象包含受你所使用的 Git 版本支持的属性
正在使用。

如需了解支持的标记的更多详情，请参见
official git log documentation

日志响应属性顺序错误

The properties of git.log 通过字符序列获取 ò 作为分隔符。如果你的提交信息
使用此序列，提供定制内容 splitter 在选项中，例如: git.log({ splitter: '💻' })

拉取/差异/合并摘要响应不识别任何文件

  • 启用环境变量以开启详细日志 DEBUG=simple-git:task:*,simple-git:output:*
  • 检查一下 output (for example: simple-git:output:diff:1 [stdOut] 1 file changed, 1 insertion(+))
  • Check the stdOut 输出与您直接在终端中运行该命令时看到的结果相同
  • 检查响应中使用的是英语区域的语言

在某些情况下 git 将在输出中显示进度信息或在错误状态下的附加详细信息
stdErr 这将有助于调试您的问题，这些信息也包含在详细日志中。

遗留节点版本

From v3.x, simple-git 将停止对的支持 node.js 版本10或以下，用于在较低版本的node中使用
可能导致以下错误：:

  • Object.fromEntries is not a function
  • Object.entries is not a function
  • message.flatMap is not a function

为了解决这些问题，请升级到较新的版本 node.js 或者确保您使用了必要的polyfills
来自 core-js - 看见 Legacy Node Versions.

示例

使用路径规范来限制任务的范围

如果 simple-git API 没有明确限制正在运行的任务范围（例如: git.add() 需要文件进行
将被添加，但 git.status() 将会针对整个仓库，添加一个 pathspec 使用尾随选项执行命令:

1
2
3
4
5
6
import { simpleGit, pathspec } from "simple-git";
 
const git = simpleGit();
const wholeRepoStatus = await git.status();
const subDirStatusUsingOptArray = await git.status([pathspec('sub-dir')]);
const subDirStatusUsingOptObject = await git.status({ 'sub-dir': pathspec('sub-dir') });

异步等待

1
2
3
4
5
6
7
8
9
10
11
12
13
async function status(workingDir) {
   let statusSummary = null;
   try {
      statusSummary = await simpleGit(workingDir).status();
   } catch (e) {
      // handle the error
   }
 
   return statusSummary;
}
 
// using the async function
status(__dirname + '/some-repo').then((status) => console.log(status));

如果有必要，请初始化一个git仓库

1
2
3
4
5
6
7
8
9
const git = simpleGit(__dirname);
 
git.checkIsRepo()
   .then((isRepo) => !isRepo && initialiseRepo(git))
   .then(() => git.fetch());
 
function initialiseRepo(git) {
   return git.init().then(() => git.addRemote('origin', 'https://some.git.repo'));
}

更新仓库并获取标签列表

1
2
3
4
5
6
7
8
9
10
simpleGit(__dirname + '/some-repo')
   .pull()
   .tags((err, tags) => console.log('Latest available tag: %s', tags.latest));
 
// update repo and when there are changes, restart the app
simpleGit().pull((err, update) => {
   if (update && update.summary.changes) {
      require('child_process').exec('npm restart');
   }
});

开始一个新仓库

1
2
3
4
5
6
simpleGit()
   .init()
   .add('./*')
   .commit('first commit!')
   .addRemote('origin', 'https://github.com/user/repo.git')
   .push('origin', 'master');

推送使用 -u

1
2
3
4
5
simpleGit()
   .add('./*')
   .commit('first commit!')
   .addRemote('origin', 'some-repo-url')
   .push(['-u', 'origin', 'master'], () => console.log('done'));

将长时间运行的任务输出到控制台

See progress events 关于更多细节
记录进度更新。

1
2
3
4
5
6
const git = simpleGit({
   progress({ method, stage, progress }) {
      console.log(`git.${method} ${stage} stage ${progress}% complete`);
   },
});
git.checkout('https://github.com/user/repo.git');

更新仓库并在有更改时打印消息，重启应用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// when using a chain
simpleGit()
   .exec(() => console.log('Starting pull...'))
   .pull((err, update) => {
      if (update && update.summary.changes) {
         require('child_process').exec('npm restart');
      }
   })
   .exec(() => console.log('pull done.'));
 
// when using async and optional chaining
const git = simpleGit();
console.log('Starting pull...');
if ((await git.pull())?.summary.changes) {
   require('child_process').exec('npm restart');
}
console.log('pull done.');

获取完整的提交列表，然后仅查看0.11.0和0.12.0标签之间的内容

1
2
console.log(await simpleGit().log());
console.log(await simpleGit().log('0.11.0', '0.12.0'));

设置作者的本地配置，然后为单个提交设置作者

1
2
3
4
5
6
7
simpleGit()
   .addConfig('user.name', 'Some One')
   .addConfig('user.email', 'some@one.com')
   .commit('committed as "Some One"', 'file-one')
   .commit('committed as "Another Person"', 'file-two', {
      '--author': '"Another Person "',
   });

获取远程仓库

1
2
3
4
5
6
simpleGit().listRemote(['--get-url'], (err, data) => {
   if (!err) {
      console.log('Remote url for repository at ' + __dirname + ':');
      console.log(data);
   }
});

免责声明 © 2025 - 虚宝阁

本站部分源码来源于网络，版权归属原开发者，用户仅获得使用权。依据《计算机软件保护条例》第十六条，禁止：

  • 逆向工程破解技术保护措施
  • 未经许可的分发行为
  • 去除源码中的原始版权标识

※ 本站源码仅用于学习和研究，禁止用于商业用途。如有侵权, 请及时联系我们进行处理。

侵权举报请提供： 侵权页面URL | 权属证明模板

响应时效：收到完整材料后48小时内处理

相关推荐

Claudable：基于 Next.js 框架的网站生成器

把你用自然语言描述的应用想法，直接变成可以运行的网站代码。Claudable 背后依赖强大的 AI 编程助手，主要是 Claude Code，也支持 Cursor CLI 来理解你的需求并生成代码。你不需要懂复杂的 API 设置、数据库配置或者部署流程：用简单的语言告诉 Claudable 你想要什么应用。

2525 2025-09-15

langchainjs： 用语言模型构建模块化AI应用

帮助你用大型语言模型（如 GPT）构建模块化智能应用。 想做 AI 代理？做会读 PDF 的问答机器人？轻松搞定。 简直是生成式 AI 的乐高积木。

15824 2025-10-01

TensorFlow.js： javascript界的机器学习大神

TensorFlow.js 把机器学习能力带进了 JavaScript。训练模型、运行推理，甚至搞实时 AI Web 或移动端、Node 后端。谷歌用，创业公司用，爱好者用，用过都说好。

18976 2025-10-01

langchain LLM应用的胶水框架

把大模型和数据库、API、知识库结合起来的胶水框架！它像“乐高积木”一样，把各种AI组件拼起来，让你轻松开发聊天机器人、问答系统、智能助手，不用从零写代码。

116885 2025-09-13

refine： 企业级React后台框架

这是一个专为构建 CRUD（增删改查）应用设计的 Web 框架，只需一行命令即可生成项目骨架，内置登录、列表、详情、编辑页面等功能。业务逻辑与 UI、路由完全解耦，可灵活集成 Ant Design、Material-UI 等设计系统，适用于快速开发管理后台、仪表盘、内部工具和 B2B 应用。

32865 2025-09-13

n8n： AI自动化工作流工具

基于节点的自动化工作流工具，能帮助用户轻松创建和管理复杂的自动化流程，无需编写大量代码。并且内置了AI能力，支持 400+ 应用和服务！

146989 2025-09-26

fastapi： Python web api 框架

一个基于 Python 3.6+ 版本的异步 WEB 应用框架，使用 Python 类型注解构建 web API 。主要特点有: 高性能：与 Node JS 和 Go 相当。 编码快：将开发功能的速度提高 2~3 倍。 Bug少：减少大约 40% 的由开发人员导致的错误。 直观：强大的编辑器支持，可智能感知和补全代码。 简单：易于学习和使用，减少文档阅读时间。 简短：尽量减少代码重复。 健壮：获得可用于生产的代码，具有自动交互文档。 基于标准：基于 OpenAPI 和 JSON Schema 。

90539 2025-09-16

pydoll： 无需 WebDriver 的浏览器自动化 Python 库

用于自动化操作 Chromium 内核浏览器的 Python 库。它通过原生 DevTools 协议（CDP）直接控制浏览器，无需依赖 WebDriver，支持绕过验证码、模拟真人交互、网页截图等功能。

5623 2025-10-04

ant-design-vue-pro

👨🏻‍💻👩🏻‍💻 Use Ant Design Vue like a Pro! (vue2)

10932 2025-09-20

adm-zip： nodejs 中 zip文件压缩神器

ADM - ZIP是用于NodeJS的纯JavaScript实现的ZIP数据压缩库。可通过npm安装，无其他NodeJS依赖。能解压、压缩文件，更新ZIP内容。更多详情查看wiki。

2138 2025-08-28

OpenIsle- 轻量级的Java开源社区系统

这是一个基于 Spring Boot 和 Vue3 构建的开源自由社区系统，定位为轻量级的 Discourse。它完全开源、可二次开发，支持白名单邀请、自定义标签、实时通知等功能。

393 2025-09-13

pyscript： 直接在浏览器中用 Python 创建应用程序

在 HTML 文件中直接使用 Python 编程语言，像 JavaScript 文件一样引入和执行 Python 代码，支持更小的 MicroPython、常见第三方库和操作页面元素等功能，适用于快速创建交互的数据可视化、网站原型和在线教育等 Web 应用场景。

18589 2025-10-04

热 榜

scira： AI 驱动搜索引擎

51018

image-compressor： 前端图片压缩库

21018

squish： 基于浏览器的图像压缩工具

9908

AirBattery： 隔空查看苹果设备电量的 Mac 工具

36031

Seelen-UI： 高度可定制的 Windows 桌面美化工具

17024

pyscript： 直接在浏览器中用 Python 创建应用程序

22267

pydoll： 无需 WebDriver 的浏览器自动化 Python 库

14772

pdfplumber： 轻松提取 PDF 文本和表格的 Python 库

24967

暂无数据

友情链接

Github-最大的开源仓库
Github
Gitee-国内开源仓库, github国内镜像仓库
Gitee