Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge branch '1.0'

  • Loading branch information...
commit 7cf6f5b713efe27cc0962fd2075134ce53374876 2 parents a221126 + e265b12
@isaacs isaacs authored
Showing with 6,000 additions and 7,106 deletions.
  1. +5 −1 .gitignore
  2. +0 −7 .npmignore
  3. +4 −3 Makefile
  4. +0 −24 doc/activate.md
  5. +4 −18 doc/adduser.md
  6. +1 −0  doc/author.md
  7. +2 −8 doc/build.md
  8. +0 −60 doc/bundle.md
  9. +26 −23 doc/cache.md
  10. +29 −230 doc/changelog.md
  11. +11 −14 doc/completion.md
  12. +224 −177 doc/config.md
  13. +0 −15 doc/deactivate.md
  14. +0 −9 doc/deprecate.md
  15. +1 −3 doc/docs.md
  16. +3 −15 doc/edit.md
  17. +20 −26 doc/faq.md
  18. +133 −51 doc/folders.md
  19. +0 −27 doc/future-ideas/deploy.md
  20. +0 −276 doc/future-ideas/new-module-system.md
  21. +0 −23 doc/future-ideas/remote.md
  22. +0 −58 doc/future-ideas/site.md
  23. +13 −87 doc/install.md
  24. +4 −0 doc/json.md
  25. +21 −16 doc/link.md
  26. +15 −49 doc/list.md
  27. +3 −4 doc/npm.md
  28. +0 −28 doc/outdated.md
  29. +0 −32 doc/owner.md
  30. +10 −0 doc/prefix.md
  31. +15 −0 doc/prune.md
  32. +1 −9 doc/publish.md
  33. +1 −7 doc/rebuild.md
  34. +2 −45 doc/registry.md
  35. +1 −1  doc/restart.md
  36. +10 −0 doc/root.md
  37. +1 −3 doc/run-script.md
  38. +0 −20 doc/scripts.md
  39. +0 −1  doc/search.md
  40. +10 −0 doc/search.md
  41. +1 −3 doc/start.md
  42. +1 −3 doc/stop.md
  43. +3 −6 doc/tag.md
  44. +3 −2 doc/test.md
  45. +3 −15 doc/uninstall.md
  46. +2 −12 doc/update.md
  47. +0 −157 lib/activate.js
  48. +1 −1  lib/adduser.js
  49. +0 −13 lib/autoremove.js
  50. +82 −293 lib/build.js
  51. +0 −113 lib/bundle.js
  52. +135 −221 lib/cache.js
  53. +185 −42 lib/completion.js
  54. +28 −18 lib/config.js
  55. +0 −104 lib/deactivate.js
  56. +15 −4 lib/deprecate.js
  57. +6 −4 lib/docs.js
  58. +9 −10 lib/edit.js
  59. +7 −12 lib/explore.js
  60. +1 −3 lib/get.js
  61. +24 −31 lib/help.js
  62. +2 −3 lib/init.js
  63. +282 −284 lib/install.js
  64. +81 −101 lib/link.js
  65. +129 −237 lib/ls.js
  66. +139 −64 lib/outdated.js
  67. +59 −21 lib/owner.js
  68. +6 −0 lib/prefix.js
  69. +40 −0 lib/prune.js
  70. +9 −2 lib/publish.js
  71. +44 −89 lib/rebuild.js
  72. +6 −0 lib/root.js
  73. +56 −43 lib/run-script.js
  74. +203 −0 lib/search.js
  75. +1 −3 lib/set.js
  76. +6 −9 lib/tag.js
  77. +73 −0 lib/unbuild.js
  78. +17 −260 lib/uninstall.js
  79. +27 −4 lib/unpublish.js
  80. +0 −266 lib/update-dependents.js
  81. +17 −86 lib/update.js
  82. +10 −6 lib/utils/async-map.js
  83. +42 −0 lib/utils/completion.sh
  84. +0 −8 lib/utils/completion/contains-single-match.js
  85. +29 −0 lib/utils/completion/file-completion.js
  86. +0 −17 lib/utils/completion/get-completions.js
  87. +46 −0 lib/utils/completion/installed-deep.js
  88. +0 −36 lib/utils/completion/installed-packages.js
  89. +79 −0 lib/utils/completion/installed-shallow.js
  90. +1 −1  lib/utils/completion/remote-packages.js
  91. +1 −1  lib/utils/completion/users.js
  92. +24 −22 lib/utils/default-config.js
  93. +0 −11 lib/utils/default.npmignore
  94. +103 −25 lib/utils/error-handler.js
  95. +39 −0 lib/utils/find-prefix.js
  96. +2 −0  lib/utils/ini.js
  97. +68 −118 lib/utils/lifecycle.js
  98. +8 −6 lib/utils/link.js
  99. +1 −18 lib/utils/load-package-defaults.js
  100. +9 −1 lib/utils/log.js
  101. +235 −0 lib/utils/minimatch.js
  102. 0  lib/utils/{registry → npm-registry-client}/adduser.js
  103. +12 −1 lib/utils/{registry → npm-registry-client}/get.js
  104. +1 −1  lib/utils/{registry.js → npm-registry-client/index.js}
  105. +5 −0 lib/utils/{registry → npm-registry-client}/publish.js
  106. 0  lib/utils/{registry → npm-registry-client}/request.js
  107. 0  lib/utils/{registry → npm-registry-client}/tag.js
  108. 0  lib/utils/{registry → npm-registry-client}/unpublish.js
  109. +16 −15 lib/utils/output.js
  110. +57 −29 lib/utils/parse-args.js
  111. +254 −50 lib/utils/read-installed.js
  112. +16 −4 lib/utils/read-json.js
  113. +1 −0  lib/utils/relativize.js
  114. +55 −23 lib/utils/rm-rf.js
  115. +477 −0 lib/utils/tar.js
  116. +1 −1  lib/utils/which.js
  117. +47 −33 lib/view.js
  118. +1 −2  lib/xmas.js
  119. +0 −29 man1/activate.1
  120. +5 −23 man1/adduser.1
  121. +51 −0 man1/author.1
  122. +2 −7 man1/build.1
  123. +0 −82 man1/bundle.1
  124. +25 −24 man1/cache.1
  125. +31 −445 man1/changelog.1
  126. +12 −17 man1/completion.1
  127. +482 −190 man1/config.1
  128. +0 −21 man1/deactivate.1
  129. +0 −8 man1/deprecate.1
  130. +1 −4 man1/docs.1
  131. +3 −16 man1/edit.1
  132. +24 −36 man1/faq.1
  133. +23 −63 man1/find.1
  134. +132 −58 man1/folders.1
  135. +0 −49 man1/future-ideas/deploy.1
  136. +0 −334 man1/future-ideas/new-module-system.1
  137. +0 −28 man1/future-ideas/remote.1
  138. +0 −79 man1/future-ideas/site.1
  139. +482 −190 man1/get.1
  140. +14 −89 man1/install.1
  141. +3 −0  man1/json.1
  142. +26 −15 man1/link.1
  143. +23 −63 man1/list.1
  144. +26 −15 man1/ln.1
  145. +23 −63 man1/ls.1
  146. +3 −3 man1/npm.1
  147. +0 −30 man1/outdated.1
  148. +0 −38 man1/owner.1
  149. +17 −0 man1/prefix.1
  150. +23 −0 man1/prune.1
  151. +1 −9 man1/publish.1
  152. +1 −10 man1/rebuild.1
  153. +2 −56 man1/registry.1
  154. +1 −1  man1/restart.1
  155. +3 −24 man1/rm.1
  156. +17 −0 man1/root.1
  157. +1 −4 man1/run-script.1
  158. +0 −29 man1/scripts.1
  159. +4 −85 man1/search.1
  160. +482 −190 man1/set.1
  161. +1 −4 man1/start.1
  162. +1 −4 man1/stop.1
  163. +2 −7 man1/tag.1
  164. +3 −2 man1/test.1
  165. +3 −24 man1/uninstall.1
  166. +2 −14 man1/update.1
  167. +0 −42 npm-completion.sh
  168. +82 −63 npm.js
  169. +5 −2 package.json
  170. +13 −1 scripts/install.sh
  171. +0 −2  test/packages/npm-test-bindir/bin/prog.js
  172. +0 −5 test/packages/npm-test-bindir/package.json
  173. +0 −16 test/packages/npm-test-bindir/test.js
  174. +0 −13 test/packages/npm-test-bundletest/foo.js
  175. +0 −5 test/packages/npm-test-bundletest/package.json
  176. +0 −4 test/packages/npm-test-depends-on-connect/package.json
  177. +0 −5 test/packages/npm-test-depends-on-jsdom/package.json
  178. +0 −13 test/packages/npm-test-depends-on-jsdom/test.js
  179. +0 −5 test/packages/npm-test-depends-on-spark/package.json
  180. +0 −1  test/packages/npm-test-files-array-npmignore/.npmignore
  181. +0 −1  test/packages/npm-test-files-array-npmignore/foo/bar
  182. 0  test/packages/npm-test-files-array-npmignore/foo/baz
  183. +0 −4 test/packages/npm-test-files-array-npmignore/package.json
  184. +0 −11 test/packages/npm-test-files-array-npmignore/test.sh
  185. +0 −1  test/packages/npm-test-files-array-simple/bar
  186. +0 −1  test/packages/npm-test-files-array-simple/foo
  187. +0 −4 test/packages/npm-test-files-array-simple/package.json
  188. +0 −12 test/packages/npm-test-files-array-simple/test.sh
  189. 0  test/packages/npm-test-npmignore/.dot-keeper
  190. 0  test/packages/npm-test-npmignore/.dotfile
  191. 0  test/packages/npm-test-npmignore/.dotglob-a
  192. 0  test/packages/npm-test-npmignore/.dotglob-b
  193. 0  test/packages/npm-test-npmignore/.dotglob-c
  194. +0 −3  test/packages/npm-test-npmignore/.npmignore
  195. +0 −1  test/packages/npm-test-npmignore/foo/bar
  196. 0  test/packages/npm-test-npmignore/foo/baz
  197. +0 −4 test/packages/npm-test-npmignore/package.json
  198. +0 −14 test/packages/npm-test-npmignore/test.sh
  199. +1 −1  test/packages/npm-test-url-dep/package.json
  200. +31 −52 test/run.sh
View
6 .gitignore
@@ -1,6 +1,10 @@
+*.swp
test/bin
test/output.log
test/packages/*/node_modules
test/packages/npm-test-depends-on-spark/which-spark.log
+test/packages/test-package/random-data.txt
test/root
-*.swp
+node_modules/ronn
+node_modules/.bin
+npm-debug.log
View
7 .npmignore
@@ -1,7 +0,0 @@
-test/packages/test-package/random-data.txt
-test/packages/npm-test-depends-on-spark/which-spark.log
-test/packages/*/node_modules
-test/output.log
-test/root
-test/bin
-*.swp
View
7 Makefile
@@ -20,7 +20,7 @@ latest: submodules
node cli.js install
install: submodules
- node cli.js install
+ node cli.js install -g
# backwards compat
dev: install
@@ -32,7 +32,7 @@ clean: uninstall
uninstall: submodules
node cli.js cache clean
- node cli.js rm npm -f
+ node cli.js rm npm -g
man: man1
@@ -43,7 +43,8 @@ doc: man1 $(docs)
# use `npm install ronn` for this to work.
man1/%.1: doc/%.md
- ronn --roff $< > $@
+ @[ -x ./node_modules/.bin/ronn ] || node cli.js install ronn
+ ./node_modules/.bin/ronn --roff $< > $@
man1/%/: doc/%/
@if ! test -d $@ ; then mkdir -p $@ ; fi
View
24 doc/activate.md
@@ -1,24 +0,0 @@
-npm activate(1) -- Activate an installed version of a package
-=============================================================
-
-## SYNOPSIS
-
- npm activate <name>@<version> [<name>@<version> ...]
-
-## DESCRIPTION
-
-This "activates" a specific version of a package, so that you can just do
-`require("foo")` without having to specify the version.
-
-## CONFIGURATION
-
-### auto-activate
-
-Default: true
-
-Automatically activate a package after installation, if there is not an active
-version already. Set to "always" to always activate when installing.
-
-## SEE ALSO
-
-npm-deactivate(1)
View
22 doc/adduser.md
@@ -10,34 +10,20 @@ npm-adduser(1) -- Add a registry user account
Create or verify a user named `<username>` in the npm registry, and
save the credentials to the `.npmrc` file.
-The username, password, and email are read in from prompts. This command
-cannot be scripted. If you think you need to script the creation of new
-users, or the authorization of existing ones, without human intervention,
-please rethink your use case. That's a very bad idea.
+The username, password, and email are read in from prompts.
You may use this command to change your email address, but not username
or password.
+To reset your password, go to <http://admin.npmjs.org/>
+
You may use this command multiple times with the same user account to
authorize on a new machine.
## CONFIGURATION
-### _auth
-
-A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
-
-If your config file is ever corrupted, you can set this manually by doing:
-
- npm adduser
-
### registry
-Default: https://registry.npmjs.org/
+Default: http://registry.npmjs.org/
The base URL of the npm package registry.
-
-### username, _password
-
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`. This is the part before the ":"
View
1  doc/author.md
View
10 doc/build.md
@@ -10,15 +10,9 @@ npm-build(1) -- Build a package
## DESCRIPTION
-This command should almost never need to be run directly. It is an abstraction
-of the functionality shared by both npm-install(1) and npm-link(1).
-
-This command creates the various interwoven links that ensure a package's contents
-are available in the root appropriately, and that its dependencies are linked
-appropriately.
-
-## CONFIGURATION
+This is the plumbing command called by `npm link` and `npm install`.
+It should generally not be called directly.
## SEE ALSO
View
60 doc/bundle.md
@@ -1,60 +0,0 @@
-npm-bundle(1) -- Bundle package dependencies
-============================================
-
-## SYNOPSIS
-
- npm bundle
- npm bundle destroy
- npm bundle <cmd> <args>
-
-Run in a package folder.
-
-## DESCRIPTION
-
-When run in a package folder, this command can be used to install
-package dependencies into the `node_modules` folder.
-
-When the package is installed, it will read dependencies from the local
-bundle *before* reading any dependencies that are already installed.
-
-Furthermore, when installing, npm will not attempt to install
-dependencies that already exist in the bundle.
-
-To bundle all the dependencies of a given package, run `npm bundle`
-without any arguments.
-
-To completely remove the bundle folder, run `npm bundle destroy`.
-
-To operate on the bundle packages, any npm command and arguments may be
-passed to the `npm bundle` command. For example, to install a package
-into the bundle, you can do `npm bundle install express`.
-
-To list the packages in the bundle, do `npm bundle ls`. To remove bundled
-packages, do `npm bundle remove <whatever>`. Et cetera.
-
-In this way, a command like
-`npm bundle install http://github.com/user/project/tarball/master` can be used
-to have a dependency that is not published on the npm registry. (It still
-must contain a package.json, though, of course.)
-
-## CAVEATS
-
-Man pages are not installed by bundle.
-
-Bins are installed, but not globally.
-
-When a dependency is specified as a URL rather than a version range, it
-is bundled with the package depending upon it.
-
-## CONFIGURATION
-
-The bundle command itself is a proxy for `install`, or whichever command
-is passed as the first argument. As such, it uses
-the same configuration parameters as the commands it proxies,
-but with the following temporary changes:
-
-* root: $PWD/node_modules/
-* binroot: $PWD/node_modules/.bin
-* manroot: null
-
-See `npm help config` for more information on these.
View
49 doc/cache.md
@@ -10,48 +10,51 @@ npm-cache(1) -- install a package
npm cache ls [<path>]
- npm cache clean [<name>[@<version>]]
+ npm cache clean [<path>]
## DESCRIPTION
* add:
- Access the local cache of package data. This command is primarily
+ Add the specified package to the local cache. This command is primarily
intended to be used internally by npm, but it can provide a way to
add data to the local installation cache explicitly.
- If two arguments are provided, then npm will fetch the data from the
- registry. This allows npm to use the filesystem as a local proxy to
- the registry.
-
* ls:
- Show the data in the cache. Additional arguments are joined together
- in a path-like fashion, but something like `npm cache ls npm/0.1.5` is
- acceptable as well.
+ Show the data in the cache. Argument is a path to show in the cache
+ folder. Works a bit like the `find` program, but limited by the
+ `depth` config.
* clean:
- Delete data out of the cache for a specific package and version, all
- versions of a package, or all data for all packages, depending on the
- arguments supplied.
-
- This can be used if invalid data gets into the cache.
+ Delete data out of the cache folder. If an argument is provided, then
+ it specifies a subpath to delete. If no argument is provided, then
+ the entire cache is cleared.
## DETAILS
-npm stores data for a version of a package in
-`$ROOT/.npm/.cache/<name>/<version>`. Three pieces of data are stored
-in this folder:
+npm stores cache data in `$HOME/.npm`. For each package that is added
+to the cache, three pieces of information are stored in
+`{cache}/{name}/{version}`:
-* package/:
+* .../package/:
A folder containing the package contents as they appear in the tarball.
-* package.json:
+* .../package.json:
The package.json file, as npm sees it, with overlays applied and a _id attribute.
-* package.tgz:
+* .../package.tgz:
The tarball for that version.
+Additionally, whenever a registry request is made, a `.cache.json` file
+is placed at the corresponding URI, to store the ETag and the requested
+data.
+
+Commands that make non-essential registry requests (such as `search` and
+`view`, or the completion scripts) generally specify a minimum timeout.
+If the `.cache.json` file is younger than the specified timeout, then
+they do not make an HTTP request to the registry.
+
## CONFIGURATION
-### root
+### cache
-Default: `$INSTALL_PREFIX/lib/node`
+Default: `$HOME/.npm` on Posix, or `$HOME/npm-cache` on Windows.
-The root folder where packages are installed and npm keeps its data.
+The root cache folder.
View
259 doc/changelog.md
@@ -3,249 +3,48 @@ npm-changelog(1) -- Changes
## HISTORY
-* 0.0.1:
- Lots of sketches and false starts. Abandoned a few times.
+* 0.0
+ Lots of sketches and false starts. Abandoned a few times.
+ Core functionality established.
+ alpha.
-* 0.0.2:
- Install worked mostly. Still promise-based.
-
-* 0.0.3:
- Converted to callbacks.
- Mikeal Rogers wrote a registry for it.
-
-* 0.0.4:
- version dependencies
- link packages
- activation
- lifecycle scripts
- bin linking
- uninstallation
-
-* 0.0.5:
- fix a few bugs in uninstall wrt dependent packages
- fix relative require()for nodejs modules installed with the "bin" field.
- (issue #2)
- update to work with node 0.1.33 (aka net2)
- added publish and tag commands
-
-* 0.0.6:
- set up a public registry
- send content-length with registry PUTs
- adduser command (Mikeal Rogers)
- ini file stuff (Mikeal Rogers)
- env-specific package.json
- added more info to npm's the package.json (bugs, contributors, etc.)
-
-* 0.0.7:
- fixed a few bugs in semver
- refactor documentation
- add "help" command
- add install from registry
- everything else core
- push to beta
-
-* 0.1.0 - 0.1.2:
+* 0.1
push to beta, and announce
- clean up some bugs around lifecycle scripts
- reduce reliance on makefile
- documentation updates
- Fixed DOA bugs
- Removed dependence on ronn
-
-* 0.1.3:
- Changed a few details with configs (fix #5)
- Update adduser and publish to put author info in the data
- Use buffer api for file writes, hopefully fix #4
-
-* 0.1.4 - 0.1.5:
- Fixes for a few more bugs and fix some documentation.
-
-* 0.1.6 - 0.1.7:
- Add cache functionality
- Use couchdb attachments to host tarballs
- Handle odd require.paths more appropriately
- Don't break on install if the man path is missing
- Support publishing or installing a folder or local tarball
-
-* 0.1.8:
- Bugfixes
- Add start, stop, restart, and test commands
-
-* 0.1.9:
- npm list enhancements
- fix the install bug
-
-* 0.1.10:
- More errors found by Ryan Dahl and Kris Zyp
- Better uninstall and list behavior
- Docs for new developers.
- Better tracking of ownership on the registry.
-
-* 0.1.11:
- Martyn Smith found a whole lot of bugs.
- Make publish not die when the tarball is big.
- "make uninstall" support
-
-* 0.1.12 - 0.1.13:
- Fix the downloading bug that was breaking the tarballs
- Update some docs
-
-* 0.1.14 - 0.1.16:
- Fix to stay in sync with node changes
- Put a special tag on link installs
- Modify semver comparison slightly
- add unpublish command
- Use the "drain" event properly for uploads
- Handle thrown errors
- Handle .npmignore
-
-* 0.1.17:
- Stabilization.
-
-* 0.1.18:
- Change a few default configurations
- Add test harness
- Default publish, install, and link to "." if no arguments given
-
-* 0.1.19 - 0.1.20:
- Create a bunch of bugs
- Fix a bunch of bugs
- Some minor speed improvements
-
-* 0.1.21 - 0.1.22:
- Relative paths
- Support comments in package.json
- Add owner name to ls output
- Add "owner" command to manage package owners
- Support hook scripts in `{root}/.npm/.hooks/`
- Initial support for config file relative to node executable
- Support for http proxies
- Documentation updates
-
-* 0.1.23:
- update command - This is huge.
- Rollback for failed installations
- Install dependencies for link packages
- Silently read passwords for adduser
- Cascading configs: cli, env, user, global
- First pass at `npm view` command
-
-* 0.1.24, 0.1.25:
- Fix a bunch of things
- Cleanup, etc.
- help via --help, -h, or -?
-
-* 0.1.26:
- "modules" hash in package.json (Alex K. Wolfe)
- Better "restart" command (Alex K Wolfe)
- Work on Cygwin
- Remove link packages properly
- Make several commands more parallel
-
-* 0.1.27:
- Man pages handled with the "man" entry, or a "man" directory
- Install man pages in the "manroot" config dir
- Control log output with the "loglevel" config
- Support a "bin" directory of executables that get auto-linked
- Un-deprecate the "lib" directory.
- Bug killing
- Split up the tar usage so it works on Solaris
+ documentation, caching, more robust script support
+ ownership tracking in the registry (no more admin party!)
+ more robust config and option parsing
+ stabilize semver semantics
+ tests
+ update command
bundle command
- rebuild command
+ Rollback for failed installations
+ Solaris and Cygwin support
-* 0.2.0:
- Lots more bug killing
- Various fixes found during the Node Knockout extravaganza
- Change all "name-version" things to be "name@version"
+* 0.2
First allegedly "stable" release.
-
-* 0.2.1:
- Minor updates and bugfixes
-
-* 0.2.2:
- Update "help" to work on Solaris
- Remove updated packages that don't have dependencies.
- Allow implied suffixes on .js bins
- Fix an "adduser" bug
-
-* 0.2.3:
- Lots of documentation tweaks and cleanup
- Support || in version ranges
-
-* 0.2.4:
- Contribution party!
- Better list whitespace
- Lots of config happiness
- Ignore all major SCM folders by default
- Handle proxies and hostnames with ports
- Better Bundling
- Add 'outdated' command
- Better handling of "engines" field
-
-* 0.2.5:
+ Various fixes found during the Node Knockout extravaganza
+ Minor updates and bugfixes
+ more complete semver functionality
Make npm OK to use programmatically (Charlie Robbins)
-
-* 0.2.6:
- More programmatic updates
recursive package removal
- tab completion
-
-* 0.2.7 - 0.2.8:
- Bundle treated like a first-class citizen, and simplified
- Many bug fixes
-
-* 0.2.9:
- npm version command
+ tab completion (Evan Meagher)
shasums on all tarballs
- More portable tar option usage
- Much beefed up bundle command
- Deep view command
-
-* 0.2.10:
- npm edit command
- various stability bugfixes.
-
-* 0.2.11:
- ~> and 1.2.x style version ranges
- complete tab completion: see `npm help completion` (Evan Meagher)
explore command: see `npm help explore`
docs command: see `npm help docs`
- keywords and description in `npm ls`
- Frequently asked questions at `npm help faq`
-
-* 0.2.12:
- Various bugfixes (0.2.11 was big, broke some stuff)
- `npm faq` command (wrapper for `npm help faq`)
-
-* 0.2.13:
- Merry Xmas!
- Config setting on the command line with grace and gusto
- Portability and stability fixes.
- Mostly sort of works with Homebrew-installed nodejs.
-
-* 0.2.14:
- A little bit of documentation overhaul.
- Support for `"<name>":"<url>"` for dependencies.
- Fix for "unpublish" regression.
- Support for "files" array.
- Dependency info in lifecycle scripts.
- More data validation.
-
-* 0.2.15 - 0.2.17:
- Added "--force" for publish
- Support argless "unpublish" and "uninstall" in package dirs
- Document future stuff
- Remove support for "modules" hash
- Read package defaults when reading json
+ Frequently asked questions at `npm faq`
+ xmas easter egg
+ work with homebrew nodejs
+ Support for `"<name>":"<url>"` for dependencies.
-* 0.3.0:
- More correct permission/uid handling. (Sudo is now encouraged!)
+* 0.3
+ More correct permission/uid handling. (Sudo now encouraged!)
Require node 0.4.0
Separate semver out into a separate utility.
Packages without "main" modules don't export modules.
+ Remove support for invalid JSON (since node doesn't support it)
No shims! (Still has symlinks, though)
-* 0.3.1-0.3.5:
- Ease up on permission forcing.
- Fix bugs around proxy handling.
- Remove support for invalid JSON (since node doesn't support it)
+* 1.0
+ Simplify configuration greatly.
+ Install locally (bundle by default)
+ Drastic rearchitecture
View
25 doc/completion.md
@@ -1,22 +1,19 @@
npm-completion(1) -- Tab Completion for npm
===========================================
-## DESCRIPTION
+## SYNOPSIS
-You should set up tab completion for npm if you haven't already.
-There are a few ways to do this:
+ npm completion >> ~/.bashrc
+ npm completion >> ~/.zshrc
-1. Add `. /path/to/npm-completion.sh` to your ~/.bashrc file. OR:
-2. Create a symlink like this if you have automatic bash completion set up:
- `ln - /path/to/npm-completion.sh /etc/bash-completion.d/npm`
- or, perhaps:
- `ln - /path/to/npm-completion.sh /usr/local/etc/bash-completion.d/npm`
+## DESCRIPTION
-If you're using a non-bash shell (like zsh or ksh) then this might not work.
+Sets up a function that enables tab-completion in all npm commands.
-To get the path to the npm-completion.sh file, use `npm explore npm pwd`.
+You may of course also pipe the relevant script to a file such as
+`/usr/local/etc/bash_completion.d/npm` if you have a system that will
+read that file for you.
-It's a very new feature, and it would be great to get feedback on it.
-Hopefully, I'll be able to work out a way to install the completion script
-automatically. If you have any ideas about how that should work, then please
-share them.
+When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the
+environment, `npm completion` acts in "plumbing mode", and outputs
+completions based on the arguments.
View
401 doc/config.md
@@ -35,8 +35,6 @@ npm gets its configuration values from 5 sources, in this priority:
This is a set of configuration parameters that are internal to npm, and are
defaults if nothing else is specified.
-
-
## Sub-commands
Config supports the following sub-commands:
@@ -47,13 +45,13 @@ Config supports the following sub-commands:
Sets the config key to the value.
+If value is omitted, then it sets it to "true".
+
### get
npm config get key
-Echo the config value to stdout. (NOTE: All the other npm logging is done to
-stderr, so pipes should work properly, and you can do `npm get key 2>/dev/null`
-to print out JUST the config value.)
+Echo the config value to stdout.
### list
@@ -71,7 +69,45 @@ Deletes the key from all configuration files.
npm config edit
-Opens the config file in an editor. Use the `--global` flag to edit the global config.
+Opens the config file in an editor. Use the `--global` flag to edit the
+global config.
+
+## Shorthands and Other CLI Niceties
+
+The following shorthands are parsed on the command-line:
+
+* `-v`: `--version`
+* `-h`, `-?`, `--help`, `-H`: `--usage`
+* `-s`, `--silent`: `--loglevel silent`
+* `-d`: `--loglevel info`
+* `-dd`, `--verbose`: `--loglevel verbose`
+* `-ddd`: `--loglevel silly`
+* `-g`: `--global`
+* `-l`: `--long`
+* `-p`, `--porcelain`: `--parseable`
+* `-reg`: `--registry`
+* `-v`: `--version`
+* `-f`: `--force`
+* `-l`: `--long`
+* `-desc`: `--description`
+* `ll` and `la` commands: `ls --long`
+
+If the specified configuration param resolves unambiguously to a known
+configuration parameter, then it is expanded to that configuration
+parameter. For example:
+
+ npm ls --par
+ # same as:
+ npm ls --parseable
+
+If multiple single-character shorthands are strung together, and the
+resulting combination is unambiguously not some other configuration
+param, then it is expanded to its various component pieces. For
+example:
+
+ npm ls -gpld
+ # same as:
+ npm ls --global --parseable --long --loglevel info
## Per-Package Config Settings
@@ -94,292 +130,303 @@ then the user could change the behavior by doing:
## Config Settings
-### auto-activate
+### browser
-Default: true
+* Default: OS X: `"open"`, others: `"google-chrome"`
+* Type: String
-Automatically activate a package after installation, if there is not an active
-version already. Set to "always" to always activate when installing.
+The browser that is called by the `npm docs` command to open websites.
-### rebuild-bundle
+### cache
-Default: true
-
-Set to some truish value to rebuild bundled dependencies after
-installation.
+* Default: Windows: `~/npm-cache`, Posix: `~/.npm`
+* Type: path
-### recursive
+The location of npm's cache directory. See `npm help cache`
-Default: false
-
-Set to some truish value to recursively remove dependent packages. For
-example if foo depends on bar, and bar depends on baz, then:
-
- npm uninstall baz --recursive
+### color
-will remove baz, bar, and foo.
+* Default: true
+* Type: Boolean or `"always"`
-### loglevel
+If false, never shows colors. If `"always"` then always shows colors.
+If true, then only prints color codes for tty file descriptors.
-Default: "info"
+### depth
-The log level to show.
+* Default: Infinity
+* Type: Number
-Each level maps to a numeric value, above which all logs must pass to be
-seen. So, setting it to "warn" shows "win", "error" and "warn" messages.
+The depth to go when recursing directories for `npm ls` and
+`npm cache ls`.
-The log levels:
+### description
-* silent: Show no output. Nothing. If there is output on stderr, it's
- because something is broken.
-* win: Show the "npm ok" or "npm not ok", but that's all.
-* error: Errors, usually with a stack trace.
-* warn: Things that you should probably be aware of.
-* info: Helpful info.
-* silly: Not-helpful info. (Lots of dumping whole objects and such.)
+* Default: true
+* Type: Boolean
-Note that output to stdout is always printed. This setting just modifies
-what's logged to stderr.
+Whether or not to show the description in `npm search`
-### update-dependents
+### dev
-Default: true
+* Default: false
+* Type: Boolean
-Automatically update a package's dependencies after installation, if it is the
-newest version installed. Set to "always" to update dependents when a new
-version is installed, even if it's not the newest.
+Whether or not to install `dev-dependencies` along with packages.
-### root
+Note that `dev-dependencies` are also installed if the `npat` flag is
+set.
-Default: `$INSTALL_PREFIX/lib/node`
+### editor
-The root folder where packages are installed and npm keeps its data.
+* Default: `EDITOR` environment variable if set, or `"vi"`
+* Type: path
-### binroot
+The command to run for `npm edit` or `npm config edit`.
-Default: `$INSTALL_PREFIX/bin`
+### force
-The folder where executable programs are installed.
+* Default: false
+* Type: Boolean
-Set to "false" to not install executables
+Makes various commands more forceful.
-### manroot
+* lifecycle script failure does not block progress.
+* publishing clobbers previously published versions.
+* skips cache when requesting from the registry.
+* prevents checks against clobbering non-npm files.
-Default: $INSTALL_PREFIX/share/man
+### global
-The folder where man pages are installed.
+* Default: false
+* Type: Boolean
-Set to "false" to not install man pages.
+Operates in "global" mode, so that packages are installed into the
+`prefix` folder instead of the current working directory. See
+`npm help global` for more on the differences in behavior.
-### registry
+* packages are installed into the `prefix/node_modules` folder, instead of the
+ current working directory.
+* bin files are linked to `prefix/bin`
+* man pages are linked to `prefix/share/man`
-Default: https://registry.npmjs.org/
+### globalconfig
-The base URL of the npm package registry.
+* Default: {prefix}/etc/npmrc
+* Type: path
-### _auth
+The config file to read for global config options.
-A base-64 encoded "user:pass" pair. This is created by npm-adduser(1).
+### group
-If your config file is ever corrupted, you can set this manually by doing:
+* Default: GID of the current process
+* Type: String or Number
- npm adduser
+The group to use when running package scripts in global mode as the root
+user.
-### username, _password
+### gzipbin
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`. This is the part before the ":"
+* Default: "gzip"
+* Type: path
-### proxy
+The gzip binary
-If proxy is available, then npm will access the registry via
-the proxy server.
+### logfd
-Example:
+* Default: stderr file descriptor
+* Type: Number or Stream
- proxy = http://user:password@proxy-server:8080
+The location to write log output.
-### tag
+### loglevel
-Default: latest
+* Default: "warn"
+* Type: String
+* Values: "silent", "win", "error", "warn", "info", "verbose", "silly"
-If you ask npm to install a package and don't tell it a specific version, then
-it will install the specified tag.
+What level of logs to report. On failure, *all* logs are written to
+`npm-debug.log` in the current working directory.
-Note: this has no effect on the npm-tag(1) command.
+### long
-### userconfig
+* Default: false
+* Type: Boolean
-The default user configuration file is process.env.HOME+"/.npmrc".
+Whether or not to show extended information in `npm ls`
-Note that this must be provided either in the cli or env settings. Once the
-userconfig is read, it is irrelevant.
+### node-version
-### globalconfig
+* Default: process.version
+* Type: semver
-The default global configuration file is resolved based on the location of the
-node executable. It is process.execPath+"/../../etc/npmrc". In the canonical
-NodeJS installation with `make install`, this is `/usr/local/etc/npmrc`. If you
-put the node binary somewhere else (for instance, if you are using nvm or
-nave), then it would be resolved relative to that location.
+The node version to use when checking package's "engines" hash.
-Note that this must be provided in the cli, env, or userconfig settings. Once
-the globalconfig is read, this parameter is irrelevant.
+### npat
-### global
+* Default: false
+* Type: Boolean
-If set to some truish value (for instance, by being the last cli flag or being
-passed a literal `true` or `1`), and the `npm config set` param is being
-called, then the new configuration paramater is written global config file.
-Otherwise, they are saved to the user config file.
+Whether or not to run tests on installation and report results to the
+`npaturl`.
-### dev
+### npaturl
-If set to a truish value, then it'll install the "devDependencies" as well as
-"dependencies" when installing a package.
+* Default: Not yet implemented
+* Type: url
-Note that devDependencies are *always* installed when linking a package.
+The url to report npat test results.
-### tar
+### onload-script
-Default: env.TAR or "tar"
+* Default: false
+* Type: path
-The name of a GNU-compatible tar program on your system.
+A node module to `require()` when npm loads. Useful for programmatic
+usage.
-### gzip
+### outfd
-Default: env.GZIPBIN or "gzip"
+* Default: standard output file descriptor
+* Type: Number or Stream
-The name of a GNU-compatible gzip program on your system.
+Where to write "normal" output. This has no effect on log output.
-### usage
+### parseable
-If set to `true`, then this will tell help to print out the short usage statement
-instead of the long manpage type thing.
+* Default: false
+* Type: Boolean
-This is set automatically if you invoke help like `npm command -?`.
+Whether or not to output parseable results from commands that write to
+standard output.
-### viewer
+### prefix
-Default: "man"
+* Default: node's process.installPrefix
+* Type: path
-The program to use to view help content. Set to "woman" to use the emacs troff viewer
-by that name.
+The location to install global items. If set on the command line, then
+it forces non-global commands to run in the specified folder.
-### _exit
+### proxy
-Default: true
+* Default: "HTTP_PROXY" or "http_proxy" environment variable, or null
+* Type: url
-Whether or not to exit the process when the command is finished. When
-using npm programmatically, it's a good idea to set this to `false`
-explicitly.
+A proxy to use for outgoing http requests.
-### logfd
+### rebuild-bundle
-Default: Standard Error FD (2)
+* Default: true
+* Type: Boolean
-The file descriptor (integer) or stream object where npm will write log
-messages.
+Set to some truish value to rebuild bundled dependencies after
+installation.
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
+### registry
-### outfd
+* Default: https://registry.npmjs.org/
+* Type: url
-Default: Standard Output FD (1)
+The base URL of the npm package registry.
-The file descriptor (integer) or stream object where npm will write
-"normal" output. For instance, the `ls` and `view` commands write their
-output here.
+### searchopts
-When using npm programmatically, you may want to provide a
-FileWriteStream, or some other form of WritableStream.
+* Default: ""
+* Type: String
-### color
+Space-separated options that are always passed to search.
-Default: true
+### searchexclude
-Set to false to disable colorized output.
+* Default: ""
+* Type: String
-In versions of node that expose the `isatty` function, npm will never
-write colorized output to a non-terminal file descriptor.
+Space-separated options that limit the results from search.
-### tmproot
+### shell
-Default: env.TMPDIR or "/tmp"
+* Default: SHELL environment variable, or "bash"
+* Type: path
-The folder where temporary files should be placed.
+The shell to run for the `npm explore` command.
-npm creates a subfolder whenever it is run, and attempts to delete it
-afterwards.
+### tag
-### force
+* Default: latest
+* Type: String
-Default: false
+If you ask npm to install a package and don't tell it a specific version, then
+it will install the specified tag.
-Set to a truish value to force uninstalling packages, even if they have
-dependents.
+Also the tag that is added to the package@version specified by the `npm
+tag` command, if no explicit tag is given.
-Note that setting `recursive` is safer, because forcing uninstall can
-create orphan packages that no longer function properly.
+### tar
-### editor
+* Default: TAR environment variable, or "tar"
+* Type: path
-Default: env.EDITOR
+The tar executable
-The program to use to edit files.
+### tmp
-### listexclude
+* Default: TMPDIR environment variable, or "/tmp"
+* Type: path
-Default: null
+Where to store temporary files and folders. All temp files are deleted
+on success, but left behind on failure for forensic purposes.
-A whitespace separated list of strings which *prevent* items from being
-shown to `npm ls`.
+### unsafe-perm
-For example, `npm ls installed --listexclude zombie` will show all
-installed packages *except* zombie.
+* Default: false if running as root, true otherwise
+* Type: Boolean
-### listopts
+Set to true to suppress the UID/GID switching when running package
+scripts. If set explicitly to false, then installing as a non-root user
+will fail.
-Default: ""
+### usage
-A whitespace-separated list of extra args that are always passed to npm ls
+* Default: false
+* Type: Boolean
-For example: `listopts = remote`
+Set to show short usage output (like the -H output)
+instead of complete help when doing `npm help`.
-`npm ls`
+### user
-The output here will always filter by remote
+* Default: "nobody"
+* Type: String or Number
-### must-install
+The UID to set to when running package scripts as root.
-Default: true
+### username
-Set to false to not install over packages that already exist. By
-default, `npm install foo` will fetch and install the latest version of
-`foo`, even if it matches a version already installed.
+* Default: null
+* Type: String
-## description
+The username on the npm registry. Set with `npm adduser`
-Default: true
+### userconfig
-Show the package description in npm ls.
+* Default: ~/.npmrc on Posix, or ~/npm-config on Windows
+* Type: path
-## node-version
+The location of user-level configuration settings.
-Default: `process.version` from the node environment
+### version
-An effective version of node to use when checking for "engines"
-compliance.
+* Default: false
+* Type: boolean
-Set to null or false to suppress engine checking altogether.
+If true, output the npm version and exit successfully.
-## onload-script
+Only relevant when specified explicitly on the command line.
-Default: false
+### viewer
-A script to run when npm loads. Use this to hook into various events in
-the npm flow in a programmatic way, even when using npm from the command
-line.
+* Default: "man"
+* Type: path
-If false, then don't do any onload stuff.
+The program to use to view help content.
View
15 doc/deactivate.md
@@ -1,15 +0,0 @@
-npm-deactivate(1) -- Deactivate the active version of a package
-===============================================================
-
-## SYNOPSIS
-
- npm deactivate <name>
-
-## DESCRIPTION
-
-If there's an active version of the package, this will unlink it from that
-preferential position.
-
-## SEE ALSO
-
-npm-activate(1)
View
9 doc/deprecate.md
@@ -17,12 +17,3 @@ something like this:
Note that you must be the package owner to deprecate something. See the
`owner` and `adduser` help topics.
-
-## CONFIGURATION
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
View
4 doc/docs.md
@@ -9,6 +9,4 @@ npm-docs(1) -- Docs for a package in a web browser maybe
This command tries to guess at the likely location of a package's
documentation URL, and then tries to open it using the `--browser`
-config param, which defaults to `"open"` because that works on a mac.
-
-This is an experimental command. It may disappear or change radically.
+config param.
View
18 doc/edit.md
@@ -13,18 +13,6 @@ configured as the npm `editor` config -- see `npm help config`.)
After it has been edited, the package is rebuilt so as to pick up any
changes in compiled packages.
-Note: If you're finding yourself using this a lot, it's probably better
-to use `npm link` instead. However, it is extremely handy when used in
-conjunction with `npm bundle`.
-
-For instance, you can do `npm bundle install connect` to install connect
-into your package, and then `npm bundle edit connect` to make a few
-changes to your locally bundled copy.
-
-## CONFIGURATION
-
-### editor
-
-Default: env.EDITOR
-
-The program to use to edit files.
+For instance, you can do `npm install connect` to install connect
+into your package, and then `npm edit connect` to make a few
+changes to your locally installed copy.
View
46 doc/faq.md
@@ -16,32 +16,37 @@ I don't know yet.
Read the error output, and if you can't figure out what it means,
do what it says and post a bug with all the information it asks for.
-If there doesn't seem to be enough output for your liking, run the
-command with `--loglevel verbose` or if you're really brave, `--loglevel
-silly`.
+## Where does npm put stuff?
-## How do I make npm less noisy?
+See `npm help folders`
-`npm config set loglevel error`
+## I installed something globally, but I can't `require()` it
-You can also set it to `win` or `silent` for even more quietness.
+Install it locally.
+
+## I don't wanna.
+
+Ok, then do this:
+
+ echo 'export NODE_PATH="'$(npm root -g)'"' >> ~/.bashrc
+ . ~/.bashrc
## How do I list installed packages?
-`npm ls installed`
+`npm ls`
If you just want to see the names, and not all the registry data, you
can do: `npm ls installed --no-registry` to turn off the registry.
## How do I search for packages?
-`npm ls`
+`npm search`
Arguments are greps. `npm ls jsdom` shows jsdom packages.
## How do I update npm?
-`npm update npm`
+`npm update npm -g`
You can also update all outdated packages by doing `npm update` without
any arguments.
@@ -78,19 +83,8 @@ awesomely handy.
## Can I list a url as a dependency?
-No.
-
-If you need to depend on something that isn't published, or a package
-that is published, but which you've modified slightly, you can do this.
-
-The correct way is to do the following:
-
-* add a `"name":"version"` entry to your package.json file.
-* `npm bundle install <pkg>` where `<pkg>` is a url or path to your
- custom unpublished package.
-
-When installing your package, npm will skip over any dependencies that
-are bundled.
+Yes. It should be a url to a gzipped tarball containing a single folder
+that has a package.json in its root.
## OK, but can I list a git repo as a dependency?
@@ -106,7 +100,7 @@ lot of use cases, and is very easy to maintain.
## How do I symlink to a dev folder so that I don't have to keep re-installing?
-`npm link`
+See `npm help link`
## The package registry website. What is that exactly?
@@ -123,8 +117,7 @@ https reliably.
## I forgot my password, and can't publish. How do I reset it?
-Email <i@izs.me> from the email address that you signed up with. Then
-wait a day or two maybe.
+Go to <http://admin.npmjs.org/> to reset it.
## I get ECONNREFUSED a lot. What's up?
@@ -132,7 +125,8 @@ Either the registry is down, or node's DNS isn't able to reach out.
This happens a lot if you don't follow *all* the steps in the Cygwin
setup doc.
-To check if the registry is down, open up <http://registry.npmjs.org/>
+To check if the registry is down, open up
+<http://registry.npmjs.org/-/short>
in a web browser. This will also tell you if you are just unable to
access the internet for some reason.
View
184 doc/folders.md
@@ -3,89 +3,171 @@ npm-folders(1) -- Folder Structures Used by npm
## DESCRIPTION
-Node modules and metadata live
-in the `root` setting. Check `npm help config` for more
-on configuration options.
+npm puts various things on your computer. That's its job.
-`root/foo` Symlink to the active version's module folder.
+This document will tell you what it puts where.
-`root/foo@1.0.0/` Node modules for the foo package.
+### prefix Configuration
-`root/foo@1.0.0/{module-name}.js` Generated shim corresponding to a module
-defined in the modules option. The module shim requires
-`root/.npm/foo/1.0.0/package/{module-path}.js`
+The `prefix` config defaults to node's `process.installPrefix`. On most
+systems, this is `/usr/local`.
-The `main` script is implemented by creating an `index.js` file in this folder.
+When the `global` flag is set, npm installs things into this prefix.
+When it is not set, it uses the root of the current package, or the
+current working directory if not in a package already.
-`root/.npm/foo` is where the stuff for package `foo` would go.
+### Node Modules
-`root/.npm/foo/1.0.0/package` the contents of the tarball containing foo
-version 1.0.0
+Packages are droped into the `node_modules` folder under the `prefix`.
+When installing locally, this means that you can
+`require("packagename")` to load its main module, or
+`require("packagename/path/to/sub/module")` to load other modules.
-`root/.npm/foo/1.0.0/main.js` Generated file that exports the `main` module in
-foo. This is a shim, not a symbolic link, so that relative paths will work
-appropriately.
+If you wish to install node modules globally which can be loaded via
+`require()` from anywhere, then add the `prefix/node_modules` folder to
+your NODE_PATH environment variable.
-`root/.npm/foo/active` symlink to the active version.
+### Executables
-`root/.npm/foo/1.0.0/node_modules` links to the modules that foo depends upon.
-This is loaded into the require path first in the foo shims.
+When in global mode, executables are linked into `prefix/bin`.
-`root/.npm/foo/1.0.0/dependson` links to the package folders that foo depends
-on. This is here so that npm can access those packages programmatically.
+When in local mode, executables are linked into
+`prefix/node_modules/.bin`.
-`root/.npm/foo/1.0.0/dependents` links to the packages that depend upon foo.
+### Man Pages
-`root/.npm/.cache` the cache folder.
+When in global mode, man pages are linked into `prefix/share/man`.
-`root/.npm/.cache/foo/1.0.0/package.json` the parsed package.json for foo@1.0.0
+When in local node, man pages are not installed.
-`root/.npm/.cache/foo/1.0.0/package.tgz` the tarball of foo@1.0.0
+### Cache
-`root/.npm/.cache/foo/1.0.0/package` the untouched pristine copy of foo@1.0.0
+See `npm help cache`. Cache files are stored in `~/.npm` on Posix, or
+`~/npm-cache` on Windows.
-Executables are installed to the folder specified by the `binroot` config.
+This is controlled by the `cache` configuration param.
-`binroot/foo` Symlink to the active version of the "foo" executable.
+### Temp Files
-`binroot/foo@1.0.0` An executable for foo at version 1.0.0. Either a
-symbolic link or a shim to a file in the foo package.
+Temporary files are stored by default in the folder specified by the
+`tmp` config, which defaults to either the TMPDIR environment
+variable, or `/tmp`.
-Man pages are installed to the folder specified by the `manroot` config.
-Man pages named something other than the package name are prefixed with
-the package name.
+Temp files are given a unique folder under this root for each run of the
+program, and are deleted upon successful exit.
-`manroot/man1/foo.1` Symlink to the section 1 manpage for the active
-version of foo.
+## More Information
-`manroot/man1/foo@1.0.0.1` Section 1 man page for foo version 1.0.0
+When you run `npm install foo@1.2.3` it downloads and builds the
+package, and then, if there is a package.json file in the current
+working directory, it copies it to `$PWD/node_modules/foo`, so that your
+current package will get it when you do `require("foo")`.
-`manroot/man8/foo-bar.8` Symlink to a section 8 manpage for the active
-version of foo.
+When this is done, it also installs all of foo's dependencies to
+`./node_modules/foo/node_modules/`, so that it will get its dependencies
+appropriately when it calls `require()`. If foo depends on bar, and bar
+depends on baz, then there will also be a
+`./node_modules/foo/node_modules/bar/node_modules/baz`, and so on.
-`manroot/man8/foo-bar@1.0.0.8` A section 8 manpage for foo version
-1.0.0.
+If there is not a package.json in the current working directory, then
+npm walks up the working dir parent paths looking for a package.json,
+indicating the root of a package, or a node_modules folder,
+indicating an npm package deployment location, and then take the party to that
+location. This behavior may be suppressed by setting the `seek-root`
+config value to false.
-## CONFIGURATION
+If no package root is found, then a global installation is performed.
+The global installation may be supressed by setting the `global`
+configuration to false, in which case, the install will fail.
-### root
+### Global Installation
-Default: `$INSTALL_PREFIX/lib/node`
+If the `global` configuration is set to true, or if it is not explicitly
+set false and no suitable node_modules folder was found, then npm will
+install packages "globally".
-The root folder where packages are installed and npm keeps its data.
+This means that the module contents are symlinked (or, on windows,
+copied) from `root/<name>/<version>/package` to
+`root/node_modules/<name>`.
-### binroot
+### Cycles, Conflicts, and Folder Parsimony
-Default: `$INSTALL_PREFIX/bin`
+Cycles are handled using the property of node's module system that it
+walks up the directories looking for node_modules folders. So, at every
+stage, if a package is already installed in an ancestor node_modules
+folder, then it is not installed at the current location.
-The folder where executable programs are installed.
+Consider the case above, where `foo -> bar -> baz`. Imagine if, in
+addition to that, baz depended on bar, so you'd have:
+`foo -> bar -> baz -> bar -> baz ...`. However, since the folder
+structure is: foo/node_modules/bar/node_modules/baz, there's no need to
+put another copy of bar into .../baz/node_modules, since when it calls
+require("bar"), it will get the copy that is installed in
+foo/node_modules/bar.
-Set to "false" to not install executables
+This shortcut is only used if the exact same
+version would be installed in multiple nested node_modules folders. It
+is still possible to have `a/node_modules/b/node_modules/a` if the two
+"a" packages are different versions. However, without repeating the
+exact same package multiple times, an infinite regress will always be
+prevented.
-### manroot
+Another optimization can be made by installing dependencies at the
+highest level possible, below the localized "target" folder.
-Default: $INSTALL_PREFIX/share/man
+For example, consider this dependency graph:
-The folder where man pages are installed.
+ foo
+ +-- bar@1.2.3
+ | +-- baz@2.x
+ | | `-- quux@3.x
+ | | `-- bar@1.2.3 (cycle)
+ | `-- asdf@*
+ `-- baz@1.2.3
+ `-- quux@3.x
+ `-- bar
-Set to "false" to not install man pages.
+In this case, we might expect a folder structure like this:
+
+ foo
+ +-- node_modules
+ +-- bar (1.2.3)
+ | +-- node_modules
+ | | `-- baz (2.0.2)
+ | | `-- node_modules
+ | | `-- quux (3.2.0)
+ | `-- asdf (2.3.4)
+ `-- baz (1.2.3)
+ `-- node_modules
+ `-- quux (3.2.0)
+ `-- node_modules
+ `-- bar (1.2.3)
+ `-- node_modules
+ `-- asdf (2.3.4)
+
+Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are
+installed in foo's node_modules folder.
+
+Bar has dependencies on baz and asdf, so those are installed in bar's
+node_modules folder. Baz has a dependency on quux, so that is installed
+in its node_modules folder.
+
+Underneath bar, the `baz->quux->bar` dependency creates a cycle.
+However, because `bar` is already in `quux`'s ancestry, it does not
+unpack another copy of bar into that folder.
+
+Similarly, underneath `foo->baz`, the same cycle is gradually prevented
+because `bar`'s `quux` dependency is satisfied by its parent folder.
+
+For a graphical breakdown of what is installed where, use `npm ls`.
+
+### Publishing
+
+Upon publishing, npm will look in the node_modules folder. If any of
+the items there are on the "dependencies" or "devDependencies" list,
+and are not in the `bundledDependencies` array, then they will not be
+included in the package tarball.
+
+This allows a package maintainer to install all of their dependencies
+(and dev dependencies) locally, but only re-publish those items that
+cannot be found elsewhere.
View
27 doc/future-ideas/deploy.md
@@ -1,27 +0,0 @@
-npm-deploy(1) -- Deploy a package to a remote host
-==================================================
-
-## FUTURE
-
-This functionality does not yet exist.
-
-## SUMMARY
-
- npm deploy <pkg> [--host <hostname>]
-
-## DESCRIPTION
-
-This is a porcelain command. It is equivalent to doing:
-
- npm publish --registry $(npm config get host) <pkg>
- npm remote install <pkg-name>@<pkg-version>
-
-That is, it first publishes the package to the server specified
-by the `host` config, and then remotely installs that package
-on the host.
-
-## SEE ALSO
-
-* npm-remote(1)
-* npm-site(1)
-* npm-publish(1)
View
276 doc/future-ideas/new-module-system.md
@@ -1,276 +0,0 @@
-npm-folders(1) -- Folder Structures Used by npm
-===============================================
-
-## FUTURE
-
-This functionality is not yet implemented. It is a plan, not reality.
-It is not the map, nor the territory, but a blueprint with blank areas.
-
-In particular, this is the scheme that will be used starting in npm@0.3,
-which will require node@0.5.0 or above.
-
-## GOALS
-
-* Don't splat stuff across the filesystem so much. Just specify a single
-root location, and be done with it.
-
-* Work on windows.
-
-* Minimize shim/symlink usage.
-
-* Do not rely on any global system path for node modules.
-
-* Remove the "activation" concept.
-
-## DESCRIPTION
-
-npm metadata lives in the `root` setting. There is the cache folder,
-and the contents of all installed packages.
-
-The default npm root folder is `/usr/local/lib/npm`.
-
-TODO: What should the root folder be on windows?
-
-### Cache folder
-
-The cache folder is a mirror of the data in the registry, as well as a
-working space for unpacking and creating tarballs.
-
-Files and folders created in the cache are owned by the executing user,
-often "root".
-
-Files are created with 0666 and folders with 0777, so that they can be
-modified by any user.
-
-* `root/cache` Cache folder
-* `root/cache/foo/cache.json` Expirable cache of registry/foo json data
-* `root/cache/foo/1.2.3/package` Pristine copy of foo package contents
-* `root/cache/foo/1.2.3/package.tgz` tarball of foo@1.2.3
-
-### Package folders
-
-In the npm root folder, package contents are unpacked, built, and then
-moved into the desired location.
-
-* `root/packages/foo/1.2.3` Metadata and contents of foo@1.2.3
-* `root/packages/foo/1.2.3/package` Build location of foo@1.2.3
-* `root/packages/foo/1.2.3/node_modules` Links to (or, on windows, copies of)
- dependencies of foo@1.2.3
-* `root/packages/foo/1.2.3/metadata.json` Metadata about the foo package.
-
-### Installation in `node_modules` Folders
-
-When you run `npm install foo@1.2.3` it downloads and builds the
-package, and then, if there is a package.json file in the current
-working directory, it copies it to `$PWD/node_modules/foo`, so that your
-current package will get it when you do `require("foo")`.
-
-When this is done, it also installs all of foo's dependencies to
-`./node_modules/foo/node_modules/`, so that it will get its dependencies
-appropriately when it calls `require()`. If foo depends on bar, and bar
-depends on baz, then there will also be a
-`./node_modules/foo/node_modules/bar/node_modules/baz`, and so on.
-
-If there is not a package.json in the current working directory, then
-npm walks up the working dir parent paths looking for a package.json,
-indicating the root of a package, or a node_modules folder,
-indicating an npm package deployment location, and then take the party to that
-location. This behavior may be suppressed by setting the `seek-root`
-config value to false.
-
-If no package root is found, then a global installation is performed.
-The global installation may be supressed by setting the `global`
-configuration to false, in which case, the install will fail.
-
-### Global Installation
-
-If the `global` configuration is set to true, or if it is not explicitly
-set false and no suitable node_modules folder was found, then npm will
-install packages "globally".
-
-This means that the module contents are symlinked (or, on windows,
-copied) from `root/<name>/<version>/package` to
-`root/node_modules/<name>`.
-
-### Installing executables
-
-When installing globally, executables are linked (or, on windows,
-shimmed with a .bat file) to `root/bin`.
-
-When doing a
-localized installation, executables are linked (or, on windows, shimmed)
-to `./node_modules/.bin`. This also applies to the case when a globally
-installed package's dependents are being installed into it. Basically,
-whenever writing `.../node_modules/foo`, and the "foo"
-package has an executable named "bar", it'll write it to
-`.../node_modules/.bin/bar`.
-
-It is up to the user to update their PATH environment variable
-appropriately for globally installed executables. When running package
-lifecycle scripts (for example, to build, start, test, etc.), npm will
-put `./node_modules/.bin` as the first item in the PATH environ.
-
-### Installing manpages
-
-npm will install man pages to `root/share/man`. It is up to the user to
-make sure that their man program searches this location.
-
-### Cycles, Conflicts, and Folder Parsimony
-
-Cycles are handled using the property of node's module system that it
-walks up the directories looking for node_modules folders. So, at every
-stage, if a package is already installed in an ancestor node_modules
-folder, then it is not installed at the current location.
-
-Consider the case above, where `foo -> bar -> baz`. Imagine if, in
-addition to that, baz depended on bar, so you'd have:
-`foo -> bar -> baz -> bar -> baz ...`. However, since the folder
-structure is: foo/node_modules/bar/node_modules/baz, there's no need to
-put another copy of bar into .../baz/node_modules, since when it calls
-require("bar"), it will get the copy that is installed in
-foo/node_modules/bar.
-
-This shortcut is only used if the exact same
-version would be installed in multiple nested node_modules folders. It
-is still possible to have `a/node_modules/b/node_modules/a` if the two
-"a" packages are different versions. However, without repeating the
-exact same package multiple times, an infinite regress will always be
-prevented.
-
-Another optimization can be made by installing dependencies at the
-highest level possible, below the localized "target" folder.
-
-For example, consider this dependency graph:
-
- foo
- +-- bar@1.2.3
- | +-- baz@2.x
- | | `-- quux@3.x
- | `-- asdf@*
- `-- baz@1.2.3
- `-- quux@3.x
-
-In this case, we'd expect a folder structure like this:
-
- foo
- +-- node_modules
- +-- bar (1.2.3)
- | `-- node_modules
- | `-- baz (2.0.2)
- +-- quux (3.2.0)
- +-- asdf (0.2.5)
- `-- baz (1.2.3)
-
-Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are
-installed in foo's node_modules folder.
-
-Since baz@1.2.3 depends on quux@3.x, a satisfying version is placed in
-foo's node_modules folder, because there are no conflicts.
-
-Since bar@1.2.3 depends on asdf@*, a satisfying version is placed in
-foo's node_modules folder. It also depends on baz@2.x, but this
-conflicts with the version already installed in foo's node_modules
-folder, so it is installed into the node_modules folder under bar@1.2.3.
-
-baz@2.0.2 depends on quux@3.x, but this dependency is already satisfied
-by the quux version installed in foo's node_modules folder, so nothing
-further needs to be done.
-
-### Snapshotting
-
-Whenever the `npm snapshot` command is run, the package.json file is
-updated to include the versions of all of the packages in the
-`./node_modules` folder as dependencies.
-
-### Publishing
-
-Upon publishing, npm will look in the node_modules folder. If any of
-the items there are on the "dependencies" or "devDependencies" list, and
-are unmodified copies of the corresponding packages in
-`root/node_modules/<name>/<version>/package`, then they will not be
-included in the package tarball.
-
-If the package has been modified, then it is left as-is, and included in
-the package.
-
-This allows a package maintainer to install all of their dependencies
-(and dev dependencies) locally, but only publish those items that cannot
-be found elsewhere.
-
-### Updating
-
-npm keeps track of every installation of foo@1.2.3 in
-`root/packages/foo/1.2.3/metadata.json`.
-
-When updating in a package folder (see algorithm for determining this in
-"Installation in `node_modules` Folders"), npm updates the packages in
-the local folder to the latest versions that are compatible with the
-requirements in the package.json file.
-
-If global is set to `"super"`, then npm will attempt to update
-all copies of packages installed anywhere and everywhere that it is
-aware of.
-
-If `global` is set to `true, or implied by not being in a package folder
-at the time, then npm will update the globally installed packages.
-
-If you do `npm update foo`, and you're in a local package folder, but
-`foo` is not installed there, and it *is* installed globally, then that
-will be equivalent to doing `npm update foo --global`.
-
-### Uninstalling
-
-Uninstalling works like updating.
-
-If global is set to "super", then it removes all traces from everywhere.
-
-If global is set to "true", or implied, then it removes the global copy.
-
-If global is set to "false", or unset and the command is in a package
-folder with a copy of the package being removed, then it removes it from
-the local folder.
-
-### Linking
-
-When `npm link` is run without any arguments in a package folder, then a
-symbolic link is created from that folder to `root/<name>/LINK`.
-Additionally, its package dependencies are installed to its
-./node_modules folder as necessary.
-
-When `npm link <name>` is run in another package folder, a symbolic
-link is created from `root/<name>/LINK` to `./node_modules/<name>`, and
-its dependencies are also installed if necessary. (Generally, it will
-not be necessary, as the package will already have its own node_modules
-folder containing its dependencies.)
-
-When publishing, linked package dependencies are resolved to their
-current state. It is assumed that the linked folder was linked for a
-reason, and may contain changes required for the proper functioning of
-the host program.
-
-#### npm link use case
-
- # create a linked "request" package
- cd ~/projects/request
- npm link
-
- # now write a program that uses request
- mkdir -p ~/projects/my-program
- cd ~/projects/my-program
- git init
- # do your git stuff...
- npm init
- # enter some package.json values
- # now we're ready to rock.
- # use redis, but don't need bleeding edge.
- npm install redis
- # use the linked copy of request
- npm link request
-
- # now any changes to ~/projects/request will
- # be immediately effective in my-program when
- # I do require("request")
-
-#### link on Windows
-
-Not sure how this will work. Maybe linking simply isn't possible?
View
23 doc/future-ideas/remote.md
@@ -1,23 +0,0 @@
-npm-remote(1) -- Execute commands on a remote machine
-=====================================================
-
-## FUTURE
-
-This functionality does not yet exist.
-
-## SYNOPSIS
-
- npm remote <commands>
-
-## DESCRIPTION
-
-Run a command on a remote npm site instance.
-
-In order to do this, the current authenticated user must be in
-the "admin" list on the server, and it must be running with https
-support.
-
-It uses the `host` config to know where to do things.
-
-
-
View
58 doc/future-ideas/site.md
@@ -1,58 +0,0 @@
-npm-site(1) -- Run the npm web site
-===================================
-
-## FUTURE
-
-This functionality does not yet exist.
-
-## SYNOPSIS
-
- npm site [ start | stop ]
-
-## DESCRIPTION
-
-This starts up npm in "site" mode. The following configs are relevant,
-and can either be specified in the `.npmrc` file, or as command line
-options.
-
-* userfile:
- A file containing the encrypted authorization info for all users. If
- specified, then this is used for `npm adduser` requests
- to this registry.
-* admin:
- A comma-delimited list of admin users. All of these must already be
- in the local adduser config. If there is no admin, then the site will
- not allow remote management. All admin usernames must already be
- in the userfile, and a userfile must be specified.
-* listen:
- Ports to listen on for WS requests. The first number is for http,
- the second for https, and the third for secure TCP. Set any to "-",
- or omit, to use the default.
- Defaults to "80,443,15443"
-* registry:
- If a package is not found, then its contents will be fetched from the
- upstream registry, and cached for future retrieval.
-
- isaacs: Make sure that this does loop-detection, so that a "ring" of
- registries can work as a distributed network. Also, once we have
- support for checking multiple registries, you could have a distribution
- ring that secondarily depends on some other upstream resource.
-
-The content for the site is stored in the npm cache directory, which is
-inside the folder used for the `root` setting, at `{root}/.npm/.cache`.
-It is organized in a simple hierarchical folder structure corresponding
-to the web service URLs that npm uses.
-
-## TCP Server
-
-The TCP server starts up to support the `npm remote` command, if there is
-a valid admin userlist.
-
-## NOTE
-
-This also is what happens when you do `npm start npm`.
-
-## SEE ALSO
-
-* npm-remote(1)
-* npm-config(1)
View
100 doc/install.md
@@ -3,6 +3,7 @@ npm-install(1) -- install a package
## SYNOPSIS
+ npm install (with no args in a package dir)
npm install <tarball file>
npm install <tarball url>
npm install <folder>
@@ -13,8 +14,12 @@ npm-install(1) -- install a package
## DESCRIPTION
-This command installs a package, and any packages that it depends on. It
-resolves circular dependencies by talking to the npm registry.
+This command installs a package, and any packages that it depends on.
+
+* npm install (in package directory):
+ Install the dependencies in the local node_modules folder.
+
+ In global mode, it is the same as `npm install $PWD`
* npm install `<tarball file>`:
Install a package that is sitting on the filesystem. Note: if you just want
@@ -37,8 +42,8 @@ resolves circular dependencies by talking to the npm registry.
npm install http://github.com/waveto/node-crypto/tarball/v0.0.5
* npm install `<name>`:
- Do a `<name>@<tag>` install, where `<tag>` is the "tag" config from either your
- .npmrc file, or the --tag argument on the command line.
+ Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
+ `npm help config`)
Example:
@@ -72,97 +77,18 @@ resolves circular dependencies by talking to the npm registry.
npm install sax@">=0.1.0 <0.2.0"
-You may combine multiple arguments, and even multiple types of arguments. For example:
+You may combine multiple arguments, and even multiple types of arguments.
+For example:
npm install sax@">=0.1.0 <0.2.0" bench supervisor
The `--tag` argument will apply to all of the specified install targets.
-The `--force` argument will force npm to fetch remote resources even if a local copy exists on disk.
+The `--force` argument will force npm to fetch remote resources even if a
+local copy exists on disk.
npm install sax --force
-## CONFIGURATION
-
-### root
-
-Default: `$INSTALL_PREFIX/lib/node`
-
-The root folder where packages are installed and npm keeps its data.
-
-### binroot
-
-Default: `$INSTALL_PREFIX/bin`
-
-The folder where executable programs are installed.
-
-Set to "false" to not install executables
-
-### manroot
-
-Default: $INSTALL_PREFIX/share/man
-
-The folder where man pages are installed.
-
-Set to "false" to not install man pages.
-
-### registry
-
-Default: https://registry.npmjs.org/
-
-The base URL of the npm package registry.
-
-### tag
-
-Default: latest
-
-If you ask npm to install a package and don't tell it a specific version, then
-it will install the specified tag.
-
-Note: this has no effect on the npm-tag(1) command.
-
-### dev
-
-If set to a truish value, then it'll install the "devDependencies" as well as
-"dependencies" when installing a package.
-
-Note that devDependencies are *always* installed when linking a package.
-
-### tar
-
-Default: env.TAR or "tar"
-
-The name of a GNU-compatible tar program on your system.
-
-### gzip
-
-Default: env.GZIPBIN or "gzip"
-
-The name of a GNU-compatible gzip program on your system.
-
-### must-install
-
-Default: true
-
-Set to false to not install over packages that already exist. By
-default, `npm install foo` will fetch and install the latest version of
-`foo`, even if it matches a version already installed.
-
-### auto-activate
-
-Default: true
-
-Automatically activate a package after installation, if there is not an active
-version already. Set to "always" to always activate when installing.
-
-### update-dependents
-
-Default: true
-
-Automatically update a package's dependencies after installation, if it is the
-newest version installed. Set to "always" to update dependents when a new
-version is installed, even if it's not the newest.
-
## SEE ALSO
* npm-build(1)
View <