Socket
Socket
Sign inDemoInstall

simple-git

Package Overview
Dependencies
Maintainers
2
Versions
259
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

simple-git - npm Package Compare versions

Comparing version 3.0.2 to 3.0.3

9

CHANGELOG.md
# Changelog
### [3.0.3](https://www.github.com/steveukx/git-js/compare/repo-v3.0.2...repo-v3.0.3) (2022-01-20)
### Bug Fixes
* allow branches without labels ([07a1388](https://www.github.com/steveukx/git-js/commit/07a138808fb0b78068da83030698a957e567541c))
* implement v3 deprecations ([ed6d18e](https://www.github.com/steveukx/git-js/commit/ed6d18e88a6a4f9fd18d4733a94b491e0e9e3ba1))
* publish v3 as `latest` ([5db4434](https://www.github.com/steveukx/git-js/commit/5db4434d00acba560fe2569c04f9813cde026468))
### [3.0.2](https://www.github.com/steveukx/git-js/compare/repo-v3.0.1...repo-v3.0.2) (2022-01-18)

@@ -4,0 +13,0 @@

7

package.json

@@ -5,3 +5,3 @@ {

"private": false,
"version": "3.0.2",
"version": "3.0.3",
"author": "Steve King <steve@mydev.co>",

@@ -53,6 +53,3 @@ "contributors": [

},
"types": "./typings/index.d.ts",
"publishConfig": {
"tag": "canary"
}
"types": "./typings/index.d.ts"
}

233

readme.md

@@ -6,2 +6,8 @@ # Simple Git

# Version 3 - Out Now
From v3 of `simple-git` you can now import as an ES module, Common JS module or as TypeScript with bundled type
definitions. Upgrading from v2 will be seamless for any application not relying on APIs that were marked as deprecated
in v2 (deprecation notices were logged to `stdout` as `console.warn` in v2).
# Installation

@@ -20,3 +26,3 @@

Include into your JavaScript app using commons js:
Include into your JavaScript app using common js:

@@ -36,10 +42,12 @@ ```javascript

```javascript
import simpleGit, {CleanOptions} from 'simple-git';
import simpleGit, { CleanOptions } from 'simple-git';
simpleGit().clean(CleanOptions.FORCE);
```
Include in a TypeScript app using:
Include in a TypeScript app using the bundled type definitions:
```typescript
import simpleGit, {SimpleGit, CleanOptions} from 'simple-git';
import simpleGit, { SimpleGit, CleanOptions } from 'simple-git';
const git: SimpleGit = simpleGit().clean(CleanOptions.FORCE);

@@ -104,3 +112,3 @@ ```

## Using task promises
## Using Task Promises

@@ -112,3 +120,2 @@ Each task in the API returns the `simpleGit` instance for chaining together multiple tasks, and each

```javascript
import simpleGit from 'simple-git';
const git = simpleGit();

@@ -124,3 +131,3 @@

## Catching errors in async code
### Catching errors in async code

@@ -152,3 +159,3 @@ To catch errors in async code, either wrap the whole chain in a try/catch:

## Using task callbacks
## Using Task Callbacks

@@ -159,3 +166,2 @@ In addition to returning a promise, each method can also be called with a trailing callback argument

```javascript
const simpleGit = require('simple-git');
const git = simpleGit();

@@ -176,5 +182,4 @@ git.init(onInit).addRemote('origin', 'git@github.com:steveukx/git-js.git', onRemoteAdd);

For type details of the response for each of the tasks, please see the [TypeScript definitions](https://github.com/steveukx/git-js/blob/main/simple-git/typings/simple-git.d.ts).
For type details of the response for each of the tasks, please see the [TypeScript definitions](https://github.com/steveukx/git-js/blob/main/simple-git/typings/simple-git.d.ts).
# API

@@ -387,3 +392,3 @@

# How to Specify Options
## How to Specify Options

@@ -393,3 +398,3 @@ Where the task accepts custom options (eg: `pull` or `commit`), these can be supplied as an object, the keys of which

## Options as an Object
### Options as an Object

@@ -407,3 +412,3 @@ When the value of the property in the options object is a `string`, that name value

## Options as an Array
### Options as an Array

@@ -420,43 +425,20 @@ Options can also be supplied as an array of strings to be merged into the task's commands

Major release 2.x changes the way the queue of tasks are handled to use promises internally and makes
available the `.then` and `.catch` methods for integrating with promise consumers or async await.
Major release 3.x changes the packaging of the library, making it consumable as a CommonJS module, ES module as well as
with TypeScript (see [usage](#usage) above). The library is now published as a single file, so please ensure your
application hasn't been making use of non-documented APIs by importing from a sub-directory path.
TypeScript is used by default for all new code, allowing for auto-generated type definitions and a phased
re-write of the library rather than a big-bang.
See also:
For a per-release overview of changes, see the [changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md).
- [release notes v2](https://github.com/steveukx/git-js/blob/main/docs/RELEASE-NOTES-V2.md)
## 2.x Upgrade Notes
When upgrading to release 2.x from 1.x, see the [changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md) for the release 2.0.0
# Recently Deprecated / Altered APIs
- ~~2.25.0 depends on Node.js version 12 or above, for use in lower versions of node.js ensure you are also
importing the necessary polyfills from `core-js`, see [Legacy Node Versions](https://github.com/steveukx/git-js/blob/main/docs/LEGACY_NODE_VERSIONS.md)~~
_this change has been reverted in 2.30.0 and will be postponed until version 3.x_.
- 2.13.0 `.push` now returns a [PushResult](https://github.com/steveukx/git-js/blob/main/simple-git/typings/response.d.ts) parsed representation of the response.
- 2.11.0 treats tasks chained together as atomic, where any failure in the chain prevents later tasks from
executing and tasks called from the root `git` instance as the origin of a new chain, and able to be
[run in parallel](#concurrent--parallel-requests) without failures impacting one anther. Prior to this
version, tasks called on the root `git` instance would be cancelled when another one failed.
- 2.7.0 deprecates use of `.silent()` in favour of using the `debug` library - see the
[debug logging guide](https://github.com/steveukx/git-js/blob/main/docs/DEBUG-LOGGING-GUIDE.md) for further details.
- 2.6.0 introduced `.then` and `.catch` as a way to chain a promise onto the current step of the chain.
Importing from `simple-git/promise` instead of just `simple-git` is no longer required and is actively discouraged.
For the full history see the [changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md);
# Concurrent / Parallel Requests
When the methods of `simple-git` are chained together, they create an execution chain that will run in series,
useful for when the tasks themselves are order-dependent, eg:
When the methods of `simple-git` are chained together, they create an execution chain that will run in series, useful
for when the tasks themselves are order-dependent, eg:
```typescript
const git = simpleGit();
git.init().addRemote('origin', 'https://some-repo.git').fetch();
simpleGit()
.init()
.addRemote('origin', 'https://some-repo.git')
.fetch();
```

@@ -474,4 +456,4 @@

const results = await Promise.all([
git.raw('rev-parse', '--show-cdup').catch(swallow),
git.raw('rev-parse', '--show-prefix').catch(swallow),
git.raw('rev-parse', '--show-cdup').catch(swallow),
git.raw('rev-parse', '--show-prefix').catch(swallow),
]);

@@ -494,15 +476,14 @@ function swallow (err) { return null }

When no suitable wrapper exists in the interface for creating a request, it is possible to run a command directly
When no suitable wrapper exists in the interface for creating a request, run the command directly
using `git.raw([...], handler)`. The array of commands are passed directly to the `git` binary:
```javascript
const git = require('simple-git');
const path = '/path/to/repo';
const commands = [ 'config', '--global', 'advice.pushNonFastForward', 'false' ];
const commands = ['config', '--global', 'advice.pushNonFastForward', 'false'];
// using an array of commands
git(path).raw(commands, (err, result) => {
// 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
// err is null unless this command failed
// result is the raw output of this command

@@ -512,3 +493,3 @@ });

// using a var-args of strings and awaiting rather than using the callback
const result = await git(path).raw(...commands);
const result = await simpleGit(path).raw(...commands);
```

@@ -525,6 +506,5 @@

const git = require('simple-git');
const remote = `https://${USER}:${PASS}@${REPO}`;
const remote = `https://${ USER }:${ PASS }@${ REPO }`;
git().silent(true)
simpleGit()
.clone(remote)

@@ -536,3 +516,4 @@ .then(() => console.log('finished'))

Be sure to enable silent mode to prevent fatal errors from being logged to stdout.
Be sure to not enable debug logging when using this mechanism for authentication
to ensure passwords aren't logged to stdout.

@@ -547,55 +528,20 @@ # Environment Variables

const git = require('simple-git');
git()
simpleGit()
.env('GIT_SSH_COMMAND', GIT_SSH_COMMAND)
.status((err, status) => { /* */ })
git().env({ ...process.env, GIT_SSH_COMMAND })
simpleGit().env({...process.env, GIT_SSH_COMMAND})
.status()
.then(status => { })
.catch(err => {});
```
Note - when passing environment variables into the child process, these will replace the standard `process.env`
variables, the example above creates a new object based on `process.env` but with the `GIT_SSH_COMMAND` property
added.
variables, the example above creates a new object based on `process.env` but with the `GIT_SSH_COMMAND` property added.
# TypeScript
To import with TypeScript:
```typescript
import simpleGit, { SimpleGit, StatusResult } from 'simple-git';
const git: SimpleGit = simpleGit();
const status: StatusResult = await git.status();
```
# Promise and async compatible
For each task run, the return is the same `SimpleGit` instance for ease of building
a series of tasks that all run sequentially and are treated as atomic (ie: if any
step fails, the later tasks are not attempted).
To work with promises (either directly or as part of async/await), simply call the
function as before:
```javascript
const simpleGit = require('simple-git');
const git = simpleGit();
// async / await
const status = await git.status();
// promise
git.status().then(result => {...});
```
# Exception Handling
When the `git` process exits with a non-zero status (or in some cases like `merge` the git
process exits with a successful zero code but there are conflicts in the merge) the task
will reject with a `GitError` when there is no available parser to handle the error or a
When the `git` process exits with a non-zero status (or in some cases like `merge` the git process exits with a
successful zero code but there are conflicts in the merge) the task will reject with a `GitError` when there is no
available parser to handle the error or a
`GitResponseError` for when there is.

@@ -617,11 +563,11 @@

try {
const mergeSummary = await git.merge();
console.log(`Merged ${ mergeSummary.merges.length } files`);
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
// 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`);
console.error(`Merge resulted in ${ err.git.conflicts.length } conflicts`);
}

@@ -688,3 +634,3 @@ ```

to output its logs add `@kwsites/file-exists` to your `DEBUG` environment variable. eg:
`DEBUG=@kwsites/file-exists,simple-git node ./your-app.js`

@@ -719,4 +665,4 @@

From `v3.x`, `simple-git` will drop support for `node.js` version 10 or below, to use in a lower version of
node will result in errors such as:
From `v3.x`, `simple-git` will drop support for `node.js` version 10 or below, to use in a lower version of node will
result in errors such as:

@@ -727,8 +673,7 @@ - `Object.fromEntries is not a function`

To resolve these issues, either upgrade to a newer version of node.js or ensure you are using the necessary
polyfills from `core-js` - see [Legacy Node Versions](https://github.com/steveukx/git-js/blob/main/docs/LEGACY_NODE_VERSIONS.md).
To resolve these issues, either upgrade to a newer version of node.js or ensure you are using the necessary polyfills
from `core-js` - see [Legacy Node Versions](https://github.com/steveukx/git-js/blob/main/docs/LEGACY_NODE_VERSIONS.md).
# Examples
### using a pathspec to limit the scope of the task

@@ -750,7 +695,5 @@

async function status (workingDir) {
const git = require('simple-git');
let statusSummary = null;
try {
statusSummary = await git(workingDir).status();
statusSummary = await simpleGit(workingDir).status();
}

@@ -760,3 +703,3 @@ catch (e) {

}
return statusSummary;

@@ -772,3 +715,2 @@ }

```javascript
const simpleGit = require('simple-git');
const git = simpleGit(__dirname);

@@ -789,3 +731,3 @@

```javascript
require('simple-git')(__dirname + '/some-repo')
simpleGit(__dirname + '/some-repo')
.pull()

@@ -795,5 +737,5 @@ .tags((err, tags) => console.log("Latest available tag: %s", tags.latest));

// update repo and when there are changes, restart the app
require('simple-git')()
simpleGit()
.pull((err, update) => {
if(update && update.summary.changes) {
if (update && update.summary.changes) {
require('child_process').exec('npm restart');

@@ -807,3 +749,3 @@ }

```javascript
require('simple-git')()
simpleGit()
.init()

@@ -819,3 +761,3 @@ .add('./*')

```javascript
require('simple-git')()
simpleGit()
.add('./*')

@@ -829,15 +771,12 @@ .commit("first commit!")

See [progress events](https://github.com/steveukx/git-js/blob/main/docs/PLUGIN-PROGRESS-EVENTS.md) for more details on
logging progress updates.
```javascript
require('simple-git')()
.outputHandler((bin, stdout, stderr, args) => {
stdout.pipe(process.stdout);
stderr.pipe(process.stderr);
// the name of the binary used, defaults to git, see customBinary for more info
assert.equal(bin, 'git');
// all other arguments passsed to the binary
assert.deepEqual(args, ['checkout', 'https://github.com/user/repo.git']);
})
.checkout('https://github.com/user/repo.git');
const git = simpleGit({
progress ({method, stage, progress}) {
console.log(`git.${ method } ${ stage } stage ${ progress }% complete`);
}
});
git.checkout('https://github.com/user/repo.git');
```

@@ -849,6 +788,6 @@

// when using a chain
require('simple-git')()
simpleGit()
.exec(() => console.log('Starting pull...'))
.pull((err, update) => {
if(update && update.summary.changes) {
if (update && update.summary.changes) {
require('child_process').exec('npm restart');

@@ -860,4 +799,4 @@ }

// when using async and optional chaining
const git = require('simple-git')()
console.log('Starting pull...')
const git = simpleGit();
console.log('Starting pull...');
if ((await git.pull())?.summary.changes) {

@@ -867,3 +806,2 @@ require('child_process').exec('npm restart');

console.log('pull done.');
```

@@ -874,5 +812,4 @@

```javascript
require('simple-git')()
.log((err, log) => console.log(log))
.log('0.11.0', '0.12.0', (err, log) => console.log(log));
console.log(await simpleGit().log());
console.log(await simpleGit().log('0.11.0', '0.12.0'));
```

@@ -883,7 +820,7 @@

```javascript
require('simple-git')()
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 <another@person.com>"' });
.commit('committed as "Another Person"', 'file-two', {'--author': '"Another Person <another@person.com>"'});
```

@@ -894,3 +831,3 @@

```javascript
require('simple-git')()
simpleGit()
.listRemote(['--get-url'], (err, data) => {

@@ -897,0 +834,0 @@ if (!err) {

cjs/index.js

Sorry, the diff of this file is too big to display

cjs/index.js.map

Sorry, the diff of this file is not supported yet

esm/index.js

Sorry, the diff of this file is too big to display

esm/index.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc