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

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

import type { GetChangesBetweenRefsOptions, GitBranchOptions, GitCommitOptions, GitCommonOptions, GitFetchOptions, GitInitOptions, GitStageOptions, ParsedRemoteBranch, ParseRemoteBranchOptions } from "./types";
/**
 * Get a list of files with untracked changes.
 * Throws an error on failure by default.
 *
 * @returns An array of file paths with untracked changes
 */
export declare function getUntrackedChanges(options: GitCommonOptions): string[];
/** @deprecated Use object params version */
export declare function getUntrackedChanges(cwd: string): string[];
/**
 * Fetch from the given remote (and optionally branch) or all remotes.
 * Throws an error on failure by default.
 */
export declare function fetchRemote(options: GitFetchOptions): void;
/** @deprecated Use object params version */
export declare function fetchRemote(remote: string, cwd: string): void;
/**
 * Fetch from the given remote and branch. Throws an error on failure.
 * @deprecated Use `fetchRemote({ remote, remoteBranch, cwd })`
 */
export declare function fetchRemoteBranch(remote: string, remoteBranch: string, cwd: string): void;
/**
 * Gets file paths with changes that have not been staged yet.
 * Throws an error on failure by default.
 *
 * @returns An array of relative file paths with unstaged changes
 */
export declare function getUnstagedChanges(options: GitCommonOptions): string[];
/** @deprecated Use object params version */
export declare function getUnstagedChanges(cwd: string): string[];
/**
 * Gets file paths with changes between the current branch and the given branch.
 * Throws an error on failure.
 *
 * @returns An array of relative file paths that have changed
 * @deprecated Use `getBranchChanges({ branch, cwd })`
 */
export declare function getChanges(branch: string, cwd: string): string[];
/**
 * Gets file paths with changes between the branch and the merge-base.
 * Throws an error on failure by default.
 *
 * @returns An array of relative file paths that have changed
 */
export declare function getBranchChanges(options: GitBranchOptions): string[];
/** @deprecated Use object params version */
export declare function getBranchChanges(branch: string, cwd: string): string[];
/**
 * Gets file paths with changes between two git references (commits, branches, tags).
 * Throws an error on failure by default.
 *
 * @returns An array of file paths that have changed
 */
export declare function getChangesBetweenRefs(options: GetChangesBetweenRefsOptions): string[];
/** @deprecated Use object param version */
export declare function getChangesBetweenRefs(fromRef: string, toRef: string, options: string[], pattern: string, cwd: string): string[];
/**
 * Gets all files with staged changes (files added to the index).
 * Throws an error on failure by default.
 *
 * @returns An array of relative file paths that have been staged
 */
export declare function getStagedChanges(options: GitCommonOptions): string[];
/** @deprecated Use object params version */
export declare function getStagedChanges(cwd: string): string[];
/**
 * Gets recent commit messages between the specified parent branch and HEAD.
 * By default, returns an empty array if the operation fails.
 *
 * @returns An array of commit message strings
 */
export declare function getRecentCommitMessages(options: GitBranchOptions): string[];
/** @deprecated Use object params version */
export declare function getRecentCommitMessages(branch: string, cwd: string): string[];
/**
 * Gets the user email from the git config.
 * @returns The email string if found, null otherwise
 */
export declare function getUserEmail(options: GitCommonOptions): string | null;
/** @deprecated Use object params version */
export declare function getUserEmail(cwd: string): string | null;
/**
 * Gets the current branch name.
 * In detached HEAD state, returns "HEAD".
 *
 * @returns The branch name if successful, null otherwise
 */
export declare function getBranchName(options: GitCommonOptions): string;
/** @deprecated Use object params version */
export declare function getBranchName(cwd: string): string;
/**
 * Gets the full reference path for a given branch.
 * `branch` here is the short branch name, e.g. `branch-name`.
 * @returns The full branch reference (e.g., `refs/heads/branch-name`) if found, null otherwise
 */
export declare function getFullBranchRef(options: GitBranchOptions): string | null;
/** @deprecated Use object params version */
export declare function getFullBranchRef(branch: string, cwd: string): string | null;
/**
 * Gets the short branch name from a full branch reference.
 * @returns The short branch name if successful, null otherwise
 */
export declare function getShortBranchName(options: {
    /** The full branch reference (e.g., `refs/heads/branch-name`) */
    fullBranchRef: string;
} & GitCommonOptions): string | null;
/** @deprecated Use object params version */
export declare function getShortBranchName(fullBranchRef: string, cwd: string): string | null;
/**
 * Gets the current commit hash (SHA).
 * @returns The hash if successful, null otherwise
 */
export declare function getCurrentHash(options: GitCommonOptions): string | null;
/** @deprecated Use object params version */
export declare function getCurrentHash(cwd: string): string | null;
/**
 * Get the commit hash in which the file was first added.
 * @returns The commit hash if found, undefined otherwise
 */
export declare function getFileAddedHash(options: {
    filename: string;
} & GitCommonOptions): string | undefined;
/** @deprecated Use object params version */
export declare function getFileAddedHash(filename: string, cwd: string): string | undefined;
/**
 * Run `git init` and verify that the `user.name` and `user.email` configs are set (at any level).
 * Throws an error if `git init` fails.
 *
 * If `user.email` and `user.name` aren't already set globally, and the missing value is provided
 * in params, set it at the repo level. Otherwise, throw an error.
 */
export declare function init(options: GitInitOptions): void;
/** @deprecated Use object params version */
export declare function init(cwd: string, email?: string, username?: string): void;
/**
 * Stages files matching the given patterns.
 */
export declare function stage(options: GitStageOptions): void;
/** @deprecated Use object params version */
export declare function stage(patterns: string[], cwd: string): void;
/**
 * Commit changes. Throws an error on failure by default.
 */
export declare function commit(options: GitCommitOptions): void;
/** @deprecated Use object params version */
export declare function commit(message: string, cwd: string, options?: string[]): void;
/**
 * Stages files matching the given patterns and creates a commit with the specified message.
 * Convenience function that combines `stage()` and `commit()`.
 * Throws an error on commit failure by default.
 */
export declare function stageAndCommit(options: GitStageOptions & GitCommitOptions): void;
/** @deprecated Use object params version */
export declare function stageAndCommit(patterns: string[], message: string, cwd: string, commitOptions?: string[]): void;
/**
 * Reverts all local changes (both staged and unstaged) by stashing them and then dropping the stash.
 * @returns True if the revert was successful, false otherwise. It will also be false if there were
 * no changes to revert. (To distinguish between this case and errors, use the `throwOnError` option.)
 */
export declare function revertLocalChanges(options: GitCommonOptions): boolean;
/** @deprecated Use object params version */
export declare function revertLocalChanges(cwd: string): boolean;
/**
 * Attempts to determine the parent branch of the current branch using `git show-branch`.
 * @returns The parent branch name if found, null otherwise
 * @deprecated Does not appear to be used
 */
export declare function getParentBranch(cwd: string): string | null;
/**
 * Gets the remote tracking branch for the specified branch.
 *
 * @returns The remote branch name (e.g., `origin/main`) if found, null otherwise
 */
export declare function getRemoteBranch(options: GitBranchOptions): string | null;
/** @deprecated Use object params version */
export declare function getRemoteBranch(branch: string, cwd: string): string | null;
/**
 * Get the remote and branch name from a full branch name that may include a remote prefix.
 * If the path doesn't start with one of `options.knownRemotes` (but has multiple segments),
 * the actual list of remotes will be fetched to see if one of those matches.
 *
 * NOTE: The additional verification is new in the object params version; the original version
 * incorrectly assumes the first segment before a slash is always a remote.
 */
export declare function parseRemoteBranch(options: ParseRemoteBranchOptions): ParsedRemoteBranch;
/**
 * @deprecated Use object params version, which does more verification. This version inaccurately
 * assumes the first segment before a slash is always a remote, which could lead to tricky bugs.
 */
export declare function parseRemoteBranch(branch: string): ParsedRemoteBranch;
/**
 * Gets the default branch based on `git config init.defaultBranch`, falling back to `master`.
 */
export declare function getDefaultBranch(options: GitCommonOptions): string;
/** @deprecated Use object params version */
export declare function getDefaultBranch(cwd: string): string;
/**
 * Lists all tracked files matching the given patterns.
 * Throws on error by default.
 * @returns An array of file paths, or an empty array if no files are found
 */
export declare function listAllTrackedFiles(options: {
    /** File patterns to match (passed to git ls-files) */
    patterns: string[];
} & GitCommonOptions): string[];
/** @deprecated Use object params version */
export declare function listAllTrackedFiles(patterns: string[], cwd: string): string[];