git-repo-info

import gitRepoInfo from "git-repo-info";

const gitRepoInfo = require("git-repo-info");

const gitRepoInfo = require("git-repo-info");

// Get info for current directory (searches upward for .git)
const info = gitRepoInfo();

console.log(info.branch);              // 'main'
console.log(info.sha);                 // '5359aabd3872d9ffd160712e9615c5592dfe6745'
console.log(info.abbreviatedSha);      // '5359aabd38'
console.log(info.tag);                 // 'v1.0.0' or null
console.log(info.lastTag);             // 'v0.9.0' or null
console.log(info.commitsSinceLastTag); // 5

// Get info for specific directory
const specificInfo = gitRepoInfo('/path/to/repo');

/**
 * Retrieves Git repository information for the specified path or current directory
 * @param gitPath - Optional path to the repository's .git folder. If not provided, searches upward from current directory
 * @returns GitRepoInfo object containing repository metadata
 */
function gitRepoInfo(gitPath?: string): GitRepoInfo;

interface GitRepoInfo {
  /** The current branch name (null if in detached HEAD state or repo not found) */
  branch: string | null;
  /** SHA hash of the current commit (null if repo not found) */
  sha: string | null;
  /** First 10 characters of the current SHA (null if repo not found) */
  abbreviatedSha: string | null;
  /** Tag for the current SHA (null if no tag exists or repo not found) */
  tag: string | null;
  /** Tag for the closest tagged ancestor (null if no ancestor is tagged or repo not found) */
  lastTag: string | null;
  /** Number of commits since the closest tagged ancestor (0 if current commit is tagged, Infinity if no ancestor is tagged) */
  commitsSinceLastTag: number;
  /** Committer name and email for the current SHA (null if commit data unavailable or repo not found) */
  committer: string | null;
  /** Commit date for the current SHA in ISO format (null if commit data unavailable or repo not found) */
  committerDate: string | null;
  /** Author name and email for the current SHA (null if commit data unavailable or repo not found) */
  author: string | null;
  /** Authored date for the current SHA in ISO format (null if commit data unavailable or repo not found) */
  authorDate: string | null;
  /** Commit message for the current SHA (null if commit data unavailable or repo not found) */
  commitMessage: string | null;
  /** Root directory for the Git repo or submodule (null if repo not found) */
  root: string | null;
  /** Directory containing Git metadata for this repo or submodule (null if repo not found) */
  commonGitDir: string | null;
  /** Directory containing Git metadata specific to worktree (same as commonGitDir if not in worktree, null if repo not found) */
  worktreeGitDir: string | null;
  /** Array of parent commit SHA hashes (available when commit data is accessible) */
  parents?: string[];
}

const gitRepoInfo = require("git-repo-info");

// Basic usage - get info for current directory
const info = gitRepoInfo();
if (info.sha) {
  console.log(`Current commit: ${info.sha} on branch ${info.branch}`);
  if (info.tag) {
    console.log(`Tagged as: ${info.tag}`);
  } else if (info.lastTag) {
    console.log(`${info.commitsSinceLastTag} commits since ${info.lastTag}`);
  }
}

// Get info for specific path
const projectInfo = gitRepoInfo('/path/to/project');

// Handle repositories that might not exist
const safeInfo = gitRepoInfo('./maybe-not-a-repo');
if (!safeInfo.sha) {
  console.log('Not a git repository');
}

// Access detailed commit information (when available)
if (info.committer && info.commitMessage) {
  console.log(`Last commit by ${info.committer}: "${info.commitMessage}"`);
  console.log(`Committed on: ${info.committerDate}`);
}

// Working with worktrees and submodules
console.log(`Repository root: ${info.root}`);
console.log(`Git directory: ${info.commonGitDir}`);
if (info.worktreeGitDir !== info.commonGitDir) {
  console.log(`Worktree git directory: ${info.worktreeGitDir}`);
}

/** Controls whether errors are suppressed (default: true) */
gitRepoInfo._suppressErrors: boolean;

/**
 * Internal function to find repository location (exposed for testing)
 * @param startingPath - Starting directory for repository search
 * @returns Repository path information or null
 */
gitRepoInfo._findRepo(startingPath?: string): PathInfo | null;

/**
 * Internal function to change the Git directory name (exposed for testing)
 * @param newDirName - New directory name to use instead of '.git'
 */
gitRepoInfo._changeGitDir(newDirName: string): void;

interface PathInfo {
  /** Directory containing worktree-specific Git metadata */
  worktreeGitDir: string;
  /** Directory containing common Git metadata */
  commonGitDir: string;
  /** Root directory of the repository */
  root: string;
}

// Default behavior - returns object with null values on error
const info = gitRepoInfo('/not/a/repo');
console.log(info.sha); // null

// Enable error throwing for debugging
gitRepoInfo._suppressErrors = false;
try {
  const info = gitRepoInfo('/not/a/repo');
} catch (error) {
  console.error('Repository error:', error.message);
}