@struktoai/mirage-core/dist/commands/cli/builtin/git/history.d.ts

A Unified Virtual Filesystem For AI Agents

import { LineRegex, type PosixRegex } from '../../../../rs/regex.ts';
import type { FlagView } from '../../../spec/flag_view.ts';
import { type CommitFacts, type LogFormat } from './format.ts';
import { type DiffFlags } from './diff_output.ts';
import type { Pickaxe } from './pickaxe.ts';
import { type Repo } from './repo.ts';
import type { Context } from '../../../config.ts';
import { Decoration, type DateMode, type MailmapEntry } from './types.ts';
/** A `--grep`, `--author` or `--committer` pattern, compiled by mirage-rs. */
export type LinePattern = LineRegex | PosixRegex;
/** The parsed shape of a `git log` invocation. */
export interface LogFlags {
    /** `--author` patterns, any of which may match. */
    readonly authors: readonly LinePattern[];
    /** `--grep` patterns, any of which may match a line of the message. */
    readonly greps: readonly LinePattern[];
    /** `--committer` patterns, any of which may match. */
    readonly committers: readonly LinePattern[];
    /** The worktree `.mailmap`, which `%aN`-style placeholders always read. */
    readonly mailmap: readonly MailmapEntry[];
    /**
     * `log.mailmap` or `--[no-]mailmap`: map the header identities and what
     * `--author` and `--committer` match.
     */
    readonly useMailmap: boolean;
    /** `-i`, which folds case for `--grep`, `--author` and `-S` alike. */
    readonly ignoreCase: boolean;
    readonly minParents: number | null;
    readonly maxParents: number | null;
    readonly firstParent: boolean;
    readonly date: DateMode;
    /**
     * How commits are labelled with their refs; parseFlags leaves it off, and
     * `decorationFor` settles it once the repository's config can be read.
     */
    readonly decorate: Decoration;
    /** `-n`/`--max-count`, how many commits to print; null when unlimited. */
    readonly maxCount: number | null;
    /** `--oneline`, one abbreviated row per commit. */
    readonly oneline: boolean;
    /** `--reverse`, oldest first. */
    readonly reverse: boolean;
    /** `-S` or `-G`, null for neither. */
    readonly pickaxe: Pickaxe | null;
    /** `--since` as an epoch second. */
    readonly since: number | null;
    /** `--until` as an epoch second. */
    readonly until: number | null;
    /** `--all`, start from every ref as well. */
    readonly allRefs: boolean;
    /**
     * How each commit renders; medium unless `--oneline` or
     * `--pretty`/`--format` said otherwise.
     */
    readonly pretty: LogFormat;
    /**
     * Print abbreviated ids, which `--oneline` implies and
     * `--pretty=oneline` alone does not.
     */
    readonly abbrevCommit: boolean;
    /** `--graph`, draw the history beside the commits. */
    readonly graph: boolean;
    /**
     * The walk order: newest first (`default`), `topo` (`--topo-order`, which
     * `--graph` implies) or `date` (`--date-order`).
     */
    readonly order: 'default' | 'topo' | 'date';
    /** `--boundary`, print the commits the walk stops at after the ones it shows. */
    readonly boundary: boolean;
    /** The repository-relative patterns the history is limited to, none for the whole tree. */
    readonly pathspecs: readonly string[];
    /** The line's abort, which a long `--grep`, `--author` or `--committer` search stops at. */
    readonly signal?: AbortSignal;
    /**
     * Whether `-m` or `--diff-merges` asks for merges' diffs against their
     * parents. Only then does a path walk keep merges' whole history; the
     * first-parent diff `--first-parent` implies leaves it simplified (git 2.47.3).
     */
    readonly mergeDiffs: boolean;
}
/** One commit of a walk: drawn by `--graph` always, printed unless `-S` passed it by. */
export interface WalkStep {
    readonly commit: CommitFacts;
    readonly shown: boolean;
}
/** The commits a log walks, in order, and the ones a graph may draw an edge to. */
export interface Walk {
    readonly steps: readonly WalkStep[];
    /**
     * Every commit in the walk that no filter leaves out, which is what makes
     * it a parent `--graph` draws a line to. Filled only for an ordered walk.
     */
    readonly interesting: ReadonlySet<string>;
    /** The `--boundary` commits, in the order they print after the walk. */
    readonly boundary: readonly CommitFacts[];
    /**
     * The parents a path-limited walk prints each of its commits with: under
     * `--graph` the nearest shown commits along the history it kept, otherwise
     * the ones it followed; empty when the walk is not limited.
     */
    readonly parents: ReadonlyMap<string, readonly string[]>;
}
/**
 * Read display formats in command-line order, validating every occurrence.
 * --oneline sets the format; its abbreviation side effect is read separately.
 * Bare --pretty resets to medium, while bare --format is always an error
 * (Git 2.50.1).
 */
export declare function prettyFormat(fl: FlagView): LogFormat;
export declare function parseFlags(fl: FlagView, env?: Readonly<Record<string, string>> | null, signal?: AbortSignal): LogFlags;
/**
 * A walk's operands as revisions and the patterns of the paths it is limited
 * to, and whether `--` was on the line; see `operands`.
 *
 * @param ctx the line's context, carrying its argv
 * @param fl the verb's flags, for `-C`
 * @param repo the opened repository
 * @param texts the operands
 */
export declare function walkOperands(ctx: Context, fl: FlagView, repo: Repo, texts: readonly string[]): Promise<[string[], string[], boolean]>;
/**
 * The commits a walk starts from and hides, as `splitRevisions` reads them,
 * except that with `--` on the line a revision that resolves to nothing is a
 * bad revision (git 2.47.3).
 *
 * @param repo the opened repository
 * @param revisions the revision operands
 * @param dashed whether `--` is on the line
 */
export declare function walkEnds(repo: Repo, revisions: readonly string[], dashed: boolean): Promise<[CommitFacts[], CommitFacts[]]>;
/** Follow tag objects down to the commit a ref ultimately names. */
export declare function peelToCommit(repo: Repo, oid: string): Promise<CommitFacts | null>;
/** A ref table with symrefs resolved to the ids they name. */
export declare function resolvedRefs(repo: Repo): Promise<Map<string, string>>;
/** Every commit a ref points at, tags peeled, for `--all`. */
export declare function refCommits(repo: Repo): Promise<CommitFacts[]>;
/**
 * The decoration style a value names: a boolean word or number, `short`, `full`
 * or `auto`, which decorates only a terminal and so never here; null for
 * anything else.
 *
 * @param value the `--decorate=` or `log.decorate` value
 */
export declare function decorationStyle(value: string): Decoration | null;
/**
 * How a `log` or `show` line labels its commits, as git settles it (pinned
 * against git 2.47.3).
 *
 * `log.decorate` sets the style, a value it cannot read meaning none, and the
 * line's `--decorate[=<style>]` and `--no-decorate` override it, the last one
 * typed winning; `--pretty=raw` ignores the config. A template that prints
 * `%d` or `%D` is decorated even when nothing asked, by short names unless a
 * style says full, and one that prints neither loads no labels at all.
 *
 * @param repo the opened repository
 * @param fl the line's flags
 * @param pretty the line's format
 * @throws InvalidDecorateError a `--decorate` value that names no style
 */
export declare function decorationFor(repo: Repo, fl: FlagView, pretty: LogFormat): Promise<Decoration>;
/**
 * How `log` and `show` present commits, once the repository's config can be
 * read: the worktree `.mailmap`, whether the header identities map through it
 * (`log.mailmap` unless the line's `--[no-]mailmap` says otherwise), and the
 * decoration style.
 *
 * @param repo the opened repository
 * @param fl the line's flags
 * @param pretty the line's format
 * @throws BadConfigValueError a `log.mailmap` git cannot read as a boolean
 * @throws InvalidDecorateError a `--decorate` value that names no style
 */
export declare function displayed(repo: Repo, fl: FlagView, pretty: LogFormat): Promise<[readonly MailmapEntry[], boolean, Decoration]>;
/**
 * Ref labels per commit, in the order git prints them; null for a line that
 * prints none.
 *
 * git walks refs alphabetically and prepends each label, so a commit's labels
 * read in reverse ref order; HEAD is pulled to the front, spelled
 * `HEAD -> branch` when attached (the branch's own label is absorbed) and
 * `HEAD` alone when detached. Pinned against git 2.50.
 *
 * @param repo the opened repository
 * @param style `FULL` keeps each ref's whole name, `NONE` loads nothing;
 *   anything else shortens it
 */
export declare function decorations(repo: Repo, style?: Decoration): Promise<Map<string, string[]> | null>;
/**
 * The commits a log walks, in the order it walks them.
 *
 * Order of operations is git's: walk history, drop what the filters reject,
 * and cut at `-n` printed commits. A topological or date order needs the whole
 * walk first (git's limited walk), and is taken over the commits inside the
 * date window before the other filters run. The pickaxe is the one filter that
 * leaves a commit in the walk: git still draws it into the graph and only
 * declines to print it, which is why `--graph -S` shows `...` rows.
 *
 * @param repo repository to walk
 * @param starts the commits to walk back from; more than one when `--all`
 *   seeds every ref
 * @param flags the parsed invocation
 * @param hidden commits whose whole history is left out, the `A` of `A..B`
 * @param diff the diff the pickaxe searches: its renames, its merge diff and its paths
 */
export declare function walked(repo: Repo, starts: readonly CommitFacts[], flags: LogFlags, hidden?: readonly CommitFacts[], diff?: DiffFlags): Promise<Walk>;
/**
 * The commits a log invocation prints, in the order it prints them.
 *
 * The walk's printed commits, reversed last when asked: reversing after the
 * cut is what makes `-S <name> --reverse` name the commit that introduced a
 * string rather than the most recent one to touch it.
 *
 * @param repo repository to walk
 * @param starts the commits to walk back from
 * @param flags the parsed invocation
 * @param hidden commits whose whole history is left out, the `A` of `A..B`
 * @param diff the diff the pickaxe searches
 */
export declare function select(repo: Repo, starts: readonly CommitFacts[], flags: LogFlags, hidden?: readonly CommitFacts[], diff?: DiffFlags): Promise<CommitFacts[]>;
/**
 * The commits a walk prints, in the order it prints them: the shown ones, then
 * the `--boundary` ones, all of them reversed under `--reverse`.
 *
 * @param walk the walk
 * @param flags the parsed invocation
 */
export declare function inPrintOrder(walk: Walk, flags: LogFlags): CommitFacts[];
//# sourceMappingURL=history.d.ts.map