Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation for 1.0

  • Loading branch information...
commit c178365094bcb99250fd85c9fc1de541ccbf541a 1 parent b222a0a
@isaacs isaacs authored
View
22 doc/adduser.md
@@ -10,34 +10,20 @@ npm-adduser(1) -- Add a registry user account
Create or verify a user named `<username>` in the npm registry, and
save the credentials to the `.npmrc` file.
-The username, password, and email are read in from prompts. This command
-cannot be scripted. If you think you need to script the creation of new
-users, or the authorization of existing ones, without human intervention,
-please rethink your use case. That's a very bad idea.
+The username, password, and email are read in from prompts.
You may use this command to change your email address, but not username
or password.
+To reset your password, go to <http://admin.npmjs.org/>
+
You may use this command multiple times with the same user account to
authorize on a new machine.
## CONFIGURATION
-### _auth
-
-A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
-
-If your config file is ever corrupted, you can set this manually by doing:
-
- npm adduser
-
### registry
-Default: https://registry.npmjs.org/
+Default: http://registry.npmjs.org/
The base URL of the npm package registry.
-
-### username, _password
-
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`. This is the part before the ":"
View
1  doc/author.md
View
10 doc/build.md
@@ -10,15 +10,9 @@ npm-build(1) -- Build a package
## DESCRIPTION
-This command should almost never need to be run directly. It is an abstraction
-of the functionality shared by both npm-install(1) and npm-link(1).
-
-This command creates the various interwoven links that ensure a package's contents
-are available in the root appropriately, and that its dependencies are linked
-appropriately.
-
-## CONFIGURATION
+This is the plumbing command called by `npm link` and `npm install`.
+It should generally not be called directly.
## SEE ALSO
View
49 doc/cache.md
@@ -10,48 +10,51 @@ npm-cache(1) -- install a package
npm cache ls [<path>]
- npm cache clean [<name>[@<version>]]
+ npm cache clean [<path>]
## DESCRIPTION
* add:
- Access the local cache of package data. This command is primarily
+ Add the specified package to the local cache. This command is primarily
intended to be used internally by npm, but it can provide a way to
add data to the local installation cache explicitly.
- If two arguments are provided, then npm will fetch the data from the
- registry. This allows npm to use the filesystem as a local proxy to
- the registry.
-
* ls:
- Show the data in the cache. Additional arguments are joined together
- in a path-like fashion, but something like `npm cache ls npm/0.1.5` is
- acceptable as well.
+ Show the data in the cache. Argument is a path to show in the cache
+ folder. Works a bit like the `find` program, but limited by the
+ `depth` config.
* clean:
- Delete data out of the cache for a specific package and version, all
- versions of a package, or all data for all packages, depending on the
- arguments supplied.
-
- This can be used if invalid data gets into the cache.
+ Delete data out of the cache folder. If an argument is provided, then
+ it specifies a subpath to delete. If no argument is provided, then
+ the entire cache is cleared.
## DETAILS
-npm stores data for a version of a package in
-`$ROOT/.npm/.cache/<name>/<version>`. Three pieces of data are stored
-in this folder:
+npm stores cache data in `$HOME/.npm`. For each package that is added
+to the cache, three pieces of information are stored in
+`{cache}/{name}/{version}`:
-* package/:
+* .../package/:
A folder containing the package contents as they appear in the tarball.
-* package.json:
+* .../package.json:
The package.json file, as npm sees it, with overlays applied and a _id attribute.
-* package.tgz:
+* .../package.tgz:
The tarball for that version.
+Additionally, whenever a registry request is made, a `.cache.json` file
+is placed at the corresponding URI, to store the ETag and the requested
+data.
+
+Commands that make non-essential registry requests (such as `search` and
+`view`, or the completion scripts) generally specify a minimum timeout.
+If the `.cache.json` file is younger than the specified timeout, then
+they do not make an HTTP request to the registry.
+
## CONFIGURATION
-### root
+### cache
-Default: `$INSTALL_PREFIX/lib/node`
+Default: `$HOME/.npm` on Posix, or `$HOME/npm-cache` on Windows.
-The root folder where packages are installed and npm keeps its data.
+The root cache folder.
View
258 doc/changelog.md
@@ -3,249 +3,47 @@ npm-changelog(1) -- Changes
## HISTORY
-* 0.0.1:
- Lots of sketches and false starts. Abandoned a few times.
+* 0.0
+ Lots of sketches and false starts. Abandoned a few times.
+ Core functionality established.
+ alpha.
-* 0.0.2:
- Install worked mostly. Still promise-based.
-
-* 0.0.3:
- Converted to callbacks.
- Mikeal Rogers wrote a registry for it.
-
-* 0.0.4:
- version dependencies
- link packages
- activation
- lifecycle scripts
- bin linking
- uninstallation
-
-* 0.0.5:
- fix a few bugs in uninstall wrt dependent packages
- fix relative require()for nodejs modules installed with the "bin" field.
- (issue #2)
- update to work with node 0.1.33 (aka net2)
- added publish and tag commands
-
-* 0.0.6:
- set up a public registry
- send content-length with registry PUTs
- adduser command (Mikeal Rogers)
- ini file stuff (Mikeal Rogers)
- env-specific package.json
- added more info to npm's the package.json (bugs, contributors, etc.)
-
-* 0.0.7:
- fixed a few bugs in semver
- refactor documentation
- add "help" command
- add install from registry
- everything else core
- push to beta
-
-* 0.1.0 - 0.1.2:
+* 0.1
push to beta, and announce
- clean up some bugs around lifecycle scripts
- reduce reliance on makefile
- documentation updates
- Fixed DOA bugs
- Removed dependence on ronn
-
-* 0.1.3:
- Changed a few details with configs (fix #5)
- Update adduser and publish to put author info in the data
- Use buffer api for file writes, hopefully fix #4
-
-* 0.1.4 - 0.1.5:
- Fixes for a few more bugs and fix some documentation.
-
-* 0.1.6 - 0.1.7:
- Add cache functionality
- Use couchdb attachments to host tarballs
- Handle odd require.paths more appropriately
- Don't break on install if the man path is missing
- Support publishing or installing a folder or local tarball
-
-* 0.1.8:
- Bugfixes
- Add start, stop, restart, and test commands
-
-* 0.1.9:
- npm list enhancements
- fix the install bug
-
-* 0.1.10:
- More errors found by Ryan Dahl and Kris Zyp
- Better uninstall and list behavior
- Docs for new developers.
- Better tracking of ownership on the registry.
-
-* 0.1.11:
- Martyn Smith found a whole lot of bugs.
- Make publish not die when the tarball is big.
- "make uninstall" support
-
-* 0.1.12 - 0.1.13:
- Fix the downloading bug that was breaking the tarballs
- Update some docs
-
-* 0.1.14 - 0.1.16:
- Fix to stay in sync with node changes
- Put a special tag on link installs
- Modify semver comparison slightly
- add unpublish command
- Use the "drain" event properly for uploads
- Handle thrown errors
- Handle .npmignore
-
-* 0.1.17:
- Stabilization.
-
-* 0.1.18:
- Change a few default configurations
- Add test harness
- Default publish, install, and link to "." if no arguments given
-
-* 0.1.19 - 0.1.20:
- Create a bunch of bugs
- Fix a bunch of bugs
- Some minor speed improvements
-
-* 0.1.21 - 0.1.22:
- Relative paths
- Support comments in package.json
- Add owner name to ls output
- Add "owner" command to manage package owners
- Support hook scripts in `{root}/.npm/.hooks/`
- Initial support for config file relative to node executable
- Support for http proxies
- Documentation updates
-
-* 0.1.23:
- update command - This is huge.
- Rollback for failed installations
- Install dependencies for link packages
- Silently read passwords for adduser
- Cascading configs: cli, env, user, global
- First pass at `npm view` command
-
-* 0.1.24, 0.1.25:
- Fix a bunch of things
- Cleanup, etc.
- help via --help, -h, or -?
-
-* 0.1.26:
- "modules" hash in package.json (Alex K. Wolfe)
- Better "restart" command (Alex K Wolfe)
- Work on Cygwin
- Remove link packages properly
- Make several commands more parallel
-
-* 0.1.27:
- Man pages handled with the "man" entry, or a "man" directory
- Install man pages in the "manroot" config dir
- Control log output with the "loglevel" config
- Support a "bin" directory of executables that get auto-linked
- Un-deprecate the "lib" directory.
- Bug killing
- Split up the tar usage so it works on Solaris
+ documentation, caching, more robust script support
+ ownership tracking in the registry (no more admin party!)
+ more robust config and option parsing
+ stabilize semver semantics
+ tests
+ update command
bundle command
- rebuild command
+ Rollback for failed installations
+ Solaris and Cygwin support
-* 0.2.0:
- Lots more bug killing
- Various fixes found during the Node Knockout extravaganza
- Change all "name-version" things to be "name@version"
+* 0.2
First allegedly "stable" release.
-
-* 0.2.1:
- Minor updates and bugfixes
-
-* 0.2.2:
- Update "help" to work on Solaris
- Remove updated packages that don't have dependencies.
- Allow implied suffixes on .js bins
- Fix an "adduser" bug
-
-* 0.2.3:
- Lots of documentation tweaks and cleanup
- Support || in version ranges
-
-* 0.2.4:
- Contribution party!
- Better list whitespace
- Lots of config happiness
- Ignore all major SCM folders by default
- Handle proxies and hostnames with ports
- Better Bundling
- Add 'outdated' command
- Better handling of "engines" field
-
-* 0.2.5:
+ Various fixes found during the Node Knockout extravaganza
+ Minor updates and bugfixes
+ more complete semver functionality
Make npm OK to use programmatically (Charlie Robbins)
-
-* 0.2.6:
- More programmatic updates
recursive package removal
- tab completion
-
-* 0.2.7 - 0.2.8:
- Bundle treated like a first-class citizen, and simplified
- Many bug fixes
-
-* 0.2.9:
- npm version command
+ tab completion (Evan Meagher)
shasums on all tarballs
- More portable tar option usage
- Much beefed up bundle command
- Deep view command
-
-* 0.2.10:
- npm edit command
- various stability bugfixes.
-
-* 0.2.11:
- ~> and 1.2.x style version ranges
- complete tab completion: see `npm help completion` (Evan Meagher)
explore command: see `npm help explore`
docs command: see `npm help docs`
- keywords and description in `npm ls`
- Frequently asked questions at `npm help faq`
-
-* 0.2.12:
- Various bugfixes (0.2.11 was big, broke some stuff)
- `npm faq` command (wrapper for `npm help faq`)
-
-* 0.2.13:
- Merry Xmas!
- Config setting on the command line with grace and gusto
- Portability and stability fixes.
- Mostly sort of works with Homebrew-installed nodejs.
-
-* 0.2.14:
- A little bit of documentation overhaul.
- Support for `"<name>":"<url>"` for dependencies.
- Fix for "unpublish" regression.
- Support for "files" array.
- Dependency info in lifecycle scripts.
- More data validation.
-
-* 0.2.15 - 0.2.17:
- Added "--force" for publish
- Support argless "unpublish" and "uninstall" in package dirs
- Document future stuff
- Remove support for "modules" hash
- Read package defaults when reading json
+ Frequently asked questions at `npm faq`
+ xmas easter egg
+ work with homebrew nodejs
+ Support for `"<name>":"<url>"` for dependencies.
-* 0.3.0:
- More correct permission/uid handling. (Sudo is now encouraged!)
+* 0.3
+ More correct permission/uid handling. (Sudo now encouraged!)
Require node 0.4.0
Separate semver out into a separate utility.
Packages without "main" modules don't export modules.
+ Remove support for invalid JSON (since node doesn't support it)
No shims! (Still has symlinks, though)
-* 0.3.1-0.3.5:
- Ease up on permission forcing.
- Fix bugs around proxy handling.
- Remove support for invalid JSON (since node doesn't support it)
+* 1.0
+ Simplify configuration greatly.
+ Install locally (bundle by default)
View
25 doc/completion.md
@@ -1,22 +1,19 @@
npm-completion(1) -- Tab Completion for npm
===========================================
-## DESCRIPTION
+## SYNOPSIS
-You should set up tab completion for npm if you haven't already.
-There are a few ways to do this:
+ npm completion >> ~/.bashrc
+ npm completion >> ~/.zshrc
-1. Add `. /path/to/npm-completion.sh` to your ~/.bashrc file. OR:
-2. Create a symlink like this if you have automatic bash completion set up:
- `ln - /path/to/npm-completion.sh /etc/bash-completion.d/npm`
- or, perhaps:
- `ln - /path/to/npm-completion.sh /usr/local/etc/bash-completion.d/npm`
+## DESCRIPTION
-If you're using a non-bash shell (like zsh or ksh) then this might not work.
+Sets up a function that enables tab-completion in all npm commands.
-To get the path to the npm-completion.sh file, use `npm explore npm pwd`.
+You may of course also pipe the relevant script to a file such as
+`/usr/local/etc/bash_completion.d/npm` if you have a system that will
+read that file for you.
-It's a very new feature, and it would be great to get feedback on it.
-Hopefully, I'll be able to work out a way to install the completion script
-automatically. If you have any ideas about how that should work, then please
-share them.
+When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the
+environment, `npm completion` acts in "plumbing mode", and outputs
+completions based on the arguments.
View
401 doc/config.md
@@ -35,8 +35,6 @@ npm gets its configuration values from 5 sources, in this priority:
This is a set of configuration parameters that are internal to npm, and are
defaults if nothing else is specified.
-
-
## Sub-commands
Config supports the following sub-commands:
@@ -47,13 +45,13 @@ Config supports the following sub-commands:
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. (NOTE: All the other npm logging is done to
-stderr, so pipes should work properly, and you can do `npm get key 2>/dev/null`
-to print out JUST the config value.)
+Echo the config value to stdout.
### list
@@ -71,7 +69,45 @@ Deletes the key from all configuration files.
npm config edit
-Opens the config file in an editor. Use the `--global` flag to edit the global config.
+Opens the config file in an editor. Use the `--global` flag to edit the
+global config.
+
+## Shorthands and Other CLI Niceties
+
+The following shorthands are parsed on the command-line:
+
+* `-v`: `--version`
+* `-h`, `-?`, `--help`, `-H`: `--usage`
+* `-s`, `--silent`: `--loglevel silent`
+* `-d`: `--loglevel info`
+* `-dd`, `--verbose`: `--loglevel verbose`
+* `-ddd`: `--loglevel silly`
+* `-g`: `--global`
+* `-l`: `--long`
+* `-p`, `--porcelain`: `--parseable`
+* `-reg`: `--registry`
+* `-v`: `--version`
+* `-f`: `--force`
+* `-l`: `--long`
+* `-desc`: `--description`
+* `ll` and `la` commands: `ls --long`
+
+If the specified configuration param resolves unambiguously to a known
+configuration parameter, then it is expanded to that configuration
+parameter. For example:
+
+ npm ls --par
+ # same as:
+ npm ls --parseable
+
+If multiple single-character shorthands are strung together, and the
+resulting combination is unambiguously not some other configuration
+param, then it is expanded to its various component pieces. For
+example:
+
+ npm ls -gpld
+ # same as:
+ npm ls --global --parseable --long --loglevel info
## Per-Package Config Settings
@@ -94,292 +130,303 @@ then the user could change the behavior by doing:
## Config Settings
-### auto-activate
+### browser
-Default: true
+* Default: OS X: `"open"`, others: `"google-chrome"`
+* Type: String
-Automatically activate a package after installation, if there is not an active
-version already. Set to "always" to always activate when installing.
+The browser that is called by the `npm docs` command to open websites.
-### rebuild-bundle
+### cache
-Default: true
-
-Set to some truish value to rebuild bundled dependencies after
-installation.
+* Default: Windows: `~/npm-cache`, Posix: `~/.npm`
+* Type: path
-### recursive
+The location of npm's cache directory. See `npm help cache`
-Default: false
-
-Set to some truish value to recursively remove dependent packages. For
-example if foo depends on bar, and bar depends on baz, then:
-
- npm uninstall baz --recursive
+### color
-will remove baz, bar, and foo.
+* Default: true
+* Type: Boolean or `"always"`
-### loglevel
+If false, never shows colors. If `"always"` then always shows colors.
+If true, then only prints color codes for tty file descriptors.
-Default: "info"
+### depth
-The log level to show.
+* Default: Infinity
+* Type: Number
-Each level maps to a numeric value, above which all logs must pass to be
-seen. So, setting it to "warn" shows "win", "error" and "warn" messages.
+The depth to go when recursing directories for `npm ls` and
+`npm cache ls`.
-The log levels:
+### description
-* silent: Show no output. Nothing. If there is output on stderr, it's
- because something is broken.
-* win: Show the "npm ok" or "npm not ok", but that's all.
-* error: Errors, usually with a stack trace.
-* warn: Things that you should probably be aware of.
-* info: Helpful info.
-* silly: Not-helpful info. (Lots of dumping whole objects and such.)
+* Default: true
+* Type: Boolean
-Note that output to stdout is always printed. This setting just modifies
-what's logged to stderr.
+Whether or not to show the description in `npm search`
-### update-dependents
+### dev
-Default: true
+* Default: false
+* Type: Boolean
-Automatically update a package's dependencies after installation, if it is the
-newest version installed. Set to "always" to update dependents when a new
-version is installed, even if it's not the newest.
+Whether or not to install `dev-dependencies` along with packages.
-### root
+Note that `dev-dependencies` are also installed if the `npat` flag is
+set.
-Default: `$INSTALL_PREFIX/lib/node`
+### editor
-The root folder where packages are installed and npm keeps its data.
+* Default: `EDITOR` environment variable if set, or `"vi"`
+* Type: path
-### binroot
+The command to run for `npm edit` or `npm config edit`.
-Default: `$INSTALL_PREFIX/bin`
+### force
-The folder where executable programs are installed.
+* Default: false
+* Type: Boolean
-Set to "false" to not install executables
+Makes various commands more forceful.
-### manroot
+* lifecycle script failure does not block progress.
+* publishing clobbers previously published versions.
+* skips cache when requesting from the registry.
+* prevents checks against clobbering non-npm files.
-Default: $INSTALL_PREFIX/share/man
+### global
-The folder where man pages are installed.
+* Default: false
+* Type: Boolean
-Set to "false" to not install man pages.
+Operates in "global" mode, so that packages are installed into the
+`prefix` folder instead of the current working directory. See
+`npm help global` for more on the differences in behavior.
-### registry
+* packages are installed into the `prefix/node_modules` folder, instead of the
+ current working directory.
+* bin files are linked to `prefix/bin`
+* man pages are linked to `prefix/share/man`
-Default: https://registry.npmjs.org/
+### globalconfig
-The base URL of the npm package registry.
+* Default: {prefix}/etc/npmrc
+* Type: path
-### _auth
+The config file to read for global config options.
-A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
+### group
-If your config file is ever corrupted, you can set this manually by doing:
+* Default: GID of the current process
+* Type: String or Number
- npm adduser
+The group to use when running package scripts in global mode as the root
+user.
-### username, _password
+### gzipbin
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`. This is the part before the ":"
+* Default: "gzip"
+* Type: path
-### proxy
+The gzip binary
-If proxy is available, then npm will access the registry via
-the proxy server.
+### logfd
-Example:
+* Default: stderr file descriptor
+* Type: Number or Stream
- proxy = http://user:password@proxy-server:8080
+The location to write log output.
-### tag
+### loglevel
-Default: latest
+* Default: "warn"
+* Type: String
+* Values: "silent", "win", "error", "warn", "info", "verbose", "silly"
-If you ask npm to install a package and don't tell it a specific version, then
-it will install the specified tag.
+What level of logs to report. On failure, *all* logs are written to
+`npm-debug.log` in the current working directory.
-Note: this has no effect on the npm-tag(1) command.
+### long
-### userconfig
+* Default: false
+* Type: Boolean
-The default user configuration file is process.env.HOME+"/.npmrc".
+Whether or not to show extended information in `npm ls`
-Note that this must be provided either in the cli or env settings. Once the
-userconfig is read, it is irrelevant.
+### node-version
-### globalconfig
+* Default: process.version
+* Type: semver
-The default global configuration file is resolved based on the location of the
-node executable. It is process.execPath+"/../../etc/npmrc". In the canonical
-NodeJS installation with `make install`, this is `/usr/local/etc/npmrc`. If you
-put the node binary somewhere else (for instance, if you are using nvm or
-nave), then it would be resolved relative to that location.
+The node version to use when checking package's "engines" hash.
-Note that this must be provided in the cli, env, or userconfig settings. Once
-the globalconfig is read, this parameter is irrelevant.
+### npat
-### global
+* Default: false
+* Type: Boolean
-If set to some truish value (for instance, by being the last cli flag or being
-passed a literal `true` or `1`), and the `npm config set` param is being
-called, then the new configuration paramater is written global config file.
-Otherwise, they are saved to the user config file.
+Whether or not to run tests on installation and report results to the
+`npaturl`.
-### dev
+### npaturl
-If set to a truish value, then it'll install the "devDependencies" as well as
-"dependencies" when installing a package.
+* Default: Not yet implemented
+* Type: url
-Note that devDependencies are *always* installed when linking a package.
+The url to report npat test results.
-### tar
+### onload-script
-Default: env.TAR or "tar"
+* Default: false
+* Type: path
-The name of a GNU-compatible tar program on your system.
+A node module to `require()` when npm loads. Useful for programmatic
+usage.
-### gzip
+### outfd
-Default: env.GZIPBIN or "gzip"
+* Default: standard output file descriptor
+* Type: Number or Stream
-The name of a GNU-compatible gzip program on your system.
+Where to write "normal" output. This has no effect on log output.
-### usage
+### parseable
-If set to `true`, then this will tell help to print out the short usage statement
-instead of the long manpage type thing.
+* Default: false
+* Type: Boolean
-This is set automatically if you invoke help like `npm command -?`.
+Whether or not to output parseable results from commands that write to
+standard output.
-### viewer
+### prefix
-Default: "man"
+* Default: node's process.installPrefix
+* Type: path
-The program to use to view help content. Set to "woman" to use the emacs troff viewer
-by that name.
+The location to install global items. If set on the command line, then
+it forces non-global commands to run in the specified folder.
-### _exit
+### proxy
-Default: true
+* Default: "HTTP_PROXY" or "http_proxy" environment variable, or null
+* Type: url
-Whether or not to exit the process when the command is finished. When
-using npm programmatically, it's a good idea to set this to `false`
-explicitly.
+A proxy to use for outgoing http requests.
-### logfd
+### rebuild-bundle
-Default: Standard Error FD (2)
+* Default: true
+* Type: Boolean
-The file descriptor (integer) or stream object where npm will write log
-messages.
+Set to some truish value to rebuild bundled dependencies after
+installation.
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
+### registry
-### outfd
+* Default: https://registry.npmjs.org/
+* Type: url
-Default: Standard Output FD (1)
+The base URL of the npm package registry.
-The file descriptor (integer) or stream object where npm will write
-"normal" output. For instance, the `ls` and `view` commands write their
-output here.
+### searchopts
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
+* Default: ""
+* Type: String
-### color
+Space-separated options that are always passed to search.
-Default: true
+### searchexclude
-Set to false to disable colorized output.
+* Default: ""
+* Type: String
-In versions of node that expose the `isatty` function, npm will never
-write colorized output to a non-terminal file descriptor.
+Space-separated options that limit the results from search.
-### tmproot
+### shell
-Default: env.TMPDIR or "/tmp"
+* Default: SHELL environment variable, or "bash"
+* Type: path
-The folder where temporary files should be placed.
+The shell to run for the `npm explore` command.
-npm creates a subfolder whenever it is run, and attempts to delete it
-afterwards.
+### tag
-### force
+* Default: latest
+* Type: String
-Default: false
+If you ask npm to install a package and don't tell it a specific version, then
+it will install the specified tag.
-Set to a truish value to force uninstalling packages, even if they have
-dependents.
+Also the tag that is added to the package@version specified by the `npm
+tag` command, if no explicit tag is given.
-Note that setting `recursive` is safer, because forcing uninstall can
-create orphan packages that no longer function properly.
+### tar
-### editor
+* Default: TAR environment variable, or "tar"
+* Type: path
-Default: env.EDITOR
+The tar executable
-The program to use to edit files.
+### tmp
-### listexclude
+* Default: TMPDIR environment variable, or "/tmp"
+* Type: path
-Default: null
+Where to store temporary files and folders. All temp files are deleted
+on success, but left behind on failure for forensic purposes.
-A whitespace separated list of strings which *prevent* items from being
-shown to `npm ls`.
+### unsafe-perm
-For example, `npm ls installed --listexclude zombie` will show all
-installed packages *except* zombie.
+* Default: false if running as root, true otherwise
+* Type: Boolean
-### listopts
+Set to true to suppress the UID/GID switching when running package
+scripts. If set explicitly to false, then installing as a non-root user
+will fail.
-Default: ""
+### usage
-A whitespace-separated list of extra args that are always passed to npm ls
+* Default: false
+* Type: Boolean
-For example: `listopts = remote`
+Set to show short usage output (like the -H output)
+instead of complete help when doing `npm help`.
-`npm ls`
+### user
-The output here will always filter by remote
+* Default: "nobody"
+* Type: String or Number
-### must-install
+The UID to set to when running package scripts as root.
-Default: true
+### username
-Set to false to not install over packages that already exist. By
-default, `npm install foo` will fetch and install the latest version of
-`foo`, even if it matches a version already installed.
+* Default: null
+* Type: String
-## description
+The username on the npm registry. Set with `npm adduser`
-Default: true
+### userconfig
-Show the package description in npm ls.
+* Default: ~/.npmrc on Posix, or ~/npm-config on Windows
+* Type: path
-## node-version
+The location of user-level configuration settings.
-Default: `process.version` from the node environment
+### version
-An effective version of node to use when checking for "engines"
-compliance.
+* Default: false
+* Type: boolean
-Set to null or false to suppress engine checking altogether.
+If true, output the npm version and exit successfully.
-## onload-script
+Only relevant when specified explicitly on the command line.
-Default: false
+### viewer
-A script to run when npm loads. Use this to hook into various events in
-the npm flow in a programmatic way, even when using npm from the command
-line.
+* Default: "man"
+* Type: path
-If false, then don't do any onload stuff.
+The program to use to view help content.
View
9 doc/deprecate.md
@@ -17,12 +17,3 @@ something like this:
Note that you must be the package owner to deprecate something. See the
`owner` and `adduser` help topics.
-
-## CONFIGURATION
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
View
4 doc/docs.md
@@ -9,6 +9,4 @@ npm-docs(1) -- Docs for a package in a web browser maybe
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, which defaults to `"open"` because that works on a mac.
-
-This is an experimental command. It may disappear or change radically.
+config param.
View
18 doc/edit.md
@@ -13,18 +13,6 @@ configured as the npm `editor` config -- see `npm help config`.)
After it has been edited, the package is rebuilt so as to pick up any
changes in compiled packages.
-Note: If you're finding yourself using this a lot, it's probably better
-to use `npm link` instead. However, it is extremely handy when used in
-conjunction with `npm bundle`.
-
-For instance, you can do `npm bundle install connect` to install connect
-into your package, and then `npm bundle edit connect` to make a few
-changes to your locally bundled copy.
-
-## CONFIGURATION
-
-### editor
-
-Default: env.EDITOR
-
-The program to use to edit files.
+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.
View
46 doc/faq.md
@@ -16,32 +16,37 @@ I don't know yet.
Read the error output, and if you can't figure out what it means,
do what it says and post a bug with all the information it asks for.
-If there doesn't seem to be enough output for your liking, run the
-command with `--loglevel verbose` or if you're really brave, `--loglevel
-silly`.
+## Where does npm put stuff?
-## How do I make npm less noisy?
+See `npm help folders`
-`npm config set loglevel error`
+## I installed something globally, but I can't `require()` it
-You can also set it to `win` or `silent` for even more quietness.
+Install it locally.
+
+## I don't wanna.
+
+Ok, then do this:
+
+ echo 'export NODE_PATH="'$(npm root -g)'"' >> ~/.bashrc
+ . ~/.bashrc
## How do I list installed packages?
-`npm ls installed`
+`npm ls`
If you just want to see the names, and not all the registry data, you
can do: `npm ls installed --no-registry` to turn off the registry.
## How do I search for packages?
-`npm ls`
+`npm search`
Arguments are greps. `npm ls jsdom` shows jsdom packages.
## How do I update npm?
-`npm update npm`
+`npm update npm -g`
You can also update all outdated packages by doing `npm update` without
any arguments.
@@ -78,19 +83,8 @@ awesomely handy.
## Can I list a url as a dependency?
-No.
-
-If you need to depend on something that isn't published, or a package
-that is published, but which you've modified slightly, you can do this.
-
-The correct way is to do the following:
-
-* add a `"name":"version"` entry to your package.json file.
-* `npm bundle install <pkg>` where `<pkg>` is a url or path to your
- custom unpublished package.
-
-When installing your package, npm will skip over any dependencies that
-are bundled.
+Yes. It should be a url to a gzipped tarball containing a single folder
+that has a package.json in its root.
## OK, but can I list a git repo as a dependency?
@@ -106,7 +100,7 @@ lot of use cases, and is very easy to maintain.
## How do I symlink to a dev folder so that I don't have to keep re-installing?
-`npm link`
+See `npm help link`
## The package registry website. What is that exactly?
@@ -123,8 +117,7 @@ https reliably.
## I forgot my password, and can't publish. How do I reset it?
-Email <i@izs.me> from the email address that you signed up with. Then
-wait a day or two maybe.
+Go to <http://admin.npmjs.org/> to reset it.
## I get ECONNREFUSED a lot. What's up?
@@ -132,7 +125,8 @@ Either the registry is down, or node's DNS isn't able to reach out.
This happens a lot if you don't follow *all* the steps in the Cygwin
setup doc.
-To check if the registry is down, open up <http://registry.npmjs.org/>
+To check if the registry is down, open up
+<http://registry.npmjs.org/-/short>
in a web browser. This will also tell you if you are just unable to
access the internet for some reason.
View
184 doc/folders.md
@@ -3,89 +3,171 @@ npm-folders(1) -- Folder Structures Used by npm
## DESCRIPTION
-Node modules and metadata live
-in the `root` setting. Check `npm help config` for more
-on configuration options.
+npm puts various things on your computer. That's its job.
-`root/foo` Symlink to the active version's module folder.
+This document will tell you what it puts where.
-`root/foo@1.0.0/` Node modules for the foo package.
+### prefix Configuration
-`root/foo@1.0.0/{module-name}.js` Generated shim corresponding to a module
-defined in the modules option. The module shim requires
-`root/.npm/foo/1.0.0/package/{module-path}.js`
+The `prefix` config defaults to node's `process.installPrefix`. On most
+systems, this is `/usr/local`.
-The `main` script is implemented by creating an `index.js` file in this folder.
+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.
-`root/.npm/foo` is where the stuff for package `foo` would go.
+### Node Modules
-`root/.npm/foo/1.0.0/package` the contents of the tarball containing foo
-version 1.0.0
+Packages are droped 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/path/to/sub/module")` to load other modules.
-`root/.npm/foo/1.0.0/main.js` Generated file that exports the `main` module in
-foo. This is a shim, not a symbolic link, so that relative paths will work
-appropriately.
+If you wish to install node modules globally which can be loaded via
+`require()` from anywhere, then add the `prefix/node_modules` folder to
+your NODE_PATH environment variable.
-`root/.npm/foo/active` symlink to the active version.
+### Executables
-`root/.npm/foo/1.0.0/node_modules` links to the modules that foo depends upon.
-This is loaded into the require path first in the foo shims.
+When in global mode, executables are linked into `prefix/bin`.
-`root/.npm/foo/1.0.0/dependson` links to the package folders that foo depends
-on. This is here so that npm can access those packages programmatically.
+When in local mode, executables are linked into
+`prefix/node_modules/.bin`.
-`root/.npm/foo/1.0.0/dependents` links to the packages that depend upon foo.
+### Man Pages
-`root/.npm/.cache` the cache folder.
+When in global mode, man pages are linked into `prefix/share/man`.
-`root/.npm/.cache/foo/1.0.0/package.json` the parsed package.json for foo@1.0.0
+When in local node, man pages are not installed.
-`root/.npm/.cache/foo/1.0.0/package.tgz` the tarball of foo@1.0.0
+### Cache
-`root/.npm/.cache/foo/1.0.0/package` the untouched pristine copy of foo@1.0.0
+See `npm help cache`. Cache files are stored in `~/.npm` on Posix, or
+`~/npm-cache` on Windows.
-Executables are installed to the folder specified by the `binroot` config.
+This is controlled by the `cache` configuration param.
-`binroot/foo` Symlink to the active version of the "foo" executable.
+### Temp Files
-`binroot/foo@1.0.0` An executable for foo at version 1.0.0. Either a
-symbolic link or a shim to a file in the foo package.
+Temporary files are stored by default in the folder specified by the
+`tmp` config, which defaults to either the TMPDIR environment
+variable, or `/tmp`.
-Man pages are installed to the folder specified by the `manroot` config.
-Man pages named something other than the package name are prefixed with
-the package name.
+Temp files are given a unique folder under this root for each run of the
+program, and are deleted upon successful exit.
-`manroot/man1/foo.1` Symlink to the section 1 manpage for the active
-version of foo.
+## More Information
-`manroot/man1/foo@1.0.0.1` Section 1 man page for foo version 1.0.0
+When you run `npm install foo@1.2.3` it downloads and builds the
+package, and then, if there is a package.json file in the current
+working directory, it copies it to `$PWD/node_modules/foo`, so that your
+current package will get it when you do `require("foo")`.
-`manroot/man8/foo-bar.8` Symlink to a section 8 manpage for the active
-version of foo.
+When this is done, it also installs all of foo's dependencies to
+`./node_modules/foo/node_modules/`, so that it will get its dependencies
+appropriately when it calls `require()`. If foo depends on bar, and bar
+depends on baz, then there will also be a
+`./node_modules/foo/node_modules/bar/node_modules/baz`, and so on.
-`manroot/man8/foo-bar@1.0.0.8` A section 8 manpage for foo version
-1.0.0.
+If there is not a package.json in the current working directory, then
+npm walks up the working dir parent paths looking for a package.json,
+indicating the root of a package, or a node_modules folder,
+indicating an npm package deployment location, and then take the party to that
+location. This behavior may be suppressed by setting the `seek-root`
+config value to false.
-## CONFIGURATION
+If no package root is found, then a global installation is performed.
+The global installation may be supressed by setting the `global`
+configuration to false, in which case, the install will fail.
-### root
+### Global Installation
-Default: `$INSTALL_PREFIX/lib/node`
+If the `global` configuration is set to true, or if it is not explicitly
+set false and no suitable node_modules folder was found, then npm will
+install packages "globally".
-The root folder where packages are installed and npm keeps its data.
+This means that the module contents are symlinked (or, on windows,
+copied) from `root/<name>/<version>/package` to
+`root/node_modules/<name>`.
-### binroot
+### Cycles, Conflicts, and Folder Parsimony
-Default: `$INSTALL_PREFIX/bin`
+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.
-The folder where executable programs are installed.
+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.
-Set to "false" to not install executables
+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.
-### manroot
+Another optimization can be made by installing dependencies at the
+highest level possible, below the localized "target" folder.
-Default: $INSTALL_PREFIX/share/man
+For example, consider this dependency graph:
-The folder where man pages are installed.
+ foo
+ +-- bar@1.2.3
+ | +-- baz@2.x
+ | | `-- quux@3.x
+ | | `-- bar@1.2.3 (cycle)
+ | `-- asdf@*
+ `-- baz@1.2.3
+ `-- quux@3.x
+ `-- bar
-Set to "false" to not install man pages.
+In this case, we might expect a folder structure like this:
+
+ foo
+ +-- node_modules
+ +-- bar (1.2.3)
+ | +-- node_modules
+ | | `-- baz (2.0.2)
+ | | `-- node_modules
+ | | `-- quux (3.2.0)
+ | `-- asdf (2.3.4)
+ `-- baz (1.2.3)
+ `-- node_modules
+ `-- quux (3.2.0)
+ `-- node_modules
+ `-- bar (1.2.3)
+ `-- node_modules
+ `-- asdf (2.3.4)
+
+Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are
+installed in foo's node_modules folder.
+
+Bar has dependencies on baz and asdf, so those are installed in bar's
+node_modules folder. Baz has a dependency on quux, so that is installed
+in its node_modules folder.
+
+Underneath bar, the `baz->quux->bar` dependency creates a cycle.
+However, because `bar` is already in `quux`'s ancestry, it does not
+unpack another copy of bar into that folder.
+
+Similarly, underneath `foo->baz`, the same cycle is gradually prevented
+because `bar`'s `quux` dependency is satisfied by its parent folder.
+
+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 on the "dependencies" or "devDependencies" list,
+and 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.
View
100 doc/install.md
@@ -3,6 +3,7 @@ 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>
@@ -13,8 +14,12 @@ npm-install(1) -- install a package
## DESCRIPTION
-This command installs a package, and any packages that it depends on. It
-resolves circular dependencies by talking to the npm registry.
+This command installs a package, and any packages that it depends on.
+
+* npm install (in package directory):
+ Install the dependencies in the local node_modules folder.
+
+ In global mode, it is the same as `npm install $PWD`
* npm install `<tarball file>`:
Install a package that is sitting on the filesystem. Note: if you just want
@@ -37,8 +42,8 @@ resolves circular dependencies by talking to the npm registry.
npm install http://github.com/waveto/node-crypto/tarball/v0.0.5
* npm install `<name>`:
- Do a `<name>@<tag>` install, where `<tag>` is the "tag" config from either your
- .npmrc file, or the --tag argument on the command line.
+ Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
+ `npm help config`)
Example:
@@ -72,97 +77,18 @@ resolves circular dependencies by talking to the npm registry.
npm install sax@">=0.1.0 <0.2.0"
-You may combine multiple arguments, and even multiple types of arguments. For example:
+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.
+The `--force` argument will force npm to fetch remote resources even if a
+local copy exists on disk.
npm install sax --force
-## CONFIGURATION
-
-### root
-
-Default: `$INSTALL_PREFIX/lib/node`
-
-The root folder where packages are installed and npm keeps its data.
-
-### binroot
-
-Default: `$INSTALL_PREFIX/bin`
-
-The folder where executable programs are installed.
-
-Set to "false" to not install executables
-
-### manroot
-
-Default: $INSTALL_PREFIX/share/man
-
-The folder where man pages are installed.
-
-Set to "false" to not install man pages.
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
-### tag
-
-Default: latest
-
-If you ask npm to install a package and don't tell it a specific version, then
-it will install the specified tag.
-
-Note: this has no effect on the npm-tag(1) command.
-
-### dev
-
-If set to a truish value, then it'll install the "devDependencies" as well as
-"dependencies" when installing a package.
-
-Note that devDependencies are *always* installed when linking a package.
-
-### tar
-
-Default: env.TAR or "tar"
-
-The name of a GNU-compatible tar program on your system.
-
-### gzip
-
-Default: env.GZIPBIN or "gzip"
-
-The name of a GNU-compatible gzip program on your system.
-
-### must-install
-
-Default: true
-
-Set to false to not install over packages that already exist. By
-default, `npm install foo` will fetch and install the latest version of
-`foo`, even if it matches a version already installed.
-
-### auto-activate
-
-Default: true
-
-Automatically activate a package after installation, if there is not an active
-version already. Set to "always" to always activate when installing.
-
-### update-dependents
-
-Default: true
-
-Automatically update a package's dependencies after installation, if it is the
-newest version installed. Set to "always" to update dependents when a new
-version is installed, even if it's not the newest.
-
## SEE ALSO
* npm-build(1)
View
4 doc/json.md
@@ -387,6 +387,10 @@ is set. This flag is set automatically when doing `npm link`, and can
be managed like any other npm configuration param. See `npm help
config` for more on the topic.
+## bundledDependencies
+
+Array of package names that will be bundled when publishing the package.
+
## engines
Packages/1.0 says that you can have an "engines" field with an array of engine
View
37 doc/link.md
@@ -3,28 +3,33 @@ npm-link(1) -- Symlink a package folder
## SYNOPSIS
- npm link <folder>
+ npm link (in package folder)
+ npm link <pkgname>
+
## DESCRIPTION
-This will link a source folder into npm's registry using a symlink, and then
-build it according to the package.json file in that folder's root. This is
-handy for installing your own stuff, so that you can work on it and test it
-iteratively without having to continually rebuild.
+Package linking is a two-step process.
-## Linked Package Version
+First, `npm link` in a package folder will create a globally-installed
+symbolic link from `prefix/package-name` to the current folder.
-When linking a package folder, npm doesn't use the version in the
-package.json file. Instead, it creates a "fake" version number of:
+Next, in some other location, `npm link package-name` will create a
+symlink from the local `node_modules` folder to the global symlink.
- "9999.0.0-LINK-" + hash(folder)
+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.
-This way, linking the same folder will always result in the same version
-number, even if you bump the version in the package.json file. The
-extremely high major version ensures that it will always be considered
-the "highest" version, since it is a development bleeding-edge thing.
+For example:
-## CONFIGURATION
+ 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
-See the config section of `npm help install`. The `dev` configuration
-setting is always set to `true` when doing a link install.
+Now, any changes to ~/projects/node-redis will be reflected in
+~/projects/node-bloggy/node_modules/redis/
View
64 doc/list.md
@@ -1,70 +1,36 @@
-npm-list(1) -- List installed packages
+npm-ls(1) -- List installed packages
======================================
## SYNOPSIS
npm list
npm ls
+ npm la
+ npm ll
## DESCRIPTION
This command will print to stdout all the versions of packages that are
-either installed or available in the registry, with their tags and whether
-or not they're active and/or stable.
+installed, as well as their dependencies, in a tree-structure.
-To filter a single package or state, you can provide words to filter on
-and highlight (if appropriate). For instance, to see all the stable
-packages, you could do this:
+It does not take arguments.
- npm ls stable
+It will print out extraneous, missing, and invalid packages.
-Another common usage is to find the set of all packages that are
-installed. This can be accomplished by doing this:
-
- npm ls installed
+When run as `ll` or `la`, it shows extended information by default.
## CONFIGURATION
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
-### listopts
-
-Default: ""
-
-A whitespace-separated list of extra args that are always passed to npm ls
-
-For example: `listopts = remote`
-
-`npm ls`
-
-The output here will always filter by remote
-
-### description
-
-Default: true
-
-Show the package description in npm ls.
-
-### outfd
-
-Default: Standard Output FD (1)
-
-The file descriptor (integer) or stream object where npm will write
-"normal" output. For instance, the `ls` and `view` commands write their
-output here.
+### long
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
+* Default: false
+* Type: Boolean
-### color
+Show extended information.
-Default: true
+### parseable
-Set to false to disable colorized output.
+* Default: false
+* Type: Boolean
-In versions of node that expose the `isatty` function, npm will never
-write colorized output to a non-terminal file descriptor.
+Show parseable output instead of tree view.
View
7 doc/npm.md
@@ -24,9 +24,8 @@ You probably got npm because you want to install stuff.
Use `npm install blerg` to install the latest version of "blerg". Check out
`npm help install` for more info. It can do a lot of stuff.
-Use the `npm ls` command to show everything that's available.
-Use `npm ls installed` to show everything you've installed.
-`npm help ls` will tell you more.
+Use the `npm search` command to show everything that's available.
+Use `npm ls` to show everything you've installed.
## DEVELOPER USAGE
@@ -107,7 +106,7 @@ When you find issues, please report them:
<npm-@googlegroups.com>
Be sure to include *all* of the output from the npm command that didn't work
-as expected.
+as expected. The `npm-debug.log` file is also helpful to provide.
You can also look for isaacs in #node.js on irc://irc.freenode.net. He
will no doubt tell you to put the output in a gist or email.
View
28 doc/outdated.md
@@ -9,31 +9,3 @@ npm-outdated(1) -- Check for outdated packages
This command will check the registry to see if any (or, specific) installed
packages are currently outdated.
-
-## CONFIGURATION
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
-### tag
-
-Default: latest
-
-If you ask npm to install a package and don't tell it a specific version, then
-it will install the specified tag.
-
-Note: this has no effect on the npm-tag(1) command.
-
-### outfd
-
-Default: Standard Output FD (1)
-
-The file descriptor (integer) or stream object where npm will write
-"normal" output. For instance, the `ls` and `view` commands write their
-output here.
-
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
View
32 doc/owner.md
@@ -23,38 +23,6 @@ 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.
-## CONFIGURATION
-
-### outfd
-
-Default: Standard Output FD (1)
-
-The file descriptor (integer) or stream object where npm will write
-"normal" output. For instance, the `ls` and `view` commands write their
-output here.
-
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
-### _auth
-
-A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
-
-If your config file is ever corrupted, you can set this manually by doing:
-
- npm adduser
-
-### username, _password
-
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`. This is the part before the ":"
-
## SEE ALSO
* npm-publish(1)
View
10 doc/prefix.md
@@ -0,0 +1,10 @@
+npm-prefix(1) -- Display prefix
+===============================
+
+## SYNOPSIS
+
+ npm prefix
+
+## DESCRIPTION
+
+Print the prefix to standard out.
View
15 doc/prune.md
@@ -0,0 +1,15 @@
+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.
View
10 doc/publish.md
@@ -19,15 +19,7 @@ Publishes a package to the registry so that it can be installed by name.
with a package.json file inside.
Fails if the package name and version combination already exists in
-the registry.
-
-## CONFIGURATION
-
-See `npm help registry`
-
-Also, the `force` configuration param will cause it to unpublish an
-existing package, so that it can be published over. Please use with
-caution!
+the registry. Overwrites when the "--force" flag is set.
## SEE ALSO
View
8 doc/rebuild.md
@@ -3,12 +3,10 @@ npm-rebuild(1) -- Rebuild a package
## SYNOPSIS
- npm rebuild [<name>[@<version>] [<name>[@<version>] ...]]
+ npm rebuild [<name> [<name> ...]]
* `<name>`:
The package to rebuild
-* `<version>`:
- The version range to rebuild. Any matching installed packages are rebuilt.
## DESCRIPTION
@@ -16,10 +14,6 @@ This command runs the `npm build` command on the matched folders. This is usefu
when you install a new version of node, and must recompile all your C++ addons with
the new binary.
-Regardless of the configuration settings, rebuild always sets `update-dependents`
-and `auto-activate` to false, to minimize unexpected side effects. It does not
-change any state outside of the package's folder.
-
## CONFIGURATION
See `npm help build`
View
47 doc/registry.md
@@ -13,8 +13,8 @@ account information.
The official public npm registry is at <http://registry.npmjs.org/>. It
is powered by a CouchDB database at
-<http://isaacs.couchone.com/jsregistry>. The code for the couchapp is
-available at <http://github.com/isaacs/js-registry>. npm user accounts
+<http://isaacs.couchone.com/registry>. The code for the couchapp is
+available at <http://github.com/isaacs/npmjs.org>. npm user accounts
are CouchDB users, stored in the <http://isaacs.couchone.com/_users>
database.
@@ -76,46 +76,3 @@ ask for help on the <npm-@googlegroups.com> mailing list.
No, but such a thing is planned, and a tiny bit developed.
Stay tuned!
-
-## CONFIGURATION
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
-### _auth
-
-A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
-
-If your config file is ever corrupted, you can set this manually by doing:
-
- npm adduser
-
-### username, _password
-
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`. This is the part before the ":"
-
-### proxy
-
-If proxy is available, then npm will access the registry via
-the proxy server.
-
-Example:
-
- proxy = http://user:password@proxy-server:8080
-
-### tar
-
-Default: env.TAR or "tar"
-
-The name of a GNU-compatible tar program on your system.
-
-### gzip
-
-Default: env.GZIPBIN or "gzip"
-
-The name of a GNU-compatible gzip program on your system.
-
View
2  doc/restart.md
@@ -3,7 +3,7 @@ npm-restart(1) -- Start a package
## SYNOPSIS
- npm restart <name>[@<version>] [<name>[@<version>] ...]
+ npm restart <name>
## DESCRIPTION
View
10 doc/root.md
@@ -0,0 +1,10 @@
+npm-root(1) -- Display npm root
+===============================
+
+## SYNOPSIS
+
+ npm root
+
+## DESCRIPTION
+
+Print the effective `node_modules` folder to standard out.
View
4 doc/run-script.md
@@ -3,14 +3,12 @@ npm-run-script(1) -- Run arbitrary package scripts
## SYNOPSIS
- npm run-script <script> <name>[@<version>] [<name>[@<version] ...]
+ npm run-script <script> <name>
## DESCRIPTION
This runs an arbitrary command from a package's "scripts" object.
-If no version is provided then it uses the active version.
-
It is used by the test, start, restart, and stop commands, but can be
called directly, as well.
View
20 doc/scripts.md
@@ -10,14 +10,6 @@ following scripts:
Run BEFORE the package is installed
* install, postinstall:
Run AFTER the package is installed.
-* preactivate:
- Run BEFORE the package is activated.
-* activate, postactivate:
- Run AFTER the package has been activated.
-* predeactivate, deactivate:
- Run BEFORE the package is deactivated.
-* postdeactivate:
- Run AFTER the package is deactivated.
* preuninstall, uninstall:
Run BEFORE the package is uninstalled.
* postuninstall:
@@ -26,10 +18,6 @@ following scripts:
Run BEFORE the package is updated with the update command.
* update, postupdate:
Run AFTER the package is updated with the update command.
-* preupdatedependencies:
- Run BEFORE the package dependencies are pointed to the new version.
-* updatedependencies, postupdatedependencies:
- Run AFTER the package dependencies are pointed to the new version.
* (pre,post,)updatedependency-foo:
Run (before,after) the "foo" dependency is modified.
* pretest, test, posttest:
@@ -64,14 +52,6 @@ Configuration parameters are put in the environment with the `npm_config_`
prefix. For instance, you can view the effective `root` config by checking the
`npm_config_root` environment variable.
-### dependency path and versions
-
-All of the resolved dependencies are available in the environtment as
-`npm_dependency_<name>=<version>` and
-`npm_dependency_<name>_path=<dir>`. So, if you need to refer to files
-from dependency packages, or see which version is installed, you can
-refer to those environment variables.
-
### Special: package.json "config" hash
The package.json "config" keys are overwritten in the environment if
View
1  doc/search.md
View
10 doc/search.md
@@ -0,0 +1,10 @@
+npm-ls(1) -- List installed packages
+======================================
+
+## SYNOPSIS
+
+ npm search [search terms ...]
+
+## DESCRIPTION
+
+Search the registry for packages matching the search terms.
View
4 doc/start.md
@@ -3,10 +3,8 @@ npm-start(1) -- Start a package
## SYNOPSIS
- npm start <name>[@<version>] [<name>[@<version>] ...]
+ npm start <name>
## DESCRIPTION
This runs a package's "start" script, if one was provided.
-
-If no version is specified, then it starts the "active" version.
View
4 doc/stop.md
@@ -3,10 +3,8 @@ npm-stop(1) -- Stop a package
## SYNOPSIS
- npm stop <name>[@<version>] [<name>[@<version>] ...]
+ npm stop <name>
## DESCRIPTION
This runs a package's "stop" script, if one was provided.
-
-If no version is specified, then it stops the "active" version.
View
9 doc/tag.md
@@ -3,12 +3,9 @@ npm-tag(1) -- Tag a published version
## SYNOPSIS
- npm tag <name>@<version> <tagname>
+ npm tag <name>@<version> [<tag>]
## DESCRIPTION
-Tags the specified version of the package with the specified "tagname".
-
-The only tag with special significance is "latest". That version is
-installed by default when no other tag or version number is specified,
-and always points to the most recently updated version of a package.
+Tags the specified version of the package with the specified tag, or the
+`--tag` config if not specified.
View
5 doc/test.md
@@ -3,10 +3,11 @@ npm-test(1) -- Test a package
## SYNOPSIS
- npm test <name>[@<version>] [<name>[@<version>] ...]
+ npm test <name>
## DESCRIPTION
This runs a package's "test" script, if one was provided.
-If no version is specified, then it tests the "active" version.
+To run tests as a condition of installation, set the `npat` config to
+true.
View
18 doc/uninstall.md
@@ -3,21 +3,9 @@ npm-uninstall(1) -- Remove a package
## SYNOPSIS
- npm uninstall <name>[@<version> [<name>[@<version>] ...]
- npm rm <name>[@<version> [<name>[@<version>] ...]
+ npm uninstall <name>
+ npm rm <name>
## DESCRIPTION
-This uninstalls a package, completely removing everything installed for it. If
-it's currently active, then it will be deactivated first, unless the
-`auto-deactivate` config setting is set to "false". If anything is
-depending on it, then those must be uninstalled first.
-
-If the version is omitted, then all versions of a package are removed.
-
-`<version>` may in fact be a version range, so these commands are
-acceptable:
-
- npm rm foo@'1.2.3 - 4.8.9'
- npm rm foo@'>=1.0.0'
- npm rm foo@'<2.0.3'
+This uninstalls a package, completely removing everything installed for it.
View
14 doc/update.md
@@ -8,16 +8,6 @@ npm-update(1) -- Update a package
## DESCRIPTION
This command will update all the packages listed to the latest version
-(specified by the `tag` config), as well as updating any dependent
-packages to use the new version, if possible.
+(specified by the `tag` config).
-Additionally, it will activate the new version, and delete any old versions, if
-safe to do so
-
-If the `update-dependents` configuration parameter is set to `"true"`, then
-packages will always be updated when they are installed, if they are the newest
-version.
-
-If the `update-dependents` configuration parameter is set to `"always"`, then
-packages will be updated when they are installed, even if to do so would be a
-downgrade.
+It will also install missing packages.
Please sign in to comment.
Something went wrong with that request. Please try again.