Document the pubspec_overrides.yaml file

firebase.json

@@ -387,6 +387,7 @@
       { "source": "/to/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 },
       { "source": "/to/publish-from-github", "destination": "/tools/pub/automated-publishing#publishing-packages-using-github-actions", "type": 301 },
       { "source": "/to/publish-with-service-account", "destination": "/tools/pub/automated-publishing#publishing-from-google-cloud-build", "type": 301 },
+      { "source": "/to/pubspec-overrides", "destination": "/tools/pub/dependencies#pubspec-overrides", "type": 301 },
       { "source": "/to/sdk-constraint", "destination": "/tools/pub/pubspec#sdk-constraints", "type": 301 },
       { "source": "/to/sdk-version-pinning", "destination": "https://github.com/dart-lang/sdk/blob/main/docs/Flutter-Pinned-Packages.md", "type": 301 },
       { "source": "/to/web-debug-extension", "destination": "https://chromewebstore.google.com/detail/dart-debug-extension/eljbmlghnomdjgdjmbdekegdkbabckhm", "type": 301 },

src/content/tools/pub/dependencies.md

@@ -432,6 +432,32 @@ As a result, if you publish a package to pub.dev,
 keep in mind that your package's dependency overrides
 are ignored by all users of your package.
 
+If you are using a [pub workspace][workspaces],
+you can have `dependency_overrides` in each workspace package, but
+a single package can only be overridden once in the workspace.
+
+## `pubspec_overrides.yaml` {:#pubspec-overrides}
+
+If you want to change certain aspects of
+the resolution of your `pubspec.yaml` file, but
+do not want to change the actual file, you can
+place a file named `pubspec_overrides.yaml` next to the `pubspec.yaml`.
+
+Attributes from that file will override those from `pubspec.yaml`.
+
+The properties that can be overridden are:
+
+* `dependency_overrides`
+* `workspace`
+* `resolution`
+
+This can be useful to avoid accidentally
+checking temporary overrides in to version control.
+It can also make it easier to generate overrides from a script.
+
+In a [pub workspace][workspaces], each workspace package
+can have a `pubspec_overrides.yaml` file.
+
 ## Best practices
 
 Be proactive in managing your dependencies.
@@ -570,3 +596,4 @@ to differentiate versions. <a href="#fnref:semver">↩</a>
 [`dart pub upgrade`]: /tools/pub/cmd/pub-upgrade
 [pubsite]: {{site.pub}}
 [semantic versioning specification]: https://semver.org/spec/v2.0.0-rc.1.html
+[workspaces]: /tools/pub/workspaces

src/content/tools/pub/package-layout.md

@@ -25,7 +25,8 @@ might look like:
 enchilada/
   .dart_tool/ *
   pubspec.yaml
-  pubspec.lock **
+  pubspec_overrides.yaml **
+  pubspec.lock ***
   LICENSE
   README.md
   CHANGELOG.md
@@ -34,7 +35,7 @@ enchilada/
   bin/
     enchilada
   doc/
-    api/ ***
+    api/ ****
     getting_started.md
   example/
     main.dart
@@ -58,22 +59,28 @@ enchilada/
     index.html
     main.dart
     style.css
-```    
+```
 
 \* The `.dart_tool/` directory exists after you've run `dart pub get`.
    Don't check it into source control.
    To learn more, see 
    [Project specific caching for tools](#project-specific-caching-for-tools).
 
-\** The `pubspec.lock` file exists after you've run `dart pub get`.
+\** The [`pubspec_overrides.yaml`][] file,
+    if present, overrides certain aspects of `pubspec.yaml`.
+    Usually you don't want to check it into source control.
+
+\*** The `pubspec.lock` file exists after you've run `dart pub get`.
     Leave it out of source control unless your package is an
     [application package](/tools/pub/glossary#application-package).
 
-\*** The `doc/api` directory exists locally after you've run
+\**** The `doc/api` directory exists locally after you've run
      [`dart doc`](/tools/dart-doc).
      Don't check the `api` directory into source control.
 
 
+[`pubspec_overrides.yaml`]: /tools/pub/dependencies#pubspec-overrides
+
 ## The pubspec
 
 ```plaintext