@gitkraken/core-gitlens 0.16.5 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-25
+
+## [0.17.0] - 2026-10-25
+
+### Added
+
+- Adds `ignoredWorktreeFolders` to `CliGitProviderOptions` and `createCliGitService`: folders, relative to a repository's common git dir, whose worktrees core acts as if didn't exist, for a tool's throwaway worktrees (sync-tools' `sync-tools-worktrees`, say). They are matched under the common git dir as spelled and as it resolves through symlinks. They are left out of worktree lists, and adding, removing, locking, unlocking or moving one (by absolute path, in a `notify: 'infer'` run; the typed worktree writes still announce it) announces no `worktrees` change, so it no longer evicts every checkout's cached git results. The `.git` watchers leave the folders unwatched, so a throwaway checkout inside `.git` costs the watcher nothing. Nothing is ignored unless registered (git, git-cli)
+- Adds `readDirectory` to `GitService.createSingleton`'s options, shaped like `FileSystemProvider.readDirectory`, which `createCliGitService` passes from the host's file system. With it and `readFile`, the watcher lists and reads a repository's worktree admin entries once as it starts, so an ignored worktree's reports, every HEAD move of a rebase in one included, reach no session, while a known worktree's reports are told at once without a read (git, git-cli)
+- Adds `WorktreeSummaryService.getSummarySnapshot(repoPath, { probeDirty?, cancellation? })`, which answers a worktree's summary with `dirtyReadAt`, when its dirty flag was read: `undefined` for a subscribed worktree, whose summary follows its working tree. For a worktree without a subscription, `probeDirty` reads the dirty flag whatever its inputs say (git)
+- Adds `onDidStart` to `FileWatcherOptions`, passed to working-tree watchers only, with or without polling: a provider that places its watch asynchronously calls it once the watch is live, and core rescans the working tree once for whatever changed meanwhile (git)
+- Adds `stat` to `WorktreeSummaryServiceOptions`, which `GitService` fills from `watchPolling.stat`: with it, a worktree without a subscription re-reads its dirty flag only when its index file moved (git)
+- Adds `GitWorktree.branchName`: the branch `git worktree list` names, set even when the branch list has no match for it, which `GitWorktree.name` now falls back to (git, git-cli)
+- Adds a `force` option to `worktrees.getWorktrees(repoPath, options?, cancellation?)` and `worktrees.getWorktree(repoPath, predicate, options?, cancellation?)`: it re-reads `git worktree list` and evicts only the cached worktree list, for the repository and its sibling worktrees, unless a read whose git process hasn't started yet is pending, which it joins. Clearing the `'worktrees'` and `'branches'` cache types to get a fresh list made every sibling worktree re-run its branch, ref and log reads (git, git-cli)
+- Adds `onSpawn` to `GitRunOptions`, called once when the git process starts, after any wait in core's queue; a call sharing an identical run in flight is told when that run starts (git, git-cli)
+- Adds the `'worktreeHead'` repository change, a linked worktree's HEAD moving (a checkout in a worktree whose own `.git` isn't watched), which the `.git` watchers report beside `'worktrees'` for a worktree's `HEAD` and for an admin entry created or removed (a watcher may report a removal as its directory alone), and `git worktree add`, `remove` and `prune` (typed or `notify: 'infer'`) announce; and the `'worktreeList'` cache type, which evicts only the cached worktree list, for the repository and its sibling worktrees (git, git-cli)
+
+### Changed
+
+- **Breaking (git, git-cli)** — `worktrees.getWorktrees` and `worktrees.getWorktree` take `options` before `cancellation`, `getWorktrees(repoPath, options?, cancellation?)` and `getWorktree(repoPath, predicate, options?, cancellation?)`, like `branches.getBranch`. A caller passing a cancellation positionally must move it
+- **Breaking (git, git-cli)** — `RepositoryChange` gains `'worktreeHead'` and `CachedGitTypes` gains `'worktreeList'`, which breaks a host's exhaustive `switch` or `Record` over either. A host that refreshed on a linked worktree's checkout by `'worktrees'` still hears it, since its report carries both
+- Changes a lock or unlock of a worktree, typed or raw, a raw `git worktree move` or `repair`, and a watcher's report of a worktree's `locked` file, a `gitdir` written or an admin entry's directory changed, to evict only the cached worktree list rather than every worktree's cached git results and merge targets. An add, remove or prune, or a worktree's HEAD moving, still evicts them all (git, git-cli)
+- Changes a `'providers'`-only cache reset, which only touches remote-provider metadata, to leave in-flight git runs joinable in core's typed writes and `notifyChanged`, as it already did in GitLens (git, git-cli)
+- Changes a checkout, switch, rebase, bisect or `stash branch` core runs (typed or `notify: 'infer'`), and its move of a detached HEAD, to announce `'worktrees'` and `'worktreeHead'` beside its own kinds, so every other worktree takes the watchers' report of the rewritten HEAD for the write's own: it no longer hears it a second time as an outside change, nor evicts every worktree's cached git results again for it. A commit on a branch, which leaves the HEAD file as it was, announces neither (git-cli)
+- Changes `getSummary` of a worktree without a subscription to answer from its last read, kept for the 256 most recently asked, rather than reading every field afresh each time (4 to 7 git processes): it re-reads only what its inputs say moved since, all of them read from core's caches, so nothing moved means no git. HEAD's branch or commit moving reads everything; the upstream's tip or name, the branch; a ref the base depends on (for a remote's `HEAD` symref, where it points), the base, re-measured from the previous one as for a subscribed worktree; the config inputs the base read consulted, the branch and the base; the index file (with `stat`), the dirty flag; and core's own write of the branch's merge target or base, the stored base values. Only a `.git` watch of the worktree (or core's own writes) keeps those caches current, so a host watches the `.git` of a worktree it asks about. Concurrent reads of one worktree share a read, which still takes no read slot, so it never waits behind subscribed worktrees' runs; a caller after core's write of a merge target or base gets a read of its own. A subscription drops the last read, and so does a failed read (git)
+
+### Fixed
+
+- Fixes a write that creates or removes the directory holding its ref (the first `team/…` branch, say) also reaching watchers as an outside change of every branch: the watcher's report of that directory is now the write's own (git)
+- Fixes the first move of a base after a clone, or after the reflog lost the entries before it, re-measuring every worktree in full instead of in one shared read (git-cli)
+- Fixes a worktree list pairing a worktree with no branch, or a stale one, after a change the branch caches missed (a branch `git worktree add -b` created outside core, a worktree that switched branches, a commit), so a `pull` of a branch checked out in another worktree fetched into it and failed: where `git worktree list` contradicts the cached branch list, core re-reads the branches once, first dropping the branch caches of a worktree whose branch changed, and announces an unnamed `heads` change so a host's views of the branches refresh too. A contradiction the fresh branch list still shows (a layout where git's two listings never agree) isn't re-read again until the worktree list changes (git-cli)
+- Fixes a worktree whose HEAD points outside `refs/heads/` getting a garbled branch name; it has none (git-cli)
+
 ## [0.16.5] - 2026-10-24
 
 ### Added
@@ -926,7 +958,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 - Initial release. Bundles `@gitlens/utils`, `@gitlens/git`, `@gitlens/git-cli`, `@gitlens/ai`, and `@gitlens/git-github` into a single core npm package with subpath exports.
 
-[unreleased]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.16.5...HEAD
+[unreleased]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.18.0...HEAD
+[0.18.0]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.17.0...gitkraken:releases/core/v0.18.0
+[0.17.0]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.16.5...gitkraken:releases/core/v0.17.0
 [0.16.5]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.16.4...gitkraken:releases/core/v0.16.5
 [0.16.4]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.16.3...gitkraken:releases/core/v0.16.4
 [0.16.3]: https://github.com/gitkraken/vscode-gitlens/compare/releases/core/v0.16.2...gitkraken:releases/core/v0.16.3

package/dist/git/cache.d.ts

@@ -31,7 +31,11 @@ type RepoPath = string;
 /** Cache types that are keyed by file path within a repo — support per-file clearing */
 export type UriScopedCachedGitTypes = 'blame' | 'diff' | 'fileLog';
 export declare function areUriScopedCachedGitTypes(types: string[]): types is UriScopedCachedGitTypes[];
-export type CachedGitTypes = UriScopedCachedGitTypes | 'branch' | 'branches' | 'config' | 'contributors' | 'gitignore' | 'gkConfig' | 'lastFetched' | 'providers' | 'remotes' | 'stashes' | 'status' | 'tags' | 'tracking' | 'worktrees';
+export type CachedGitTypes = UriScopedCachedGitTypes | 'branch' | 'branches' | 'config' | 'contributors' | 'gitignore' | 'gkConfig' | 'lastFetched' | 'providers' | 'remotes' | 'stashes' | 'status' | 'tags' | 'tracking' | 'worktrees' |
+/** Only the worktree list: unlike `'worktrees'`, no worktree's git results or merge targets */
+'worktreeList';
+/** Whether a reset of these types makes in-flight git runs stale (none or empty meaning every type) */
+export declare function resetDropsPendingRuns(types: readonly CachedGitTypes[] | undefined): boolean;
 /**
  * What a gk-config reconcile did, so `Cache` knows whether the coarse fallback is still owed.
  *
@@ -187,6 +191,7 @@ export declare class Cache implements Disposable {
   get gitDir(): Map<RepoPath, GitDir>;
   get gitIgnore(): Map<RepoPath, GitIgnoreFilter>;
   get gitResults(): RepoPromiseCacheMap<RepoPath, GitResult>;
+  get ignoreConfigListing(): PromiseMap<RepoPath, string | undefined>;
   get initialCommitSha(): PromiseMap<RepoPath, string | undefined>;
   get lastFetched(): PromiseCache<RepoPath, number | undefined>;
   get leftRightCommitCount(): RepoPromiseCacheMap<string, LeftRightCommitCountResult | undefined>;
@@ -484,6 +489,12 @@ export declare class Cache implements Disposable {
    * before it.
    */
   getAheadOfBaseConfigListing(repoPath: string, factory: (commonPath: string, cacheable: CacheController, cancellation?: AbortSignal) => PromiseOrValue<string | undefined>, cancellation?: AbortSignal): Promise<string | undefined>;
+  /**
+   * One listing of the gitignore filter's config inputs for every checkout of a repository, which serves a checkout's
+   * filter while nothing makes config differ by checkout. Evicted hard, so a read after a change never joins one
+   * from before it.
+   */
+  getIgnoreConfigListing(repoPath: string, factory: (commonPath: string, cacheable: CacheController, cancellation?: AbortSignal) => PromiseOrValue<string | undefined>, cancellation?: AbortSignal): Promise<string | undefined>;
   getBranchMetadataMap(repoPath: string, factory: (commonPath: string) => PromiseOrValue<Map<string, BranchMetadata>>): Promise<Map<string, BranchMetadata>>;
   getDefaultBranchName(repoPath: string, remote: string, factory: (commonPath: string, cacheable: CacheController, cancellation?: AbortSignal) => PromiseOrValue<string | undefined>, cancellation?: AbortSignal): Promise<string | undefined>;
   /** The cached default branch for one `remote` key, without reading it; `undefined` when none is cached */
@@ -513,7 +524,9 @@ export declare class Cache implements Disposable {
     cancellation?: AbortSignal;
   }): Promise<GitStash>;
   getTags(repoPath: string, factory: (commonPath: string, cacheable: CacheController, cancellation?: AbortSignal) => PromiseOrValue<PagedResult<GitTag>>, cancellation?: AbortSignal): Promise<PagedResult<GitTag>>;
-  getWorktrees(repoPath: string, factory: (commonPath: string, cacheable: CacheController, cancellation?: AbortSignal) => PromiseOrValue<GitWorktree[]>, cancellation?: AbortSignal): Promise<GitWorktree[]>;
+  getWorktrees(repoPath: string, factory: (commonPath: string, cacheable: CacheController, cancellation?: AbortSignal) => PromiseOrValue<GitWorktree[]>, options?: {
+    force?: boolean;
+  }, cancellation?: AbortSignal): Promise<GitWorktree[]>;
   private getSharedOrCreate;
   private getSharedOrCreateWithKey;
   private getSharedSimple;

package/dist/git/cache.js

@@ -1,5 +1,5 @@
 import { exhaustiveArray } from "../utils/array.js";
-import { raceWithSignal } from "../utils/cancellation.js";
+import { CancellationError, raceWithSignal } from "../utils/cancellation.js";
 import { debug } from "../utils/decorators/log.js";
 import { invalidateMemoized } from "../utils/decorators/memoize.js";
 import { Emitter } from "../utils/event.js";
@@ -19,6 +19,10 @@ const uriScopedCachedGitTypes = [
 function areUriScopedCachedGitTypes(types) {
 	return types.every((t) => uriScopedCachedGitTypes.includes(t));
 }
+/** Whether a reset of these types makes in-flight git runs stale (none or empty meaning every type) */
+function resetDropsPendingRuns(types) {
+	return !types?.length || types.some((t) => t !== "worktreeList" && t !== "providers");
+}
 /**
 * Ceiling on how long a derived branch base is trusted. Long enough that repeated reads during normal use
 * are served from cache, short enough that a base that changed by a route with no eviction signal (an
@@ -69,6 +73,7 @@ const sharedCacheKeys = new Set(exhaustiveArray()([
 	"emptyTreeSha",
 	"gitResults",
 	"gkConfigMap",
+	"ignoreConfigListing",
 	"initialCommitSha",
 	"lastFetched",
 	"logShas",
@@ -117,6 +122,7 @@ function createEmptyCaches() {
 		gitIgnore: void 0,
 		gitResults: void 0,
 		gkConfigMap: void 0,
+		ignoreConfigListing: void 0,
 		initialCommitSha: void 0,
 		lastFetched: void 0,
 		logShas: void 0,
@@ -298,6 +304,9 @@ var Cache = class Cache {
 	get gitResults() {
 		return this._caches.gitResults ??= new RepoPromiseCacheMap({ capacity: 200 });
 	}
+	get ignoreConfigListing() {
+		return this._caches.ignoreConfigListing ??= new PromiseMap();
+	}
 	get initialCommitSha() {
 		return this._caches.initialCommitSha ??= new PromiseMap();
 	}
@@ -438,6 +447,7 @@ var Cache = class Cache {
 			if (types.includes("branch")) {
 				keysToClear.add("aheadOfBaseConfigKey");
 				keysToClear.add("aheadOfBaseConfigListing");
+				keysToClear.add("ignoreConfigListing");
 				keysToClear.add("baseBranchName");
 			}
 			if (!worktreeOnly && (types.includes("branch") || types.includes("worktrees"))) this.evictMergeTargetsOnCheckout(repoPath);
@@ -454,6 +464,7 @@ var Cache = class Cache {
 			if (types.includes("config")) {
 				keysToClear.add("aheadOfBaseConfigKey");
 				keysToClear.add("aheadOfBaseConfigListing");
+				keysToClear.add("ignoreConfigListing");
 				keysToClear.add("baseBranchName");
 				keysToClear.add("configKeys");
 				keysToClear.add("configPatterns");
@@ -503,8 +514,8 @@ var Cache = class Cache {
 				keysToClear.add("fileExistence");
 				keysToClear.add("trackedPaths");
 			}
-			if (types.includes("worktrees")) keysToClear.add("worktrees");
-			if (types.some((t) => t !== "gitignore" && t !== "gkConfig" && t !== "providers")) keysToClear.add("gitResults");
+			if (types.includes("worktrees") || types.includes("worktreeList")) keysToClear.add("worktrees");
+			if (types.some((t) => t !== "gitignore" && t !== "gkConfig" && t !== "providers" && t !== "worktreeList")) keysToClear.add("gitResults");
 		}
 		for (const key of keysToClear) {
 			const cache = this._caches[key];
@@ -513,7 +524,7 @@ var Cache = class Cache {
 			else if (key === "aheadOfBaseConfigKey" && !worktreeOnly && (!types.length || types.includes("config"))) this.evictShared(key, repoPath, "evict");
 			else if (sharedCacheKeys.has(key)) {
 				if (!worktreeOnly) {
-					const hardEvict = key === "aheadOfBaseConfigListing" || key === "gitResults" && (types.includes("config") || types.includes("branch"));
+					const hardEvict = key === "aheadOfBaseConfigListing" || key === "ignoreConfigListing" || key === "gitResults" && (types.includes("config") || types.includes("branch"));
 					this.evictShared(key, repoPath, hardEvict ? "evict" : inFlight);
 				}
 			} else cache.delete(repoPath);
@@ -626,7 +637,10 @@ var Cache = class Cache {
 		if (previousCommonPath != null && previousCommonPath !== commonPath) this.unregisterRepoPath(normalizedPath);
 		if (previousCommonPath !== commonPath) {
 			this._caches.aheadOfBaseConfigKey?.delete(normalizedPath);
-			if (normalizedPath === commonPath) this._caches.aheadOfBaseConfigListing?.delete(commonPath);
+			if (normalizedPath === commonPath) {
+				this._caches.aheadOfBaseConfigListing?.delete(commonPath);
+				this._caches.ignoreConfigListing?.delete(commonPath);
+			}
 			this._caches.gitResults?.delete(normalizedPath);
 		}
 		this._commonPathRegistry.set(normalizedPath, commonPath);
@@ -670,7 +684,7 @@ var Cache = class Cache {
 				if (key === "gitResults" && isLastWorktree && repoPath !== commonPath) cache.delete(commonPath);
 				continue;
 			}
-			if (key === "aheadOfBaseConfigListing") {
+			if (key === "aheadOfBaseConfigListing" || key === "ignoreConfigListing") {
 				if (repoPath === commonPath || isLastWorktree) cache.delete(commonPath);
 				continue;
 			}
@@ -759,7 +773,8 @@ var Cache = class Cache {
 		}
 		if (hasAny("stash")) types.add("stashes");
 		if (hasAny("tags")) types.add("tags");
-		if (hasAny("worktrees")) types.add("worktrees");
+		if (hasAny("worktreeHead")) types.add("worktrees");
+		else if (hasAny("worktrees")) types.add("worktreeList");
 		if (types.size) this.clearCachesCore(inFlight, repoPath, [...types], worktreeOnly);
 		return [...types];
 	}
@@ -1183,6 +1198,14 @@ var Cache = class Cache {
 	getAheadOfBaseConfigListing(repoPath, factory, cancellation) {
 		return this.getSharedSimple(this.aheadOfBaseConfigListing, repoPath, factory, cancellation);
 	}
+	/**
+	* One listing of the gitignore filter's config inputs for every checkout of a repository, which serves a checkout's
+	* filter while nothing makes config differ by checkout. Evicted hard, so a read after a change never joins one
+	* from before it.
+	*/
+	getIgnoreConfigListing(repoPath, factory, cancellation) {
+		return this.getSharedSimple(this.ignoreConfigListing, repoPath, factory, cancellation);
+	}
 	getBranchMetadataMap(repoPath, factory) {
 		return this.getSharedSimple(this.branchMetadataMap, repoPath, factory);
 	}
@@ -1279,7 +1302,11 @@ var Cache = class Cache {
 			values: data.values.map((t) => t.withRepoPath(newRepoPath))
 		}), cancellation);
 	}
-	async getWorktrees(repoPath, factory, cancellation) {
+	async getWorktrees(repoPath, factory, options, cancellation) {
+		if (options?.force) {
+			if (cancellation?.aborted) throw new CancellationError();
+			this.evictCaches(repoPath, "worktreeList");
+		}
 		return this.getSharedOrCreate(this.worktrees, repoPath, factory, (data, newRepoPath) => data.map((w) => w.withRepoPath(newRepoPath)), cancellation);
 	}
 	async getSharedOrCreate(cache, repoPath, factory, mapper, cancellation) {
@@ -1345,6 +1372,6 @@ __decorate([debug({ onlyExit: true })], Cache.prototype, "reset", null);
 __decorate([debug({ onlyExit: true })], Cache.prototype, "onRepositoryChanged", null);
 __decorate([debug({ onlyExit: true })], Cache.prototype, "applyRepositoryChanges", null);
 //#endregion
-export { Cache, areUriScopedCachedGitTypes, shouldEvictBlameCacheEntry };
+export { Cache, areUriScopedCachedGitTypes, resetDropsPendingRuns, shouldEvictBlameCacheEntry };
 
 //# sourceMappingURL=cache.js.map