Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

make doc for 1.0

  • Loading branch information...
commit 0b249b688ccea8ab18aeeb382104a5a3102e9d62 1 parent 5fb8201
@isaacs isaacs authored
Showing with 1,952 additions and 2,734 deletions.
  1. +0 −27 doc/future-ideas/deploy.md
  2. +0 −276 doc/future-ideas/new-module-system.md
  3. +0 −23 doc/future-ideas/remote.md
  4. +0 −58 doc/future-ideas/site.md
  5. +5 −23 man1/adduser.1
  6. +51 −0 man1/author.1
  7. +2 −7 man1/build.1
  8. +25 −24 man1/cache.1
  9. +28 −445 man1/changelog.1
  10. +12 −17 man1/completion.1
  11. +482 −190 man1/config.1
  12. +0 −8 man1/deprecate.1
  13. +1 −4 man1/docs.1
  14. +3 −16 man1/edit.1
  15. +24 −36 man1/faq.1
  16. +23 −63 man1/find.1
  17. +132 −58 man1/folders.1
  18. +0 −49 man1/future-ideas/deploy.1
  19. +0 −334 man1/future-ideas/new-module-system.1
  20. +0 −28 man1/future-ideas/remote.1
  21. +0 −79 man1/future-ideas/site.1
  22. +482 −190 man1/get.1
  23. +14 −89 man1/install.1
  24. +3 −0  man1/json.1
  25. +26 −15 man1/link.1
  26. +23 −63 man1/list.1
  27. +26 −15 man1/ln.1
  28. +23 −63 man1/ls.1
  29. +3 −3 man1/npm.1
  30. +0 −30 man1/outdated.1
  31. +0 −38 man1/owner.1
  32. +17 −0 man1/prefix.1
  33. +23 −0 man1/prune.1
  34. +1 −9 man1/publish.1
  35. +1 −10 man1/rebuild.1
  36. +2 −56 man1/registry.1
  37. +1 −1  man1/restart.1
  38. +3 −24 man1/rm.1
  39. +17 −0 man1/root.1
  40. +1 −4 man1/run-script.1
  41. +0 −29 man1/scripts.1
  42. +4 −85 man1/search.1
  43. +482 −190 man1/set.1
  44. +1 −4 man1/start.1
  45. +1 −4 man1/stop.1
  46. +2 −7 man1/tag.1
  47. +3 −2 man1/test.1
  48. +3 −24 man1/uninstall.1
  49. +2 −14 man1/update.1
View
27 doc/future-ideas/deploy.md
@@ -1,27 +0,0 @@
-npm-deploy(1) -- Deploy a package to a remote host
-==================================================
-
-## FUTURE
-
-This functionality does not yet exist.
-
-## SUMMARY
-
- npm deploy <pkg> [--host <hostname>]
-
-## DESCRIPTION
-
-This is a porcelain command. It is equivalent to doing:
-
- npm publish --registry $(npm config get host) <pkg>
- npm remote install <pkg-name>@<pkg-version>
-
-That is, it first publishes the package to the server specified
-by the `host` config, and then remotely installs that package
-on the host.
-
-## SEE ALSO
-
-* npm-remote(1)
-* npm-site(1)
-* npm-publish(1)
View
276 doc/future-ideas/new-module-system.md
@@ -1,276 +0,0 @@
-npm-folders(1) -- Folder Structures Used by npm
-===============================================
-
-## FUTURE
-
-This functionality is not yet implemented. It is a plan, not reality.
-It is not the map, nor the territory, but a blueprint with blank areas.
-
-In particular, this is the scheme that will be used starting in npm@0.3,
-which will require node@0.5.0 or above.
-
-## GOALS
-
-* Don't splat stuff across the filesystem so much. Just specify a single
-root location, and be done with it.
-
-* Work on windows.
-
-* Minimize shim/symlink usage.
-
-* Do not rely on any global system path for node modules.
-
-* Remove the "activation" concept.
-
-## DESCRIPTION
-
-npm metadata lives in the `root` setting. There is the cache folder,
-and the contents of all installed packages.
-
-The default npm root folder is `/usr/local/lib/npm`.
-
-TODO: What should the root folder be on windows?
-
-### Cache folder
-
-The cache folder is a mirror of the data in the registry, as well as a
-working space for unpacking and creating tarballs.
-
-Files and folders created in the cache are owned by the executing user,
-often "root".
-
-Files are created with 0666 and folders with 0777, so that they can be
-modified by any user.
-
-* `root/cache` Cache folder
-* `root/cache/foo/cache.json` Expirable cache of registry/foo json data
-* `root/cache/foo/1.2.3/package` Pristine copy of foo package contents
-* `root/cache/foo/1.2.3/package.tgz` tarball of foo@1.2.3
-
-### Package folders
-
-In the npm root folder, package contents are unpacked, built, and then
-moved into the desired location.
-
-* `root/packages/foo/1.2.3` Metadata and contents of foo@1.2.3
-* `root/packages/foo/1.2.3/package` Build location of foo@1.2.3
-* `root/packages/foo/1.2.3/node_modules` Links to (or, on windows, copies of)
- dependencies of foo@1.2.3
-* `root/packages/foo/1.2.3/metadata.json` Metadata about the foo package.
-
-### Installation in `node_modules` Folders
-
-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")`.
-
-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.
-
-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.
-
-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.
-
-### Global Installation
-
-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".
-
-This means that the module contents are symlinked (or, on windows,
-copied) from `root/<name>/<version>/package` to
-`root/node_modules/<name>`.
-
-### Installing executables
-
-When installing globally, executables are linked (or, on windows,
-shimmed with a .bat file) to `root/bin`.
-
-When doing a
-localized installation, executables are linked (or, on windows, shimmed)
-to `./node_modules/.bin`. This also applies to the case when a globally
-installed package's dependents are being installed into it. Basically,
-whenever writing `.../node_modules/foo`, and the "foo"
-package has an executable named "bar", it'll write it to
-`.../node_modules/.bin/bar`.
-
-It is up to the user to update their PATH environment variable
-appropriately for globally installed executables. When running package
-lifecycle scripts (for example, to build, start, test, etc.), npm will
-put `./node_modules/.bin` as the first item in the PATH environ.
-
-### Installing manpages
-
-npm will install man pages to `root/share/man`. It is up to the user to
-make sure that their man program searches this location.
-
-### 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.
-
-For example, consider this dependency graph:
-
- foo
- +-- bar@1.2.3
- | +-- baz@2.x
- | | `-- quux@3.x
- | `-- asdf@*
- `-- baz@1.2.3
- `-- quux@3.x
-
-In this case, we'd expect a folder structure like this:
-
- foo
- +-- node_modules
- +-- bar (1.2.3)
- | `-- node_modules
- | `-- baz (2.0.2)
- +-- quux (3.2.0)
- +-- asdf (0.2.5)
- `-- baz (1.2.3)
-
-Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are
-installed in foo's node_modules folder.
-
-Since baz@1.2.3 depends on quux@3.x, a satisfying version is placed in
-foo's node_modules folder, because there are no conflicts.
-
-Since bar@1.2.3 depends on asdf@*, a satisfying version is placed in
-foo's node_modules folder. It also depends on baz@2.x, but this
-conflicts with the version already installed in foo's node_modules
-folder, so it is installed into the node_modules folder under bar@1.2.3.
-
-baz@2.0.2 depends on quux@3.x, but this dependency is already satisfied
-by the quux version installed in foo's node_modules folder, so nothing
-further needs to be done.
-
-### Snapshotting
-
-Whenever the `npm snapshot` command is run, the package.json file is
-updated to include the versions of all of the packages in the
-`./node_modules` folder as dependencies.
-
-### 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 unmodified copies of the corresponding packages in
-`root/node_modules/<name>/<version>/package`, then they will not be
-included in the package tarball.
-
-If the package has been modified, then it is left as-is, and included in
-the package.
-
-This allows a package maintainer to install all of their dependencies
-(and dev dependencies) locally, but only publish those items that cannot
-be found elsewhere.
-
-### Updating
-
-npm keeps track of every installation of foo@1.2.3 in
-`root/packages/foo/1.2.3/metadata.json`.
-
-When updating in a package folder (see algorithm for determining this in
-"Installation in `node_modules` Folders"), npm updates the packages in
-the local folder to the latest versions that are compatible with the
-requirements in the package.json file.
-
-If global is set to `"super"`, then npm will attempt to update
-all copies of packages installed anywhere and everywhere that it is
-aware of.
-
-If `global` is set to `true, or implied by not being in a package folder
-at the time, then npm will update the globally installed packages.
-
-If you do `npm update foo`, and you're in a local package folder, but
-`foo` is not installed there, and it *is* installed globally, then that
-will be equivalent to doing `npm update foo --global`.
-
-### Uninstalling
-
-Uninstalling works like updating.
-
-If global is set to "super", then it removes all traces from everywhere.
-
-If global is set to "true", or implied, then it removes the global copy.
-
-If global is set to "false", or unset and the command is in a package
-folder with a copy of the package being removed, then it removes it from
-the local folder.
-
-### Linking
-
-When `npm link` is run without any arguments in a package folder, then a
-symbolic link is created from that folder to `root/<name>/LINK`.
-Additionally, its package dependencies are installed to its
-./node_modules folder as necessary.
-
-When `npm link <name>` is run in another package folder, a symbolic
-link is created from `root/<name>/LINK` to `./node_modules/<name>`, and
-its dependencies are also installed if necessary. (Generally, it will
-not be necessary, as the package will already have its own node_modules
-folder containing its dependencies.)
-
-When publishing, linked package dependencies are resolved to their
-current state. It is assumed that the linked folder was linked for a
-reason, and may contain changes required for the proper functioning of
-the host program.
-
-#### npm link use case
-
- # create a linked "request" package
- cd ~/projects/request
- npm link
-
- # now write a program that uses request
- mkdir -p ~/projects/my-program
- cd ~/projects/my-program
- git init
- # do your git stuff...
- npm init
- # enter some package.json values
- # now we're ready to rock.
- # use redis, but don't need bleeding edge.
- npm install redis
- # use the linked copy of request
- npm link request
-
- # now any changes to ~/projects/request will
- # be immediately effective in my-program when
- # I do require("request")
-
-#### link on Windows
-
-Not sure how this will work. Maybe linking simply isn't possible?
View
23 doc/future-ideas/remote.md
@@ -1,23 +0,0 @@
-npm-remote(1) -- Execute commands on a remote machine
-=====================================================
-
-## FUTURE
-
-This functionality does not yet exist.
-
-## SYNOPSIS
-
- npm remote <commands>
-
-## DESCRIPTION
-
-Run a command on a remote npm site instance.
-
-In order to do this, the current authenticated user must be in
-the "admin" list on the server, and it must be running with https
-support.
-
-It uses the `host` config to know where to do things.
-
-
-
View
58 doc/future-ideas/site.md
@@ -1,58 +0,0 @@
-npm-site(1) -- Run the npm web site
-===================================
-
-## FUTURE
-
-This functionality does not yet exist.
-
-## SYNOPSIS
-
- npm site [ start | stop ]
-
-## DESCRIPTION
-
-This starts up npm in "site" mode. The following configs are relevant,
-and can either be specified in the `.npmrc` file, or as command line
-options.
-
-* userfile:
- A file containing the encrypted authorization info for all users. If
- specified, then this is used for `npm adduser` requests
- to this registry.
-* admin:
- A comma-delimited list of admin users. All of these must already be
- in the local adduser config. If there is no admin, then the site will
- not allow remote management. All admin usernames must already be
- in the userfile, and a userfile must be specified.
-* listen:
- Ports to listen on for WS requests. The first number is for http,
- the second for https, and the third for secure TCP. Set any to "-",
- or omit, to use the default.
- Defaults to "80,443,15443"
-* registry:
- If a package is not found, then its contents will be fetched from the
- upstream registry, and cached for future retrieval.
-
- isaacs: Make sure that this does loop-detection, so that a "ring" of
- registries can work as a distributed network. Also, once we have
- support for checking multiple registries, you could have a distribution
- ring that secondarily depends on some other upstream resource.
-
-The content for the site is stored in the npm cache directory, which is
-inside the folder used for the `root` setting, at `{root}/.npm/.cache`.
-It is organized in a simple hierarchical folder structure corresponding
-to the web service URLs that npm uses.
-
-## TCP Server
-
-The TCP server starts up to support the `npm remote` command, if there is
-a valid admin userlist.
-
-## NOTE
-
-This also is what happens when you do `npm start npm`.
-
-## SEE ALSO
-
-* npm-remote(1)
-* npm-config(1)
View
28 man1/adduser.1
@@ -18,41 +18,23 @@ Create or verify a user named \fB<username>\fR in the npm registry, and
save the credentials to the \fB\|\.npmrc\fR file\.
.
.P
-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\.
.
.P
You may use this command to change your email address, but not username
or password\.
.
.P
+To reset your password, go to \fIhttp://admin\.npmjs\.org/\fR
+.
+.P
You may use this command multiple times with the same user account to
authorize on a new machine\.
.
.SH "CONFIGURATION"
.
-.SS "_auth"
-A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\.
-.
-.P
-If your config file is ever corrupted, you can set this manually by doing:
-.
-.IP "" 4
-.
-.nf
-npm adduser
-.
-.fi
-.
-.IP "" 0
-.
.SS "registry"
-Default: https://registry\.npmjs\.org/
+Default: http://registry\.npmjs\.org/
.
.P
The base URL of the npm package registry\.
-.
-.SS "username, _password"
-Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":"
View
51 man1/author.1
@@ -0,0 +1,51 @@
+.\" Generated with Ronnjs/v0.1
+.\" http://github.com/kapouer/ronnjs/
+.
+.TH "NPM\-OWNER" "1" "March 2011" "" ""
+.
+.SH "NAME"
+\fBnpm-owner\fR \-\- Manage package owners
+.
+.SH "SYNOPSIS"
+.
+.nf
+npm owner ls <package name>
+npm owner add <user> <package name>
+npm owner rm <user> <package name>
+.
+.fi
+.
+.SH "DESCRIPTION"
+.
+.IP "\(bu" 4
+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\.
+.
+.IP "\(bu" 4
+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\.
+.
+.IP "\(bu" 4
+rm:
+Remove a user from the package owner list\. This immediately revokes their
+privileges\.
+.
+.IP "" 0
+.
+.P
+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\.
+.
+.SH "SEE ALSO"
+.
+.IP "\(bu" 4
+npm\-publish(1)
+.
+.IP "\(bu" 4
+npm\-registry(1)
+.
+.IP "" 0
+
View
9 man1/build.1
@@ -20,15 +20,10 @@ A folder containing a \fBpackage\.json\fR file in its root\.
.IP "" 0
.
.SH "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 is the plumbing command called by \fBnpm link\fR and \fBnpm install\fR\|\.
.
.P
-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\.
-.
-.SH "CONFIGURATION"
+It should generally not be called directly\.
.
.SH "SEE ALSO"
.
View
49 man1/cache.1
@@ -14,7 +14,7 @@ npm cache add <folder>
npm cache add <tarball url>
npm cache add <name>@<version>
npm cache ls [<path>]
-npm cache clean [<name>[@<version>]]
+npm cache clean [<path>]
.
.fi
.
@@ -22,54 +22,55 @@ npm cache clean [<name>[@<version>]]
.
.IP "\(bu" 4
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\.
.
-.IP
-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\.
-.
.IP "\(bu" 4
ls:
-Show the data in the cache\. Additional arguments are joined together
-in a path\-like fashion, but something like \fBnpm cache ls npm/0\.1\.5\fR 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 \fBfind\fR program, but limited by the \fBdepth\fR config\.
.
.IP "\(bu" 4
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\.
-.
-.IP
-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\.
.
.IP "" 0
.
.SH "DETAILS"
-npm stores data for a version of a package in \fB$ROOT/\.npm/\.cache/<name>/<version>\fR\|\. Three pieces of data are stored
-in this folder:
+npm stores cache data in \fB$HOME/\.npm\fR\|\. For each package that is added
+to the cache, three pieces of information are stored in \fB{cache}/{name}/{version}\fR:
.
.IP "\(bu" 4
-package/:
+\|\.\.\./package/:
A folder containing the package contents as they appear in the tarball\.
.
.IP "\(bu" 4
-package\.json:
+\|\.\.\./package\.json:
The package\.json file, as npm sees it, with overlays applied and a _id attribute\.
.
.IP "\(bu" 4
-package\.tgz:
+\|\.\.\./package\.tgz:
The tarball for that version\.
.
.IP "" 0
.
+.P
+Additionally, whenever a registry request is made, a \fB\|\.cache\.json\fR file
+is placed at the corresponding URI, to store the ETag and the requested
+data\.
+.
+.P
+Commands that make non\-essential registry requests (such as \fBsearch\fR and \fBview\fR, or the completion scripts) generally specify a minimum timeout\.
+If the \fB\|\.cache\.json\fR file is younger than the specified timeout, then
+they do not make an HTTP request to the registry\.
+.
.SH "CONFIGURATION"
.
-.SS "root"
-Default: \fB$INSTALL_PREFIX/lib/node\fR
+.SS "cache"
+Default: \fB$HOME/\.npm\fR on Posix, or \fB$HOME/npm\-cache\fR on Windows\.
.
.P
-The root folder where packages are installed and npm keeps its data\.
+The root cache folder\.
View
473 man1/changelog.1
@@ -9,513 +9,94 @@
.SH "HISTORY"
.
.IP "\(bu" 4
-0\.0\.1:
-Lots of sketches and false starts\. Abandoned a few times\.
-.
-.IP "\(bu" 4
-0\.0\.2:
-Install worked mostly\. Still promise\-based\.
-.
-.IP "\(bu" 4
-0\.0\.3:
-Converted to callbacks\.
-.
-.br
-Mikeal Rogers wrote a registry for it\.
-.
-.IP "\(bu" 4
-0\.0\.4:
-version dependencies
-.
-.br
-link packages
-.
-.br
-activation
-.
-.br
-lifecycle scripts
-.
-.br
-bin linking
-.
-.br
-uninstallation
-.
-.IP "\(bu" 4
-0\.0\.5:
-fix a few bugs in uninstall wrt dependent packages
-.
-.br
-fix relative require()for nodejs modules installed with the "bin" field\.
-.
-.br
-(issue #2)
-.
-.br
-update to work with node 0\.1\.33 (aka net2)
-.
-.br
-added publish and tag commands
-.
-.IP "\(bu" 4
-0\.0\.6:
-set up a public registry
-.
-.br
-send content\-length with registry PUTs
+0\.0
.
.br
-adduser command (Mikeal Rogers)
-.
-.br
-ini file stuff (Mikeal Rogers)
+Lots of sketches and false starts\. Abandoned a few times\.
.
.br
-env\-specific package\.json
+Core functionality established\.
.
.br
-added more info to npm\'s the package\.json (bugs, contributors, etc\.)
+alpha\.
.
.IP "\(bu" 4
-0\.0\.7:
-fixed a few bugs in semver
-.
-.br
-refactor documentation
-.
-.br
-add "help" command
-.
-.br
-add install from registry
+0\.1
.
.br
-everything else core
-.
-.br
-push to beta
-.
-.IP "\(bu" 4
-0\.1\.0 \- 0\.1\.2:
push to beta, and announce
.
.br
-clean up some bugs around lifecycle scripts
-.
-.br
-reduce reliance on makefile
-.
-.br
-documentation updates
-.
-.br
-Fixed DOA bugs
-.
-.br
-Removed dependence on ronn
-.
-.IP "\(bu" 4
-0\.1\.3:
-Changed a few details with configs (fix #5)
-.
-.br
-Update adduser and publish to put author info in the data
-.
-.br
-Use buffer api for file writes, hopefully fix #4
-.
-.IP "\(bu" 4
-0\.1\.4 \- 0\.1\.5:
-Fixes for a few more bugs and fix some documentation\.
-.
-.IP "\(bu" 4
-0\.1\.6 \- 0\.1\.7:
-Add cache functionality
-.
-.br
-Use couchdb attachments to host tarballs
+documentation, caching, more robust script support
.
.br
-Handle odd require\.paths more appropriately
+ownership tracking in the registry (no more admin party!)
.
.br
-Don\'t break on install if the man path is missing
+more robust config and option parsing
.
.br
-Support publishing or installing a folder or local tarball
-.
-.IP "\(bu" 4
-0\.1\.8:
-Bugfixes
-.
-.br
-Add start, stop, restart, and test commands
-.
-.IP "\(bu" 4
-0\.1\.9:
-npm list enhancements
-.
-.br
-fix the install bug
-.
-.IP "\(bu" 4
-0\.1\.10:
-More errors found by Ryan Dahl and Kris Zyp
-.
-.br
-Better uninstall and list behavior
-.
-.br
-Docs for new developers\.
-.
-.br
-Better tracking of ownership on the registry\.
-.
-.IP "\(bu" 4
-0\.1\.11:
-Martyn Smith found a whole lot of bugs\.
-.
-.br
-Make publish not die when the tarball is big\.
-.
-.br
-"make uninstall" support
-.
-.IP "\(bu" 4
-0\.1\.12 \- 0\.1\.13:
-Fix the downloading bug that was breaking the tarballs
-.
-.br
-Update some docs
-.
-.IP "\(bu" 4
-0\.1\.14 \- 0\.1\.16:
-Fix to stay in sync with node changes
-.
-.br
-Put a special tag on link installs
-.
-.br
-Modify semver comparison slightly
-.
-.br
-add unpublish command
-.
-.br
-Use the "drain" event properly for uploads
-.
-.br
-Handle thrown errors
+stabilize semver semantics
.
.br
-Handle \.npmignore
-.
-.IP "\(bu" 4
-0\.1\.17:
-Stabilization\.
-.
-.IP "\(bu" 4
-0\.1\.18:
-Change a few default configurations
+tests
.
.br
-Add test harness
+update command
.
.br
-Default publish, install, and link to "\." if no arguments given
-.
-.IP "\(bu" 4
-0\.1\.19 \- 0\.1\.20:
-Create a bunch of bugs
-.
-.br
-Fix a bunch of bugs
-.
-.br
-Some minor speed improvements
-.
-.IP "\(bu" 4
-0\.1\.21 \- 0\.1\.22:
-Relative paths
-.
-.br
-Support comments in package\.json
-.
-.br
-Add owner name to ls output
-.
-.br
-Add "owner" command to manage package owners
-.
-.br
-Support hook scripts in \fB{root}/\.npm/\.hooks/\fR
-.
-.br
-Initial support for config file relative to node executable
-.
-.br
-Support for http proxies
-.
-.br
-Documentation updates
-.
-.IP "\(bu" 4
-0\.1\.23:
-update command \- This is huge\.
+bundle command
.
.br
Rollback for failed installations
.
.br
-Install dependencies for link packages
-.
-.br
-Silently read passwords for adduser
-.
-.br
-Cascading configs: cli, env, user, global
-.
-.br
-First pass at \fBnpm view\fR command
-.
-.IP "\(bu" 4
-0\.1\.24, 0\.1\.25:
-Fix a bunch of things
-.
-.br
-Cleanup, etc\.
-.
-.br
-help via \-\-help, \-h, or \-?
-.
-.IP "\(bu" 4
-0\.1\.26:
-"modules" hash in package\.json (Alex K\. Wolfe)
-.
-.br
-Better "restart" command (Alex K Wolfe)
-.
-.br
-Work on Cygwin
-.
-.br
-Remove link packages properly
-.
-.br
-Make several commands more parallel
-.
-.IP "\(bu" 4
-0\.1\.27:
-Man pages handled with the "man" entry, or a "man" directory
-.
-.br
-Install man pages in the "manroot" config dir
-.
-.br
-Control log output with the "loglevel" config
-.
-.br
-Support a "bin" directory of executables that get auto\-linked
-.
-.br
-Un\-deprecate the "lib" directory\.
-.
-.br
-Bug killing
-.
-.br
-Split up the tar usage so it works on Solaris
-.
-.br
-bundle command
-.
-.br
-rebuild command
+Solaris and Cygwin support
.
.IP "\(bu" 4
-0\.2\.0:
-Lots more bug killing
+0\.2
.
.br
+First allegedly "stable" release\.
Various fixes found during the Node Knockout extravaganza
.
.br
-Change all "name\-version" things to be "name@version"
-.
-.br
-First allegedly "stable" release\.
-.
-.IP "\(bu" 4
-0\.2\.1:
Minor updates and bugfixes
.
-.IP "\(bu" 4
-0\.2\.2:
-Update "help" to work on Solaris
-.
-.br
-Remove updated packages that don\'t have dependencies\.
-.
-.br
-Allow implied suffixes on \.js bins
-.
-.br
-Fix an "adduser" bug
-.
-.IP "\(bu" 4
-0\.2\.3:
-Lots of documentation tweaks and cleanup
-.
-.br
-Support || in version ranges
-.
-.IP "\(bu" 4
-0\.2\.4:
-Contribution party!
-.
-.br
-Better list whitespace
-.
-.br
-Lots of config happiness
-.
.br
-Ignore all major SCM folders by default
+more complete semver functionality
.
.br
-Handle proxies and hostnames with ports
-.
-.br
-Better Bundling
-.
-.br
-Add \'outdated\' command
-.
-.br
-Better handling of "engines" field
-.
-.IP "\(bu" 4
-0\.2\.5:
Make npm OK to use programmatically (Charlie Robbins)
-.
-.IP "\(bu" 4
-0\.2\.6:
-More programmatic updates
-.
-.br
recursive package removal
.
.br
-tab completion
-.
-.IP "\(bu" 4
-0\.2\.7 \- 0\.2\.8:
-Bundle treated like a first\-class citizen, and simplified
-.
-.br
-Many bug fixes
-.
-.IP "\(bu" 4
-0\.2\.9:
-npm version command
+tab completion (Evan Meagher)
.
.br
shasums on all tarballs
.
.br
-More portable tar option usage
-.
-.br
-Much beefed up bundle command
-.
-.br
-Deep view command
-.
-.IP "\(bu" 4
-0\.2\.10:
-npm edit command
-.
-.br
-various stability bugfixes\.
-.
-.IP "\(bu" 4
-0\.2\.11:
-~> and 1\.2\.x style version ranges
-.
-.br
-complete tab completion: see \fBnpm help completion\fR (Evan Meagher)
-.
-.br
explore command: see \fBnpm help explore\fR
.
.br
docs command: see \fBnpm help docs\fR
.
.br
-keywords and description in \fBnpm ls\fR
-.
-.br
-Frequently asked questions at \fBnpm help faq\fR
-.
-.IP "\(bu" 4
-0\.2\.12:
-Various bugfixes (0\.2\.11 was big, broke some stuff)
-.
-.br
-\fBnpm faq\fR command (wrapper for \fBnpm help faq\fR)
-.
-.IP "\(bu" 4
-0\.2\.13:
-Merry Xmas!
-.
-.br
-Config setting on the command line with grace and gusto
+Frequently asked questions at \fBnpm faq\fR
+xmas easter egg
.
.br
-Portability and stability fixes\.
-.
-.br
-Mostly sort of works with Homebrew\-installed nodejs\.
-.
-.IP "\(bu" 4
-0\.2\.14:
-A little bit of documentation overhaul\.
+work with homebrew nodejs
.
.br
Support for \fB"<name>":"<url>"\fR for dependencies\.
.
-.br
-Fix for "unpublish" regression\.
-.
-.br
-Support for "files" array\.
-.
-.br
-Dependency info in lifecycle scripts\.
-.
-.br
-More data validation\.
-.
.IP "\(bu" 4
-0\.2\.15 \- 0\.2\.17:
-Added "\-\-force" for publish
-.
-.br
-Support argless "unpublish" and "uninstall" in package dirs
-.
-.br
-Document future stuff
+0\.3
.
.br
-Remove support for "modules" hash
-.
-.br
-Read package defaults when reading json
-.
-.IP "\(bu" 4
-0\.3\.0:
-More correct permission/uid handling\. (Sudo is now encouraged!)
+More correct permission/uid handling\. (Sudo now encouraged!)
.
.br
Require node 0\.4\.0
@@ -527,17 +108,19 @@ Separate semver out into a separate utility\.
Packages without "main" modules don\'t export modules\.
.
.br
+Remove support for invalid JSON (since node doesn\'t support it)
+.
+.br
No shims! (Still has symlinks, though)
.
.IP "\(bu" 4
-0\.3\.1\-0\.3\.5:
-Ease up on permission forcing\.
+1\.0
.
.br
-Fix bugs around proxy handling\.
+Simplify configuration greatly\.
.
.br
-Remove support for invalid JSON (since node doesn\'t support it)
+Install locally (bundle by default)
.
.IP "" 0
View
29 man1/completion.1
@@ -6,27 +6,22 @@
.SH "NAME"
\fBnpm-completion\fR \-\- Tab Completion for npm
.
-.SH "DESCRIPTION"
-You should set up tab completion for npm if you haven\'t already\.
-There are a few ways to do this:
-.
-.IP "1" 4
-Add \fB\|\. /path/to/npm\-completion\.sh\fR to your ~/\.bashrc file\. OR:
+.SH "SYNOPSIS"
.
-.IP "2" 4
-Create a symlink like this if you have automatic bash completion set up: \fBln \- /path/to/npm\-completion\.sh /etc/bash\-completion\.d/npm\fR
-or, perhaps: \fBln \- /path/to/npm\-completion\.sh /usr/local/etc/bash\-completion\.d/npm\fR
+.nf
+npm completion >> ~/\.bashrc
+npm completion >> ~/\.zshrc
.
-.IP "" 0
+.fi
.
-.P
-If you\'re using a non\-bash shell (like zsh or ksh) then this might not work\.
+.SH "DESCRIPTION"
+Sets up a function that enables tab\-completion in all npm commands\.
.
.P
-To get the path to the npm\-completion\.sh file, use \fBnpm explore npm pwd\fR\|\.
+You may of course also pipe the relevant script to a file such as \fB/usr/local/etc/bash_completion\.d/npm\fR if you have a system that will
+read that file for you\.
.
.P
-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 \fBCOMP_CWORD\fR, \fBCOMP_LINE\fR, and \fBCOMP_POINT\fR are defined in the
+environment, \fBnpm completion\fR acts in "plumbing mode", and outputs
+completions based on the arguments\.
View
672 man1/config.1
@@ -65,6 +65,9 @@ npm config set key value
.P
Sets the config key to the value\.
.
+.P
+If value is omitted, then it sets it to "true"\.
+.
.SS "get"
.
.nf
@@ -73,9 +76,7 @@ npm config get key
.fi
.
.P
-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 \fBnpm get key 2>/dev/null\fR
-to print out JUST the config value\.)
+Echo the config value to stdout\.
.
.SS "list"
.
@@ -105,7 +106,91 @@ npm config edit
.fi
.
.P
-Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\.
+Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the
+global config\.
+.
+.SH "Shorthands and Other CLI Niceties"
+The following shorthands are parsed on the command\-line:
+.
+.IP "\(bu" 4
+\fB\-v\fR: \fB\-\-version\fR
+.
+.IP "\(bu" 4
+\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR, \fB\-H\fR: \fB\-\-usage\fR
+.
+.IP "\(bu" 4
+\fB\-s\fR, \fB\-\-silent\fR: \fB\-\-loglevel silent\fR
+.
+.IP "\(bu" 4
+\fB\-d\fR: \fB\-\-loglevel info\fR
+.
+.IP "\(bu" 4
+\fB\-dd\fR, \fB\-\-verbose\fR: \fB\-\-loglevel verbose\fR
+.
+.IP "\(bu" 4
+\fB\-ddd\fR: \fB\-\-loglevel silly\fR
+.
+.IP "\(bu" 4
+\fB\-g\fR: \fB\-\-global\fR
+.
+.IP "\(bu" 4
+\fB\-l\fR: \fB\-\-long\fR
+.
+.IP "\(bu" 4
+\fB\-p\fR, \fB\-\-porcelain\fR: \fB\-\-parseable\fR
+.
+.IP "\(bu" 4
+\fB\-reg\fR: \fB\-\-registry\fR
+.
+.IP "\(bu" 4
+\fB\-v\fR: \fB\-\-version\fR
+.
+.IP "\(bu" 4
+\fB\-f\fR: \fB\-\-force\fR
+.
+.IP "\(bu" 4
+\fB\-l\fR: \fB\-\-long\fR
+.
+.IP "\(bu" 4
+\fB\-desc\fR: \fB\-\-description\fR
+.
+.IP "\(bu" 4
+\fBll\fR and \fBla\fR commands: \fBls \-\-long\fR
+.
+.IP "" 0
+.
+.P
+If the specified configuration param resolves unambiguously to a known
+configuration parameter, then it is expanded to that configuration
+parameter\. For example:
+.
+.IP "" 4
+.
+.nf
+npm ls \-\-par
+# same as:
+npm ls \-\-parseable
+.
+.fi
+.
+.IP "" 0
+.
+.P
+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:
+.
+.IP "" 4
+.
+.nf
+npm ls \-gpld
+# same as:
+npm ls \-\-global \-\-parseable \-\-long \-\-loglevel info
+.
+.fi
+.
+.IP "" 0
.
.SH "Per\-Package Config Settings"
When running scripts (see \fBnpm help scripts\fR)
@@ -150,340 +235,547 @@ npm config set foo:port 80
.
.SH "Config Settings"
.
-.SS "auto\-activate"
-Default: true
+.SS "browser"
+.
+.IP "\(bu" 4
+Default: OS X: \fB"open"\fR, others: \fB"google\-chrome"\fR
+.
+.IP "\(bu" 4
+Type: String
+.
+.IP "" 0
.
.P
-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 \fBnpm docs\fR command to open websites\.
.
-.SS "rebuild\-bundle"
+.SS "cache"
+.
+.IP "\(bu" 4
+Default: Windows: \fB~/npm\-cache\fR, Posix: \fB~/\.npm\fR
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
+.
+.P
+The location of npm\'s cache directory\. See \fBnpm help cache\fR
+.
+.SS "color"
+.
+.IP "\(bu" 4
Default: true
.
+.IP "\(bu" 4
+Type: Boolean or \fB"always"\fR
+.
+.IP "" 0
+.
.P
-Set to some truish value to rebuild bundled dependencies after
-installation\.
+If false, never shows colors\. If \fB"always"\fR then always shows colors\.
+If true, then only prints color codes for tty file descriptors\.
.
-.SS "recursive"
-Default: false
+.SS "depth"
+.
+.IP "\(bu" 4
+Default: Infinity
+.
+.IP "\(bu" 4
+Type: Number
+.
+.IP "" 0
.
.P
-Set to some truish value to recursively remove dependent packages\. For
-example if foo depends on bar, and bar depends on baz, then:
+The depth to go when recursing directories for \fBnpm ls\fR and \fBnpm cache ls\fR\|\.
.
-.IP "" 4
+.SS "description"
.
-.nf
-npm uninstall baz \-\-recursive
+.IP "\(bu" 4
+Default: true
.
-.fi
+.IP "\(bu" 4
+Type: Boolean
.
.IP "" 0
.
.P
-will remove baz, bar, and foo\.
+Whether or not to show the description in \fBnpm search\fR
.
-.SS "loglevel"
-Default: "info"
+.SS "dev"
+.
+.IP "\(bu" 4
+Default: false
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
.
.P
-The log level to show\.
+Whether or not to install \fBdev\-dependencies\fR along with packages\.
.
.P
-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\.
+Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is
+set\.
+.
+.SS "editor"
+.
+.IP "\(bu" 4
+Default: \fBEDITOR\fR environment variable if set, or \fB"vi"\fR
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-The log levels:
+The command to run for \fBnpm edit\fR or \fBnpm config edit\fR\|\.
+.
+.SS "force"
.
.IP "\(bu" 4
-silent: Show no output\. Nothing\. If there is output on stderr, it\'s
-because something is broken\.
+Default: false
.
.IP "\(bu" 4
-win: Show the "npm ok" or "npm not ok", but that\'s all\.
+Type: Boolean
+.
+.IP "" 0
+.
+.P
+Makes various commands more forceful\.
.
.IP "\(bu" 4
-error: Errors, usually with a stack trace\.
+lifecycle script failure does not block progress\.
.
.IP "\(bu" 4
-warn: Things that you should probably be aware of\.
+publishing clobbers previously published versions\.
.
.IP "\(bu" 4
-info: Helpful info\.
+skips cache when requesting from the registry\.
.
.IP "\(bu" 4
-silly: Not\-helpful info\. (Lots of dumping whole objects and such\.)
+prevents checks against clobbering non\-npm files\.
.
.IP "" 0
.
-.P
-Note that output to stdout is always printed\. This setting just modifies
-what\'s logged to stderr\.
+.SS "global"
.
-.SS "update\-dependents"
-Default: true
+.IP "\(bu" 4
+Default: false
.
-.P
-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\.
+.IP "\(bu" 4
+Type: Boolean
.
-.SS "root"
-Default: \fB$INSTALL_PREFIX/lib/node\fR
+.IP "" 0
.
.P
-The root folder where packages are installed and npm keeps its data\.
+Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\. See \fBnpm help global\fR for more on the differences in behavior\.
.
-.SS "binroot"
-Default: \fB$INSTALL_PREFIX/bin\fR
+.IP "\(bu" 4
+packages are installed into the \fBprefix/node_modules\fR folder, instead of the
+current working directory\.
.
-.P
-The folder where executable programs are installed\.
+.IP "\(bu" 4
+bin files are linked to \fBprefix/bin\fR
.
-.P
-Set to "false" to not install executables
+.IP "\(bu" 4
+man pages are linked to \fBprefix/share/man\fR
.
-.SS "manroot"
-Default: $INSTALL_PREFIX/share/man
+.IP "" 0
.
-.P
-The folder where man pages are installed\.
+.SS "globalconfig"
.
-.P
-Set to "false" to not install man pages\.
+.IP "\(bu" 4
+Default: {prefix}/etc/npmrc
.
-.SS "registry"
-Default: https://registry\.npmjs\.org/
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-The base URL of the npm package registry\.
+The config file to read for global config options\.
+.
+.SS "group"
+.
+.IP "\(bu" 4
+Default: GID of the current process
+.
+.IP "\(bu" 4
+Type: String or Number
.
-.SS "_auth"
-A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\.
+.IP "" 0
.
.P
-If your config file is ever corrupted, you can set this manually by doing:
+The group to use when running package scripts in global mode as the root
+user\.
.
-.IP "" 4
+.SS "gzipbin"
.
-.nf
-npm adduser
+.IP "\(bu" 4
+Default: "gzip"
.
-.fi
+.IP "\(bu" 4
+Type: path
.
.IP "" 0
.
-.SS "username, _password"
-Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":"
+.P
+The gzip binary
.
-.SS "proxy"
-If proxy is available, then npm will access the registry via
-the proxy server\.
+.SS "logfd"
+.
+.IP "\(bu" 4
+Default: stderr file descriptor
+.
+.IP "\(bu" 4
+Type: Number or Stream
+.
+.IP "" 0
.
.P
-Example:
+The location to write log output\.
.
-.IP "" 4
+.SS "loglevel"
.
-.nf
-proxy = http://user:password@proxy\-server:8080
+.IP "\(bu" 4
+Default: "warn"
.
-.fi
+.IP "\(bu" 4
+Type: String
.
-.IP "" 0
+.IP "\(bu" 4
+Values: "silent", "win", "error", "warn", "info", "verbose", "silly"
.
-.SS "tag"
-Default: latest
+.IP "" 0
.
.P
-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, \fIall\fR logs are written to \fBnpm\-debug\.log\fR in the current working directory\.
.
-.P
-Note: this has no effect on the npm\-tag(1) command\.
+.SS "long"
.
-.SS "userconfig"
-The default user configuration file is process\.env\.HOME+"/\.npmrc"\.
+.IP "\(bu" 4
+Default: false
.
-.P
-Note that this must be provided either in the cli or env settings\. Once the
-userconfig is read, it is irrelevant\.
+.IP "\(bu" 4
+Type: Boolean
.
-.SS "globalconfig"
-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 \fBmake install\fR, this is \fB/usr/local/etc/npmrc\fR\|\. 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\.
+.IP "" 0
.
.P
-Note that this must be provided in the cli, env, or userconfig settings\. Once
-the globalconfig is read, this parameter is irrelevant\.
+Whether or not to show extended information in \fBnpm ls\fR
.
-.SS "global"
-If set to some truish value (for instance, by being the last cli flag or being
-passed a literal \fBtrue\fR or \fB1\fR), and the \fBnpm config set\fR param is being
-called, then the new configuration paramater is written global config file\.
-Otherwise, they are saved to the user config file\.
+.SS "node\-version"
.
-.SS "dev"
-If set to a truish value, then it\'ll install the "devDependencies" as well as
-"dependencies" when installing a package\.
+.IP "\(bu" 4
+Default: process\.version
.
-.P
-Note that devDependencies are \fIalways\fR installed when linking a package\.
+.IP "\(bu" 4
+Type: semver
.
-.SS "tar"
-Default: env\.TAR or "tar"
+.IP "" 0
.
.P
-The name of a GNU\-compatible tar program on your system\.
+The node version to use when checking package\'s "engines" hash\.
.
-.SS "gzip"
-Default: env\.GZIPBIN or "gzip"
+.SS "npat"
.
-.P
-The name of a GNU\-compatible gzip program on your system\.
+.IP "\(bu" 4
+Default: false
.
-.SS "usage"
-If set to \fBtrue\fR, then this will tell help to print out the short usage statement
-instead of the long manpage type thing\.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
.
.P
-This is set automatically if you invoke help like \fBnpm command \-?\fR\|\.
+Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\.
.
-.SS "viewer"
-Default: "man"
+.SS "npaturl"
.
-.P
-The program to use to view help content\. Set to "woman" to use the emacs troff viewer
-by that name\.
+.IP "\(bu" 4
+Default: Not yet implemented
.
-.SS "_exit"
-Default: true
+.IP "\(bu" 4
+Type: url
+.
+.IP "" 0
.
.P
-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 \fBfalse\fR
-explicitly\.
+The url to report npat test results\.
.
-.SS "logfd"
-Default: Standard Error FD (2)
+.SS "onload\-script"
.
-.P
-The file descriptor (integer) or stream object where npm will write log
-messages\.
+.IP "\(bu" 4
+Default: false
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream\.
+A node module to \fBrequire()\fR when npm loads\. Useful for programmatic
+usage\.
.
.SS "outfd"
-Default: Standard Output FD (1)
+.
+.IP "\(bu" 4
+Default: standard output file descriptor
+.
+.IP "\(bu" 4
+Type: Number or Stream
+.
+.IP "" 0
.
.P
-The file descriptor (integer) or stream object where npm will write
-"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their
-output here\.
+Where to write "normal" output\. This has no effect on log output\.
+.
+.SS "parseable"
+.
+.IP "\(bu" 4
+Default: false
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
.
.P
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream\.
+Whether or not to output parseable results from commands that write to
+standard output\.
.
-.SS "color"
-Default: true
+.SS "prefix"
+.
+.IP "\(bu" 4
+Default: node\'s process\.installPrefix
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-Set to false to disable colorized output\.
+The location to install global items\. If set on the command line, then
+it forces non\-global commands to run in the specified folder\.
+.
+.SS "proxy"
+.
+.IP "\(bu" 4
+Default: "HTTP\fIPROXY" or "http\fRproxy" environment variable, or null
+.
+.IP "\(bu" 4
+Type: url
+.
+.IP "" 0
.
.P
-In versions of node that expose the \fBisatty\fR function, npm will never
-write colorized output to a non\-terminal file descriptor\.
+A proxy to use for outgoing http requests\.
+.
+.SS "rebuild\-bundle"
.
-.SS "tmproot"
-Default: env\.TMPDIR or "/tmp"
+.IP "\(bu" 4
+Default: true
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
.
.P
-The folder where temporary files should be placed\.
+Set to some truish value to rebuild bundled dependencies after
+installation\.
+.
+.SS "registry"
+.
+.IP "\(bu" 4
+Default: https://registry\.npmjs\.org/
+.
+.IP "\(bu" 4
+Type: url
+.
+.IP "" 0
.
.P
-npm creates a subfolder whenever it is run, and attempts to delete it
-afterwards\.
+The base URL of the npm package registry\.
.
-.SS "force"
-Default: false
+.SS "searchopts"
+.
+.IP "\(bu" 4
+Default: ""
+.
+.IP "\(bu" 4
+Type: String
+.
+.IP "" 0
.
.P
-Set to a truish value to force uninstalling packages, even if they have
-dependents\.
+Space\-separated options that are always passed to search\.
+.
+.SS "searchexclude"
+.
+.IP "\(bu" 4
+Default: ""
+.
+.IP "\(bu" 4
+Type: String
+.
+.IP "" 0
.
.P
-Note that setting \fBrecursive\fR is safer, because forcing uninstall can
-create orphan packages that no longer function properly\.
+Space\-separated options that limit the results from search\.
.
-.SS "editor"
-Default: env\.EDITOR
+.SS "shell"
+.
+.IP "\(bu" 4
+Default: SHELL environment variable, or "bash"
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-The program to use to edit files\.
+The shell to run for the \fBnpm explore\fR command\.
.
-.SS "listexclude"
-Default: null
+.SS "tag"
+.
+.IP "\(bu" 4
+Default: latest
+.
+.IP "\(bu" 4
+Type: String
+.
+.IP "" 0
.
.P
-A whitespace separated list of strings which \fIprevent\fR items from being
-shown to \fBnpm ls\fR\|\.
+If you ask npm to install a package and don\'t tell it a specific version, then
+it will install the specified tag\.
.
.P
-For example, \fBnpm ls installed \-\-listexclude zombie\fR will show all
-installed packages \fIexcept\fR zombie\.
+Also the tag that is added to the package@version specified by the \fBnpm
+tag\fR command, if no explicit tag is given\.
.
-.SS "listopts"
-Default: ""
+.SS "tar"
.
-.P
-A whitespace\-separated list of extra args that are always passed to npm ls
+.IP "\(bu" 4
+Default: TAR environment variable, or "tar"
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-For example: \fBlistopts = remote\fR
+The tar executable
+.
+.SS "tmp"
+.
+.IP "\(bu" 4
+Default: TMPDIR environment variable, or "/tmp"
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-\fBnpm ls\fR
+Where to store temporary files and folders\. All temp files are deleted
+on success, but left behind on failure for forensic purposes\.
+.
+.SS "unsafe\-perm"
+.
+.IP "\(bu" 4
+Default: false if running as root, true otherwise
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
.
.P
-The output here will always filter by remote
+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\.
.
-.SS "must\-install"
-Default: true
+.SS "usage"
+.
+.IP "\(bu" 4
+Default: false
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
.
.P
-Set to false to not install over packages that already exist\. By
-default, \fBnpm install foo\fR will fetch and install the latest version of \fBfoo\fR, even if it matches a version already installed\.
+Set to show short usage output (like the \-H output)
+instead of complete help when doing \fBnpm help\fR\|\.
.
-.SH "description"
-Default: true
+.SS "user"
+.
+.IP "\(bu" 4
+Default: "nobody"
+.
+.IP "\(bu" 4
+Type: String or Number
+.
+.IP "" 0
.
.P
-Show the package description in npm ls\.
+The UID to set to when running package scripts as root\.
+.
+.SS "username"
.
-.SH "node\-version"
-Default: \fBprocess\.version\fR from the node environment
+.IP "\(bu" 4
+Default: null
+.
+.IP "\(bu" 4
+Type: String
+.
+.IP "" 0
.
.P
-An effective version of node to use when checking for "engines"
-compliance\.
+The username on the npm registry\. Set with \fBnpm adduser\fR
+.
+.SS "userconfig"
+.
+.IP "\(bu" 4
+Default: ~/\.npmrc on Posix, or ~/npm\-config on Windows
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-Set to null or false to suppress engine checking altogether\.
+The location of user\-level configuration settings\.
.
-.SH "onload\-script"
+.SS "version"
+.
+.IP "\(bu" 4
Default: false
.
+.IP "\(bu" 4
+Type: boolean
+.
+.IP "" 0
+.
.P
-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\.
+If true, output the npm version and exit successfully\.
+.
+.P
+Only relevant when specified explicitly on the command line\.
+.
+.SS "viewer"
+.
+.IP "\(bu" 4
+Default: "man"
+.
+.IP "\(bu" 4
+Type: path
+.
+.IP "" 0
.
.P
-If false, then don\'t do any onload stuff\.
+The program to use to view help content\.
View
8 man1/deprecate.1
@@ -32,11 +32,3 @@ npm deprecate my\-thing@"< 0\.2\.3" "critical bug fixed in v0\.2\.3"
.
.P
Note that you must be the package owner to deprecate something\. See the \fBowner\fR and \fBadduser\fR help topics\.
-.
-.SH "CONFIGURATION"
-.
-.SS "registry"
-Default: https://registry\.npmjs\.org/
-.
-.P
-The base URL of the npm package registry\.
View
5 man1/docs.1
@@ -16,7 +16,4 @@ npm docs <pkgname>
.SH "DESCRIPTION"
This command tries to guess at the likely location of a package\'s
documentation URL, and then tries to open it using the \fB\-\-browser\fR
-config param, which defaults to \fB"open"\fR because that works on a mac\.
-.
-.P
-This is an experimental command\. It may disappear or change radically\.
+config param\.
View
19 man1/edit.1
@@ -22,19 +22,6 @@ After it has been edited, the package is rebuilt so as to pick up any
changes in compiled packages\.
.
.P
-Note: If you\'re finding yourself using this a lot, it\'s probably better
-to use \fBnpm link\fR instead\. However, it is extremely handy when used in
-conjunction with \fBnpm bundle\fR\|\.
-.
-.P
-For instance, you can do \fBnpm bundle install connect\fR to install connect
-into your package, and then \fBnpm bundle edit connect\fR to make a few
-changes to your locally bundled copy\.
-.
-.SH "CONFIGURATION"
-.
-.SS "editor"
-Default: env\.EDITOR
-.
-.P
-The program to use to edit files\.
+For instance, you can do \fBnpm install connect\fR to install connect
+into your package, and then \fBnpm edit connect\fR to make a few
+changes to your locally installed copy\.
View
60 man1/faq.1
@@ -19,32 +19,40 @@ 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\.
.
-.P
-If there doesn\'t seem to be enough output for your liking, run the
-command with \fB\-\-loglevel verbose\fR or if you\'re really brave, \fB\-\-loglevel
-silly\fR\|\.
+.SH "Where does npm put stuff?"
+See \fBnpm help folders\fR
.
-.SH "How do I make npm less noisy?"
-\fBnpm config set loglevel error\fR
+.SH "I installed something globally, but I can\'t `require()` it"
+Install it locally\.
.
-.P
-You can also set it to \fBwin\fR or \fBsilent\fR for even more quietness\.
+.SH "I don\'t wanna\."
+Ok, then do this:
+.
+.IP "" 4
+.
+.nf
+echo \'export NODE_PATH="\'$(npm root \-g)\'"\' >> ~/\.bashrc
+\|\. ~/\.bashrc
+.
+.fi
+.
+.IP "" 0
.
.SH "How do I list installed packages?"
-\fBnpm ls installed\fR
+\fBnpm ls\fR
.
.P
If you just want to see the names, and not all the registry data, you
can do: \fBnpm ls installed \-\-no\-registry\fR to turn off the registry\.
.
.SH "How do I search for packages?"
-\fBnpm ls\fR
+\fBnpm search\fR
.
.P
Arguments are greps\. \fBnpm ls jsdom\fR shows jsdom packages\.
.
.SH "How do I update npm?"
-\fBnpm update npm\fR
+\fBnpm update npm \-g\fR
.
.P
You can also update all outdated packages by doing \fBnpm update\fR without
@@ -98,27 +106,8 @@ You\'ll most likely want to \fBnpm link\fR your development folder\. That\'s
awesomely handy\.
.
.SH "Can I list a url as a dependency?"
-No\.
-.
-.P
-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\.
-.
-.P
-The correct way is to do the following:
-.
-.IP "\(bu" 4
-add a \fB"name":"version"\fR entry to your package\.json file\.
-.
-.IP "\(bu" 4
-\fBnpm bundle install <pkg>\fR where \fB<pkg>\fR is a url or path to your
-custom unpublished package\.
-.
-.IP "" 0
-.
-.P
-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\.
.
.SH "OK, but can I list a git repo as a dependency?"
No\.
@@ -134,7 +123,7 @@ point in the future, but not likely\. The current system allows for a
lot of use cases, and is very easy to maintain\.
.
.SH "How do I symlink to a dev folder so that I don\'t have to keep re\-installing?"
-\fBnpm link\fR
+See \fBnpm help link\fR
.
.SH "The package registry website\. What is that exactly?"
See \fBnpm help registry\fR for more info\.
@@ -149,8 +138,7 @@ The warnings will disappear when node supports uploading tarballs over
https reliably\.
.
.SH "I forgot my password, and can\'t publish\. How do I reset it?"
-Email \fIi@izs\.me\fR from the email address that you signed up with\. Then
-wait a day or two maybe\.
+Go to \fIhttp://admin\.npmjs\.org/\fR to reset it\.
.
.SH "I get ECONNREFUSED a lot\. What\'s up?"
Either the registry is down, or node\'s DNS isn\'t able to reach out\.
@@ -158,7 +146,7 @@ This happens a lot if you don\'t follow \fIall\fR the steps in the Cygwin
setup doc\.
.
.P
-To check if the registry is down, open up \fIhttp://registry\.npmjs\.org/\fR
+To check if the registry is down, open up \fIhttp://registry\.npmjs\.org/\-/short\fR
in a web browser\. This will also tell you if you are just unable to
access the internet for some reason\.
.
View
86 man1/find.1
@@ -1,98 +1,58 @@
.\" Generated with Ronnjs/v0.1
.\" http://github.com/kapouer/ronnjs/
.
-.TH "NPM\-LIST" "1" "March 2011" "" ""
+.TH "NPM\-LS" "1" "March 2011" "" ""
.
.SH "NAME"
-\fBnpm-list\fR \-\- List installed packages
+\fBnpm-ls\fR \-\- List installed packages
.
.SH "SYNOPSIS"
.
.nf
npm list
npm ls
+npm la
+npm ll
.
.fi
.
.SH "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\.
.
.P
-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:
-.
-.IP "" 4
-.
-.nf
-npm ls stable
-.
-.fi
-.
-.IP "" 0
+It does not take arguments\.
.
.P
-Another common usage is to find the set of all packages that are
-installed\. This can be accomplished by doing this:
-.
-.IP "" 4
-.
-.nf
-npm ls installed
-.
-.fi
-.
-.IP "" 0
-.
-.SH "CONFIGURATION"
-.
-.SS "registry"
-Default: https://registry\.npmjs\.org/
+It will print out extraneous, missing, and invalid packages\.
.
.P
-The base URL of the npm package registry\.
+When run as \fBll\fR or \fBla\fR, it shows extended information by default\.
.
-.SS "listopts"
-Default: ""
-.
-.P
-A whitespace\-separated list of extra args that are always passed to npm ls
+.SH "CONFIGURATION"
.
-.P
-For example: \fBlistopts = remote\fR
+.SS "long"
.
-.P
-\fBnpm ls\fR
+.IP "\(bu" 4
+Default: false
.
-.P
-The output here will always filter by remote
+.IP "\(bu" 4
+Type: Boolean
.
-.SS "description"
-Default: true
+.IP "" 0
.
.P
-Show the package description in npm ls\.
+Show extended information\.
.
-.SS "outfd"
-Default: Standard Output FD (1)
+.SS "parseable"
.
-.P
-The file descriptor (integer) or stream object where npm will write
-"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their
-output here\.
+.IP "\(bu" 4
+Default: false
.
-.P
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream\.
+.IP "\(bu" 4
+Type: Boolean
.
-.SS "color"
-Default: true
-.
-.P
-Set to false to disable colorized output\.
+.IP "" 0
.
.P
-In versions of node that expose the \fBisatty\fR function, npm will never
-write colorized output to a non\-terminal file descriptor\.
+Show parseable output instead of tree view\.
View
190 man1/folders.1
@@ -7,113 +7,187 @@
\fBnpm-folders\fR \-\- Folder Structures Used by npm
.
.SH "DESCRIPTION"
-Node modules and metadata live
-in the \fBroot\fR setting\. Check \fBnpm help config\fR for more
-on configuration options\.
+npm puts various things on your computer\. That\'s its job\.
.
.P
-\fBroot/foo\fR Symlink to the active version\'s module folder\.
+This document will tell you what it puts where\.
.
-.P
-\fBroot/foo@1\.0\.0/\fR Node modules for the foo package\.
+.SS "prefix Configuration"
+The \fBprefix\fR config defaults to node\'s \fBprocess\.installPrefix\fR\|\. On most
+systems, this is \fB/usr/local\fR\|\.
.
.P
-\fBroot/foo@1\.0\.0/{module\-name}\.js\fR Generated shim corresponding to a module
-defined in the modules option\. The module shim requires \fBroot/\.npm/foo/1\.0\.0/package/{module\-path}\.js\fR
+When the \fBglobal\fR 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\.
.
-.P
-The \fBmain\fR script is implemented by creating an \fBindex\.js\fR file in this folder\.
+.SS "Node Modules"
+Packages are droped into the \fBnode_modules\fR folder under the \fBprefix\fR\|\.
+When installing locally, this means that you can \fBrequire("packagename")\fR to load its main module, or \fBrequire("packagename/path/to/sub/module")\fR to load other modules\.
.
.P
-\fBroot/\.npm/foo\fR is where the stuff for package \fBfoo\fR would go\.
+If you wish to install node modules globally which can be loaded via \fBrequire()\fR from anywhere, then add the \fBprefix/node_modules\fR folder to
+your NODE_PATH environment variable\.
.
-.P
-\fBroot/\.npm/foo/1\.0\.0/package\fR the contents of the tarball containing foo
-version 1\.0\.0
+.SS "Executables"
+When in global mode, executables are linked into \fBprefix/bin\fR\|\.
.
.P
-\fBroot/\.npm/foo/1\.0\.0/main\.js\fR Generated file that exports the \fBmain\fR module in
-foo\. This is a shim, not a symbolic link, so that relative paths will work
-appropriately\.
+When in local mode, executables are linked into \fBprefix/node_modules/\.bin\fR\|\.
.
-.P
-\fBroot/\.npm/foo/active\fR symlink to the active version\.
+.SS "Man Pages"
+When in global mode, man pages are linked into \fBprefix/share/man\fR\|\.
.
.P
-\fBroot/\.npm/foo/1\.0\.0/node_modules\fR links to the modules that foo depends upon\.
-This is loaded into the require path first in the foo shims\.
+When in local node, man pages are not installed\.
.
-.P
-\fBroot/\.npm/foo/1\.0\.0/dependson\fR links to the package folders that foo depends
-on\. This is here so that npm can access those packages programmatically\.
+.SS "Cache"
+See \fBnpm help cache\fR\|\. Cache files are stored in \fB~/\.npm\fR on Posix, or \fB~/npm\-cache\fR on Windows\.
.
.P
-\fBroot/\.npm/foo/1\.0\.0/dependents\fR links to the packages that depend upon foo\.
+This is controlled by the \fBcache\fR configuration param\.
.
-.P
-\fBroot/\.npm/\.cache\fR the cache folder\.
+.SS "Temp Files"
+Temporary files are stored by default in the folder specified by the \fBtmp\fR config, which defaults to either the TMPDIR environment
+variable, or \fB/tmp\fR\|\.
.
.P
-\fBroot/\.npm/\.cache/foo/1\.0\.0/package\.json\fR the parsed package\.json for foo@1\.0\.0
+Temp files are given a unique folder under this root for each run of the
+program, and are deleted upon successful exit\.
.
-.P
-\fBroot/\.npm/\.cache/foo/1\.0\.0/package\.tgz\fR the tarball of foo@1\.0\.0
+.SH "More Information"
+When you run \fBnpm install foo@1\.2\.3\fR it downloads and builds the
+package, and then, if there is a package\.json file in the current
+working directory, it copies it to \fB$PWD/node_modules/foo\fR, so that your
+current package will get it when you do \fBrequire("foo")\fR\|\.
.
.P
-\fBroot/\.npm/\.cache/foo/1\.0\.0/package\fR the untouched pristine copy of foo@1\.0\.0
+When this is done, it also installs all of foo\'s dependencies to \fB\|\./node_modules/foo/node_modules/\fR, so that it will get its dependencies
+appropriately when it calls \fBrequire()\fR\|\. If foo depends on bar, and bar
+depends on baz, then there will also be a \fB\|\./node_modules/foo/node_modules/bar/node_modules/baz\fR, and so on\.
.
.P
-Executables are installed to the folder specified by the \fBbinroot\fR config\.
+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 \fBseek\-root\fR
+config value to false\.
.
.P
-\fBbinroot/foo\fR Symlink to the active version of the "foo" executable\.
+If no package root is found, then a global installation is performed\.
+The global installation may be supressed by setting the \fBglobal\fR
+configuration to false, in which case, the install will fail\.
.
-.P
-\fBbinroot/foo@1\.0\.0\fR An executable for foo at version 1\.0\.0\. Either a
-symbolic link or a shim to a file in the foo package\.
+.SS "Global Installation"
+If the \fBglobal\fR 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"\.
.
.P
-Man pages are installed to the folder specified by the \fBmanroot\fR config\.
-Man pages named something other than the package name are prefixed with
-the package name\.
+This means that the module contents are symlinked (or, on windows,
+copied) from \fBroot/<name>/<version>/package\fR to \fBroot/node_modules/<name>\fR\|\.
+.
+.SS "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\fImodules folders\. So, at every
+stage, if a package is already installed in an ancestor node\fRmodules