From b8d242b4721293294acccb01f8cbd5dba39fe6f9 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jul 2020 15:35:47 -0700 Subject: [PATCH] Update FAQ as suggested in https://github.com/microsoft/rushstack/issues/2001#issuecomment-654568654 --- pages/advanced/api.md | 5 ++++- pages/help/faq.md | 9 +++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/pages/advanced/api.md b/pages/advanced/api.md index bcfd835f..07763cab 100644 --- a/pages/advanced/api.md +++ b/pages/advanced/api.md @@ -4,7 +4,7 @@ title: The "rush-lib" API navigation_source: docs_nav --- -Rush provides an API for use by automation scripts. It is documented in integrated API reference for all Rush Stack projects: +Rush provides an API for use by automation scripts. It is documented in the integrated API reference for all Rush Stack projects:      [API Reference: @microsoft/rush-lib package](https://rushstack.io/pages/api/rush-lib/) @@ -54,3 +54,6 @@ project.packageJsonEditor.addOrUpdateDependency('lodash', '4.17.15', "optionalDe project.packageJsonEditor.saveIfModified(); ``` +## Generating a README.md summary + +For a more realistic example, the [repo-toolbox/src/ReadmeAction.ts](https://github.com/microsoft/rushstack/blob/master/repo-scripts/repo-toolbox/src/ReadmeAction.ts) tool uses these APIs to generate the [README.md](https://github.com/microsoft/rushstack/blob/master/README.md#published-packages) inventory for the Rush Stack monorepo. diff --git a/pages/help/faq.md b/pages/help/faq.md index 894e6612..8ed0673a 100644 --- a/pages/help/faq.md +++ b/pages/help/faq.md @@ -100,3 +100,12 @@ caching issue): *For a discussion of some other possibilities, see [issue #1088](https://github.com/microsoft/rushstack/issues/1088).* + + +### How to clean up Rush's installation to avoid interfering with other tools? + +Generally it's recommended to perform all monorepo management using Rush. The symlinks that Rush creates under the project `node_modules` folders may confuse other tools such as NPM or Yarn, causing them to malfunction because they expect a different installation model. Sometimes this is unavoidable, however. For example, when migrating an existing repo to use Rush however, the CI system may need to reuse an existing working folder to build different branches that use different installation models. To prevent interference, your CI job will first need to invoke a command that deletes the old files from the previous installation model. + +For Yarn or NPM, a command like `git clean -dfx` is generally sufficient. (THIS DELETES FILES -- [read the manual](https://git-scm.com/docs/git-clean) before invoking!) + +For cleaning up a Rush installation, `git clean` is NOT recommended because it does not handle symlinks reliably. Instead, use the [rush purge]({% link pages/commands/rush_purge.md %}) command to delete the `node_modules` folders created by Rush.