diff --git a/deps/npm/AUTHORS b/deps/npm/AUTHORS index 42263ec8df..b1b915af67 100644 --- a/deps/npm/AUTHORS +++ b/deps/npm/AUTHORS @@ -52,3 +52,5 @@ Gautham Pai David Trejo Paul Vorbach George Ornbo +Tim Oxley +Tyler Green diff --git a/deps/npm/bin/npm-cli.js b/deps/npm/bin/npm-cli.js index e0b9f20bb8..f29437093e 100755 --- a/deps/npm/bin/npm-cli.js +++ b/deps/npm/bin/npm-cli.js @@ -49,6 +49,13 @@ if (conf.version) { return } +if (conf.versions) { + var v = process.versions + v.npm = npm.version + console.log(v) + return +} + log.info("npm@"+npm.version, "using") log.info("node@"+process.version, "using") diff --git a/deps/npm/bin/npm.cmd b/deps/npm/bin/npm.cmd index bac9e5f1c4..7720e20529 100644 --- a/deps/npm/bin/npm.cmd +++ b/deps/npm/bin/npm.cmd @@ -1,6 +1,6 @@ :: Created by npm, please don't edit manually. -@IF EXIST "%~dp0"\"node.exe" ( - "%~dp0"\"node.exe" "%~dp0\.\node_modules\npm\bin\npm-cli.js" %* +@IF EXIST "%~dp0\node.exe" ( + "%~dp0\node.exe" "%~dp0\.\node_modules\npm\bin\npm-cli.js" %* ) ELSE ( - node "%~dp0\.\node_modules\npm\bin\npm-cli.js" %* -) \ No newline at end of file + node "%~dp0\.\node_modules\npm\bin\npm-cli.js" %* +) diff --git a/deps/npm/doc/api/ls.md b/deps/npm/doc/api/ls.md index a6c0a13821..ed890ff146 100644 --- a/deps/npm/doc/api/ls.md +++ b/deps/npm/doc/api/ls.md @@ -21,6 +21,12 @@ It will print out extraneous, missing, and invalid packages. If the silent parameter is set to true, nothing will be output to the screen, but the data will still be returned. +Callback is provided an error if one occurred, the full data about which +packages are installed and which dependencies they will receive, and a +"lite" data object which just shows which versions are installed where. +Note that the full data object is a circular structure, so care must be +taken if it is serialized to JSON. + ## CONFIGURATION ### long diff --git a/deps/npm/doc/api/shrinkwrap.md b/deps/npm/doc/api/shrinkwrap.md new file mode 100644 index 0000000000..6584d6a0da --- /dev/null +++ b/deps/npm/doc/api/shrinkwrap.md @@ -0,0 +1,20 @@ +npm-shrinkwrap(3) -- programmatically generate package shrinkwrap file +==================================================== + +## SYNOPSIS + + npm.commands.shrinkwrap(args, [silent,] callback) + +## DESCRIPTION + +This acts much the same ways as shrinkwrapping on the command-line. + +This command does not take any arguments, but 'args' must be defined. +Beyond that, if any arguments are passed in, npm will politely warn that it +does not take positional arguments. + +If the 'silent' parameter is set to true, nothing will be output to the screen, +but the shrinkwrap file will still be written. + +Finally, 'callback' is a function that will be called when the shrinkwrap has +been saved. diff --git a/deps/npm/doc/cli/config.md b/deps/npm/doc/cli/config.md index 9b3da04c65..9d90f4024e 100644 --- a/deps/npm/doc/cli/config.md +++ b/deps/npm/doc/cli/config.md @@ -372,6 +372,17 @@ The value `npm init` should use by default for the package author's email. The value `npm init` should use by default for the package author's homepage. +### json + +* Default: false +* Type: Boolean + +Whether or not to output JSON data, rather than the normal output. + +This feature is currently experimental, and the output data structures +for many commands is either not implemented in JSON yet, or subject to +change. Only the output from `npm ls --json` is currently valid. + ### link * Default: false @@ -682,6 +693,16 @@ If true, output the npm version and exit successfully. Only relevant when specified explicitly on the command line. +### versions + +* Default: false +* Type: boolean + +If true, output the npm version as well as node's `process.versions` +hash, and exit successfully. + +Only relevant when specified explicitly on the command line. + ### viewer * Default: "man" on Posix, "browser" on Windows diff --git a/deps/npm/doc/cli/index.md b/deps/npm/doc/cli/index.md index 5a9b99be19..ee88f3d8f3 100644 --- a/deps/npm/doc/cli/index.md +++ b/deps/npm/doc/cli/index.md @@ -170,6 +170,10 @@ npm-index(1) -- Index of all npm documentation The semantic versioner for npm +## npm-shrinkwrap(1) + + Lock down dependency versions + ## npm-star(1) Mark your favorite packages @@ -323,6 +327,10 @@ npm-index(1) -- Index of all npm documentation Search for packages +## npm-shrinkwrap(3) + + programmatically generate package shrinkwrap file + ## npm-start(3) Start a package diff --git a/deps/npm/doc/cli/install.md b/deps/npm/doc/cli/install.md index 22eb8234e7..903844a413 100644 --- a/deps/npm/doc/cli/install.md +++ b/deps/npm/doc/cli/install.md @@ -14,7 +14,9 @@ npm-install(1) -- Install a package ## DESCRIPTION -This command installs a package, and any packages that it depends on. +This command installs a package, and any packages that it depends on. If the +package has a shrinkwrap file, the installation of dependencies will be driven +by that. See npm-shrinkwrap(1). A `package` is: @@ -199,3 +201,4 @@ affects a real use-case, it will be investigated. * npm-folders(1) * npm-tag(1) * npm-rm(1) +* npm-shrinkwrap(1) diff --git a/deps/npm/doc/cli/list.md b/deps/npm/doc/cli/list.md index 596349a815..93d86cd838 100644 --- a/deps/npm/doc/cli/list.md +++ b/deps/npm/doc/cli/list.md @@ -22,6 +22,13 @@ When run as `ll` or `la`, it shows extended information by default. ## CONFIGURATION +### json + +* Default: false +* Type: Boolean + +Show information in JSON format. + ### long * Default: false diff --git a/deps/npm/doc/cli/shrinkwrap.md b/deps/npm/doc/cli/shrinkwrap.md new file mode 100644 index 0000000000..3b60b13f7f --- /dev/null +++ b/deps/npm/doc/cli/shrinkwrap.md @@ -0,0 +1,171 @@ +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. + +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", + "dependencies": { + "C": { + "version": "0.1.0" + } + } + } + } + } + +The shrinkwrap command has locked down the dependencies based on what's +currently installed in node_modules. When "npm install" installs a package with +a npm-shrinkwrap.json file 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.1.0, 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 + +Since "npm shrinkwrap" uses the locally installed packages to construct the +shrinkwrap file, devDependencies will be included if and only if you've +installed them already when you make the shrinkwrap. + +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. + +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 + +Shrinkwrap files only lock down package versions, not actual package contents. +While discouraged, a package author can republish an existing version of a +package, causing shrinkwrapped packages using that version to pick up different +code than they were before. If you want to avoid any risk that a byzantine +author replaces a package you're using with code that breaks your application, +you could modify the shrinkwrap file to use git URL references rather than +version numbers so that npm always fetches all packages from git. + +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) +* npm-json(1) +* npm-list(1) diff --git a/deps/npm/html/api/bin.html b/deps/npm/html/api/bin.html index 53a93ac7b9..f532874a08 100644 --- a/deps/npm/html/api/bin.html +++ b/deps/npm/html/api/bin.html @@ -19,7 +19,7 @@

This function should not be used programmatically. Instead, just refer to the npm.bin member.

- + + diff --git a/deps/npm/html/api/start.html b/deps/npm/html/api/start.html index 186fa29f04..6830137e9d 100644 --- a/deps/npm/html/api/start.html +++ b/deps/npm/html/api/start.html @@ -19,7 +19,7 @@

npm can run tests on multiple packages. Just specify multiple packages in the packages parameter.

- + + diff --git a/deps/npm/html/doc/star.html b/deps/npm/html/doc/star.html index 139344be39..a5e1ec3d45 100644 --- a/deps/npm/html/doc/star.html +++ b/deps/npm/html/doc/star.html @@ -26,7 +26,7 @@ a vaguely positive way to show that you care.

- +