From 832f5a7d16a80293274789928dc0061bcc83314d Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Wed, 8 Jan 2025 18:28:37 +0100 Subject: [PATCH] Add section about stray files (#6274) In support of https://github.com/dart-lang/pub/pull/4446 --------- Co-authored-by: Eric Windmill Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- firebase.json | 1 + src/content/tools/pub/workspaces.md | 41 +++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/firebase.json b/firebase.json index 1acac338fa..941492351d 100644 --- a/firebase.json +++ b/firebase.json @@ -179,6 +179,7 @@ { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, { "source": "/go/macros", "destination": "/language/macros", "type": 301 }, { "source": "/go/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 }, + { "source": "/go/workspaces-stray-files", "destination": "/guides/workspaces#stray-files", "type": 301 }, { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 }, { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 }, { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 }, diff --git a/src/content/tools/pub/workspaces.md b/src/content/tools/pub/workspaces.md index feb5251de5..26735a5df4 100644 --- a/src/content/tools/pub/workspaces.md +++ b/src/content/tools/pub/workspaces.md @@ -107,6 +107,47 @@ To use pub workspaces, all your workspace packages (but not your dependencies) must have an SDK version constraint of `^3.6.0` or higher. ::: + +## Stray files + +When you migrate an existing monorepo to use Pub workspaces, there will +be existing "stray" `pubspec.lock` and `.dart_tool/package_config.json` files +adjacent to each pubspec. These shadow the `pubspec.lock` and +`.dart_tool/package_config.json` files placed next to the root. + +Therefore, `pub get` will delete any `pubspec.lock` and +`.dart_tool/package_config.json` located in directories between the root and +(including) any workspace package. + +```plaintext +/ + pubspec.yaml # Root + packages/ + pubspec.lock # Deleted by `pub get` + .dart_tool/package_config.json # Deleted by `pub get` + foo/ + pubspec.yaml # Workspace member + pubspec.lock # Deleted by `pub get` + .dart_tool/package_config.json # Deleted by `pub get` +``` + +If any directory between the workspace root and a workspace package contains a +"stray" `pubspec.yaml` file that is not member of the workspace, `pub get` will +report an error and fail to resolve. This is because resolving such a `pubspec.yaml` would +create a `.dart_tool/package_config.json` file that shadows the one at the root. + +For example: + +```plaintext +/ + pubspec.yaml # Root `workspace: ['foo/']` + packages/ + pubspec.yaml # Not workspace member => error + foo/ + pubspec.yaml # Workspace member +``` + + ## Interdependencies between workspace packages If any of the workspace packages depend on each other, they will automatically