diff options
| author | isaacs <i@izs.me> | 2011-03-21 23:55:53 +0300 |
|---|---|---|
| committer | isaacs <i@izs.me> | 2011-03-22 01:56:47 +0300 |
| commit | 0b249b688ccea8ab18aeeb382104a5a3102e9d62 (patch) | |
| tree | b9c85d76c65dfb46af22d243919e80c156da8744 /man1 | |
| parent | 5fb82016a9b0ba27a9d94600eaed5713c5ea9ac0 (diff) | |
make doc for 1.0
Diffstat (limited to 'man1')
45 files changed, 1952 insertions, 2350 deletions
diff --git a/man1/adduser.1 b/man1/adduser.1 index 3e8c71a4f..9b0683c81 100644 --- a/man1/adduser.1 +++ b/man1/adduser.1 @@ -18,41 +18,23 @@ Create or verify a user named \fB<username>\fR in the npm registry, and save the credentials to the \fB\|\.npmrc\fR file\. . .P -The username, password, and email are read in from prompts\. This command -cannot be scripted\. If you think you need to script the creation of new -users, or the authorization of existing ones, without human intervention, -please rethink your use case\. That\'s a very bad idea\. +The username, password, and email are read in from prompts\. . .P You may use this command to change your email address, but not username or password\. . .P +To reset your password, go to \fIhttp://admin\.npmjs\.org/\fR +. +.P You may use this command multiple times with the same user account to authorize on a new machine\. . .SH "CONFIGURATION" . -.SS "_auth" -A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\. -. -.P -If your config file is ever corrupted, you can set this manually by doing: -. -.IP "" 4 -. -.nf -npm adduser -. -.fi -. -.IP "" 0 -. .SS "registry" -Default: https://registry\.npmjs\.org/ +Default: http://registry\.npmjs\.org/ . .P The base URL of the npm package registry\. -. -.SS "username, _password" -Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":" diff --git a/man1/author.1 b/man1/author.1 new file mode 100644 index 000000000..51fd7c482 --- /dev/null +++ b/man1/author.1 @@ -0,0 +1,51 @@ +.\" Generated with Ronnjs/v0.1 +.\" http://github.com/kapouer/ronnjs/ +. +.TH "NPM\-OWNER" "1" "March 2011" "" "" +. +.SH "NAME" +\fBnpm-owner\fR \-\- Manage package owners +. +.SH "SYNOPSIS" +. +.nf +npm owner ls <package name> +npm owner add <user> <package name> +npm owner rm <user> <package name> +. +.fi +. +.SH "DESCRIPTION" +. +.IP "\(bu" 4 +ls: +List all the users who have access to modify a package and push new versions\. +Handy when you need to know who to bug for help\. +. +.IP "\(bu" 4 +add: +Add a new user as a maintainer of a package\. This user is enabled to modify +metadata, publish new versions, and add other owners\. +. +.IP "\(bu" 4 +rm: +Remove a user from the package owner list\. This immediately revokes their +privileges\. +. +.IP "" 0 +. +.P +Note that there is only one level of access\. Either you can modify a package, +or you can\'t\. Future versions may contain more fine\-grained access levels, but +that is not implemented at this time\. +. +.SH "SEE ALSO" +. +.IP "\(bu" 4 +npm\-publish(1) +. +.IP "\(bu" 4 +npm\-registry(1) +. +.IP "" 0 + diff --git a/man1/build.1 b/man1/build.1 index dd00f445b..ccce7315c 100644 --- a/man1/build.1 +++ b/man1/build.1 @@ -20,15 +20,10 @@ A folder containing a \fBpackage\.json\fR file in its root\. .IP "" 0 . .SH "DESCRIPTION" -This command should almost never need to be run directly\. It is an abstraction -of the functionality shared by both npm\-install(1) and npm\-link(1)\. +This is the plumbing command called by \fBnpm link\fR and \fBnpm install\fR\|\. . .P -This command creates the various interwoven links that ensure a package\'s contents -are available in the root appropriately, and that its dependencies are linked -appropriately\. -. -.SH "CONFIGURATION" +It should generally not be called directly\. . .SH "SEE ALSO" . diff --git a/man1/cache.1 b/man1/cache.1 index 86f28627e..3f347c0a8 100644 --- a/man1/cache.1 +++ b/man1/cache.1 @@ -14,7 +14,7 @@ npm cache add <folder> npm cache add <tarball url> npm cache add <name>@<version> npm cache ls [<path>] -npm cache clean [<name>[@<version>]] +npm cache clean [<path>] . .fi . @@ -22,54 +22,55 @@ npm cache clean [<name>[@<version>]] . .IP "\(bu" 4 add: -Access the local cache of package data\. This command is primarily +Add the specified package to the local cache\. This command is primarily intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly\. . -.IP -If two arguments are provided, then npm will fetch the data from the -registry\. This allows npm to use the filesystem as a local proxy to -the registry\. -. .IP "\(bu" 4 ls: -Show the data in the cache\. Additional arguments are joined together -in a path\-like fashion, but something like \fBnpm cache ls npm/0\.1\.5\fR is -acceptable as well\. +Show the data in the cache\. Argument is a path to show in the cache +folder\. Works a bit like the \fBfind\fR program, but limited by the \fBdepth\fR config\. . .IP "\(bu" 4 clean: -Delete data out of the cache for a specific package and version, all -versions of a package, or all data for all packages, depending on the -arguments supplied\. -. -.IP -This can be used if invalid data gets into the cache\. +Delete data out of the cache folder\. If an argument is provided, then +it specifies a subpath to delete\. If no argument is provided, then +the entire cache is cleared\. . .IP "" 0 . .SH "DETAILS" -npm stores data for a version of a package in \fB$ROOT/\.npm/\.cache/<name>/<version>\fR\|\. Three pieces of data are stored -in this folder: +npm stores cache data in \fB$HOME/\.npm\fR\|\. For each package that is added +to the cache, three pieces of information are stored in \fB{cache}/{name}/{version}\fR: . .IP "\(bu" 4 -package/: +\|\.\.\./package/: A folder containing the package contents as they appear in the tarball\. . .IP "\(bu" 4 -package\.json: +\|\.\.\./package\.json: The package\.json file, as npm sees it, with overlays applied and a _id attribute\. . .IP "\(bu" 4 -package\.tgz: +\|\.\.\./package\.tgz: The tarball for that version\. . .IP "" 0 . +.P +Additionally, whenever a registry request is made, a \fB\|\.cache\.json\fR file +is placed at the corresponding URI, to store the ETag and the requested +data\. +. +.P +Commands that make non\-essential registry requests (such as \fBsearch\fR and \fBview\fR, or the completion scripts) generally specify a minimum timeout\. +If the \fB\|\.cache\.json\fR file is younger than the specified timeout, then +they do not make an HTTP request to the registry\. +. .SH "CONFIGURATION" . -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR +.SS "cache" +Default: \fB$HOME/\.npm\fR on Posix, or \fB$HOME/npm\-cache\fR on Windows\. . .P -The root folder where packages are installed and npm keeps its data\. +The root cache folder\. diff --git a/man1/changelog.1 b/man1/changelog.1 index 759042ac5..79d48b61d 100644 --- a/man1/changelog.1 +++ b/man1/changelog.1 @@ -9,513 +9,94 @@ .SH "HISTORY" . .IP "\(bu" 4 -0\.0\.1: -Lots of sketches and false starts\. Abandoned a few times\. -. -.IP "\(bu" 4 -0\.0\.2: -Install worked mostly\. Still promise\-based\. -. -.IP "\(bu" 4 -0\.0\.3: -Converted to callbacks\. -. -.br -Mikeal Rogers wrote a registry for it\. -. -.IP "\(bu" 4 -0\.0\.4: -version dependencies -. -.br -link packages -. -.br -activation -. -.br -lifecycle scripts -. -.br -bin linking -. -.br -uninstallation -. -.IP "\(bu" 4 -0\.0\.5: -fix a few bugs in uninstall wrt dependent packages -. -.br -fix relative require()for nodejs modules installed with the "bin" field\. -. -.br -(issue #2) -. -.br -update to work with node 0\.1\.33 (aka net2) -. -.br -added publish and tag commands -. -.IP "\(bu" 4 -0\.0\.6: -set up a public registry -. -.br -send content\-length with registry PUTs +0\.0 . .br -adduser command (Mikeal Rogers) -. -.br -ini file stuff (Mikeal Rogers) +Lots of sketches and false starts\. Abandoned a few times\. . .br -env\-specific package\.json +Core functionality established\. . .br -added more info to npm\'s the package\.json (bugs, contributors, etc\.) +alpha\. . .IP "\(bu" 4 -0\.0\.7: -fixed a few bugs in semver -. -.br -refactor documentation -. -.br -add "help" command -. -.br -add install from registry +0\.1 . .br -everything else core -. -.br -push to beta -. -.IP "\(bu" 4 -0\.1\.0 \- 0\.1\.2: push to beta, and announce . .br -clean up some bugs around lifecycle scripts -. -.br -reduce reliance on makefile -. -.br -documentation updates -. -.br -Fixed DOA bugs -. -.br -Removed dependence on ronn -. -.IP "\(bu" 4 -0\.1\.3: -Changed a few details with configs (fix #5) -. -.br -Update adduser and publish to put author info in the data -. -.br -Use buffer api for file writes, hopefully fix #4 -. -.IP "\(bu" 4 -0\.1\.4 \- 0\.1\.5: -Fixes for a few more bugs and fix some documentation\. -. -.IP "\(bu" 4 -0\.1\.6 \- 0\.1\.7: -Add cache functionality -. -.br -Use couchdb attachments to host tarballs +documentation, caching, more robust script support . .br -Handle odd require\.paths more appropriately +ownership tracking in the registry (no more admin party!) . .br -Don\'t break on install if the man path is missing +more robust config and option parsing . .br -Support publishing or installing a folder or local tarball -. -.IP "\(bu" 4 -0\.1\.8: -Bugfixes -. -.br -Add start, stop, restart, and test commands -. -.IP "\(bu" 4 -0\.1\.9: -npm list enhancements -. -.br -fix the install bug -. -.IP "\(bu" 4 -0\.1\.10: -More errors found by Ryan Dahl and Kris Zyp -. -.br -Better uninstall and list behavior -. -.br -Docs for new developers\. -. -.br -Better tracking of ownership on the registry\. -. -.IP "\(bu" 4 -0\.1\.11: -Martyn Smith found a whole lot of bugs\. -. -.br -Make publish not die when the tarball is big\. -. -.br -"make uninstall" support -. -.IP "\(bu" 4 -0\.1\.12 \- 0\.1\.13: -Fix the downloading bug that was breaking the tarballs -. -.br -Update some docs -. -.IP "\(bu" 4 -0\.1\.14 \- 0\.1\.16: -Fix to stay in sync with node changes -. -.br -Put a special tag on link installs -. -.br -Modify semver comparison slightly -. -.br -add unpublish command -. -.br -Use the "drain" event properly for uploads -. -.br -Handle thrown errors +stabilize semver semantics . .br -Handle \.npmignore -. -.IP "\(bu" 4 -0\.1\.17: -Stabilization\. -. -.IP "\(bu" 4 -0\.1\.18: -Change a few default configurations +tests . .br -Add test harness +update command . .br -Default publish, install, and link to "\." if no arguments given -. -.IP "\(bu" 4 -0\.1\.19 \- 0\.1\.20: -Create a bunch of bugs -. -.br -Fix a bunch of bugs -. -.br -Some minor speed improvements -. -.IP "\(bu" 4 -0\.1\.21 \- 0\.1\.22: -Relative paths -. -.br -Support comments in package\.json -. -.br -Add owner name to ls output -. -.br -Add "owner" command to manage package owners -. -.br -Support hook scripts in \fB{root}/\.npm/\.hooks/\fR -. -.br -Initial support for config file relative to node executable -. -.br -Support for http proxies -. -.br -Documentation updates -. -.IP "\(bu" 4 -0\.1\.23: -update command \- This is huge\. +bundle command . .br Rollback for failed installations . .br -Install dependencies for link packages -. -.br -Silently read passwords for adduser -. -.br -Cascading configs: cli, env, user, global -. -.br -First pass at \fBnpm view\fR command -. -.IP "\(bu" 4 -0\.1\.24, 0\.1\.25: -Fix a bunch of things -. -.br -Cleanup, etc\. -. -.br -help via \-\-help, \-h, or \-? -. -.IP "\(bu" 4 -0\.1\.26: -"modules" hash in package\.json (Alex K\. Wolfe) -. -.br -Better "restart" command (Alex K Wolfe) -. -.br -Work on Cygwin -. -.br -Remove link packages properly -. -.br -Make several commands more parallel -. -.IP "\(bu" 4 -0\.1\.27: -Man pages handled with the "man" entry, or a "man" directory -. -.br -Install man pages in the "manroot" config dir -. -.br -Control log output with the "loglevel" config -. -.br -Support a "bin" directory of executables that get auto\-linked -. -.br -Un\-deprecate the "lib" directory\. -. -.br -Bug killing -. -.br -Split up the tar usage so it works on Solaris -. -.br -bundle command -. -.br -rebuild command +Solaris and Cygwin support . .IP "\(bu" 4 -0\.2\.0: -Lots more bug killing +0\.2 . .br +First allegedly "stable" release\. Various fixes found during the Node Knockout extravaganza . .br -Change all "name\-version" things to be "name@version" -. -.br -First allegedly "stable" release\. -. -.IP "\(bu" 4 -0\.2\.1: Minor updates and bugfixes . -.IP "\(bu" 4 -0\.2\.2: -Update "help" to work on Solaris -. -.br -Remove updated packages that don\'t have dependencies\. -. -.br -Allow implied suffixes on \.js bins -. -.br -Fix an "adduser" bug -. -.IP "\(bu" 4 -0\.2\.3: -Lots of documentation tweaks and cleanup -. -.br -Support || in version ranges -. -.IP "\(bu" 4 -0\.2\.4: -Contribution party! -. -.br -Better list whitespace -. -.br -Lots of config happiness -. .br -Ignore all major SCM folders by default +more complete semver functionality . .br -Handle proxies and hostnames with ports -. -.br -Better Bundling -. -.br -Add \'outdated\' command -. -.br -Better handling of "engines" field -. -.IP "\(bu" 4 -0\.2\.5: Make npm OK to use programmatically (Charlie Robbins) -. -.IP "\(bu" 4 -0\.2\.6: -More programmatic updates -. -.br recursive package removal . .br -tab completion -. -.IP "\(bu" 4 -0\.2\.7 \- 0\.2\.8: -Bundle treated like a first\-class citizen, and simplified -. -.br -Many bug fixes -. -.IP "\(bu" 4 -0\.2\.9: -npm version command +tab completion (Evan Meagher) . .br shasums on all tarballs . .br -More portable tar option usage -. -.br -Much beefed up bundle command -. -.br -Deep view command -. -.IP "\(bu" 4 -0\.2\.10: -npm edit command -. -.br -various stability bugfixes\. -. -.IP "\(bu" 4 -0\.2\.11: -~> and 1\.2\.x style version ranges -. -.br -complete tab completion: see \fBnpm help completion\fR (Evan Meagher) -. -.br explore command: see \fBnpm help explore\fR . .br docs command: see \fBnpm help docs\fR . .br -keywords and description in \fBnpm ls\fR -. -.br -Frequently asked questions at \fBnpm help faq\fR -. -.IP "\(bu" 4 -0\.2\.12: -Various bugfixes (0\.2\.11 was big, broke some stuff) -. -.br -\fBnpm faq\fR command (wrapper for \fBnpm help faq\fR) -. -.IP "\(bu" 4 -0\.2\.13: -Merry Xmas! -. -.br -Config setting on the command line with grace and gusto +Frequently asked questions at \fBnpm faq\fR +xmas easter egg . .br -Portability and stability fixes\. -. -.br -Mostly sort of works with Homebrew\-installed nodejs\. -. -.IP "\(bu" 4 -0\.2\.14: -A little bit of documentation overhaul\. +work with homebrew nodejs . .br Support for \fB"<name>":"<url>"\fR for dependencies\. . -.br -Fix for "unpublish" regression\. -. -.br -Support for "files" array\. -. -.br -Dependency info in lifecycle scripts\. -. -.br -More data validation\. -. .IP "\(bu" 4 -0\.2\.15 \- 0\.2\.17: -Added "\-\-force" for publish -. -.br -Support argless "unpublish" and "uninstall" in package dirs -. -.br -Document future stuff +0\.3 . .br -Remove support for "modules" hash -. -.br -Read package defaults when reading json -. -.IP "\(bu" 4 -0\.3\.0: -More correct permission/uid handling\. (Sudo is now encouraged!) +More correct permission/uid handling\. (Sudo now encouraged!) . .br Require node 0\.4\.0 @@ -527,17 +108,19 @@ Separate semver out into a separate utility\. Packages without "main" modules don\'t export modules\. . .br +Remove support for invalid JSON (since node doesn\'t support it) +. +.br No shims! (Still has symlinks, though) . .IP "\(bu" 4 -0\.3\.1\-0\.3\.5: -Ease up on permission forcing\. +1\.0 . .br -Fix bugs around proxy handling\. +Simplify configuration greatly\. . .br -Remove support for invalid JSON (since node doesn\'t support it) +Install locally (bundle by default) . .IP "" 0 diff --git a/man1/completion.1 b/man1/completion.1 index 55ed2b77e..7476a2d87 100644 --- a/man1/completion.1 +++ b/man1/completion.1 @@ -6,27 +6,22 @@ .SH "NAME" \fBnpm-completion\fR \-\- Tab Completion for npm . -.SH "DESCRIPTION" -You should set up tab completion for npm if you haven\'t already\. -There are a few ways to do this: -. -.IP "1" 4 -Add \fB\|\. /path/to/npm\-completion\.sh\fR to your ~/\.bashrc file\. OR: +.SH "SYNOPSIS" . -.IP "2" 4 -Create a symlink like this if you have automatic bash completion set up: \fBln \- /path/to/npm\-completion\.sh /etc/bash\-completion\.d/npm\fR -or, perhaps: \fBln \- /path/to/npm\-completion\.sh /usr/local/etc/bash\-completion\.d/npm\fR +.nf +npm completion >> ~/\.bashrc +npm completion >> ~/\.zshrc . -.IP "" 0 +.fi . -.P -If you\'re using a non\-bash shell (like zsh or ksh) then this might not work\. +.SH "DESCRIPTION" +Sets up a function that enables tab\-completion in all npm commands\. . .P -To get the path to the npm\-completion\.sh file, use \fBnpm explore npm pwd\fR\|\. +You may of course also pipe the relevant script to a file such as \fB/usr/local/etc/bash_completion\.d/npm\fR if you have a system that will +read that file for you\. . .P -It\'s a very new feature, and it would be great to get feedback on it\. -Hopefully, I\'ll be able to work out a way to install the completion script -automatically\. If you have any ideas about how that should work, then please -share them\. +When \fBCOMP_CWORD\fR, \fBCOMP_LINE\fR, and \fBCOMP_POINT\fR are defined in the +environment, \fBnpm completion\fR acts in "plumbing mode", and outputs +completions based on the arguments\. diff --git a/man1/config.1 b/man1/config.1 index 751a96d9e..ac266ca31 100644 --- a/man1/config.1 +++ b/man1/config.1 @@ -65,6 +65,9 @@ npm config set key value .P Sets the config key to the value\. . +.P +If value is omitted, then it sets it to "true"\. +. .SS "get" . .nf @@ -73,9 +76,7 @@ npm config get key .fi . .P -Echo the config value to stdout\. (NOTE: All the other npm logging is done to -stderr, so pipes should work properly, and you can do \fBnpm get key 2>/dev/null\fR -to print out JUST the config value\.) +Echo the config value to stdout\. . .SS "list" . @@ -105,7 +106,91 @@ npm config edit .fi . .P -Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\. +Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the +global config\. +. +.SH "Shorthands and Other CLI Niceties" +The following shorthands are parsed on the command\-line: +. +.IP "\(bu" 4 +\fB\-v\fR: \fB\-\-version\fR +. +.IP "\(bu" 4 +\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR, \fB\-H\fR: \fB\-\-usage\fR +. +.IP "\(bu" 4 +\fB\-s\fR, \fB\-\-silent\fR: \fB\-\-loglevel silent\fR +. +.IP "\(bu" 4 +\fB\-d\fR: \fB\-\-loglevel info\fR +. +.IP "\(bu" 4 +\fB\-dd\fR, \fB\-\-verbose\fR: \fB\-\-loglevel verbose\fR +. +.IP "\(bu" 4 +\fB\-ddd\fR: \fB\-\-loglevel silly\fR +. +.IP "\(bu" 4 +\fB\-g\fR: \fB\-\-global\fR +. +.IP "\(bu" 4 +\fB\-l\fR: \fB\-\-long\fR +. +.IP "\(bu" 4 +\fB\-p\fR, \fB\-\-porcelain\fR: \fB\-\-parseable\fR +. +.IP "\(bu" 4 +\fB\-reg\fR: \fB\-\-registry\fR +. +.IP "\(bu" 4 +\fB\-v\fR: \fB\-\-version\fR +. +.IP "\(bu" 4 +\fB\-f\fR: \fB\-\-force\fR +. +.IP "\(bu" 4 +\fB\-l\fR: \fB\-\-long\fR +. +.IP "\(bu" 4 +\fB\-desc\fR: \fB\-\-description\fR +. +.IP "\(bu" 4 +\fBll\fR and \fBla\fR commands: \fBls \-\-long\fR +. +.IP "" 0 +. +.P +If the specified configuration param resolves unambiguously to a known +configuration parameter, then it is expanded to that configuration +parameter\. For example: +. +.IP "" 4 +. +.nf +npm ls \-\-par +# same as: +npm ls \-\-parseable +. +.fi +. +.IP "" 0 +. +.P +If multiple single\-character shorthands are strung together, and the +resulting combination is unambiguously not some other configuration +param, then it is expanded to its various component pieces\. For +example: +. +.IP "" 4 +. +.nf +npm ls \-gpld +# same as: +npm ls \-\-global \-\-parseable \-\-long \-\-loglevel info +. +.fi +. +.IP "" 0 . .SH "Per\-Package Config Settings" When running scripts (see \fBnpm help scripts\fR) @@ -150,340 +235,547 @@ npm config set foo:port 80 . .SH "Config Settings" . -.SS "auto\-activate" -Default: true +.SS "browser" +. +.IP "\(bu" 4 +Default: OS X: \fB"open"\fR, others: \fB"google\-chrome"\fR +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Automatically activate a package after installation, if there is not an active -version already\. Set to "always" to always activate when installing\. +The browser that is called by the \fBnpm docs\fR command to open websites\. . -.SS "rebuild\-bundle" +.SS "cache" +. +.IP "\(bu" 4 +Default: Windows: \fB~/npm\-cache\fR, Posix: \fB~/\.npm\fR +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 +. +.P +The location of npm\'s cache directory\. See \fBnpm help cache\fR +. +.SS "color" +. +.IP "\(bu" 4 Default: true . +.IP "\(bu" 4 +Type: Boolean or \fB"always"\fR +. +.IP "" 0 +. .P -Set to some truish value to rebuild bundled dependencies after -installation\. +If false, never shows colors\. If \fB"always"\fR then always shows colors\. +If true, then only prints color codes for tty file descriptors\. . -.SS "recursive" -Default: false +.SS "depth" +. +.IP "\(bu" 4 +Default: Infinity +. +.IP "\(bu" 4 +Type: Number +. +.IP "" 0 . .P -Set to some truish value to recursively remove dependent packages\. For -example if foo depends on bar, and bar depends on baz, then: +The depth to go when recursing directories for \fBnpm ls\fR and \fBnpm cache ls\fR\|\. . -.IP "" 4 +.SS "description" . -.nf -npm uninstall baz \-\-recursive +.IP "\(bu" 4 +Default: true . -.fi +.IP "\(bu" 4 +Type: Boolean . .IP "" 0 . .P -will remove baz, bar, and foo\. +Whether or not to show the description in \fBnpm search\fR . -.SS "loglevel" -Default: "info" +.SS "dev" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The log level to show\. +Whether or not to install \fBdev\-dependencies\fR along with packages\. . .P -Each level maps to a numeric value, above which all logs must pass to be -seen\. So, setting it to "warn" shows "win", "error" and "warn" messages\. +Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is +set\. +. +.SS "editor" +. +.IP "\(bu" 4 +Default: \fBEDITOR\fR environment variable if set, or \fB"vi"\fR +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The log levels: +The command to run for \fBnpm edit\fR or \fBnpm config edit\fR\|\. +. +.SS "force" . .IP "\(bu" 4 -silent: Show no output\. Nothing\. If there is output on stderr, it\'s -because something is broken\. +Default: false . .IP "\(bu" 4 -win: Show the "npm ok" or "npm not ok", but that\'s all\. +Type: Boolean +. +.IP "" 0 +. +.P +Makes various commands more forceful\. . .IP "\(bu" 4 -error: Errors, usually with a stack trace\. +lifecycle script failure does not block progress\. . .IP "\(bu" 4 -warn: Things that you should probably be aware of\. +publishing clobbers previously published versions\. . .IP "\(bu" 4 -info: Helpful info\. +skips cache when requesting from the registry\. . .IP "\(bu" 4 -silly: Not\-helpful info\. (Lots of dumping whole objects and such\.) +prevents checks against clobbering non\-npm files\. . .IP "" 0 . -.P -Note that output to stdout is always printed\. This setting just modifies -what\'s logged to stderr\. +.SS "global" . -.SS "update\-dependents" -Default: true +.IP "\(bu" 4 +Default: false . -.P -Automatically update a package\'s dependencies after installation, if it is the -newest version installed\. Set to "always" to update dependents when a new -version is installed, even if it\'s not the newest\. +.IP "\(bu" 4 +Type: Boolean . -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR +.IP "" 0 . .P -The root folder where packages are installed and npm keeps its data\. +Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\. See \fBnpm help global\fR for more on the differences in behavior\. . -.SS "binroot" -Default: \fB$INSTALL_PREFIX/bin\fR +.IP "\(bu" 4 +packages are installed into the \fBprefix/node_modules\fR folder, instead of the +current working directory\. . -.P -The folder where executable programs are installed\. +.IP "\(bu" 4 +bin files are linked to \fBprefix/bin\fR . -.P -Set to "false" to not install executables +.IP "\(bu" 4 +man pages are linked to \fBprefix/share/man\fR . -.SS "manroot" -Default: $INSTALL_PREFIX/share/man +.IP "" 0 . -.P -The folder where man pages are installed\. +.SS "globalconfig" . -.P -Set to "false" to not install man pages\. +.IP "\(bu" 4 +Default: {prefix}/etc/npmrc . -.SS "registry" -Default: https://registry\.npmjs\.org/ +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The base URL of the npm package registry\. +The config file to read for global config options\. +. +.SS "group" +. +.IP "\(bu" 4 +Default: GID of the current process +. +.IP "\(bu" 4 +Type: String or Number . -.SS "_auth" -A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\. +.IP "" 0 . .P -If your config file is ever corrupted, you can set this manually by doing: +The group to use when running package scripts in global mode as the root +user\. . -.IP "" 4 +.SS "gzipbin" . -.nf -npm adduser +.IP "\(bu" 4 +Default: "gzip" . -.fi +.IP "\(bu" 4 +Type: path . .IP "" 0 . -.SS "username, _password" -Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":" +.P +The gzip binary . -.SS "proxy" -If proxy is available, then npm will access the registry via -the proxy server\. +.SS "logfd" +. +.IP "\(bu" 4 +Default: stderr file descriptor +. +.IP "\(bu" 4 +Type: Number or Stream +. +.IP "" 0 . .P -Example: +The location to write log output\. . -.IP "" 4 +.SS "loglevel" . -.nf -proxy = http://user:password@proxy\-server:8080 +.IP "\(bu" 4 +Default: "warn" . -.fi +.IP "\(bu" 4 +Type: String . -.IP "" 0 +.IP "\(bu" 4 +Values: "silent", "win", "error", "warn", "info", "verbose", "silly" . -.SS "tag" -Default: latest +.IP "" 0 . .P -If you ask npm to install a package and don\'t tell it a specific version, then -it will install the specified tag\. +What level of logs to report\. On failure, \fIall\fR logs are written to \fBnpm\-debug\.log\fR in the current working directory\. . -.P -Note: this has no effect on the npm\-tag(1) command\. +.SS "long" . -.SS "userconfig" -The default user configuration file is process\.env\.HOME+"/\.npmrc"\. +.IP "\(bu" 4 +Default: false . -.P -Note that this must be provided either in the cli or env settings\. Once the -userconfig is read, it is irrelevant\. +.IP "\(bu" 4 +Type: Boolean . -.SS "globalconfig" -The default global configuration file is resolved based on the location of the -node executable\. It is process\.execPath+"/\.\./\.\./etc/npmrc"\. In the canonical -NodeJS installation with \fBmake install\fR, this is \fB/usr/local/etc/npmrc\fR\|\. If you -put the node binary somewhere else (for instance, if you are using nvm or -nave), then it would be resolved relative to that location\. +.IP "" 0 . .P -Note that this must be provided in the cli, env, or userconfig settings\. Once -the globalconfig is read, this parameter is irrelevant\. +Whether or not to show extended information in \fBnpm ls\fR . -.SS "global" -If set to some truish value (for instance, by being the last cli flag or being -passed a literal \fBtrue\fR or \fB1\fR), and the \fBnpm config set\fR param is being -called, then the new configuration paramater is written global config file\. -Otherwise, they are saved to the user config file\. +.SS "node\-version" . -.SS "dev" -If set to a truish value, then it\'ll install the "devDependencies" as well as -"dependencies" when installing a package\. +.IP "\(bu" 4 +Default: process\.version . -.P -Note that devDependencies are \fIalways\fR installed when linking a package\. +.IP "\(bu" 4 +Type: semver . -.SS "tar" -Default: env\.TAR or "tar" +.IP "" 0 . .P -The name of a GNU\-compatible tar program on your system\. +The node version to use when checking package\'s "engines" hash\. . -.SS "gzip" -Default: env\.GZIPBIN or "gzip" +.SS "npat" . -.P -The name of a GNU\-compatible gzip program on your system\. +.IP "\(bu" 4 +Default: false . -.SS "usage" -If set to \fBtrue\fR, then this will tell help to print out the short usage statement -instead of the long manpage type thing\. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -This is set automatically if you invoke help like \fBnpm command \-?\fR\|\. +Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\. . -.SS "viewer" -Default: "man" +.SS "npaturl" . -.P -The program to use to view help content\. Set to "woman" to use the emacs troff viewer -by that name\. +.IP "\(bu" 4 +Default: Not yet implemented . -.SS "_exit" -Default: true +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -Whether or not to exit the process when the command is finished\. When -using npm programmatically, it\'s a good idea to set this to \fBfalse\fR -explicitly\. +The url to report npat test results\. . -.SS "logfd" -Default: Standard Error FD (2) +.SS "onload\-script" . -.P -The file descriptor (integer) or stream object where npm will write log -messages\. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +A node module to \fBrequire()\fR when npm loads\. Useful for programmatic +usage\. . .SS "outfd" -Default: Standard Output FD (1) +. +.IP "\(bu" 4 +Default: standard output file descriptor +. +.IP "\(bu" 4 +Type: Number or Stream +. +.IP "" 0 . .P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. +Where to write "normal" output\. This has no effect on log output\. +. +.SS "parseable" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +Whether or not to output parseable results from commands that write to +standard output\. . -.SS "color" -Default: true +.SS "prefix" +. +.IP "\(bu" 4 +Default: node\'s process\.installPrefix +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -Set to false to disable colorized output\. +The location to install global items\. If set on the command line, then +it forces non\-global commands to run in the specified folder\. +. +.SS "proxy" +. +.IP "\(bu" 4 +Default: "HTTP\fIPROXY" or "http\fRproxy" environment variable, or null +. +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +A proxy to use for outgoing http requests\. +. +.SS "rebuild\-bundle" . -.SS "tmproot" -Default: env\.TMPDIR or "/tmp" +.IP "\(bu" 4 +Default: true +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The folder where temporary files should be placed\. +Set to some truish value to rebuild bundled dependencies after +installation\. +. +.SS "registry" +. +.IP "\(bu" 4 +Default: https://registry\.npmjs\.org/ +. +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -npm creates a subfolder whenever it is run, and attempts to delete it -afterwards\. +The base URL of the npm package registry\. . -.SS "force" -Default: false +.SS "searchopts" +. +.IP "\(bu" 4 +Default: "" +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Set to a truish value to force uninstalling packages, even if they have -dependents\. +Space\-separated options that are always passed to search\. +. +.SS "searchexclude" +. +.IP "\(bu" 4 +Default: "" +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Note that setting \fBrecursive\fR is safer, because forcing uninstall can -create orphan packages that no longer function properly\. +Space\-separated options that limit the results from search\. . -.SS "editor" -Default: env\.EDITOR +.SS "shell" +. +.IP "\(bu" 4 +Default: SHELL environment variable, or "bash" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The program to use to edit files\. +The shell to run for the \fBnpm explore\fR command\. . -.SS "listexclude" -Default: null +.SS "tag" +. +.IP "\(bu" 4 +Default: latest +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -A whitespace separated list of strings which \fIprevent\fR items from being -shown to \fBnpm ls\fR\|\. +If you ask npm to install a package and don\'t tell it a specific version, then +it will install the specified tag\. . .P -For example, \fBnpm ls installed \-\-listexclude zombie\fR will show all -installed packages \fIexcept\fR zombie\. +Also the tag that is added to the package@version specified by the \fBnpm +tag\fR command, if no explicit tag is given\. . -.SS "listopts" -Default: "" +.SS "tar" . -.P -A whitespace\-separated list of extra args that are always passed to npm ls +.IP "\(bu" 4 +Default: TAR environment variable, or "tar" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -For example: \fBlistopts = remote\fR +The tar executable +. +.SS "tmp" +. +.IP "\(bu" 4 +Default: TMPDIR environment variable, or "/tmp" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -\fBnpm ls\fR +Where to store temporary files and folders\. All temp files are deleted +on success, but left behind on failure for forensic purposes\. +. +.SS "unsafe\-perm" +. +.IP "\(bu" 4 +Default: false if running as root, true otherwise +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The output here will always filter by remote +Set to true to suppress the UID/GID switching when running package +scripts\. If set explicitly to false, then installing as a non\-root user +will fail\. . -.SS "must\-install" -Default: true +.SS "usage" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -Set to false to not install over packages that already exist\. By -default, \fBnpm install foo\fR will fetch and install the latest version of \fBfoo\fR, even if it matches a version already installed\. +Set to show short usage output (like the \-H output) +instead of complete help when doing \fBnpm help\fR\|\. . -.SH "description" -Default: true +.SS "user" +. +.IP "\(bu" 4 +Default: "nobody" +. +.IP "\(bu" 4 +Type: String or Number +. +.IP "" 0 . .P -Show the package description in npm ls\. +The UID to set to when running package scripts as root\. +. +.SS "username" . -.SH "node\-version" -Default: \fBprocess\.version\fR from the node environment +.IP "\(bu" 4 +Default: null +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -An effective version of node to use when checking for "engines" -compliance\. +The username on the npm registry\. Set with \fBnpm adduser\fR +. +.SS "userconfig" +. +.IP "\(bu" 4 +Default: ~/\.npmrc on Posix, or ~/npm\-config on Windows +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -Set to null or false to suppress engine checking altogether\. +The location of user\-level configuration settings\. . -.SH "onload\-script" +.SS "version" +. +.IP "\(bu" 4 Default: false . +.IP "\(bu" 4 +Type: boolean +. +.IP "" 0 +. .P -A script to run when npm loads\. Use this to hook into various events in -the npm flow in a programmatic way, even when using npm from the command -line\. +If true, output the npm version and exit successfully\. +. +.P +Only relevant when specified explicitly on the command line\. +. +.SS "viewer" +. +.IP "\(bu" 4 +Default: "man" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -If false, then don\'t do any onload stuff\. +The program to use to view help content\. diff --git a/man1/deprecate.1 b/man1/deprecate.1 index 1a7e3ba8b..01b25f448 100644 --- a/man1/deprecate.1 +++ b/man1/deprecate.1 @@ -32,11 +32,3 @@ npm deprecate my\-thing@"< 0\.2\.3" "critical bug fixed in v0\.2\.3" . .P Note that you must be the package owner to deprecate something\. See the \fBowner\fR and \fBadduser\fR help topics\. -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ -. -.P -The base URL of the npm package registry\. diff --git a/man1/docs.1 b/man1/docs.1 index 3d68038c0..95a9bcdcd 100644 --- a/man1/docs.1 +++ b/man1/docs.1 @@ -16,7 +16,4 @@ npm docs <pkgname> .SH "DESCRIPTION" This command tries to guess at the likely location of a package\'s documentation URL, and then tries to open it using the \fB\-\-browser\fR -config param, which defaults to \fB"open"\fR because that works on a mac\. -. -.P -This is an experimental command\. It may disappear or change radically\. +config param\. diff --git a/man1/edit.1 b/man1/edit.1 index aebbf1d95..750d0ca71 100644 --- a/man1/edit.1 +++ b/man1/edit.1 @@ -22,19 +22,6 @@ After it has been edited, the package is rebuilt so as to pick up any changes in compiled packages\. . .P -Note: If you\'re finding yourself using this a lot, it\'s probably better -to use \fBnpm link\fR instead\. However, it is extremely handy when used in -conjunction with \fBnpm bundle\fR\|\. -. -.P -For instance, you can do \fBnpm bundle install connect\fR to install connect -into your package, and then \fBnpm bundle edit connect\fR to make a few -changes to your locally bundled copy\. -. -.SH "CONFIGURATION" -. -.SS "editor" -Default: env\.EDITOR -. -.P -The program to use to edit files\. +For instance, you can do \fBnpm install connect\fR to install connect +into your package, and then \fBnpm edit connect\fR to make a few +changes to your locally installed copy\. diff --git a/man1/faq.1 b/man1/faq.1 index 631680d81..8f3ceff38 100644 --- a/man1/faq.1 +++ b/man1/faq.1 @@ -19,32 +19,40 @@ I don\'t know yet\. Read the error output, and if you can\'t figure out what it means, do what it says and post a bug with all the information it asks for\. . -.P -If there doesn\'t seem to be enough output for your liking, run the -command with \fB\-\-loglevel verbose\fR or if you\'re really brave, \fB\-\-loglevel -silly\fR\|\. +.SH "Where does npm put stuff?" +See \fBnpm help folders\fR . -.SH "How do I make npm less noisy?" -\fBnpm config set loglevel error\fR +.SH "I installed something globally, but I can\'t `require()` it" +Install it locally\. . -.P -You can also set it to \fBwin\fR or \fBsilent\fR for even more quietness\. +.SH "I don\'t wanna\." +Ok, then do this: +. +.IP "" 4 +. +.nf +echo \'export NODE_PATH="\'$(npm root \-g)\'"\' >> ~/\.bashrc +\|\. ~/\.bashrc +. +.fi +. +.IP "" 0 . .SH "How do I list installed packages?" -\fBnpm ls installed\fR +\fBnpm ls\fR . .P If you just want to see the names, and not all the registry data, you can do: \fBnpm ls installed \-\-no\-registry\fR to turn off the registry\. . .SH "How do I search for packages?" -\fBnpm ls\fR +\fBnpm search\fR . .P Arguments are greps\. \fBnpm ls jsdom\fR shows jsdom packages\. . .SH "How do I update npm?" -\fBnpm update npm\fR +\fBnpm update npm \-g\fR . .P You can also update all outdated packages by doing \fBnpm update\fR without @@ -98,27 +106,8 @@ You\'ll most likely want to \fBnpm link\fR your development folder\. That\'s awesomely handy\. . .SH "Can I list a url as a dependency?" -No\. -. -.P -If you need to depend on something that isn\'t published, or a package -that is published, but which you\'ve modified slightly, you can do this\. -. -.P -The correct way is to do the following: -. -.IP "\(bu" 4 -add a \fB"name":"version"\fR entry to your package\.json file\. -. -.IP "\(bu" 4 -\fBnpm bundle install <pkg>\fR where \fB<pkg>\fR is a url or path to your -custom unpublished package\. -. -.IP "" 0 -. -.P -When installing your package, npm will skip over any dependencies that -are bundled\. +Yes\. It should be a url to a gzipped tarball containing a single folder +that has a package\.json in its root\. . .SH "OK, but can I list a git repo as a dependency?" No\. @@ -134,7 +123,7 @@ point in the future, but not likely\. The current system allows for a lot of use cases, and is very easy to maintain\. . .SH "How do I symlink to a dev folder so that I don\'t have to keep re\-installing?" -\fBnpm link\fR +See \fBnpm help link\fR . .SH "The package registry website\. What is that exactly?" See \fBnpm help registry\fR for more info\. @@ -149,8 +138,7 @@ The warnings will disappear when node supports uploading tarballs over https reliably\. . .SH "I forgot my password, and can\'t publish\. How do I reset it?" -Email \fIi@izs\.me\fR from the email address that you signed up with\. Then -wait a day or two maybe\. +Go to \fIhttp://admin\.npmjs\.org/\fR to reset it\. . .SH "I get ECONNREFUSED a lot\. What\'s up?" Either the registry is down, or node\'s DNS isn\'t able to reach out\. @@ -158,7 +146,7 @@ This happens a lot if you don\'t follow \fIall\fR the steps in the Cygwin setup doc\. . .P -To check if the registry is down, open up \fIhttp://registry\.npmjs\.org/\fR +To check if the registry is down, open up \fIhttp://registry\.npmjs\.org/\-/short\fR in a web browser\. This will also tell you if you are just unable to access the internet for some reason\. . diff --git a/man1/find.1 b/man1/find.1 index 4a75b7329..8432cde52 100644 --- a/man1/find.1 +++ b/man1/find.1 @@ -1,98 +1,58 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-LIST" "1" "March 2011" "" "" +.TH "NPM\-LS" "1" "March 2011" "" "" . .SH "NAME" -\fBnpm-list\fR \-\- List installed packages +\fBnpm-ls\fR \-\- List installed packages . .SH "SYNOPSIS" . .nf npm list npm ls +npm la +npm ll . .fi . .SH "DESCRIPTION" This command will print to stdout all the versions of packages that are -either installed or available in the registry, with their tags and whether -or not they\'re active and/or stable\. +installed, as well as their dependencies, in a tree\-structure\. . .P -To filter a single package or state, you can provide words to filter on -and highlight (if appropriate)\. For instance, to see all the stable -packages, you could do this: -. -.IP "" 4 -. -.nf -npm ls stable -. -.fi -. -.IP "" 0 +It does not take arguments\. . .P -Another common usage is to find the set of all packages that are -installed\. This can be accomplished by doing this: -. -.IP "" 4 -. -.nf -npm ls installed -. -.fi -. -.IP "" 0 -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ +It will print out extraneous, missing, and invalid packages\. . .P -The base URL of the npm package registry\. +When run as \fBll\fR or \fBla\fR, it shows extended information by default\. . -.SS "listopts" -Default: "" -. -.P -A whitespace\-separated list of extra args that are always passed to npm ls +.SH "CONFIGURATION" . -.P -For example: \fBlistopts = remote\fR +.SS "long" . -.P -\fBnpm ls\fR +.IP "\(bu" 4 +Default: false . -.P -The output here will always filter by remote +.IP "\(bu" 4 +Type: Boolean . -.SS "description" -Default: true +.IP "" 0 . .P -Show the package description in npm ls\. +Show extended information\. . -.SS "outfd" -Default: Standard Output FD (1) +.SS "parseable" . -.P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. +.IP "\(bu" 4 +Default: false . -.P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +.IP "\(bu" 4 +Type: Boolean . -.SS "color" -Default: true -. -.P -Set to false to disable colorized output\. +.IP "" 0 . .P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +Show parseable output instead of tree view\. diff --git a/man1/folders.1 b/man1/folders.1 index 39f06ac63..d07337381 100644 --- a/man1/folders.1 +++ b/man1/folders.1 @@ -7,113 +7,187 @@ \fBnpm-folders\fR \-\- Folder Structures Used by npm . .SH "DESCRIPTION" -Node modules and metadata live -in the \fBroot\fR setting\. Check \fBnpm help config\fR for more -on configuration options\. +npm puts various things on your computer\. That\'s its job\. . .P -\fBroot/foo\fR Symlink to the active version\'s module folder\. +This document will tell you what it puts where\. . -.P -\fBroot/foo@1\.0\.0/\fR Node modules for the foo package\. +.SS "prefix Configuration" +The \fBprefix\fR config defaults to node\'s \fBprocess\.installPrefix\fR\|\. On most +systems, this is \fB/usr/local\fR\|\. . .P -\fBroot/foo@1\.0\.0/{module\-name}\.js\fR Generated shim corresponding to a module -defined in the modules option\. The module shim requires \fBroot/\.npm/foo/1\.0\.0/package/{module\-path}\.js\fR +When the \fBglobal\fR flag is set, npm installs things into this prefix\. +When it is not set, it uses the root of the current package, or the +current working directory if not in a package already\. . -.P -The \fBmain\fR script is implemented by creating an \fBindex\.js\fR file in this folder\. +.SS "Node Modules" +Packages are droped into the \fBnode_modules\fR folder under the \fBprefix\fR\|\. +When installing locally, this means that you can \fBrequire("packagename")\fR to load its main module, or \fBrequire("packagename/path/to/sub/module")\fR to load other modules\. . .P -\fBroot/\.npm/foo\fR is where the stuff for package \fBfoo\fR would go\. +If you wish to install node modules globally which can be loaded via \fBrequire()\fR from anywhere, then add the \fBprefix/node_modules\fR folder to +your NODE_PATH environment variable\. . -.P -\fBroot/\.npm/foo/1\.0\.0/package\fR the contents of the tarball containing foo -version 1\.0\.0 +.SS "Executables" +When in global mode, executables are linked into \fBprefix/bin\fR\|\. . .P -\fBroot/\.npm/foo/1\.0\.0/main\.js\fR Generated file that exports the \fBmain\fR module in -foo\. This is a shim, not a symbolic link, so that relative paths will work -appropriately\. +When in local mode, executables are linked into \fBprefix/node_modules/\.bin\fR\|\. . -.P -\fBroot/\.npm/foo/active\fR symlink to the active version\. +.SS "Man Pages" +When in global mode, man pages are linked into \fBprefix/share/man\fR\|\. . .P -\fBroot/\.npm/foo/1\.0\.0/node_modules\fR links to the modules that foo depends upon\. -This is loaded into the require path first in the foo shims\. +When in local node, man pages are not installed\. . -.P -\fBroot/\.npm/foo/1\.0\.0/dependson\fR links to the package folders that foo depends -on\. This is here so that npm can access those packages programmatically\. +.SS "Cache" +See \fBnpm help cache\fR\|\. Cache files are stored in \fB~/\.npm\fR on Posix, or \fB~/npm\-cache\fR on Windows\. . .P -\fBroot/\.npm/foo/1\.0\.0/dependents\fR links to the packages that depend upon foo\. +This is controlled by the \fBcache\fR configuration param\. . -.P -\fBroot/\.npm/\.cache\fR the cache folder\. +.SS "Temp Files" +Temporary files are stored by default in the folder specified by the \fBtmp\fR config, which defaults to either the TMPDIR environment +variable, or \fB/tmp\fR\|\. . .P -\fBroot/\.npm/\.cache/foo/1\.0\.0/package\.json\fR the parsed package\.json for foo@1\.0\.0 +Temp files are given a unique folder under this root for each run of the +program, and are deleted upon successful exit\. . -.P -\fBroot/\.npm/\.cache/foo/1\.0\.0/package\.tgz\fR the tarball of foo@1\.0\.0 +.SH "More Information" +When you run \fBnpm install foo@1\.2\.3\fR it downloads and builds the +package, and then, if there is a package\.json file in the current +working directory, it copies it to \fB$PWD/node_modules/foo\fR, so that your +current package will get it when you do \fBrequire("foo")\fR\|\. . .P -\fBroot/\.npm/\.cache/foo/1\.0\.0/package\fR the untouched pristine copy of foo@1\.0\.0 +When this is done, it also installs all of foo\'s dependencies to \fB\|\./node_modules/foo/node_modules/\fR, so that it will get its dependencies +appropriately when it calls \fBrequire()\fR\|\. If foo depends on bar, and bar +depends on baz, then there will also be a \fB\|\./node_modules/foo/node_modules/bar/node_modules/baz\fR, and so on\. . .P -Executables are installed to the folder specified by the \fBbinroot\fR config\. +If there is not a package\.json in the current working directory, then +npm walks up the working dir parent paths looking for a package\.json, +indicating the root of a package, or a node_modules folder, +indicating an npm package deployment location, and then take the party to that +location\. This behavior may be suppressed by setting the \fBseek\-root\fR +config value to false\. . .P -\fBbinroot/foo\fR Symlink to the active version of the "foo" executable\. +If no package root is found, then a global installation is performed\. +The global installation may be supressed by setting the \fBglobal\fR +configuration to false, in which case, the install will fail\. . -.P -\fBbinroot/foo@1\.0\.0\fR An executable for foo at version 1\.0\.0\. Either a -symbolic link or a shim to a file in the foo package\. +.SS "Global Installation" +If the \fBglobal\fR configuration is set to true, or if it is not explicitly +set false and no suitable node_modules folder was found, then npm will +install packages "globally"\. . .P -Man pages are installed to the folder specified by the \fBmanroot\fR config\. -Man pages named something other than the package name are prefixed with -the package name\. +This means that the module contents are symlinked (or, on windows, +copied) from \fBroot/<name>/<version>/package\fR to \fBroot/node_modules/<name>\fR\|\. +. +.SS "Cycles, Conflicts, and Folder Parsimony" +Cycles are handled using the property of node\'s module system that it +walks up the directories looking for node\fImodules folders\. So, at every +stage, if a package is already installed in an ancestor node\fRmodules +folder, then it is not installed at the current location\. . .P -\fBmanroot/man1/foo\.1\fR Symlink to the section 1 manpage for the active -version of foo\. +Consider the case above, where \fBfoo \-> bar \-> baz\fR\|\. Imagine if, in +addition to that, baz depended on bar, so you\'d have: \fBfoo \-> bar \-> baz \-> bar \-> baz \.\.\.\fR\|\. However, since the folder +structure is: foo/node\fImodules/bar/node\fRmodules/baz, there\'s no need to +put another copy of bar into \.\.\./baz/node\fImodules, since when it calls +require("bar"), it will get the copy that is installed in +foo/node\fRmodules/bar\. . .P -\fBmanroot/man1/foo@1\.0\.0\.1\fR Section 1 man page for foo version 1\.0\.0 +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 \fBa/node_modules/b/node_modules/a\fR if the two +"a" packages are different versions\. However, without repeating the +exact same package multiple times, an infinite regress will always be +prevented\. . .P -\fBmanroot/man8/foo\-bar\.8\fR Symlink to a section 8 manpage for the active -version of foo\. +Another optimization can be made by installing dependencies at the +highest level possible, below the localized "target" folder\. . .P -\fBmanroot/man8/foo\-bar@1\.0\.0\.8\fR A section 8 manpage for foo version -1\.0\.0\. +For example, consider this dependency graph: . -.SH "CONFIGURATION" +.IP "" 4 . -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR +.nf +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 +. +.fi +. +.IP "" 0 . .P -The root folder where packages are installed and npm keeps its data\. +In this case, we might expect a folder structure like this: +. +.IP "" 4 +. +.nf +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) +. +.fi . -.SS "binroot" -Default: \fB$INSTALL_PREFIX/bin\fR +.IP "" 0 . .P -The folder where executable programs are installed\. +Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are +installed in foo\'s node_modules folder\. . .P -Set to "false" to not install executables +Bar has dependencies on baz and asdf, so those are installed in bar\'s +node\fImodules folder\. Baz has a dependency on quux, so that is installed +in its node\fRmodules folder\. . -.SS "manroot" -Default: $INSTALL_PREFIX/share/man +.P +Underneath bar, the \fBbaz\->quux\->bar\fR dependency creates a cycle\. +However, because \fBbar\fR is already in \fBquux\fR\'s ancestry, it does not +unpack another copy of bar into that folder\. +. +.P +Similarly, underneath \fBfoo\->baz\fR, the same cycle is gradually prevented +because \fBbar\fR\'s \fBquux\fR dependency is satisfied by its parent folder\. . .P -The folder where man pages are installed\. +For a graphical breakdown of what is installed where, use \fBnpm ls\fR\|\. +. +.SS "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 \fBbundledDependencies\fR array, then they will not be +included in the package tarball\. . .P -Set to "false" to not install man pages\. +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/man1/future-ideas/deploy.1 b/man1/future-ideas/deploy.1 deleted file mode 100644 index 2326c63d0..000000000 --- a/man1/future-ideas/deploy.1 +++ /dev/null @@ -1,49 +0,0 @@ -.\" Generated with Ronnjs/v0.1 -.\" http://github.com/kapouer/ronnjs/ -. -.TH "NPM\-DEPLOY" "1" "March 2011" "" "" -. -.SH "NAME" -\fBnpm-deploy\fR \-\- Deploy a package to a remote host -. -.SH "FUTURE" -This functionality does not yet exist\. -. -.SH "SUMMARY" -. -.nf -npm deploy <pkg> [\-\-host <hostname>] -. -.fi -. -.SH "DESCRIPTION" -This is a porcelain command\. It is equivalent to doing: -. -.IP "" 4 -. -.nf -npm publish \-\-registry $(npm config get host) <pkg> -npm remote install <pkg\-name>@<pkg\-version> -. -.fi -. -.IP "" 0 -. -.P -That is, it first publishes the package to the server specified -by the \fBhost\fR config, and then remotely installs that package -on the host\. -. -.SH "SEE ALSO" -. -.IP "\(bu" 4 -npm\-remote(1) -. -.IP "\(bu" 4 -npm\-site(1) -. -.IP "\(bu" 4 -npm\-publish(1) -. -.IP "" 0 - diff --git a/man1/future-ideas/new-module-system.1 b/man1/future-ideas/new-module-system.1 deleted file mode 100644 index 296f1573b..000000000 --- a/man1/future-ideas/new-module-system.1 +++ /dev/null @@ -1,334 +0,0 @@ -.\" Generated with Ronnjs/v0.1 -.\" http://github.com/kapouer/ronnjs/ -. -.TH "NPM\-FOLDERS" "1" "March 2011" "" "" -. -.SH "NAME" -\fBnpm-folders\fR \-\- Folder Structures Used by npm -. -.SH "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\. -. -.P -In particular, this is the scheme that will be used starting in npm@0\.3, -which will require node@0\.5\.0 or above\. -. -.SH "GOALS" -. -.IP "\(bu" 4 -Don\'t splat stuff across the filesystem so much\. Just specify a single -root location, and be done with it\. -. -.IP "\(bu" 4 -Work on windows\. -. -.IP "\(bu" 4 -Minimize shim/symlink usage\. -. -.IP "\(bu" 4 -Do not rely on any global system path for node modules\. -. -.IP "\(bu" 4 -Remove the "activation" concept\. -. -.IP "" 0 -. -.SH "DESCRIPTION" -npm metadata lives in the \fBroot\fR setting\. There is the cache folder, -and the contents of all installed packages\. -. -.P -The default npm root folder is \fB/usr/local/lib/npm\fR\|\. -. -.P -TODO: What should the root folder be on windows? -. -.SS "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\. -. -.P -Files and folders created in the cache are owned by the executing user, -often "root"\. -. -.P -Files are created with 0666 and folders with 0777, so that they can be -modified by any user\. -. -.IP "\(bu" 4 -\fBroot/cache\fR Cache folder -. -.IP "\(bu" 4 -\fBroot/cache/foo/cache\.json\fR Expirable cache of registry/foo json data -. -.IP "\(bu" 4 -\fBroot/cache/foo/1\.2\.3/package\fR Pristine copy of foo package contents -. -.IP "\(bu" 4 -\fBroot/cache/foo/1\.2\.3/package\.tgz\fR tarball of foo@1\.2\.3 -. -.IP "" 0 -. -.SS "Package folders" -In the npm root folder, package contents are unpacked, built, and then -moved into the desired location\. -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3\fR Metadata and contents of foo@1\.2\.3 -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3/package\fR Build location of foo@1\.2\.3 -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3/node_modules\fR Links to (or, on windows, copies of) -dependencies of foo@1\.2\.3 -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3/metadata\.json\fR Metadata about the foo package\. -. -.IP "" 0 -. -.SS "Installation in `node_modules` Folders" -When you run \fBnpm install foo@1\.2\.3\fR it downloads and builds the -package, and then, if there is a package\.json file in the current -working directory, it copies it to \fB$PWD/node_modules/foo\fR, so that your -current package will get it when you do \fBrequire("foo")\fR\|\. -. -.P -When this is done, it also installs all of foo\'s dependencies to \fB\|\./node_modules/foo/node_modules/\fR, so that it will get its dependencies -appropriately when it calls \fBrequire()\fR\|\. If foo depends on bar, and bar -depends on baz, then there will also be a \fB\|\./node_modules/foo/node_modules/bar/node_modules/baz\fR, and so on\. -. -.P -If there is not a package\.json in the current working directory, then -npm walks up the working dir parent paths looking for a package\.json, -indicating the root of a package, or a node_modules folder, -indicating an npm package deployment location, and then take the party to that -location\. This behavior may be suppressed by setting the \fBseek\-root\fR -config value to false\. -. -.P -If no package root is found, then a global installation is performed\. -The global installation may be supressed by setting the \fBglobal\fR -configuration to false, in which case, the install will fail\. -. -.SS "Global Installation" -If the \fBglobal\fR configuration is set to true, or if it is not explicitly -set false and no suitable node_modules folder was found, then npm will -install packages "globally"\. -. -.P -This means that the module contents are symlinked (or, on windows, -copied) from \fBroot/<name>/<version>/package\fR to \fBroot/node_modules/<name>\fR\|\. -. -.SS "Installing executables" -When installing globally, executables are linked (or, on windows, -shimmed with a \.bat file) to \fBroot/bin\fR\|\. -. -.P -When doing a -localized installation, executables are linked (or, on windows, shimmed) -to \fB\|\./node_modules/\.bin\fR\|\. This also applies to the case when a globally -installed package\'s dependents are being installed into it\. Basically, -whenever writing \fB\|\.\.\./node_modules/foo\fR, and the "foo" -package has an executable named "bar", it\'ll write it to \fB\|\.\.\./node_modules/\.bin/bar\fR\|\. -. -.P -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 \fB\|\./node_modules/\.bin\fR as the first item in the PATH environ\. -. -.SS "Installing manpages" -npm will install man pages to \fBroot/share/man\fR\|\. It is up to the user to -make sure that their man program searches this location\. -. -.SS "Cycles, Conflicts, and Folder Parsimony" -Cycles are handled using the property of node\'s module system that it -walks up the directories looking for node\fImodules folders\. So, at every -stage, if a package is already installed in an ancestor node\fRmodules -folder, then it is not installed at the current location\. -. -.P -Consider the case above, where \fBfoo \-> bar \-> baz\fR\|\. Imagine if, in -addition to that, baz depended on bar, so you\'d have: \fBfoo \-> bar \-> baz \-> bar \-> baz \.\.\.\fR\|\. However, since the folder -structure is: foo/node\fImodules/bar/node\fRmodules/baz, there\'s no need to -put another copy of bar into \.\.\./baz/node\fImodules, since when it calls -require("bar"), it will get the copy that is installed in -foo/node\fRmodules/bar\. -. -.P -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 \fBa/node_modules/b/node_modules/a\fR if the two -"a" packages are different versions\. However, without repeating the -exact same package multiple times, an infinite regress will always be -prevented\. -. -.P -Another optimization can be made by installing dependencies at the -highest level possible, below the localized "target" folder\. -. -.P -For example, consider this dependency graph: -. -.IP "" 4 -. -.nf -foo -+\-\- bar@1\.2\.3 -| +\-\- baz@2\.x -| | `\-\- quux@3\.x -| `\-\- asdf@* -`\-\- baz@1\.2\.3 - `\-\- quux@3\.x -. -.fi -. -.IP "" 0 -. -.P -In this case, we\'d expect a folder structure like this: -. -.IP "" 4 -. -.nf -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) -. -.fi -. -.IP "" 0 -. -.P -Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are -installed in foo\'s node_modules folder\. -. -.P -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\. -. -.P -Since bar@1\.2\.3 depends on asdf@*, a satisfying version is placed in -foo\'s node\fImodules folder\. It also depends on baz@2\.x, but this -conflicts with the version already installed in foo\'s node\fRmodules -folder, so it is installed into the node_modules folder under bar@1\.2\.3\. -. -.P -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\. -. -.SS "Snapshotting" -Whenever the \fBnpm snapshot\fR command is run, the package\.json file is -updated to include the versions of all of the packages in the \fB\|\./node_modules\fR folder as dependencies\. -. -.SS "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 \fBroot/node_modules/<name>/<version>/package\fR, then they will not be -included in the package tarball\. -. -.P -If the package has been modified, then it is left as\-is, and included in -the package\. -. -.P -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\. -. -.SS "Updating" -npm keeps track of every installation of foo@1\.2\.3 in \fBroot/packages/foo/1\.2\.3/metadata\.json\fR\|\. -. -.P -When updating in a package folder (see algorithm for determining this in -"Installation in \fBnode_modules\fR Folders"), npm updates the packages in -the local folder to the latest versions that are compatible with the -requirements in the package\.json file\. -. -.P -If global is set to \fB"super"\fR, then npm will attempt to update -all copies of packages installed anywhere and everywhere that it is -aware of\. -. -.P -If \fBglobal\fR is set to `true, or implied by not being in a package folder -at the time, then npm will update the globally installed packages\. -. -.P -If you do \fBnpm update foo\fR, and you\'re in a local package folder, but \fBfoo\fR is not installed there, and it \fIis\fR installed globally, then that -will be equivalent to doing \fBnpm update foo \-\-global\fR\|\. -. -.SS "Uninstalling" -Uninstalling works like updating\. -. -.P -If global is set to "super", then it removes all traces from everywhere\. -. -.P -If global is set to "true", or implied, then it removes the global copy\. -. -.P -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\. -. -.SS "Linking" -When \fBnpm link\fR is run without any arguments in a package folder, then a -symbolic link is created from that folder to \fBroot/<name>/LINK\fR\|\. -Additionally, its package dependencies are installed to its -\|\./node_modules folder as necessary\. -. -.P -When \fBnpm link <name>\fR is run in another package folder, a symbolic -link is created from \fBroot/<name>/LINK\fR to \fB\|\./node_modules/<name>\fR, 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\.) -. -.P -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\. -. -.TP -npm link use case -. -.IP "" 4 -. -.nf -# 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") -. -.fi -. -.IP "" 0 -. -.TP -link on Windows -.Not sure how this will work\. Maybe linking simply isn\'t possible? diff --git a/man1/future-ideas/remote.1 b/man1/future-ideas/remote.1 deleted file mode 100644 index 453eecb2c..000000000 --- a/man1/future-ideas/remote.1 +++ /dev/null @@ -1,28 +0,0 @@ -.\" Generated with Ronnjs/v0.1 -.\" http://github.com/kapouer/ronnjs/ -. -.TH "NPM\-REMOTE" "1" "March 2011" "" "" -. -.SH "NAME" -\fBnpm-remote\fR \-\- Execute commands on a remote machine -. -.SH "FUTURE" -This functionality does not yet exist\. -. -.SH "SYNOPSIS" -. -.nf -npm remote <commands> -. -.fi -. -.SH "DESCRIPTION" -Run a command on a remote npm site instance\. -. -.P -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\. -. -.P -It uses the \fBhost\fR config to know where to do things\. diff --git a/man1/future-ideas/site.1 b/man1/future-ideas/site.1 deleted file mode 100644 index 023cfa2b9..000000000 --- a/man1/future-ideas/site.1 +++ /dev/null @@ -1,79 +0,0 @@ -.\" Generated with Ronnjs/v0.1 -.\" http://github.com/kapouer/ronnjs/ -. -.TH "NPM\-SITE" "1" "March 2011" "" "" -. -.SH "NAME" -\fBnpm-site\fR \-\- Run the npm web site -. -.SH "FUTURE" -This functionality does not yet exist\. -. -.SH "SYNOPSIS" -. -.nf -npm site [ start | stop ] -. -.fi -. -.SH "DESCRIPTION" -This starts up npm in "site" mode\. The following configs are relevant, -and can either be specified in the \fB\|\.npmrc\fR file, or as command line -options\. -. -.IP "\(bu" 4 -userfile: -A file containing the encrypted authorization info for all users\. If -specified, then this is used for \fBnpm adduser\fR requests -to this registry\. -. -.IP "\(bu" 4 -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\. -. -.IP "\(bu" 4 -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" -. -.IP "\(bu" 4 -registry: -If a package is not found, then its contents will be fetched from the -upstream registry, and cached for future retrieval\. -. -.IP -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\. -. -.IP "" 0 -. -.P -The content for the site is stored in the npm cache directory, which is -inside the folder used for the \fBroot\fR setting, at \fB{root}/\.npm/\.cache\fR\|\. -It is organized in a simple hierarchical folder structure corresponding -to the web service URLs that npm uses\. -. -.SH "TCP Server" -The TCP server starts up to support the \fBnpm remote\fR command, if there is -a valid admin userlist\. -. -.SH "NOTE" -This also is what happens when you do \fBnpm start npm\fR\|\. -. -.SH "SEE ALSO" -. -.IP "\(bu" 4 -npm\-remote(1) -. -.IP "\(bu" 4 -npm\-config(1) -. -.IP "" 0 - diff --git a/man1/get.1 b/man1/get.1 index 751a96d9e..ac266ca31 100644 --- a/man1/get.1 +++ b/man1/get.1 @@ -65,6 +65,9 @@ npm config set key value .P Sets the config key to the value\. . +.P +If value is omitted, then it sets it to "true"\. +. .SS "get" . .nf @@ -73,9 +76,7 @@ npm config get key .fi . .P -Echo the config value to stdout\. (NOTE: All the other npm logging is done to -stderr, so pipes should work properly, and you can do \fBnpm get key 2>/dev/null\fR -to print out JUST the config value\.) +Echo the config value to stdout\. . .SS "list" . @@ -105,7 +106,91 @@ npm config edit .fi . .P -Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\. +Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the +global config\. +. +.SH "Shorthands and Other CLI Niceties" +The following shorthands are parsed on the command\-line: +. +.IP "\(bu" 4 +\fB\-v\fR: \fB\-\-version\fR +. +.IP "\(bu" 4 +\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR, \fB\-H\fR: \fB\-\-usage\fR +. +.IP "\(bu" 4 +\fB\-s\fR, \fB\-\-silent\fR: \fB\-\-loglevel silent\fR +. +.IP "\(bu" 4 +\fB\-d\fR: \fB\-\-loglevel info\fR +. +.IP "\(bu" 4 +\fB\-dd\fR, \fB\-\-verbose\fR: \fB\-\-loglevel verbose\fR +. +.IP "\(bu" 4 +\fB\-ddd\fR: \fB\-\-loglevel silly\fR +. +.IP "\(bu" 4 +\fB\-g\fR: \fB\-\-global\fR +. +.IP "\(bu" 4 +\fB\-l\fR: \fB\-\-long\fR +. +.IP "\(bu" 4 +\fB\-p\fR, \fB\-\-porcelain\fR: \fB\-\-parseable\fR +. +.IP "\(bu" 4 +\fB\-reg\fR: \fB\-\-registry\fR +. +.IP "\(bu" 4 +\fB\-v\fR: \fB\-\-version\fR +. +.IP "\(bu" 4 +\fB\-f\fR: \fB\-\-force\fR +. +.IP "\(bu" 4 +\fB\-l\fR: \fB\-\-long\fR +. +.IP "\(bu" 4 +\fB\-desc\fR: \fB\-\-description\fR +. +.IP "\(bu" 4 +\fBll\fR and \fBla\fR commands: \fBls \-\-long\fR +. +.IP "" 0 +. +.P +If the specified configuration param resolves unambiguously to a known +configuration parameter, then it is expanded to that configuration +parameter\. For example: +. +.IP "" 4 +. +.nf +npm ls \-\-par +# same as: +npm ls \-\-parseable +. +.fi +. +.IP "" 0 +. +.P +If multiple single\-character shorthands are strung together, and the +resulting combination is unambiguously not some other configuration +param, then it is expanded to its various component pieces\. For +example: +. +.IP "" 4 +. +.nf +npm ls \-gpld +# same as: +npm ls \-\-global \-\-parseable \-\-long \-\-loglevel info +. +.fi +. +.IP "" 0 . .SH "Per\-Package Config Settings" When running scripts (see \fBnpm help scripts\fR) @@ -150,340 +235,547 @@ npm config set foo:port 80 . .SH "Config Settings" . -.SS "auto\-activate" -Default: true +.SS "browser" +. +.IP "\(bu" 4 +Default: OS X: \fB"open"\fR, others: \fB"google\-chrome"\fR +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Automatically activate a package after installation, if there is not an active -version already\. Set to "always" to always activate when installing\. +The browser that is called by the \fBnpm docs\fR command to open websites\. . -.SS "rebuild\-bundle" +.SS "cache" +. +.IP "\(bu" 4 +Default: Windows: \fB~/npm\-cache\fR, Posix: \fB~/\.npm\fR +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 +. +.P +The location of npm\'s cache directory\. See \fBnpm help cache\fR +. +.SS "color" +. +.IP "\(bu" 4 Default: true . +.IP "\(bu" 4 +Type: Boolean or \fB"always"\fR +. +.IP "" 0 +. .P -Set to some truish value to rebuild bundled dependencies after -installation\. +If false, never shows colors\. If \fB"always"\fR then always shows colors\. +If true, then only prints color codes for tty file descriptors\. . -.SS "recursive" -Default: false +.SS "depth" +. +.IP "\(bu" 4 +Default: Infinity +. +.IP "\(bu" 4 +Type: Number +. +.IP "" 0 . .P -Set to some truish value to recursively remove dependent packages\. For -example if foo depends on bar, and bar depends on baz, then: +The depth to go when recursing directories for \fBnpm ls\fR and \fBnpm cache ls\fR\|\. . -.IP "" 4 +.SS "description" . -.nf -npm uninstall baz \-\-recursive +.IP "\(bu" 4 +Default: true . -.fi +.IP "\(bu" 4 +Type: Boolean . .IP "" 0 . .P -will remove baz, bar, and foo\. +Whether or not to show the description in \fBnpm search\fR . -.SS "loglevel" -Default: "info" +.SS "dev" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The log level to show\. +Whether or not to install \fBdev\-dependencies\fR along with packages\. . .P -Each level maps to a numeric value, above which all logs must pass to be -seen\. So, setting it to "warn" shows "win", "error" and "warn" messages\. +Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is +set\. +. +.SS "editor" +. +.IP "\(bu" 4 +Default: \fBEDITOR\fR environment variable if set, or \fB"vi"\fR +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The log levels: +The command to run for \fBnpm edit\fR or \fBnpm config edit\fR\|\. +. +.SS "force" . .IP "\(bu" 4 -silent: Show no output\. Nothing\. If there is output on stderr, it\'s -because something is broken\. +Default: false . .IP "\(bu" 4 -win: Show the "npm ok" or "npm not ok", but that\'s all\. +Type: Boolean +. +.IP "" 0 +. +.P +Makes various commands more forceful\. . .IP "\(bu" 4 -error: Errors, usually with a stack trace\. +lifecycle script failure does not block progress\. . .IP "\(bu" 4 -warn: Things that you should probably be aware of\. +publishing clobbers previously published versions\. . .IP "\(bu" 4 -info: Helpful info\. +skips cache when requesting from the registry\. . .IP "\(bu" 4 -silly: Not\-helpful info\. (Lots of dumping whole objects and such\.) +prevents checks against clobbering non\-npm files\. . .IP "" 0 . -.P -Note that output to stdout is always printed\. This setting just modifies -what\'s logged to stderr\. +.SS "global" . -.SS "update\-dependents" -Default: true +.IP "\(bu" 4 +Default: false . -.P -Automatically update a package\'s dependencies after installation, if it is the -newest version installed\. Set to "always" to update dependents when a new -version is installed, even if it\'s not the newest\. +.IP "\(bu" 4 +Type: Boolean . -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR +.IP "" 0 . .P -The root folder where packages are installed and npm keeps its data\. +Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\. See \fBnpm help global\fR for more on the differences in behavior\. . -.SS "binroot" -Default: \fB$INSTALL_PREFIX/bin\fR +.IP "\(bu" 4 +packages are installed into the \fBprefix/node_modules\fR folder, instead of the +current working directory\. . -.P -The folder where executable programs are installed\. +.IP "\(bu" 4 +bin files are linked to \fBprefix/bin\fR . -.P -Set to "false" to not install executables +.IP "\(bu" 4 +man pages are linked to \fBprefix/share/man\fR . -.SS "manroot" -Default: $INSTALL_PREFIX/share/man +.IP "" 0 . -.P -The folder where man pages are installed\. +.SS "globalconfig" . -.P -Set to "false" to not install man pages\. +.IP "\(bu" 4 +Default: {prefix}/etc/npmrc . -.SS "registry" -Default: https://registry\.npmjs\.org/ +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The base URL of the npm package registry\. +The config file to read for global config options\. +. +.SS "group" +. +.IP "\(bu" 4 +Default: GID of the current process +. +.IP "\(bu" 4 +Type: String or Number . -.SS "_auth" -A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\. +.IP "" 0 . .P -If your config file is ever corrupted, you can set this manually by doing: +The group to use when running package scripts in global mode as the root +user\. . -.IP "" 4 +.SS "gzipbin" . -.nf -npm adduser +.IP "\(bu" 4 +Default: "gzip" . -.fi +.IP "\(bu" 4 +Type: path . .IP "" 0 . -.SS "username, _password" -Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":" +.P +The gzip binary . -.SS "proxy" -If proxy is available, then npm will access the registry via -the proxy server\. +.SS "logfd" +. +.IP "\(bu" 4 +Default: stderr file descriptor +. +.IP "\(bu" 4 +Type: Number or Stream +. +.IP "" 0 . .P -Example: +The location to write log output\. . -.IP "" 4 +.SS "loglevel" . -.nf -proxy = http://user:password@proxy\-server:8080 +.IP "\(bu" 4 +Default: "warn" . -.fi +.IP "\(bu" 4 +Type: String . -.IP "" 0 +.IP "\(bu" 4 +Values: "silent", "win", "error", "warn", "info", "verbose", "silly" . -.SS "tag" -Default: latest +.IP "" 0 . .P -If you ask npm to install a package and don\'t tell it a specific version, then -it will install the specified tag\. +What level of logs to report\. On failure, \fIall\fR logs are written to \fBnpm\-debug\.log\fR in the current working directory\. . -.P -Note: this has no effect on the npm\-tag(1) command\. +.SS "long" . -.SS "userconfig" -The default user configuration file is process\.env\.HOME+"/\.npmrc"\. +.IP "\(bu" 4 +Default: false . -.P -Note that this must be provided either in the cli or env settings\. Once the -userconfig is read, it is irrelevant\. +.IP "\(bu" 4 +Type: Boolean . -.SS "globalconfig" -The default global configuration file is resolved based on the location of the -node executable\. It is process\.execPath+"/\.\./\.\./etc/npmrc"\. In the canonical -NodeJS installation with \fBmake install\fR, this is \fB/usr/local/etc/npmrc\fR\|\. If you -put the node binary somewhere else (for instance, if you are using nvm or -nave), then it would be resolved relative to that location\. +.IP "" 0 . .P -Note that this must be provided in the cli, env, or userconfig settings\. Once -the globalconfig is read, this parameter is irrelevant\. +Whether or not to show extended information in \fBnpm ls\fR . -.SS "global" -If set to some truish value (for instance, by being the last cli flag or being -passed a literal \fBtrue\fR or \fB1\fR), and the \fBnpm config set\fR param is being -called, then the new configuration paramater is written global config file\. -Otherwise, they are saved to the user config file\. +.SS "node\-version" . -.SS "dev" -If set to a truish value, then it\'ll install the "devDependencies" as well as -"dependencies" when installing a package\. +.IP "\(bu" 4 +Default: process\.version . -.P -Note that devDependencies are \fIalways\fR installed when linking a package\. +.IP "\(bu" 4 +Type: semver . -.SS "tar" -Default: env\.TAR or "tar" +.IP "" 0 . .P -The name of a GNU\-compatible tar program on your system\. +The node version to use when checking package\'s "engines" hash\. . -.SS "gzip" -Default: env\.GZIPBIN or "gzip" +.SS "npat" . -.P -The name of a GNU\-compatible gzip program on your system\. +.IP "\(bu" 4 +Default: false . -.SS "usage" -If set to \fBtrue\fR, then this will tell help to print out the short usage statement -instead of the long manpage type thing\. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -This is set automatically if you invoke help like \fBnpm command \-?\fR\|\. +Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\. . -.SS "viewer" -Default: "man" +.SS "npaturl" . -.P -The program to use to view help content\. Set to "woman" to use the emacs troff viewer -by that name\. +.IP "\(bu" 4 +Default: Not yet implemented . -.SS "_exit" -Default: true +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -Whether or not to exit the process when the command is finished\. When -using npm programmatically, it\'s a good idea to set this to \fBfalse\fR -explicitly\. +The url to report npat test results\. . -.SS "logfd" -Default: Standard Error FD (2) +.SS "onload\-script" . -.P -The file descriptor (integer) or stream object where npm will write log -messages\. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +A node module to \fBrequire()\fR when npm loads\. Useful for programmatic +usage\. . .SS "outfd" -Default: Standard Output FD (1) +. +.IP "\(bu" 4 +Default: standard output file descriptor +. +.IP "\(bu" 4 +Type: Number or Stream +. +.IP "" 0 . .P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. +Where to write "normal" output\. This has no effect on log output\. +. +.SS "parseable" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +Whether or not to output parseable results from commands that write to +standard output\. . -.SS "color" -Default: true +.SS "prefix" +. +.IP "\(bu" 4 +Default: node\'s process\.installPrefix +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -Set to false to disable colorized output\. +The location to install global items\. If set on the command line, then +it forces non\-global commands to run in the specified folder\. +. +.SS "proxy" +. +.IP "\(bu" 4 +Default: "HTTP\fIPROXY" or "http\fRproxy" environment variable, or null +. +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +A proxy to use for outgoing http requests\. +. +.SS "rebuild\-bundle" . -.SS "tmproot" -Default: env\.TMPDIR or "/tmp" +.IP "\(bu" 4 +Default: true +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The folder where temporary files should be placed\. +Set to some truish value to rebuild bundled dependencies after +installation\. +. +.SS "registry" +. +.IP "\(bu" 4 +Default: https://registry\.npmjs\.org/ +. +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -npm creates a subfolder whenever it is run, and attempts to delete it -afterwards\. +The base URL of the npm package registry\. . -.SS "force" -Default: false +.SS "searchopts" +. +.IP "\(bu" 4 +Default: "" +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Set to a truish value to force uninstalling packages, even if they have -dependents\. +Space\-separated options that are always passed to search\. +. +.SS "searchexclude" +. +.IP "\(bu" 4 +Default: "" +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Note that setting \fBrecursive\fR is safer, because forcing uninstall can -create orphan packages that no longer function properly\. +Space\-separated options that limit the results from search\. . -.SS "editor" -Default: env\.EDITOR +.SS "shell" +. +.IP "\(bu" 4 +Default: SHELL environment variable, or "bash" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The program to use to edit files\. +The shell to run for the \fBnpm explore\fR command\. . -.SS "listexclude" -Default: null +.SS "tag" +. +.IP "\(bu" 4 +Default: latest +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -A whitespace separated list of strings which \fIprevent\fR items from being -shown to \fBnpm ls\fR\|\. +If you ask npm to install a package and don\'t tell it a specific version, then +it will install the specified tag\. . .P -For example, \fBnpm ls installed \-\-listexclude zombie\fR will show all -installed packages \fIexcept\fR zombie\. +Also the tag that is added to the package@version specified by the \fBnpm +tag\fR command, if no explicit tag is given\. . -.SS "listopts" -Default: "" +.SS "tar" . -.P -A whitespace\-separated list of extra args that are always passed to npm ls +.IP "\(bu" 4 +Default: TAR environment variable, or "tar" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -For example: \fBlistopts = remote\fR +The tar executable +. +.SS "tmp" +. +.IP "\(bu" 4 +Default: TMPDIR environment variable, or "/tmp" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -\fBnpm ls\fR +Where to store temporary files and folders\. All temp files are deleted +on success, but left behind on failure for forensic purposes\. +. +.SS "unsafe\-perm" +. +.IP "\(bu" 4 +Default: false if running as root, true otherwise +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The output here will always filter by remote +Set to true to suppress the UID/GID switching when running package +scripts\. If set explicitly to false, then installing as a non\-root user +will fail\. . -.SS "must\-install" -Default: true +.SS "usage" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -Set to false to not install over packages that already exist\. By -default, \fBnpm install foo\fR will fetch and install the latest version of \fBfoo\fR, even if it matches a version already installed\. +Set to show short usage output (like the \-H output) +instead of complete help when doing \fBnpm help\fR\|\. . -.SH "description" -Default: true +.SS "user" +. +.IP "\(bu" 4 +Default: "nobody" +. +.IP "\(bu" 4 +Type: String or Number +. +.IP "" 0 . .P -Show the package description in npm ls\. +The UID to set to when running package scripts as root\. +. +.SS "username" . -.SH "node\-version" -Default: \fBprocess\.version\fR from the node environment +.IP "\(bu" 4 +Default: null +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -An effective version of node to use when checking for "engines" -compliance\. +The username on the npm registry\. Set with \fBnpm adduser\fR +. +.SS "userconfig" +. +.IP "\(bu" 4 +Default: ~/\.npmrc on Posix, or ~/npm\-config on Windows +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -Set to null or false to suppress engine checking altogether\. +The location of user\-level configuration settings\. . -.SH "onload\-script" +.SS "version" +. +.IP "\(bu" 4 Default: false . +.IP "\(bu" 4 +Type: boolean +. +.IP "" 0 +. .P -A script to run when npm loads\. Use this to hook into various events in -the npm flow in a programmatic way, even when using npm from the command -line\. +If true, output the npm version and exit successfully\. +. +.P +Only relevant when specified explicitly on the command line\. +. +.SS "viewer" +. +.IP "\(bu" 4 +Default: "man" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -If false, then don\'t do any onload stuff\. +The program to use to view help content\. diff --git a/man1/install.1 b/man1/install.1 index 0119b278a..df19e3e26 100644 --- a/man1/install.1 +++ b/man1/install.1 @@ -9,6 +9,7 @@ .SH "SYNOPSIS" . .nf +npm install (with no args in a package dir) npm install <tarball file> npm install <tarball url> npm install <folder> @@ -20,8 +21,14 @@ npm install <name>@<version range> .fi . .SH "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\. +. +.IP "\(bu" 4 +npm install (in package directory): +Install the dependencies in the local node_modules folder\. +. +.IP +In global mode, it is the same as \fBnpm install $PWD\fR . .IP "\(bu" 4 npm install \fB<tarball file>\fR: @@ -52,8 +59,7 @@ Example: . .IP "\(bu" 4 npm install \fB<name>\fR: -Do a \fB<name>@<tag>\fR install, where \fB<tag>\fR is the "tag" config from either your -\|\.npmrc file, or the \-\-tag argument on the command line\. +Do a \fB<name>@<tag>\fR install, where \fB<tag>\fR is the "tag" config\. (See \fBnpm help config\fR) . .IP Example: @@ -102,7 +108,8 @@ Example: .IP "" 0 . .P -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: . .IP "" 4 . @@ -117,7 +124,8 @@ npm install sax@">=0\.1\.0 <0\.2\.0" bench supervisor The \fB\-\-tag\fR argument will apply to all of the specified install targets\. . .P -The \fB\-\-force\fR argument will force npm to fetch remote resources even if a local copy exists on disk\. +The \fB\-\-force\fR argument will force npm to fetch remote resources even if a +local copy exists on disk\. . .IP "" 4 . @@ -128,89 +136,6 @@ npm install sax \-\-force . .IP "" 0 . -.SH "CONFIGURATION" -. -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR -. -.P -The root folder where packages are installed and npm keeps its data\. -. -.SS "binroot" -Default: \fB$INSTALL_PREFIX/bin\fR -. -.P -The folder where executable programs are installed\. -. -.P -Set to "false" to not install executables -. -.SS "manroot" -Default: $INSTALL_PREFIX/share/man -. -.P -The folder where man pages are installed\. -. -.P -Set to "false" to not install man pages\. -. -.SS "registry" -Default: https://registry\.npmjs\.org/ -. -.P -The base URL of the npm package registry\. -. -.SS "tag" -Default: latest -. -.P -If you ask npm to install a package and don\'t tell it a specific version, then -it will install the specified tag\. -. -.P -Note: this has no effect on the npm\-tag(1) command\. -. -.SS "dev" -If set to a truish value, then it\'ll install the "devDependencies" as well as -"dependencies" when installing a package\. -. -.P -Note that devDependencies are \fIalways\fR installed when linking a package\. -. -.SS "tar" -Default: env\.TAR or "tar" -. -.P -The name of a GNU\-compatible tar program on your system\. -. -.SS "gzip" -Default: env\.GZIPBIN or "gzip" -. -.P -The name of a GNU\-compatible gzip program on your system\. -. -.SS "must\-install" -Default: true -. -.P -Set to false to not install over packages that already exist\. By -default, \fBnpm install foo\fR will fetch and install the latest version of \fBfoo\fR, even if it matches a version already installed\. -. -.SS "auto\-activate" -Default: true -. -.P -Automatically activate a package after installation, if there is not an active -version already\. Set to "always" to always activate when installing\. -. -.SS "update\-dependents" -Default: true -. -.P -Automatically update a package\'s dependencies after installation, if it is the -newest version installed\. Set to "always" to update dependents when a new -version is installed, even if it\'s not the newest\. -. .SH "SEE ALSO" . .IP "\(bu" 4 diff --git a/man1/json.1 b/man1/json.1 index 081850ede..3fb3e3506 100644 --- a/man1/json.1 +++ b/man1/json.1 @@ -549,6 +549,9 @@ is set\. This flag is set automatically when doing \fBnpm link\fR, and can be managed like any other npm configuration param\. See \fBnpm help config\fR for more on the topic\. . +.SH "bundledDependencies" +Array of package names that will be bundled when publishing the package\. +. .SH "engines" Packages/1\.0 says that you can have an "engines" field with an array of engine names\. However, it has no provision for specifying which version of the engine diff --git a/man1/link.1 b/man1/link.1 index 195981872..f3fbfab35 100644 --- a/man1/link.1 +++ b/man1/link.1 @@ -9,35 +9,46 @@ .SH "SYNOPSIS" . .nf -npm link <folder> +npm link (in package folder) +npm link <pkgname> . .fi . .SH "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 +Package linking is a two\-step process\. +. +.P +First, \fBnpm link\fR in a package folder will create a globally\-installed +symbolic link from \fBprefix/package\-name\fR to the current folder\. +. +.P +Next, in some other location, \fBnpm link package\-name\fR will create a +symlink from the local \fBnode_modules\fR folder to the global symlink\. +. +.P +When creating tarballs for \fBnpm publish\fR, the linked packages are +"snapshotted" to their current state by resolving the symbolic links\. +. +.P +This is handy for installing your own stuff, so that you can work on it and test it iteratively without having to continually rebuild\. . -.SH "Linked Package Version" -When linking a package folder, npm doesn\'t use the version in the -package\.json file\. Instead, it creates a "fake" version number of: +.P +For example: . .IP "" 4 . .nf -"9999\.0\.0\-LINK\-" + hash(folder) +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 . .fi . .IP "" 0 . .P -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\. -. -.SH "CONFIGURATION" -See the config section of \fBnpm help install\fR\|\. The \fBdev\fR configuration -setting is always set to \fBtrue\fR 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/man1/list.1 b/man1/list.1 index 4a75b7329..8432cde52 100644 --- a/man1/list.1 +++ b/man1/list.1 @@ -1,98 +1,58 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-LIST" "1" "March 2011" "" "" +.TH "NPM\-LS" "1" "March 2011" "" "" . .SH "NAME" -\fBnpm-list\fR \-\- List installed packages +\fBnpm-ls\fR \-\- List installed packages . .SH "SYNOPSIS" . .nf npm list npm ls +npm la +npm ll . .fi . .SH "DESCRIPTION" This command will print to stdout all the versions of packages that are -either installed or available in the registry, with their tags and whether -or not they\'re active and/or stable\. +installed, as well as their dependencies, in a tree\-structure\. . .P -To filter a single package or state, you can provide words to filter on -and highlight (if appropriate)\. For instance, to see all the stable -packages, you could do this: -. -.IP "" 4 -. -.nf -npm ls stable -. -.fi -. -.IP "" 0 +It does not take arguments\. . .P -Another common usage is to find the set of all packages that are -installed\. This can be accomplished by doing this: -. -.IP "" 4 -. -.nf -npm ls installed -. -.fi -. -.IP "" 0 -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ +It will print out extraneous, missing, and invalid packages\. . .P -The base URL of the npm package registry\. +When run as \fBll\fR or \fBla\fR, it shows extended information by default\. . -.SS "listopts" -Default: "" -. -.P -A whitespace\-separated list of extra args that are always passed to npm ls +.SH "CONFIGURATION" . -.P -For example: \fBlistopts = remote\fR +.SS "long" . -.P -\fBnpm ls\fR +.IP "\(bu" 4 +Default: false . -.P -The output here will always filter by remote +.IP "\(bu" 4 +Type: Boolean . -.SS "description" -Default: true +.IP "" 0 . .P -Show the package description in npm ls\. +Show extended information\. . -.SS "outfd" -Default: Standard Output FD (1) +.SS "parseable" . -.P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. +.IP "\(bu" 4 +Default: false . -.P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +.IP "\(bu" 4 +Type: Boolean . -.SS "color" -Default: true -. -.P -Set to false to disable colorized output\. +.IP "" 0 . .P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +Show parseable output instead of tree view\. @@ -9,35 +9,46 @@ .SH "SYNOPSIS" . .nf -npm link <folder> +npm link (in package folder) +npm link <pkgname> . .fi . .SH "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 +Package linking is a two\-step process\. +. +.P +First, \fBnpm link\fR in a package folder will create a globally\-installed +symbolic link from \fBprefix/package\-name\fR to the current folder\. +. +.P +Next, in some other location, \fBnpm link package\-name\fR will create a +symlink from the local \fBnode_modules\fR folder to the global symlink\. +. +.P +When creating tarballs for \fBnpm publish\fR, the linked packages are +"snapshotted" to their current state by resolving the symbolic links\. +. +.P +This is handy for installing your own stuff, so that you can work on it and test it iteratively without having to continually rebuild\. . -.SH "Linked Package Version" -When linking a package folder, npm doesn\'t use the version in the -package\.json file\. Instead, it creates a "fake" version number of: +.P +For example: . .IP "" 4 . .nf -"9999\.0\.0\-LINK\-" + hash(folder) +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 . .fi . .IP "" 0 . .P -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\. -. -.SH "CONFIGURATION" -See the config section of \fBnpm help install\fR\|\. The \fBdev\fR configuration -setting is always set to \fBtrue\fR when doing a link install\. +Now, any changes to ~/projects/node\-redis will be reflected in +~/projects/node\-bloggy/node_modules/redis/ @@ -1,98 +1,58 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-LIST" "1" "March 2011" "" "" +.TH "NPM\-LS" "1" "March 2011" "" "" . .SH "NAME" -\fBnpm-list\fR \-\- List installed packages +\fBnpm-ls\fR \-\- List installed packages . .SH "SYNOPSIS" . .nf npm list npm ls +npm la +npm ll . .fi . .SH "DESCRIPTION" This command will print to stdout all the versions of packages that are -either installed or available in the registry, with their tags and whether -or not they\'re active and/or stable\. +installed, as well as their dependencies, in a tree\-structure\. . .P -To filter a single package or state, you can provide words to filter on -and highlight (if appropriate)\. For instance, to see all the stable -packages, you could do this: -. -.IP "" 4 -. -.nf -npm ls stable -. -.fi -. -.IP "" 0 +It does not take arguments\. . .P -Another common usage is to find the set of all packages that are -installed\. This can be accomplished by doing this: -. -.IP "" 4 -. -.nf -npm ls installed -. -.fi -. -.IP "" 0 -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ +It will print out extraneous, missing, and invalid packages\. . .P -The base URL of the npm package registry\. +When run as \fBll\fR or \fBla\fR, it shows extended information by default\. . -.SS "listopts" -Default: "" -. -.P -A whitespace\-separated list of extra args that are always passed to npm ls +.SH "CONFIGURATION" . -.P -For example: \fBlistopts = remote\fR +.SS "long" . -.P -\fBnpm ls\fR +.IP "\(bu" 4 +Default: false . -.P -The output here will always filter by remote +.IP "\(bu" 4 +Type: Boolean . -.SS "description" -Default: true +.IP "" 0 . .P -Show the package description in npm ls\. +Show extended information\. . -.SS "outfd" -Default: Standard Output FD (1) +.SS "parseable" . -.P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. +.IP "\(bu" 4 +Default: false . -.P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +.IP "\(bu" 4 +Type: Boolean . -.SS "color" -Default: true -. -.P -Set to false to disable colorized output\. +.IP "" 0 . .P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +Show parseable output instead of tree view\. diff --git a/man1/npm.1 b/man1/npm.1 index 9b599bc08..9b6e779e6 100644 --- a/man1/npm.1 +++ b/man1/npm.1 @@ -33,8 +33,8 @@ You probably got npm because you want to install stuff\. Use \fBnpm install blerg\fR to install the latest version of "blerg"\. Check out \fBnpm help install\fR for more info\. It can do a lot of stuff\. . .P -Use the \fBnpm ls\fR command to show everything that\'s available\. -Use \fBnpm ls installed\fR to show everything you\'ve installed\. \fBnpm help ls\fR will tell you more\. +Use the \fBnpm search\fR command to show everything that\'s available\. +Use \fBnpm ls\fR to show everything you\'ve installed\. . .SH "DEVELOPER USAGE" If you\'re using npm to develop and publish your code, check out the @@ -157,7 +157,7 @@ email: \fInpm\-@googlegroups\.com\fR . .P Be sure to include \fIall\fR of the output from the npm command that didn\'t work -as expected\. +as expected\. The \fBnpm\-debug\.log\fR file is also helpful to provide\. . .P You can also look for isaacs in #node\.js on irc://irc\.freenode\.net\. He diff --git a/man1/outdated.1 b/man1/outdated.1 index fbb508815..99de38692 100644 --- a/man1/outdated.1 +++ b/man1/outdated.1 @@ -16,33 +16,3 @@ npm outdated [<name> [<name> \.\.\.]] .SH "DESCRIPTION" This command will check the registry to see if any (or, specific) installed packages are currently outdated\. -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ -. -.P -The base URL of the npm package registry\. -. -.SS "tag" -Default: latest -. -.P -If you ask npm to install a package and don\'t tell it a specific version, then -it will install the specified tag\. -. -.P -Note: this has no effect on the npm\-tag(1) command\. -. -.SS "outfd" -Default: Standard Output FD (1) -. -.P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. -. -.P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. diff --git a/man1/owner.1 b/man1/owner.1 index 068baef97..51fd7c482 100644 --- a/man1/owner.1 +++ b/man1/owner.1 @@ -39,44 +39,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\. . -.SH "CONFIGURATION" -. -.SS "outfd" -Default: Standard Output FD (1) -. -.P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. -. -.P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. -. -.SS "registry" -Default: https://registry\.npmjs\.org/ -. -.P -The base URL of the npm package registry\. -. -.SS "_auth" -A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\. -. -.P -If your config file is ever corrupted, you can set this manually by doing: -. -.IP "" 4 -. -.nf -npm adduser -. -.fi -. -.IP "" 0 -. -.SS "username, _password" -Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":" -. .SH "SEE ALSO" . .IP "\(bu" 4 diff --git a/man1/prefix.1 b/man1/prefix.1 new file mode 100644 index 000000000..87367f731 --- /dev/null +++ b/man1/prefix.1 @@ -0,0 +1,17 @@ +.\" Generated with Ronnjs/v0.1 +.\" http://github.com/kapouer/ronnjs/ +. +.TH "NPM\-PREFIX" "1" "March 2011" "" "" +. +.SH "NAME" +\fBnpm-prefix\fR \-\- Display prefix +. +.SH "SYNOPSIS" +. +.nf +npm prefix +. +.fi +. +.SH "DESCRIPTION" +Print the prefix to standard out\. diff --git a/man1/prune.1 b/man1/prune.1 new file mode 100644 index 000000000..1f1e7d726 --- /dev/null +++ b/man1/prune.1 @@ -0,0 +1,23 @@ +.\" Generated with Ronnjs/v0.1 +.\" http://github.com/kapouer/ronnjs/ +. +.TH "NPM\-PRUNE" "1" "March 2011" "" "" +. +.SH "NAME" +\fBnpm-prune\fR \-\- Remove extraneous packages +. +.SH "SYNOPSIS" +. +.nf +npm prune [<name> [<name \.\.\.]] +. +.fi +. +.SH "DESCRIPTION" +This command removes "extraneous" packages\. If a package name is +provided, then only packages matching one of the supplied names are +removed\. +. +.P +Extraneous packages are packages that are not listed on the parent +package\'s dependencies list\. diff --git a/man1/publish.1 b/man1/publish.1 index 92c4fba31..beb97c571 100644 --- a/man1/publish.1 +++ b/man1/publish.1 @@ -30,15 +30,7 @@ with a package\.json file inside\. . .P Fails if the package name and version combination already exists in -the registry\. -. -.SH "CONFIGURATION" -See \fBnpm help registry\fR -. -.P -Also, the \fBforce\fR configuration param will cause it to unpublish an -existing package, so that it can be published over\. Please use with -caution! +the registry\. Overwrites when the "\-\-force" flag is set\. . .SH "SEE ALSO" . diff --git a/man1/rebuild.1 b/man1/rebuild.1 index b6cffaa29..2ebc88474 100644 --- a/man1/rebuild.1 +++ b/man1/rebuild.1 @@ -9,7 +9,7 @@ .SH "SYNOPSIS" . .nf -npm rebuild [<name>[@<version>] [<name>[@<version>] \.\.\.]] +npm rebuild [<name> [<name> \.\.\.]] . .fi . @@ -17,10 +17,6 @@ npm rebuild [<name>[@<version>] [<name>[@<version>] \.\.\.]] \fB<name>\fR: The package to rebuild . -.IP "\(bu" 4 -\fB<version>\fR: -The version range to rebuild\. Any matching installed packages are rebuilt\. -. .IP "" 0 . .SH "DESCRIPTION" @@ -28,10 +24,5 @@ This command runs the \fBnpm build\fR command on the matched folders\. This is when you install a new version of node, and must recompile all your C++ addons with the new binary\. . -.P -Regardless of the configuration settings, rebuild always sets \fBupdate\-dependents\fR -and \fBauto\-activate\fR to false, to minimize unexpected side effects\. It does not -change any state outside of the package\'s folder\. -. .SH "CONFIGURATION" See \fBnpm help build\fR diff --git a/man1/registry.1 b/man1/registry.1 index 6fbc1115e..5205405ab 100644 --- a/man1/registry.1 +++ b/man1/registry.1 @@ -18,8 +18,8 @@ account information\. . .P The official public npm registry is at \fIhttp://registry\.npmjs\.org/\fR\|\. It -is powered by a CouchDB database at \fIhttp://isaacs\.couchone\.com/jsregistry\fR\|\. The code for the couchapp is -available at \fIhttp://github\.com/isaacs/js\-registry\fR\|\. npm user accounts +is powered by a CouchDB database at \fIhttp://isaacs\.couchone\.com/registry\fR\|\. The code for the couchapp is +available at \fIhttp://github\.com/isaacs/npmjs\.org\fR\|\. npm user accounts are CouchDB users, stored in the \fIhttp://isaacs\.couchone\.com/_users\fR database\. . @@ -86,57 +86,3 @@ No, but such a thing is planned, and a tiny bit developed\. . .P Stay tuned! -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ -. -.P -The base URL of the npm package registry\. -. -.SS "_auth" -A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\. -. -.P -If your config file is ever corrupted, you can set this manually by doing: -. -.IP "" 4 -. -.nf -npm adduser -. -.fi -. -.IP "" 0 -. -.SS "username, _password" -Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":" -. -.SS "proxy" -If proxy is available, then npm will access the registry via -the proxy server\. -. -.P -Example: -. -.IP "" 4 -. -.nf -proxy = http://user:password@proxy\-server:8080 -. -.fi -. -.IP "" 0 -. -.SS "tar" -Default: env\.TAR or "tar" -. -.P -The name of a GNU\-compatible tar program on your system\. -. -.SS "gzip" -Default: env\.GZIPBIN or "gzip" -. -.P -The name of a GNU\-compatible gzip program on your system\. diff --git a/man1/restart.1 b/man1/restart.1 index 62fe06e61..6b637f596 100644 --- a/man1/restart.1 +++ b/man1/restart.1 @@ -9,7 +9,7 @@ .SH "SYNOPSIS" . .nf -npm restart <name>[@<version>] [<name>[@<version>] \.\.\.] +npm restart <name> . .fi . @@ -9,31 +9,10 @@ .SH "SYNOPSIS" . .nf -npm uninstall <name>[@<version> [<name>[@<version>] \.\.\.] -npm rm <name>[@<version> [<name>[@<version>] \.\.\.] +npm uninstall <name> +npm rm <name> . .fi . .SH "DESCRIPTION" -This uninstalls a package, completely removing everything installed for it\. If -it\'s currently active, then it will be deactivated first, unless the \fBauto\-deactivate\fR config setting is set to "false"\. If anything is -depending on it, then those must be uninstalled first\. -. -.P -If the version is omitted, then all versions of a package are removed\. -. -.P -\fB<version>\fR may in fact be a version range, so these commands are -acceptable: -. -.IP "" 4 -. -.nf -npm rm foo@\'1\.2\.3 \- 4\.8\.9\' -npm rm foo@\'>=1\.0\.0\' -npm rm foo@\'<2\.0\.3\' -. -.fi -. -.IP "" 0 - +This uninstalls a package, completely removing everything installed for it\. diff --git a/man1/root.1 b/man1/root.1 new file mode 100644 index 000000000..d8e5b18bf --- /dev/null +++ b/man1/root.1 @@ -0,0 +1,17 @@ +.\" Generated with Ronnjs/v0.1 +.\" http://github.com/kapouer/ronnjs/ +. +.TH "NPM\-ROOT" "1" "March 2011" "" "" +. +.SH "NAME" +\fBnpm-root\fR \-\- Display npm root +. +.SH "SYNOPSIS" +. +.nf +npm root +. +.fi +. +.SH "DESCRIPTION" +Print the effective \fBnode_modules\fR folder to standard out\. diff --git a/man1/run-script.1 b/man1/run-script.1 index 07e20bf26..717ea4f37 100644 --- a/man1/run-script.1 +++ b/man1/run-script.1 @@ -9,7 +9,7 @@ .SH "SYNOPSIS" . .nf -npm run\-script <script> <name>[@<version>] [<name>[@<version] \.\.\.] +npm run\-script <script> <name> . .fi . @@ -17,9 +17,6 @@ npm run\-script <script> <name>[@<version>] [<name>[@<version] \.\.\.] This runs an arbitrary command from a package\'s "scripts" object\. . .P -If no version is provided then it uses the active version\. -. -.P It is used by the test, start, restart, and stop commands, but can be called directly, as well\. . diff --git a/man1/scripts.1 b/man1/scripts.1 index ee6ad6a13..06a51f2a2 100644 --- a/man1/scripts.1 +++ b/man1/scripts.1 @@ -19,22 +19,6 @@ install, postinstall: Run AFTER the package is installed\. . .IP "\(bu" 4 -preactivate: -Run BEFORE the package is activated\. -. -.IP "\(bu" 4 -activate, postactivate: -Run AFTER the package has been activated\. -. -.IP "\(bu" 4 -predeactivate, deactivate: -Run BEFORE the package is deactivated\. -. -.IP "\(bu" 4 -postdeactivate: -Run AFTER the package is deactivated\. -. -.IP "\(bu" 4 preuninstall, uninstall: Run BEFORE the package is uninstalled\. . @@ -51,14 +35,6 @@ update, postupdate: Run AFTER the package is updated with the update command\. . .IP "\(bu" 4 -preupdatedependencies: -Run BEFORE the package dependencies are pointed to the new version\. -. -.IP "\(bu" 4 -updatedependencies, postupdatedependencies: -Run AFTER the package dependencies are pointed to the new version\. -. -.IP "\(bu" 4 (pre,post,)updatedependency\-foo: Run (before,after) the "foo" dependency is modified\. . @@ -99,11 +75,6 @@ variable set to "foo", and the \fBnpm_package_version\fR set to "1\.2\.5" Configuration parameters are put in the environment with the \fBnpm_config_\fR prefix\. For instance, you can view the effective \fBroot\fR config by checking the \fBnpm_config_root\fR environment variable\. . -.SS "dependency path and versions" -All of the resolved dependencies are available in the environtment as \fBnpm_dependency_<name>=<version>\fR and \fBnpm_dependency_<name>_path=<dir>\fR\|\. So, if you need to refer to files -from dependency packages, or see which version is installed, you can -refer to those environment variables\. -. .SS "Special: package\.json "config" hash" The package\.json "config" keys are overwritten in the environment if there is a config param of \fB<name>[@<version>]:<key>\fR\|\. For example, if diff --git a/man1/search.1 b/man1/search.1 index 4a75b7329..2cae3bbb5 100644 --- a/man1/search.1 +++ b/man1/search.1 @@ -1,98 +1,17 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-LIST" "1" "March 2011" "" "" +.TH "NPM\-LS" "1" "March 2011" "" "" . .SH "NAME" -\fBnpm-list\fR \-\- List installed packages +\fBnpm-ls\fR \-\- List installed packages . .SH "SYNOPSIS" . .nf -npm list -npm ls +npm search [search terms \.\.\.] . .fi . .SH "DESCRIPTION" -This command will print to stdout all the versions of packages that are -either installed or available in the registry, with their tags and whether -or not they\'re active and/or stable\. -. -.P -To filter a single package or state, you can provide words to filter on -and highlight (if appropriate)\. For instance, to see all the stable -packages, you could do this: -. -.IP "" 4 -. -.nf -npm ls stable -. -.fi -. -.IP "" 0 -. -.P -Another common usage is to find the set of all packages that are -installed\. This can be accomplished by doing this: -. -.IP "" 4 -. -.nf -npm ls installed -. -.fi -. -.IP "" 0 -. -.SH "CONFIGURATION" -. -.SS "registry" -Default: https://registry\.npmjs\.org/ -. -.P -The base URL of the npm package registry\. -. -.SS "listopts" -Default: "" -. -.P -A whitespace\-separated list of extra args that are always passed to npm ls -. -.P -For example: \fBlistopts = remote\fR -. -.P -\fBnpm ls\fR -. -.P -The output here will always filter by remote -. -.SS "description" -Default: true -. -.P -Show the package description in npm ls\. -. -.SS "outfd" -Default: Standard Output FD (1) -. -.P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. -. -.P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. -. -.SS "color" -Default: true -. -.P -Set to false to disable colorized output\. -. -.P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +Search the registry for packages matching the search terms\. diff --git a/man1/set.1 b/man1/set.1 index 751a96d9e..ac266ca31 100644 --- a/man1/set.1 +++ b/man1/set.1 @@ -65,6 +65,9 @@ npm config set key value .P Sets the config key to the value\. . +.P +If value is omitted, then it sets it to "true"\. +. .SS "get" . .nf @@ -73,9 +76,7 @@ npm config get key .fi . .P -Echo the config value to stdout\. (NOTE: All the other npm logging is done to -stderr, so pipes should work properly, and you can do \fBnpm get key 2>/dev/null\fR -to print out JUST the config value\.) +Echo the config value to stdout\. . .SS "list" . @@ -105,7 +106,91 @@ npm config edit .fi . .P -Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the global config\. +Opens the config file in an editor\. Use the \fB\-\-global\fR flag to edit the +global config\. +. +.SH "Shorthands and Other CLI Niceties" +The following shorthands are parsed on the command\-line: +. +.IP "\(bu" 4 +\fB\-v\fR: \fB\-\-version\fR +. +.IP "\(bu" 4 +\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR, \fB\-H\fR: \fB\-\-usage\fR +. +.IP "\(bu" 4 +\fB\-s\fR, \fB\-\-silent\fR: \fB\-\-loglevel silent\fR +. +.IP "\(bu" 4 +\fB\-d\fR: \fB\-\-loglevel info\fR +. +.IP "\(bu" 4 +\fB\-dd\fR, \fB\-\-verbose\fR: \fB\-\-loglevel verbose\fR +. +.IP "\(bu" 4 +\fB\-ddd\fR: \fB\-\-loglevel silly\fR +. +.IP "\(bu" 4 +\fB\-g\fR: \fB\-\-global\fR +. +.IP "\(bu" 4 +\fB\-l\fR: \fB\-\-long\fR +. +.IP "\(bu" 4 +\fB\-p\fR, \fB\-\-porcelain\fR: \fB\-\-parseable\fR +. +.IP "\(bu" 4 +\fB\-reg\fR: \fB\-\-registry\fR +. +.IP "\(bu" 4 +\fB\-v\fR: \fB\-\-version\fR +. +.IP "\(bu" 4 +\fB\-f\fR: \fB\-\-force\fR +. +.IP "\(bu" 4 +\fB\-l\fR: \fB\-\-long\fR +. +.IP "\(bu" 4 +\fB\-desc\fR: \fB\-\-description\fR +. +.IP "\(bu" 4 +\fBll\fR and \fBla\fR commands: \fBls \-\-long\fR +. +.IP "" 0 +. +.P +If the specified configuration param resolves unambiguously to a known +configuration parameter, then it is expanded to that configuration +parameter\. For example: +. +.IP "" 4 +. +.nf +npm ls \-\-par +# same as: +npm ls \-\-parseable +. +.fi +. +.IP "" 0 +. +.P +If multiple single\-character shorthands are strung together, and the +resulting combination is unambiguously not some other configuration +param, then it is expanded to its various component pieces\. For +example: +. +.IP "" 4 +. +.nf +npm ls \-gpld +# same as: +npm ls \-\-global \-\-parseable \-\-long \-\-loglevel info +. +.fi +. +.IP "" 0 . .SH "Per\-Package Config Settings" When running scripts (see \fBnpm help scripts\fR) @@ -150,340 +235,547 @@ npm config set foo:port 80 . .SH "Config Settings" . -.SS "auto\-activate" -Default: true +.SS "browser" +. +.IP "\(bu" 4 +Default: OS X: \fB"open"\fR, others: \fB"google\-chrome"\fR +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Automatically activate a package after installation, if there is not an active -version already\. Set to "always" to always activate when installing\. +The browser that is called by the \fBnpm docs\fR command to open websites\. . -.SS "rebuild\-bundle" +.SS "cache" +. +.IP "\(bu" 4 +Default: Windows: \fB~/npm\-cache\fR, Posix: \fB~/\.npm\fR +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 +. +.P +The location of npm\'s cache directory\. See \fBnpm help cache\fR +. +.SS "color" +. +.IP "\(bu" 4 Default: true . +.IP "\(bu" 4 +Type: Boolean or \fB"always"\fR +. +.IP "" 0 +. .P -Set to some truish value to rebuild bundled dependencies after -installation\. +If false, never shows colors\. If \fB"always"\fR then always shows colors\. +If true, then only prints color codes for tty file descriptors\. . -.SS "recursive" -Default: false +.SS "depth" +. +.IP "\(bu" 4 +Default: Infinity +. +.IP "\(bu" 4 +Type: Number +. +.IP "" 0 . .P -Set to some truish value to recursively remove dependent packages\. For -example if foo depends on bar, and bar depends on baz, then: +The depth to go when recursing directories for \fBnpm ls\fR and \fBnpm cache ls\fR\|\. . -.IP "" 4 +.SS "description" . -.nf -npm uninstall baz \-\-recursive +.IP "\(bu" 4 +Default: true . -.fi +.IP "\(bu" 4 +Type: Boolean . .IP "" 0 . .P -will remove baz, bar, and foo\. +Whether or not to show the description in \fBnpm search\fR . -.SS "loglevel" -Default: "info" +.SS "dev" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The log level to show\. +Whether or not to install \fBdev\-dependencies\fR along with packages\. . .P -Each level maps to a numeric value, above which all logs must pass to be -seen\. So, setting it to "warn" shows "win", "error" and "warn" messages\. +Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is +set\. +. +.SS "editor" +. +.IP "\(bu" 4 +Default: \fBEDITOR\fR environment variable if set, or \fB"vi"\fR +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The log levels: +The command to run for \fBnpm edit\fR or \fBnpm config edit\fR\|\. +. +.SS "force" . .IP "\(bu" 4 -silent: Show no output\. Nothing\. If there is output on stderr, it\'s -because something is broken\. +Default: false . .IP "\(bu" 4 -win: Show the "npm ok" or "npm not ok", but that\'s all\. +Type: Boolean +. +.IP "" 0 +. +.P +Makes various commands more forceful\. . .IP "\(bu" 4 -error: Errors, usually with a stack trace\. +lifecycle script failure does not block progress\. . .IP "\(bu" 4 -warn: Things that you should probably be aware of\. +publishing clobbers previously published versions\. . .IP "\(bu" 4 -info: Helpful info\. +skips cache when requesting from the registry\. . .IP "\(bu" 4 -silly: Not\-helpful info\. (Lots of dumping whole objects and such\.) +prevents checks against clobbering non\-npm files\. . .IP "" 0 . -.P -Note that output to stdout is always printed\. This setting just modifies -what\'s logged to stderr\. +.SS "global" . -.SS "update\-dependents" -Default: true +.IP "\(bu" 4 +Default: false . -.P -Automatically update a package\'s dependencies after installation, if it is the -newest version installed\. Set to "always" to update dependents when a new -version is installed, even if it\'s not the newest\. +.IP "\(bu" 4 +Type: Boolean . -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR +.IP "" 0 . .P -The root folder where packages are installed and npm keeps its data\. +Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\. See \fBnpm help global\fR for more on the differences in behavior\. . -.SS "binroot" -Default: \fB$INSTALL_PREFIX/bin\fR +.IP "\(bu" 4 +packages are installed into the \fBprefix/node_modules\fR folder, instead of the +current working directory\. . -.P -The folder where executable programs are installed\. +.IP "\(bu" 4 +bin files are linked to \fBprefix/bin\fR . -.P -Set to "false" to not install executables +.IP "\(bu" 4 +man pages are linked to \fBprefix/share/man\fR . -.SS "manroot" -Default: $INSTALL_PREFIX/share/man +.IP "" 0 . -.P -The folder where man pages are installed\. +.SS "globalconfig" . -.P -Set to "false" to not install man pages\. +.IP "\(bu" 4 +Default: {prefix}/etc/npmrc . -.SS "registry" -Default: https://registry\.npmjs\.org/ +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The base URL of the npm package registry\. +The config file to read for global config options\. +. +.SS "group" +. +.IP "\(bu" 4 +Default: GID of the current process +. +.IP "\(bu" 4 +Type: String or Number . -.SS "_auth" -A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\. +.IP "" 0 . .P -If your config file is ever corrupted, you can set this manually by doing: +The group to use when running package scripts in global mode as the root +user\. . -.IP "" 4 +.SS "gzipbin" . -.nf -npm adduser +.IP "\(bu" 4 +Default: "gzip" . -.fi +.IP "\(bu" 4 +Type: path . .IP "" 0 . -.SS "username, _password" -Once the configuration is parsed, the \fB_auth\fR config is split into \fBusername\fR and \fB_password\fR\|\. This is the part before the ":" +.P +The gzip binary . -.SS "proxy" -If proxy is available, then npm will access the registry via -the proxy server\. +.SS "logfd" +. +.IP "\(bu" 4 +Default: stderr file descriptor +. +.IP "\(bu" 4 +Type: Number or Stream +. +.IP "" 0 . .P -Example: +The location to write log output\. . -.IP "" 4 +.SS "loglevel" . -.nf -proxy = http://user:password@proxy\-server:8080 +.IP "\(bu" 4 +Default: "warn" . -.fi +.IP "\(bu" 4 +Type: String . -.IP "" 0 +.IP "\(bu" 4 +Values: "silent", "win", "error", "warn", "info", "verbose", "silly" . -.SS "tag" -Default: latest +.IP "" 0 . .P -If you ask npm to install a package and don\'t tell it a specific version, then -it will install the specified tag\. +What level of logs to report\. On failure, \fIall\fR logs are written to \fBnpm\-debug\.log\fR in the current working directory\. . -.P -Note: this has no effect on the npm\-tag(1) command\. +.SS "long" . -.SS "userconfig" -The default user configuration file is process\.env\.HOME+"/\.npmrc"\. +.IP "\(bu" 4 +Default: false . -.P -Note that this must be provided either in the cli or env settings\. Once the -userconfig is read, it is irrelevant\. +.IP "\(bu" 4 +Type: Boolean . -.SS "globalconfig" -The default global configuration file is resolved based on the location of the -node executable\. It is process\.execPath+"/\.\./\.\./etc/npmrc"\. In the canonical -NodeJS installation with \fBmake install\fR, this is \fB/usr/local/etc/npmrc\fR\|\. If you -put the node binary somewhere else (for instance, if you are using nvm or -nave), then it would be resolved relative to that location\. +.IP "" 0 . .P -Note that this must be provided in the cli, env, or userconfig settings\. Once -the globalconfig is read, this parameter is irrelevant\. +Whether or not to show extended information in \fBnpm ls\fR . -.SS "global" -If set to some truish value (for instance, by being the last cli flag or being -passed a literal \fBtrue\fR or \fB1\fR), and the \fBnpm config set\fR param is being -called, then the new configuration paramater is written global config file\. -Otherwise, they are saved to the user config file\. +.SS "node\-version" . -.SS "dev" -If set to a truish value, then it\'ll install the "devDependencies" as well as -"dependencies" when installing a package\. +.IP "\(bu" 4 +Default: process\.version . -.P -Note that devDependencies are \fIalways\fR installed when linking a package\. +.IP "\(bu" 4 +Type: semver . -.SS "tar" -Default: env\.TAR or "tar" +.IP "" 0 . .P -The name of a GNU\-compatible tar program on your system\. +The node version to use when checking package\'s "engines" hash\. . -.SS "gzip" -Default: env\.GZIPBIN or "gzip" +.SS "npat" . -.P -The name of a GNU\-compatible gzip program on your system\. +.IP "\(bu" 4 +Default: false . -.SS "usage" -If set to \fBtrue\fR, then this will tell help to print out the short usage statement -instead of the long manpage type thing\. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -This is set automatically if you invoke help like \fBnpm command \-?\fR\|\. +Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\. . -.SS "viewer" -Default: "man" +.SS "npaturl" . -.P -The program to use to view help content\. Set to "woman" to use the emacs troff viewer -by that name\. +.IP "\(bu" 4 +Default: Not yet implemented . -.SS "_exit" -Default: true +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -Whether or not to exit the process when the command is finished\. When -using npm programmatically, it\'s a good idea to set this to \fBfalse\fR -explicitly\. +The url to report npat test results\. . -.SS "logfd" -Default: Standard Error FD (2) +.SS "onload\-script" . -.P -The file descriptor (integer) or stream object where npm will write log -messages\. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +A node module to \fBrequire()\fR when npm loads\. Useful for programmatic +usage\. . .SS "outfd" -Default: Standard Output FD (1) +. +.IP "\(bu" 4 +Default: standard output file descriptor +. +.IP "\(bu" 4 +Type: Number or Stream +. +.IP "" 0 . .P -The file descriptor (integer) or stream object where npm will write -"normal" output\. For instance, the \fBls\fR and \fBview\fR commands write their -output here\. +Where to write "normal" output\. This has no effect on log output\. +. +.SS "parseable" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -When using npm programmatically, you may want to provide a -FileWriteStream, or some other form of WritableStream\. +Whether or not to output parseable results from commands that write to +standard output\. . -.SS "color" -Default: true +.SS "prefix" +. +.IP "\(bu" 4 +Default: node\'s process\.installPrefix +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -Set to false to disable colorized output\. +The location to install global items\. If set on the command line, then +it forces non\-global commands to run in the specified folder\. +. +.SS "proxy" +. +.IP "\(bu" 4 +Default: "HTTP\fIPROXY" or "http\fRproxy" environment variable, or null +. +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -In versions of node that expose the \fBisatty\fR function, npm will never -write colorized output to a non\-terminal file descriptor\. +A proxy to use for outgoing http requests\. +. +.SS "rebuild\-bundle" . -.SS "tmproot" -Default: env\.TMPDIR or "/tmp" +.IP "\(bu" 4 +Default: true +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The folder where temporary files should be placed\. +Set to some truish value to rebuild bundled dependencies after +installation\. +. +.SS "registry" +. +.IP "\(bu" 4 +Default: https://registry\.npmjs\.org/ +. +.IP "\(bu" 4 +Type: url +. +.IP "" 0 . .P -npm creates a subfolder whenever it is run, and attempts to delete it -afterwards\. +The base URL of the npm package registry\. . -.SS "force" -Default: false +.SS "searchopts" +. +.IP "\(bu" 4 +Default: "" +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Set to a truish value to force uninstalling packages, even if they have -dependents\. +Space\-separated options that are always passed to search\. +. +.SS "searchexclude" +. +.IP "\(bu" 4 +Default: "" +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -Note that setting \fBrecursive\fR is safer, because forcing uninstall can -create orphan packages that no longer function properly\. +Space\-separated options that limit the results from search\. . -.SS "editor" -Default: env\.EDITOR +.SS "shell" +. +.IP "\(bu" 4 +Default: SHELL environment variable, or "bash" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -The program to use to edit files\. +The shell to run for the \fBnpm explore\fR command\. . -.SS "listexclude" -Default: null +.SS "tag" +. +.IP "\(bu" 4 +Default: latest +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -A whitespace separated list of strings which \fIprevent\fR items from being -shown to \fBnpm ls\fR\|\. +If you ask npm to install a package and don\'t tell it a specific version, then +it will install the specified tag\. . .P -For example, \fBnpm ls installed \-\-listexclude zombie\fR will show all -installed packages \fIexcept\fR zombie\. +Also the tag that is added to the package@version specified by the \fBnpm +tag\fR command, if no explicit tag is given\. . -.SS "listopts" -Default: "" +.SS "tar" . -.P -A whitespace\-separated list of extra args that are always passed to npm ls +.IP "\(bu" 4 +Default: TAR environment variable, or "tar" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -For example: \fBlistopts = remote\fR +The tar executable +. +.SS "tmp" +. +.IP "\(bu" 4 +Default: TMPDIR environment variable, or "/tmp" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -\fBnpm ls\fR +Where to store temporary files and folders\. All temp files are deleted +on success, but left behind on failure for forensic purposes\. +. +.SS "unsafe\-perm" +. +.IP "\(bu" 4 +Default: false if running as root, true otherwise +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -The output here will always filter by remote +Set to true to suppress the UID/GID switching when running package +scripts\. If set explicitly to false, then installing as a non\-root user +will fail\. . -.SS "must\-install" -Default: true +.SS "usage" +. +.IP "\(bu" 4 +Default: false +. +.IP "\(bu" 4 +Type: Boolean +. +.IP "" 0 . .P -Set to false to not install over packages that already exist\. By -default, \fBnpm install foo\fR will fetch and install the latest version of \fBfoo\fR, even if it matches a version already installed\. +Set to show short usage output (like the \-H output) +instead of complete help when doing \fBnpm help\fR\|\. . -.SH "description" -Default: true +.SS "user" +. +.IP "\(bu" 4 +Default: "nobody" +. +.IP "\(bu" 4 +Type: String or Number +. +.IP "" 0 . .P -Show the package description in npm ls\. +The UID to set to when running package scripts as root\. +. +.SS "username" . -.SH "node\-version" -Default: \fBprocess\.version\fR from the node environment +.IP "\(bu" 4 +Default: null +. +.IP "\(bu" 4 +Type: String +. +.IP "" 0 . .P -An effective version of node to use when checking for "engines" -compliance\. +The username on the npm registry\. Set with \fBnpm adduser\fR +. +.SS "userconfig" +. +.IP "\(bu" 4 +Default: ~/\.npmrc on Posix, or ~/npm\-config on Windows +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -Set to null or false to suppress engine checking altogether\. +The location of user\-level configuration settings\. . -.SH "onload\-script" +.SS "version" +. +.IP "\(bu" 4 Default: false . +.IP "\(bu" 4 +Type: boolean +. +.IP "" 0 +. .P -A script to run when npm loads\. Use this to hook into various events in -the npm flow in a programmatic way, even when using npm from the command -line\. +If true, output the npm version and exit successfully\. +. +.P +Only relevant when specified explicitly on the command line\. +. +.SS "viewer" +. +.IP "\(bu" 4 +Default: "man" +. +.IP "\(bu" 4 +Type: path +. +.IP "" 0 . .P -If false, then don\'t do any onload stuff\. +The program to use to view help content\. diff --git a/man1/start.1 b/man1/start.1 index 087434bec..43f98ba10 100644 --- a/man1/start.1 +++ b/man1/start.1 @@ -9,12 +9,9 @@ .SH "SYNOPSIS" . .nf -npm start <name>[@<version>] [<name>[@<version>] \.\.\.] +npm start <name> . .fi . .SH "DESCRIPTION" This runs a package\'s "start" script, if one was provided\. -. -.P -If no version is specified, then it starts the "active" version\. diff --git a/man1/stop.1 b/man1/stop.1 index b863638b3..cfa3997e2 100644 --- a/man1/stop.1 +++ b/man1/stop.1 @@ -9,12 +9,9 @@ .SH "SYNOPSIS" . .nf -npm stop <name>[@<version>] [<name>[@<version>] \.\.\.] +npm stop <name> . .fi . .SH "DESCRIPTION" This runs a package\'s "stop" script, if one was provided\. -. -.P -If no version is specified, then it stops the "active" version\. diff --git a/man1/tag.1 b/man1/tag.1 index 07b10d4c0..8920f8722 100644 --- a/man1/tag.1 +++ b/man1/tag.1 @@ -9,14 +9,9 @@ .SH "SYNOPSIS" . .nf -npm tag <name>@<version> <tagname> +npm tag <name>@<version> [<tag>] . .fi . .SH "DESCRIPTION" -Tags the specified version of the package with the specified "tagname"\. -. -.P -The only tag with special significance is "latest"\. That version is -installed by default when no other tag or version number is specified, -and always points to the most recently updated version of a package\. +Tags the specified version of the package with the specified tag, or the \fB\-\-tag\fR config if not specified\. diff --git a/man1/test.1 b/man1/test.1 index f439f7c09..5a1f9bb85 100644 --- a/man1/test.1 +++ b/man1/test.1 @@ -9,7 +9,7 @@ .SH "SYNOPSIS" . .nf - npm test <name>[@<version>] [<name>[@<version>] \.\.\.] + npm test <name> . .fi . @@ -17,4 +17,5 @@ This runs a package\'s "test" script, if one was provided\. . .P -If no version is specified, then it tests the "active" version\. +To run tests as a condition of installation, set the \fBnpat\fR config to +true\. diff --git a/man1/uninstall.1 b/man1/uninstall.1 index 45f1570c2..e9aa4e4c1 100644 --- a/man1/uninstall.1 +++ b/man1/uninstall.1 @@ -9,31 +9,10 @@ .SH "SYNOPSIS" . .nf -npm uninstall <name>[@<version> [<name>[@<version>] \.\.\.] -npm rm <name>[@<version> [<name>[@<version>] \.\.\.] +npm uninstall <name> +npm rm <name> . .fi . .SH "DESCRIPTION" -This uninstalls a package, completely removing everything installed for it\. If -it\'s currently active, then it will be deactivated first, unless the \fBauto\-deactivate\fR config setting is set to "false"\. If anything is -depending on it, then those must be uninstalled first\. -. -.P -If the version is omitted, then all versions of a package are removed\. -. -.P -\fB<version>\fR may in fact be a version range, so these commands are -acceptable: -. -.IP "" 4 -. -.nf -npm rm foo@\'1\.2\.3 \- 4\.8\.9\' -npm rm foo@\'>=1\.0\.0\' -npm rm foo@\'<2\.0\.3\' -. -.fi -. -.IP "" 0 - +This uninstalls a package, completely removing everything installed for it\. diff --git a/man1/update.1 b/man1/update.1 index c127b6a11..a265bb17f 100644 --- a/man1/update.1 +++ b/man1/update.1 @@ -15,19 +15,7 @@ npm update [<name> [<name> \.\.\.]] . .SH "DESCRIPTION" This command will update all the packages listed to the latest version -(specified by the \fBtag\fR config), as well as updating any dependent -packages to use the new version, if possible\. +(specified by the \fBtag\fR config)\. . .P -Additionally, it will activate the new version, and delete any old versions, if -safe to do so -. -.P -If the \fBupdate\-dependents\fR configuration parameter is set to \fB"true"\fR, then -packages will always be updated when they are installed, if they are the newest -version\. -. -.P -If the \fBupdate\-dependents\fR configuration parameter is set to \fB"always"\fR, then -packages will be updated when they are installed, even if to do so would be a -downgrade\. +It will also install missing packages\. |