Package Exports

git-client
git-client/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (git-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

npm install git-client

Basic Usage

Simple Command Execution

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

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

Using Named Methods

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

// 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:

// 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

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

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:

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

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

Running Tests

npm test

License

MIT License - see the LICENSE file for details.

Credits

Created and maintained by Jarvus Innovations.