diff options
author | Rebecca Turner <me@re-becca.org> | 2015-03-20 12:19:32 +0300 |
---|---|---|
committer | Rebecca Turner <me@re-becca.org> | 2015-06-26 03:26:41 +0300 |
commit | 4335c25df81ba8a46c4b2a661b85b9773c204ae3 (patch) | |
tree | 0cf2445ac4d0da0b221b0164936f63ba32524372 /doc | |
parent | bd6919729f9535f4e3698e78eeb2331236dcdeea (diff) |
Update documentation
Diffstat (limited to 'doc')
-rw-r--r-- | doc/cli/npm-dedupe.md | 21 | ||||
-rw-r--r-- | doc/cli/npm-install.md | 48 | ||||
-rw-r--r-- | doc/cli/npm-ls.md | 3 | ||||
-rw-r--r-- | doc/cli/npm-rm.md | 23 | ||||
-rw-r--r-- | doc/cli/npm-shrinkwrap.md | 38 | ||||
-rw-r--r-- | doc/cli/npm-uninstall.md | 3 | ||||
-rw-r--r-- | doc/files/package.json.md | 13 | ||||
-rw-r--r-- | doc/misc/npm-config.md | 2 |
8 files changed, 70 insertions, 81 deletions
diff --git a/doc/cli/npm-dedupe.md b/doc/cli/npm-dedupe.md index d3be01050..c963dfa8e 100644 --- a/doc/cli/npm-dedupe.md +++ b/doc/cli/npm-dedupe.md @@ -31,25 +31,20 @@ Because of the hierarchical nature of node's module lookup, b and d will both get their dependency met by the single c package at the root level of the tree. +The deduplication algorithm walks the tree, moving each dependency as far +up in the tree as possible, even if duplicates are not found. This will +result in both a flat and deduplicated tree. + If a suitable version exists at the target location in the tree already, then it will be left untouched, but the other duplicates will be deleted. -If no suitable version can be found, then a warning is printed, and -nothing is done. - -If any arguments are supplied, then they are filters, and only the -named packages will be touched. - -Note that this operation transforms the dependency tree, and may -result in packages getting updated versions, perhaps from the npm -registry. +Arguments are ignored. Dedupe always acts on the entire tree. -This feature is experimental, and may change in future versions. +Modules -The `--tag` argument will apply to all of the affected dependencies. If a -tag with the given name exists, the tagged version is preferred over newer -versions. +Note that this operation transforms the dependency tree, but will never +result in new modules being installed. ## SEE ALSO diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md index be32f7b29..2ccde25e0 100644 --- a/doc/cli/npm-install.md +++ b/doc/cli/npm-install.md @@ -27,7 +27,7 @@ A `package` is: * d) a `<name>@<version>` that is published on the registry (see `npm-registry(7)`) with (c) * e) a `<name>@<tag>` that points to (d) * f) a `<name>` that has a "latest" tag satisfying (e) -* g) a `<git remote url>` that resolves to (b) +* g) a `<git remote url>` that resolves to (a) Even if you never publish your package, you can still get a lot of benefits of using npm if you just want to write a node program (a), and @@ -99,6 +99,9 @@ after packing it up into a tarball (b). exact version rather than using npm's default semver range operator. + Further, if you have an `npm-shrinkwrap.json` then it will be updated as + well. + `<scope>` is optional. The package will be downloaded from the registry associated with the specified scope. If no registry is associated with the given scope the default registry is assumed. See `npm-scope(7)`. @@ -157,10 +160,10 @@ after packing it up into a tarball (b). * `npm install <git remote url>`: - Install a package by cloning a git remote url. The format of the git - url is: + Installs the package from the hosted git provider, cloning it with + `git`. First it tries via the https (git with github) and if that fails, via ssh. - <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit-ish>] + <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish>] `<protocol>` is one of `git`, `git+ssh`, `git+http`, or `git+https`. If no `<commit-ish>` is specified, then `master` is @@ -271,26 +274,39 @@ effect on installation, since that's most of what npm does. To install a package, npm uses the following algorithm: - install(where, what, family, ancestors) - fetch what, unpack to <where>/node_modules/<what> - for each dep in what.dependencies - resolve dep to precise version - for each dep@version in what.dependencies - not in <where>/node_modules/<what>/node_modules/* - and not in <family> - add precise version deps to <family> - install(<where>/node_modules/<what>, dep, family) + load the existing node_modules tree from disk + clone the tree + fetch the package.json and assorted metadata and add it to the clone + walk the clone and add any missing dependencies + dependencies will be added as close to the top as is possible + without breaking any other modules + compare the original tree with the cloned tree and make a list of + actions to take to convert one to the other + execute all of the actions, deepest first + kinds of actions are install, update, remove and move For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`, this algorithm produces: A +-- B - `-- C - `-- D + +-- C + +-- D That is, the dependency from B to C is satisfied by the fact that A -already caused C to be installed at a higher level. +already caused C to be installed at a higher level. D is still installed +at the top level because nothing conflicts with it. + +For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces: + + A + +-- B + +-- C + `-- D@2 + +-- D@1 + +Because B's D@1 will be installed in the top leve, C now has to install D@2 +privately for itself. See npm-folders(5) for a more detailed description of the specific folder structures that npm creates. diff --git a/doc/cli/npm-ls.md b/doc/cli/npm-ls.md index 318cdd8fd..fa93e836e 100644 --- a/doc/cli/npm-ls.md +++ b/doc/cli/npm-ls.md @@ -28,6 +28,9 @@ If a project specifies git urls for dependencies these are shown in parentheses after the name@version to make it easier for users to recognize potential forks of a project. +The tree shown is the logical dependency tree, based on package +dependencies, not the physical layout of your node_modules folder. + When run as `ll` or `la`, it shows extended information by default. ## CONFIGURATION diff --git a/doc/cli/npm-rm.md b/doc/cli/npm-rm.md deleted file mode 100644 index 6691265ff..000000000 --- a/doc/cli/npm-rm.md +++ /dev/null @@ -1,23 +0,0 @@ -npm-rm(1) -- Remove a package -============================= - -## SYNOPSIS - - npm rm <name> - npm r <name> - npm uninstall <name> - npm un <name> - -## DESCRIPTION - -This uninstalls a package, completely removing everything npm installed -on its behalf. - -## SEE ALSO - -* npm-prune(1) -* npm-install(1) -* npm-folders(5) -* npm-config(1) -* npm-config(7) -* npmrc(5) diff --git a/doc/cli/npm-shrinkwrap.md b/doc/cli/npm-shrinkwrap.md index ca9cb257b..b4548ca7c 100644 --- a/doc/cli/npm-shrinkwrap.md +++ b/doc/cli/npm-shrinkwrap.md @@ -82,29 +82,32 @@ This generates `npm-shrinkwrap.json`, which will look something like this: { "name": "A", - "version": "0.1.0", + "version": "1.1.0", "dependencies": { "B": { - "version": "0.0.1", + "version": "1.0.1", + "from": "B@^1.0.0", + "resolved": "https://registry.npmjs.org/B/-/B-1.0.1.tgz", "dependencies": { "C": { - "version": "0.0.1" + "version": "1.0.1", + "from": "org/C#v1.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. +The shrinkwrap command has locked down the dependencies based on what's +currently installed in `node_modules`. The installation behavior is changed to: + +1. The module tree described by the shrinkwrap 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. +2. The tree is walked and any missing dependencies are installed in the usual fasion. ### Using shrinkwrapped packages @@ -126,15 +129,14 @@ 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 +2. Add or update dependencies. `npm install --save` each new or updated + package individually to update the `package.json` and the shrinkwrap. + 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. +4. Commit the new `npm-shrinkwrap.json`, and publish your package. You can use npm-outdated(1) to view dependencies with newer versions available. diff --git a/doc/cli/npm-uninstall.md b/doc/cli/npm-uninstall.md index bfa667c3e..72e3b7d45 100644 --- a/doc/cli/npm-uninstall.md +++ b/doc/cli/npm-uninstall.md @@ -27,6 +27,9 @@ the package version in your main package.json: * `--save-optional`: Package will be removed from your `optionalDependencies`. +Further, if you have an `npm-shrinkwrap.json` then it will be updated as +well. + Scope is optional and follows the usual rules for `npm-scope(7)`. Examples: diff --git a/doc/files/package.json.md b/doc/files/package.json.md index f402e2ebc..b8f543c5f 100644 --- a/doc/files/package.json.md +++ b/doc/files/package.json.md @@ -603,17 +603,10 @@ field is advisory only. ## engineStrict -**NOTE: This feature is deprecated and will be removed in npm 3.0.0.** +**This feature was deprecated with npm 3.0.0** -If you are sure that your module will *definitely not* run properly on -versions of Node/npm other than those specified in the `engines` object, -then you can set `"engineStrict": true` in your package.json file. -This will override the user's `engine-strict` config setting. - -Please do not do this unless you are really very very sure. If your -engines object is something overly restrictive, you can quite easily and -inadvertently lock yourself into obscurity and prevent your users from -updating to new versions of Node. Consider this choice carefully. +Prior to npm 3.0.0, this feature was used to treat this package as if the +user had set `engine-strict`. ## os diff --git a/doc/misc/npm-config.md b/doc/misc/npm-config.md index c5cfbe943..454130d43 100644 --- a/doc/misc/npm-config.md +++ b/doc/misc/npm-config.md @@ -816,7 +816,7 @@ on success, but left behind on failure for forensic purposes. ### unicode -* Default: true +* Default: true on windows and mac/unix systems with a unicode locale * Type: Boolean When set to true, npm uses unicode characters in the tree output. When |