Explain when to use dart pub get --enforce-lockfile (#6108)

Contributes dart-lang/pub#4093 --------- Co-authored-by: Jonas Finnemann Jensen <[email protected]> Co-authored-by: Parker Lougheed <[email protected]>
dart-lang · Oct 3, 2024 · 6f11311 · 6f11311
1 parent 35c7a25
commit 6f11311
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 1 deletion.
diff --git a/firebase.json b/firebase.json
@@ -182,7 +182,6 @@
       { "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": "https://flutter.dev/go/pub-workspace", "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 },
@@ -284,6 +283,7 @@
       { "source": "/support/faq", "destination": "/resources/faq", "type": 301 },
       { "source": "/support{,/**}", "destination": "/community", "type": 301 },
 
+      { "source": "/to/enforce-lockfile", "destination": "/guides/packages#get-dependencies-for-production", "type": 301 },
       { "source": "/to/main-function", "destination": "/language/functions#main", "type": 301 },
       { "source": "/to/web-debug-extension", "destination": "https://chromewebstore.google.com/detail/dart-debug-extension/eljbmlghnomdjgdjmbdekegdkbabckhm", "type": 301 },
 

diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md
@@ -178,6 +178,89 @@ due to conflicting version constraints in the pubspec.
 To identify out-of-date packages that require editing the pubspec,
 use [`dart pub outdated`][outdated].
 
+## Get dependencies for production
+
+In some situations, `dart pub get` does not retrieve
+the exact package versions locked in the `pubspec.lock` file:
+
+* If new dependencies are added to or removed from `pubspec.yaml` after
+  the `pubspec.lock` file was last updated.
+* If the locked version no longer exists in the package repository.
+* If you changed to a different version of the Dart SDK,
+  and some packages are no longer compatible with that new version.
+
+In these cases `dart pub get` will:
+
+* Unlock enough of the locked dependency versions that
+  a resolution becomes possible.
+* Notify you about any dependency changes relative to
+  the existing `pubspec.lock`.
+
+For example, after adding `retry: ^3.0.0` to your dependencies:
+
+```console
+$ dart pub get
+Resolving dependencies... (1.0s)
+Downloading packages... 
++ retry 3.1.2
+```
+
+Also, if the [content hash][] of a published package version
+differs from the hash in the `pubspec.lock` file, pub will
+warn you and update the lockfile to reflect the published version.
+
+For example, if you manually change the hash of `retry` in `pubspec.lock`:
+
+```console
+$ dart pub get
+Resolving dependencies... 
+Downloading packages... 
+~ retry 3.1.2 (was 3.1.2)
+The existing content-hash from pubspec.lock doesn't match contents for:
+ * retry-3.1.2 from "https://pub.dev"
+
+This indicates one of:
+ * The content has changed on the server since you created the pubspec.lock.
+ * The pubspec.lock has been corrupted.
+
+The content-hashes in pubspec.lock has been updated.
+
+For more information see:
+https://dart.dev/go/content-hashes
+Changed 1 dependency!
+```
+
+When deploying your project to production,
+use `dart pub get --enforce-lockfile` to retrieve dependencies.
+
+If your project's dependency constraints can't be
+satisfied with the exact versions and content hashes in `pubspec.lock`,
+package retrieval and the command will fail.
+This helps avoid deploying untested
+dependencies and dependency versions to production.
+
+```console
+$ dart pub get --enforce-lockfile
+Resolving dependencies... 
+Downloading packages... 
+~ retry 3.1.2 (was 3.1.2)
+The existing content-hash from pubspec.lock doesn't match contents for:
+ * retry-3.1.2 from "https://pub.dev"
+
+This indicates one of:
+ * The content has changed on the server since you created the pubspec.lock.
+ * The pubspec.lock has been corrupted.
+
+For more information see:
+https://dart.dev/go/content-hashes
+Would change 1 dependency.
+Unable to satisfy `pubspec.yaml` using `pubspec.lock`.
+
+To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`.
+```
+
+[content hash]: /tools/pub/glossary#content-hashes
+
 ## More information
 
 The following pages have more information about packages and