Simple email application for Android. Original source code: https://framagit.org/dystopia-project/simple-email
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

199 lines
6.7 KiB

  1. .TH "NPM\-PACKAGE\-LOCKS" "5" "August 2018" "" ""
  2. .SH "NAME"
  3. \fBnpm-package-locks\fR \- An explanation of npm lockfiles
  4. .SH DESCRIPTION
  5. .P
  6. Conceptually, the "input" to npm help install is a npm help 5 package\.json, while its
  7. "output" is a fully\-formed \fBnode_modules\fP tree: a representation of the
  8. dependencies you declared\. In an ideal world, npm would work like a pure
  9. function: the same \fBpackage\.json\fP should produce the exact same \fBnode_modules\fP
  10. tree, any time\. In some cases, this is indeed true\. But in many others, npm is
  11. unable to do this\. There are multiple reasons for this:
  12. .RS 0
  13. .IP \(bu 2
  14. different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms\.
  15. .IP \(bu 2
  16. 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\.
  17. .IP \(bu 2
  18. 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)
  19. .IP \(bu 2
  20. 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\.
  21. .RE
  22. .P
  23. As an example, consider package A:
  24. .P
  25. .RS 2
  26. .nf
  27. {
  28. "name": "A",
  29. "version": "0\.1\.0",
  30. "dependencies": {
  31. "B": "<0\.1\.0"
  32. }
  33. }
  34. .fi
  35. .RE
  36. .P
  37. package B:
  38. .P
  39. .RS 2
  40. .nf
  41. {
  42. "name": "B",
  43. "version": "0\.0\.1",
  44. "dependencies": {
  45. "C": "<0\.1\.0"
  46. }
  47. }
  48. .fi
  49. .RE
  50. .P
  51. and package C:
  52. .P
  53. .RS 2
  54. .nf
  55. {
  56. "name": "C",
  57. "version": "0\.0\.1"
  58. }
  59. .fi
  60. .RE
  61. .P
  62. If these are the only versions of A, B, and C available in the
  63. registry, then a normal \fBnpm install A\fP will install:
  64. .P
  65. .RS 2
  66. .nf
  67. A@0\.1\.0
  68. `\-\- B@0\.0\.1
  69. `\-\- C@0\.0\.1
  70. .fi
  71. .RE
  72. .P
  73. However, if is published, then a fresh \fBnpm install A\fP will
  74. install:
  75. .P
  76. .RS 2
  77. .nf
  78. A@0\.1\.0
  79. `\-\- B@0\.0\.2
  80. `\-\- C@0\.0\.1
  81. .fi
  82. .RE
  83. .P
  84. assuming the new version did not modify B's dependencies\. Of course,
  85. the new version of B could include a new version of C and any number
  86. of new dependencies\. If such changes are undesirable, the author of A
  87. could specify a dependency on \|\. However, if A's author and B's
  88. author are not the same person, there's no way for A's author to say
  89. that he or she does not want to pull in newly published versions of C
  90. when B hasn't changed at all\.
  91. .P
  92. To prevent this potential issue, npm uses npm help 5 package\-lock\.json or, if present,
  93. npm help 5 shrinkwrap\.json\. These files are called package locks, or lockfiles\.
  94. .P
  95. Whenever you run \fBnpm install\fP, npm generates or updates your package lock,
  96. which will look something like this:
  97. .P
  98. .RS 2
  99. .nf
  100. {
  101. "name": "A",
  102. "version": "0\.1\.0",
  103. \.\.\.metadata fields\.\.\.
  104. "dependencies": {
  105. "B": {
  106. "version": "0\.0\.1",
  107. "resolved": "https://registry\.npmjs\.org/B/\-/B\-0\.0\.1\.tgz",
  108. "integrity": "sha512\-DeAdb33F+"
  109. "dependencies": {
  110. "C": {
  111. "version": "git://github\.com/org/C\.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
  112. }
  113. }
  114. }
  115. }
  116. }
  117. .fi
  118. .RE
  119. .P
  120. This file describes an \fIexact\fR, and more importantly \fIreproducible\fR
  121. \fBnode_modules\fP tree\. Once it's present, any future installation will base its
  122. work off this file, instead of recalculating dependency versions off
  123. npm help 5 package\.json\.
  124. .P
  125. The presence of a package lock changes the installation behavior such that:
  126. .RS 0
  127. .IP 1. 3
  128. The module tree described by the package lock is reproduced\. This means
  129. reproducing the structure described in the file, using the specific files
  130. referenced in "resolved" if available, falling back to normal package resolution
  131. using "version" if one isn't\.
  132. .IP 2. 3
  133. The tree is walked and any missing dependencies are installed in the usual
  134. fashion\.
  135. .RE
  136. .P
  137. If \fBpreshrinkwrap\fP, \fBshrinkwrap\fP or \fBpostshrinkwrap\fP are in the \fBscripts\fP
  138. property of the \fBpackage\.json\fP, they will be executed in order\. \fBpreshrinkwrap\fP
  139. and \fBshrinkwrap\fP are executed before the shrinkwrap, \fBpostshrinkwrap\fP is
  140. executed afterwards\. These scripts run for both \fBpackage\-lock\.json\fP and
  141. \fBnpm\-shrinkwrap\.json\fP\|\. For example to run some postprocessing on the generated
  142. file:
  143. .P
  144. .RS 2
  145. .nf
  146. "scripts": {
  147. "postshrinkwrap": "json \-I \-e \\"this\.myMetadata = $MY_APP_METADATA\\""
  148. }
  149. .fi
  150. .RE
  151. .SS Using locked packages
  152. .P
  153. Using a locked package is no different than using any package without a package
  154. lock: any commands that update \fBnode_modules\fP and/or \fBpackage\.json\fP\|'s
  155. dependencies will automatically sync the existing lockfile\. This includes \fBnpm
  156. install\fP, \fBnpm rm\fP, \fBnpm update\fP, etc\. To prevent this update from happening,
  157. you can use the \fB\-\-no\-save\fP option to prevent saving altogether, or
  158. \fB\-\-no\-shrinkwrap\fP to allow \fBpackage\.json\fP to be updated while leaving
  159. \fBpackage\-lock\.json\fP or \fBnpm\-shrinkwrap\.json\fP intact\.
  160. .P
  161. It is highly recommended you commit the generated package lock to source
  162. control: this will allow anyone else on your team, your deployments, your
  163. CI/continuous integration, and anyone else who runs \fBnpm install\fP in your
  164. package source to get the exact same dependency tree that you were developing
  165. on\. Additionally, the diffs from these changes are human\-readable and will
  166. inform you of any changes npm has made to your \fBnode_modules\fP, so you can notice
  167. if any transitive dependencies were updated, hoisted, etc\.
  168. .SS Resolving lockfile conflicts
  169. .P
  170. Occasionally, two separate npm install will create package locks that cause
  171. merge conflicts in source control systems\. As of \fB, these conflicts
  172. can be resolved by manually fixing any\fPpackage\.json\fBconflicts, and then
  173. running\fPnpm install [\-\-package\-lock\-only]\fBagain\. npm will automatically
  174. resolve any conflicts for you and write a merged package lock that includes all
  175. the dependencies from both branches in a reasonable tree\. If\fP\-\-package\-lock\-only\fBis provided, it will do this without also modifying your
  176. local\fPnode_modules/`\.
  177. .P
  178. To make this process seamless on git, consider installing
  179. \fBnpm\-merge\-driver\fP \fIhttps://npm\.im/npm\-merge\-driver\fR, which will teach git how
  180. to do this itself without any user interaction\. In short: \fB$ npx
  181. npm\-merge\-driver install \-g\fP will let you do this, and even works with
  182. \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\.
  183. .SH SEE ALSO
  184. .RS 0
  185. .IP \(bu 2
  186. https://
  187. .IP \(bu 2
  188. npm help 5 package\.json
  189. .IP \(bu 2
  190. npm help 5 package\-lock\.json
  191. .IP \(bu 2
  192. npm help 5 shrinkwrap\.json
  193. .IP \(bu 2
  194. npm help shrinkwrap
  195. .RE