@gitkraken/core-gitlens 0.3.0 → 0.3.1

package/src/git/models/graph.ts

@@ -19,6 +19,14 @@ export interface GitGraphRowHead {
 	isCurrentHead: boolean;
 	context?: string | object;
 	upstream?: { name: string; id: string };
+	/** Set when this branch is checked out in a (non-default) worktree. Grouped so producers can't
+	 *  half-populate id-without-path or vice versa. GitLens consumers should read this field. */
+	worktree?: { id: string; path: string };
+	/** Upstream-component-compatibility mirror of `worktree?.id`. The bundled
+	 *  `@gitkraken/gitkraken-components` library still reads `worktreeId` to switch between
+	 *  WORKTREE and HEAD ref-badge styling — keeping it populated preserves the visual cue.
+	 *  Producers MUST set this whenever they set `worktree`; do not read it from GitLens code,
+	 *  read `worktree.id` instead. */
 	worktreeId?: string;
 }
 
@@ -40,11 +48,43 @@ export interface GitGraphRowTag {
 	context?: string | object;
 }
 
+/**
+ * Compact, host-computed flags for a commit/stash row, shipped instead of the bulky serialized
+ * `contexts.row`/`contexts.avatar` blobs (which duplicated sha/message/repoPath already on the row).
+ * The webview reconstructs the full webview-item contexts from these flags + row fields + repoPath.
+ * Bit 0: reachable-from-HEAD (`+current`); Bit 1: unique-to-one-local-branch (`+unique`);
+ * Bit 2: has-children — set ONLY on undo-eligible tip rows (active HEAD + worktree HEADs) that have a
+ * child, to gate Undo Commit to leaf tips (undoing a commit other work is stacked on is unsafe). It is
+ * NOT a general has-children signal: non-tip rows never carry it (the host only computes it for tips);
+ * Bit 3: unpushed/ahead-of-upstream (`+unpublished`).
+ * Bit 4: history-rewriteable (`+rewriteable`) — on the first-parent chain from HEAD up to (excluding)
+ * the first merge commit, so a plain (non-`--rebase-merges`) interactive rebase can safely rewrite it;
+ * gates squash/drop/reword/modify. Strictly narrower than `+current` (reachable-from-HEAD includes a
+ * merge's other-parent ancestry, which is NOT safely rewriteable).
+ * (`+HEAD` derives from `row.heads[].isCurrentHead`; contributor `+current` from `row.isCurrentUser`.)
+ */
+export const enum GitGraphRowContextFlags {
+	None = 0,
+	ReachableFromHead = 1 << 0,
+	UniqueToBranch = 1 << 1,
+	HasChildren = 1 << 2,
+	Unpublished = 1 << 3,
+	RewriteableFromHead = 1 << 4,
+}
+
 /**
  * Context data attached to graph row regions for command/menu handling.
  * Structurally compatible with @gitkraken/gitkraken-components RowContexts.
  */
 export interface GitGraphRowContexts {
+	/** Compact replacement for the serialized commit `row`/`avatar` contexts; see {@link GitGraphRowContextFlags}. */
+	flags?: GitGraphRowContextFlags;
+	/**
+	 * Index into the per-graph `GraphReachabilityTable.sets` for this row's reachable-refs set,
+	 * shipped instead of the per-row `reachability` object (which dominated the graph payload). The
+	 * webview rebuilds `row.reachability` from the shared table. Absent ⇒ no reachability for this row.
+	 */
+	reachabilityIndex?: number;
 	row?: string | object;
 	ref?: string | object;
 	refGroups?: Record<string, string | object>;
@@ -63,6 +103,28 @@ export interface GitGraphRowStats {
 	deletions: number;
 }
 
+/**
+ * Wire encoding for per-row reachability, shipped once per graph payload instead of inline on every
+ * row. Git reachability is monotone (adjacent commits share ref-sets), so the rows collapse to a
+ * relatively small number of distinct sets over the repo's ref universe — `dictionary` (the shared
+ * ref list) + `sets` (distinct membership bitmaps, base64; bit i ⇒ `dictionary[i]` reachable) + a
+ * per-row index (`GitGraphRowContexts.reachabilityIndex`) reconstructs every row's `reachability`
+ * client-side for a fraction of the bytes the inline objects cost. `current` is a per-ref property
+ * (the checked-out HEAD branch) and lives in the dictionary entry.
+ *
+ * The table is append-only within a graph generation, so the host ships only the entries appended
+ * since its last push (a delta) on same-generation pagination and the full table on a new generation;
+ * `id` lets the webview tell the two apart (same `id` ⇒ append the delta, new `id` ⇒ replace + reset
+ * its decode cache). A fresh `getGraph` walk mints a new `id`; `more()` keeps the same one.
+ */
+export interface GraphReachabilityTable {
+	/** Generation id — stable across `more()` pagination, new per fresh graph walk. */
+	readonly id: number;
+	readonly dictionary: GitCommitReachability['refs'];
+	/** Distinct ref-membership bitmaps, base64-encoded `Uint8Array` of `ceil(dictionary.length/8)` bytes. */
+	readonly sets: string[];
+}
+
 /** Library-owned graph row type. Structurally compatible with @gitkraken/gitkraken-components GraphRow. */
 export interface GitGraphRow {
 	sha: string;
@@ -78,6 +140,12 @@ export interface GitGraphRow {
 	tags?: GitGraphRowTag[];
 	contexts?: GitGraphRowContexts;
 	stats?: GitGraphRowStats;
+	/**
+	 * Transient, set only for the duration of {@link GraphRowProcessor.processRow} (the row processor's
+	 * `+unique` decision reads it). The provider strips it before pushing the row and records the
+	 * reachable-ref set into the shared {@link GitGraph.reachability} table instead (see
+	 * {@link GitGraphRowContexts.reachabilityIndex}), so emitted rows do NOT retain the per-row arrays.
+	 */
 	reachability?: GitCommitReachability;
 	isCurrentUser?: boolean;
 }
@@ -99,6 +167,22 @@ export interface GitGraph {
 	/** SHAs reachable from HEAD (for enrichment: marking commits on the current branch) */
 	readonly reachableFromHEAD?: ReadonlySet<string>;
 
+	/**
+	 * SHAs on the first-parent chain from HEAD up to (excluding) the first merge commit — i.e. the
+	 * commits a plain interactive rebase can safely rewrite. Empty when HEAD itself is a merge. Used by
+	 * the graph's history-rewriting commands (squash/drop/reword/modify) to validate selections.
+	 */
+	readonly rewriteableFromHEAD?: ReadonlySet<string>;
+
+	/**
+	 * Shared, append-only reachability table for the loaded rows (the primary representation — rows
+	 * carry only a {@link GitGraphRowContexts.reachabilityIndex} into it, not per-row ref arrays).
+	 * Grows monotonically across {@link more} pagination within a graph session: indices already
+	 * assigned never change, so consumers can decode any row on demand and cache by index. Absent ⇒
+	 * no row in the graph has reachability. See {@link GraphReachabilityTable}.
+	 */
+	readonly reachability?: GraphReachabilityTable;
+
 	/** The rows for the set of commits requested */
 	readonly rows: GitGraphRow[];
 	readonly id?: string;
@@ -178,5 +262,18 @@ export interface GraphContext {
 	readonly branchIdOfMainWorktree: string | undefined;
 	readonly stashes: ReadonlyMap<string, GitStashCommit> | undefined;
 	readonly reachableFromHEAD: ReadonlySet<string>;
+	/** SHAs on the first-parent chain from HEAD up to (excluding) the first merge commit — the commits
+	 *  a plain interactive rebase can safely rewrite. Empty when HEAD is a merge. Sets the
+	 *  {@link GitGraphRowContextFlags.RewriteableFromHead} flag, gating squash/drop/reword/modify. */
+	readonly rewriteableFromHEAD: ReadonlySet<string>;
+	/** The subset of undo-eligible tip shas (active HEAD + worktree HEADs) that have at least one
+	 *  child — i.e. are NOT leaves. Scoped to tips (not all commits) for performance; do not treat as
+	 *  a general has-children signal. Sets the {@link GitGraphRowContextFlags.HasChildren} flag, which
+	 *  gates Undo Commit to leaf tips. */
+	readonly tipShasWithChildren: ReadonlySet<string>;
+	/** SHAs reachable from HEAD's tracking-upstream tip, or `undefined` when HEAD has no upstream.
+	 * A commit reachable from HEAD but NOT from this set is unpushed (`+unpublished`); `undefined`
+	 * means there's no upstream to be ahead of, so nothing is flagged. */
+	readonly reachableFromHeadUpstream: ReadonlySet<string> | undefined;
 	readonly avatars: Map<string, string>;
 }

package/src/git/models/remoteProvider.ts

@@ -74,6 +74,7 @@ export interface RemotesUrlsConfig {
 	readonly fileInCommit: string;
 	readonly fileLine: string;
 	readonly fileRange: string;
+	readonly avatar?: string;
 }
 
 export abstract class RemoteProvider<T extends ResourceDescriptor = ResourceDescriptor> implements ProviderReference {

package/src/git/models/repository.ts

@@ -7,7 +7,6 @@ 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 { getScopedLogger } from '../../utils/logger.scoped.js';
 import { basename, normalizePath } from '../../utils/path.js';
 import type { Uri } from '../../utils/uri.js';
 import { fileUri } from '../../utils/uri.js';
@@ -84,8 +83,6 @@ export interface RepositoryInit {
 	readonly gitDir: GitDir | undefined;
 	readonly index: number;
 	readonly root: boolean;
-	readonly closed?: boolean;
-	readonly suspended?: boolean;
 	readonly watchService: RepositoryWatchService;
 }
 
@@ -118,19 +115,21 @@ export class Repository {
 	readonly root: boolean;
 
 	protected readonly _gitDir: GitDir | undefined;
-	protected _pendingResumeTimer: ReturnType<typeof setTimeout> | undefined;
 	protected _repoSubscription: RepositorySubscription | undefined;
-	protected _suspended: boolean;
 	protected _watchHandle: WatchHandle | undefined;
 	protected readonly _watchService: RepositoryWatchService;
 
 	private _pendingWorkingTreeChange?: RepositoryWorkingTreeChangeEvent;
 	private _pendingWorkingTreeFlush = false;
 	private _repoChangeListener: UnifiedDisposable | undefined;
+	/** Outstanding leases on the shared {@link _watchHandle} across `watch()` + `watchWorkingTree()`. */
+	private _watchHandleRefs = 0;
+	/** Outstanding `watch()` (repo-change) leases; drives the single shared bridge subscription. */
+	private _watchRefs = 0;
+	private _disposed = false;
 
 	constructor(init: RepositoryInit) {
 		({
-			closed: this._closed = init.closed ?? false,
 			id: this.id,
 			index: this.index,
 			gitDir: this._gitDir,
@@ -138,7 +137,6 @@ export class Repository {
 			path: this.path,
 			provider: this.provider,
 			root: this.root,
-			suspended: this._suspended = init.suspended ?? false,
 			uri: this.uri,
 			watchService: this._watchService,
 		} = init);
@@ -156,45 +154,25 @@ export class Repository {
 				this._name = `${prefix}${this._name}`;
 			}
 		}
-
-		this.setupWatching();
 	}
 
 	dispose(): void {
-		clearTimeout(this._pendingResumeTimer);
+		this._disposed = true;
 		this._repoChangeListener?.dispose();
 		this._repoChangeListener = undefined;
 		this._repoSubscription?.dispose();
 		this._repoSubscription = undefined;
 		this._watchHandle?.dispose();
 		this._watchHandle = undefined;
+		this._watchHandleRefs = 0;
+		this._watchRefs = 0;
 		this._onDidChange.dispose();
 		this._onDidChangeWorkingTree.dispose();
 	}
 
-	protected _closed: boolean;
-	get closed(): boolean {
-		return this._closed;
-	}
-	set closed(value: boolean) {
-		const changed = this._closed !== value;
-		this._closed = value;
-		if (changed) {
-			if (this._closed) {
-				// When closing, fire immediately even if suspended
-				this.fireChange('closed', true);
-
-				this._repoChangeListener?.dispose();
-				this._repoChangeListener = undefined;
-				this._repoSubscription?.dispose();
-				this._repoSubscription = undefined;
-			} else {
-				this.setupWatching();
-				this.fireChange('opened');
-			}
-
-			this.onClosedChanged(value);
-		}
+	/** Indicates whether this repository currently has an active `watch()` (repo-change) lease. */
+	get watching(): boolean {
+		return this._watchRefs > 0;
 	}
 
 	get etag(): number {
@@ -249,41 +227,6 @@ export class Repository {
 		return this.provider.virtual;
 	}
 
-	@trace({ onlyExit: true })
-	suspend(): void {
-		this._suspended = true;
-		this._watchHandle?.session.suspend();
-
-		if (this._pendingResumeTimer != null) {
-			clearTimeout(this._pendingResumeTimer);
-			this._pendingResumeTimer = undefined;
-		}
-	}
-
-	@trace({ onlyExit: true })
-	resume(delayMs?: number): void {
-		if (delayMs) {
-			if (this._pendingResumeTimer != null) {
-				clearTimeout(this._pendingResumeTimer);
-			}
-			this._pendingResumeTimer = setTimeout(() => {
-				this._pendingResumeTimer = undefined;
-				this.resume();
-			}, delayMs);
-			return;
-		}
-
-		const scope = getScopedLogger();
-
-		if (!this._suspended) {
-			scope?.addExitInfo('ignored; not suspended');
-			return;
-		}
-
-		this._suspended = false;
-		this._watchHandle?.session.resume();
-	}
-
 	waitForRepoChange(timeoutMs: number): Promise<boolean> {
 		let timeoutId: ReturnType<typeof setTimeout> | undefined;
 		let listener: UnifiedDisposable | undefined;
@@ -313,17 +256,57 @@ export class Repository {
 		]);
 	}
 
+	/**
+	 * Starts watching this repository's `.git` directory for repo-change events (delivered via
+	 * {@link onDidChange}) and returns a lease. Ref-counted: the underlying watch handle is acquired
+	 * on the first lease (across `watch()` and {@link watchWorkingTree}) and released when the last
+	 * is disposed. The model is inert until watched. No-ops (returns a disposable that does nothing)
+	 * for repositories without a git directory (e.g. virtual repos).
+	 */
+	@trace({ onlyExit: true })
+	watch(): UnifiedDisposable {
+		const acquired = this.acquireWatchHandle();
+		if (acquired == null) return createDisposable(() => {});
+
+		if (this._watchRefs++ === 0) {
+			const sub = acquired.handle.session.subscribe();
+			this._repoSubscription = sub;
+			this._repoChangeListener = sub.onDidChange(e => this.onSessionRepoChange(e));
+		}
+
+		return createDisposable(
+			() => {
+				// Repo already torn down — its handle/subscriptions are gone; skip to avoid a negative refcount
+				if (this._disposed) return;
+
+				if (--this._watchRefs === 0) {
+					this._repoChangeListener?.dispose();
+					this._repoChangeListener = undefined;
+					this._repoSubscription?.dispose();
+					this._repoSubscription = undefined;
+				}
+				acquired.lease.dispose();
+			},
+			{ once: true },
+		);
+	}
+
 	@trace({ onlyExit: true })
 	watchWorkingTree(delay: number = 2500): UnifiedDisposable {
-		const sub = this._watchHandle?.session.subscribeToWorkingTree({ delayMs: delay });
-		if (sub == null) return createDisposable(() => {});
+		const acquired = this.acquireWatchHandle();
+		if (acquired == null) return createDisposable(() => {});
 
+		const sub = acquired.handle.session.subscribeToWorkingTree({ delayMs: delay });
 		const listener = sub.onDidChangeWorkingTree(e => this.onWorkingTreeChanged(e.paths));
 
-		return createDisposable(() => {
-			listener.dispose();
-			sub.dispose();
-		});
+		return createDisposable(
+			() => {
+				listener.dispose();
+				sub.dispose();
+				acquired.lease.dispose();
+			},
+			{ once: true },
+		);
 	}
 
 	/**
@@ -338,7 +321,7 @@ export class Repository {
 	protected fireChange(change: RepositoryChange, force: boolean): void;
 	@trace()
 	protected fireChange(...args: RepositoryChange[] | [RepositoryChange, boolean]): void {
-		const lastArg = args[args.length - 1];
+		const lastArg = args.at(-1);
 		const force = typeof lastArg === 'boolean' ? lastArg : false;
 		const changes = (force ? args.slice(0, -1) : args) as RepositoryChange[];
 
@@ -353,9 +336,6 @@ export class Repository {
 		this._watchHandle?.session.fireChange(...changes);
 	}
 
-	/** Called when the closed state changes. Override to add behavior (e.g., branch access tracking). */
-	protected onClosedChanged(_closed: boolean): void {}
-
 	/** Called when the watch service notifies of FETCH_HEAD changes. */
 	protected onFetchHeadChanged(): void {
 		// Don't reset `_lastFetched` here: the FS watcher can fire even when the on-disk mtime
@@ -414,39 +394,50 @@ export class Repository {
 			(this._pendingWorkingTreeChange.uris as Set<Uri>).add(fileUri(p));
 		}
 
-		if (this._suspended) return;
 		if (this._pendingWorkingTreeFlush) return;
 
 		this._pendingWorkingTreeFlush = true;
 		queueMicrotask(() => {
 			this._pendingWorkingTreeFlush = false;
 			const e = this._pendingWorkingTreeChange;
-			if (e == null || this._suspended) return;
+			if (e == null) return;
 
 			this._pendingWorkingTreeChange = undefined;
 			this._onDidChangeWorkingTree.fire(e);
 		});
 	}
 
-	@trace({ onlyExit: true })
-	private setupWatching(): void {
-		if (this._gitDir == null || this._closed) return;
-		if (this._repoSubscription != null) return;
-
-		const scope = getScopedLogger();
+	/**
+	 * Lazily acquires (and ref-counts) the shared {@link _watchHandle} for this repository, returning
+	 * the handle plus a one-shot lease whose disposal decrements the ref count (releasing the handle
+	 * when the last lease is gone). Returns `undefined` for repositories without a git directory.
+	 */
+	private acquireWatchHandle(): { handle: WatchHandle; lease: UnifiedDisposable } | undefined {
+		if (this._gitDir == null || this._disposed) return undefined;
 
 		this._watchHandle ??= this._watchService.watch(this.path, this._gitDir, {
 			onFetchHeadChanged: () => this.onFetchHeadChanged(),
 			onGitIgnoreChanged: () => this.onGitIgnoreChanged(),
 			onIgnoresChanged: () => this.onIgnoresChanged(),
 		} satisfies WatchHooks);
-		if (this._watchHandle == null) return;
-
-		const sub = this._watchHandle.session.subscribe();
-		this._repoSubscription = sub;
-		this._repoChangeListener = sub.onDidChange(e => this.onSessionRepoChange(e));
-
-		scope?.trace(`subscribed to repo changes for '${this.uri.toString()}'`);
+		const handle = this._watchHandle;
+		if (handle == null) return undefined;
+
+		this._watchHandleRefs++;
+		const lease = createDisposable(
+			() => {
+				// Repo already torn down — the handle is gone; skip to avoid a negative refcount
+				if (this._disposed) return;
+
+				if (--this._watchHandleRefs === 0) {
+					this._watchHandle?.dispose();
+					this._watchHandle = undefined;
+				}
+			},
+			{ once: true },
+		);
+
+		return { handle: handle, lease: lease };
 	}
 
 	static is(repository: unknown): repository is Repository {

package/src/git/models/statusFile.ts

@@ -94,6 +94,18 @@ export class GitStatusFile implements GitFile {
 		return this.conflictStatus != null;
 	}
 
+	/**
+	 * True when the file has both staged (index) and unstaged (working-tree) changes and is not
+	 * conflicted. Used by the host-side discard flows to apply partial-discard semantics — drop the
+	 * working-tree delta while preserving the staged portion. Centralized here so those host paths
+	 * agree on what "mixed" means. (The webview button predicate can't consume this getter — it
+	 * runs against the wire `GitFileChangeShape` and infers the same state from the duplicate
+	 * staged/unstaged rows the WIP feed emits per mixed path.)
+	 */
+	get mixed(): boolean {
+		return this.indexStatus != null && this.workingTreeStatus != null && this.conflictStatus == null;
+	}
+
 	get staged(): boolean {
 		return this.indexStatus != null;
 	}

package/src/git/providers/commits.ts

@@ -78,6 +78,10 @@ export interface GitCommitReachability {
 export interface GitCommitsSubProvider {
 	getCommit(repoPath: string, rev: string, cancellation?: AbortSignal): Promise<GitCommit | undefined>;
 	getCommitCount(repoPath: string, rev: string, cancellation?: AbortSignal): Promise<number | undefined>;
+	/** Whether `rev` has any commits not reachable from any remote-tracking ref (i.e. unpushed/unpublished).
+	 *  Cheap early-exit probe (`rev-list --not --remotes <rev> -n 1`) — it does NOT count them. Returns
+	 *  `undefined` when it can't be determined. */
+	hasUnpublishedCommits?(repoPath: string, rev: string, cancellation?: AbortSignal): Promise<boolean | undefined>;
 	/** Cheap author/committer date lookup for a single revision. Skips the full commit parse (no files, parents, or message) — use when only the dates are needed. Pass a full SHA so caching stays correct (commits are immutable; refs are not). */
 	getCommitDates?(
 		repoPath: string,

package/src/git/providers/config.ts

@@ -88,11 +88,7 @@ export interface GitConfigSubProvider {
 		| []
 	>;
 
-	getGkConfig?(
-		repoPath: string,
-		key: GkConfigKeys | DeprecatedGkConfigKeys,
-		options?: { type?: GitConfigType },
-	): Promise<string | undefined>;
+	getGkConfig?(repoPath: string, key: GkConfigKeys | DeprecatedGkConfigKeys): Promise<string | undefined>;
 	getGkConfigRegex?(repoPath: string, pattern: string): Promise<Map<string, string>>;
 	setGkConfig?(
 		repoPath: string,

package/src/git/providers/operations.ts

@@ -21,31 +21,14 @@ export interface GitOperationResult {
 export type GitOperationRunOptions = Pick<GitRunOptions, 'env' | 'cancellation' | 'timeout'>;
 
 export interface GitOperationsSubProvider {
-	checkout(
-		repoPath: string,
-		ref: string,
-		options?: { createBranch?: string | undefined } | { path?: string | undefined },
-		runOptions?: GitOperationRunOptions,
-	): Promise<void>;
 	/**
-	 * Checks out one side of a conflicted path during a paused merge/rebase/cherry-pick.
-	 * Executes `git checkout --ours|--theirs -- <path>`, leaving the file unstaged.
+	 * Switches the repository to a branch or ref. Pure branch/ref switching — does not accept
+	 * a path. For path-level operations use {@link restore}.
 	 */
-	checkoutConflictedPath(
-		repoPath: string,
-		path: string,
-		side: 'ours' | 'theirs',
-		runOptions?: GitOperationRunOptions,
-	): Promise<void>;
-	/**
-	 * Checks out one side for multiple conflicted paths during a paused merge/rebase/cherry-pick.
-	 * Batches paths into `git checkout --ours|--theirs -- <paths...>`, chunked to stay under the
-	 * CLI length limit. Leaves files unstaged.
-	 */
-	checkoutConflictedPaths(
+	checkout(
 		repoPath: string,
-		paths: string[],
-		side: 'ours' | 'theirs',
+		ref: string,
+		options?: { createBranch?: string | undefined },
 		runOptions?: GitOperationRunOptions,
 	): Promise<void>;
 	cherryPick(
@@ -110,8 +93,24 @@ export interface GitOperationsSubProvider {
 		options?: {
 			autoStash?: boolean;
 			branch?: string;
+			/** Command set as `sequence.editor` — edits the interactive rebase todo list. */
 			editor?: string;
 			interactive?: boolean;
+			/**
+			 * Set when the `editor` is a script that rewrites the todo by command word + SHA (e.g. the
+			 * Commit Graph's headless squash/drop/reword) rather than a human. Forces git to emit a plain,
+			 * natural-order todo by disabling `rebase.autosquash` (which would reorder commits and rewrite
+			 * `pick`→`fixup` for `fixup!`/`squash!` commits) and `rebase.abbreviateCommands` (which would
+			 * emit `p` instead of `pick`). Both honor the user's git config otherwise.
+			 */
+			programmaticEditor?: boolean;
+			/**
+			 * Command git uses to edit per-commit messages (the combined message a `squash` produces, or a
+			 * `reword`). Applied as `GIT_EDITOR` — which git's interactive-rebase `reword`/`squash` step honors,
+			 * unlike `core.editor` — with `core.editor` also set as a fallback. When omitted, git falls back to
+			 * the user's configured editor.
+			 */
+			messageEditor?: string;
 			onto?: string;
 			updateRefs?: boolean;
 			source?: unknown;
@@ -124,6 +123,27 @@ export interface GitOperationsSubProvider {
 		options?: { mode?: 'hard' | 'keep' | 'merge' | 'mixed' | 'soft' },
 		runOptions?: GitOperationRunOptions,
 	): Promise<void>;
+	/**
+	 * Restores the working-tree copy of one or more paths. Single path or array; arrays are
+	 * chunked under the CLI length limit and dispatched as one git invocation per chunk
+	 * (typically one for normal-sized batches).
+	 *
+	 * Source selection — `options` is mutually exclusive (`side` wins if both are supplied):
+	 *
+	 * - **No options** (`git checkout -- <paths>`): copies the index to the working tree, leaving
+	 *   the index untouched. Use to drop unstaged changes (mixed-file partial discard preserves
+	 *   the staged portion this way).
+	 * - **`{ ref }`** (`git checkout <ref> -- <paths>`): resets BOTH the index and the working
+	 *   tree of the path(s) to `<ref>`. Use to fully revert files to HEAD, a specific commit, etc.
+	 * - **`{ side }`** (`git checkout --ours|--theirs -- <paths>`): conflict-resolution
+	 *   shortcut, valid only during a paused merge/rebase/cherry-pick. Leaves files unstaged.
+	 */
+	restore(
+		repoPath: string,
+		path: string | string[],
+		options?: { ref?: string; side?: 'ours' | 'theirs' },
+		runOptions?: GitOperationRunOptions,
+	): Promise<void>;
 	revert(
 		repoPath: string,
 		refs: string[],

package/src/git/remotes/custom.ts

@@ -35,6 +35,29 @@ export class CustomRemoteProvider extends RemoteProvider {
 		return [];
 	}
 
+	get avatarUrlTemplate(): string | undefined {
+		return this.urls.avatar;
+	}
+
+	getUrlForAvatar(email: string, size: number): string | undefined {
+		if (this.urls.avatar == null) return undefined;
+
+		// Split on the last `@` so local-parts that contain `@` are preserved (per RFC 5322)
+		const at = email.lastIndexOf('@');
+		const emailName = at === -1 ? email : email.slice(0, at);
+		const domain = at === -1 ? '' : email.slice(at + 1);
+
+		// Component-encode identity values — commit emails are attacker-controllable and
+		// must never be able to inject URL-structural characters (`/`, `?`, `#`, ...) into the
+		// resulting URL
+		return interpolate(this.urls.avatar, {
+			email: encodeURIComponent(email),
+			emailName: encodeURIComponent(emailName),
+			domain: encodeURIComponent(domain),
+			size: String(size),
+		});
+	}
+
 	protected override getUrlForRepository(): string {
 		return this.getUrl(this.urls.repository, this.getContext());
 	}

package/src/git/utils/contributor.utils.ts

@@ -79,3 +79,27 @@ export function calculateDistribution<T extends string>(
 export function matchContributor(c: GitContributor, user: GitUser): boolean {
 	return c.name === user.name && c.email === user.email && c.username === user.username;
 }
+
+/** Appends `Co-authored-by:` trailers for the given coauthors to a commit message, replacing
+ *  any existing trailer block. Each coauthor is the `Name <email>` form (GitContributor.coauthor). */
+export function appendCoauthorsToMessage(message: string, coauthors: Iterable<string>): string {
+	const index = message.indexOf('Co-authored-by: ');
+	if (index !== -1) {
+		message = message.substring(0, index - 1).trimEnd();
+	}
+
+	for (const coauthor of coauthors) {
+		let newlines;
+		if (message.includes('Co-authored-by: ')) {
+			newlines = '\n';
+		} else if (message.length !== 0 && message.endsWith('\n')) {
+			newlines = '\n\n';
+		} else {
+			newlines = '\n\n\n';
+		}
+
+		message += `${newlines}Co-authored-by: ${coauthor}`;
+	}
+
+	return message;
+}