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

A Unified Virtual Filesystem For AI Agents

import { Decoration, type DateMode, type MailmapEntry } from './types.ts';
export declare const FULL_SHA = 40;
export declare const DEFAULT_DATE: DateMode;
/** A commit as far as rendering is concerned, whoever read it. */
export interface CommitFacts {
    readonly oid: string;
    readonly tree: string;
    readonly message: string;
    readonly authorName: string;
    readonly authorEmail: string;
    /** Seconds since the epoch. */
    readonly authorTime: number;
    /** The author's UTC offset in minutes, git's own sign convention. */
    readonly authorTimezoneMinutes: number;
    readonly committerName: string;
    readonly committerEmail: string;
    readonly committerTime: number;
    readonly committerTimezoneMinutes: number;
    readonly parents: readonly string[];
    /**
     * The message and the `Name <email>` identities as their bytes, a byte that
     * is no part of a character as its surrogate escape; set only when the
     * decoded text lost one, for the filters that match bytes.
     */
    readonly bytes?: {
        readonly message: string;
        readonly author: string;
        readonly committer: string;
    };
}
/** Ref labels per commit id, for %d/%D. */
export type Decorations = ReadonlyMap<string, readonly string[]>;
/**
 * The parsed value of `--pretty`/`--format`.
 *
 * `kind` is a preset name, or `format`/`tformat` for a placeholder template:
 * `format` separates entries with a newline while `tformat` terminates each
 * with one, and is what a bare `%` string means.
 */
export interface LogFormat {
    readonly kind: string;
    readonly template: string | null;
}
export declare const MEDIUM: LogFormat;
/** What `log` and `show` both read off their flags to present a commit. */
export interface CommitDisplay {
    /** How the commit renders. */
    readonly pretty: LogFormat;
    /**
     * Print an abbreviated id, which `--oneline` implies and `--pretty=oneline`
     * alone does not.
     */
    readonly abbrevCommit: boolean;
    /** How dates render. */
    readonly date: DateMode;
    /** The worktree `.mailmap`. */
    readonly mailmap: readonly MailmapEntry[];
    /** Map the header identities. */
    readonly useMailmap: boolean;
    /** How the commit is labelled with its refs. */
    readonly decorate: Decoration;
}
/**
 * Read a --pretty/--format value the way git reads it.
 *
 * @throws UnsupportedPrettyError for a real git preset this build lacks
 * @throws BadPrettyError for a name git itself would refuse
 */
export declare function parsePretty(value: string): LogFormat;
/**
 * Whether rendering this format has to know the refs.
 *
 * Only `%d`/`%D` read them; git turns decorations off for piped preset
 * output, which is the only output mirage produces.
 */
export declare function needsDecorations(fmt: LogFormat): boolean;
/**
 * How many hex digits an abbreviated id needs in a repository.
 *
 * git widens the abbreviation as a repository grows, so `--oneline` on a large
 * repository prints nine characters where a fresh one prints seven, and a build
 * that always printed seven disagreed with real git on every line of every big
 * repository.
 *
 * Measured against git 2.50.1 rather than read off its source, and the boundary
 * is sharp: 16,383 packed objects abbreviate to 7 and 16,384 to 8, which is one
 * hex digit per two bits of object count, floored at git's seven. Confirmed
 * again at 20,102 (8), 70,102 (9) and 184,401 (9).
 *
 * Only packed objects count. The same 70,102 objects abbreviate to 7 while loose
 * and to 9 once packed, which is consistent with it being an estimate: a pack
 * index states its object count in its header, while counting loose objects
 * means walking 256 directories.
 *
 * @param packed how many objects the repository's packs hold
 */
export declare function abbrevLength(packed: number): number;
/**
 * Abbreviate an object id the way `--oneline` prints it.
 *
 * @param sha hex object id
 * @param length how many hex digits to keep, from abbrevLength
 */
export declare function short(sha: string, length?: number): string;
/** The first paragraph of a commit message, folded onto one line. */
export declare function subject(commit: CommitFacts): string;
/**
 * One `--oneline` row: abbreviated id then subject.
 *
 * @param commit the commit to render
 * @param length how many hex digits of the id to print
 */
export declare function oneline(commit: CommitFacts, length?: number): string;
/**
 * One commit as a block preset renders it (short/medium/full/fuller).
 *
 * Pinned against git 2.50: `medium` is the id, author, author date and
 * indented message; `short` is the id, author and indented subject; `full`
 * adds `Commit:` and drops both dates; `fuller` aligns four header lines to
 * the `AuthorDate:` column.
 *
 * @param parents the parents to print, the commit's own when null; a
 *   path-limited log prints the ones it kept, though raw prints the stored ones
 *   whatever the graph draws (git 2.47.3)
 */
export declare function presetBlock(commit: CommitFacts, kind: string, length: number, date?: DateMode, mailmap?: readonly MailmapEntry[], parents?: readonly string[] | null): string[];
/**
 * Expand a format:/tformat: template for one commit.
 *
 * The scan matches git's behaviour pinned in docker: an unknown or
 * incomplete placeholder stays verbatim (`%q` prints `%q`), `%%` is a literal
 * percent, and `%xHH` names a raw output byte (`%x80` is the single byte
 * 0x80, carried by the shell's byte-escape convention until `encodeText`
 * writes it). Explicit cursor, one pass, like the stat -c engine.
 */
export declare function renderTemplate(template: string, commit: CommitFacts, length: number, decor: Decorations | null, date?: DateMode, mailmap?: readonly MailmapEntry[], parents?: readonly string[] | null): string;
/**
 * One commit's header, as `log` and `show` print it.
 *
 * `format:` is a separator, so a single commit prints with no trailing newline
 * at all; `tformat:` terminates the entry even when it renders empty, except
 * that an empty template prints nothing, which is how `--format=` stays
 * silent. The caller encodes through `encodeText` because `%xHH` names a raw
 * byte. Pinned against git 2.37 and 2.54. A decorated preset labels the commit
 * after its id.
 *
 * @param commit the commit to render
 * @param display the invocation's presentation flags
 * @param width abbreviated id width for this repository
 * @param decor ref labels when the format asked
 */
export declare function commitHeader(commit: CommitFacts, display: CommitDisplay, width: number, decor: Decorations | null, parents?: readonly string[] | null): string;
//# sourceMappingURL=format.d.ts.map