@gitkraken/core-gitlens 0.1.0

package/src/git/utils/worktree.utils.ts

@@ -0,0 +1,21 @@
+import type { GitWorktree } from '../models/worktree.js';
+
+export function getWorktreeId(repoPath: string, name: string): string {
+	return `${repoPath}|worktrees/${name}`;
+}
+
+export function groupWorktreesByBranch(
+	worktrees: GitWorktree[],
+	options?: { includeDefault?: boolean; worktreesByBranch?: Map<string, GitWorktree> },
+): Map<string, GitWorktree> {
+	const worktreesByBranch = options?.worktreesByBranch ?? new Map<string, GitWorktree>();
+	if (worktrees == null) return worktreesByBranch;
+
+	for (const wt of worktrees) {
+		if (wt.branch == null || (!options?.includeDefault && wt.isDefault)) continue;
+
+		worktreesByBranch.set(wt.branch.id, wt);
+	}
+
+	return worktreesByBranch;
+}

package/src/git/watching/changeEvent.ts

@@ -0,0 +1,90 @@
+import { filter, some } from '../../utils/iterable.js';
+import type { RepositoryChange } from '../models/repository.js';
+
+/**
+ * An event describing changes to a repository, produced by the watching pipeline.
+ *
+ * Changes are coalesced within a debounce window — a single event may represent
+ * multiple filesystem changes. Use {@link changed} to test for specific change types.
+ */
+export class WatcherRepoChangeEvent {
+	protected readonly _changes: Set<RepositoryChange>;
+
+	constructor(
+		/** The repository path this event is for */
+		public readonly repoPath: string,
+		changes: RepositoryChange[],
+	) {
+		this._changes = new Set(changes);
+	}
+
+	get changes(): ReadonlySet<RepositoryChange> {
+		return this._changes;
+	}
+
+	toString(changesOnly: boolean = false): string {
+		const changeList = [...this._changes].join(', ');
+		return changesOnly ? `changes=${changeList}` : `{ repoPath: ${this.repoPath}, changes: ${changeList} }`;
+	}
+
+	/**
+	 * Test whether any of the specified change types are present in the event.
+	 *
+	 * @param affected - Change types to test for.
+	 * @returns `true` if any of the specified changes are present.
+	 */
+	changed(...affected: RepositoryChange[]): boolean {
+		return some(this._changes, c => affected.includes(c));
+	}
+
+	/**
+	 * Test whether the event contains ONLY the specified change types.
+	 *
+	 * `pausedOp` is treated as a union of `cherryPick`, `merge`, `rebase`,
+	 * and `revert` for convenience.
+	 *
+	 * @param affected - Change types to test for.
+	 * @returns `true` if the event contains only the specified changes.
+	 */
+	changedExclusive(...affected: RepositoryChange[]): boolean {
+		let changes = this._changes;
+
+		// When checking for specific paused operation types, also accept the union type
+		if (
+			affected.includes('cherryPick') ||
+			affected.includes('merge') ||
+			affected.includes('rebase') ||
+			affected.includes('revert')
+		) {
+			if (!affected.includes('pausedOp')) {
+				affected = [...affected, 'pausedOp'];
+			}
+		} else if (affected.includes('pausedOp')) {
+			// When checking for the union type exclusively, ignore specific subtypes
+			changes = new Set(changes);
+			changes.delete('cherryPick');
+			changes.delete('merge');
+			changes.delete('rebase');
+			changes.delete('revert');
+		}
+
+		const intersection = [...filter(changes, c => affected.includes(c))];
+		return intersection.length === changes.size;
+	}
+
+	/** Coalesce: return a new event with all changes from both this and the given set */
+	with(changes: RepositoryChange[]): WatcherRepoChangeEvent {
+		return new WatcherRepoChangeEvent(this.repoPath, [...this._changes, ...changes]);
+	}
+}
+
+/**
+ * An event describing working tree file changes, produced by the working tree pipeline.
+ *
+ * Paths have already been filtered through the gitignore filter and noise filter.
+ */
+export interface WorkingTreeChangeEvent {
+	readonly repoPath: string;
+	/** Absolute paths of changed files (post-gitignore filtering) */
+	readonly paths: ReadonlySet<string>;
+}

package/src/git/watching/classifyChange.ts

@@ -0,0 +1,81 @@
+import type { RepositoryChange } from '../models/repository.js';
+
+const classifyRegex =
+	/(worktrees|index|HEAD|FETCH_HEAD|ORIG_HEAD|CHERRY_PICK_HEAD|MERGE_HEAD|REBASE_HEAD|rebase-merge|rebase-apply|sequencer|REVERT_HEAD|config|gk\/config|info\/exclude|refs\/(?:heads|remotes|stash|tags))/;
+
+/**
+ * Maps a path relative to a `.git` directory to the corresponding
+ * {@link RepositoryChange} types. This is pure Git knowledge — the
+ * regex and switch table encode which files in `.git/` correspond
+ * to which logical repository changes.
+ *
+ * @param relativePath - Path relative to the `.git` directory
+ *   (e.g., `refs/heads/main`, `HEAD`, `config`)
+ * @returns An array of change types, or `undefined` if the path
+ *   is noise or unrecognized. `undefined` for `FETCH_HEAD` which
+ *   is intentionally not mapped to a change type (the extension
+ *   handles it as a last-fetched timestamp).
+ */
+export function classifyGitDirChange(relativePath: string): RepositoryChange[] | undefined {
+	const match = classifyRegex.exec(relativePath);
+	if (match == null) return undefined;
+
+	switch (match[1]) {
+		case 'config':
+			return ['config', 'remotes'];
+
+		case 'gk/config':
+			return ['gkConfig'];
+
+		case 'info/exclude':
+			return ['ignores'];
+
+		case 'index':
+			return ['index'];
+
+		case 'FETCH_HEAD':
+			// No RepositoryChange — extension handles this for last-fetched timestamps
+			return undefined;
+
+		case 'HEAD':
+			return ['head', 'heads'];
+
+		case 'ORIG_HEAD':
+			return ['heads'];
+
+		case 'CHERRY_PICK_HEAD':
+			return ['cherryPick', 'pausedOp'];
+
+		case 'MERGE_HEAD':
+			return ['merge', 'pausedOp'];
+
+		case 'REBASE_HEAD':
+		case 'rebase-merge':
+		case 'rebase-apply':
+			return ['rebase', 'pausedOp'];
+
+		case 'REVERT_HEAD':
+			return ['revert', 'pausedOp'];
+
+		case 'sequencer':
+			return ['pausedOp'];
+
+		case 'refs/heads':
+			return ['heads'];
+
+		case 'refs/remotes':
+			return ['remotes'];
+
+		case 'refs/stash':
+			return ['stash'];
+
+		case 'refs/tags':
+			return ['tags'];
+
+		case 'worktrees':
+			return ['worktrees'];
+
+		default:
+			return undefined;
+	}
+}

package/src/git/watching/gitIgnoreFilter.ts

@@ -0,0 +1,134 @@
+import { getScopedCounter } from '../../utils/counter.js';
+import { fileUri } from '../../utils/uri.js';
+import type { Ignore } from 'ignore';
+import ignore from 'ignore';
+import type { FileSystemProvider } from '../context.js';
+
+export interface GitIgnoreFilterOptions {
+	/** Absolute path to the repository root (working tree) */
+	readonly repoPath: string;
+	/** Absolute path to the .git directory (for info/exclude) */
+	readonly gitDirPath: string;
+	/** File system provider for reading ignore files */
+	readonly fs: FileSystemProvider;
+	/**
+	 * Returns the path to the global excludes file (core.excludesFile).
+	 * May return undefined if not configured.
+	 */
+	readonly getGlobalExcludesPath?: () => Promise<string | undefined>;
+}
+
+/**
+ * In-memory gitignore filter using the `ignore` npm package.
+ * Fully library-owned — no VS Code dependencies.
+ *
+ * Loads patterns eagerly on creation from:
+ * 1. `<repoPath>/.gitignore`
+ * 2. `<gitDirPath>/info/exclude`
+ * 3. Global excludes file (`core.excludesFile`)
+ *
+ * Once loaded, all checks are **synchronous** for maximum performance.
+ * Call `ready()` before first use to ensure patterns are loaded.
+ */
+export class GitIgnoreFilter {
+	private ig: Ignore = ignore();
+	private loading: Promise<void> | undefined;
+	private readonly _generation = getScopedCounter();
+
+	private readonly repoPath: string;
+	private readonly gitDirPath: string;
+	private readonly fs: FileSystemProvider;
+	private readonly getGlobalExcludesPath?: () => Promise<string | undefined>;
+
+	constructor(options: GitIgnoreFilterOptions) {
+		this.repoPath = options.repoPath;
+		this.gitDirPath = options.gitDirPath;
+		this.fs = options.fs;
+		this.getGlobalExcludesPath = options.getGlobalExcludesPath;
+
+		// Start loading immediately
+		this.loading = this.loadPatterns();
+	}
+
+	/** Resolves when patterns are loaded. Safe to call multiple times. */
+	async ready(): Promise<void> {
+		if (this.loading != null) {
+			await this.loading;
+		}
+	}
+
+	/**
+	 * Check if a path is ignored. Must be called after `ready()`.
+	 * @param relativePath Path relative to the repository root (forward slashes)
+	 * @returns true if the path should be ignored
+	 */
+	isIgnored(relativePath: string): boolean {
+		if (!relativePath) return false;
+
+		try {
+			return this.ig.ignores(relativePath);
+		} catch {
+			// `ignore` can throw on edge-case paths
+			return false;
+		}
+	}
+
+	/**
+	 * Filter an array of relative paths, returning only non-ignored ones.
+	 * Must be called after `ready()`.
+	 */
+	filter(relativePaths: readonly string[]): string[] {
+		return this.ig.filter(relativePaths);
+	}
+
+	/**
+	 * Reload all patterns (e.g., after .gitignore or info/exclude changes).
+	 * Returns a promise that resolves when reload is complete.
+	 */
+	async refresh(): Promise<void> {
+		this.loading = this.loadPatterns();
+		await this.loading;
+	}
+
+	private async loadPatterns(): Promise<void> {
+		const id = this._generation.next();
+		const newIg = ignore();
+
+		await Promise.allSettled([
+			this.loadFile(newIg, `${this.repoPath}/.gitignore`),
+			this.loadFile(newIg, `${this.gitDirPath}/info/exclude`),
+			this.loadGlobalExcludes(newIg),
+		]);
+
+		// Only commit results if no newer refresh has started
+		if (id !== this._generation.current) return;
+
+		this.ig = newIg;
+		this.loading = undefined;
+	}
+
+	private async loadFile(target: Ignore, path: string): Promise<void> {
+		try {
+			const data = await this.fs.readFile(fileUri(path));
+			const content = new TextDecoder().decode(data);
+			if (content) {
+				target.add(content);
+			}
+		} catch {
+			// File might not exist or be unreadable — that's fine
+		}
+	}
+
+	private async loadGlobalExcludes(target: Ignore): Promise<void> {
+		if (this.getGlobalExcludesPath == null) return;
+
+		try {
+			const path = await this.getGlobalExcludesPath();
+			if (path != null) {
+				await this.loadFile(target, path);
+			}
+		} catch {
+			// Global excludes might not be configured
+		}
+	}
+}

package/src/git/watching/initWatcher.ts

@@ -0,0 +1,79 @@
+import type { UnifiedDisposable } from '../../utils/disposable.js';
+import { createDisposable } from '../../utils/disposable.js';
+import type { Event } from '../../utils/event.js';
+import { Emitter } from '../../utils/event.js';
+import type { FileWatcher, FileWatchingProvider } from './provider.js';
+import { gitInitGlob } from './watcherPatterns.js';
+
+export interface RepositoryInitEvent {
+	/** Absolute path of the created .git directory */
+	readonly path: string;
+	/** Absolute path of the base directory being watched */
+	readonly basePath: string;
+}
+
+/**
+ * Watches for `.git` directory creation within watched base paths.
+ * Used to discover new repositories when `git init` or `git clone` runs.
+ *
+ * This is separate from {@link RepositoryWatchService} which monitors
+ * already-discovered repositories. The init watcher is a pre-discovery
+ * concern — it fires before a repository is known.
+ */
+export class RepositoryInitWatcher implements UnifiedDisposable {
+	private readonly provider: FileWatchingProvider;
+	private readonly emitter = new Emitter<RepositoryInitEvent>();
+	private readonly watchers = new Map<string, FileWatcher>();
+	private _disposed = false;
+
+	constructor(provider: FileWatchingProvider) {
+		this.provider = provider;
+	}
+
+	[Symbol.dispose](): void {
+		this.dispose();
+	}
+
+	dispose(): void {
+		if (this._disposed) return;
+		this._disposed = true;
+
+		for (const watcher of this.watchers.values()) {
+			watcher.dispose();
+		}
+		this.watchers.clear();
+		this.emitter.dispose();
+	}
+
+	get onDidCreate(): Event<RepositoryInitEvent> {
+		return this.emitter.event;
+	}
+
+	/**
+	 * Start watching a directory for `.git` creation.
+	 * Returns a disposable that stops watching that directory.
+	 */
+	watch(basePath: string): UnifiedDisposable {
+		if (this._disposed || this.watchers.has(basePath)) {
+			return createDisposable(() => {});
+		}
+
+		const watcher = this.provider.createWatcher(basePath, gitInitGlob, event => {
+			if (event.reason !== 'create') return;
+			this.emitter.fire({ path: event.path, basePath: basePath });
+		});
+
+		this.watchers.set(basePath, watcher);
+
+		return createDisposable(
+			() => {
+				const w = this.watchers.get(basePath);
+				if (w === watcher) {
+					this.watchers.delete(basePath);
+					w.dispose();
+				}
+			},
+			{ once: true },
+		);
+	}
+}

package/src/git/watching/provider.ts

@@ -0,0 +1,24 @@
+import type { UnifiedDisposable } from '../../utils/disposable.js';
+
+/** Event from a filesystem watcher */
+export interface FileWatchEvent {
+	/** Absolute path of the changed file */
+	readonly path: string;
+	readonly reason: 'create' | 'change' | 'delete';
+}
+
+/** Opaque token representing a filesystem watcher */
+export interface FileWatcher extends UnifiedDisposable {}
+
+/**
+ * Factory for creating filesystem watchers. The library calls this
+ * with a base path + glob pattern; the caller creates platform-specific
+ * watchers (e.g., VS Code's `workspace.createFileSystemWatcher`).
+ *
+ * This is the only pluggable concern in the watching system.
+ * Everything else (interpretation, gitignore, debouncing, etc.)
+ * is fully library-owned.
+ */
+export interface FileWatchingProvider {
+	createWatcher(basePath: string, pattern: string, onEvent: (event: FileWatchEvent) => void): FileWatcher;
+}

package/src/git/watching/watchGroup.ts

@@ -0,0 +1,182 @@
+import type { UnifiedDisposable } from '../../utils/disposable.js';
+import { isDescendant, relative } from '../../utils/path.js';
+import type { GitDir, RepositoryChange } from '../models/repository.js';
+import { classifyGitDirChange } from './classifyChange.js';
+import type { FileWatcher, FileWatchEvent, FileWatchingProvider } from './provider.js';
+import { dotGitGlobCombined, dotGitGlobCommon, dotGitGlobRoot, shouldIgnoreRepoPath } from './watcherPatterns.js';
+
+/**
+ * Hooks that the WatchGroup fires when events are interpreted.
+ * These are raw, un-debounced events — the session handles debouncing.
+ */
+export interface WatchGroupHooks {
+	readonly onRepoChanged: (repoPath: string, changes: RepositoryChange[]) => void;
+	readonly onFetchHeadChanged?: (repoPath: string) => void;
+	readonly onIgnoresChanged?: (repoPath: string) => void;
+}
+
+/**
+ * Tracks one session's connection to a WatchGroup.
+ * Each session has its own root watcher but shares the common watcher.
+ */
+interface SessionEntry {
+	readonly repoPath: string;
+	readonly gitDirPath: string;
+	readonly rootWatcher: FileWatcher;
+	readonly hooks: WatchGroupHooks;
+}
+
+/**
+ * Manages filesystem watchers for a single physical `.git` directory,
+ * shared across all worktrees that reference it.
+ *
+ * Structure:
+ * - 1 common watcher: config, refs/**, info/exclude, etc.
+ * - N root watchers: one per worktree (index, HEAD, *_HEAD, etc.)
+ *
+ * For a standard (non-worktree) repo, the common and root directories
+ * are the same, but we still create separate watchers for clean separation.
+ */
+export class WatchGroup implements UnifiedDisposable {
+	private readonly _sessions = new Map<string, SessionEntry>();
+	private _commonWatcher: FileWatcher | undefined;
+	private _disposed = false;
+
+	constructor(
+		readonly commonGitDir: string,
+		private readonly provider: FileWatchingProvider,
+	) {}
+
+	[Symbol.dispose](): void {
+		this.dispose();
+	}
+
+	/** Dispose the entire group (common watcher + all root watchers). */
+	dispose(): void {
+		if (this._disposed) return;
+		this._disposed = true;
+
+		for (const entry of this._sessions.values()) {
+			entry.rootWatcher.dispose();
+		}
+		this._sessions.clear();
+
+		this._commonWatcher?.dispose();
+		this._commonWatcher = undefined;
+	}
+
+	get sessions(): ReadonlyMap<string, SessionEntry> {
+		return this._sessions;
+	}
+
+	/** Add a session to this group. Creates the root watcher for the session's gitDir. */
+	addSession(repoPath: string, gitDir: GitDir, hooks: WatchGroupHooks): void {
+		if (this._disposed) return;
+		if (this._sessions.has(repoPath)) return; // Already tracked
+
+		// Determine the glob pattern for the root watcher
+		const isStandard = gitDir.commonUri == null;
+		const rootPattern = isStandard ? dotGitGlobCombined : dotGitGlobRoot;
+
+		const rootWatcher = this.provider.createWatcher(gitDir.uri.fsPath, rootPattern, (event: FileWatchEvent) => {
+			const entry = this._sessions.get(repoPath);
+			if (entry != null) {
+				this.onRootEvent(event, entry);
+			}
+		});
+
+		const entry: SessionEntry = {
+			repoPath: repoPath,
+			gitDirPath: gitDir.uri.fsPath,
+			rootWatcher: rootWatcher,
+			hooks: hooks,
+		};
+
+		this._sessions.set(repoPath, entry);
+
+		// Start the common watcher if this is a worktree repo and we haven't yet.
+		// Standard repos don't need a separate common watcher because their root
+		// watcher uses dotGitGlobCombined which already covers all patterns.
+		if (!isStandard) {
+			this.ensureCommonWatcher();
+		}
+	}
+
+	/** Remove a session from this group. Disposes its root watcher. */
+	removeSession(repoPath: string): void {
+		const entry = this._sessions.get(repoPath);
+		if (entry == null) return;
+
+		entry.rootWatcher.dispose();
+		this._sessions.delete(repoPath);
+
+		// If no more sessions, dispose the common watcher
+		if (this._sessions.size === 0 && this._commonWatcher != null) {
+			this._commonWatcher.dispose();
+			this._commonWatcher = undefined;
+		}
+	}
+
+	private ensureCommonWatcher(): void {
+		if (this._commonWatcher != null || this._disposed) return;
+
+		this._commonWatcher = this.provider.createWatcher(
+			this.commonGitDir,
+			dotGitGlobCommon,
+			(event: FileWatchEvent) => {
+				this.onCommonEvent(event);
+			},
+		);
+	}
+
+	private onCommonEvent(event: FileWatchEvent): void {
+		// Compute relative path from common git dir
+		if (!isDescendant(event.path, this.commonGitDir)) return;
+		const relativePath = relative(this.commonGitDir, event.path);
+		if (shouldIgnoreRepoPath(relativePath)) return;
+
+		// FETCH_HEAD lives in the main .git dir, not in worktree subdirs.
+		// Dispatch to all sessions so each worktree can update its last-fetched state.
+		if (relativePath === 'FETCH_HEAD') {
+			for (const entry of this._sessions.values()) {
+				entry.hooks.onFetchHeadChanged?.(entry.repoPath);
+			}
+			return;
+		}
+
+		const changes = classifyGitDirChange(relativePath);
+
+		// Dispatch to ALL sessions in the group
+		for (const entry of this._sessions.values()) {
+			if (changes != null) {
+				entry.hooks.onRepoChanged(entry.repoPath, changes);
+			}
+
+			// Check for special cases
+			if (relativePath === 'info/exclude') {
+				entry.hooks.onIgnoresChanged?.(entry.repoPath);
+			}
+		}
+	}
+
+	private onRootEvent(event: FileWatchEvent, entry: SessionEntry): void {
+		if (!isDescendant(event.path, entry.gitDirPath)) return;
+		const relativePath = relative(entry.gitDirPath, event.path);
+		if (shouldIgnoreRepoPath(relativePath)) return;
+
+		// Check for FETCH_HEAD before interpretation
+		if (relativePath === 'FETCH_HEAD') {
+			entry.hooks.onFetchHeadChanged?.(entry.repoPath);
+			return;
+		}
+
+		const changes = classifyGitDirChange(relativePath);
+		if (changes != null) {
+			entry.hooks.onRepoChanged(entry.repoPath, changes);
+		}
+
+		if (relativePath === 'info/exclude') {
+			entry.hooks.onIgnoresChanged?.(entry.repoPath);
+		}
+	}
+}