@gitkraken/core-gitlens 0.16.5 → 0.17.0

package/dist/git/watching/provider.d.ts

@@ -42,6 +42,12 @@ export interface FileWatcherOptions {
    * already down reports `unwatchable` itself. Going from `unwatchable` to anything else makes core rescan.
    */
   readonly onDidChangeReliability?: (state: FileWatcherReliability) => void;
+  /**
+   * Called once, when a watch the provider places asynchronously goes live: whatever changed under `basePath` between
+   * `createWatcher` and then went unseen, so core rescans. A provider whose watch is live when `createWatcher` returns
+   * never calls it. Passed only to working-tree watchers, whether or not the host opted into polling.
+   */
+  readonly onDidStart?: () => void;
 }
 /**
  * Factory for creating filesystem watchers. The library calls this

package/dist/git/watching/watchGroup.d.ts

@@ -61,14 +61,51 @@ interface SessionEntry {
  * starts, is the baseline and delivers nothing; a report arriving before it completes may describe a change it
  * already holds, so it is delivered unconfined. A read that fails or doesn't settle within a few seconds, or a file
  * git couldn't parse, is unconfined too.
+ *
+ * Given a `readFile`, a `readDirectory` (a directory's entries with their types, only the directories counting as
+ * admin entries) and the folders whose worktrees the host has core ignore (a tool's throwaway worktrees, which no
+ * host shows), the group reports no change of an ignored worktree's admin entry
+ * (`<common>/worktrees/<id>`) to any session. Only registered folders count, since a user may keep real worktrees
+ * anywhere, `.git` included. It lists the entries and reads each one's `gitdir` once as it starts, and again after a
+ * watcher dropped events; a report arriving meanwhile is told at once, and decided once the listing settles, so what
+ * is known of its entry catches up. From then on it reads an entry only when its `gitdir` may be new (the entry was
+ * created, or its `gitdir` written, or it was removed before), so a real worktree's HEAD moves are told at once,
+ * unread. Of two reads of one entry, the later decides both reports. An entry it doesn't know whose `gitdir` can't be
+ * read (a watcher can report one before git writes it, and miss the write) is read once more a moment later, its
+ * reports held until then, and told if it still can't be. Only the entry's directory or its `gitdir` going is a
+ * removal; a deleted `HEAD` (a watcher may report git's lock file renamed over it as a delete) or `locked` is told as
+ * the entry is known. Removing an entry deletes the `gitdir` a read needs, so a removal is told from what the entry was
+ * known to be (before a read that couldn't read it, if one is waiting to read it again), and an entry it never knew is
+ * told as real. Any other report of a removed entry but a delete is read, and one that can't be read is the removal's
+ * own (a watcher may report the entry's directory changed beside each file it deletes), unless it creates the entry
+ * again. A report of the `worktrees` directory itself (a coalesced
+ * removal, a parent directory change, a poll, which sees nothing finer) lists it again: it is told to every session
+ * when a real entry was added or removed since the last listing, and to none when only ignored ones were. Git removes
+ * the directory with its last entry, so a directory that isn't there is an empty listing, as is a removal of it that
+ * can't be listed. Since a listing (or a worktree moved into or out of a folder) changes what every session shows, it
+ * is told to all of them; the other watcher's report of the same change then finds nothing left to tell. Where only a
+ * poll watches the common dir, it sees just the `worktrees` directory, so an entry removed and added again under the
+ * same id between two polls, or an entry's HEAD or lock changed in place, goes untold.
+ *
+ * Given the folders, the watchers over the common dir leave each one unwatched, since a tool's checkout there would
+ * otherwise have every directory of it watched; one that shares a top-level directory with what the `.git` watch reads
+ * stays watched.
  */
 export declare class WatchGroup implements UnifiedDisposable {
   readonly commonGitDir: string;
   private readonly provider;
   /** When given, a watcher that reports it can't be trusted is polled; otherwise none is asked */
   private readonly poller?;
-  /** When given, reports of the shared `.git/config` are classified by what changed in it (see above) */
+  /**
+   * When given, reports of the shared `.git/config` are classified by what changed in it, and admin entries are
+   * read to tell an ignored worktree's (see above)
+   */
   private readonly readFile?;
+  /**
+   * Returns a directory's entries with their types; with `readFile`, the admin entries are listed, only the
+   * directories counting (see above)
+   */
+  private readonly readDirectory?;
   private readonly _sessions;
   private _commonWatcher;
   private _commonReliability;
@@ -80,11 +117,52 @@ export declare class WatchGroup implements UnifiedDisposable {
   private _configBaselining;
   private _configReading;
   private _configRereadQueued;
+  /**
+   * Settles once the latest baseline of the admin entries was taken; `undefined` when the group can't tell an
+   * ignored worktree's, so every report is told at once
+   */
+  private _worktreesBaseline;
+  /** A baseline is pending, so a report waits for it */
+  private _worktreesBaselining;
+  private _worktreesRebaselineQueued;
+  /** Set by the first baseline; while empty, nothing is ignored and every report is told at once */
+  private _ignoredWorktreeRoots;
+  /** Listings run one at a time, so each compares with the one before it */
+  private _worktreesQueue;
+  /** The `worktrees` directory's reports waiting on the queued listing; `undefined` while none is queued */
+  private _worktreesRescanQueued;
+  /** The admin entries the last listing found */
+  private _listedWorktreeIds;
+  /** Admin entries known to exist, by id: whether each is an ignored worktree's */
+  private readonly _worktreeIds;
+  /** What removed admin entries were, by id, oldest first */
+  private readonly _removedWorktreeIds;
+  /**
+   * Each id's latest `gitdir` read, settling with what it found and what the id was known to be before it; only it
+   * may update what is known of the id. A removal of the entry drops it
+   */
+  private readonly _worktreeReads;
+  /** Admin entries whose `gitdir` couldn't be read, by id, waiting to be read once more */
+  private readonly _worktreeRetries;
+  /** The `.git` excludes of a watcher over the common git dir, with the ignored worktrees' folders it may leave out */
+  private readonly _commonGitDirExcludes;
   constructor(commonGitDir: string, provider: FileWatchingProvider,
   /** When given, a watcher that reports it can't be trusted is polled; otherwise none is asked */
   poller?: GitDirPoller | undefined,
-  /** When given, reports of the shared `.git/config` are classified by what changed in it (see above) */
-  readFile?: ((path: string) => Promise<Uint8Array>) | undefined);
+  /**
+   * When given, reports of the shared `.git/config` are classified by what changed in it, and admin entries are
+   * read to tell an ignored worktree's (see above)
+   */
+  readFile?: ((path: string) => Promise<Uint8Array>) | undefined,
+  /**
+   * Returns a directory's entries with their types; with `readFile`, the admin entries are listed, only the
+   * directories counting (see above)
+   */
+  readDirectory?: ((path: string) => Promise<readonly (readonly [string, number])[]>) | undefined,
+  /** The absolute, normalized folders whose worktrees are ignored; none reads no admin entry */
+  ignoredWorktreeRoots?: Promise<readonly string[]>,
+  /** The folders whose worktrees are ignored, relative to the common git dir */
+  ignoredWorktreeFolders?: readonly string[]);
   [Symbol.dispose](): void;
   /** Dispose the entire group (common watcher + all root watchers). */
   dispose(): void;
@@ -100,6 +178,12 @@ export declare class WatchGroup implements UnifiedDisposable {
   private disposeCommonWatcher;
   /** Hosts that didn't opt into polling get exactly the options they always had */
   private getWatcherOptions;
+  /**
+   * The ignored worktrees' folders join the `.git` excludes of a watcher over the common git dir: a tool that keeps its
+   * throwaway checkouts inside the git dir would otherwise have each one's every directory watched, and every file it
+   * writes reported. Every other watcher sits on a linked worktree's admin entry, which holds none of them
+   */
+  private getExcludes;
   private setRootReliability;
   private setCommonReliability;
   private stopPolling;
@@ -119,12 +203,67 @@ export declare class WatchGroup implements UnifiedDisposable {
   private onCommonEvent;
   private deliverOverflow;
   private onRootEvent;
+  /** A report of the `worktrees` directory, an admin entry or a file in it, once the group may tell them apart */
+  private isWorktreesReport;
+  /** `deliver` tells the sessions the report reaches of it, should the report concern them (see above) */
+  private onWorktreesReported;
+  private decideWorktreesReport;
+  /**
+   * Reads the entry's `gitdir`: whether it names an ignored worktree (`undefined` when it can't be read), and what the
+   * id was known to be when this read replaced it. Reads of one id can settle out of order (a slow one from before the
+   * worktree moved out of the folder), so only the latest updates what is known of it; an earlier one settles with
+   * what the latest finds, without what the id was, since the latest tells a move itself, or once the entry was removed
+   * since, with what the removal found it was. One that can't read the entry forgets what it was known to be, since git
+   * may be writing its `gitdir` again, and reads it once more a moment later, unless `retry` is false (it then leaves
+   * what is known as it was); one that can settles that read, if pending.
+   */
+  private readWorktreeId;
+  /** Reads the entry once more a moment later, unless that is already pending; `previous` is what it was known to be */
+  private scheduleWorktreeRetry;
+  /**
+   * A report whose read couldn't read the entry waits on the entry's next read, and `deliver` is told then, unless that
+   * read finds an ignored worktree's; one still unreadable is told. Both watchers report each change of an entry, so
+   * the reports of one id wait on one read. Resolves with what it found, as {@link settleWorktreeRetry} does
+   */
+  private waitForWorktreeRetry;
+  /**
+   * Tells the reports waiting on the id's retry what the entry turned out to be: nothing when an ignored worktree's,
+   * every session when it moved into or out of an ignored folder, and the reports' own sessions otherwise, `ignored`
+   * being `undefined` when it still couldn't be read
+   */
+  private settleWorktreeRetry;
+  /**
+   * Takes `id` as removed, remembering what it was for the removal's other reports; returns that, or `undefined` when
+   * the id was never known
+   */
+  private forgetWorktreeId;
+  /** Whether the entry's `gitdir` names an ignored worktree, or `undefined` when it can't be read. Never rejects */
+  private readIgnoredWorktree;
+  private queueWorktreesBaseline;
+  /** A watcher of the `worktrees` directory dropped events: whatever changed meanwhile went unseen */
+  private rebaselineWorktrees;
+  /** The watchers' reports of the directory pile onto one queued listing, which tells them apart */
+  private queueWorktreesRescan;
+  /**
+   * Lists the admin entries and compares them with the last listing. A baseline (or a rebaseline, after a watcher
+   * dropped events) reads every entry; a rescan only those it doesn't know, reading one it can't read once more a
+   * moment later. Git removes the directory with its last entry, so a directory that isn't there is an empty listing,
+   * whatever the reports said of it (a poll sees its removal as a change). A listing that fails otherwise is a
+   * baseline's empty directory, and a rescan's too when one of its reports (`delivers`) removed the directory. For any
+   * other rescan, it is a change it can't rule out, told to the reports' own sessions
+   */
+  private listWorktrees;
+  private deliverWorktreesChange;
   private onConfigReported;
   private readConfigBaseline;
   /** Reads and compares until no report came in during the last read: it may describe a change the read missed */
   private readConfigChanges;
   /** `undefined` when the file couldn't be read or parsed, or the read didn't settle in time */
   private readConfig;
+  /** `undefined` when the file couldn't be read, or the read didn't settle in time */
+  private readWithTimeout;
+  /** `undefined` when `read` rejects, or doesn't settle in time */
+  private withTimeout;
   /**
    * Tells every session of a change to the shared `.git/config`: confined to some branches' sections, or (`undefined`,
    * or a change outside them) anywhere, which may have changed a remote's settings too. Either way no ref moved