v2.4.0 — Stable

.git SDK

A lightweight, type-safe JavaScript/TypeScript client for managing repositories, automating workflows, and interacting with the .git deployment pipeline.

Installation #

Install the SDK via your preferred package manager. The SDK supports Node.js 18+, Deno, and modern browsers.

npm

npm install @git/sdk

yarn

yarn add @git/sdk

pnpm

pnpm add @git/sdk

Quick Start #

Get up and running in under a minute. The SDK requires an API token scoped to your organization.

javascript

import { GitClient } from '@git/sdk';

// Initialize client with your API token
const client = new GitClient({
  token: process.env.GIT_API_TOKEN,
  version: 'v2',
  timeout: 10000
});

// Fetch repository status
const status = await client.status('main');
console.log(status.branch, status.ahead, status.behind);

// Create a commit and push
await client.commit({
  message: 'feat: add new feature',
  author: 'sdk@example.com'
});

await client.push({ remote: 'origin' });

💡

Tip: Environment Variables Never hardcode tokens. Use dotenv or your platform's secret management to inject GIT_API_TOKEN.

Configuration #

The SDK accepts a configuration object during initialization. All options are optional except token.

Option	Type	Description
token Required	string	API key with repository read/write permissions
version Optional	string	API version to target. Defaults to 'v2'
timeout Optional	number	Request timeout in ms. Defaults to 30000
retries Optional	number	Max retry attempts on network failure. Defaults to 3
proxy Optional	string \| null	HTTP/HTTPS proxy URL. null bypasses system proxy

API Reference #

Core methods available on the GitClient instance.

Method	Parameters	Returns
.status(branch)	branch: string	Promise<RepoStatus>
.commit(opts)	opts: CommitOptions	Promise<Commit>
.push(opts)	opts: PushOptions	Promise<PushResult>
.pull(opts)	opts: PullOptions	Promise<PullResult>
.hooks.register(name, fn)	name: string, fn: Handler	void

TypeScript Support #

The SDK is written in TypeScript and ships with full type definitions. No additional @types package required.

typescript

import { GitClient, CommitOptions, PushResult } from '@git/sdk';

const client = new GitClient({ token: process.env.TOKEN });

// Full type inference available
const result: PushResult = await client.push({
  remote: 'origin',
  force: false
});

if (result.success) {
  console.log(`Pushed ${result.commits} commits`);
}

Error Handling #

The SDK throws standardized GitError instances. Check the code property to handle specific scenarios.

javascript

import { GitError } from '@git/sdk';

try {
  await client.push({ remote: 'origin' });
} catch (err) {
  if (err instanceof GitError) {
    if (err.code === 'CONFLICT') {
      console.log('Merge conflict detected');
    } else if (err.code === 'RATE_LIMITED') {
      console.log(`Retry after ${err.retryAfter}ms`);
    }
  }
}

⚠️

Rate Limiting API calls are limited to 1000 requests per minute per token. The SDK automatically retries with exponential backoff on 429 responses.