diff --git a/.gitignore b/.gitignore index 7e68c475522..d28e5585eb1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,10 @@ +*.swp test/bin test/output.log test/packages/*/node_modules test/packages/npm-test-depends-on-spark/which-spark.log +test/packages/test-package/random-data.txt test/root -*.swp +node_modules/ronn +node_modules/.bin +npm-debug.log diff --git a/.npmignore b/.npmignore deleted file mode 100644 index 2c53106db35..00000000000 --- a/.npmignore +++ /dev/null @@ -1,7 +0,0 @@ -test/packages/test-package/random-data.txt -test/packages/npm-test-depends-on-spark/which-spark.log -test/packages/*/node_modules -test/output.log -test/root -test/bin -*.swp diff --git a/Makefile b/Makefile index 2a9c80d8b32..1d3dff947a7 100644 --- a/Makefile +++ b/Makefile @@ -20,7 +20,7 @@ latest: submodules node cli.js install install: submodules - node cli.js install + node cli.js install -g # backwards compat dev: install @@ -32,7 +32,7 @@ clean: uninstall uninstall: submodules node cli.js cache clean - node cli.js rm npm -f + node cli.js rm npm -g man: man1 @@ -43,7 +43,8 @@ doc: man1 $(docs) # use `npm install ronn` for this to work. man1/%.1: doc/%.md - ronn --roff $< > $@ + @[ -x ./node_modules/.bin/ronn ] || node cli.js install ronn + ./node_modules/.bin/ronn --roff $< > $@ man1/%/: doc/%/ @if ! test -d $@ ; then mkdir -p $@ ; fi diff --git a/doc/activate.md b/doc/activate.md deleted file mode 100644 index cf964a8a42c..00000000000 --- a/doc/activate.md +++ /dev/null @@ -1,24 +0,0 @@ -npm activate(1) -- Activate an installed version of a package -============================================================= - -## SYNOPSIS - - npm activate @ [@ ...] - -## DESCRIPTION - -This "activates" a specific version of a package, so that you can just do -`require("foo")` without having to specify the version. - -## CONFIGURATION - -### 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) diff --git a/doc/adduser.md b/doc/adduser.md index b02cb2b7b25..c6136814dfc 100644 --- a/doc/adduser.md +++ b/doc/adduser.md @@ -10,34 +10,20 @@ npm-adduser(1) -- Add a registry user account Create or verify a user named `` 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 + 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 ":" diff --git a/doc/author.md b/doc/author.md new file mode 120000 index 00000000000..b7a53cb66be --- /dev/null +++ b/doc/author.md @@ -0,0 +1 @@ +owner.md \ No newline at end of file diff --git a/doc/build.md b/doc/build.md index 5f8144a8e8e..978f4a6d62f 100644 --- a/doc/build.md +++ b/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 diff --git a/doc/bundle.md b/doc/bundle.md deleted file mode 100644 index 7e0d10fb0a3..00000000000 --- a/doc/bundle.md +++ /dev/null @@ -1,60 +0,0 @@ -npm-bundle(1) -- Bundle package dependencies -============================================ - -## SYNOPSIS - - npm bundle - npm bundle destroy - npm bundle - -Run in a package folder. - -## DESCRIPTION - -When run in a package folder, this command can be used to install -package dependencies into the `node_modules` folder. - -When the package is installed, it will read dependencies from the local -bundle *before* reading any dependencies that are already installed. - -Furthermore, when installing, npm will not attempt to install -dependencies that already exist in the bundle. - -To bundle all the dependencies of a given package, run `npm bundle` -without any arguments. - -To completely remove the bundle folder, run `npm bundle destroy`. - -To operate on the bundle packages, any npm command and arguments may be -passed to the `npm bundle` command. For example, to install a package -into the bundle, you can do `npm bundle install express`. - -To list the packages in the bundle, do `npm bundle ls`. To remove bundled -packages, do `npm bundle remove `. Et cetera. - -In this way, a command like -`npm bundle install http://github.com/user/project/tarball/master` can be used -to have a dependency that is not published on the npm registry. (It still -must contain a package.json, though, of course.) - -## CAVEATS - -Man pages are not installed by bundle. - -Bins are installed, but not globally. - -When a dependency is specified as a URL rather than a version range, it -is bundled with the package depending upon it. - -## CONFIGURATION - -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. diff --git a/doc/cache.md b/doc/cache.md index a18df676451..5c26808125c 100644 --- a/doc/cache.md +++ b/doc/cache.md @@ -10,48 +10,51 @@ npm-cache(1) -- install a package npm cache ls [] - npm cache clean [[@]] + npm cache clean [] ## 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//`. 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. diff --git a/doc/changelog.md b/doc/changelog.md index 6bb4693ee05..6f91d387f7d 100644 --- a/doc/changelog.md +++ b/doc/changelog.md @@ -3,249 +3,48 @@ 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 `"":""` 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 `"":""` 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) + Drastic rearchitecture diff --git a/doc/completion.md b/doc/completion.md index 454468b4ce7..2f80be395c0 100644 --- a/doc/completion.md +++ b/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. diff --git a/doc/config.md b/doc/config.md index 6f0db6c2842..d6c0a02a343 100644 --- a/doc/config.md +++ b/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. diff --git a/doc/deactivate.md b/doc/deactivate.md deleted file mode 100644 index 5bf5a17e9cb..00000000000 --- a/doc/deactivate.md +++ /dev/null @@ -1,15 +0,0 @@ -npm-deactivate(1) -- Deactivate the active version of a package -=============================================================== - -## SYNOPSIS - - npm deactivate - -## DESCRIPTION - -If there's an active version of the package, this will unlink it from that -preferential position. - -## SEE ALSO - -npm-activate(1) diff --git a/doc/deprecate.md b/doc/deprecate.md index b6f87e11956..a6d7c74e7d8 100644 --- a/doc/deprecate.md +++ b/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. - diff --git a/doc/docs.md b/doc/docs.md index c3f613deff6..754407e01c4 100644 --- a/doc/docs.md +++ b/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. diff --git a/doc/edit.md b/doc/edit.md index f3af36b8c5d..b5bd07947d9 100644 --- a/doc/edit.md +++ b/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. diff --git a/doc/faq.md b/doc/faq.md index 51bd724c2c0..38663b5b0f5 100644 --- a/doc/faq.md +++ b/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 ` where `` 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 from the email address that you signed up with. Then -wait a day or two maybe. +Go to 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 +To check if the registry is down, open up + in a web browser. This will also tell you if you are just unable to access the internet for some reason. diff --git a/doc/folders.md b/doc/folders.md index bfc022411a1..ae10dfada6d 100644 --- a/doc/folders.md +++ b/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///package` to +`root/node_modules/`. -### 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. diff --git a/doc/future-ideas/deploy.md b/doc/future-ideas/deploy.md deleted file mode 100644 index 9d2e17aa62f..00000000000 --- a/doc/future-ideas/deploy.md +++ /dev/null @@ -1,27 +0,0 @@ -npm-deploy(1) -- Deploy a package to a remote host -================================================== - -## FUTURE - -This functionality does not yet exist. - -## SUMMARY - - npm deploy [--host ] - -## DESCRIPTION - -This is a porcelain command. It is equivalent to doing: - - npm publish --registry $(npm config get host) - npm remote install @ - -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) diff --git a/doc/future-ideas/new-module-system.md b/doc/future-ideas/new-module-system.md deleted file mode 100644 index acac578a336..00000000000 --- a/doc/future-ideas/new-module-system.md +++ /dev/null @@ -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///package` to -`root/node_modules/`. - -### 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///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//LINK`. -Additionally, its package dependencies are installed to its -./node_modules folder as necessary. - -When `npm link ` is run in another package folder, a symbolic -link is created from `root//LINK` to `./node_modules/`, 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? diff --git a/doc/future-ideas/remote.md b/doc/future-ideas/remote.md deleted file mode 100644 index 7806b9b53a8..00000000000 --- a/doc/future-ideas/remote.md +++ /dev/null @@ -1,23 +0,0 @@ -npm-remote(1) -- Execute commands on a remote machine -===================================================== - -## FUTURE - -This functionality does not yet exist. - -## SYNOPSIS - - npm remote - -## 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. - - - diff --git a/doc/future-ideas/site.md b/doc/future-ideas/site.md deleted file mode 100644 index 7936e71f7b1..00000000000 --- a/doc/future-ideas/site.md +++ /dev/null @@ -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) diff --git a/doc/install.md b/doc/install.md index 4e74f6e36f6..eb1ec4ff784 100644 --- a/doc/install.md +++ b/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 npm install npm install @@ -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 ``: 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 ``: - Do a `@` install, where `` is the "tag" config from either your - .npmrc file, or the --tag argument on the command line. + Do a `@` install, where `` 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) diff --git a/doc/json.md b/doc/json.md index 0e213b34d73..cb83368528d 100644 --- a/doc/json.md +++ b/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 diff --git a/doc/link.md b/doc/link.md index 58af1be1eb5..32964e45ae0 100644 --- a/doc/link.md +++ b/doc/link.md @@ -3,28 +3,33 @@ npm-link(1) -- Symlink a package folder ## SYNOPSIS - npm link + npm link (in package folder) + npm link + ## 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/ diff --git a/doc/list.md b/doc/list.md index 60b71d48007..f802bb4698e 100644 --- a/doc/list.md +++ b/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. diff --git a/doc/npm.md b/doc/npm.md index a596fd6118f..4fa36af00ff 100644 --- a/doc/npm.md +++ b/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: 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. diff --git a/doc/outdated.md b/doc/outdated.md index 6931a0c42c2..fd30478cc98 100644 --- a/doc/outdated.md +++ b/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. diff --git a/doc/owner.md b/doc/owner.md index 98d313999fc..c637bea64b0 100644 --- a/doc/owner.md +++ b/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) diff --git a/doc/prefix.md b/doc/prefix.md new file mode 100644 index 00000000000..93da78b943a --- /dev/null +++ b/doc/prefix.md @@ -0,0 +1,10 @@ +npm-prefix(1) -- Display prefix +=============================== + +## SYNOPSIS + + npm prefix + +## DESCRIPTION + +Print the prefix to standard out. diff --git a/doc/prune.md b/doc/prune.md new file mode 100644 index 00000000000..7344753f2d0 --- /dev/null +++ b/doc/prune.md @@ -0,0 +1,15 @@ +npm-prune(1) -- Remove extraneous packages +========================================== + +## SYNOPSIS + + npm prune [ [[@] [[@] ...]] + npm rebuild [ [ ...]] * ``: The package to rebuild -* ``: - 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` diff --git a/doc/registry.md b/doc/registry.md index ab3a13b0b1a..0e30c9239c6 100644 --- a/doc/registry.md +++ b/doc/registry.md @@ -13,8 +13,8 @@ account information. The official public npm registry is at . It is powered by a CouchDB database at -. The code for the couchapp is -available at . npm user accounts +. The code for the couchapp is +available at . npm user accounts are CouchDB users, stored in the database. @@ -76,46 +76,3 @@ ask for help on the 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. - diff --git a/doc/restart.md b/doc/restart.md index 20a34535f1e..f052098be4e 100644 --- a/doc/restart.md +++ b/doc/restart.md @@ -3,7 +3,7 @@ npm-restart(1) -- Start a package ## SYNOPSIS - npm restart [@] [[@] ...] + npm restart ## DESCRIPTION diff --git a/doc/root.md b/doc/root.md new file mode 100644 index 00000000000..ce4e0411339 --- /dev/null +++ b/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. diff --git a/doc/run-script.md b/doc/run-script.md index 75cce699258..41ef5e78721 100644 --- a/doc/run-script.md +++ b/doc/run-script.md @@ -3,14 +3,12 @@ npm-run-script(1) -- Run arbitrary package scripts ## SYNOPSIS - npm run-script