git-context

Know your Git state from inside Node.js.

git-context is a zero-configuration, read-only TypeScript library that exposes the Git repository state around an application, script, deployment, migration, or CI job. It intentionally is not a complete Git wrapper.

Installation

npm install @utkarsh2325/git-context

Node.js 20 or later and the git executable are required.

Quick Start

import { git } from "@utkarsh2325/git-context";

const context = git();

console.log({
  branch: context.branch,
  commit: context.shortCommit,
  dirty: context.dirty,
});

git() finds the enclosing repository through Git itself, so it works seamlessly from nested directories, monorepo packages, and linked worktrees. It returns a fresh snapshot on every call so deployment checks never rely on stale clean/dirty state.

Usage

1. Reading Repository Context

Call git() to read an immutable snapshot of the current repository:

import { git } from "git-context";

const context = git();

console.log(`Branch: ${context.branch}`);
console.log(`Commit: ${context.commit} (${context.shortCommit})`);
console.log(`Clean: ${!context.dirty}`);
console.log(`Author: ${context.author} <${context.email}>`);
console.log(`Root: ${context.root}`);

if (context.remote) {
  console.log(`Remote: ${context.remote} (${context.remoteUrl})`);
}

GitContext Properties

Property	Type	Description
branch	string | null	Current branch name, or null when HEAD is detached
commit	string	Full 40-character SHA of HEAD
shortCommit	string	Abbreviated SHA of HEAD (7+ characters)
dirty	boolean	true if tracked, staged, or untracked changes exist
detached	boolean	true if HEAD points directly at a commit rather than a branch
author	string	Author name of the HEAD commit
email	string	Author email of the HEAD commit
root	string	Absolute filesystem path to the repository root directory
commitDate	string	ISO 8601 commit timestamp of HEAD
tag	string | undefined	Exact tag pointing at HEAD, if tagged
ahead	number | undefined	Commits ahead of upstream tracking branch, if configured
behind	number | undefined	Commits behind upstream tracking branch, if configured
stashCount	number	Number of stash entries saved in the repository
mergeConflict	boolean	true if unmerged files exist (merge conflict state)
submodules	readonly SubmoduleInfo[]	List of submodules with paths, commit SHAs, and dirty states
remote	string | undefined	Preferred remote name (origin when present, otherwise first available)
remoteUrl	string | undefined	URL of the preferred remote

2. Checking Repository Presence

Check whether a directory is inside a Git repository before executing Git-dependent logic:

import { git } from "git-context";

if (git.isRepository()) {
  const context = git();
  console.log(`Running in Git repo at ${context.root}`);
} else {
  console.log("Not running inside a Git repository; skipping Git checks.");
}

3. Enforcing Safety Guards

Prevent accidental deployments, database migrations, or release publishing from dirty working trees, untracked changes, or wrong branches:

import { git } from "git-context";

// Require a specific branch (throws BranchMismatchError if mismatched or detached)
git.requireBranch("main");

// Require a completely clean working tree (throws DirtyRepositoryError if dirty)
git.assertClean();

// Enforce both in a single check
git.requireCleanBranch("main");

// Generic assertion combining multiple criteria:
git.assert({
  branch: ["main", "release"], // accept array of allowed branches
  clean: true,                 // require clean working tree
  detached: false,             // reject detached HEAD
  tag: true,                   // require HEAD to have an exact tag (or specific string like "v1.0.0")
  unpushed: true,              // require no unpushed commits ahead of upstream
});

// Proceed with sensitive task safely
await deploy();

4. Watch Mode (Event-Driven)

React to Git changes in real time (e.g. for development servers, watch scripts, or live status displays):

import { git } from "git-context";

const watcher = git.watch({ interval: 1000 });

// Fired whenever commit, branch, or dirty state changes
watcher.on("change", (newContext, oldContext) => {
  console.log(`Repository changed: ${oldContext.shortCommit} → ${newContext.shortCommit}`);
});

// Fired when working tree transitions from clean to dirty
watcher.on("dirty", (context) => {
  console.warn("Working tree has uncommitted changes!");
});

// Fired when working tree transitions back to clean
watcher.on("clean", (context) => {
  console.log("Working tree is now clean.");
});

// Stop polling when done
watcher.stop();

5. Configuration File Support

Define repository assertion rules in .gitcontextrc.json or package.json#gitContext and enforce them with a single line:

{
  "$schema": "https://github.com/KDM-cli/git-context",
  "assertions": {
    "branch": "main",
    "clean": true,
    "detached": false,
    "unpushed": true
  },
  "format": "table"
}

import { git } from "git-context";

// Enforce rules defined in configuration:
git.assertFromConfig();

// Or load the parsed config object directly:
const config = git.loadConfig();

6. Inspecting Another Directory (cwd)

By default, git-context discovers the repository enclosing process.cwd(). Pass { cwd } to any method to inspect a different repository, submodule, or workspace:

import { git } from "git-context";

const repoContext = git({ cwd: "/srv/release-checkout" });

git.requireCleanBranch("main", { cwd: "/srv/release-checkout" });

7. Error Handling

git-context throws dedicated, typed errors extending GitContextError:

import {
  git,
  GitContextError,
  DirtyRepositoryError,
  BranchMismatchError,
  DetachedHeadError,
  TagMismatchError,
  UnpushedCommitsError,
  RepositoryNotFoundError,
  GitExecutableNotFoundError,
} from "git-context";

try {
  git.assert({
    branch: "main",
    clean: true,
    tag: true,
  });
} catch (error) {
  if (error instanceof DirtyRepositoryError) {
    console.error("Please commit or stash changes before deploying.");
  } else if (error instanceof BranchMismatchError) {
    console.error(`Expected branch "${error.expected}", but found "${error.actual}".`);
  } else if (error instanceof DetachedHeadError) {
    console.error("HEAD is detached; checkout a named branch.");
  } else if (error instanceof TagMismatchError) {
    console.error(`Tag requirement failed (expected: ${error.expected}, actual: ${error.actual}).`);
  } else if (error instanceof UnpushedCommitsError) {
    console.error(`Please push ${error.ahead} local commit(s) before publishing.`);
  } else if (error instanceof RepositoryNotFoundError) {
    console.error(`No Git repository found from: ${error.cwd}`);
  } else if (error instanceof GitExecutableNotFoundError) {
    console.error("Git is not installed or not found on PATH.");
  } else if (error instanceof GitContextError) {
    console.error(`Git context error: ${error.message}`);
  }
}

8. Command Line Interface (CLI)

Run git-context directly from the terminal without installing:

npx git-context

Output Formats

• Table (default): Color-coded, aligned table output displaying branch, commit, dirty status, author, remotes, tracking, stash count, merge conflict alerts, and submodules.
• Minimal (--format=minimal): Compact one-liner with color highlights, ideal for terminal prompts and status lines (e.g., main* a1b2c3d [1↑0↓]).
• JSON (--json or --format=json): Machine-readable JSON for CI/CD pipelines and scripting.

# Compact format
npx git-context --format=minimal

# Disable ANSI colors
npx git-context --no-color

# Output JSON
npx git-context --json

Scaffold Configuration (init)

Generate a .gitcontextrc.json configuration file and a sample scripts/deploy-guard.ts guard script:

npx git-context init

Flags:

• --format=<format>: Output format: table (default), json, minimal
• --json: Output machine-readable JSON (alias for --format=json)
• --no-color: Disable colored output
• -h, --help: Show usage and options
• --version: Show version number

Examples

See the examples/ directory:

• basic.ts — read and print Git context
• deployment.ts — deploy only from clean main
• migration.ts — run migrations with branch guard
• express.ts — embed Git context in HTTP response headers
• ci-guard.ts — CI pre-deploy validation
• release.ts — release script with metadata logging

Design and Security

All Git commands are executed with Node's non-shell process API (execFileSync) using explicit argument arrays. git-context:

• Never interpolates arguments into a shell command (safe from shell injection)
• Never changes Git configuration or modifies the repository (read-only)
• Never contacts remote servers or performs network requests
• Emits zero telemetry
• Communicates failures through typed, actionable errors

License

MIT