simple-git
4.1.0 · 16 Nov 2026MIT15.5M / weekRepositorynpmAtom feed
278 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.
- 4.x · latest line
4.1.0
16 Nov 2026Summary· from the note as AI read it
Upgrade: this release fixes a security issue.
Minor Changes
Add the
allowConfigandstrictoptions. Configuration keys outside the built-in list of known-safe keys
(SAFE_CONFIG_KEYS) and the keys named inallowConfignow emit a one-offSIMPLE_GIT_UNLISTED_CONFIGwarning,
or are rejected whenstrict: trueis set. Known-unsafe keys can now be permitted individually throughallowConfig, and environment variables throughallowEnvironment, deprecating theunsafe.allowUnsafe*options
that only covered configuration keys or environment variables (they continue to work as before).The custom binary (the first string of the
binaryoption orgit.customBinary()) may now contain spaces
when it looks like a path to a file, for exampleC:\Program Files\Git\bin\git.exe. The value must include
a path separator and no part of the path may start or end with a space. The prefix (the optional second string)
remains limited to the existing restricted character set, as it is passed to the binary as its first argument.When the recommended checks are enabled (with
unsafe.recommended: trueorstrict: true),HOMEandXDG_CONFIG_HOME
supplied through.env()with a value other than the one inprocess.envrequireallowUnsafeConfigPaths
(or naming them inallowEnvironment), asgitreads the global configuration from$HOME/.gitconfigand$XDG_CONFIG_HOME/git/configin the same way asGIT_CONFIG_GLOBAL. Passing the inherited value through is unaffected,
and neither is removed from the inherited environment.parseEnvaccepts the inherited environment as an optional second argument, used to compareHOMEandXDG_CONFIG_HOMEagainst.isGuardedEnvKeyis now exported from@simple-git/argv-parser, identifying the environment variables
(GIT_*and the othersgitreads, such asEDITORandPAGER) thatsimple-gitremoves from an inherited
environment.Settle on the use of
strictto refer to thesimpleGitconfiguration setting to enable strict controls,
applying to both Git impacting environment variables and writing to the Git config.Use of the
strictmode also implies the use ofunsafe.recommendedVulnerability reports:
With thanks to @manus-pi, @manus-use, @ba-am, @mspiq, @hoseinenddev, @freyesperales, @dalberrt,
@zer0d4y5, @gamster01, @humaneBicycle, @Hama1cco, @eliteaja11-dev, @Cone-Tester, @Figo5, @MalwareEZ,
@zachariah-mithani, @shaswata56, @Akokonunes for submitting CVE proposals that contributed to these changes.closing the loop on any configuration setting ending with
.cmdorcommandunder the catch-allallowUnsafeCommandBinariessetting (only enforced with the newunsafe.recommendedoption, orstrict), and blockinggpg.ssh.defaultKeyCommandunderallowUnsafeGpgProgram.allowUnsafePagerwill now catch setting a custom binary ingit grep --open-files-in-pager.allowUnsafePagernow also coversinteractive.diffFilter, the shell command thatgit add -pand the other--patchcommands pipe their diff through.new (deprecated on arrival, prefer
allowConfig)allowUnsafeSendEmailConfigoption covering thesendemail.*keys thatgit send-emailruns as commands, reads as files or uses to turn off certificate verification (sendmailCmd,toCmd,ccCmd,headerCmd,smtpServer,smtpServerOption,smtpSSLCertPath,smtpSSLClientCert,smtpSSLClientKey,aliasesFileandmailmap.file, including their per-identitysendemail.<identity>.*variants), and theimap.tunnel,imap.hostandimap.sslVerifykeys used bygit imap-send.new (deprecated on arrival, prefer
allowConfig)allowUnsafeWebServerConfigoption covering theinstaweb.httpd,instaweb.modulePathandinstaweb.gitwebDirkeys used bygit instaweb.new (deprecated on arrival, prefer
allowConfig)allowUnsafeBrowseroption covering thebrowser.<tool>.path,browser.<tool>.cmd,man.<tool>.pathandman.<tool>.cmdkeys used bygit helpandgit instawebto open a browser or man page viewer.browser.<tool>.cmdandman.<tool>.cmdwere previously covered byallowUnsafeCommandBinaries.new (deprecated on arrival, prefer
allowConfig)allowUnsafeSignatureTrustoption coveringgpg.ssh.allowedSignersFile,gpg.ssh.revocationFileandgpg.minTrustLevel, which decide which signatures pass verification.allowUnsafePacknow blocks--execfor every command other thanrebase, as it names the remote program forpush,send-pack,fetch-pack,archive --remoteandls-remote(previously onlypush).new
allowUnsafeConfigRenameoption blockinggit config --rename-section/git config rename-section, which could move keys written under a harmless section name (eg:foo.fsmonitor) into one that runs commands (core.fsmonitor).allowUnsafeExecnow also covers thegit filter-branchoptions that run a shell command:--setup,--env-filter,--tree-filter,--index-filter,--parent-filter,--msg-filter,--commit-filterand--tag-name-filter.allowUnsafeDiffExternalnow also coversdifftool.<tool>.path, matchingmergetool.<tool>.pathunderallowUnsafeMergeDriver.
Patch Changes
Add a security policy describing which inputs are safe for untrusted data.
4.0.2
26 Sep 2026Add
VISUALenvironment variable to set ofallowUnsafeEditorenvironment variables.
Patch Changes
Add
VISUALenvironment variable to set ofallowUnsafeEditorenvironment variables.
4.0.1
25 Sep 2026Prepare package.json before publishing.
4.0.0
25 Sep 2026- Breaking
Major upgrade to v4. In this version:
// v3 - previously supported imports import simpleGit from "simple-git"; import { gitP } from "simple-git"; import simpleGit from "simple-git/promise"; const simpleGit = require("simple-git"); // v4 - consolidates to a single supported import import { simpleGit } from "simple-git"; const { simpleGit } = require("simple-git");// v3 - allowed the use of unambiguous long-form options git.raw("clone", "--conf=user.name=me", "..."); // v4 - requires full option names, abbreviated option names will now throw a GitConfigurationError git.raw("fetch", "--config=user.name=me", "...");// v3 process.env.FOO = "bar"; process.env.GIT_TEMPLATE_DIR = "./some/path"; simpleGit().raw("clone"); // git child process can see both environment variables // v4 process.env.FOO = "bar"; process.env.GIT_TEMPLATE_DIR = "./some/path"; simpleGit().raw("clone"); // git child process now sees only FOO simpleGit({ // explicitly allow the named environment variable so it can pass through. allowEnvoronment: ["GIT_TEMPLATE_DIR"], // and enable the use of an unsafe behaviour unsafe: { allowUnsafeTemplateDir: true }, });// v3 used a single opt-in to potential unsafe actiity simpleGit({ unsafe: { allowUnsafeTemplateDir: true } }) .env({ GIT_TEMPLATE_DIR: "./foo" }) .init(); // v4 uses a double opt-in, allow the behaviour and the mechanism simpleGit({ allowEnvoronment: ["GIT_TEMPLATE_DIR"], unsafe: { allowUnsafeTemplateDir: true }, }) .env({ GIT_TEMPLATE_DIR: "./foo" }) .init(); Support one-shot stdin via
git.input(data)(stringorBuffer).Add
allowUnsafeExecdetection torebase -xandrebase --exec.
Major Changes
- Breaking
Major upgrade to v4. In this version:
Removed previously available default export, now uses a consistently named
simpleGitexport.Removed previously deprecated import
simple-git/promise(change to using the mainsimple-gitimport).Removed legacy
gitPexport (change to using the mainsimpleGitexport).
// v3 - previously supported imports import simpleGit from "simple-git"; import { gitP } from "simple-git"; import simpleGit from "simple-git/promise"; const simpleGit = require("simple-git"); // v4 - consolidates to a single supported import import { simpleGit } from "simple-git"; const { simpleGit } = require("simple-git");Prevents the use of abbreviated long-form
gitoptions:
// v3 - allowed the use of unambiguous long-form options git.raw("clone", "--conf=user.name=me", "..."); // v4 - requires full option names, abbreviated option names will now throw a GitConfigurationError git.raw("fetch", "--config=user.name=me", "...");Ambient environment variables are filtered before passing into the
gitchild process.
// v3 process.env.FOO = "bar"; process.env.GIT_TEMPLATE_DIR = "./some/path"; simpleGit().raw("clone"); // git child process can see both environment variables // v4 process.env.FOO = "bar"; process.env.GIT_TEMPLATE_DIR = "./some/path"; simpleGit().raw("clone"); // git child process now sees only FOO simpleGit({ // explicitly allow the named environment variable so it can pass through. allowEnvoronment: ["GIT_TEMPLATE_DIR"], // and enable the use of an unsafe behaviour unsafe: { allowUnsafeTemplateDir: true }, });Explicitly supplied disallowed environment variables will throw when used.
// v3 used a single opt-in to potential unsafe actiity simpleGit({ unsafe: { allowUnsafeTemplateDir: true } }) .env({ GIT_TEMPLATE_DIR: "./foo" }) .init(); // v4 uses a double opt-in, allow the behaviour and the mechanism simpleGit({ allowEnvoronment: ["GIT_TEMPLATE_DIR"], unsafe: { allowUnsafeTemplateDir: true }, }) .env({ GIT_TEMPLATE_DIR: "./foo" }) .init();Removed content deprecated during the v2 to v3 major change
simpleGit.silent()logging is configured through environment variables in thedebugpackagesimpleGit.clearQueue()this has been a noop since v3, switch to using theabortpluginAccessing parsed properties of a
GitResponseErrorthrough a trailing callback function are available only through theerror.gitproperty (previously properties were also spread onto theerroritself with a deprecation notice).
Minor Changes
Support one-shot stdin via
git.input(data)(stringorBuffer).
Patch Changes
Add
allowUnsafeExecdetection torebase -xandrebase --exec.Parse binary rename entries without byte counts in diff summaries.
- 3.x
3.36.0
12 Apr 2026Extend known exploitable configuration keys and per-task environment variables.
Note -
ParsedVulnerabilitiesfromargv-parseris removed in favour of a readonly array ofVulnerabilityto match usage insimple-git, rolled into the newvulnerabilityCheckfor simpler access to the identified issues.Remove conflicting node:buffer import
Minor Changes
Extend known exploitable configuration keys and per-task environment variables.
Note -
ParsedVulnerabilitiesfromargv-parseris removed in favour of a readonly array ofVulnerabilityto match usage insimple-git, rolled into the newvulnerabilityCheckfor simpler access to the identified issues.
Patch Changes
Remove conflicting node:buffer import
3.35.2
6 Apr 2026Improvements for mono-repo publishing pipeline
Patch Changes
Improvements for mono-repo publishing pipeline
3.35.1
6 Apr 2026Update monorepo version handling during publish
Patch Changes
Update monorepo version handling during publish
3.35.0
6 Apr 2026Updating publish config
Minor Changes
Updating publish config
3.34.0
6 Apr 2026Revised dependency tree to add helper modules as dependencies in main
simple-gitEnhances scanning of arguments before passing on to the spawned
child_process.Caters for
-cflags prefixing thegittask (used when setting global inline config) and suffixing with either-c,--configor--config-env. Detectsgit configoperations that write to the configuration.
Minor Changes
Revised dependency tree to add helper modules as dependencies in main
simple-git
Patch Changes
Enhances scanning of arguments before passing on to the spawned
child_process.Caters for
-cflags prefixing thegittask (used when setting global inline config) and suffixing with either-c,--configor--config-env. Detectsgit configoperations that write to the configuration.
3.33.0
10 Mar 2026Use
pathspecwrappers for remote and local paths when running eithergit.cloneorgit.mirrorto
avoid leaving them less open for unexpected outcomes when passing unsanitised data into these tasks.Enhanced
git -cchecks inunsafeplugin.
3.32.3
26 Feb 2026Enhanced
protocol.allowchecks inallowUnsafeExtProtocolhandling.
3.32.2
22 Feb 2026Enhanced clone unsafe switch detection.
3.32.1
21 Feb 2026Fix regex for detecting unsafe clone options
3.32.0
21 Feb 2026Enhances the
unsafeplugin to block additional cases where the-uswitch may be disguised
along with other single character options.Use task runner for logging use of deprecated (already no-op) functions.
3.31.1
14 Feb 2026Resolve NPM publish steps
3.30.0
2 Nov 2025Correctly identify current branch name when using
git.statusin a cloned empty repo.Previously
git.statuswould report the current branch name asNo. Thank you to @MaddyGuthridge for identifying this issue.
3.29.0
30 Oct 2025Support for absolute paths on Windows when using
git.checkIngore, previously Windows would report paths with duplicate separators\\\\between directories.Following this change all paths returned from
git.checkIgnorewill be normalized throughnode:path, this should have no impact on non-windows users where thegitbinary doesn't wrap absolute paths with quotes.Support the use of
git.branch(['--show-current'])to limit the branch list to only the current branch.Change to biome for lint and format
3.28.0
6 Jun 2025Allow repeating git options like
{'--opt': ['value1', 'value2']}
3.27.0
19 Sep 2024Add
similarityto theDiffResultNameStatusFileinterface used when fetching log/diff with the--name-statusoption.Diff summary includes original name of renamed files when run wiht the
--name-statusoption.Fixes an issue with reporting name changes in the
filesarray returned bygit.status.
Minor Changes
Add
similarityto theDiffResultNameStatusFileinterface used when fetching log/diff with the--name-statusoption.Diff summary includes original name of renamed files when run wiht the
--name-statusoption.Fixes an issue with reporting name changes in the
filesarray returned bygit.status.
Patch Changes
Resolve error in log parsing when fields have empty values.
3.26.0
1 Sep 2024Upgrade build tools and typescript
3.25.0
10 Jun 2024Add support for parsing
count-objectsUpgrade dependencies and build tools
3.24.0
28 Mar 2024Enable the use of a two part custom binary
3.23.0
17 Mar 2024Bump package manager from yarn v1 to v4
Fixed a performance issue when parsing stat diff summaries
Update build tools and workflows for Yarn 4 compatibility
3.22.0
29 Dec 2023Add status to DiffResult when using --name-status
3.21.0
20 Nov 2023Add firstCommit utility interface
3.20.0
23 Sep 2023Use
pathspecingit.logto allow use of previously deleted files infileargument
3.19.1
26 Jun 2023Keep path splitter without path specs
3.19.0
24 May 2023Create a utility to append pathspec / file lists to tasks through the TaskOptions array/object
3.18.0
25 Apr 2023Add new interface for showBuffer to allow using
git showon binary files.Examples and documentation for outputHandler
3.17.0
4 Mar 2023Timeout plugin can now be configured to ignore data on either stdOut or stdErr in the git process when determining whether to kill the spawned process.
3.16.1
15 Feb 2023Fix overly permissive regex in push parser
3.16.0
16 Jan 2023- Security
Adds vulnerability detection to prevent use of
--upload-packand--receive-packwithout explicitly opting in. Support the use of
-Bin place of the default-bin checkout methodsInclude restricting the use of git push --exec with other allowUnsafePack exclusions, thanks to @stsewd for the suggestion.
3.15.1
30 Nov 2022Resolves an issue whereby non-strings can be passed into the config switch detector.
3.15.0
12 Nov 2022Disables the use of inline configuration arguments to prevent unitentionally allowing non-standard remote protocols without explicitly opting in to this practice with the new
allowUnsafeProtocolOverrideproperty having been enabled.Upgrade repo dependencies - lerna and jest
3.14.1
17 Sep 2022Add version parsing support for non-numeric patches (including "built from source" style
1.11.GIT)
3.14.0
4 Sep 2022Create the abort plugin to allow cancelling all pending and future tasks.
Add
.versionto return git version information, including whether the git binary is installed.
3.13.0
22 Aug 2022Increase the level of deprecation notices for use of
simple-git/promise, which will be fully removed in the next majorAllow supplying just one of to/from in the options supplied to git.log
Use shared test utilities bundle in simple-git tests, to enable consistent testing across packages in the future
3.12.0
8 Aug 2022Add a new configuration option to enable trimming white-space from the response to
git.raw
3.10.0
25 Jun 2022Support for importing as an ES module with TypeScript moduleResolution
node16or newer by addingsimpleGitas a named export.
3.9.0
22 Jun 2022Branches that have been checked out as a linked work tree will now be included in the
BranchSummaryoutput, with alinkedWorkTreeproperty set totruein theBranchSummaryBranch.
3.8.0
18 Jun 2022Support for additional log formats in diffSummary / log / stashList.
Adds support for the
--numstat,--name-onlyand--name-statin addition to the existing--statoption.Update CI environments to run build and test in node v18, drop node v12 now out of life.
Update
debugdependency to latest4.x
3.7.1
23 Apr 2022Resolves issue whereby renamed files no longer appear correctly in the response to
git.status.
3.7.0
19 Apr 2022Enable the use of types when loading with module-resolution
Timeout plugin no longer keeps short lived processes alive until timeout is hit
3.6.0
10 Apr 2022Show full commit hash in a
CommitResult, prior to this changegit.commitwould result in a partial hash in thecommitproperty ifcore.abbrevis unset or has a value under40. Following this change thecommitproperty will contain the full commit hash.
Minor Changes
Show full commit hash in a
CommitResult, prior to this changegit.commitwould result in a partial hash in thecommitproperty ifcore.abbrevis unset or has a value under40. Following this change thecommitproperty will contain the full commit hash.
3.5.0
29 Mar 2022- Security
Resolves potential command injection vulnerability by preventing use of
--upload-packingit.clone
3.4.0
18 Mar 2022Use null separators in git.status to allow for non-ascii file names
3.3.0
11 Mar 2022- Security
Resolves potential command injection vulnerability by preventing use of
--upload-packingit.fetch
3.2.6
17 Feb 2022Resolve issue in prePublish script
3.2.4
13 Feb 2022Release with changesets
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.