Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

first wave of documentation overhaul.

  • Loading branch information...
commit 4daf4e5f1e66c65178b404a5cd6d7a05e2a03c40 1 parent 1f0849f
@isaacs isaacs authored
View
9 doc/activate.md
@@ -10,6 +10,15 @@ npm activate(1) -- Activate an installed version of a package
This "activates" a specific version of a package, so that you can just do
`require("foo")` without having to specify the version.
+## CONFIG
+
+### 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.
+
## SEE ALSO
npm-deactivate(1)
View
27 doc/adduser.md
@@ -20,3 +20,30 @@ or password.
You may use this command multiple times with the same user account to
authorize on a new machine.
+
+## CONFIG
+
+### _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
+
+### _authCrypt
+
+If crypto.Cipher is available, and you have some private keys in `$HOME/.ssh`,
+then npm will encrypt your "_auth" config before saving to the .npmrc file,
+and will decrypt the "_authCrypt" config when it reads the .npmrc file.
+
+### registry
+
+Default: https://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
3  doc/build.md
@@ -17,6 +17,9 @@ This command creates the various interwoven links that ensure a package's conten
are available in the root appropriately, and that its dependencies are linked
appropriately.
+## CONFIG
+
+
## SEE ALSO
* npm-install(1)
View
13 doc/bundle.md
@@ -42,3 +42,16 @@ must contain a package.json, though, of course.)
Man pages are not installed by bundle.
Bins are installed, but not globally.
+
+## CONFIGS
+
+The bundle command itself is a proxy for `install`, or whichever command
+is passed as the first argument. As such, it uses
+the same configuration parameters as the commands it proxies,
+but with the following temporary changes:
+
+* root: $PWD/node_modules/
+* binroot: $PWD/node_modules/.bin
+* manroot: null
+
+See `npm help config` for more information on these.
View
8 doc/cache.md
@@ -48,6 +48,10 @@ in this folder:
* package.tgz:
The tarball for that version.
-## HISTORY
+## CONFIG
-Added in npm version 0.1.6
+### root
+
+Default: `$INSTALL_PREFIX/lib/node`
+
+The root folder where packages are installed and npm keeps its data.
View
12 doc/coding-style.md
@@ -170,3 +170,15 @@ and are rarely used.
Use a single uppercase letter for function names where the function
would normally be anonymous, but needs to call itself recursively. It
makes it clear that it's a "throwaway" function.
+
+## null, undefined, false, 0
+
+Boolean variables and functions should always be either `true` or
+`false`. Don't set it to 0 unless it's supposed to be a number.
+
+When something is intentionally missing or removed, set it to `null`.
+
+Don't set things to `undefined`. Reserve that value to mean "not yet
+set to anything."
+
+Boolean objects are verboten.
View
49 doc/config.md
@@ -35,6 +35,8 @@ 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:
@@ -92,13 +94,12 @@ then the user could change the behavior by doing:
## Config Settings
-npm supports a very basic argument parser. For any of the settings
-in npm-config(1), you can set them explicitly for a single command by
-doing:
+### auto-activate
- npm --key val <command>
+Default: true
-Configurations defined on the command line are not saved to the .npmrc file.
+Automatically activate a package after installation, if there is not an active
+version already. Set to "always" to always activate when installing.
### rebuild-bundle
@@ -140,13 +141,6 @@ The log levels:
Note that output to stdout is always printed. This setting just modifies
what's logged to stderr.
-### 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
@@ -197,23 +191,28 @@ If crypto.Cipher is available, and you have some private keys in `$HOME/.ssh`,
then npm will encrypt your "_auth" config before saving to the .npmrc file,
and will decrypt the "_authCrypt" config when it reads the .npmrc file.
-### tag
+### username, _password
-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.
+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 fetch the modules from the registry via
+If proxy is available, then npm will access the registry via
the proxy server.
Example:
- proxy = http://proxy-server:8080
+ proxy = http://user:password@proxy-server:8080
+
+### 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.
### userconfig
@@ -273,7 +272,7 @@ Default: "man"
The program to use to view help content. Set to "woman" to use the emacs troff viewer
by that name.
-### exit
+### _exit
Default: true
@@ -355,3 +354,9 @@ 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.
+
+## description
+
+Default: true
+
+Show the package description in npm ls.
View
12 doc/deprecate.md
@@ -15,4 +15,14 @@ something like this:
npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"
-Note that you must be the package owner to deprecate something.
+Note that you must be the package owner to deprecate something. See the
+`owner` and `adduser` help topics.
+
+## CONFIG
+
+### registry
+
+Default: https://registry.npmjs.org/
+
+The base URL of the npm package registry.
+
View
5 doc/developers.md
@@ -170,6 +170,11 @@ This part's easy. IN the root of your folder, do this:
You can give publish a url to a tarball, or a filename of a tarball,
or a path to a folder.
+Note that pretty much **everything in that folder will be exposed**
+by default. So, if you have secret stuff in there, use a `.npminclude`
+or `.npmignore` file to list out the globs to include/ignore, or publish
+from a fresh checkout.
+
## Brag about it
Send emails, write blogs, blab in IRC.
View
8 doc/edit.md
@@ -20,3 +20,11 @@ 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.
+
+## CONFIG
+
+### editor
+
+Default: env.EDITOR
+
+The program to use to edit files.
View
69 doc/folders.md
@@ -3,9 +3,20 @@ npm-folders(1) -- Folder Structures Used by npm
## DESCRIPTION
-Everything lives in the `root` setting. Check `npm help config` for more
+Node modules and metadata live
+in the `root` setting. Check `npm help config` for more
on configuration options.
+`root/foo` Symlink to the active version's module folder.
+
+`root/foo@1.0.0/` Node modules for the foo package.
+
+`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 `main` script is implemented by creating an `index.js` file in this folder.
+
`root/.npm/foo` is where the stuff for package `foo` would go.
`root/.npm/foo/1.0.0/package` the contents of the tarball containing foo
@@ -15,17 +26,9 @@ version 1.0.0
foo. This is a shim, not a symbolic link, so that relative paths will work
appropriately.
-`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 `main` script is implemented by creating an `index.js` file in this folder.
-
-`root/foo/` Symlink to the active version's module folder.
-
`root/.npm/foo/active` symlink to the active version.
-`root/.npm/foo/1.0.0/dependencies` links to the modules that foo depends upon.
+`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.
`root/.npm/foo/1.0.0/dependson` links to the package folders that foo depends
@@ -40,3 +43,49 @@ on. This is here so that npm can access those packages programmatically.
`root/.npm/.cache/foo/1.0.0/package.tgz` the tarball of foo@1.0.0
`root/.npm/.cache/foo/1.0.0/package` the untouched pristine copy of foo@1.0.0
+
+Executables are installed to the folder specified by the `binroot` config.
+
+`binroot/foo` Symlink to the active version of the "foo" executable.
+
+`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.
+
+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.
+
+`manroot/man1/foo.1` Symlink to the section 1 manpage for the active
+version of foo.
+
+`manroot/man1/foo@1.0.0.1` Section 1 man page for foo version 1.0.0
+
+`manroot/man8/foo-bar.8` Symlink to a section 8 manpage for the active
+version of foo.
+
+`manroot/man8/foo-bar@1.0.0.8` A section 8 manpage for foo version
+1.0.0.
+
+## CONFIG
+
+### 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.
View
81 doc/install.md
@@ -78,6 +78,87 @@ You may combine multiple arguments, and even multiple types of arguments. For e
The `--tag` argument will apply to all of the specified install targets.
+## CONFIG
+
+### 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
5 doc/link.md
@@ -23,3 +23,8 @@ 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.
+
+## CONFIG
+
+See the config section of `npm help install`. The `dev` configuration
+setting is always set to `true` when doing a link install.
View
46 doc/list.md
@@ -33,3 +33,49 @@ executions
npm config set listopts remote
This will append the remote argument each time `npm ls` is called.
+
+## CONFIG
+
+### 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.
+
+When using npm programmatically, you may want to provide a
+FileWriteStream, or some other form of WritableStream.
+
+### color
+
+Default: true
+
+Set to false to disable colorized output.
+
+In versions of node that expose the `isatty` function, npm will never
+write colorized output to a non-terminal file descriptor.
View
2  doc/npm.md
@@ -75,7 +75,7 @@ npm is extremely configurable. It reads its configuration options from
npm's default configuration options are defined in
lib/utils/default-config.js. These should not be changed.
-See `npm help config` for more information.
+See `npm help config` for much much more information.
## CONTRIBUTIONS
View
27 doc/outdated.md
@@ -10,3 +10,30 @@ 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
43 doc/owner.md
@@ -22,3 +22,46 @@ npm-owner(1) -- Manage package owners
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
+
+### _authCrypt
+
+If crypto.Cipher is available, and you have some private keys in `$HOME/.ssh`,
+then npm will encrypt your "_auth" config before saving to the .npmrc file,
+and will decrypt the "_authCrypt" config when it reads the .npmrc file.
+
+### 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)
+* npm-registry(1)
View
10 doc/publish.md
@@ -20,3 +20,13 @@ Publishes a package to the registry so that it can be installed by name.
Fails if the package name and version combination already exists in
the registry.
+
+## CONFIGURATION
+
+See `npm help registry`
+
+## SEE ALSO
+
+* npm-registry(1)
+* npm-adduser(1)
+* npm-owner(1)
View
4 doc/rebuild.md
@@ -19,3 +19,7 @@ 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
49 doc/registry.md
@@ -76,3 +76,52 @@ 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
+
+### _authCrypt
+
+If crypto.Cipher is available, and you have some private keys in `$HOME/.ssh`,
+then npm will encrypt your "_auth" config before saving to the .npmrc file,
+and will decrypt the "_authCrypt" config when it reads the .npmrc file.
+
+### 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.
+
Please sign in to comment.
Something went wrong with that request. Please try again.