X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=org.simantics.maps.server%2Fnode%2Fnode-v4.8.0-win-x64%2Fnode_modules%2Fnpm%2Fdoc%2Fcli%2Fnpm-shrinkwrap.md;fp=org.simantics.maps.server%2Fnode%2Fnode-v4.8.0-win-x64%2Fnode_modules%2Fnpm%2Fdoc%2Fcli%2Fnpm-shrinkwrap.md;h=ac6bdef776a97219adbc4ac3d0143cea4e48425e;hb=2529be6d456deeb07c128603ce4971f1dc29b695;hp=0000000000000000000000000000000000000000;hpb=2636fc31c16c23711cf2b06a4ae8537bba9c1d35;p=simantics%2Fdistrict.git diff --git a/org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/cli/npm-shrinkwrap.md b/org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/cli/npm-shrinkwrap.md new file mode 100644 index 00000000..ac6bdef7 --- /dev/null +++ b/org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/cli/npm-shrinkwrap.md @@ -0,0 +1,180 @@ +npm-shrinkwrap(1) -- Lock down dependency versions +===================================================== + +## SYNOPSIS + + npm shrinkwrap + +## DESCRIPTION + +This command locks down the versions of a package's dependencies so +that you can control exactly which versions of each dependency will be +used when your package is installed. The `package.json` file is still +required if you want to use `npm install`. + +By default, `npm install` recursively installs the target's +dependencies (as specified in `package.json`), choosing the latest +available version that satisfies the dependency's semver pattern. In +some situations, particularly when shipping software where each change +is tightly managed, it's desirable to fully specify each version of +each dependency recursively so that subsequent builds and deploys do +not inadvertently pick up newer versions of a dependency that satisfy +the semver pattern. Specifying specific semver patterns in each +dependency's `package.json` would facilitate this, but that's not always +possible or desirable, as when another author owns the npm package. +It's also possible to check dependencies directly into source control, +but that may be undesirable for other reasons. + +As an example, consider package A: + + { + "name": "A", + "version": "0.1.0", + "dependencies": { + "B": "<0.1.0" + } + } + +package B: + + { + "name": "B", + "version": "0.0.1", + "dependencies": { + "C": "<0.1.0" + } + } + +and package C: + + { + "name": "C", + "version": "0.0.1" + } + +If these are the only versions of A, B, and C available in the +registry, then a normal `npm install A` will install: + + A@0.1.0 + `-- B@0.0.1 + `-- C@0.0.1 + +However, if B@0.0.2 is published, then a fresh `npm install A` will +install: + + A@0.1.0 + `-- B@0.0.2 + `-- C@0.0.1 + +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 B@0.0.1. 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. + +In this case, A's author can run + + npm shrinkwrap + +This generates `npm-shrinkwrap.json`, which will look something like this: + + { + "name": "A", + "version": "0.1.0", + "dependencies": { + "B": { + "version": "0.0.1", + "from": "B@^0.0.1", + "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz", + "dependencies": { + "C": { + "version": "0.0.1", + "from": "org/C#v0.0.1", + "resolved": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4" + } + } + } + } + } + +The shrinkwrap command has locked down the dependencies based on +what's currently installed in node_modules. When `npm install` +installs a package with an `npm-shrinkwrap.json` in the package +root, the shrinkwrap file (rather than `package.json` files) completely +drives the installation of that package and all of its dependencies +(recursively). So now the author publishes A@0.1.0, and subsequent +installs of this package will use B@0.0.1 and C@0.0.1, regardless the +dependencies and versions listed in A's, B's, and C's `package.json` +files. + + +### Using shrinkwrapped packages + +Using a shrinkwrapped package is no different than using any other +package: you can `npm install` it by hand, or add a dependency to your +`package.json` file and `npm install` it. + +### Building shrinkwrapped packages + +To shrinkwrap an existing package: + +1. Run `npm install` in the package root to install the current + versions of all dependencies. +2. Validate that the package works as expected with these versions. +3. Run `npm shrinkwrap`, add `npm-shrinkwrap.json` to git, and publish + your package. + +To add or update a dependency in a shrinkwrapped package: + +1. Run `npm install` in the package root to install the current + versions of all dependencies. +2. Add or update dependencies. `npm install` each new or updated + package individually and then update `package.json`. Note that they + must be explicitly named in order to be installed: running `npm + install` with no arguments will merely reproduce the existing + shrinkwrap. +3. Validate that the package works as expected with the new + dependencies. +4. Run `npm shrinkwrap`, commit the new `npm-shrinkwrap.json`, and + publish your package. + +You can use npm-outdated(1) to view dependencies with newer versions +available. + +### Other Notes + +A shrinkwrap file must be consistent with the package's `package.json` +file. `npm shrinkwrap` will fail if required dependencies are not +already installed, since that would result in a shrinkwrap that +wouldn't actually work. Similarly, the command will fail if there are +extraneous packages (not referenced by `package.json`), since that would +indicate that `package.json` is not correct. + +Since `npm shrinkwrap` is intended to lock down your dependencies for +production use, `devDependencies` will not be included unless you +explicitly set the `--dev` flag when you run `npm shrinkwrap`. If +installed `devDependencies` are excluded, then npm will print a +warning. If you want them to be installed with your module by +default, please consider adding them to `dependencies` instead. + +If shrinkwrapped package A depends on shrinkwrapped package B, B's +shrinkwrap will not be used as part of the installation of A. However, +because A's shrinkwrap is constructed from a valid installation of B +and recursively specifies all dependencies, the contents of B's +shrinkwrap will implicitly be included in A's shrinkwrap. + +### Caveats + +If you wish to lock down the specific bytes included in a package, for +example to have 100% confidence in being able to reproduce a +deployment or build, then you ought to check your dependencies into +source control, or pursue some other mechanism that can verify +contents rather than versions. + +## SEE ALSO + +* npm-install(1) +* package.json(5) +* npm-ls(1)