@gitkraken/core-gitlens 0.12.0 → 0.14.0

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

@@ -15,6 +15,23 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
   private readonly git;
   private readonly cache;
   private readonly provider;
+  /** Ahead/behind counts by `<baseSha>...<tipSha>` range, from the per-tip fallback; a pair of commits always counts the same */
+  private readonly aheadBehindBySha;
+  /**
+   * When each `commonPath\0branch\0key` was last stamped by this process. Bounded: a dropped entry only costs a
+   * read of the stored stamp, which still holds off a write under 5 minutes old
+   */
+  private readonly _branchActivityStamps;
+  /** One call per `commonPath\0branch` at a time, so a call held off by another's write in flight settles after it */
+  private readonly _branchActivityCalls;
+  /**
+   * What each `commonPath\0branch`'s reflog says it was created from, as git wrote it; `undefined` when it says
+   * nothing. A branch's creation never changes, so the base read, which reruns on every commit and ref move, reads
+   * it once
+   */
+  private readonly _branchCreatedFrom;
+  /** 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;
   constructor(context: GitServiceContext, git: Git, cache: Cache, provider: CliGitProviderInternal);
   getBranch(repoPath: string, name?: string, options?: {
     force?: boolean;
@@ -55,6 +72,12 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
     priority?: GitCommandPriority;
     local?: boolean;
   }, cancellation?: AbortSignal): Promise<string | undefined>;
+  /**
+   * Writes the missing `refs/remotes/<remote>/HEAD` symref from the remote (`remote set-head -a`) in the background,
+   * never prompting for credentials; nothing runs past the cached local check when the symref exists. Rejects when
+   * the remote can't be read.
+   */
+  setRemoteHeadIfMissing(repoPath: string, remote: string): Promise<void>;
   createBranch(repoPath: string, name: string, ref: string, options?: {
     noTracking?: boolean;
   }): Promise<void>;
@@ -99,16 +122,65 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    * caches the former forever and must not cache the latter.
    */
   private getBaseBranchFromReflog;
-  getAheadOfBase(repoPath: string, branch: string, cancellation?: AbortSignal): Promise<AheadOfBase>;
+  /**
+   * The start point `ref`'s own reflog says it was created from (`branch: Created from <name>`), as git wrote it:
+   * a branch, `HEAD`, a sha, a tag or any other revision. `undefined` unless exactly one entry says so. Rejects
+   * when the reflog can't be read, including for a ref that doesn't exist.
+   */
+  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.
+   */
+  private getCreatedFromTarget;
+  getAheadOfBase(repoPath: string, branch: string | undefined, options?: {
+    skipUserTarget?: boolean;
+    preferredTarget?: string;
+  }, cancellation?: AbortSignal): Promise<AheadOfBase>;
+  /**
+   * Resolves the base from the recorded candidates, then the branch it was created from or the default branch, for
+   * {@link getAheadOfBase}
+   */
+  private getAheadOfBaseInOrder;
+  /**
+   * 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
+   * unmerged parent forked nearer, and stays its base. `undefined` when neither is usable.
+   */
+  private getCreatedFromForkTarget;
+  /** Counts HEAD's commits past `target` for {@link getAheadOfBase} */
+  private measureAheadOfBase;
+  /** Counts the default branch's own commits past its upstream (see {@link getSelfUpstreamTarget}) for {@link getAheadOfBase} */
+  private measureAheadOfSelfUpstream;
+  /**
+   * HEAD's count against `ref` from their merge base: `left` only `ref` has, `right` only HEAD has. `undefined`
+   * before HEAD's first commit, when there is nothing to count; any other failure rejects with git's error.
+   */
+  private countAgainstBase;
+  getAheadBehindCounts(repoPath: string, base: string, options?: {
+    remotes?: boolean;
+    refs?: readonly string[];
+  }, cancellation?: AbortSignal): Promise<Map<string, {
+    ahead: number;
+    behind: number;
+  }>>;
+  getMergedBranches(repoPath: string, into: string, options?: {
+    remotes?: boolean;
+  }, cancellation?: AbortSignal): Promise<Set<string>>;
   /** Counts `range` with a fresh `rev-list`, bypassing the cached count. Rejects on any failure, with git's error */
   private getLeftRightCountUncached;
   /** Whether HEAD names a branch with no commit yet. Rejects when that can't be read, so a failure isn't taken for an empty branch */
   private isUnbornHead;
   /**
-   * Whether `ref` names `branch` itself: the same name, or `<remote>/<branch>` for one of the repo's actual remotes.
-   * Splitting at the first slash instead would call a local `release/main` the same branch as `main`.
+   * Whether `ref` names `branch` itself: the same name, or `<remote>/<branch>` for one of the repo's actual remotes,
+   * short or as a full ref. Splitting at the first slash instead would call a local `release/main` the same branch
+   * as `main`.
    */
   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;
   /**
@@ -118,16 +190,41 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    */
   private getRecordedBaseCandidates;
   /**
-   * The repo's default branch from local refs only: the `origin/HEAD` symref as its local name, else
-   * `init.defaultBranch`, else `main`, else `master` — each only if it names a commit.
+   * 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
+   * remote order, `<remote>/main` or `<remote>/master`, again as the local branch of that name or else the remote
+   * ref; then `init.defaultBranch`, `main`, `master` — each only if it names a commit.
    */
   private getLocalDefaultBranchName;
+  /**
+   * `upstream/<name>` for a created-from or default base `<name>` (or `<remote>/<name>`), as another ref that base
+   * is measured against: in a fork whose `main` tracks `origin/main`, a branch taken off (or since rebased onto) a
+   * newer `upstream/main` would otherwise count the commits `origin` hasn't caught up on. Read from the cached
+   * remote and ref lists; `undefined` when there is no `upstream` remote, it lacks the branch, or the base is that
+   * ref itself.
+   */
+  private getUpstreamContender;
+  /** {@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
-   * candidate neither forks from is used as-is if it names a commit. `undefined` when the candidate is unusable.
+   * `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.
    */
   private getNearestForkTarget;
+  /**
+   * The base for a branch that is itself the default branch, with its tip: its own upstream, `upstream/<branch>`
+   * when an `upstream` remote has it, else `<branch>@{u}`. Read from the cached ref and branch lists; only a
+   * `<branch>` that isn't checked out spawns, for its `@{u}`. `undefined` when there is neither, or its ref is gone.
+   */
+  private getSelfUpstreamTarget;
+  /**
+   * {@link findRefTip} in `records`, the cached ref list. `getRefs` answers a failed enumeration with an empty list,
+   * 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 */
   private getForkPoint;
   /**
@@ -142,12 +239,15 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
   private resolveStoredMergeTarget;
   getStoredDetectedMergeTargetBranchName(repoPath: string, ref: string): Promise<string | undefined>;
   getStoredUserMergeTargetBranchName(repoPath: string, ref: string): Promise<string | undefined>;
-  /** Updates the last accessed timestamp for the current branch */
   onCurrentBranchAccessed(repoPath: string): Promise<void>;
-  /** Updates the last accessed and modified timestamp for the current branch */
   onCurrentBranchModified(repoPath: string): Promise<void>;
-  /** Updates the agent last activity timestamp for the current branch */
   onCurrentBranchAgentActivity(repoPath: string): Promise<void>;
+  private getBranchActivityKey;
+  private forgetBranchCreatedFrom;
+  /** Forgets this process's throttle marks for `name`, so its next activity re-reads the stored stamps */
+  private clearBranchActivityStamps;
+  /** Never rejects — activity stamps are bookkeeping and callers fire them without a catch */
+  private recordBranchActivity;
   renameBranch(repoPath: string, oldName: string, newName: string): Promise<void>;
   setUpstreamBranch(repoPath: string, name: string, upstream: string | undefined): Promise<void>;
   storeBaseBranchName(repoPath: string, ref: string, base: string, options?: {
@@ -162,7 +262,6 @@ export declare class BranchesGitSubProvider implements GitBranchesSubProvider {
    * @returns A map of branch name to metadata.
    */
   private getBranchMetadataMap;
-  private storeBranchMetadata;
   setBranchDisposition(repoPath: string, branchName: string, disposition: BranchDisposition | undefined): Promise<void>;
 }
 //#endregion