import { Stream } from "effect"; import { ChildProcess } from "effect/process"; import { REDACTED, maskSecrets } from "./internal/redact.js"; import { redactRemoteText, remoteSecrets } from "./internal/redactRemote.js"; /** * A pure `git` invocation: the spawnable command plus the diagnostic argv the * error taxonomy is allowed to persist. * * @remarks * `command.args` holds the raw argv git actually receives; `redactedArgs` is * the same argv with every sensitive positional masked — a config value * replaced by `` entirely, and a URL's embedded userinfo (an * `https://user:token@host/...` credential) replaced by `@`. The * redaction mask lives here, on the pure constructor, because the * constructor is the one place that knows which positionals are sensitive; * the `Git` service's `classify` step persists ONLY `redactedArgs` into * `GitCommandError.args` and `GitCommandError.message`, so raw argv never * survives into an error value. For a constructor with no sensitive * positionals the two argvs are element-wise identical. * * @public */ export interface GitInvocation { /** The spawnable, cwd-less command carrying the raw argv. */ readonly command: ChildProcess.StandardCommand; /** The argv with sensitive positionals masked — the only argv diagnostics may persist. */ readonly redactedArgs: ReadonlyArray; /** * Masks, in any text, the exact secret strings the argv carries: each * whole-value secret, and every part of a secret URL that `redactedArgs` * masks — its credential segments, user, query and a masked scheme. The `Git` * service applies it to git's stderr. A closure, so the raw secrets are not * an enumerable field a log line or serializer could surface. */ readonly scrub: (text: string) => string; } /** * One argv segment: a plain string, or a sensitive positional tagged with the * mask to apply in `redactedArgs` — `"value"` replaces the whole segment, * `"url"` masks only an embedded `scheme://userinfo@` credential. */ type GitArg = string | { readonly redact: "value" | "url"; readonly value: string }; // Tags a whole-value sensitive positional (a config value that may be a secret). const secretValue = (value: string): GitArg => ({ redact: "value", value }); // Tags a URL positional whose embedded userinfo (if any) must be masked. const secretUrl = (value: string): GitArg => ({ redact: "url", value }); /** * Builds a `git` {@link GitInvocation} with the argv this package classifies * against. * * @remarks * The returned command carries neither `cwd` NOR any environment pin — every * `GitCommand` constructor produces a pure, context-free value. The caller * (the `Git` service) applies both per invocation, via `ChildProcess.setCwd` * and `ChildProcess.setEnv`, each of which returns a new command and leaves * this one unchanged. The environment pins that make git's stderr * classifiable and keep it from blocking on a prompt live in `Git.ts` * alongside the classifier and the timeout they exist to serve; one of them * is conditional on the caller's own environment, which a pure constructor * must not read. * * `extendEnv: true` is the one spawn option set here, and it is deliberately * NOT one of those pins: it declares that a git invocation inherits the * parent environment at all (git needs `PATH`, `HOME`, `SSH_AUTH_SOCK` and * the rest to function), rather than forcing any particular value. It must * be set at construction because core exposes no run-time combinator for it * — only `setCwd` and `setEnv` — and its default is owned by whichever * platform backend implements `ChildProcessSpawner`, not by core, so a * command that needs the merge must request it explicitly rather than rely * on an implementation-specific default. * * A consumer running one of these values directly gets a plain inherited * environment and no pins. That is the honest shape: such a caller is * running a custom command, and `Git`'s classification guarantees do not * travel with the argv. */ const git = (args: ReadonlyArray, stdin?: string): GitInvocation => { const raw = args.map((arg) => (typeof arg === "string" ? arg : arg.value)); const redactedArgs = args.map((arg) => typeof arg === "string" ? arg : arg.redact === "value" ? REDACTED : redactRemoteText(arg.value), ); const secrets = args.flatMap((arg) => typeof arg === "string" ? [] : arg.redact === "value" ? [arg.value] : remoteSecrets(arg.value), ); return { command: ChildProcess.make("git", raw, { extendEnv: true, // stdin is baked into the pure command value (check-ignore's --stdin // form): a single UTF-8 chunk, closed when done. Constructors without // stdin leave the option unset entirely. ...(stdin !== undefined ? { stdin: Stream.make(new TextEncoder().encode(stdin)) } : {}), }), redactedArgs, scrub: (text) => maskSecrets(text, secrets), }; }; /** * The `git log` record format: a `\x1e` record opener followed by the five * NUL-joined header fields the log listing decodes. * * `--name-only` output carries no other unambiguous record boundary — a * commit's path lines and the next commit's header are both just bytes — so * the separator is emitted by the format itself rather than inferred. */ const LOG_FORMAT = "--format=%x1e%H%x00%aI%x00%cI%x00%an%x00%ae"; /** * Which configuration file a read is scoped to. * * @remarks * Omitted, git reads the MERGED configuration — repository-local plus global * plus system — which is what a consumer wants for "what is the effective * value" and precisely wrong for "what does THIS checkout declare". A globally * set key otherwise shadows a decision that is really about one repository, and * an enumerate-then-remove flow reads at a different scope than * `configRemoveSection` writes at. * * @public */ export type GitConfigScope = "local" | "global" | "system" | "worktree"; /** The scope flag, or nothing for the merged read. */ const scopeArgs = (scope: GitConfigScope | undefined): ReadonlyArray => scope === undefined ? [] : [`--${scope}`]; /** * The untracked-files mode of `git status` — git's `--untracked-files` flag. * * @remarks * - `"all"` lists every untracked file individually, honouring `.gitignore`. * The one `??` path that still ends in `/` under it is an untracked nested * repository (`vendor/inner/`), which git never descends into. * - `"normal"` is git's own default: a directory holding only untracked files * collapses to ONE `?? dir/` entry, so a `??` path ending in `/` is a * directory, never a file. * - `"no"` reports no untracked files at all. * * Commit builders want `"all"`: a collapsed `dir/` entry read as a file fails * the read that follows it. * * @public */ export type GitUntrackedFilesMode = "normal" | "all" | "no"; // Renders a stash index into git's reflog-style stash ref. The interpolation is // injection-safe by construction: the service refuses a non-integer index // before any spawn, and an integer cannot begin with `-`... a negative integer // can, which is exactly why the service guard requires a NON-NEGATIVE integer. const stashRef = (index: number): string => `stash@{${index}}`; /** * Pure constructors for the `git` {@link GitInvocation} values this package * spawns. * * @remarks * Every constructor returns a cwd-less, argv-only {@link GitInvocation} — no * spawning, no working directory baked in. `Git` applies the working * directory per call with `ChildProcess.setCwd` on `invocation.command` and * owns the actual spawn, timeout, and error classification. * * **Redaction policy.** A constructor whose argv carries a sensitive * positional — a config value (`configSet`), or a URL that may embed * userinfo (the remote of `fetch`, `fetchUnshallow`, `lsRemote`, `push` and * `pull`, and the url of `submoduleAdd`, `submoduleSetUrl`, `remoteAdd` and * `remoteSetUrl`) — * masks it in {@link GitInvocation.redactedArgs}: a config value becomes * `` wholesale, a URL keeps everything but its `userinfo@` * component. The `Git` service persists only the redacted argv in error * values, and its span annotations carry stable identifiers only (`cwd`, * keys, paths, remote/ref names) — never config values, never URLs. * * @public */ export class GitCommand { private constructor() {} /** * `git show :` — the contents of `path` as it existed at `ref`, * without checking anything out. */ static readonly show = (ref: string, path: string): GitInvocation => git(["show", `${ref}:${path}`]); /** * `git diff` with the output-shaping flags pinned, ` -- ` — the * patch text for one file, the working tree against `ref`. * * @remarks * Explicit flags override the config keys that change the bytes: color, * external diff, textconv, the `a/` `b/` prefixes (`diff.noprefix`, * `diff.mnemonicPrefix`), `diff.relative`, `diff.context` and * `diff.algorithm`. A path that matches nothing exits 0 with empty output, * like an unchanged one. */ static readonly diffFile = (ref: string, path: string): GitInvocation => git([ "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--src-prefix=a/", "--dst-prefix=b/", "--no-relative", "-U3", "--inter-hunk-context=0", "--indent-heuristic", "--submodule=short", "--diff-algorithm=myers", ref, "--", path, ]); /** * `git ls-tree -r -z [-- ...]` — every path in the tree at * `ref`, recursively, NUL-terminated, optionally scoped to `pathspec`. * * @remarks * `-z` is load-bearing: git paths may themselves contain newlines, so the * caller must split on `"\0"`, never on `"\n"`. When `pathspec` is provided, * a literal `--` separator is inserted before the pathspec entries to prevent * git from interpreting pathspec values as options. */ static readonly lsTree = (ref: string, pathspec: ReadonlyArray = []): GitInvocation => git(["ls-tree", "-r", "-z", ref, ...(pathspec.length > 0 ? ["--", ...pathspec] : [])]); /** * `git cat-file -e ` — checks whether `ref` resolves to an existing * object, without printing it. A non-zero exit means the ref does not exist. */ static readonly refExists = (ref: string): GitInvocation => git(["cat-file", "-e", ref]); /** * `git merge-base ` — the best common ancestor commit of `a` and `b`. * * @remarks * Two refs with NO common ancestor (disjoint histories) exit 1 with * silent stderr. One builder backs both service members: `Git.mergeBase` * surfaces that shape as a loud `GitCommandError` (absence is * exceptional), while `Git.mergeBaseOption` degrades it to `Option.none` * (a probe answer). The argv is identical either way. */ // One builder backs BOTH Git.mergeBase (loud on no ancestor) and // Git.mergeBaseOption (silent exit 1 → Option.none) — the argv is identical; // only the service's classify kind differs. static readonly mergeBase = (a: string, b: string): GitInvocation => git(["merge-base", a, b]); /** * `git diff --name-only -z [--relative] ...` — the paths that * differ between the merge base of `base` and `head`, and `head` itself, * NUL-terminated. * * @remarks * `-z` is load-bearing here too, for the same reason as {@link GitCommand.lsTree}: split * the output on `"\0"`, never on `"\n"`. * * The relative flag is **explicit in both branches** — `--relative` when * `relative` is true, `--no-relative` when false — never omitted. git honors a * configured `diff.relative=true` when no flag is passed, so an omitted flag * would silently yield cwd-relative paths on such a machine even for * `relative: false`, misaligning with {@link GitCommand.untrackedFiles}'s * repo-root base and breaking `Git.workingChanges`' dedup in a nested workspace. * `--relative` scopes the report to `cwd` (a workspace nested inside a larger * repository); `--no-relative` overrides any `diff.relative` config and reports * paths from the repository top-level. */ static readonly changedFiles = (base: string, head: string, relative = false): GitInvocation => git(["diff", "--name-only", "-z", relative ? "--relative" : "--no-relative", `${base}...${head}`]); /** * `git diff --name-only -z (--relative | --no-relative)` — the paths with * unstaged working-tree changes (the working tree against the index), * NUL-terminated. * * @remarks * `relative` behaves as it does for {@link GitCommand.changedFiles}, including the * explicit-flag-in-both-branches rule: `--no-relative` is passed for * `relative: false` so a configured `diff.relative=true` cannot silently make the * output cwd-relative. */ static readonly unstagedChanges = (relative = false): GitInvocation => git(["diff", "--name-only", "-z", relative ? "--relative" : "--no-relative"]); /** * `git diff --name-only -z (--relative | --no-relative) --cached` — the paths * staged for the next commit (the index against `HEAD`), NUL-terminated. * * @remarks * `relative` behaves as it does for {@link GitCommand.changedFiles}, including the * explicit `--no-relative` on the `relative: false` branch. */ static readonly stagedChanges = (relative = false): GitInvocation => git(["diff", "--name-only", "-z", relative ? "--relative" : "--no-relative", "--cached"]); /** * `git ls-files --others --exclude-standard -z [--full-name]` — the untracked * paths git is not ignoring, NUL-terminated. * * @remarks * `ls-files` reports paths relative to `cwd` by default, matching the * `--relative` diffs. When `relative` is `false`, `--full-name` makes it emit * repo-root-relative paths instead, so the untracked half shares a base with the * un-`--relative` diffs — otherwise `Git.workingChanges`'s union would dedup two * spellings of one file from a nested `cwd`. */ static readonly untrackedFiles = (relative = false): GitInvocation => git(["ls-files", "--others", "--exclude-standard", "-z", ...(relative ? [] : ["--full-name"])]); /** * `git rev-parse --verify ` — resolves `ref` to its full object id, or * fails if `ref` does not resolve. */ static readonly revParse = (ref: string): GitInvocation => git(["rev-parse", "--verify", ref]); /** * Mutating: `git checkout [--detach] ` — moves the working tree (and, for * a branch ref, `HEAD`) to `ref`. When `detach` is true, checks out the ref in * detached-HEAD state. */ static readonly checkout = (ref: string, detach = false): GitInvocation => git(["checkout", ...(detach ? ["--detach"] : []), ref]); /** * Mutating: `git fetch [--depth ] [--unshallow] [tag] ` — * fetches the given ref from a remote, optionally with a depth limit, the * `--unshallow` mode, and the `tag` keyword. * * @remarks * `ref` may also be a full refspec (`src:dst`, optionally `+`-prefixed) — * it is passed through VERBATIM, never transformed. That matters under a * single-branch clone (`actions/checkout`'s default): a bare-ref fetch * there updates `FETCH_HEAD` only and never creates the remote-tracking * ref, so `+refs/heads/:refs/remotes/origin/` is the only spelling * that materializes `origin/`. * * `unshallow` is a distinct MODE like {@link GitCommand.fetchUnshallow}'s: * git rejects it in a non-shallow repository and rejects it alongside * `--depth`. `remote` may be a URL as well as a remote name; an embedded * `userinfo@` credential is masked in {@link GitInvocation.redactedArgs}. */ static readonly fetch = ( remote: string, ref: string, depth?: number, tag = false, unshallow = false, ): GitInvocation => git([ "fetch", ...(depth !== undefined ? ["--depth", String(depth)] : []), ...(unshallow ? ["--unshallow"] : []), secretUrl(remote), ...(tag ? ["tag"] : []), ref, ]); /** * Mutating: `git fetch --unshallow ` — converts a shallow clone * into a complete one by fetching the missing history. * * @remarks * `--unshallow` is a distinct MODE, not a depth value: git rejects it * outright in a repository that is not shallow, with * `--unshallow on a complete repository does not make sense`, so it * cannot be expressed as `fetch`'s `depth` option. The caller decides * whether to run it — probe with `Git.isShallow` first. * * `remote` may be a URL as well as a remote name; an embedded `userinfo@` * credential is masked in {@link GitInvocation.redactedArgs}. */ static readonly fetchUnshallow = (remote = "origin"): GitInvocation => git(["fetch", "--unshallow", secretUrl(remote)]); /** * `git rev-parse --is-shallow-repository` — prints `true` when the * repository is a shallow clone, `false` otherwise. * * @remarks * A dedicated probe constructor, deliberately separate from * {@link GitCommand.revParse}: `revParse` takes a REF and resolves it, * while this takes nothing and answers a repository-shape question. * Folding the flag into `revParse` would make that constructor * sometimes-takes-a-ref, sometimes-takes-a-flag. */ static readonly isShallow = (): GitInvocation => git(["rev-parse", "--is-shallow-repository"]); /** * Mutating: `git fetch --deepen= ` — extends a shallow clone's * history by `by` more commits behind its current boundary. * * @remarks * `--deepen` counts from the existing shallow boundary, not from the tip: * `--depth` would cut the history back to `by` commits, which is the opposite * of what a caller walking backwards past the boundary needs. * * `remote` may be a URL as well as a remote name; an embedded `userinfo@` * credential is masked in {@link GitInvocation.redactedArgs}. */ static readonly fetchDeepen = (by: number, remote = "origin"): GitInvocation => git(["fetch", `--deepen=${by}`, secretUrl(remote)]); /** * `git log --diff-filter=AC --follow --max-count=1 --format=%H%x00%P -- ` * — the newest commit that added (or copied in) `path`, followed back across * renames, printed as `\0`. * * @remarks * The same argv as `@changesets/git`'s `getCommitsThatAddFiles`, except for * the literal `--` before the path. Without it, git treats a path absent from * the working tree as an ambiguous revision and fails, and a path beginning * with `-` is parsed as an option. `--follow` takes exactly one path, so this * runs once per path. * * The parent list is what tells a real add apart from a shallow clone's * boundary commit. Git reports the boundary commit as adding every file it * contains, and it prints no parents for it, because the clone has none. */ static readonly addingCommit = (path: string): GitInvocation => git(["log", "--diff-filter=AC", "--follow", "--max-count=1", "--format=%H%x00%P", "--", path]); /** * Mutating: `git reset --soft|--mixed|--hard []` — moves `HEAD` (and, * per mode, the index and working tree) to `ref`. * * @remarks * The mode flag is always explicit — `--mixed` is emitted for the default * rather than omitted — so the argv states what runs. `ref` may be any * commit-ish, including a gitlink sha. */ static readonly reset = (mode: "soft" | "mixed" | "hard" = "mixed", ref?: string): GitInvocation => git(["reset", `--${mode}`, ...(ref !== undefined ? [ref] : [])]); /** * Mutating: `git clean --force [-d] [-x] [-- ...]` — deletes * untracked files from the working tree. * * @remarks * `--force` is unconditional: this constructor exists so a consumer can * restore a tree to a known state (e.g. before retrying a non-idempotent * operation), and without `--force` git refuses to clean at all under the * default `clean.requireForce` config — a clean that silently did nothing * would hand the retry the same dirty tree. `-d` removes untracked * directories too; `-x` removes ignored files as well. The literal `--` * separator makes the optional pathspec injection-safe by construction. */ static readonly clean = (directories = false, ignored = false, paths: ReadonlyArray = []): GitInvocation => git([ "clean", "--force", ...(directories ? ["-d"] : []), ...(ignored ? ["-x"] : []), ...(paths.length > 0 ? ["--", ...paths] : []), ]); /** * Mutating: `git restore [--source ] [--staged] [--worktree] -- ` * — restores the given paths from the index (or from `source`), the * `checkout -- `-shaped operation. * * @remarks * This is a separate constructor precisely because {@link GitCommand.checkout}'s * service guard refuses `--` and option-like refs by design — `restore` is * git's own verb for pathspec restoration, and its paths always sit behind * a literal `--`, so they are injection-safe by construction. With neither * `staged` nor `worktree` set, git defaults to restoring the working tree. */ static readonly restore = ( paths: ReadonlyArray, source?: string, staged = false, worktree = false, ): GitInvocation => git([ "restore", ...(source !== undefined ? ["--source", source] : []), ...(staged ? ["--staged"] : []), ...(worktree ? ["--worktree"] : []), "--", ...paths, ]); /** * Mutating: `git branch [-f] []`, or * `git checkout (-b | -B) []` when `checkout` is true — * creates a branch, optionally from an explicit start point, optionally * switching to it, optionally force-resetting an existing branch. * * @remarks * Branch creation is a branch-member concern, NOT a widening of * {@link GitCommand.checkout}: `checkout`'s contract stays "move to an * existing ref" and its option-like-ref refusal stays intact. The `-b` / * `-B` here is this constructor's own literal, never caller data. * * `force` with `checkout` exists because the delete-then-create longhand * (`branch -D` swallowed, then `checkout -b`) papers over a real edge: * `git branch -D` refuses to delete the currently checked-out branch, * while `checkout -B` resets it fine — one invocation handles both * states. */ static readonly branchCreate = (name: string, startPoint?: string, checkout = false, force = false): GitInvocation => checkout ? git(["checkout", force ? "-B" : "-b", name, ...(startPoint !== undefined ? [startPoint] : [])]) : git(["branch", ...(force ? ["-f"] : []), name, ...(startPoint !== undefined ? [startPoint] : [])]); /** * Mutating: `git branch -d ` (or `-D` when `force` is true) — * deletes a local branch. * * @remarks * The default `-d` refuses to delete a branch not fully merged — a typed * failure, which is usually the honest answer. `force: true` emits `-D` * and deletes regardless. */ static readonly branchDelete = (name: string, force = false): GitInvocation => git(["branch", force ? "-D" : "-d", name]); /** * Mutating: * `git submodule update [--init] [--checkout] [--remote] [--no-fetch] [--recursive] [--force] [--depth ] [-- ...]` * — updates registered submodules, optionally initializing them, with an * optional depth limit, and scoped to specific paths. The literal `--` * separator makes the pathspec injection-safe by construction. * * @remarks * `options.checkout` is the documented override for a * `submodule..update = none` configuration — without it, an update of * such a submodule silently skips it (git reports success and checks out * nothing). `options.fetch` accepts only the literal `false` (emitting * `--no-fetch`): git's default already fetches and offers no positive * `--fetch` spelling, so `true` would be an unrepresentable no-op. * `options.remote` tracks the remote branch's tip instead of the * superproject's recorded sha; `options.recursive` descends into nested * submodules; `options.force` discards local changes in the submodule * working tree (and re-checks-out even when the recorded sha is current). */ static readonly submoduleUpdate = ( init = false, depth?: number, paths: ReadonlyArray = [], options: { readonly checkout?: boolean; readonly remote?: boolean; readonly fetch?: false; readonly recursive?: boolean; readonly force?: boolean; } = {}, ): GitInvocation => git([ "submodule", "update", ...(init ? ["--init"] : []), ...(options.checkout ? ["--checkout"] : []), ...(options.remote ? ["--remote"] : []), ...(options.fetch === false ? ["--no-fetch"] : []), ...(options.recursive ? ["--recursive"] : []), ...(options.force ? ["--force"] : []), ...(depth !== undefined ? ["--depth", String(depth)] : []), ...(paths.length > 0 ? ["--", ...paths] : []), ]); /** * Mutating: `git submodule add [--depth ] -- ` — registers and * initializes a new submodule. The literal `--` separator makes the url and path * injection-safe by construction. * * @remarks * An embedded `userinfo@` credential in `url` is masked in * {@link GitInvocation.redactedArgs}. */ static readonly submoduleAdd = (url: string, path: string, depth?: number): GitInvocation => git(["submodule", "add", ...(depth !== undefined ? ["--depth", String(depth)] : []), "--", secretUrl(url), path]); /** * Mutating: `git sparse-checkout set (--cone | --no-cone) ` — configures * which paths are checked out in a sparse repository. The cone flag is explicit in both * branches — `--cone` when `cone` is true, `--no-cone` when false — to prevent git's * default from silently changing the behavior. */ static readonly sparseCheckoutSet = (patterns: ReadonlyArray, cone: boolean): GitInvocation => git(["sparse-checkout", "set", cone ? "--cone" : "--no-cone", ...patterns]); /** * Mutating: `git config [-f ] ` — writes a configuration value, * optionally into an explicit configuration file (e.g., `.gitmodules`). * * @remarks * `value` may be a secret (a token, a credential-bearing URL), so it is * masked wholesale — as `` — in * {@link GitInvocation.redactedArgs}. The key and file stay visible: they * are stable identifiers, and they are what a caller debugging a failed * write actually needs. */ static readonly configSet = (key: string, value: string, file?: string): GitInvocation => git(["config", ...(file !== undefined ? ["-f", file] : []), key, secretValue(value)]); /** * Mutating: `git add -- ` — stages the given paths for commit. The literal * `--` separator makes the pathspec injection-safe by construction. */ static readonly add = (paths: ReadonlyArray): GitInvocation => git(["add", "--", ...paths]); /** * `git diff --name-status -z (--relative | --no-relative) [ | ...]` * — the changed paths WITH their one-letter status codes, NUL-terminated. * * @remarks * With `head` omitted this is the single-argument diff form: the working tree * (staged + unstaged) against `base` — NOT a two-ref range. With `head` * present it is the familiar `base...head` merge-base form, matching * {@link GitCommand.changedFiles}. `-z` and the explicit relative flag follow * the same rules as {@link GitCommand.changedFiles}. In `-z` mode a rename or * copy entry is THREE NUL tokens: `R`, the old path, the new path. */ static readonly nameStatus = (base: string, head: string | undefined, relative = false): GitInvocation => git([ "diff", "--name-status", "-z", relative ? "--relative" : "--no-relative", head === undefined ? base : `${base}...${head}`, ]); /** * `git symbolic-ref --quiet --short refs/remotes//HEAD` — the name of * the default branch on the given remote, or empty string / exit 1 if unset. * * @remarks * `--quiet` suppresses error messages; the exit code alone signals success * (0) or "symbolic-ref does not exist" (1). The contract is "does the remote * have a HEAD?" — an unset symbolic ref exits 1 silently, which `Git.defaultBranch` * degrades to `Option.none()` rather than a typed error. `symbolic-ref` is a * purely local ref lookup; it never touches the network. */ static readonly defaultBranch = (remote = "origin"): GitInvocation => git(["symbolic-ref", "--quiet", "--short", `refs/remotes/${remote}/HEAD`]); /** * `git rev-parse --abbrev-ref HEAD` — the name of the branch `HEAD` is * pointing to. * * @remarks * Returns `"HEAD"` (detached state), `""` (an attached branch), or * fails if the repository has no commits. */ static readonly currentBranch = (): GitInvocation => git(["rev-parse", "--abbrev-ref", "HEAD"]); /** * `git rev-parse --show-toplevel` — the filesystem path to the root of the * enclosing git repository. */ static readonly repoRoot = (): GitInvocation => git(["rev-parse", "--show-toplevel"]); /** * `git rev-parse --path-format=absolute --git-common-dir` — the absolute, * symlink-resolved path of the directory a repository and all of its linked * worktrees share. * * @remarks * Without `--path-format=absolute` git prints this relative to the working * directory in a plain checkout (`.git`) but absolute from inside a linked * worktree, so two answers cannot be compared as strings. The flag needs * git 2.31 or later. */ static readonly commonDir = (): GitInvocation => git(["rev-parse", "--path-format=absolute", "--git-common-dir"]); /** * `git rev-parse --show-toplevel --path-format=absolute --git-common-dir` — * a working tree's physical toplevel and its repository's common * directory, one per line, in one spawn. * * @remarks * `--path-format` applies only to the options after it, so the toplevel * (always absolute) comes first. Both answers are symlink-resolved by git. * Outside a working tree — a bare repository, or a directory inside * `.git` — git exits 128 with `this operation must be run in a work tree`. * The flag needs git 2.31 or later; an older git echoes it as a third line. */ static readonly treeIdentity = (): GitInvocation => git(["rev-parse", "--show-toplevel", "--path-format=absolute", "--git-common-dir"]); /** * `git symbolic-ref --quiet HEAD` — the full refname `HEAD` points at * (`refs/heads/`), or a silent exit 1 when `HEAD` is detached. * * @remarks * An unborn branch still answers its refname: `HEAD` names the branch * before the branch has a commit. */ static readonly headRef = (): GitInvocation => git(["symbolic-ref", "--quiet", "HEAD"]); /** * `git for-each-ref --format=%(refname)%00%(upstream)%00%(upstream:short)%00%(upstream:track,nobracket) ` * — a local branch's upstream as a NUL-separated record: the branch * refname, the upstream's full refname, its short name, and the tracking * state (`gone`, `ahead N`, `behind N`, `ahead N, behind M`, or empty). * * @remarks * Unlike `rev-parse @{upstream}`, this still reports an upstream whose * remote-tracking ref was deleted (`gone`), and its short name is the same * string `rev-parse --abbrev-ref @{upstream}` answers. `branchRef` is a full * refname (`refs/heads/main`); a pattern also matches refs below it, so the * caller keeps only the exact record. The tracking state walks history, as * `git status` does. */ static readonly upstream = (branchRef: string): GitInvocation => git([ "for-each-ref", "--format=%(refname)%00%(upstream)%00%(upstream:short)%00%(upstream:track,nobracket)", branchRef, ]); /** * `git log -1 --format=%H%x00%G?%x00%B ` — a NUL-separated triple: the * full commit hash, the GPG trust level, and the full commit body (message), * all untrimmed. * * @remarks * `%H` is the full object id (40-char sha1, or sha256 if configured). * `%x00` is a literal NUL byte (the separator). `%G?` is the GPG trust level * (`G` = good signature, `B` = bad, `U` = untrusted, `X` = expired, `Y` = * expired key, `R` = revoked key, `E` = error, or `N` = not signed). * `%B` is the full body, **untrimmed** — it includes leading/trailing * whitespace — so the caller must decide whether to trim it. Splits on the * two `\x00` bytes to extract all three values. */ static readonly commitInfo = (ref = "HEAD"): GitInvocation => git(["log", "-1", "--format=%H%x00%G?%x00%B", ref]); /** * `git log -z --format=%x1e%H%x00%aI%x00%cI%x00%an%x00%ae --name-only` — * a commit listing carrying each commit's sha, both ISO dates, its author * identity and the paths it touched. Four optional flags follow, in this * order: `--follow`, `--diff-merges=first-parent`, `--max-count=N`, then * the `--` separator and the pathspec. * * @remarks * `-z` is unconditional and does two things at once: it terminates the * `--format` output with a NUL instead of a newline, and it makes * `--name-only` emit paths RAW — no C-style quoting — so a path containing * a space, a quote or a newline comes back verbatim and `core.quotePath` * never enters the picture. * * `%x1e` opens every record because `--name-only` output has no other * unambiguous record boundary. Each record is then * `\0\0\0\0\0` * followed, when the commit touched anything, by `\n` and one * NUL-terminated path per changed file. * * `--follow` requires exactly one path — git's own restriction, enforced * pre-spawn by `Git.log`. Without `--diff-merges=first-parent` a merge * commit contributes a record with NO path lines, which is git's default * and not an anomaly. */ static readonly log = ( paths: ReadonlyArray = [], follow = false, limit?: number, firstParentDiffMerges = false, ): GitInvocation => git([ "log", "-z", LOG_FORMAT, "--name-only", ...(follow ? ["--follow"] : []), ...(firstParentDiffMerges ? ["--diff-merges=first-parent"] : []), ...(limit !== undefined ? [`--max-count=${limit}`] : []), ...(paths.length > 0 ? ["--", ...paths] : []), ]); /** * `git config --get ` — the value of the given git config key, or empty * string / exit 1 if unset. */ static readonly configGet = (key: string, scope?: GitConfigScope): GitInvocation => git(["config", ...scopeArgs(scope), "--get", key]); /** * `git remote get-url ` — the fetch URL of the given remote. A * missing remote exits non-zero with a "No such remote" stderr shape, which * the `Git` service degrades to `Option.none`, never a typed error. * * @remarks * git applies `url..insteadOf` rewrites to this URL; the value as * configured is {@link GitCommand.configGet} of `remote..url`. */ static readonly remoteUrl = (remote = "origin"): GitInvocation => git(["remote", "get-url", remote]); /** * `git status --porcelain -z --untracked-files=` — the porcelain * (stable, machine-readable) short status of every modified file in the * working tree, NUL-terminated. `untrackedFiles` defaults to `"all"`. * * @remarks * `-z` is load-bearing here too, for the same reason as * {@link GitCommand.lsTree}: split the output on `"\0"`, never on `"\n"`. * Each entry is a pair of status codes followed by a space and the path. * * The untracked-files flag is always explicit, `"all"` included, so the * argv states what runs: omitted, git falls back to the caller's * `status.showUntrackedFiles` config, and a `no` there silently drops every * untracked file from the listing. Only the untracked axis is pinned — * other config, such as `status.renames`, still shapes the output. See * {@link GitUntrackedFilesMode} for what each mode lists. */ static readonly status = (untrackedFiles: GitUntrackedFilesMode = "all"): GitInvocation => git(["status", "--porcelain", "-z", `--untracked-files=${untrackedFiles}`]); /** * `git submodule status [--recursive] [-- ...]` — one line per * registered submodule: a state prefix, the checked-out (or gitlink) sha, * the path, and — when the submodule is initialized — a `git describe` * suffix in parentheses. * * @remarks * `git submodule status` has no `-z` mode, so its output is line-based — * the one path-emitting constructor in this package that cannot follow * the `-z` rule. A submodule path containing a newline would corrupt the * parse; accepted as a git-imposed limitation. */ static readonly submoduleStatus = (paths: ReadonlyArray = [], recursive = false): GitInvocation => git(["submodule", "status", ...(recursive ? ["--recursive"] : []), ...(paths.length > 0 ? ["--", ...paths] : [])]); /** * Mutating: `git submodule init [-- ...]` — registers the * submodules from `.gitmodules` into `.git/config` (all of them, or only * `paths`), without cloning or checking anything out. */ static readonly submoduleInit = (paths: ReadonlyArray = []): GitInvocation => git(["submodule", "init", ...(paths.length > 0 ? ["--", ...paths] : [])]); /** * Mutating: `git submodule deinit [--force] (--all | -- ...)` — * unregisters submodules: clears their working trees and removes their * `.git/config` registration. The literal `--` separator makes the * pathspec injection-safe by construction. */ static readonly submoduleDeinit = (paths: ReadonlyArray, all = false, force = false): GitInvocation => git(["submodule", "deinit", ...(force ? ["--force"] : []), ...(all ? ["--all"] : ["--", ...paths])]); /** * Mutating: `git submodule sync [--recursive] [-- ...]` — * re-copies each submodule's URL from `.gitmodules` into `.git/config` * (and into the submodule's own `remote.origin.url`), so a `.gitmodules` * URL change actually reaches git's live configuration. */ static readonly submoduleSync = (paths: ReadonlyArray = [], recursive = false): GitInvocation => git(["submodule", "sync", ...(recursive ? ["--recursive"] : []), ...(paths.length > 0 ? ["--", ...paths] : [])]); /** * Mutating: `git submodule set-url -- ` — rewrites the * submodule's URL in `.gitmodules` and synchronizes it into * `.git/config`. The literal `--` separator makes the path and url * injection-safe by construction. * * @remarks * An embedded `userinfo@` credential in `url` is masked in * {@link GitInvocation.redactedArgs}. */ static readonly submoduleSetUrl = (path: string, url: string): GitInvocation => git(["submodule", "set-url", "--", path, secretUrl(url)]); /** * Mutating: `git submodule set-branch (--branch | --default) -- ` * — records (or clears, when `branch` is omitted) the branch a submodule * tracks in `.gitmodules`. The literal `--` separator makes the path * injection-safe by construction. */ static readonly submoduleSetBranch = (path: string, branch?: string): GitInvocation => git(["submodule", "set-branch", ...(branch === undefined ? ["--default"] : ["--branch", branch]), "--", path]); /** * Mutating: `git submodule absorbgitdirs [-- ...]` — moves each * submodule's embedded `.git` directory into the superproject's * `.git/modules/` and leaves a gitfile pointer behind. */ static readonly submoduleAbsorbgitdirs = (paths: ReadonlyArray = []): GitInvocation => git(["submodule", "absorbgitdirs", ...(paths.length > 0 ? ["--", ...paths] : [])]); /** * Mutating: `git submodule foreach [--recursive] ` — runs a shell * command in every checked-out submodule. `command` is a single shell * string, evaluated by git in each submodule's directory; it can mutate * anything, which is why the constructor is marked mutating regardless of * what the command does. * * @remarks * This is the ONE constructor whose argument cannot be made injection-safe * by construction: git evaluates `command` with `sh -c`, so every character * of it is shell code — a `--` separator or quoting cannot help. Callers * must treat `command` as a trusted literal and never interpolate untrusted * data into it. */ static readonly submoduleForeach = (command: string, recursive = false): GitInvocation => git(["submodule", "foreach", ...(recursive ? ["--recursive"] : []), command]); /** * `git ls-remote [--heads] [--tags] [...]` — the refs a * remote advertises (sha + refname), optionally filtered to branch heads, * tags, and/or shell-glob patterns. * * @remarks * A read that talks to the NETWORK, not to the local repository — the one * non-mutating constructor in this package that does. An embedded * `userinfo@` credential in `remote` is masked in * {@link GitInvocation.redactedArgs}. An annotated tag advertises two * entries: `refs/tags/` (the tag object) and `refs/tags/^{}` * (the peeled commit). */ static readonly lsRemote = ( remote: string, heads = false, tags = false, patterns: ReadonlyArray = [], ): GitInvocation => git(["ls-remote", ...(heads ? ["--heads"] : []), ...(tags ? ["--tags"] : []), secretUrl(remote), ...patterns]); /** * Mutating: `git remote add ` — registers a new remote. * * @remarks * An embedded `userinfo@` credential in `url` is masked in * {@link GitInvocation.redactedArgs}. */ static readonly remoteAdd = (name: string, url: string): GitInvocation => git(["remote", "add", name, secretUrl(url)]); /** * Mutating: `git remote remove ` — deletes a remote and its * remote-tracking refs and configuration. */ static readonly remoteRemove = (name: string): GitInvocation => git(["remote", "remove", name]); /** * Mutating: `git remote set-url ` — rewrites a remote's fetch * URL. * * @remarks * An embedded `userinfo@` credential in `url` is masked in * {@link GitInvocation.redactedArgs}. */ static readonly remoteSetUrl = (name: string, url: string): GitInvocation => git(["remote", "set-url", name, secretUrl(url)]); /** * Mutating: `git stash push [--include-untracked] [-m ] [-- ...]` * — saves the working tree (and index) state onto the stash stack. The * literal `--` separator makes the optional pathspec injection-safe by * construction; the message rides behind `-m`, which git consumes as a * value even when it begins with `-`. */ static readonly stashPush = ( message?: string, includeUntracked = false, paths: ReadonlyArray = [], ): GitInvocation => git([ "stash", "push", ...(includeUntracked ? ["--include-untracked"] : []), ...(message !== undefined ? ["-m", message] : []), ...(paths.length > 0 ? ["--", ...paths] : []), ]); /** * Mutating: `git stash pop [stash@{n}]` — applies a stash entry and drops * it on success. The stash ref is rendered from an INTEGER index by this * package, never caller text. */ static readonly stashPop = (index?: number): GitInvocation => git(["stash", "pop", ...(index !== undefined ? [stashRef(index)] : [])]); /** * Mutating: `git stash apply [stash@{n}]` — applies a stash entry and * keeps it on the stack. The stash ref is rendered from an INTEGER index * by this package, never caller text. */ static readonly stashApply = (index?: number): GitInvocation => git(["stash", "apply", ...(index !== undefined ? [stashRef(index)] : [])]); /** * Mutating: `git stash drop [stash@{n}]` — deletes a stash entry without * applying it. The stash ref is rendered from an INTEGER index by this * package, never caller text. */ static readonly stashDrop = (index?: number): GitInvocation => git(["stash", "drop", ...(index !== undefined ? [stashRef(index)] : [])]); /** * `git stash list -z --format=%gd%x1f%H%x1f%gs` — every stash entry as a * NUL-terminated record of unit-separated fields: the reflog selector * (`stash@{0}`), the stash commit sha, and the reflog subject. * * @remarks * The `%x1f` (ASCII unit separator) field separator plus `-z` record * terminator keeps the parse split-safe: a stash message cannot contain * either byte (reflog subjects are single-line). */ static readonly stashList = (): GitInvocation => git(["stash", "list", "-z", "--format=%gd%x1f%H%x1f%gs"]); /** * `git branch --list [--remotes | --all] --format=%(HEAD)%00%(refname:short)%00%(objectname)` * — every branch as a NUL-separated triple: the current-branch marker, the * short name, and the tip sha. * * @remarks * Records are newline-separated, which is split-safe here: git refnames * cannot contain a newline (or a space), so the only NUL bytes are the * format's own field separators. `all` wins over `remotes` when both are * set. */ static readonly branchList = (remotes = false, all = false): GitInvocation => git([ "branch", "--list", ...(all ? ["--all"] : remotes ? ["--remotes"] : []), "--format=%(HEAD)%00%(refname:short)%00%(objectname)", ]); /** * Mutating: `git tag [--force] [-m ] []` — creates a * lightweight tag, or an annotated one when `message` is given (`-m` * implies `-a`). */ static readonly tagCreate = (name: string, ref?: string, message?: string, force = false): GitInvocation => git([ "tag", ...(force ? ["--force"] : []), ...(message !== undefined ? ["-m", message] : []), name, ...(ref !== undefined ? [ref] : []), ]); /** Mutating: `git tag --delete ` — deletes a local tag. */ static readonly tagDelete = (name: string): GitInvocation => git(["tag", "--delete", name]); /** * `git tag --list []` — tag names, optionally filtered by a * shell-glob pattern, one per line (refnames cannot contain newlines). */ static readonly tagList = (pattern?: string): GitInvocation => git(["tag", "--list", ...(pattern !== undefined ? [pattern] : [])]); /** * `git for-each-ref --format=%(refname)%00%(objectname)%00%(objecttype) [...]` * — every matching ref as a NUL-separated triple: full refname, sha, and * object type. * * @remarks * The format is this package's own fixed triple — the parse contract and * the argv are decided together, so the format string is a constructor * literal, never caller data. An annotated tag's `objecttype` is `tag` * (the tag object), not `commit`. */ static readonly forEachRef = (patterns: ReadonlyArray = []): GitInvocation => git(["for-each-ref", "--format=%(refname)%00%(objectname)%00%(objecttype)", ...patterns]); /** * `git rev-list [--max-count=] [--first-parent] ` — commit * shas reachable from the ref (or range, e.g. `main..feat`), newest first. */ static readonly revList = (ref: string, limit?: number, firstParent = false): GitInvocation => git([ "rev-list", ...(limit !== undefined ? [`--max-count=${limit}`] : []), ...(firstParent ? ["--first-parent"] : []), ref, ]); /** * Mutating: `git commit [--all] [--allow-empty] [--amend] [--author=] -m ` * — records a commit. The message always rides argv behind `-m` (git * consumes it as a value even when it begins with `-`); committer identity * comes from the caller's environment — this constructor sets no * `GIT_AUTHOR_*`/`GIT_COMMITTER_*` variables, and the optional `author` * override is the fused `--author=` form. */ static readonly commit = ( message: string, all = false, allowEmpty = false, amend = false, author?: string, ): GitInvocation => git([ "commit", ...(all ? ["--all"] : []), ...(allowEmpty ? ["--allow-empty"] : []), ...(amend ? ["--amend"] : []), ...(author !== undefined ? [`--author=${author}`] : []), "-m", message, ]); /** * Mutating: `git push [--force | --force-with-lease] [--tags] [--set-upstream] []` * — updates remote refs. * * @remarks * `remote` may be a URL as well as a remote name; an embedded `userinfo@` * credential is masked in {@link GitInvocation.redactedArgs}. */ static readonly push = ( remote: string, refspec?: string, force = false, forceWithLease = false, tags = false, setUpstream = false, ): GitInvocation => git([ "push", ...(force ? ["--force"] : []), ...(forceWithLease ? ["--force-with-lease"] : []), ...(tags ? ["--tags"] : []), ...(setUpstream ? ["--set-upstream"] : []), secretUrl(remote), ...(refspec !== undefined ? [refspec] : []), ]); /** * Mutating: `git pull [--rebase] [--ff-only] []` — fetches * and integrates. * * @remarks * `remote` may be a URL as well as a remote name; an embedded `userinfo@` * credential is masked in {@link GitInvocation.redactedArgs}. */ static readonly pull = (remote: string, ref?: string, rebase = false, ffOnly = false): GitInvocation => git([ "pull", ...(rebase ? ["--rebase"] : []), ...(ffOnly ? ["--ff-only"] : []), secretUrl(remote), ...(ref !== undefined ? [ref] : []), ]); /** * `git config [-f ] --list -z` — every configuration entry in scope * (or in the given file only), NUL-terminated, the key separated from the * value by a newline within each record. * * @remarks * `-z` is load-bearing: a config VALUE may contain newlines; only the NUL * record terminator plus first-newline field split parses it losslessly. * A valueless key (git's boolean-true shorthand) emits no newline at all. */ static readonly configList = (file?: string, scope?: GitConfigScope): GitInvocation => git(["config", ...(file !== undefined ? ["-f", file] : []), ...scopeArgs(scope), "--list", "-z"]); /** * `git config [-f ] --get-all -z ` — every value of a * (possibly multi-valued) key, NUL-terminated. An unset key exits 1 with * silent stderr. */ static readonly configGetAll = (key: string, file?: string): GitInvocation => git(["config", ...(file !== undefined ? ["-f", file] : []), "--get-all", "-z", key]); /** * Mutating: `git config [-f ] (--unset | --unset-all) ` — * removes a key (or, with `all`, every value of a multi-valued key). * * @remarks * git exits 5, silently, when the key was not set — a loud failure by * this package's classification, deliberately: an unset that silently did * nothing is indistinguishable from one that worked. */ static readonly configUnset = (key: string, file?: string, all = false): GitInvocation => git(["config", ...(file !== undefined ? ["-f", file] : []), all ? "--unset-all" : "--unset", key]); /** * Mutating: `git config [-f ] --remove-section
` — removes * a whole configuration section (every key under it, and the section * header itself). * * @remarks * git exits 128 (`fatal: no such section`) when the section does not * exist — a loud failure by this package's classification, matching * {@link GitCommand.configUnset}'s posture: a removal that silently did * nothing is indistinguishable from one that worked. */ static readonly configRemoveSection = (section: string, file?: string): GitInvocation => git(["config", ...(file !== undefined ? ["-f", file] : []), "--remove-section", section]); /** * Mutating: `git config [-f ] --rename-section ` — * renames a configuration section, carrying every key under it across. * * @remarks * git exits 128 (`fatal: no such section`) when the old section does not * exist — the same loud posture as {@link GitCommand.configRemoveSection}. */ static readonly configRenameSection = (oldName: string, newName: string, file?: string): GitInvocation => git(["config", ...(file !== undefined ? ["-f", file] : []), "--rename-section", oldName, newName]); /** * Mutating: `git rm [--cached] [-r] [--force] -- ` — removes * paths from the index (and, without `cached`, the working tree). The * literal `--` separator makes the pathspec injection-safe by * construction. */ static readonly rm = ( paths: ReadonlyArray, cached = false, recursive = false, force = false, ): GitInvocation => git([ "rm", ...(cached ? ["--cached"] : []), ...(recursive ? ["-r"] : []), ...(force ? ["--force"] : []), "--", ...paths, ]); /** * Mutating: `git mv [--force] -- ` — moves or * renames a tracked path. The literal `--` separator makes both positionals * injection-safe by construction. */ static readonly mv = (source: string, destination: string, force = false): GitInvocation => git(["mv", ...(force ? ["--force"] : []), "--", source, destination]); /** * `git check-ignore -z --stdin` — which of the given paths git would * ignore, paths fed NUL-separated via stdin and answers returned * NUL-separated. * * @remarks * The `--stdin -z` form is the only fully robust one: `-z` without * `--stdin` is rejected by git outright, and the non-`-z` output C-quotes * special-character paths. Feeding paths via stdin also makes them * injection-safe by construction — nothing caller-controlled enters the * argv. When NO path is ignored, git exits 1 with silent stderr. */ static readonly checkIgnore = (paths: ReadonlyArray): GitInvocation => git(["check-ignore", "-z", "--stdin"], paths.map((path) => `${path}\0`).join("")); /** * Mutating: `git worktree add [--force] [--detach] []` — * creates a linked working tree at `path`, checked out at `ref` (or the * branch named after `path`'s basename). */ static readonly worktreeAdd = (path: string, ref?: string, detach = false, force = false): GitInvocation => git([ "worktree", "add", ...(force ? ["--force"] : []), ...(detach ? ["--detach"] : []), path, ...(ref !== undefined ? [ref] : []), ]); /** * `git worktree list --porcelain -z` — every working tree as a block of * NUL-terminated attributes (`worktree `, `HEAD `, * `branch ` / `detached`, `bare`, `locked []`, * `prunable []`), blocks separated by an empty attribute. */ static readonly worktreeList = (): GitInvocation => git(["worktree", "list", "--porcelain", "-z"]); /** Mutating: `git worktree remove [--force] ` — removes a linked working tree. */ static readonly worktreeRemove = (path: string, force = false): GitInvocation => git(["worktree", "remove", ...(force ? ["--force"] : []), path]); /** * `git ls-files --stage -z [-- ...]` — every INDEX entry (mode, * oid, stage number, path), NUL-terminated, optionally scoped to * `pathspec`. * * @remarks * The index-side sibling of {@link GitCommand.lsTree}: `lsTree` reads a * COMMITTED tree at a ref, while this reads the staging area — the only * place a staged-but-uncommitted gitlink (`160000 0 `) is * visible. `-z` is load-bearing twice over: paths may contain newlines, * and the non-`-z` output C-quotes special-character paths. */ static readonly lsFiles = (pathspec: ReadonlyArray = []): GitInvocation => git(["ls-files", "--stage", "-z", ...(pathspec.length > 0 ? ["--", ...pathspec] : [])]); }