workspace-tools/lib/git/git.d.ts

A collection of utilities that are useful in a git-controlled monorepo managed by one of these tools:

/// <reference types="node" />
/// <reference types="node" />
/// <reference types="node" />
import { SpawnSyncOptions, SpawnSyncReturns } from "child_process";
import { GitCommonOptions } from "./types";
export type GitOptions = Omit<SpawnSyncOptions, "cwd"> & GitCommonOptions & {
    /** Operation description to be used in error message (formatted as start of sentence) */
    description?: string;
    debug?: boolean;
};
export declare class GitError extends Error {
    readonly originalError: unknown;
    readonly gitOutput?: GitProcessOutput;
    constructor(message: string, originalError?: unknown, gitOutput?: GitProcessOutput);
}
export type GitProcessOutput = {
    stderr: string;
    stdout: string;
    success: boolean;
} & Omit<SpawnSyncReturns<string | Buffer>, "stdout" | "stderr">;
/** Observes the git operations called from `git()` or `gitFailFast()` */
export type GitObserver = (args: string[], output: GitProcessOutput) => void;
/**
 * Adds an observer for the git operations, e.g. for testing
 * @returns a function to remove the observer
 */
export declare function addGitObserver(observer: GitObserver): () => void;
/** Clear all git observers */
export declare function clearGitObservers(): void;
/**
 * Runs git command - use this for read-only commands, or if you'd like to explicitly check the
 * result and implement custom error handling.
 *
 * The caller is responsible for validating the input.
 * `shell` will always be set to false.
 */
export declare function git(args: string[], options?: GitOptions): GitProcessOutput;
/**
 * Run a git command. Use this for commands that make critical changes to the filesystem.
 * If it fails, throw an error and set `process.exitCode = 1` (unless `options.noExitCode` is set).
 *
 * The caller is responsible for validating the input.
 * `shell` will always be set to false.
 */
export declare function gitFailFast(args: string[], options?: GitCommonOptions & {
    noExitCode?: boolean;
}): void;
/**
 * Processes git command output by splitting it into lines and filtering out empty lines.
 * Also filters out `node_modules` lines if specified in options.
 *
 * If the command failed with stderr output, an error is thrown.
 *
 * @param output - The git command output to process
 * @returns An array of lines (presumably file paths), or an empty array if the command failed
 * without stderr output.
 * @internal
 */
export declare function processGitOutput(output: GitProcessOutput, options?: {
    excludeNodeModules?: boolean;
}): string[];