diff options
Diffstat (limited to 'deps/node/deps/npm/man/man5/npm-package-locks.5')
| -rw-r--r-- | deps/node/deps/npm/man/man5/npm-package-locks.5 | 198 |
1 files changed, 0 insertions, 198 deletions
diff --git a/deps/node/deps/npm/man/man5/npm-package-locks.5 b/deps/node/deps/npm/man/man5/npm-package-locks.5 deleted file mode 100644 index b3692ceb..00000000 --- a/deps/node/deps/npm/man/man5/npm-package-locks.5 +++ /dev/null @@ -1,198 +0,0 @@ -.TH "NPM\-PACKAGE\-LOCKS" "5" "January 2019" "" "" -.SH "NAME" -\fBnpm-package-locks\fR \- An explanation of npm lockfiles -.SH DESCRIPTION -.P -Conceptually, the "input" to npm help install is a npm help 5 package\.json, while its -"output" is a fully\-formed \fBnode_modules\fP tree: a representation of the -dependencies you declared\. In an ideal world, npm would work like a pure -function: the same \fBpackage\.json\fP should produce the exact same \fBnode_modules\fP -tree, any time\. In some cases, this is indeed true\. But in many others, npm is -unable to do this\. There are multiple reasons for this: -.RS 0 -.IP \(bu 2 -different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms\. -.IP \(bu 2 -a new version of a direct semver\-range package may have been published since the last time your packages were installed, and thus a newer version will be used\. -.IP \(bu 2 -A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (\fB1\.2\.3\fP instead of \fB^1\.2\.3\fP) -.IP \(bu 2 -The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now\. - -.RE -.P -As an example, consider package A: -.P -.RS 2 -.nf -{ - "name": "A", - "version": "0\.1\.0", - "dependencies": { - "B": "<0\.1\.0" - } -} -.fi -.RE -.P -package B: -.P -.RS 2 -.nf -{ - "name": "B", - "version": "0\.0\.1", - "dependencies": { - "C": "<0\.1\.0" - } -} -.fi -.RE -.P -and package C: -.P -.RS 2 -.nf -{ - "name": "C", - "version": "0\.0\.1" -} -.fi -.RE -.P -If these are the only versions of A, B, and C available in the -registry, then a normal \fBnpm install A\fP will install: -.P -.RS 2 -.nf -A@0\.1\.0 -`\-\- B@0\.0\.1 - `\-\- C@0\.0\.1 -.fi -.RE -.P -However, if is published, then a fresh \fBnpm install A\fP will -install: -.P -.RS 2 -.nf -A@0\.1\.0 -`\-\- B@0\.0\.2 - `\-\- C@0\.0\.1 -.fi -.RE -.P -assuming the new version did not modify B's dependencies\. Of course, -the new version of B could include a new version of C and any number -of new dependencies\. If such changes are undesirable, the author of A -could specify a dependency on \|\. However, if A's author and B's -author are not the same person, there's no way for A's author to say -that he or she does not want to pull in newly published versions of C -when B hasn't changed at all\. -.P -To prevent this potential issue, npm uses npm help 5 package\-lock\.json or, if present, -npm help 5 shrinkwrap\.json\. These files are called package locks, or lockfiles\. -.P -Whenever you run \fBnpm install\fP, npm generates or updates your package lock, -which will look something like this: -.P -.RS 2 -.nf -{ - "name": "A", - "version": "0\.1\.0", - \.\.\.metadata fields\.\.\. - "dependencies": { - "B": { - "version": "0\.0\.1", - "resolved": "https://registry\.npmjs\.org/B/\-/B\-0\.0\.1\.tgz", - "integrity": "sha512\-DeAdb33F+" - "dependencies": { - "C": { - "version": "git://github\.com/org/C\.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4" - } - } - } - } -} -.fi -.RE -.P -This file describes an \fIexact\fR, and more importantly \fIreproducible\fR -\fBnode_modules\fP tree\. Once it's present, any future installation will base its -work off this file, instead of recalculating dependency versions off -npm help 5 package\.json\. -.P -The presence of a package lock changes the installation behavior such that: -.RS 0 -.IP 1. 3 -The module tree described by the package lock is reproduced\. This means -reproducing the structure described in the file, using the specific files -referenced in "resolved" if available, falling back to normal package resolution -using "version" if one isn't\. -.IP 2. 3 -The tree is walked and any missing dependencies are installed in the usual -fashion\. - -.RE -.P -If \fBpreshrinkwrap\fP, \fBshrinkwrap\fP or \fBpostshrinkwrap\fP are in the \fBscripts\fP -property of the \fBpackage\.json\fP, they will be executed in order\. \fBpreshrinkwrap\fP -and \fBshrinkwrap\fP are executed before the shrinkwrap, \fBpostshrinkwrap\fP is -executed afterwards\. These scripts run for both \fBpackage\-lock\.json\fP and -\fBnpm\-shrinkwrap\.json\fP\|\. For example to run some postprocessing on the generated -file: -.P -.RS 2 -.nf -"scripts": { - "postshrinkwrap": "json \-I \-e \\"this\.myMetadata = $MY_APP_METADATA\\"" -} -.fi -.RE -.SS Using locked packages -.P -Using a locked package is no different than using any package without a package -lock: any commands that update \fBnode_modules\fP and/or \fBpackage\.json\fP\|'s -dependencies will automatically sync the existing lockfile\. This includes \fBnpm -install\fP, \fBnpm rm\fP, \fBnpm update\fP, etc\. To prevent this update from happening, -you can use the \fB\-\-no\-save\fP option to prevent saving altogether, or -\fB\-\-no\-shrinkwrap\fP to allow \fBpackage\.json\fP to be updated while leaving -\fBpackage\-lock\.json\fP or \fBnpm\-shrinkwrap\.json\fP intact\. -.P -It is highly recommended you commit the generated package lock to source -control: this will allow anyone else on your team, your deployments, your -CI/continuous integration, and anyone else who runs \fBnpm install\fP in your -package source to get the exact same dependency tree that you were developing -on\. Additionally, the diffs from these changes are human\-readable and will -inform you of any changes npm has made to your \fBnode_modules\fP, so you can notice -if any transitive dependencies were updated, hoisted, etc\. -.SS Resolving lockfile conflicts -.P -Occasionally, two separate npm install will create package locks that cause -merge conflicts in source control systems\. As of \fB, these conflicts -can be resolved by manually fixing any\fPpackage\.json\fBconflicts, and then -running\fPnpm install [\-\-package\-lock\-only]\fBagain\. npm will automatically -resolve any conflicts for you and write a merged package lock that includes all -the dependencies from both branches in a reasonable tree\. If\fP\-\-package\-lock\-only\fBis provided, it will do this without also modifying your -local\fPnode_modules/`\. -.P -To make this process seamless on git, consider installing -\fBnpm\-merge\-driver\fP \fIhttps://npm\.im/npm\-merge\-driver\fR, which will teach git how -to do this itself without any user interaction\. In short: \fB$ npx -npm\-merge\-driver install \-g\fP will let you do this, and even works with -\fBversions of npm 5, albeit a bit more noisily\. Note that if\fPpackage\.json\fBitself conflicts, you will have to resolve that by hand and run\fPnpm install` manually, even with the merge driver\. -.SH SEE ALSO -.RS 0 -.IP \(bu 2 -https:// -.IP \(bu 2 -npm help 5 package\.json -.IP \(bu 2 -npm help 5 package\-lock\.json -.IP \(bu 2 -npm help 5 shrinkwrap\.json -.IP \(bu 2 -npm help shrinkwrap - -.RE |