xtralab 0.1.2 → 0.3.0

package/src/fileBrowser/fileBrowser.tsx

@@ -12,7 +12,10 @@ import type {
   FileTreeDirectoryHandle
 } from '@pierre/trees';
 
+import type { Ignore } from 'ignore';
+
 import { ROOT_LOAD_KEY, listDirectory, toServerPath } from './contents';
+import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
 import { FILE_BROWSER_ICONS } from './icons';
 import type { XtralabFileBrowser } from './widget';
 
@@ -29,7 +32,7 @@ type LoadState = 'unloaded' | 'loading' | 'loaded';
  * synchronous function that returns a Widget. The contents MIME types
  * mirror what the default file browser sends so other drop targets that
  * understand them (the file browser itself, custom drop zones) keep
- * working when the user drags out of Xtralab.
+ * working when the user drags out of xtralab.
  */
 const FACTORY_MIME = 'application/vnd.lumino.widget-factory';
 const CONTENTS_MIME = 'application/x-jupyter-icontents';
@@ -76,13 +79,57 @@ export function FileBrowserComponent(
     paths: [],
     initialExpansion: 'closed',
     search: true,
-    icons: FILE_BROWSER_ICONS
+    icons: FILE_BROWSER_ICONS,
+    itemHeight: 24
   });
 
   React.useEffect(() => {
     const knownDirs = new Map<string, LoadState>();
+    // Mirror of the canonical paths currently loaded into the tree. Kept in
+    // sync with `model.resetPaths`/`model.batch`/`model.add` so we can
+    // re-test every loaded path against the gitignore matcher whenever
+    // either side changes — the model itself does not expose a
+    // path-iteration API.
+    const loadedPaths = new Set<string>();
+    let gitignoreMatcher: Ignore | null = null;
     let cancelled = false;
 
+    /**
+     * Recompute the `ignored` git status entries from the current
+     * gitignore matcher and the set of loaded paths, and push them into
+     * the tree. Safe to call at any time: when the matcher is `null`
+     * (no `.gitignore` or it failed to load) we send an empty list, which
+     * also clears any statuses that may have been applied previously.
+     */
+    const syncGitStatus = (): void => {
+      if (gitignoreMatcher === null) {
+        model.setGitStatus([]);
+        return;
+      }
+      const entries = buildIgnoredEntries(gitignoreMatcher, loadedPaths);
+      model.setGitStatus(entries);
+    };
+
+    /**
+     * Reload the workspace `.gitignore`, then re-apply the resulting
+     * ignored statuses. Called on initial mount and whenever the user
+     * triggers a refresh — the file may have been edited or created in
+     * between.
+     */
+    const refreshGitignoreMatcher = async (): Promise<void> => {
+      let next: Ignore | null = null;
+      try {
+        next = await loadGitignoreMatcher(contentsManager);
+      } catch (err) {
+        console.error('xtralab: failed to load .gitignore', err);
+      }
+      if (cancelled) {
+        return;
+      }
+      gitignoreMatcher = next;
+      syncGitStatus();
+    };
+
     const fetchDirectory = async (canonicalPath: string): Promise<void> => {
       const current = knownDirs.get(canonicalPath);
       if (current === 'loading' || current === 'loaded') {
@@ -100,6 +147,10 @@ export function FileBrowserComponent(
         }
         if (canonicalPath === ROOT_LOAD_KEY) {
           model.resetPaths(paths);
+          loadedPaths.clear();
+          for (const path of paths) {
+            loadedPaths.add(path);
+          }
         } else {
           // Filter out paths already in the model. The path-store throws
           // when an explicit directory is added a second time, so any
@@ -111,6 +162,14 @@ export function FileBrowserComponent(
           if (operations.length > 0) {
             model.batch(operations);
           }
+          // Mirror every directory child into `loadedPaths` regardless of
+          // whether it was just added or skipped above — paths skipped by
+          // the filter are already in the model from a prior add and so
+          // belong in the mirror too. `Set.add` is idempotent, so the
+          // duplicate adds are a no-op.
+          for (const path of paths) {
+            loadedPaths.add(path);
+          }
         }
         for (const subdir of subdirectories) {
           if (!knownDirs.has(subdir)) {
@@ -118,6 +177,7 @@ export function FileBrowserComponent(
           }
         }
         knownDirs.set(canonicalPath, 'loaded');
+        syncGitStatus();
       } catch (err) {
         console.error(
           `xtralab: failed to load directory "${canonicalPath}"`,
@@ -216,6 +276,10 @@ export function FileBrowserComponent(
       // Reset the tree contents and restore the load-state map so future
       // expansions know which directories still need fetching.
       model.resetPaths(allPaths);
+      loadedPaths.clear();
+      for (const path of allPaths) {
+        loadedPaths.add(path);
+      }
       knownDirs.set(ROOT_LOAD_KEY, 'loaded');
       subdirsByParent.forEach(subdirs => {
         for (const subdir of subdirs) {
@@ -226,6 +290,13 @@ export function FileBrowserComponent(
         }
       });
 
+      // Refresh the `.gitignore` matcher in case the file was edited
+      // since the last load, then re-apply the resulting statuses to the
+      // newly-loaded paths. The reload runs in parallel with the rest of
+      // the refresh — `refreshGitignoreMatcher` calls `syncGitStatus`
+      // itself when it completes.
+      void refreshGitignoreMatcher();
+
       // Re-expand the directories that were expanded before the refresh.
       // We have to do this after `resetPaths` because the reset starts
       // every directory in its initial collapsed state.
@@ -251,12 +322,14 @@ export function FileBrowserComponent(
           return;
         }
       }
+      loadedPaths.add(canonicalPath);
       if (canonicalPath.endsWith('/') && !knownDirs.has(canonicalPath)) {
         // The new directory has no children yet, so mark it as already
         // loaded — there's nothing to fetch and we don't want a stale
         // "unloaded" entry to trigger a fetch on the next expand.
         knownDirs.set(canonicalPath, 'loaded');
       }
+      syncGitStatus();
       const parent = parentOf(canonicalPath);
       if (parent === ROOT_LOAD_KEY) {
         return;
@@ -273,6 +346,7 @@ export function FileBrowserComponent(
 
     knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
     void fetchDirectory(ROOT_LOAD_KEY);
+    void refreshGitignoreMatcher();
 
     const unsubscribe = model.subscribe(() => {
       knownDirs.forEach((state, canonicalPath) => {

package/src/fileBrowser/gitignore.ts

@@ -0,0 +1,86 @@
+import ignore from 'ignore';
+import type { Ignore } from 'ignore';
+
+import { Contents } from '@jupyterlab/services';
+
+import type { GitStatusEntry } from '@pierre/trees';
+
+/**
+ * The path of the workspace `.gitignore` file. Loaded relative to the
+ * Jupyter contents root, which matches the directory the gitignore patterns
+ * are evaluated against — patterns and tested paths share the same base.
+ */
+const GITIGNORE_PATH = '.gitignore';
+
+/**
+ * Load the workspace `.gitignore` and return an `ignore` matcher built from
+ * its contents. Returns `null` when the file is missing, empty, or fails to
+ * load — callers should treat any of those as "no ignored entries".
+ */
+export async function loadGitignoreMatcher(
+  contentsManager: Contents.IManager
+): Promise<Ignore | null> {
+  let model: Contents.IModel;
+  try {
+    model = await contentsManager.get(GITIGNORE_PATH, {
+      content: true,
+      format: 'text',
+      type: 'file'
+    });
+  } catch {
+    // The most common failure here is `.gitignore` simply not existing.
+    // Other transient errors (permission denied, server unreachable) are
+    // also treated as "no matcher" so the file browser still works.
+    return null;
+  }
+  if (model.type !== 'file' || typeof model.content !== 'string') {
+    return null;
+  }
+  if (model.content.length === 0) {
+    return null;
+  }
+  return ignore().add(model.content);
+}
+
+/**
+ * Build `GitStatusEntry`s for the canonical paths that match the given
+ * gitignore matcher.
+ *
+ * `@pierre/trees` propagates the `ignored` style from a directory entry
+ * down to every descendant via its internal `ignoredDirectoryPaths` set, so
+ * we only emit one entry per ignored subtree root: emitting descendants
+ * would also pollute the library's `directoriesWithChanges` set, causing
+ * parent directories of nested ignored items to render a "contains git
+ * status items" dot.
+ *
+ * Paths are sorted lexicographically so a directory always precedes its
+ * descendants, allowing a simple ancestor-suppression check via
+ * `path.startsWith(dir)`. The trailing slash on canonical directory paths
+ * (required by `@pierre/trees`, also recognized by `ignore` as the
+ * "directory" indicator) keeps the prefix check from accidentally matching
+ * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
+ * vs `node_modules/`).
+ */
+export function buildIgnoredEntries(
+  matcher: Ignore,
+  canonicalPaths: Iterable<string>
+): GitStatusEntry[] {
+  const sorted = Array.from(canonicalPaths).sort();
+  const emittedIgnoredDirs: string[] = [];
+  const entries: GitStatusEntry[] = [];
+  for (const path of sorted) {
+    if (path.length === 0) {
+      continue;
+    }
+    if (emittedIgnoredDirs.some(dir => path.startsWith(dir))) {
+      continue;
+    }
+    if (matcher.ignores(path)) {
+      entries.push({ path, status: 'ignored' });
+      if (path.endsWith('/')) {
+        emittedIgnoredDirs.push(path);
+      }
+    }
+  }
+  return entries;
+}

package/src/fileBrowser/icons.ts

@@ -7,9 +7,9 @@ import {
 import type { FileTreeIconConfig } from '@pierre/trees';
 
 /**
- * The glyph used as the Xtralab file browser's sidebar tab icon. Defined as a
+ * The glyph used as the xtralab file browser's sidebar tab icon. Defined as a
  * `LabIcon` (rather than the default `folderIcon` from
- * `@jupyterlab/ui-components`) so the Xtralab browser is visually distinguishable
+ * `@jupyterlab/ui-components`) so the xtralab browser is visually distinguishable
  * from JupyterLab's built-in file browser, which also lives in the left
  * sidebar.
  *
@@ -49,7 +49,7 @@ const JUPYTER_NOTEBOOK_SPRITE_SHEET = `<svg data-icon-sprite aria-hidden="true"
 </svg>`;
 
 /**
- * Icon configuration for the Xtralab file browser. Keeps the default `complete`
+ * Icon configuration for the xtralab file browser. Keeps the default `complete`
  * built-in icon set (the colored language icons) and layers a Jupyter notebook
  * symbol on top so `.ipynb` files render with the JupyterLab notebook glyph.
  *
@@ -121,7 +121,7 @@ function extractSymbol(
 }
 
 /**
- * Return a JupyterLab `LabIcon` matching the icon the Xtralab file tree would
+ * Return a JupyterLab `LabIcon` matching the icon the xtralab file tree would
  * render for the given file path. Used by other plugins (e.g. the git diff
  * viewer) that want their main-area widget tabs to display the same per-file
  * glyph the tree shows in the sidebar.

package/src/fileBrowser/widget.tsx

@@ -12,7 +12,7 @@ import { xtralabFileBrowserIcon } from './icons';
 export const FILE_BROWSER_ID = 'xtralab:file-browser';
 
 /**
- * The CSS class added to the Xtralab file browser widget. The selectors that
+ * The CSS class added to the xtralab file browser widget. The selectors that
  * bind application context menu items hang off this class, so it must remain
  * specific enough not to clash with other browsers (such as the default
  * `jp-FileBrowser`).
@@ -29,7 +29,7 @@ export interface IXtralabFileBrowserOptions {
 }
 
 /**
- * Public API of the Xtralab file browser used by command handlers and other
+ * Public API of the xtralab file browser used by command handlers and other
  * collaborators. Kept narrow on purpose so the React component stays free to
  * evolve the underlying tree integration.
  */
@@ -100,7 +100,7 @@ export class XtralabFileBrowser extends Widget implements IXtralabFileBrowser {
     this._onOpenFile = options.onOpenFile;
     this.id = FILE_BROWSER_ID;
     this.title.icon = xtralabFileBrowserIcon;
-    this.title.caption = 'Xtralab File Browser';
+    this.title.caption = 'xtralab File Browser';
     this.addClass(FILE_BROWSER_CSS_CLASS);
 
     this._toolbar = new Toolbar();

package/src/git/api.ts

@@ -145,6 +145,26 @@ export async function checkout(
   });
 }
 
+/**
+ * Expand the porcelain `files` array into one entry per logical change.
+ * A single porcelain row may map to two `IFileChange` rows (a file that's
+ * both staged and modified again in the worktree); callers that just want
+ * a flat list of all changes — without any staged-vs-unstaged grouping —
+ * can use this helper.
+ *
+ * Provided as a manual concat rather than `Array.prototype.flatMap` so we
+ * don't pin our `tsconfig.lib` to ES2019.
+ */
+export function expandStatusFiles(files: IGitStatusFile[]): IFileChange[] {
+  const result: IFileChange[] = [];
+  for (const file of files) {
+    for (const change of porcelainToFileChanges(file)) {
+      result.push(change);
+    }
+  }
+  return result;
+}
+
 /**
  * Translate one entry in the porcelain `files` array into the panel's
  * preferred shape. A single porcelain entry may represent up to two changes

package/src/git/commands.ts

@@ -5,7 +5,11 @@ import { Contents } from '@jupyterlab/services';
 import { refreshIcon } from '@jupyterlab/ui-components';
 import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 
-import { createGitDiffWidget, diffWidgetId } from './diffWidget';
+import {
+  createGitDiffWidget,
+  diffWidgetId,
+  updateGitDiffWidget
+} from './diffWidget';
 import { GitPanel } from './panel';
 import { IFileChange } from './tokens';
 
@@ -29,6 +33,7 @@ export namespace CommandArguments {
   export interface IOpenDiff {
     repoPath: string;
     change: IFileChange;
+    pin?: boolean;
   }
 }
 
@@ -65,8 +70,10 @@ export interface IRegisterGitCommandsOptions {
    * `undefined` when none is open.
    */
   findDiff(
-    change: IFileChange
+    change: IFileChange,
+    pin?: boolean
   ): ReturnType<typeof createGitDiffWidget> | undefined;
+  onPinned(widget: ReturnType<typeof createGitDiffWidget>): void;
 }
 
 /**
@@ -86,7 +93,8 @@ export function registerGitCommands(
     rendermime,
     onChanged,
     trackDiff,
-    findDiff
+    findDiff,
+    onPinned
   } = options;
   const { commands } = app;
 
@@ -107,8 +115,12 @@ export function registerGitCommands(
       if (typed?.change === undefined) {
         return;
       }
-      const existing = findDiff(typed.change);
+      const pin = typed.pin === true;
+      const existing = findDiff(typed.change, pin);
       if (existing !== undefined && !existing.isDisposed) {
+        if (!pin) {
+          updateGitDiffWidget(existing, typed.change);
+        }
         app.shell.activateById(existing.id);
         return;
       }
@@ -118,7 +130,9 @@ export function registerGitCommands(
         themeManager,
         contentsManager,
         rendermime,
-        onChanged
+        onChanged,
+        pinned: pin,
+        onPinned
       });
       await trackDiff(widget);
       app.shell.add(widget, 'main', { mode: 'tab-after' });

package/src/git/diffWidget.tsx

@@ -4,7 +4,12 @@ import { IThemeManager, MainAreaWidget } from '@jupyterlab/apputils';
 import { PathExt } from '@jupyterlab/coreutils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { Contents } from '@jupyterlab/services';
-import { ReactWidget, undoIcon } from '@jupyterlab/ui-components';
+import {
+  ReactWidget,
+  ToolbarButton,
+  launchIcon,
+  undoIcon
+} from '@jupyterlab/ui-components';
 import { ISignal, Signal } from '@lumino/signaling';
 import { FileDiff } from '@pierre/diffs/react';
 import {
@@ -30,6 +35,12 @@ import { GitReference, IFileChange } from './tokens';
  */
 export const DIFF_WIDGET_CSS_CLASS = 'jp-xtralab-DiffWidget';
 
+export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
+
+export function pinnedDiffWidgetId(change: IFileChange): string {
+  return `xtralab:diff:pinned:${change.group}:${change.path}`;
+}
+
 /**
  * `localStorage` key for the user's last-chosen split ratio. Persisted so
  * the preference survives reloads — the library has no built-in way to
@@ -143,6 +154,10 @@ export function diffWidgetId(change: IFileChange): string {
   return `xtralab:diff:${change.group}:${change.path}`;
 }
 
+function toServerPath(repoPath: string, filePath: string): string {
+  return repoPath.length > 0 ? PathExt.join(repoPath, filePath) : filePath;
+}
+
 /**
  * Resolve the pair of git references whose `content` should appear on the
  * left and right side of the diff for a given file change. Mirrors VS
@@ -190,6 +205,8 @@ export interface IGitDiffWidgetOptions {
    * would just be visual noise.
    */
   onEmpty?: () => void;
+  onPinned?: (widget: MainAreaWidget<DiffContentWidget>) => void;
+  pinned?: boolean;
 }
 
 /**
@@ -216,44 +233,88 @@ export function createGitDiffWidget(
     }
   });
   widget = new MainAreaWidget<DiffContentWidget>({ content });
-  widget.id = diffWidgetId(options.change);
+  widget.id =
+    options.pinned === true
+      ? pinnedDiffWidgetId(options.change)
+      : PREVIEW_DIFF_WIDGET_ID;
   widget.title.label = formatTitle(options.change);
   widget.title.caption = options.change.path;
   widget.title.closable = true;
   widget.title.icon = getTreeIcon(options.change.path);
+  widget.title.className = options.pinned === true ? '' : 'jp-mod-preview';
+  const onPinned = options.onPinned ?? (() => {});
   widget.addClass(DIFF_WIDGET_CSS_CLASS);
   // Wire the notebook view-mode selector into the `MainAreaWidget` toolbar
   // — the proper home for document chrome controls. The toolbar starts
   // hidden and becomes visible once the React content reports a parsed
   // notebook diff via `setHasNotebookView`. Plain text / code diffs never
-  // flip that flag, so their toolbar bar stays collapsed and the
-  // resulting layout matches what other read-only main-area documents
-  // look like in JupyterLab.
+  // flip that flag, and pin state can hide the toolbar again, so the host
+  // chrome tracks the active mode.
+  const pinButton = new ToolbarButton({
+    icon: launchIcon,
+    tooltip: 'Pin tab',
+    onClick: () => content.pin()
+  });
+  if (content.pinned) {
+    pinButton.hide();
+  }
+  widget.toolbar.addItem('pin', pinButton);
   widget.toolbar.addItem(
     'notebook-view-mode',
     new NotebookViewModeToolbarItem(content)
   );
-  widget.toolbar.hide();
-  const onHasNotebookViewChanged = (
-    _sender: DiffContentWidget,
-    value: boolean
-  ): void => {
+  const syncToolbarVisibility = (): void => {
     if (widget === null || widget.isDisposed) {
       return;
     }
-    if (value) {
+    if (!content.pinned || content.hasNotebookView) {
       widget.toolbar.show();
     } else {
       widget.toolbar.hide();
     }
   };
+  const onHasNotebookViewChanged = (): void => {
+    if (widget === null || widget.isDisposed) {
+      return;
+    }
+    syncToolbarVisibility();
+  };
+  const onPinnedChanged = (sender: DiffContentWidget, value: boolean): void => {
+    if (widget === null || widget.isDisposed) {
+      return;
+    }
+    void sender;
+    if (value) {
+      pinButton.hide();
+      // Keep toolbar state and title styling consistent for promoted tabs.
+      onPinned(widget);
+      if (widget.isDisposed) {
+        return;
+      }
+      widget.title.className = '';
+    }
+    syncToolbarVisibility();
+  };
   content.hasNotebookViewChanged.connect(onHasNotebookViewChanged);
+  content.pinnedChanged.connect(onPinnedChanged);
+  syncToolbarVisibility();
   widget.disposed.connect(() => {
     content.hasNotebookViewChanged.disconnect(onHasNotebookViewChanged);
+    content.pinnedChanged.disconnect(onPinnedChanged);
   });
   return widget;
 }
 
+export function updateGitDiffWidget(
+  widget: MainAreaWidget<DiffContentWidget>,
+  change: IFileChange
+): void {
+  widget.content.setChange(change);
+  widget.title.label = formatTitle(change);
+  widget.title.caption = change.path;
+  widget.title.icon = getTreeIcon(change.path);
+}
+
 /**
  * The actual React-rendered region of the diff viewer. Held in its own
  * `ReactWidget` so the surrounding `MainAreaWidget` can manage chrome
@@ -270,6 +331,7 @@ export class DiffContentWidget extends ReactWidget {
   constructor(options: IGitDiffWidgetOptions) {
     super();
     this._options = options;
+    this._pinned = options.pinned === true;
     this._notebookViewMode = readStoredNotebookViewMode();
   }
 
@@ -320,6 +382,27 @@ export class DiffContentWidget extends ReactWidget {
     return this._hasNotebookViewChanged;
   }
 
+  get pinned(): boolean {
+    return this._pinned;
+  }
+
+  pin(): void {
+    if (this._pinned) {
+      return;
+    }
+    this._pinned = true;
+    this._pinnedChanged.emit(true);
+  }
+
+  get pinnedChanged(): ISignal<this, boolean> {
+    return this._pinnedChanged;
+  }
+
+  setChange(change: IFileChange): void {
+    this._options = { ...this._options, change };
+    this.update();
+  }
+
   protected render(): React.ReactElement {
     return <DiffViewer {...this._options} widget={this} />;
   }
@@ -331,6 +414,8 @@ export class DiffContentWidget extends ReactWidget {
   );
   private _hasNotebookView = false;
   private _hasNotebookViewChanged = new Signal<this, boolean>(this);
+  private _pinned: boolean;
+  private _pinnedChanged = new Signal<this, boolean>(this);
 }
 
 interface IDiffState {
@@ -505,9 +590,16 @@ function DiffViewer(
 
   React.useEffect(() => {
     let cancelled = false;
+    const serverPath = toServerPath(repoPath, change.path);
+    setState({
+      loading: true,
+      metadata: null,
+      notebookDiff: null,
+      serverPath,
+      isBinary: false,
+      error: null
+    });
     const { oldRef, newRef } = resolveReferences(change);
-    const serverPath =
-      repoPath.length > 0 ? PathExt.join(repoPath, change.path) : change.path;
     void (async () => {
       try {
         if (change.isBinary === true) {
@@ -861,6 +953,10 @@ function NotebookViewModeControl(props: {
       content.notebookViewModeChanged.disconnect(handler);
     };
   }, [content]);
+  if (!content.hasNotebookView) {
+    return <></>;
+  }
+
   return (
     <div
       className="jp-xtralab-DiffWidget-segmented"

package/src/git/icons.ts

@@ -6,7 +6,7 @@ import { LabIcon } from '@jupyterlab/ui-components';
  * recoloring and inverse-color sidebar painting automatically.
  *
  * Source: `git-branch` from SVG Repo (https://www.svgrepo.com/svg/377352/git-branch),
- * part of the same Pixelarticons family as the Xtralab file browser's `file-tree`
+ * part of the same Pixelarticons family as the xtralab file browser's `file-tree`
  * icon, so the two sidebar tab glyphs read as a matched set. The original
  * `fill="#000000"` is replaced with `fill="currentColor"` and the root element
  * is given the `jp-icon3` class so the icon picks up JupyterLab's theme color

package/src/git/index.ts

@@ -16,7 +16,11 @@ import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 
 import { CommandArguments, CommandIDs, registerGitCommands } from './commands';
-import { DiffContentWidget, diffWidgetId } from './diffWidget';
+import {
+  DiffContentWidget,
+  PREVIEW_DIFF_WIDGET_ID,
+  pinnedDiffWidgetId
+} from './diffWidget';
 import type { MainAreaWidget } from '@jupyterlab/apputils';
 import { GitPanel } from './panel';
 import { IFileChange } from './tokens';
@@ -62,15 +66,22 @@ const plugin: JupyterFrontEndPlugin<void> = {
     });
 
     const findDiff = (
-      change: IFileChange
+      change: IFileChange,
+      pin = false
     ): MainAreaWidget<DiffContentWidget> | undefined => {
-      const id = diffWidgetId(change);
-      return tracker.find(widget => widget.id === id) ?? undefined;
+      const id = pin ? pinnedDiffWidgetId(change) : PREVIEW_DIFF_WIDGET_ID;
+      const existing = tracker.find(
+        widget => !widget.isDisposed && widget.id === id
+      );
+      return existing ?? undefined;
     };
 
     const panel = new GitPanel({
-      openDiff: change => {
+      openDiff: (change, options) => {
         const args: CommandArguments.IOpenDiff = { repoPath, change };
+        if (options?.pin === true) {
+          args.pin = true;
+        }
         void app.commands.execute(
           CommandIDs.openDiff,
           args as unknown as ReadonlyPartialJSONObject
@@ -101,6 +112,21 @@ const plugin: JupyterFrontEndPlugin<void> = {
       rendermime,
       onChanged: () => panel.refresh(),
       trackDiff: widget => tracker.add(widget),
+      onPinned: current => {
+        const existing = findDiff(current.content.change, true);
+        if (
+          existing !== undefined &&
+          existing !== current &&
+          !existing.isDisposed
+        ) {
+          app.shell.activateById(existing.id);
+          current.close();
+          return;
+        }
+        current.id = pinnedDiffWidgetId(current.content.change);
+        current.title.className = '';
+        app.shell.activateById(current.id);
+      },
       findDiff
     });
   }