@gitkraken/core-gitlens 0.16.3 → 0.16.5

package/dist/git-cli/providers/branches.d.ts

@@ -5,7 +5,7 @@ import { ConflictDetectionResult } from "../../git/models/mergeConflicts.js";
 import { GitServiceContext } from "../../git/context.js";
 import { GitCommandPriority } from "../../git/run.types.js";
 import { BranchSortOptions } from "../../git/utils/sorting.js";
-import { AheadOfBase, BranchContributionsOverview, GitBranchMergedStatus, GitBranchesSubProvider, GitPushTarget } from "../../git/providers/branches.js";
+import { AheadOfBase, BranchContributionsOverview, GitBranchMergedStatus, GitBranchesSubProvider, GitPushTarget, MergeTarget, MergeTargetOptions } from "../../git/providers/branches.js";
 import { Cache, GkConfigInvalidationTarget } from "../../git/cache.js";
 import { Git } from "../exec/git.js";
 import { CliGitProviderInternal } from "../cliGitProvider.js";
@@ -18,18 +18,20 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
   /** Ahead/behind counts by `<baseSha>...<tipSha>` range, from the per-tip fallback; a pair of commits always counts the same */
   private readonly aheadBehindBySha;
   /**
-   * For a base that moved only forward, what its reflog reaches (else `false`), by `<ref>\0<oldSha>\0<newSha>`, for
-   * each cached ref list it was read against. A fetch moves one base under every worktree at once, so they share the
-   * one check, joining it while it runs
+   * For a base that moved only forward, what its reflog reaches (else `false`), by `<commonPath>\0<ref>`, then by the
+   * tip it moved from. A fetch moves one base under every worktree at once, so they share the one check, joining it
+   * while it runs. The reads hold for the tip the ref moved to, the reflog they read, stamped by its file's size and
+   * mtime (else by the cached ref list, through what it derives so the list itself isn't held, when there's no file
+   * to stamp), and the replace refs, which change what's reachable; a change to any of them starts the ref over. Every
+   * move appends to the reflog, so a ref moved away and back to the same tip between reads doesn't find the answer
+   * taken before
    */
   private readonly baseMovedForward;
   /**
    * For a base that moved, the count of the commits its new tip lacks for each local branch a worktree has checked
-   * out, by tip sha, keyed by that new tip alone for each cached ref list it was read against (which also fixes the
-   * branches counted). The counts don't depend on the ref or where it moved from, so each worktree the move reached
-   * finds its HEAD's count in the one read, even one whose previous answer was taken at another old tip. Only the
-   * checked-out branches are counted: the shared walk runs until every counted branch meets the new tip, so an
-   * unrelated old or orphan branch no worktree uses would make it deeper than any worktree's own count
+   * out, by tip sha, by `<commonPath>\0<newTip>`, with the replace refs it was counted under and the tips it counted.
+   * The counts don't depend on the ref or where it moved from, so each worktree the move reached finds its HEAD's
+   * count in the one read, even one whose previous answer was taken at another old tip
    */
   private readonly aheadOfMovedBase;
   /**
@@ -45,6 +47,11 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    * it once
    */
   private readonly _branchCreatedFrom;
+  /**
+   * The branch HEAD was on when each `commonPath\0branch` was first checked out, as git wrote it, for a branch
+   * created from `HEAD`; only found ones, since a later checkout can write one
+   */
+  private readonly _branchCheckedOutFrom;
   /** Bumped each time a key's created-from is forgotten, so a reflog read in flight across that doesn't store it */
   private readonly _branchCreatedFromGenerations;
   /**
@@ -75,6 +82,7 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
         position: number;
       };
     } | undefined>;
+    getFallbackDefaultBranch?: () => Promise<string | undefined>;
     priority?: GitCommandPriority;
   }, cancellation?: AbortSignal): Promise<BranchContributionsOverview | undefined>;
   getBranchesWithCommits(repoPath: string, commits: string[], branch?: string, options?: {
@@ -140,8 +148,9 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
     priority?: GitCommandPriority;
   }, cancellation?: AbortSignal): Promise<string | undefined>;
   /**
-   * `failed` separates "the reflog ran and had no answer" from "the read never happened" — the caller
-   * caches the former forever and must not cache the latter.
+   * The branch `ref` was created from, else the branch HEAD was on when it was first checked out, each as its
+   * upstream when it has one. `failed` separates "the reflog ran and had no answer" from "the read never happened" —
+   * the caller caches the former forever and must not cache the latter.
    */
   private getBaseBranchFromReflog;
   /**
@@ -151,12 +160,37 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    */
   private getReflogCreatedFrom;
   /**
-   * The branch `branch` was created from, as a base for {@link getAheadOfBaseInOrder}: the name its own reflog
-   * gives, when that is a local or remote-tracking branch in the cached ref list and not `branch` itself or its
-   * copy on a remote (`git switch <branch>` creates it from `<remote>/<branch>`). Never the checkout history in
-   * HEAD's reflog, which on a long-lived checkout names whatever was checked out last.
+   * The worktree `branch` is checked out in, whose HEAD reflog holds its checkouts; else the main worktree, never the
+   * caller's, since every worktree of the repository shares the answer
+   */
+  private getCheckoutPath;
+  /**
+   * The branch HEAD was on when `branch` was first checked out at `repoPath` (the oldest `checkout: moving from
+   * <name> to <branch>` in its HEAD reflog), as git wrote it. `undefined` when there is no such entry. Rejects when the
+   * reflog can't be read.
+   */
+  private getCheckoutSource;
+  /**
+   * The branch `branch` was created from, as a base for {@link resolveBase}: the name its own reflog gives, when that
+   * is a local or remote-tracking branch in the cached ref list and not `branch` itself or its copy on a remote
+   * (`git switch <branch>` creates it from `<remote>/<branch>`). Never the checkout history in HEAD's reflog, which
+   * on a long-lived checkout names whatever was checked out last. `fromHead` when the reflog says it was created
+   * from `HEAD`.
    */
   private getCreatedFromTarget;
+  /**
+   * For a branch its reflog says was created from `HEAD`, the branch HEAD was on when it was first checked out (see
+   * {@link getCheckoutSource}), read in the worktree it is checked out in, else the main worktree, and kept as a base
+   * like {@link getCreatedFromTarget}'s. Remembered once found, as the created-from name is; a reflog with no such
+   * entry yet marks the answer for eviction on the next checkout, which may write one.
+   */
+  private getInferredCreatedFrom;
+  /**
+   * `name` as a base for `branch`: only a local or remote-tracking branch in the cached ref list — a sha, a tag or a
+   * revision expression (`main~2`) names no `refs/heads/` or `refs/remotes/` ref — and not `branch` itself or its
+   * copy on a remote.
+   */
+  private getListedBaseName;
   getAheadOfBaseConfigKey(repoPath: string, cancellation?: AbortSignal): Promise<string | undefined>;
   getAheadOfBaseConfigEntries(repoPath: string, cancellation?: AbortSignal): Promise<readonly (readonly [key: string, value: string | undefined])[] | undefined>;
   /**
@@ -193,6 +227,16 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    * or git can't say.
    */
   private getMovedForward;
+  /**
+   * A stamp of `ref`'s reflog file in the common git directory, by its size and mtime; `undefined` when there's no
+   * file to stat (a reftable repository, or a ref without a reflog)
+   */
+  private getReflogStamp;
+  /**
+   * A stamp of the common git directory's `shallow` file, by its size and mtime; `null` when the repository isn't
+   * shallow, `undefined` when that can't be read
+   */
+  private getShallowStamp;
   /**
    * Reads {@link getMovedForward} from git, in `commonPath`, which holds the refs, their reflogs and the objects for
    * every worktree. Not bound to one caller's cancellation, since every worktree the move reached rides this one
@@ -201,25 +245,72 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    */
   private readMovedForward;
   /**
-   * For a base moved to `newTip`, read against `records` (the cached ref list), the count of the commits `newTip`
-   * lacks for each local branch a worktree has checked out, by tip sha, so a detached HEAD at one of those tips finds
-   * its count too. Only those branches are counted: the one walk runs until every counted branch meets `newTip`, so an
-   * unrelated old or orphan branch would make it deeper than any worktree's own count, and a HEAD at a commit no
-   * checked-out branch points at isn't in the answer. The branches derive from `records`, which the read is kept
-   * per, so `newTip` alone keys it. `undefined` when git can't count them in one pass (before 2.41), there is no
-   * checked-out branch or `records` can't tell which are, or git couldn't say.
+   * For a base moved to `newTip`, the count of the commits `newTip` lacks for `head`, from one count of each local
+   * branch a worktree has checked out in `records` (the cached ref list), by tip sha, so a detached HEAD at one of
+   * those tips finds its count too. Only those branches are counted: the one walk runs until every counted branch
+   * meets `newTip`, so an unrelated old or orphan branch would make it deeper than any worktree's own count. Which
+   * branches it counts only bounds that walk, since a commit's count past `newTip` doesn't depend on what else is
+   * counted, so a read that counted `head` answers it for a later list (one with a branch created at `newTip` since,
+   * say) while the replace refs match; a `head` it didn't count starts a read over the current list's checked-out
+   * branches. `undefined` when no checked-out branch is at `head` or `records` can't tell which are checked out, git
+   * can't count them in one pass (before 2.41), or git couldn't say.
    */
   private getAheadOfMovedBase;
   /**
-   * Reads {@link getAheadOfMovedBase} from git, in `commonPath`, which holds every worktree's branches. Not bound to
-   * one caller's cancellation, since every worktree the move reached rides this one read.
+   * Reads {@link getAheadOfMovedBase} for the `checkedOut` branches from git, in `commonPath`, which holds every
+   * worktree's branches. Not bound to one caller's cancellation, since every worktree the move reached rides this one
+   * read.
    */
   private readAheadOfMovedBase;
+  getMergeTarget(repoPath: string, branch: string, options?: MergeTargetOptions, cancellation?: AbortSignal): Promise<MergeTarget | undefined>;
   /**
-   * Resolves the base from the recorded candidates, then the branch it was created from or the default branch, for
-   * {@link getAheadOfBase}
+   * Where {@link getMergeTarget} measures `branch` from: its local branch's ref, or — for a remote-tracking branch given
+   * by its short name (`origin/feature`) — that ref, with `selfName` its name on the remote
    */
-  private getAheadOfBaseInOrder;
+  private getMergeTargetSource;
+  /** Resolves {@link getMergeTarget}'s answer with what it was read from; `pinnable` is false when it can't be confirmed later */
+  private resolveMergeTarget;
+  /** Whether everything `entry` was read from still reads the same; while nothing changed, every read here is cached */
+  private isMergeTargetCurrent;
+  /**
+   * The base `branch` is measured against from `reads.from`, in {@link getMergeTarget}'s order; `getAheadOfBase`'s
+   * options never reach the pull request, the reflog guess or the remote. `selfName` is the name a self check
+   * compares with: `branch`, or a remote-tracking branch's name on its remote, which has no stored targets, reflog or
+   * upstream of its own. A `'preferred'` target is already known not to be the branch itself at `from`'s commit; any
+   * other target isn't checked here.
+   */
+  private resolveBase;
+  /**
+   * The first usable stored candidate, most trusted first: the user's merge target (unless `skipUserTarget`), the
+   * detected one, the pull request's base (`getAssociatedPullRequest`, read only when neither is usable), then the
+   * recorded base — only its stored value (and with `inferBase`, VS Code's), never `getBaseBranchName`'s reflog
+   * guess, which on a long-lived checkout names whatever branch was last checked out from. A remote-tracking branch
+   * has no stored keys of its own, so only its pull request's base is tried, and never recorded.
+   */
+  private getStoredBaseTarget;
+  /**
+   * The branch's stored merge keys as read, in {@link storedMergeKeys} order, then VS Code's recorded base when
+   * `inferBase`. A failed read is absent, and leaves `reads`' answer unpinned.
+   */
+  private readStoredMergeKeys;
+  /**
+   * The pull request's base as a candidate on the branch's remote; `undefined` when there is none, the branch has no
+   * remote, or either can't be read (which leaves `reads`' answer unpinned)
+   */
+  private getPullRequestBaseCandidate;
+  /**
+   * The default branch for {@link resolveBase}: {@link getLocalDefaultBranchName}; when that names none, with
+   * `defaultBranch: 'remote'`, the default the first of those remotes reports; then `getFallbackDefaultBranch`. A
+   * remote-qualified answer is taken as its local branch when there is one
+   */
+  private getDefaultBranchForBase;
+  /** `local` when the cached ref list names that branch (depended on either way), else `remoteName` */
+  private preferListedLocalBranch;
+  /**
+   * The branch `branch` was created from (tier `'created'`); with `inferBase`, for one created from `HEAD`, the
+   * branch HEAD was on when it was first checked out (tier `'inferred'`)
+   */
+  private getCreatedFromSource;
   /**
    * The base for a branch created from `createdFrom`: that branch, unless the default branch forked strictly nearer
    * HEAD, as it does once `createdFrom` merged into it and the branch was rebased onto it. A stacked branch's
@@ -257,14 +348,13 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
   private isSelfRef;
   /** The repo's remote names from the cached remote list; empty when it can't be read */
   private getRemoteNames;
-  /** Whether `ref` names `branch` itself (see {@link isSelfRef}) and sits at HEAD's commit; tips are read only after the name matched */
-  private isSelfAtHead;
   /**
-   * The bases recorded against a branch, most trusted first: the user's merge target, the detected one, then the
-   * base a launch recorded. Only the stored value of the latter — `getBaseBranchName` would fall back to a reflog
-   * guess, which on a long-lived checkout names whatever branch was last checked out from. A failed read is absent.
+   * Whether `ref` names `selfName` itself (see {@link isSelfRef}) and sits at `reads.from`'s commit; tips are read
+   * only after the name matched. HEAD's commit is asked of git, a branch's read from the cached ref list
    */
-  private getRecordedBaseCandidates;
+  private isSelfAtTip;
+  /** The remotes a default branch is read from, in order: `upstream`, `origin`, then the first remote */
+  private getPreferredRemotes;
   /**
    * The repo's default branch from local refs only, never the network: the `HEAD` symref of the `upstream` remote,
    * else of `origin`, else of the first remote, as its local branch or else as the remote ref; then, in the same
@@ -283,16 +373,17 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
   /** {@link getNearestForkTarget} with the `upstream` remote's copy of `candidate` as its contender */
   private getUpstreamNearestForkTarget;
   /**
-   * A candidate base as the ref HEAD is measured against: the candidate or its tracking ref, whichever forked
-   * nearer HEAD, so a stale local base defers to its upstream while one carrying unpushed work wins over it. A
+   * A candidate base as the ref `reads.from` is measured against: the candidate or its tracking ref, whichever forked
+   * nearer, so a stale local base defers to its upstream while one carrying unpushed work wins over it. A
    * `contender` other than the tracking ref is taken only when it forked strictly nearer than both, so a tie keeps
-   * the candidate's own pick. A candidate none forks from is used as-is if it names a commit. `undefined` when the
-   * candidate is unusable.
+   * the candidate's own pick. A candidate none forks from is used as-is unless git confirms it names no ref: one the
+   * cached ref list names is kept, and so is one whose check fails. `undefined` when the candidate is unusable.
    */
   private getNearestForkTarget;
   /**
    * `<name>@{u}`, without asking git when the cached ref list shows `name` can't have one: a failed lookup isn't
-   * cached, so asking it of a remote-tracking ref (`origin/main`, the usual default) re-spawns on every read.
+   * cached, so asking it of a remote-tracking ref (`origin/main`, the usual default) re-spawns on every read. The
+   * list's own upstream isn't used: a config-only change (`git branch -u`) doesn't refresh it.
    */
   private getUpstreamName;
   /**
@@ -306,8 +397,13 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    * so an empty one is asked of git instead, rather than read as every ref being absent.
    */
   private getRefTip;
-  /** The merge base of HEAD and `ref`, preferring git's fork-point reading of `ref`'s reflog when it has one */
+  /** Where `reads.from` forked from `ref`: git's fork-point reading of `ref`'s reflog when it has one, else their merge base */
   private getForkPoint;
+  /**
+   * `getMergeBase`, sharing its cached and in-flight reads, but telling git's exit 1 (no common ancestor, or no fork
+   * point) from a read that failed. Both answer `undefined`; a failed one also clears `reads.pinnable`.
+   */
+  private readMergeBase;
   /**
    * The stored merge target — the user's pick, else the one detected from its PR — skipping any whose branch git
    * confirms is gone so resolution falls through to the next source. A target that couldn't be checked is kept.