[rush] Reuse the existing installation when a repo is moved, renamed, or cloned

[kevin-y-ang]

Summary

I keep a second copy of my Rush monorepo, made with a copy-on-write clone (cp -c on APFS, btrfs snapshot on Linux), so I can work on two branches with dependencies already installed. Rush refuses to reuse the install in the copy: rush install fails with "Current PNPM store path does not match the last one used" and demands --purge, which deletes and re-downloads everything even though every file is already present and correct at the new path. Plain renaming of the repo folder triggers the same thing.

The cause is that Rush records the repository's absolute path in last-install.flag (rushJsonFolder, storePath) and pnpm records the absolute storeDir in .modules.yaml, and Rush compares them as exact strings. This issue proposes making that install state relocatable.

Related: #5633 (git worktree support) shares the root cause. This proposal is narrower: it does not change where the store lives, only whether a moved store is accepted.

Repro steps

1. Create a minimal Rush repo with one project that has one dependency, and install it:

   mkdir repo-a && cd repo-a && rush init
   # rush.json: pnpmVersion 9.15.9, one project at packages/app depending on semver
   rush update

2. Clone the installed repo to a new path. cp -R works too; the copy-on-write flag only makes it fast:

   cd .. && cp -c -R -p repo-a repo-b

3. Run Rush in the copy:

   cd repo-b && rush install

Expected result: Rush notices nothing changed except the folder location and reports "Installation is already up-to-date." The store, node_modules, and lockfile in repo-b are byte-for-byte the ones from repo-a.

Actual result:

Checking installation in ".../repo-b/common/temp"
ERROR: Current PNPM store path does not match the last one used. This may cause inconsistency in your builds.

If you wish to install with the new store path, please run "rush install --purge"

Old Path: .../repo-a/common/temp/pnpm-store
New Path: .../repo-b/common/temp/pnpm-store

Running rush install --purge then deletes common/temp and reinstalls from the registry. For a real monorepo that is minutes and gigabytes.

Details

Why Rush behaves differently from plain pnpm

pnpm on its own	Rush
One content-addressable store per machine, in the user's home folder	One store per repository, inside it at common/temp/pnpm-store (pnpmStore: "local", the default)
Projects hard-link into that store	The repo's node_modules hard-links into the in-repo store
Nothing in the project records where the project folder is	last-install.flag records the absolute repo root and store path; pnpm's .modules.yaml records the absolute storeDir
Rename or copy the project folder and it keeps working	Rename or copy the repo and Rush refuses to reuse the install

Where this bites

In each diagram, the flow forks at the yellow node where Rush checks last-install.flag. Green is what the user expects; red is what Rush does today.

Cloning an installed repo to work on two branches at once

flowchart TD
    A["Copy repo A to B with cp -c (seconds)"] --> B["cd into B"]
    B --> C{"rush build: Rush checks last-install.flag"}
    C -->|What the user expects| G1["Paths match, install reused"]
    G1 --> G2["Build starts immediately"]
    C -->|What Rush does today| R1["ERROR: store path does not match"]
    R1 --> R2["rush install --purge"]
    R2 --> R3["Copied store and node_modules deleted"]
    R3 --> R4["Full reinstall: minutes, gigabytes"]
    R4 --> R5["Build finally starts"]

    classDef step fill:#F1F3F4,stroke:#5F6368,color:#202124
    classDef fork fill:#FFF4C2,stroke:#E37400,color:#202124
    classDef good fill:#E6F4EA,stroke:#1E8E3E,color:#202124
    classDef bad fill:#FCE8E6,stroke:#C5221F,color:#202124
    classDef err fill:#F5B5B1,stroke:#C5221F,color:#202124
    class A,B step
    class C fork
    class G1,G2 good
    class R1 err
    class R2,R3,R4,R5 bad
    linkStyle 2,3 stroke:#1E8E3E,stroke-width:2px
    linkStyle 4,5,6,7,8 stroke:#C5221F,stroke-width:2px

Loading

A team at ByteDance ended up writing an internal CLI whose only job is to rewrite the two recorded paths so the clone is accepted.

Renaming or moving the repo folder

flowchart TD
    A["Rename ~/code/repo to ~/code/repo-main"] --> C{"rush build: Rush checks last-install.flag"}
    C -->|What the user expects| G1["Paths match, install reused"]
    G1 --> G2["Keep working"]
    C -->|What Rush does today| R1["ERROR: store path does not match"]
    R1 --> R2["rush install --purge"]
    R2 --> R3["Full reinstall: minutes, gigabytes"]
    R3 --> R4["Back to work"]

    classDef step fill:#F1F3F4,stroke:#5F6368,color:#202124
    classDef fork fill:#FFF4C2,stroke:#E37400,color:#202124
    classDef good fill:#E6F4EA,stroke:#1E8E3E,color:#202124
    classDef bad fill:#FCE8E6,stroke:#C5221F,color:#202124
    classDef err fill:#F5B5B1,stroke:#C5221F,color:#202124
    class A step
    class C fork
    class G1,G2 good
    class R1 err
    class R2,R3,R4 bad
    linkStyle 1,2 stroke:#1E8E3E,stroke-width:2px
    linkStyle 3,4,5,6 stroke:#C5221F,stroke-width:2px

Loading

Restoring a pre-installed workspace on a build machine

A CI image or cache is prepared with the repo installed at one path, and a job restores it to a different path.

flowchart TD
    A["Restore workspace to the job folder"] --> C{"rush install: Rush checks last-install.flag"}
    C -->|What the user expects| G1["Nothing changed, install reused"]
    G1 --> G2["rush build within seconds"]
    C -->|What Rush does today| R1["ERROR: store path does not match"]
    R1 --> R2["Pipeline adds --purge to every job"]
    R2 --> R3["Full install on every job"]
    R3 --> R4["Pre-installed image gains nothing"]

    classDef step fill:#F1F3F4,stroke:#5F6368,color:#202124
    classDef fork fill:#FFF4C2,stroke:#E37400,color:#202124
    classDef good fill:#E6F4EA,stroke:#1E8E3E,color:#202124
    classDef bad fill:#FCE8E6,stroke:#C5221F,color:#202124
    classDef err fill:#F5B5B1,stroke:#C5221F,color:#202124
    class A step
    class C fork
    class G1,G2 good
    class R1 err
    class R2,R3,R4 bad
    linkStyle 1,2 stroke:#1E8E3E,stroke-width:2px
    linkStyle 3,4,5,6 stroke:#C5221F,stroke-width:2px

Loading

Proposed fix

Make the install state relocatable, in the code that decides whether the last install is still valid (LastInstallFlag and BaseInstallManager in @microsoft/rush-lib).

1. Compare recorded paths relative to the repo root. When Rush reads last-install.flag, it would first check whether the recorded rushJsonFolder matches the current repo root. If not, the repo has moved. Rush would then re-root every recorded path that was inside the old root onto the new root before comparing. Example: the store was recorded as /Users/me/code/repo-a/common/temp/pnpm-store and the repo now lives at /Users/me/code/repo-b; Rush rewrites the recorded value to /Users/me/code/repo-b/common/temp/pnpm-store, which matches the actual store, so the install counts as unchanged.

Two constraints keep this safe:

• Paths outside the repo are never adjusted. A store configured via RUSH_PNPM_STORE_PATH or pnpmStore: "global" is still compared as an exact string.
• Every other recorded value must still match exactly: Node.js version, pnpm version, selected projects, and so on. Anything else changing still triggers a clean install.

2. Patch pnpm's own record of the store. Rush accepting the move is not enough. pnpm records storeDir in node_modules/.modules.yaml and throws ERR_PNPM_UNEXPECTED_STORE if it does not match the --store argument. When Rush detects a move and everything else is valid, it would rewrite storeDir (and on Windows virtualStoreDir, which pnpm writes as an absolute path there) to point under the new root, and say so:

The repository was moved from "/Users/me/code/repo-a" to "/Users/me/code/repo-b" since the last install. Reusing the existing installation.
  Updated "storeDir" in .modules.yaml: /Users/me/code/repo-b/common/temp/pnpm-store/v3
Installation is already up-to-date.

At the end of the command Rush writes a fresh last-install.flag with the new paths, so this happens once per move.

Effect on the three cases. The clone builds immediately after cp -c. A renamed or moved repo keeps working with no extra command. A restored CI workspace passes rush install in seconds and the pre-installed image is actually reused.

Known limits. rush-pnpm run directly in a moved repo before the first rush install would still hit pnpm's store error, since only the install path patches .modules.yaml. Injected dependencies write .pnpm-sync.json files with absolute paths; those are out of scope here.

Alternatives considered

• Store repo-relative paths in last-install.flag. Cleaner data, but a format change: every existing checkout reinstalls once, and pnpm's file still needs the patch above.
• An explicit rush relocate command. Works, but users still hit the error first and have to know the command exists.
• Default pnpmStore to global. Sidesteps the problem by not having repo-local absolute state, but changes the default for everyone and breaks store sharing across copy-on-write clones.

I have a working implementation of the proposal, with unit tests and an end-to-end check against the repro above, and can open a PR if maintainers are open to the approach.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/rush globally installed version?	5.178.1
rushVersion from rush.json?	5.178.1
pnpmVersion, npmVersion, or yarnVersion from rush.json?	pnpm@9.15.9 (also reproduced with pnpm@10.27.0)
(if pnpm) useWorkspaces from pnpm-config.json?	true
Operating system?	Mac (also affects Linux with btrfs snapshots)
Would you consider contributing a PR?	Yes
Node.js version (node -v)?	v22.22.3

[octogonz]

I agree the --purge experience should be improved, but the proposed fix needs some iteration.

The original design goal of last-install.flag is that if files get moved around, rush install detects that and guarantees a correct installation. That means the acceptance criteria isn't +"renaming/copying is now fast."_ It's "there is no everyday scenario where rush install finishes fast and the build is wrong or nondeterministic (because some state is no longer tracked accurately)." Copies are the riskiest case, because stale absolute paths might not be broken, but rather point into the original tree which can get disturbed unexpectedly.

The table leaves out pnpmStore: "global" and RUSH_PNPM_STORE_PATH

Rush already supports a shared store outside the repo. With it, a copied or renamed repo never hits the "store path does not match" error. Only rushJsonFolder differs, so Rush does a clean install of common/temp/node_modules and relinks from the existing store. In my repro that took about 0.5 seconds with 0 downloads. The "minutes and gigabytes" cost is specific to the default in-repo store.

Also, plain pnpm's default store is per-filesystem rather than per-machine: it goes in the home folder only if hard links from the project to the home folder work, otherwise <mount point>/.pnpm-store (see store/store-path).

Problem 1: hotlink state deletes files in the other repo

common/temp/rush-hotlink-state.json records affectedPnpmVirtualStoreFolderPaths as absolute paths, and HotlinkManager.purgeLinksAsync() deletes those folders before installing.

Repro:

1. In repo-a, run rush bridge-package --path <external semver folder> from a project folder.
2. cp -R -p repo-a repo-b
3. In repo-b, apply the proposed fix by hand: rewrite rushJsonFolder/storePath in last-install.flag and storeDir in node_modules/.modules.yaml (this is what the ByteDance CLI does).
4. Run rush install in repo-b.

Result: "Rush install finished successfully", but:

• semver was deleted from repo-a's common/temp/node_modules/.pnpm, so repo-a is broken until its next install.
• repo-b still loads the external bridged code, although Rush now believes there are no hotlinks.
• The external package's node_modules/.pnpm-sync.json lost its targets, which belonged to repo-a. pnpmSyncUpdateFileAsync() removes every target with a matching lockfile ID ("default"), regardless of which repo it points to.

This is already reachable today: with RUSH_PNPM_STORE_PATH set, the same copy skips the store error and goes straight to purgeLinksAsync(), and I reproduced the deletion in repo-a that way. The proposal would extend it to the default configuration.

Problem 2: keeping node_modules leaves stale absolute paths

After copying, these files still reference repo-a:

• bin shims, which set NODE_PATH to absolute paths
• node_modules/.pnpm-workspace-state-v1.json (pnpm 10), keyed by absolute project paths
• node_modules/.modules.yaml (storeDir)

With only storeDir patched, pnpm 9 and 10 both report "Already up to date" and rewrite the project-level shims. However, the shims inside the virtual store (.pnpm/<pkg>/node_modules/<pkg>/node_modules/.bin/*, and in pnpm 10 also .pnpm/node_modules/.bin/*) keep NODE_PATH pointing at repo-a. If Rush skips pnpm entirely ("Installation is already up-to-date"), the project shims and the workspace state stay stale too. Also note that cp -p preserves mtimes, so canSkipInstallAsync() would allow that skip.

On Windows things can be more complicated: pnpm deliberately keeps virtualStoreDir absolute on Windows because junctions store absolute targets; see the comment in writeModulesManifest(). The absolute value exists so that a moved project fails the check and gets its node_modules rebuilt. Patching virtualStoreDir defeats that, and a copied repo's junctions would keep pointing into the original repo. pnpm doesn't verify existing links on an up-to-date install.

Smaller corrections

• pnpm install doesn't report ERR_PNPM_UNEXPECTED_STORE. validateModules() catches it and offers to delete node_modules: without a TTY it fails with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY, and with CI=true it silently deletes and relinks.
• .pnpm-sync.json stores relative paths (path.relative in pnpm-sync-lib 0.3.4), so the "injected dependencies" known limit doesn't apply.
• pnpm 10.27.0 added <store>/v10/projects/<hash of absolute lockfile dir> symlinks. They're relative on POSIX, so a copy just gets a duplicate entry, but it's another piece of path-keyed state.

Suggested direction

Treat a move the same way Rush already treats a rushJsonFolder mismatch: delete common/temp/node_modules and keep the store. I tested this by making only the store path match. The install downloaded nothing, pnpm replaced a planted stale absolute symlink in a project node_modules, and afterward grep and find found no file or symlink in repo-b referencing repo-a. The cost is relinking packages and rerunning build scripts that aren't in pnpm's side-effects cache, which is what RUSH_PNPM_STORE_PATH users already get today.

Something like:

1. LastInstallFlag: when rushJsonFolder differs, re-root the old storePath onto the new root (only if it was under the old root) before the store-path check, so it doesn't throw. Keep rushJsonFolder in the deep-equal comparison so the result is still "invalid, do a clean install." No .modules.yaml patching and no Windows-specific branch.
2. BaseInstallManager.doInstallAsync(): when a move is detected, discard rush-hotlink-state.json instead of running purgeLinksAsync(), and print a warning that hotlinks were dropped. The clean install removes the bridged content anyway.
3. HotlinkManager.purgeLinksAsync(), which also fixes the existing RUSH_PNPM_STORE_PATH bug:
   • Ignore any affectedPnpmVirtualStoreFolderPaths entry that isn't under the current subspace temp folder.
   • Remove only this repo's targets from the external .pnpm-sync.json, rather than every target with the lockfile ID. This probably needs a pnpm-sync-lib change.
4. Things we could test: store inside the repo, store outside the repo, and a move combined with another changed field (for example the Node.js version).