| @@ -0,0 +1,70 @@ | ||
| npm-config(1) -- Manage the npm configuration files | ||
| =================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm config set <key> <value> [--global] | ||
| npm config get <key> | ||
| npm config delete <key> | ||
| npm config list | ||
| npm config edit | ||
| npm get <key> | ||
| npm set <key> <value> [--global] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| npm gets its config settings from the command line, environment | ||
| variables, `npmrc` files, and in some cases, the `package.json` file. | ||
|
|
||
| See npmrc(5) for more information about the npmrc files. | ||
|
|
||
| See `npm-config(7)` for a more thorough discussion of the mechanisms | ||
| involved. | ||
|
|
||
| The `npm config` command can be used to update and edit the contents | ||
| of the user and global npmrc files. | ||
|
|
||
| ## Sub-commands | ||
|
|
||
| Config supports the following sub-commands: | ||
|
|
||
| ### set | ||
|
|
||
| npm config set key value | ||
|
|
||
| Sets the config key to the value. | ||
|
|
||
| If value is omitted, then it sets it to "true". | ||
|
|
||
| ### get | ||
|
|
||
| npm config get key | ||
|
|
||
| Echo the config value to stdout. | ||
|
|
||
| ### list | ||
|
|
||
| npm config list | ||
|
|
||
| Show all the config settings. | ||
|
|
||
| ### delete | ||
|
|
||
| npm config delete key | ||
|
|
||
| Deletes the key from all configuration files. | ||
|
|
||
| ### edit | ||
|
|
||
| npm config edit | ||
|
|
||
| Opens the config file in an editor. Use the `--global` flag to edit the | ||
| global config. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-folders(5) | ||
| * npm-config(7) | ||
| * package.json(5) | ||
| * npmrc(5) | ||
| * npm(1) |
| @@ -0,0 +1,26 @@ | ||
| npm-deprecate(1) -- Deprecate a version of a package | ||
| ==================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm deprecate <name>[@<version>] <message> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command will update the npm registry entry for a package, providing | ||
| a deprecation warning to all who attempt to install it. | ||
|
|
||
| It works on version ranges as well as specific versions, so you can do | ||
| something like this: | ||
|
|
||
| npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3" | ||
|
|
||
| Note that you must be the package owner to deprecate something. See the | ||
| `owner` and `adduser` help topics. | ||
|
|
||
| To un-deprecate a package, specify an empty string (`""`) for the `message` argument. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-publish(1) | ||
| * npm-registry(7) |
| @@ -0,0 +1,40 @@ | ||
| npm-docs(1) -- Docs for a package in a web browser maybe | ||
| ======================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm docs <pkgname> | ||
| npm home <pkgname> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command tries to guess at the likely location of a package's | ||
| documentation URL, and then tries to open it using the `--browser` | ||
| config param. | ||
|
|
||
| ## CONFIGURATION | ||
|
|
||
| ### browser | ||
|
|
||
| * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` | ||
| * Type: String | ||
|
|
||
| The browser that is called by the `npm docs` command to open websites. | ||
|
|
||
| ### registry | ||
|
|
||
| * Default: https://registry.npmjs.org/ | ||
| * Type: url | ||
|
|
||
| The base URL of the npm package registry. | ||
|
|
||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-view(1) | ||
| * npm-publish(1) | ||
| * npm-registry(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * package.json(5) |
| @@ -0,0 +1,37 @@ | ||
| npm-edit(1) -- Edit an installed package | ||
| ======================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm edit <name>[@<version>] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Opens the package folder in the default editor (or whatever you've | ||
| configured as the npm `editor` config -- see `npm-config(7)`.) | ||
|
|
||
| After it has been edited, the package is rebuilt so as to pick up any | ||
| changes in compiled packages. | ||
|
|
||
| For instance, you can do `npm install connect` to install connect | ||
| into your package, and then `npm edit connect` to make a few | ||
| changes to your locally installed copy. | ||
|
|
||
| ## CONFIGURATION | ||
|
|
||
| ### editor | ||
|
|
||
| * Default: `EDITOR` environment variable if set, or `"vi"` on Posix, | ||
| or `"notepad"` on Windows. | ||
| * Type: path | ||
|
|
||
| The command to run for `npm edit` or `npm config edit`. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-folders(7) | ||
| * npm-explore(1) | ||
| * npm-install(1) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,40 @@ | ||
| npm-explore(1) -- Browse an installed package | ||
| ============================================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm explore <name>[@<version>] [ -- <cmd>] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Spawn a subshell in the directory of the installed package specified. | ||
|
|
||
| If a command is specified, then it is run in the subshell, which then | ||
| immediately terminates. | ||
|
|
||
| This is particularly handy in the case of git submodules in the | ||
| `node_modules` folder: | ||
|
|
||
| npm explore some-dependency -- git pull origin master | ||
|
|
||
| Note that the package is *not* automatically rebuilt afterwards, so be | ||
| sure to use `npm rebuild <pkg>` if you make any changes. | ||
|
|
||
| ## CONFIGURATION | ||
|
|
||
| ### shell | ||
|
|
||
| * Default: SHELL environment variable, or "bash" on Posix, or "cmd" on | ||
| Windows | ||
| * Type: path | ||
|
|
||
| The shell to run for the `npm explore` command. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-submodule(1) | ||
| * npm-folders(7) | ||
| * npm-edit(1) | ||
| * npm-rebuild(1) | ||
| * npm-build(1) | ||
| * npm-install(1) |
| @@ -0,0 +1,35 @@ | ||
| npm-help-search(1) -- Search npm help documentation | ||
| =================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm help-search some search terms | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command will search the npm markdown documentation files for the | ||
| terms provided, and then list the results, sorted by relevance. | ||
|
|
||
| If only one result is found, then it will show that help topic. | ||
|
|
||
| If the argument to `npm help` is not a known help topic, then it will | ||
| call `help-search`. It is rarely if ever necessary to call this | ||
| command directly. | ||
|
|
||
| ## CONFIGURATION | ||
|
|
||
| ### long | ||
|
|
||
| * Type: Boolean | ||
| * Default false | ||
|
|
||
| If true, the "long" flag will cause help-search to output context around | ||
| where the terms were found in the documentation. | ||
|
|
||
| If false, then help-search will just list out the help topics found. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm(1) | ||
| * npm-faq(7) | ||
| * npm-help(1) |
| @@ -0,0 +1,40 @@ | ||
| npm-help(1) -- Get help on npm | ||
| ============================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm help <topic> | ||
| npm help some search terms | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| If supplied a topic, then show the appropriate documentation page. | ||
|
|
||
| If the topic does not exist, or if multiple terms are provided, then run | ||
| the `help-search` command to find a match. Note that, if `help-search` | ||
| finds a single subject, then it will run `help` on that topic, so unique | ||
| matches are equivalent to specifying a topic name. | ||
|
|
||
| ## CONFIGURATION | ||
|
|
||
| ### viewer | ||
|
|
||
| * Default: "man" on Posix, "browser" on Windows | ||
| * Type: path | ||
|
|
||
| The program to use to view help content. | ||
|
|
||
| Set to `"browser"` to view html help content in the default web browser. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm(1) | ||
| * README | ||
| * npm-faq(7) | ||
| * npm-folders(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * package.json(5) | ||
| * npm-help-search(1) | ||
| * npm-index(7) |
| @@ -0,0 +1,25 @@ | ||
| npm-init(1) -- Interactively create a package.json file | ||
| ======================================================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm init | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This will ask you a bunch of questions, and then write a package.json for you. | ||
|
|
||
| It attempts to make reasonable guesses about what you want things to be set to, | ||
| and then writes a package.json file with the options you've selected. | ||
|
|
||
| If you already have a package.json file, it'll read that first, and default to | ||
| the options in there. | ||
|
|
||
| It is strictly additive, so it does not delete options from your package.json | ||
| without a really good reason to do so. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * <https://github.com/isaacs/init-package-json> | ||
| * package.json(5) | ||
| * npm-version(1) |
| @@ -0,0 +1,244 @@ | ||
| npm-install(1) -- Install a package | ||
| =================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm install (with no args in a package dir) | ||
| npm install <tarball file> | ||
| npm install <tarball url> | ||
| npm install <folder> | ||
| npm install <name> [--save|--save-dev|--save-optional] | ||
| npm install <name>@<tag> | ||
| npm install <name>@<version> | ||
| npm install <name>@<version range> | ||
| npm install <name>@<version range> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| 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: | ||
|
|
||
| * a) a folder containing a program described by a package.json file | ||
| * b) a gzipped tarball containing (a) | ||
| * c) a url that resolves to (b) | ||
| * d) a `<name>@<version>` that is published on the registry 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) | ||
|
|
||
| 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 | ||
| perhaps if you also want to be able to easily install it elsewhere | ||
| after packing it up into a tarball (b). | ||
|
|
||
|
|
||
| * `npm install` (in package directory, no arguments): | ||
|
|
||
| Install the dependencies in the local node_modules folder. | ||
|
|
||
| In global mode (ie, with `-g` or `--global` appended to the command), | ||
| it installs the current package context (ie, the current working | ||
| directory) as a global package. | ||
|
|
||
|
|
||
| * `npm install <folder>`: | ||
|
|
||
| Install a package that is sitting in a folder on the filesystem. | ||
|
|
||
| * `npm install <tarball file>`: | ||
|
|
||
| Install a package that is sitting on the filesystem. Note: if you just want | ||
| to link a dev directory into your npm root, you can do this more easily by | ||
| using `npm link`. | ||
|
|
||
| Example: | ||
|
|
||
| npm install ./package.tgz | ||
|
|
||
| * `npm install <tarball url>`: | ||
|
|
||
| Fetch the tarball url, and then install it. In order to distinguish between | ||
| this and other options, the argument must start with "http://" or "https://" | ||
|
|
||
| Example: | ||
|
|
||
| npm install https://github.com/indexzero/forever/tarball/v0.5.6 | ||
|
|
||
| * `npm install <name> [--save|--save-dev|--save-optional]`: | ||
|
|
||
| Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See | ||
| `npm-config(7)`.) | ||
|
|
||
| In most cases, this will install the latest version | ||
| of the module published on npm. | ||
|
|
||
| Example: | ||
|
|
||
| npm install sax | ||
|
|
||
| `npm install` takes 3 exclusive, optional flags which save or update | ||
| the package version in your main package.json: | ||
|
|
||
| * `--save`: Package will appear in your `dependencies`. | ||
|
|
||
| * `--save-dev`: Package will appear in your `devDependencies`. | ||
|
|
||
| * `--save-optional`: Package will appear in your `optionalDependencies`. | ||
|
|
||
| Examples: | ||
|
|
||
| npm install sax --save | ||
| npm install node-tap --save-dev | ||
| npm install dtrace-provider --save-optional | ||
|
|
||
|
|
||
| **Note**: If there is a file or folder named `<name>` in the current | ||
| working directory, then it will try to install that, and only try to | ||
| fetch the package by name if it is not valid. | ||
|
|
||
| * `npm install <name>@<tag>`: | ||
|
|
||
| Install the version of the package that is referenced by the specified tag. | ||
| If the tag does not exist in the registry data for that package, then this | ||
| will fail. | ||
|
|
||
| Example: | ||
|
|
||
| npm install sax@latest | ||
|
|
||
| * `npm install <name>@<version>`: | ||
|
|
||
| Install the specified version of the package. This will fail if the version | ||
| has not been published to the registry. | ||
|
|
||
| Example: | ||
|
|
||
| npm install sax@0.1.1 | ||
|
|
||
| * `npm install <name>@<version range>`: | ||
|
|
||
| Install a version of the package matching the specified version range. This | ||
| will follow the same rules for resolving dependencies described in `package.json(5)`. | ||
|
|
||
| Note that most version ranges must be put in quotes so that your shell will | ||
| treat it as a single argument. | ||
|
|
||
| Example: | ||
|
|
||
| npm install sax@">=0.1.0 <0.2.0" | ||
|
|
||
| * `npm install <git remote url>`: | ||
|
|
||
| Install a package by cloning a git remote url. The format of the git | ||
| url is: | ||
|
|
||
| <protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>] | ||
|
|
||
| `<protocol>` is one of `git`, `git+ssh`, `git+http`, or | ||
| `git+https`. If no `<commit-ish>` is specified, then `master` is | ||
| used. | ||
|
|
||
| Examples: | ||
|
|
||
| git+ssh://git@github.com:isaacs/npm.git#v1.0.27 | ||
| git+https://isaacs@github.com/isaacs/npm.git | ||
| git://github.com/isaacs/npm.git#v1.0.27 | ||
|
|
||
| You may combine multiple arguments, and even multiple types of arguments. | ||
| For example: | ||
|
|
||
| npm install sax@">=0.1.0 <0.2.0" bench supervisor | ||
|
|
||
| The `--tag` argument will apply to all of the specified install targets. | ||
|
|
||
| The `--force` argument will force npm to fetch remote resources even if a | ||
| local copy exists on disk. | ||
|
|
||
| npm install sax --force | ||
|
|
||
| The `--global` argument will cause npm to install the package globally | ||
| rather than locally. See `npm-folders(7)`. | ||
|
|
||
| The `--link` argument will cause npm to link global installs into the | ||
| local space in some cases. | ||
|
|
||
| The `--no-bin-links` argument will prevent npm from creating symlinks for | ||
| any binaries the package might contain. | ||
|
|
||
| The `--no-shrinkwrap` argument, which will ignore an available | ||
| shrinkwrap file and use the package.json instead. | ||
|
|
||
| The `--nodedir=/path/to/node/source` argument will allow npm to find the | ||
| node source code so that npm can compile native modules. | ||
|
|
||
| See `npm-config(7)`. Many of the configuration params have some | ||
| effect on installation, since that's most of what npm does. | ||
|
|
||
| ## ALGORITHM | ||
|
|
||
| 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) | ||
|
|
||
| For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`, | ||
| this algorithm produces: | ||
|
|
||
| A | ||
| +-- B | ||
| `-- 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. | ||
|
|
||
| See npm-folders(7) for a more detailed description of the specific | ||
| folder structures that npm creates. | ||
|
|
||
| ### Limitations of npm's Install Algorithm | ||
|
|
||
| There are some very rare and pathological edge-cases where a cycle can | ||
| cause npm to try to install a never-ending tree of packages. Here is | ||
| the simplest case: | ||
|
|
||
| A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ... | ||
|
|
||
| where `A` is some version of a package, and `A'` is a different version | ||
| of the same package. Because `B` depends on a different version of `A` | ||
| than the one that is already in the tree, it must install a separate | ||
| copy. The same is true of `A'`, which must install `B'`. Because `B'` | ||
| depends on the original version of `A`, which has been overridden, the | ||
| cycle falls into infinite regress. | ||
|
|
||
| To avoid this situation, npm flat-out refuses to install any | ||
| `name@version` that is already present anywhere in the tree of package | ||
| folder ancestors. A more correct, but more complex, solution would be | ||
| to symlink the existing version into the new location. If this ever | ||
| affects a real use-case, it will be investigated. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-folders(7) | ||
| * npm-update(1) | ||
| * npm-link(1) | ||
| * npm-rebuild(1) | ||
| * npm-scripts(7) | ||
| * npm-build(1) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-registry(7) | ||
| * npm-folders(7) | ||
| * npm-tag(1) | ||
| * npm-rm(1) | ||
| * npm-shrinkwrap(1) |
| @@ -0,0 +1,62 @@ | ||
| npm-link(1) -- Symlink a package folder | ||
| ======================================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm link (in package folder) | ||
| npm link <pkgname> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Package linking is a two-step process. | ||
|
|
||
| First, `npm link` in a package folder will create a globally-installed | ||
| symbolic link from `prefix/package-name` to the current folder. | ||
|
|
||
| Next, in some other location, `npm link package-name` will create a | ||
| symlink from the local `node_modules` folder to the global symlink. | ||
|
|
||
| Note that `package-name` is taken from `package.json` , | ||
| not from directory name. | ||
|
|
||
| When creating tarballs for `npm publish`, the linked packages are | ||
| "snapshotted" to their current state by resolving the symbolic links. | ||
|
|
||
| This is | ||
| handy for installing your own stuff, so that you can work on it and test it | ||
| iteratively without having to continually rebuild. | ||
|
|
||
| For example: | ||
|
|
||
| cd ~/projects/node-redis # go into the package directory | ||
| npm link # creates global link | ||
| cd ~/projects/node-bloggy # go into some other package directory. | ||
| npm link redis # link-install the package | ||
|
|
||
| Now, any changes to ~/projects/node-redis will be reflected in | ||
| ~/projects/node-bloggy/node_modules/redis/ | ||
|
|
||
| You may also shortcut the two steps in one. For example, to do the | ||
| above use-case in a shorter way: | ||
|
|
||
| cd ~/projects/node-bloggy # go into the dir of your main project | ||
| npm link ../node-redis # link the dir of your dependency | ||
|
|
||
| The second line is the equivalent of doing: | ||
|
|
||
| (cd ../node-redis; npm link) | ||
| npm link redis | ||
|
|
||
| That is, it first creates a global link, and then links the global | ||
| installation target into your project's `node_modules` folder. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-developers(7) | ||
| * npm-faq(7) | ||
| * package.json(5) | ||
| * npm-install(1) | ||
| * npm-folders(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,74 @@ | ||
| npm-ls(1) -- List installed packages | ||
| ====================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm list [<pkg> ...] | ||
| npm ls [<pkg> ...] | ||
| npm la [<pkg> ...] | ||
| npm ll [<pkg> ...] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command will print to stdout all the versions of packages that are | ||
| installed, as well as their dependencies, in a tree-structure. | ||
|
|
||
| Positional arguments are `name@version-range` identifiers, which will | ||
| limit the results to only the paths to the packages named. Note that | ||
| nested packages will *also* show the paths to the specified packages. | ||
| For example, running `npm ls promzard` in npm's source tree will show: | ||
|
|
||
| npm@@VERSION@ /path/to/npm | ||
| └─┬ init-package-json@0.0.4 | ||
| └── promzard@0.1.5 | ||
|
|
||
| It will print out extraneous, missing, and invalid packages. | ||
|
|
||
| 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. | ||
|
|
||
| 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 | ||
| * Type: Boolean | ||
|
|
||
| Show extended information. | ||
|
|
||
| ### parseable | ||
|
|
||
| * Default: false | ||
| * Type: Boolean | ||
|
|
||
| Show parseable output instead of tree view. | ||
|
|
||
| ### global | ||
|
|
||
| * Default: false | ||
| * Type: Boolean | ||
|
|
||
| List packages in the global install prefix instead of in the current | ||
| project. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-folders(7) | ||
| * npm-install(1) | ||
| * npm-link(1) | ||
| * npm-prune(1) | ||
| * npm-outdated(1) | ||
| * npm-update(1) |
| @@ -0,0 +1,17 @@ | ||
| npm-outdated(1) -- Check for outdated packages | ||
| ============================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm outdated [<name> [<name> ...]] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command will check the registry to see if any (or, specific) installed | ||
| packages are currently outdated. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-update(1) | ||
| * npm-registry(7) | ||
| * npm-folders(7) |
| @@ -0,0 +1,33 @@ | ||
| npm-owner(1) -- Manage package owners | ||
| ===================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm owner ls <package name> | ||
| npm owner add <user> <package name> | ||
| npm owner rm <user> <package name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Manage ownership of published packages. | ||
|
|
||
| * ls: | ||
| List all the users who have access to modify a package and push new versions. | ||
| Handy when you need to know who to bug for help. | ||
| * add: | ||
| Add a new user as a maintainer of a package. This user is enabled to modify | ||
| metadata, publish new versions, and add other owners. | ||
| * rm: | ||
| Remove a user from the package owner list. This immediately revokes their | ||
| privileges. | ||
|
|
||
| Note that there is only one level of access. Either you can modify a package, | ||
| or you can't. Future versions may contain more fine-grained access levels, but | ||
| that is not implemented at this time. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-publish(1) | ||
| * npm-registry(7) | ||
| * npm-adduser(1) | ||
| * npm-disputes(7) |
| @@ -0,0 +1,27 @@ | ||
| npm-pack(1) -- Create a tarball from a package | ||
| ============================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm pack [<pkg> [<pkg> ...]] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| For anything that's installable (that is, a package folder, tarball, | ||
| tarball url, name@tag, name@version, or name), this command will fetch | ||
| it to the cache, and then copy the tarball to the current working | ||
| directory as `<name>-<version>.tgz`, and then write the filenames out to | ||
| stdout. | ||
|
|
||
| If the same package is specified multiple times, then the file will be | ||
| overwritten the second time. | ||
|
|
||
| If no arguments are supplied, then npm packs the current package folder. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-cache(1) | ||
| * npm-publish(1) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,19 @@ | ||
| npm-prefix(1) -- Display prefix | ||
| =============================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm prefix | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Print the prefix to standard out. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-root(1) | ||
| * npm-bin(1) | ||
| * npm-folders(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,21 @@ | ||
| npm-prune(1) -- Remove extraneous packages | ||
| ========================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm prune [<name> [<name ...]] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command removes "extraneous" packages. If a package name is | ||
| provided, then only packages matching one of the supplied names are | ||
| removed. | ||
|
|
||
| Extraneous packages are packages that are not listed on the parent | ||
| package's dependencies list. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-rm(1) | ||
| * npm-folders(7) | ||
| * npm-list(1) |
| @@ -0,0 +1,30 @@ | ||
| npm-publish(1) -- Publish a package | ||
| =================================== | ||
|
|
||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm publish <tarball> | ||
| npm publish <folder> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Publishes a package to the registry so that it can be installed by name. | ||
|
|
||
| * `<folder>`: | ||
| A folder containing a package.json file | ||
|
|
||
| * `<tarball>`: | ||
| A url or file path to a gzipped tar archive containing a single folder | ||
| with a package.json file inside. | ||
|
|
||
| Fails if the package name and version combination already exists in | ||
| the registry. Overwrites when the "--force" flag is set. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-registry(7) | ||
| * npm-adduser(1) | ||
| * npm-owner(1) | ||
| * npm-deprecate(1) | ||
| * npm-tag(1) |
| @@ -0,0 +1,22 @@ | ||
| npm-restart(1) -- Start a package | ||
| ================================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm restart <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This runs a package's "restart" script, if one was provided. | ||
| Otherwise it runs package's "stop" script, if one was provided, and then | ||
| the "start" script. | ||
|
|
||
| If no version is specified, then it restarts the "active" version. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-run-script(1) | ||
| * npm-scripts(7) | ||
| * npm-test(1) | ||
| * npm-start(1) | ||
| * npm-stop(1) |
| @@ -0,0 +1,21 @@ | ||
| npm-rm(1) -- Remove a package | ||
| ============================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm rm <name> | ||
| npm uninstall <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This uninstalls a package, completely removing everything npm installed | ||
| on its behalf. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-prune(1) | ||
| * npm-install(1) | ||
| * npm-folders(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,19 @@ | ||
| npm-root(1) -- Display npm root | ||
| =============================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm root | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Print the effective `node_modules` folder to standard out. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-prefix(1) | ||
| * npm-bin(1) | ||
| * npm-folders(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,21 @@ | ||
| npm-run-script(1) -- Run arbitrary package scripts | ||
| ================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm run-script <script> <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This runs an arbitrary command from a package's "scripts" object. | ||
|
|
||
| It is used by the test, start, restart, and stop commands, but can be | ||
| called directly, as well. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-scripts(7) | ||
| * npm-test(1) | ||
| * npm-start(1) | ||
| * npm-restart(1) | ||
| * npm-stop(1) |
| @@ -0,0 +1,22 @@ | ||
| npm-search(1) -- Search for packages | ||
| ==================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm search [search terms ...] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Search the registry for packages matching the search terms. | ||
|
|
||
| If a term starts with `/`, then it's interpreted as a regular expression. | ||
| A trailing `/` will be ignored in this case. (Note that many regular | ||
| expression characters must be escaped or quoted in most shells.) | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-registry(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-view(1) |
| @@ -0,0 +1,185 @@ | ||
| 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", | ||
| "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 | ||
|
|
||
| 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 | ||
|
|
||
| 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) | ||
| * package.json(5) | ||
| * npm-list(1) |
| @@ -0,0 +1,18 @@ | ||
| npm-start(1) -- Start a package | ||
| =============================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm start <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This runs a package's "start" script, if one was provided. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-run-script(1) | ||
| * npm-scripts(7) | ||
| * npm-test(1) | ||
| * npm-restart(1) | ||
| * npm-stop(1) |
| @@ -0,0 +1,18 @@ | ||
| npm-stop(1) -- Stop a package | ||
| ============================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm stop <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This runs a package's "stop" script, if one was provided. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-run-script(1) | ||
| * npm-scripts(7) | ||
| * npm-test(1) | ||
| * npm-start(1) | ||
| * npm-restart(1) |
| @@ -0,0 +1,28 @@ | ||
| npm-submodule(1) -- Add a package as a git submodule | ||
| ==================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm submodule <pkg> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| If the specified package has a git repository url in its package.json | ||
| description, then this command will add it as a git submodule at | ||
| `node_modules/<pkg name>`. | ||
|
|
||
| This is a convenience only. From then on, it's up to you to manage | ||
| updates by using the appropriate git commands. npm will stubbornly | ||
| refuse to update, modify, or remove anything with a `.git` subfolder | ||
| in it. | ||
|
|
||
| This command also does not install missing dependencies, if the package | ||
| does not include them in its git repository. If `npm ls` reports that | ||
| things are missing, you can either install, link, or submodule them yourself, | ||
| or you can do `npm explore <pkgname> -- npm install` to install the | ||
| dependencies into the submodule folder. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * package.json(5) | ||
| * git help submodule |
| @@ -0,0 +1,19 @@ | ||
| npm-tag(1) -- Tag a published version | ||
| ===================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm tag <name>@<version> [<tag>] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Tags the specified version of the package with the specified tag, or the | ||
| `--tag` config if not specified. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-publish(1) | ||
| * npm-registry(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,21 @@ | ||
| npm-test(1) -- Test a package | ||
| ============================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm test <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This runs a package's "test" script, if one was provided. | ||
|
|
||
| To run tests as a condition of installation, set the `npat` config to | ||
| true. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-run-script(1) | ||
| * npm-scripts(7) | ||
| * npm-start(1) | ||
| * npm-restart(1) | ||
| * npm-stop(1) |
| @@ -0,0 +1,21 @@ | ||
| npm-rm(1) -- Remove a package | ||
| ============================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm rm <name> | ||
| npm uninstall <name> | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This uninstalls a package, completely removing everything npm installed | ||
| on its behalf. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-prune(1) | ||
| * npm-install(1) | ||
| * npm-folders(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) |
| @@ -0,0 +1,32 @@ | ||
| npm-unpublish(1) -- Remove a package from the registry | ||
| ====================================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm unpublish <name>[@<version>] | ||
|
|
||
| ## WARNING | ||
|
|
||
| **It is generally considered bad behavior to remove versions of a library | ||
| that others are depending on!** | ||
|
|
||
| Consider using the `deprecate` command | ||
| instead, if your intent is to encourage users to upgrade. | ||
|
|
||
| There is plenty of room on the registry. | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This removes a package version from the registry, deleting its | ||
| entry and removing the tarball. | ||
|
|
||
| If no version is specified, or if all versions are removed then | ||
| the root package entry is removed from the registry entirely. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-deprecate(1) | ||
| * npm-publish(1) | ||
| * npm-registry(7) | ||
| * npm-adduser(1) | ||
| * npm-owner(1) |
| @@ -0,0 +1,24 @@ | ||
| npm-update(1) -- Update a package | ||
| ================================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm update [-g] [<name> [<name> ...]] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command will update all the packages listed to the latest version | ||
| (specified by the `tag` config). | ||
|
|
||
| It will also install missing packages. | ||
|
|
||
| If the `-g` flag is specified, this command will update globally installed packages. | ||
| If no package name is specified, all packages in the specified location (global or local) will be updated. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-install(1) | ||
| * npm-outdated(1) | ||
| * npm-registry(7) | ||
| * npm-folders(7) | ||
| * npm-list(1) |
| @@ -0,0 +1,45 @@ | ||
| npm-version(1) -- Bump a package version | ||
| ======================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm version [<newversion> | major | minor | patch | build] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Run this in a package directory to bump the version and write the new | ||
| data back to the package.json file. | ||
|
|
||
| The `newversion` argument should be a valid semver string, *or* a valid | ||
| second argument to semver.inc (one of "build", "patch", "minor", or | ||
| "major"). In the second case, the existing version will be incremented | ||
| by 1 in the specified field. | ||
|
|
||
| If run in a git repo, it will also create a version commit and tag, and | ||
| fail if the repo is not clean. | ||
|
|
||
| If supplied with `--message` (shorthand: `-m`) config option, npm will | ||
| use it as a commit message when creating a version commit. If the | ||
| `message` config contains `%s` then that will be replaced with the | ||
| resulting version number. For example: | ||
|
|
||
| npm version patch -m "Upgrade to %s for reasons" | ||
|
|
||
| If the `sign-git-tag` config is set, then the tag will be signed using | ||
| the `-s` flag to git. Note that you must have a default GPG key set up | ||
| in your git config for this to work properly. For example: | ||
|
|
||
| $ npm config set sign-git-tag true | ||
| $ npm version patch | ||
|
|
||
| You need a passphrase to unlock the secret key for | ||
| user: "isaacs (http://blog.izs.me/) <i@izs.me>" | ||
| 2048-bit RSA key, ID 6C481CF6, created 2010-08-31 | ||
|
|
||
| Enter passphrase: | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-init(1) | ||
| * package.json(5) | ||
| * npm-semver(7) |
| @@ -0,0 +1,89 @@ | ||
| npm-view(1) -- View registry info | ||
| ================================= | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm view <name>[@<version>] [<field>[.<subfield>]...] | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| This command shows data about a package and prints it to the stream | ||
| referenced by the `outfd` config, which defaults to stdout. | ||
|
|
||
| To show the package registry entry for the `connect` package, you can do | ||
| this: | ||
|
|
||
| npm view connect | ||
|
|
||
| The default version is "latest" if unspecified. | ||
|
|
||
| Field names can be specified after the package descriptor. | ||
| For example, to show the dependencies of the `ronn` package at version | ||
| 0.3.5, you could do the following: | ||
|
|
||
| npm view ronn@0.3.5 dependencies | ||
|
|
||
| You can view child field by separating them with a period. | ||
| To view the git repository URL for the latest version of npm, you could | ||
| do this: | ||
|
|
||
| npm view npm repository.url | ||
|
|
||
| This makes it easy to view information about a dependency with a bit of | ||
| shell scripting. For example, to view all the data about the version of | ||
| opts that ronn depends on, you can do this: | ||
|
|
||
| npm view opts@$(npm view ronn dependencies.opts) | ||
|
|
||
| For fields that are arrays, requesting a non-numeric field will return | ||
| all of the values from the objects in the list. For example, to get all | ||
| the contributor names for the "express" project, you can do this: | ||
|
|
||
| npm view express contributors.email | ||
|
|
||
| You may also use numeric indices in square braces to specifically select | ||
| an item in an array field. To just get the email address of the first | ||
| contributor in the list, you can do this: | ||
|
|
||
| npm view express contributors[0].email | ||
|
|
||
| Multiple fields may be specified, and will be printed one after another. | ||
| For exampls, to get all the contributor names and email addresses, you | ||
| can do this: | ||
|
|
||
| npm view express contributors.name contributors.email | ||
|
|
||
| "Person" fields are shown as a string if they would be shown as an | ||
| object. So, for example, this will show the list of npm contributors in | ||
| the shortened string format. (See `package.json(5)` for more on this.) | ||
|
|
||
| npm view npm contributors | ||
|
|
||
| If a version range is provided, then data will be printed for every | ||
| matching version of the package. This will show which version of jsdom | ||
| was required by each matching version of yui3: | ||
|
|
||
| npm view yui3@'>0.5.4' dependencies.jsdom | ||
|
|
||
| ## OUTPUT | ||
|
|
||
| If only a single string field for a single version is output, then it | ||
| will not be colorized or quoted, so as to enable piping the output to | ||
| another command. If the field is an object, it will be output as a JavaScript object literal. | ||
|
|
||
| If the --json flag is given, the outputted fields will be JSON. | ||
|
|
||
| If the version range matches multiple versions, than each printed value | ||
| will be prefixed with the version it applies to. | ||
|
|
||
| If multiple fields are requested, than each of them are prefixed with | ||
| the field name. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-search(1) | ||
| * npm-registry(7) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-docs(1) |
| @@ -0,0 +1,17 @@ | ||
| npm-whoami(1) -- Display npm username | ||
| ===================================== | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| npm whoami | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| Print the `username` config to standard output. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-adduser(1) |
| @@ -0,0 +1,211 @@ | ||
| npm-folders(5) -- Folder Structures Used by npm | ||
| =============================================== | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| npm puts various things on your computer. That's its job. | ||
|
|
||
| This document will tell you what it puts where. | ||
|
|
||
| ### tl;dr | ||
|
|
||
| * Local install (default): puts stuff in `./node_modules` of the current | ||
| package root. | ||
| * Global install (with `-g`): puts stuff in /usr/local or wherever node | ||
| is installed. | ||
| * Install it **locally** if you're going to `require()` it. | ||
| * Install it **globally** if you're going to run it on the command line. | ||
| * If you need both, then install it in both places, or use `npm link`. | ||
|
|
||
| ### prefix Configuration | ||
|
|
||
| The `prefix` config defaults to the location where node is installed. | ||
| On most systems, this is `/usr/local`, and most of the time is the same | ||
| as node's `process.installPrefix`. | ||
|
|
||
| On windows, this is the exact location of the node.exe binary. On Unix | ||
| systems, it's one level up, since node is typically installed at | ||
| `{prefix}/bin/node` rather than `{prefix}/node.exe`. | ||
|
|
||
| When the `global` flag is set, npm installs things into this prefix. | ||
| When it is not set, it uses the root of the current package, or the | ||
| current working directory if not in a package already. | ||
|
|
||
| ### Node Modules | ||
|
|
||
| Packages are dropped into the `node_modules` folder under the `prefix`. | ||
| When installing locally, this means that you can | ||
| `require("packagename")` to load its main module, or | ||
| `require("packagename/lib/path/to/sub/module")` to load other modules. | ||
|
|
||
| Global installs on Unix systems go to `{prefix}/lib/node_modules`. | ||
| Global installs on Windows go to `{prefix}/node_modules` (that is, no | ||
| `lib` folder.) | ||
|
|
||
| If you wish to `require()` a package, then install it locally. | ||
|
|
||
| ### Executables | ||
|
|
||
| When in global mode, executables are linked into `{prefix}/bin` on Unix, | ||
| or directly into `{prefix}` on Windows. | ||
|
|
||
| When in local mode, executables are linked into | ||
| `./node_modules/.bin` so that they can be made available to scripts run | ||
| through npm. (For example, so that a test runner will be in the path | ||
| when you run `npm test`.) | ||
|
|
||
| ### Man Pages | ||
|
|
||
| When in global mode, man pages are linked into `{prefix}/share/man`. | ||
|
|
||
| When in local mode, man pages are not installed. | ||
|
|
||
| Man pages are not installed on Windows systems. | ||
|
|
||
| ### Cache | ||
|
|
||
| See `npm-cache(1)`. Cache files are stored in `~/.npm` on Posix, or | ||
| `~/npm-cache` on Windows. | ||
|
|
||
| This is controlled by the `cache` configuration param. | ||
|
|
||
| ### Temp Files | ||
|
|
||
| Temporary files are stored by default in the folder specified by the | ||
| `tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment | ||
| variables, or `/tmp` on Unix and `c:\windows\temp` on Windows. | ||
|
|
||
| Temp files are given a unique folder under this root for each run of the | ||
| program, and are deleted upon successful exit. | ||
|
|
||
| ## More Information | ||
|
|
||
| When installing locally, npm first tries to find an appropriate | ||
| `prefix` folder. This is so that `npm install foo@1.2.3` will install | ||
| to the sensible root of your package, even if you happen to have `cd`ed | ||
| into some other folder. | ||
|
|
||
| Starting at the $PWD, npm will walk up the folder tree checking for a | ||
| folder that contains either a `package.json` file, or a `node_modules` | ||
| folder. If such a thing is found, then that is treated as the effective | ||
| "current directory" for the purpose of running npm commands. (This | ||
| behavior is inspired by and similar to git's .git-folder seeking | ||
| logic when running git commands in a working dir.) | ||
|
|
||
| If no package root is found, then the current folder is used. | ||
|
|
||
| When you run `npm install foo@1.2.3`, then the package is loaded into | ||
| the cache, and then unpacked into `./node_modules/foo`. Then, any of | ||
| foo's dependencies are similarly unpacked into | ||
| `./node_modules/foo/node_modules/...`. | ||
|
|
||
| Any bin files are symlinked to `./node_modules/.bin/`, so that they may | ||
| be found by npm scripts when necessary. | ||
|
|
||
| ### Global Installation | ||
|
|
||
| If the `global` configuration is set to true, then npm will | ||
| install packages "globally". | ||
|
|
||
| For global installation, packages are installed roughly the same way, | ||
| but using the folders described above. | ||
|
|
||
| ### Cycles, Conflicts, and Folder Parsimony | ||
|
|
||
| Cycles are handled using the property of node's module system that it | ||
| walks up the directories looking for `node_modules` folders. So, at every | ||
| stage, if a package is already installed in an ancestor `node_modules` | ||
| folder, then it is not installed at the current location. | ||
|
|
||
| Consider the case above, where `foo -> bar -> baz`. Imagine if, in | ||
| addition to that, baz depended on bar, so you'd have: | ||
| `foo -> bar -> baz -> bar -> baz ...`. However, since the folder | ||
| structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to | ||
| put another copy of bar into `.../baz/node_modules`, since when it calls | ||
| require("bar"), it will get the copy that is installed in | ||
| `foo/node_modules/bar`. | ||
|
|
||
| This shortcut is only used if the exact same | ||
| version would be installed in multiple nested `node_modules` folders. It | ||
| is still possible to have `a/node_modules/b/node_modules/a` if the two | ||
| "a" packages are different versions. However, without repeating the | ||
| exact same package multiple times, an infinite regress will always be | ||
| prevented. | ||
|
|
||
| Another optimization can be made by installing dependencies at the | ||
| highest level possible, below the localized "target" folder. | ||
|
|
||
| #### Example | ||
|
|
||
| Consider this dependency graph: | ||
|
|
||
| foo | ||
| +-- blerg@1.2.5 | ||
| +-- bar@1.2.3 | ||
| | +-- blerg@1.x (latest=1.3.7) | ||
| | +-- baz@2.x | ||
| | | `-- quux@3.x | ||
| | | `-- bar@1.2.3 (cycle) | ||
| | `-- asdf@* | ||
| `-- baz@1.2.3 | ||
| `-- quux@3.x | ||
| `-- bar | ||
|
|
||
| In this case, we might expect a folder structure like this: | ||
|
|
||
| foo | ||
| +-- node_modules | ||
| +-- blerg (1.2.5) <---[A] | ||
| +-- bar (1.2.3) <---[B] | ||
| | `-- node_modules | ||
| | +-- baz (2.0.2) <---[C] | ||
| | | `-- node_modules | ||
| | | `-- quux (3.2.0) | ||
| | `-- asdf (2.3.4) | ||
| `-- baz (1.2.3) <---[D] | ||
| `-- node_modules | ||
| `-- quux (3.2.0) <---[E] | ||
| Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are | ||
| installed in foo's `node_modules` folder. | ||
| Even though the latest copy of blerg is 1.3.7, foo has a specific | ||
| dependency on version 1.2.5. So, that gets installed at [A]. Since the | ||
| parent installation of blerg satisfies bar's dependency on `blerg@1.x`, | ||
| it does not install another copy under [B]. | ||
| Bar [B] also has dependencies on baz and asdf, so those are installed in | ||
| bar's `node_modules` folder. Because it depends on `baz@2.x`, it cannot | ||
| re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D], | ||
| and must install its own copy [C]. | ||
| Underneath bar, the `baz -> quux -> bar` dependency creates a cycle. | ||
| However, because bar is already in quux's ancestry [B], it does not | ||
| unpack another copy of bar into that folder. | ||
| Underneath `foo -> baz` [D], quux's [E] folder tree is empty, because its | ||
| dependency on bar is satisfied by the parent folder copy installed at [B]. | ||
| For a graphical breakdown of what is installed where, use `npm ls`. | ||
| ### Publishing | ||
| Upon publishing, npm will look in the `node_modules` folder. If any of | ||
| the items there are not in the `bundledDependencies` array, then they will | ||
| not be included in the package tarball. | ||
| This allows a package maintainer to install all of their dependencies | ||
| (and dev dependencies) locally, but only re-publish those items that | ||
| cannot be found elsewhere. See `package.json(5)` for more information. | ||
| ## SEE ALSO | ||
| * npm-faq(7) | ||
| * package.json(5) | ||
| * npm-install(1) | ||
| * npm-pack(1) | ||
| * npm-cache(1) | ||
| * npm-config(1) | ||
| * npmrc(5) | ||
| * npm-config(7) | ||
| * npm-publish(1) |