Share a linked worktree's local cache with the main worktree

CHANGELOG.md

@@ -19,6 +19,10 @@ Versioning](https://semver.org/spec/v2.0.0.html).
   version, shrinks by one entry per write, and Wireit reminds you once a day
   while it holds more than twice the limit. To free it at once, run
   `rm -rf .wireit/*/cache`. See [#71](https://github.com/google/wireit/issues/71).
+- Set `WIREIT_CACHE_WORKTREES=true` to store a linked Git worktree's local
+  cache in the main worktree's corresponding `.wireit` folders. Any other value
+  keeps each worktree's own cache. Fingerprints and GitHub Actions caching are
+  unchanged.
 
 ### Fixed
 

README.md

@@ -372,6 +372,19 @@ Note the limit is applied per script, so a package with many cached scripts will
 still use a multiple of this space. To free all of it at once, use
 `rm -rf .wireit/*/cache .wireit/*/temp .wireit/trash`.
 
+Linked Git worktrees (`git worktree add`) keep their own `.wireit` cache
+folders. Set `WIREIT_CACHE_WORKTREES=true` to store a linked worktree's local
+cache in the main worktree's corresponding `.wireit` folders. Shared entries
+are named from package-relative paths, so both worktrees hit the same entry.
+Any other value keeps each worktree's own cache and the same entry names as
+before. Worktrees of bare clones, submodules, and checkouts with a separate
+git dir also keep their own cache, since the main git dir's parent isn't a
+checkout. Lock, fingerprint, and output-manifest files stay in the current
+worktree. Fingerprints and GitHub Actions caching are unchanged.
+
+Restored files are copied verbatim. Wireit does not rewrite output contents
+that embed another checkout's absolute path.
+
 ### GitHub Actions caching
 
 In _[GitHub Actions](https://github.com/features/actions)_ mode, Wireit caches
@@ -895,6 +908,7 @@ The following environment variables affect the behavior of Wireit:
 | `WIREIT_FAILURES`          | [How to handle script failures](#failures-and-errors).<br><br>Options:<br><ul><li>[`no-new`](#failures-and-errors) (default): Allow running scripts to finish, but don't start new ones.</li><li>[`continue`](#continue): Allow running scripts to continue, and start new ones unless any of their dependencies failed.</li><li>[`kill`](#kill): Immediately kill running scripts, and don't start new ones.</li></ul>                                                                                                                                                                                                                                                                   |
 | `WIREIT_LOGGER`            | How to present progress and results on the command line.<br><br>Options:<br><ul><li>`quiet` (default for normal execution): Writes a single dynamically updating line summarizing progress. Only passes along stdout and stderr from commands if there's a failure, or if the command is a service.</li><li>`quiet-ci` (default when `env.CI` or `!stdout.isTTY`): like `quiet` but optimized for non-interactive environments, like GitHub Actions runners.</li><li>`simple`: A verbose logger that presents clear information about the work that Wireit is doing.</li><li>`metrics`: Like `simple`, but also presents a summary table of results once a command is finished.</li></ul> |
 | `WIREIT_CACHE_MAX_ENTRIES` | Maximum number of [local cache](#local-caching) entries to retain per script.<br><br>Defaults to `10`.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `WIREIT_CACHE_WORKTREES`   | Set to `true` to store a linked Git worktree's [local cache](#local-caching) in the main worktree's corresponding `.wireit` folders.<br><br>Must be exactly `true`. If unset or any other value, interpreted as `false`. Does not affect fingerprints or GitHub Actions caching.                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `WIREIT_DEBUG_LOG_FILE`    | Path to a file which will receive detailed event logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `WIREIT_MAX_OPEN_FILES`    | Limits the number of file descriptors Wireit will have open concurrently. Prevents resource exhaustion when checking large numbers of cached files. Set to a lower number if you hit file descriptor limits.<br><br>Defaults to `200`.<br><br>Must be a positive integer.                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `WIREIT_PARALLEL`          | [Maximum number of scripts to run at one time](#parallelism).<br><br>Defaults to 2×logical CPU cores.<br><br>Must be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

package.json

@@ -183,7 +183,7 @@
       "output": []
     },
     "test:local-cache": {
-      "command": "node --test --test-reporter=dot lib/test/local-cache.test.js",
+      "command": "node --test --test-reporter=dot lib/test/local-cache.test.js lib/test/fingerprint.test.js lib/test/cache-root.test.js",
       "env": {
         "NODE_OPTIONS": "--enable-source-maps"
       },

src/caching/cache.ts

@@ -94,4 +94,7 @@ export interface CacheHit {
    * before this method is called.
    */
   apply(): Promise<void>;
+
+  /** Release resources held by this hit when it won't be applied. */
+  release(): Promise<void>;
 }

src/caching/github-actions-cache.ts

@@ -759,6 +759,10 @@ class GitHubActionsCacheHit implements CacheHit {
     await this.#extract(tarballPath);
   }
 
+  async release(): Promise<void> {
+    // This cache hit holds no resources before apply.
+  }
+
   async #download(tarballPath: string): Promise<void> {
     using requestResult = request(this.#url);
     const {req, resPromise} = requestResult;