Skip to main content

​
Overview

useGit provides two ways to work with Git repositories:
  1. Default instance - A pre-configured instance ready to use immediately
  2. Custom instances - Create multiple instances with custom configurations

​
Default Git Instance

The simplest way to use useGit is with the default exported instance: 
import git from "use-git"

// Ready to use - defaults to current directory
await git.status()
await git.commit("Initial commit")
The default instance is created with these settings:
  • Working directory: "."
  • Debug mode: false

​
Creating Custom Instances

Use createGit() to create custom instances with specific configurations: 
import { createGit } from "use-git"

const git = createGit({
  cwd: "/path/to/repo",
  debug: true,
})

await git.status()

​
Configuration Options

The createGit() function accepts a configuration object with the following properties:
​
cwd
string
default:"."
The working directory for Git operations. All commands will execute in this directory.
​
debug
boolean
default:"false"
Enable debug logging to see Git commands as they execute. Logs are written to stdout/stderr.

​
Type Signature

interface CreateGit {
  cwd?: string
  debug?: boolean
}

function createGit(options?: CreateGit): GitInstance

​
Multiple Repository Support

Create separate instances to work with multiple repositories simultaneously: 
import { createGit } from "use-git"

const mainRepo = createGit({ cwd: "./main-project" })
const docsRepo = createGit({ cwd: "./docs-site" })

// Work with both repositories independently
await mainRepo.commit("Update API")
await docsRepo.commit("Update documentation")
Each instance maintains its own working directory state, allowing you to manage multiple repositories without conflicts.

​
Debug Mode

Enable debug mode to troubleshoot issues or understand what Git commands are being executed: 
const git = createGit({ debug: true })

// This will log the actual git command being run:
// [use-git] DEBUG  running: git status
await git.status()
Debug mode sets process.env.DEBUG = "true" and outputs formatted logs with colored labels to help identify command execution.

​
Best Practices

​
Single Repository Projects

For projects working with a single repository, use the default instance: 
import git from "use-git"

// Simple and clean
await git.add()
await git.commit("Update feature")

​
Multi-Repository Projects

For monorepos or tools managing multiple repositories, create named instances: 
import { createGit } from "use-git"

const backend = createGit({ cwd: "./packages/backend" })
const frontend = createGit({ cwd: "./packages/frontend" })

// Clear which repository you're working with
await backend.status()
await frontend.status()

​
Development vs Production

Use environment variables to control debug mode: 
import { createGit } from "use-git"

const git = createGit({
  cwd: process.cwd(),
  debug: process.env.NODE_ENV === "development",
})

​
Instance Lifecycle

Each Git instance is independent and lightweight. You don’t need to explicitly close or dispose of instances: 
const git = createGit({ cwd: "./repo" })

// Use the instance
await git.status()

// No cleanup needed - instance can be garbage collected
Changing the working directory after instance creation requires creating a new instance. See Working Directory for details.

​
Next Steps

Working Directory

Learn how working directories are managed

Error Handling

Handle errors and failures gracefully

Build docs developers (and LLMs) love

Get started for freeTalk to us