or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced.mdblame.mdcheckout.mdconfig.mddiff-status.mdindex-operations.mdindex.mdobjects.mdreferences.mdremotes.mdrepository.mdrevwalk.mdsignatures.md
tile.json

tessl/npm-nodegit

Node.js libgit2 asynchronous native bindings for comprehensive Git operations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/nodegit@0.27.x

To install, run

npx @tessl/cli install tessl/npm-nodegit@0.27.0

index.mddocs/

NodeGit

NodeGit is a comprehensive Node.js library that provides asynchronous native bindings to libgit2, enabling JavaScript applications to perform advanced Git operations programmatically. It offers a complete API for repository management including cloning, committing, branching, merging, and status tracking, along with low-level Git object manipulation capabilities for blobs, trees, and commits.

Package Information

  • Package Name: nodegit
  • Package Type: npm
  • Language: JavaScript (with C++ native bindings)
  • Installation: npm install nodegit

Core Imports

const NodeGit = require('nodegit');

// Core repository and object classes
const Repository = NodeGit.Repository;
const Commit = NodeGit.Commit;
const Tree = NodeGit.Tree;
const Blob = NodeGit.Blob;
const Tag = NodeGit.Tag;

// Repository operations
const Clone = NodeGit.Clone;
const Branch = NodeGit.Branch;
const Reference = NodeGit.Reference;
const Remote = NodeGit.Remote;
const Index = NodeGit.Index;

// Advanced operations
const Merge = NodeGit.Merge;
const Rebase = NodeGit.Rebase;
const Stash = NodeGit.Stash;
const Diff = NodeGit.Diff;
const Status = NodeGit.Status;

// Utility classes
const Blame = NodeGit.Blame;
const Revwalk = NodeGit.Revwalk;
const Config = NodeGit.Config;
const Signature = NodeGit.Signature;
const Checkout = NodeGit.Checkout;

CommonJS destructuring:

const { 
  Repository, Clone, Commit, Tree, Blob, Tag,
  Branch, Reference, Remote, Index, Status, Diff,
  Merge, Rebase, Stash, Cherrypick, Revert,
  Blame, Revwalk, Config, Signature, Checkout
} = require('nodegit');

ES6 import (if using Babel/transpiler):

import NodeGit from 'nodegit';
const { Repository, Commit, Clone } = NodeGit;

Basic Usage

const NodeGit = require('nodegit');

// Clone a repository
NodeGit.Clone('https://github.com/user/repo.git', './local-repo')
  .then(function(repository) {
    // Repository cloned successfully
    return repository.getHeadCommit();
  })
  .then(function(commit) {
    console.log('Latest commit:', commit.sha());
    console.log('Message:', commit.message());
  });

// Open existing repository
NodeGit.Repository.open('./path/to/repo')
  .then(function(repo) {
    // Get current branch
    return repo.getCurrentBranch();
  })
  .then(function(reference) {
    console.log('Current branch:', reference.shorthand());
  });

Architecture

NodeGit is built using a 3-layer architecture:

  • Native C++ Layer: Direct bindings to libgit2 C library for Git operations
  • Generated JavaScript Layer: Auto-generated Promise wrappers that convert C++ callbacks to JavaScript Promises
  • Manual Extensions: Hand-written JavaScript enhancements that add convenience methods and better developer experience
  • Repository Context: Most operations require a Repository instance as the central context for Git operations

Capabilities

Repository Management

Core repository operations including initialization, opening, cloning, and configuration. The Repository class serves as the central hub for all Git operations.

class Repository {
  static discover(path, acrossFs, ceilingDirs): Promise<string>;
  static init(path, opts): Promise<Repository>;
  static open(path): Promise<Repository>;
  static clone(url, localPath, options): Promise<Repository>;
  
  config(): Promise<Config>;
  head(): Promise<Reference>;
  index(): Promise<Index>;
  workdir(): string;
  getHeadCommit(): Promise<Commit>;
  getCurrentBranch(): Promise<Reference>;
  getStatus(): Promise<StatusFile[]>;
}

Repository Management

Git Object Model

Access to core Git objects including commits, trees, blobs, and tags. These classes provide full access to Git's object database.

class Commit {
  static lookup(repo, oid): Promise<Commit>;
  static create(repo, updateRef, author, committer, encoding, message, tree, parentCount, parents): Promise<Oid>;
  
  id(): Oid;
  message(): string;
  author(): Signature;
  committer(): Signature;
  tree(): Promise<Tree>;
  getParents(): Promise<Commit[]>;
  sha(): string;
}

class Tree {
  static lookup(repo, oid): Promise<Tree>;
  
  id(): Oid;
  entries(): TreeEntry[];
  entryByPath(path): TreeEntry;
  diff(tree): Promise<Diff>;
}

class Blob {
  static lookup(repo, oid): Promise<Blob>;
  static createFromBuffer(repo, buffer): Promise<Oid>;
  
  id(): Oid;
  content(): Buffer;
  toString(): string;
  rawsize(): number;
}

Git Objects

Index and Staging

Index operations for staging changes, managing the Git index, and preparing commits.

class Index {
  static open(indexPath): Promise<Index>;
  
  add(pathspec): Promise<void>;
  addByPath(path): Promise<void>;
  entries(): IndexEntry[];
  write(): Promise<void>;
  writeTree(): Promise<Oid>;
}

Index Operations

References and Branches

Branch and reference management including creation, deletion, and traversal of Git references.

class Reference {
  static create(repo, name, oid, force, logMessage): Promise<Reference>;
  static lookup(repo, name): Promise<Reference>;
  static list(repo): Promise<string[]>;
  
  name(): string;
  shorthand(): string;
  target(): Oid;
  isBranch(): boolean;
  isRemote(): boolean;
}

class Branch {
  static create(repo, branchName, target, force): Promise<Reference>;
  static lookup(repo, branchName, branchType): Promise<Reference>;
  static delete(branch): Promise<void>;
}

References and Branches

Remote Operations

Remote repository operations including fetching, pushing, and managing remote connections.

class Remote {
  static create(repo, name, url): Promise<Remote>;
  static lookup(repo, name): Promise<Remote>;
  
  connect(direction, callbacks): Promise<void>;
  fetch(refspecs, opts, message): Promise<void>;
  push(refSpecs, options): Promise<void>;
  name(): string;
  url(): string;
}

class Clone {
  static clone(url, localPath, options): Promise<Repository>;
}

Remote Operations

Diff and Status

File difference computation and working directory status tracking.

class Diff {
  static treeToTree(repo, oldTree, newTree, opts): Promise<Diff>;
  static indexToWorkdir(repo, index, opts): Promise<Diff>;
  
  patches(): Promise<ConvenientPatch[]>;
  numDeltas(): number;
}

class Status {
  static file(repo, path): Promise<number>;
  static foreach(repo, callback): Promise<void>;
}

Diff and Status

Advanced Operations

Complex Git workflows including merging, rebasing, stashing, and cherry-picking.

class Merge {
  static commits(repo, ourCommit, theirCommit, opts): Promise<Index>;
  static base(repo, one, two): Promise<Oid>;
}

class Rebase {
  static init(repo, branch, upstream, onto, opts): Promise<Rebase>;
  
  next(): Promise<RebaseOperation>;
  commit(author, committer): Promise<Oid>;
  finish(signature): Promise<void>;
}

class Stash {
  static save(repo, stasher, message, flags): Promise<Oid>;
  static apply(repo, index, opts): Promise<void>;
  static drop(repo, index): Promise<void>;
}

Advanced Operations

Blame and History

File annotation and history tracking for determining line-by-line changes and commit traversal.

class Blame {
  static file(repo, path, options): Promise<Blame>;
  
  getHunkCount(): number;
  getHunkByIndex(index): BlameHunk;
  getHunkByLine(lineNumber): BlameHunk;
}

class Revwalk {
  static create(repo): Revwalk;
  
  sorting(...sorts): void;
  push(oid): void;
  pushHead(): void;
  next(): Promise<Oid>;
  getCommits(count): Promise<Commit[]>;
  getCommitsUntil(checkFn): Promise<Commit[]>;
  fileHistoryWalk(filePath, maxCount): Promise<HistoryEntry[]>;
}

Blame Operations | Commit History Traversal

Configuration and Signatures

Repository and user configuration management with signature handling for commits and tags.

class Config {
  static openDefault(): Promise<Config>;
  static openOndisk(path): Promise<Config>;
  
  getString(name): Promise<string>;
  setBool(name, value): Promise<void>;
  setString(name, value): Promise<void>;
}

class Signature {
  static now(name, email): Signature;
  static create(name, email, time, offset): Signature;
  static default(repo): Promise<Signature>;
  
  name(): string;
  email(): string;
  when(): Time;
  toString(withTime): string;
}

Configuration Management | Signature Handling

Checkout Operations

Working directory checkout operations for updating files to match specific commits or branches.

class Checkout {
  static head(repo, options): Promise<void>;
  static index(repo, index, options): Promise<void>;
  static tree(repo, treeish, options): Promise<void>;
}

Checkout Operations

Types

interface Signature {
  name(): string;
  email(): string;
  when(): Time;
}

interface Oid {
  tostrS(): string;
  fmt(): string;
  equal(b: Oid): boolean;
}

interface Time {
  time: number;
  offset: number;
}

interface StatusFile {
  path(): string;
  statusFlags(): number;
}

interface TreeEntry {
  name(): string;
  oid(): Oid;
  filemode(): number;
  type(): number;
}

interface IndexEntry {
  path: string;
  oid: Oid;
  flags: number;
  mode: number;
}

interface BlameHunk {
  linesInHunk(): number;
  finalCommitId(): Oid;
  finalStartLineNumber(): number;
  finalSignature(): Signature;
  origCommitId(): Oid;
  origStartLineNumber(): number;
  origSignature(): Signature;
  origPath(): string;
  boundary(): boolean;
}

interface HistoryEntry {
  commit: Commit;
  status: number;
  newName?: string;
  oldName?: string;
}

interface CheckoutOptions {
  checkoutStrategy?: number;
  disableFilters?: boolean;
  dirMode?: number;
  fileMode?: number;
  fileOpenFlags?: number;
  notifyCallback?: Function;
  notifyFlags?: number;
  progressCallback?: Function;
  paths?: string[];
  baseline?: Tree;
  targetDirectory?: string;
  ancestorLabel?: string;
  ourLabel?: string;
  theirLabel?: string;
}