# git-client

> Promise-based git client that mostly just executes the git binary

Latest version **1.12.1** (published 2026-05-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install git-client
pnpm add git-client
yarn add git-client
bun add git-client
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.12.1 |
| Published | 2026-05-18 |
| First published | 2018-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 45 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 12 |
| Author | Chris Alfano |
| Maintainers | themightychris |
| Keywords | git, promise, typescript |

## Links

- npm: https://www.npmjs.com/package/git-client
- Repository: https://github.com/JarvusInnovations/git-client
- Issues: https://github.com/JarvusInnovations/git-client/issues
- npm.io page: https://npm.io/package/git-client

## Dependencies (4)

- [mz](https://npm.io/package/mz.md) ^2.7.0
- [rusha](https://npm.io/package/rusha.md) ^0.8.14
- [semver](https://npm.io/package/semver.md) ^7.6.3
- [async-exit-hook](https://npm.io/package/async-exit-hook.md) ^2.0.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.12.1 (latest) — 2026-05-18
- 1.11.1 — 2026-03-22
- 1.11.0 — 2026-03-21
- 1.10.1 — 2026-03-21
- 1.9.4 — 2025-10-11
- 1.9.3 — 2024-12-09
- 1.9.2 — 2024-12-09
- 1.9.1 — 2024-12-09
- 1.9.0 — 2024-12-09
- 1.8.3 — 2021-02-28
- 1.8.2 — 2021-02-16
- 1.8.0 — 2020-12-20
- 1.7.1 — 2019-11-13
- 1.7.0 — 2019-10-31
- 1.6.2 — 2019-08-04
- … 19 more at https://npm.io/package/git-client/versions

## README

# git-client

[![Tests](https://github.com/JarvusInnovations/git-client/actions/workflows/test.yml/badge.svg)](https://github.com/JarvusInnovations/git-client/actions/workflows/test.yml)
[![npm version](https://badge.fury.io/js/git-client.svg)](https://badge.fury.io/js/git-client)

A lightweight, Promise-based Git client for Node.js that executes the git binary. This library provides a clean, Promise-based interface to Git operations while maintaining the full power and flexibility of the git command line.

## Features

- Promise-based API for all Git operations
- Supports all Git commands with automatic method generation
- Flexible option handling with both short and long format support
- Spawn mode for streaming operations
- Built-in support for common Git operations
- Minimal dependencies
- Full TypeScript support with type definitions

## Requirements

- Node.js 16.x or higher
- Git installed and available in PATH

## Installation

```bash
npm install git-client
```

## Basic Usage

### Simple Command Execution

```js
const git = require('git-client');

// Get current commit hash
const hash = await git('rev-parse', 'HEAD');
```

### Using Named Methods

```js
const git = require('git-client');

// Using the revParse method
const hash = await git.revParse({ verify: true }, 'HEAD');

// Using the status method
const status = await git.status({ porcelain: true });
```

### Working with Options

```js
// Short format options
const log = await git('log', { n: 5 });

// Long format options
const diff = await git('diff', { 'word-diff': true });

// Mixed options with arguments
const show = await git('show', { format: '%H', 'no-patch': true }, 'HEAD');
```

## Advanced Usage

### Spawning Processes

Use spawn mode for operations that need streaming or real-time output:

```js
// Save file from the web
const writer = await git.hashObject({ w: true, stdin: true, $spawn: true });
const response = await axios.get('https://placekitten.com/1000/1000', { responseType: 'stream' });

// pipe data from HTTP response into git
response.data.pipe(writer.stdin);

// wait for data to finish
await new Promise((resolve, reject) => {
    response.data.on('end', () => resolve());
    response.data.on('error', () => reject());
});

// read written hash
const hash = await writer.captureOutputTrimmed();
```

### Building Trees

```js
const lines = [
    '100644 blob bc0c330151d9a2ca8d87d1ff914b87f152036b19\tkitten.jpg',
    '100644 blob 97ab63ad46e50ac4012ac9370b33878b224c4fa3\tcage.jpg'
];

const mktree = await git.mktree({ $spawn: true });
const hash = await mktree.captureOutputTrimmed(lines.join('\n')+'\n');
```

### Custom Git Directory

```js
const customGit = new git.Git({ gitDir: '/path/to/repo/.git' });
const status = await customGit.status();
```

## TypeScript Support

The library includes TypeScript definitions for all methods and options. When using TypeScript, you'll get full type checking and autocompletion for:

- Git instance configuration options
- Command execution options
- All git commands and their parameters
- Spawn mode process types
- Event handlers and callbacks

## API Reference

### Main Function

The default export is a function that executes git commands:

```js
git(command: string, ...args: Array<string|object>): Promise<string>
```

### Special Options

When passing options objects, the following special keys are supported:

- `$gitDir`: Set custom git directory
- `$workTree`: Set custom working tree
- `$indexFile`: Set custom index file
- `$spawn`: Enable spawn mode
- `$shell`: Enable shell mode
- `$nullOnError`: Return null instead of throwing on error
- `$onStdout`: Callback for stdout in spawn mode
- `$onStderr`: Callback for stderr in spawn mode
- `$env`: Object of environment variables to set on the spawned process
- `$config`: Object of `key=value` config overrides injected as `-c` flags before the subcommand (e.g. `{ $config: { 'gc.auto': '0' } }`)

### Common Methods

All git commands are available as methods. Some commonly used ones include:

- `git.status(options)`
- `git.add(options, ...files)`
- `git.commit(options, message)`
- `git.push(options)`
- `git.pull(options)`
- `git.checkout(options, ref)`
- `git.branch(options)`
- `git.merge(options, ref)`
- `git.log(options)`

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -am 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Running Tests

```bash
npm test
```

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Credits

Created and maintained by [Jarvus Innovations](https://github.com/JarvusInnovations).

---
_Source: https://npm.io/package/git-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._