diff options
| author | Ryan Dahl <ry@tinyclouds.org> | 2011-11-21 09:48:45 -0800 |
|---|---|---|
| committer | Ryan Dahl <ry@tinyclouds.org> | 2011-11-21 10:50:52 -0800 |
| commit | b488be127a8cf1e59eb257db3f8eaf6efdb0f275 (patch) | |
| tree | 83436f4f84b9651ea66c3a0d304050252916c149 /deps/npm/doc | |
| parent | 05de01d707cd9a80f34da23445f507f5f2e2c277 (diff) | |
| download | node-new-b488be127a8cf1e59eb257db3f8eaf6efdb0f275.tar.gz | |
Include NPM, update .pkg to install it.
.msi update coming soon.
Diffstat (limited to 'deps/npm/doc')
106 files changed, 4954 insertions, 0 deletions
diff --git a/deps/npm/doc/api/author.md b/deps/npm/doc/api/author.md new file mode 120000 index 0000000000..b7a53cb66b --- /dev/null +++ b/deps/npm/doc/api/author.md @@ -0,0 +1 @@ +owner.md
\ No newline at end of file diff --git a/deps/npm/doc/api/bin.md b/deps/npm/doc/api/bin.md new file mode 100644 index 0000000000..f3dc48286d --- /dev/null +++ b/deps/npm/doc/api/bin.md @@ -0,0 +1,13 @@ +npm-bin(3) -- Display npm bin folder +==================================== + +## SYNOPSIS + + npm.commands.bin(args, cb) + +## DESCRIPTION + +Print the folder where npm will install executables. + +This function should not be used programmatically. Instead, just refer +to the `npm.bin` member. diff --git a/deps/npm/doc/api/bugs.md b/deps/npm/doc/api/bugs.md new file mode 100644 index 0000000000..cc4db8f9ec --- /dev/null +++ b/deps/npm/doc/api/bugs.md @@ -0,0 +1,19 @@ +npm-bugs(3) -- Bugs for a package in a web browser maybe +======================================================== + +## SYNOPSIS + + npm.commands.bugs(package, callback) + +## DESCRIPTION + +This command tries to guess at the likely location of a package's +bug tracker URL, and then tries to open it using the `--browser` +config param. + +Like other commands, the first parameter is an array. This command only +uses the first element, which is expected to be a package name with an +optional version number. + +This command will launch a browser, so this command may not be the most +friendly for programmatic use. diff --git a/deps/npm/doc/api/commands.md b/deps/npm/doc/api/commands.md new file mode 100644 index 0000000000..eb7545639d --- /dev/null +++ b/deps/npm/doc/api/commands.md @@ -0,0 +1,22 @@ +npm-commands(3) -- npm commands +=============================== + +## SYNOPSIS + + npm.commands[<command>](args, callback) + +## DESCRIPTION + +npm comes with a full set of commands, and each of the commands takes a +similar set of arguments. + +In general, all commands on the command object take an **array** of positional +argument **strings**. The last argument to any function is a callback. Some +commands are special and take other optional arguments. + +All commands have their own man page. See `man npm-<command>` for command-line +usage, or `man 3 npm-<command>` for programmatic usage. + +## SEE ALSO + +* npm-index(1) diff --git a/deps/npm/doc/api/config.md b/deps/npm/doc/api/config.md new file mode 100644 index 0000000000..7ae2274281 --- /dev/null +++ b/deps/npm/doc/api/config.md @@ -0,0 +1,45 @@ +npm-config(3) -- Manage the npm configuration files +=================================================== + +## SYNOPSIS + + npm.commands.config(args, callback) + var val = npm.config.get(key) + npm.config.set(key, val) + +## DESCRIPTION + +This function acts much the same way as the command-line version. The first +element in the array tells config what to do. Possible values are: + +* `set` + + Sets a config parameter. The second element in `args` is interpreted as the + key, and the third element is interpreted as the value. + +* `get` + + Gets the value of a config parameter. The second element in `args` is the + key to get the value of. + +* `delete` (`rm` or `del`) + + Deletes a parameter from the config. The second element in `args` is the + key to delete. + +* `list` (`ls`) + + Show all configs that aren't secret. No parameters necessary. + +* `edit`: + + Opens the config file in the default editor. This command isn't very useful + programmatically, but it is made available. + +To programmatically access npm configuration settings, or set them for +the duration of a program, use the `npm.config.set` and `npm.config.get` +functions instead. + +## SEE ALSO + +* npm(3) diff --git a/deps/npm/doc/api/deprecate.md b/deps/npm/doc/api/deprecate.md new file mode 100644 index 0000000000..ac94fd7a9f --- /dev/null +++ b/deps/npm/doc/api/deprecate.md @@ -0,0 +1,32 @@ +npm-deprecate(3) -- Deprecate a version of a package +==================================================== + +## SYNOPSIS + + npm.commands.deprecate(args, callback) + +## DESCRIPTION + +This command will update the npm registry entry for a package, providing +a deprecation warning to all who attempt to install it. + +The 'args' parameter must have exactly two elements: + +* `package[@version]` + + The `version` portion is optional, and may be either a range, or a + specific version, or a tag. + +* `message` + + The warning message that will be printed whenever a user attempts to + install the package. + +Note that you must be the package owner to deprecate something. See the +`owner` and `adduser` help topics. + +## SEE ALSO + +* npm-publish(3) +* npm-unpublish(3) +* npm-registry(1) diff --git a/deps/npm/doc/api/docs.md b/deps/npm/doc/api/docs.md new file mode 100644 index 0000000000..2c5fc5e632 --- /dev/null +++ b/deps/npm/doc/api/docs.md @@ -0,0 +1,19 @@ +npm-docs(3) -- Docs for a package in a web browser maybe +======================================================== + +## SYNOPSIS + + npm.commands.docs(package, callback) + +## DESCRIPTION + +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. + +Like other commands, the first parameter is an array. This command only +uses the first element, which is expected to be a package name with an +optional version number. + +This command will launch a browser, so this command may not be the most +friendly for programmatic use. diff --git a/deps/npm/doc/api/edit.md b/deps/npm/doc/api/edit.md new file mode 100644 index 0000000000..b13fbb8578 --- /dev/null +++ b/deps/npm/doc/api/edit.md @@ -0,0 +1,24 @@ +npm-edit(3) -- Edit an installed package +======================================== + +## SYNOPSIS + + npm.commands.edit(package, callback) + +## DESCRIPTION + +Opens the package folder in the default editor (or whatever you've +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. + +For instance, you can do `npm install connect` to install connect +into your package, and then `npm.commands.edit(["connect"], callback)` +to make a few changes to your locally installed copy. + +The first parameter is a string array with a single element, the package +to open. The package can optionally have a version number attached. + +Since this command opens an editor in a new process, be careful about where +and how this is used. diff --git a/deps/npm/doc/api/explore.md b/deps/npm/doc/api/explore.md new file mode 100644 index 0000000000..a239f3df31 --- /dev/null +++ b/deps/npm/doc/api/explore.md @@ -0,0 +1,18 @@ +npm-explore(3) -- Browse an installed package +============================================= + +## SYNOPSIS + + npm.commands.explore(args, callback) + +## DESCRIPTION + +Spawn a subshell in the directory of the installed package specified. + +If a command is specified, then it is run in the subshell, which then +immediately terminates. + +Note that the package is *not* automatically rebuilt afterwards, so be +sure to use `npm rebuild <pkg>` if you make any changes. + +The first element in the 'args' parameter must be a package name. After that is the optional command, which can be any number of strings. All of the strings will be combined into one, space-delimited command. diff --git a/deps/npm/doc/api/find.md b/deps/npm/doc/api/find.md new file mode 120000 index 0000000000..5b3debb8f1 --- /dev/null +++ b/deps/npm/doc/api/find.md @@ -0,0 +1 @@ +ls.md
\ No newline at end of file diff --git a/deps/npm/doc/api/get.md b/deps/npm/doc/api/get.md new file mode 120000 index 0000000000..3dc8737366 --- /dev/null +++ b/deps/npm/doc/api/get.md @@ -0,0 +1 @@ +config.md
\ No newline at end of file diff --git a/deps/npm/doc/api/help-search.md b/deps/npm/doc/api/help-search.md new file mode 100644 index 0000000000..5c00cfc177 --- /dev/null +++ b/deps/npm/doc/api/help-search.md @@ -0,0 +1,30 @@ +npm-help-search(3) -- Search the help pages +=========================================== + +## SYNOPSIS + + npm.commands.helpSearch(args, [silent,] callback) + +## DESCRIPTION + +This command is rarely useful, but it exists in the rare case that it is. + +This command takes an array of search terms and returns the help pages that +match in order of best match. + +If there is only one match, then npm displays that help section. If there +are multiple results, the results are printed to the screen formatted and the +array of results is returned. Each result is an object with these properties: + +* hits: + A map of args to number of hits on that arg. For example, {"npm": 3} +* found: + Total number of unique args that matched. +* totalHits: + Total number of hits. +* lines: + An array of all matching lines (and some adjacent lines). +* file: + Name of the file that matched + +The silent parameter is not neccessary not used, but it may in the future. diff --git a/deps/npm/doc/api/home.md b/deps/npm/doc/api/home.md new file mode 120000 index 0000000000..8828313f5b --- /dev/null +++ b/deps/npm/doc/api/home.md @@ -0,0 +1 @@ +docs.md
\ No newline at end of file diff --git a/deps/npm/doc/api/init.md b/deps/npm/doc/api/init.md new file mode 100644 index 0000000000..5afc11b3ba --- /dev/null +++ b/deps/npm/doc/api/init.md @@ -0,0 +1,29 @@ +npm init(3) -- Interactively create a package.json file +======================================================= + +## SYNOPSIS + + npm.commands.init(args, callback) + +## DESCRIPTION + +This will ask you a bunch of questions, and then write a package.json for you. + +It attempts to make reasonable guesses about what you want things to be set to, +and then writes a package.json file with the options you've selected. + +If you already have a package.json file, it'll read that first, and default to +the options in there. + +It is strictly additive, so it does not delete options from your package.json +without a really good reason to do so. + +Since this function expects to be run on the command-line, it doesn't work very +well as a programmatically. The best option is to roll your own, and since +JavaScript makes it stupid simple to output formatted JSON, that is the +preferred method. If you're sure you want to handle command-line prompting, +then go ahead and use this programmatically. + +## SEE ALSO + +npm-json(1) diff --git a/deps/npm/doc/api/install.md b/deps/npm/doc/api/install.md new file mode 100644 index 0000000000..12f665a76c --- /dev/null +++ b/deps/npm/doc/api/install.md @@ -0,0 +1,19 @@ +npm-install(3) -- install a package programmatically +==================================================== + +## SYNOPSIS + + npm.commands.install([where,] packages, callback) + +## DESCRIPTION + +This acts much the same ways as installing on the command-line. + +The 'where' parameter is optional and only used internally, and it specifies +where the packages should be installed to. + +The 'packages' parameter is an array of strings. Each element in the array is +the name of a package to be installed. + +Finally, 'callback' is a function that will be called when all packages have been +installed or when an error has been encountered. diff --git a/deps/npm/doc/api/link.md b/deps/npm/doc/api/link.md new file mode 100644 index 0000000000..ad8cefcab3 --- /dev/null +++ b/deps/npm/doc/api/link.md @@ -0,0 +1,33 @@ +npm-link(3) -- Symlink a package folder +======================================= + +## SYNOPSIS + + npm.command.link(callback) + npm.command.link(packages, callback) + +## DESCRIPTION + +Package linking is a two-step process. + +Without parameters, link will create a globally-installed +symbolic link from `prefix/package-name` to the current folder. + +With a parameters, link will create a symlink from the local `node_modules` +folder to the global symlink. + +When creating tarballs for `npm publish`, the linked packages are +"snapshotted" to their current state by resolving the symbolic links. + +This is +handy for installing your own stuff, so that you can work on it and test it +iteratively without having to continually rebuild. + +For example: + + npm.commands.link(cb) # creates global link from the cwd + # (say redis package) + npm.commands.link('redis', cb) # link-install the package + +Now, any changes to the redis package will be reflected in +the package in the current working directory diff --git a/deps/npm/doc/api/list.md b/deps/npm/doc/api/list.md new file mode 120000 index 0000000000..5b3debb8f1 --- /dev/null +++ b/deps/npm/doc/api/list.md @@ -0,0 +1 @@ +ls.md
\ No newline at end of file diff --git a/deps/npm/doc/api/ln.md b/deps/npm/doc/api/ln.md new file mode 120000 index 0000000000..243f994145 --- /dev/null +++ b/deps/npm/doc/api/ln.md @@ -0,0 +1 @@ +link.md
\ No newline at end of file diff --git a/deps/npm/doc/api/load.md b/deps/npm/doc/api/load.md new file mode 100644 index 0000000000..a95a6b295d --- /dev/null +++ b/deps/npm/doc/api/load.md @@ -0,0 +1,26 @@ +npm-load(3) -- Load config settings +=================================== + +## SYNOPSIS + + npm.load(conf, cb) + +## DESCRIPTION + +npm.load() must be called before any other function call. Both parameters are +optional, but the second is recommended. + +The first parameter is an object hash of command-line config params, and the +second parameter is a callback that will be called when npm is loaded and +ready to serve. + +The first parameter should follow a similar structure as the package.json +config object. + +For example, to emulate the --dev flag, pass an object that looks like this: + + { + "dev": true + } + +For a list of all the available command-line configs, see `npm help config` diff --git a/deps/npm/doc/api/ls.md b/deps/npm/doc/api/ls.md new file mode 100644 index 0000000000..a6c0a13821 --- /dev/null +++ b/deps/npm/doc/api/ls.md @@ -0,0 +1,50 @@ +npm-ls(3) -- List installed packages +====================================== + +## SYNOPSIS + + npm.commands.ls(args, [silent,] callback) + +## DESCRIPTION + +This command will print to stdout all the versions of packages that are +installed, as well as their dependencies, in a tree-structure. It will also +return that data using the callback. + +This command does not take any arguments, but args must be defined. +Beyond that, if any arguments are passed in, npm will politely warn that it +does not take positional arguments, though you may set config flags +like with any other command, such as `global` to list global packages. + +It will print out extraneous, missing, and invalid packages. + +If the silent parameter is set to true, nothing will be output to the screen, +but the data will still be returned. + +## CONFIGURATION + +### long + +* Default: false +* Type: Boolean + +Show extended information. + +### parseable + +* Default: false +* Type: Boolean + +Show parseable output instead of tree view. + +### global + +* Default: false +* Type: Boolean + +List packages in the global install prefix instead of in the current +project. + +Note, if parseable is set or long isn't set, then duplicates will be trimmed. +This means that if a submodule a same dependency as a parent module, then the +dependency will only be output once. diff --git a/deps/npm/doc/api/npm.md b/deps/npm/doc/api/npm.md new file mode 100644 index 0000000000..a2f034c4b7 --- /dev/null +++ b/deps/npm/doc/api/npm.md @@ -0,0 +1,115 @@ +npm(3) -- node package manager +============================== + +## SYNOPSIS + + var npm = require("npm") + npm.load(configObject, function (er, npm) { + // use the npm object, now that it's loaded. + + npm.config.set(key, val) + val = npm.config.get(key) + + console.log("prefix = %s", npm.prefix) + + npm.commands.install(["package"], cb) + }) + +## VERSION + +@VERSION@ + +## DESCRIPTION + +This is the API documentation for npm. +To find documentation of the command line +client, see `npm(1)`. + +Prior to using npm's commands, +`npm.load()` must be called with an object hash of +top-level configs. In the npm command line client, +this set of configs is parsed from the command line options. Additional +configuration params are loaded from two configuration files. See +`npm-config(1)` for more information. + +After that, each of the functions are accessible in the +commands object: `npm.commands.<cmd>`. See `npm-index(1)` for a list of +all possible commands. + +All commands on the command object take an **array** of positional argument +**strings**. The last argument to any function is a callback. Some +commands take other optional arguments. + +Configs cannot currently be set on a per function basis, as each call to +npm.config.set will change the value for *all* npm commands in that process. + +To find API documentation for a specific command, run the `npm apihelp` +command. + +## METHODS AND PROPERTIES + +* `npm.load(configs, cb)` + + Load the configuration params, and call the `cb` function once the + globalconfig and userconfig files have been loaded as well, or on + nextTick if they've already been loaded. + +* `npm.config` + + An object for accessing npm configuration parameters. + + * `npm.config.get(key)` + * `npm.config.set(key, val)` + * `npm.config.del(key)` + +* `npm.dir` or `npm.root` + + The `node_modules` directory where npm will operate. + +* `npm.prefix` + + The prefix where npm is operating. (Most often the current working + directory.) + +* `npm.cache` + + The place where npm keeps JSON and tarballs it fetches from the + registry (or uploads to the registry). + +* `npm.tmp` + + npm's temporary working directory. + +* `npm.deref` + + Get the "real" name for a command that has either an alias or + abbreviation. + +## MAGIC + +For each of the methods in the `npm.commands` hash, a method is added to +the npm object, which takes a set of positional string arguments rather +than an array and a callback. + +If the last argument is a callback, then it will use the supplied +callback. However, if no callback is provided, then it will print out +the error or results. + +For example, this would work in a node repl: + + > npm = require("npm") + > npm.load() // wait a sec... + > npm.install("dnode", "express") + +Note that that *won't* work in a node program, since the `install` +method will get called before the configuration load is completed. + +## ABBREVS + +In order to support `npm ins foo` instead of `npm install foo`, the +`npm.commands` object has a set of abbreviations as well as the full +method names. Use the `npm.deref` method to find the real name. + +For example: + + var cmd = npm.deref("unp") // cmd === "unpublish" diff --git a/deps/npm/doc/api/outdated.md b/deps/npm/doc/api/outdated.md new file mode 100644 index 0000000000..89f4cf6faa --- /dev/null +++ b/deps/npm/doc/api/outdated.md @@ -0,0 +1,13 @@ +npm-outdated(3) -- Check for outdated packages +============================================== + +## SYNOPSIS + + npm.commands.outdated([packages,] callback) + +## DESCRIPTION + +This command will check the registry to see if the specified packages are +currently outdated. + +If the 'packages' parameter is left out, npm will check all packages. diff --git a/deps/npm/doc/api/owner.md b/deps/npm/doc/api/owner.md new file mode 100644 index 0000000000..de203c072a --- /dev/null +++ b/deps/npm/doc/api/owner.md @@ -0,0 +1,31 @@ +npm-owner(3) -- Manage package owners +===================================== + +## SYNOPSIS + + npm.commands.owner(args, callback) + +## DESCRIPTION + +The first element of the 'args' parameter defines what to do, and the subsequent +elements depend on the action. Possible values for the action are (order of +parameters are given in parenthesis): + +* ls (package): + 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. +* add (user, package): + Add a new user as a maintainer of a package. This user is enabled to modify + metadata, publish new versions, and add other owners. +* rm (user, package): + Remove a user from the package owner list. This immediately revokes their + privileges. + +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. + +## SEE ALSO + +* npm-publish(3) +* npm-registry(1) diff --git a/deps/npm/doc/api/pack.md b/deps/npm/doc/api/pack.md new file mode 100644 index 0000000000..cb339c0c42 --- /dev/null +++ b/deps/npm/doc/api/pack.md @@ -0,0 +1,19 @@ +npm-pack(3) -- Create a tarball from a package +============================================== + +## SYNOPSIS + + npm.commands.pack([packages,] callback) + +## DESCRIPTION + +For anything that's installable (that is, a package folder, tarball, +tarball url, name@tag, name@version, or name), this command will fetch +it to the cache, and then copy the tarball to the current working +directory as `<name>-<version>.tgz`, and then write the filenames out to +stdout. + +If the same package is specified multiple times, then the file will be +overwritten the second time. + +If no arguments are supplied, then npm packs the current package folder. diff --git a/deps/npm/doc/api/prefix.md b/deps/npm/doc/api/prefix.md new file mode 100644 index 0000000000..806dd4b6cb --- /dev/null +++ b/deps/npm/doc/api/prefix.md @@ -0,0 +1,15 @@ +npm-prefix(3) -- Display prefix +=============================== + +## SYNOPSIS + + npm.commands.prefix(args, callback) + +## DESCRIPTION + +Print the prefix to standard out. + +'args' is never used and callback is never called with data. +'args' must be present or things will break. + +This function is not useful programmatically diff --git a/deps/npm/doc/api/prune.md b/deps/npm/doc/api/prune.md new file mode 100644 index 0000000000..2a4f177485 --- /dev/null +++ b/deps/npm/doc/api/prune.md @@ -0,0 +1,17 @@ +npm-prune(3) -- Remove extraneous packages +========================================== + +## SYNOPSIS + + npm.commands.prune([packages,] callback) + +## DESCRIPTION + +This command removes "extraneous" packages. + +The first parameter is optional, and it specifies packages to be removed. + +No packages are specified, then all packages will be checked. + +Extraneous packages are packages that are not listed on the parent +package's dependencies list. diff --git a/deps/npm/doc/api/publish.md b/deps/npm/doc/api/publish.md new file mode 100644 index 0000000000..a743303f88 --- /dev/null +++ b/deps/npm/doc/api/publish.md @@ -0,0 +1,30 @@ +npm-publish(3) -- Publish a package +=================================== + +## SYNOPSIS + + npm.commands.publish([packages,] callback) + +## DESCRIPTION + +Publishes a package to the registry so that it can be installed by name. +Possible values in the 'packages' array are: + +* `<folder>`: + A folder containing a package.json file + +* `<tarball>`: + A url or file path to a gzipped tar archive containing a single folder + with a package.json file inside. + +If the package array is empty, npm will try to publish something in the +current working directory. + +This command could fails if one of the packages specified already exists in +the registry. Overwrites when the "force" environment variable is set. + +## SEE ALSO + +* npm-registry(1) +* npm-adduser(1) +* npm-owner(3) diff --git a/deps/npm/doc/api/rebuild.md b/deps/npm/doc/api/rebuild.md new file mode 100644 index 0000000000..8b8989806a --- /dev/null +++ b/deps/npm/doc/api/rebuild.md @@ -0,0 +1,16 @@ +npm-rebuild(3) -- Rebuild a package +=================================== + +## SYNOPSIS + + npm.commands.rebuild([packages,] callback) + +## DESCRIPTION + +This command runs the `npm build` command on each of the matched packages. This is useful +when you install a new version of node, and must recompile all your C++ addons with +the new binary. If no 'packages' parameter is specify, every package will be rebuilt. + +## CONFIGURATION + +See `npm help build` diff --git a/deps/npm/doc/api/restart.md b/deps/npm/doc/api/restart.md new file mode 100644 index 0000000000..c40704438e --- /dev/null +++ b/deps/npm/doc/api/restart.md @@ -0,0 +1,22 @@ +npm-restart(3) -- Start a package +================================= + +## SYNOPSIS + + npm.commands.restart(packages, callback) + +## DESCRIPTION + +This runs a package's "restart" script, if one was provided. +Otherwise it runs package's "stop" script, if one was provided, and then +the "start" script. + +If no version is specified, then it restarts the "active" version. + +npm can run tests on multiple packages. Just specify multiple packages +in the `packages` parameter. + +## SEE ALSO + +* npm-start(3) +* npm-stop(3) diff --git a/deps/npm/doc/api/rm.md b/deps/npm/doc/api/rm.md new file mode 120000 index 0000000000..32d3b511f9 --- /dev/null +++ b/deps/npm/doc/api/rm.md @@ -0,0 +1 @@ +uninstall.md
\ No newline at end of file diff --git a/deps/npm/doc/api/root.md b/deps/npm/doc/api/root.md new file mode 100644 index 0000000000..1c3ab56402 --- /dev/null +++ b/deps/npm/doc/api/root.md @@ -0,0 +1,15 @@ +npm-root(3) -- Display npm root +=============================== + +## SYNOPSIS + + npm.commands.root(args, callback) + +## DESCRIPTION + +Print the effective `node_modules` folder to standard out. + +'args' is never used and callback is never called with data. +'args' must be present or things will break. + +This function is not useful programmatically. diff --git a/deps/npm/doc/api/run-script.md b/deps/npm/doc/api/run-script.md new file mode 100644 index 0000000000..f15900ecbc --- /dev/null +++ b/deps/npm/doc/api/run-script.md @@ -0,0 +1,27 @@ +npm-run-script(3) -- Run arbitrary package scripts +================================================== + +## SYNOPSIS + + npm.commands.run-script(args, callback) + +## DESCRIPTION + +This runs an arbitrary command from a package's "scripts" object. + +It is used by the test, start, restart, and stop commands, but can be +called directly, as well. + +The 'args' parameter is an array of strings. Behavior depends on the number +of elements. If there is only one element, npm assumes that the element +represents a command to be run on the local repository. If there is more than +one element, then the first is assumed to be the package and the second is +assumed to be the command to run. All other elements are ignored. + +## SEE ALSO + +* npm-scripts(1) +* npm-test(3) +* npm-start(3) +* npm-restart(3) +* npm-stop(3) diff --git a/deps/npm/doc/api/search.md b/deps/npm/doc/api/search.md new file mode 100644 index 0000000000..30651d76a4 --- /dev/null +++ b/deps/npm/doc/api/search.md @@ -0,0 +1,35 @@ +npm-search(3) -- Search for packages +==================================== + +## SYNOPSIS + + npm.commands.search(searchTerms, [silent,] [staleness,] callback) + +## DESCRIPTION + +Search the registry for packages matching the search terms. The available parameters are: + +* searchTerms: + Array of search terms. These terms are case-insensitive. +* silent: + If true, npm will not log anything to the console. +* staleness: + This is the threshold for stale packages. "Fresh" packages are not refreshed + from the registry. This value is measured in seconds. +* callback: + Returns an object where each key is the name of a package, and the value + is information about that package along with a 'words' property, which is + a space-delimited string of all of the interesting words in that package. + The only properties included are those that are searched, which generally include: + + * name + * description + * maintainers + * url + * keywords + +A search on the registry excludes any result that does not match all of the +search terms. It also removes any items from the results that contain an +excluded term (the "searchexclude" config). The search is case insensitive +and doesn't try to read your mind (it doesn't do any verb tense matching or the +like). diff --git a/deps/npm/doc/api/set.md b/deps/npm/doc/api/set.md new file mode 120000 index 0000000000..3dc8737366 --- /dev/null +++ b/deps/npm/doc/api/set.md @@ -0,0 +1 @@ +config.md
\ No newline at end of file diff --git a/deps/npm/doc/api/start.md b/deps/npm/doc/api/start.md new file mode 100644 index 0000000000..74491146aa --- /dev/null +++ b/deps/npm/doc/api/start.md @@ -0,0 +1,13 @@ +npm-start(3) -- Start a package +=============================== + +## SYNOPSIS + + npm.commands.start(packages, callback) + +## DESCRIPTION + +This runs a package's "start" script, if one was provided. + +npm can run tests on multiple packages. Just specify multiple packages +in the `packages` parameter. diff --git a/deps/npm/doc/api/stop.md b/deps/npm/doc/api/stop.md new file mode 100644 index 0000000000..0f8333d351 --- /dev/null +++ b/deps/npm/doc/api/stop.md @@ -0,0 +1,13 @@ +npm-stop(3) -- Stop a package +============================= + +## SYNOPSIS + + npm.commands.stop(packages, callback) + +## DESCRIPTION + +This runs a package's "stop" script, if one was provided. + +npm can run stop on multiple packages. Just specify multiple packages +in the `packages` parameter. diff --git a/deps/npm/doc/api/submodule.md b/deps/npm/doc/api/submodule.md new file mode 100644 index 0000000000..2d8bafaa31 --- /dev/null +++ b/deps/npm/doc/api/submodule.md @@ -0,0 +1,28 @@ +npm-submodule(3) -- Add a package as a git submodule +==================================================== + +## SYNOPSIS + + npm.commands.submodule(packages, callback) + +## DESCRIPTION + +For each package specified, npm will check if it has a git repository url +in its package.json description then add it as a git submodule at +`node_modules/<pkg name>`. + +This is a convenience only. From then on, it's up to you to manage +updates by using the appropriate git commands. npm will stubbornly +refuse to update, modify, or remove anything with a `.git` subfolder +in it. + +This command also does not install missing dependencies, if the package +does not include them in its git repository. If `npm ls` reports that +things are missing, you can either install, link, or submodule them yourself, +or you can do `npm explore <pkgname> -- npm install` to install the +dependencies into the submodule folder. + +## SEE ALSO + +* npm help json +* git help submodule diff --git a/deps/npm/doc/api/tag.md b/deps/npm/doc/api/tag.md new file mode 100644 index 0000000000..b5a3d7faa6 --- /dev/null +++ b/deps/npm/doc/api/tag.md @@ -0,0 +1,23 @@ +npm-tag(3) -- Tag a published version +===================================== + +## SYNOPSIS + + npm.commands.tag(package@version, tag, callback) + +## DESCRIPTION + +Tags the specified version of the package with the specified tag, or the +`--tag` config if not specified. + +The 'package@version' is an array of strings, but only the first two elements are +currently used. + +The first element must be in the form package@version, where package +is the package name and version is the version number (much like installing a +specific version). + +The second element is the name of the tag to tag this version with. If this +parameter is missing or falsey (empty), the default froom the config will be +used. For more information about how to set this config, check +`man 3 npm-config` for programmatic usage or `man npm-config` for cli usage. diff --git a/deps/npm/doc/api/test.md b/deps/npm/doc/api/test.md new file mode 100644 index 0000000000..bc48dcc35f --- /dev/null +++ b/deps/npm/doc/api/test.md @@ -0,0 +1,16 @@ +npm-test(3) -- Test a package +============================= + +## SYNOPSIS + + npm.commands.test(packages, callback) + +## DESCRIPTION + +This runs a package's "test" script, if one was provided. + +To run tests as a condition of installation, set the `npat` config to +true. + +npm can run tests on multiple packages. Just specify multiple packages +in the `packages` parameter. diff --git a/deps/npm/doc/api/uninstall.md b/deps/npm/doc/api/uninstall.md new file mode 100644 index 0000000000..4505295b3b --- /dev/null +++ b/deps/npm/doc/api/uninstall.md @@ -0,0 +1,16 @@ +npm-uninstall(3) -- uninstall a package programmatically +======================================================== + +## SYNOPSIS + + npm.commands.uninstall(packages, callback) + +## DESCRIPTION + +This acts much the same ways as uninstalling on the command-line. + +The 'packages' parameter is an array of strings. Each element in the array is +the name of a package to be uninstalled. + +Finally, 'callback' is a function that will be called when all packages have been +uninstalled or when an error has been encountered. diff --git a/deps/npm/doc/api/unpublish.md b/deps/npm/doc/api/unpublish.md new file mode 100644 index 0000000000..6cbc5c1f37 --- /dev/null +++ b/deps/npm/doc/api/unpublish.md @@ -0,0 +1,20 @@ +npm-unpublish(3) -- Remove a package from the registry +====================================================== + +## SYNOPSIS + + npm.commands.unpublish(package, callback) + +## DESCRIPTION + +This removes a package version from the registry, deleting its +entry and removing the tarball. + +The package parameter must be defined. + +Only the first element in the package parameter is used. If there is no first +element, then npm assumes that the package at the current working directory +is what is meant. + +If no version is specified, or if all versions are removed then +the root package entry is removed from the registry entirely. diff --git a/deps/npm/doc/api/update.md b/deps/npm/doc/api/update.md new file mode 100644 index 0000000000..bf02fd3c84 --- /dev/null +++ b/deps/npm/doc/api/update.md @@ -0,0 +1,11 @@ +npm-update(3) -- Update a package +================================= + +## SYNOPSIS + npm.commands.update(packages, callback) + +# DESCRIPTION + +Updates a package, upgrading it to the latest version. It also installs any missing packages. + +The 'packages' argument is an array of packages to update. The 'callback' parameter will be called when done or when an error occurs. diff --git a/deps/npm/doc/api/version.md b/deps/npm/doc/api/version.md new file mode 100644 index 0000000000..bd40102c45 --- /dev/null +++ b/deps/npm/doc/api/version.md @@ -0,0 +1,18 @@ +npm-version(3) -- Bump a package version +======================================== + +## SYNOPSIS + + npm.commands.version(newversion, callback) + +## DESCRIPTION + +Run this in a package directory to bump the version and write the new +data back to the package.json file. + +If run in a git repo, it will also create a version commit and tag, and +fail if the repo is not clean. + +Like all other commands, this function takes a string array as its first +parameter. The difference, however, is this function will fail if it does +not have exactly one element. The only element should be a version number. diff --git a/deps/npm/doc/api/view.md b/deps/npm/doc/api/view.md new file mode 100644 index 0000000000..fd0076c967 --- /dev/null +++ b/deps/npm/doc/api/view.md @@ -0,0 +1,93 @@ +npm-view(3) -- View registry info +================================= + +## SYNOPSIS + + npm.commands.view(args, [silent,] callback) + +## DESCRIPTION + +This command shows data about a package and prints it to the stream +referenced by the `outfd` config, which defaults to stdout. + +The "args" parameter is an ordered list that closely resembles the command-line +usage. The elements should be ordered such that the first element is +the package and version (package@version). The version is optional. After that, +the rest of the parameters are fields with optional subfields ("field.subfield") +which can be used to get only the information desired from the registry. + +The callback will be passed all of the data returned by the query. + +For example, to get the package registry entry for the `connect` package, +you can do this: + + npm.commands.view(["connect"], callback) + +If no version is specified, "latest" is assumed. + +Field names can be specified after the package descriptor. +For example, to show the dependencies of the `ronn` package at version +0.3.5, you could do the following: + + npm.commands.view(["ronn@0.3.5", "dependencies"], callback) + +You can view child field by separating them with a period. +To view the git repository URL for the latest version of npm, you could +do this: + + npm.commands.view(["npm", "repository.url"], callback) + +For fields that are arrays, requesting a non-numeric field will return +all of the values from the objects in the list. For example, to get all +the contributor names for the "express" project, you can do this: + + npm.commands.view(["express", "contributors.email"], callback) + +You may also use numeric indices in square braces to specifically select +an item in an array field. To just get the email address of the first +contributor in the list, you can do this: + + npm.commands.view(["express", "contributors[0].email"], callback) + +Multiple fields may be specified, and will be printed one after another. +For exampls, to get all the contributor names and email addresses, you +can do this: + + npm.commands.view(["express", "contributors.name", "contributors.email"], callback) + +"Person" fields are shown as a string if they would be shown as an +object. So, for example, this will show the list of npm contributors in +the shortened string format. (See `npm help json` for more on this.) + + npm.commands.view(["npm", "contributors"], callback) + +If a version range is provided, then data will be printed for every +matching version of the package. This will show which version of jsdom +was required by each matching version of yui3: + + npm.commands.view(["yui3@'>0.5.4'", "dependencies.jsdom"], callback) + +## OUTPUT + +If only a single string field for a single version is output, then it +will not be colorized or quoted, so as to enable piping the output to +another command. + +If the version range matches multiple versions, than each printed value +will be prefixed with the version it applies to. + +If multiple fields are requested, than each of them are prefixed with +the field name. + +Console output can be disabled by setting the 'silent' parameter to true. + +## RETURN VALUE + +The data returned will be an object in this formation: + + { <version>: + { <field>: <value> + , ... } + , ... } + +corresponding to the list of fields selected. diff --git a/deps/npm/doc/api/whoami.md b/deps/npm/doc/api/whoami.md new file mode 100644 index 0000000000..598a1ab1a3 --- /dev/null +++ b/deps/npm/doc/api/whoami.md @@ -0,0 +1,15 @@ +npm-whoami(3) -- Display npm username +===================================== + +## SYNOPSIS + + npm.commands.whoami(args, callback) + +## DESCRIPTION + +Print the `username` config to standard output. + +'args' is never used and callback is never called with data. +'args' must be present or things will break. + +This function is not useful programmatically diff --git a/deps/npm/doc/cli/adduser.md b/deps/npm/doc/cli/adduser.md new file mode 100644 index 0000000000..51aa6f6a3d --- /dev/null +++ b/deps/npm/doc/cli/adduser.md @@ -0,0 +1,36 @@ +npm-adduser(1) -- Add a registry user account +============================================= + +## SYNOPSIS + + npm adduser + +## DESCRIPTION + +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. + +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 + +### registry + +Default: http://registry.npmjs.org/ + +The base URL of the npm package registry. + +## SEE ALSO + +* npm-registry(1) +* npm-config(1) +* npm-owner(1) +* npm-whoami(1) diff --git a/deps/npm/doc/cli/author.md b/deps/npm/doc/cli/author.md new file mode 120000 index 0000000000..b7a53cb66b --- /dev/null +++ b/deps/npm/doc/cli/author.md @@ -0,0 +1 @@ +owner.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/bin.md b/deps/npm/doc/cli/bin.md new file mode 100644 index 0000000000..2c2e7c4772 --- /dev/null +++ b/deps/npm/doc/cli/bin.md @@ -0,0 +1,17 @@ +npm-bin(1) -- Display npm bin folder +==================================== + +## SYNOPSIS + + npm bin + +## DESCRIPTION + +Print the folder where npm will install executables. + +## SEE ALSO + +* npm-prefix(1) +* npm-root(1) +* npm-folders(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/bugs.md b/deps/npm/doc/cli/bugs.md new file mode 100644 index 0000000000..2e57cc891b --- /dev/null +++ b/deps/npm/doc/cli/bugs.md @@ -0,0 +1,38 @@ +npm-bugs(1) -- Bugs for a package in a web browser maybe +======================================================== + +## SYNOPSIS + + npm bugs <pkgname> + +## DESCRIPTION + +This command tries to guess at the likely location of a package's +bug tracker URL, and then tries to open it using the `--browser` +config param. + +## CONFIGURATION + +### browser + +* Default: OS X: `"open"`, others: `"google-chrome"` +* Type: String + +The browser that is called by the `npm bugs` command to open websites. + +### registry + +* Default: https://registry.npmjs.org/ +* Type: url + +The base URL of the npm package registry. + + +## SEE ALSO + +* npm-docs(1) +* npm-view(1) +* npm-publish(1) +* npm-registry(1) +* npm-config(1) +* npm-json(1) diff --git a/deps/npm/doc/cli/build.md b/deps/npm/doc/cli/build.md new file mode 100644 index 0000000000..978f4a6d62 --- /dev/null +++ b/deps/npm/doc/cli/build.md @@ -0,0 +1,22 @@ +npm-build(1) -- Build a package +=============================== + +## SYNOPSIS + + npm build <package-folder> + +* `<package-folder>`: + A folder containing a `package.json` file in its root. + +## DESCRIPTION + +This is the plumbing command called by `npm link` and `npm install`. + +It should generally not be called directly. + +## SEE ALSO + +* npm-install(1) +* npm-link(1) +* npm-scripts(1) +* npm-json(1) diff --git a/deps/npm/doc/cli/bundle.md b/deps/npm/doc/cli/bundle.md new file mode 100644 index 0000000000..69b3d83e45 --- /dev/null +++ b/deps/npm/doc/cli/bundle.md @@ -0,0 +1,14 @@ +npm-bundle(1) -- REMOVED +======================== + +## DESCRIPTION + +The `npm bundle` command has been removed in 1.0, for the simple reason +that it is no longer necessary, as the default behavior is now to +install packages into the local space. + +Just use `npm install` now to do what `npm bundle` used to do. + +## SEE ALSO + +* npm-install(1) diff --git a/deps/npm/doc/cli/cache.md b/deps/npm/doc/cli/cache.md new file mode 100644 index 0000000000..1fa128ad44 --- /dev/null +++ b/deps/npm/doc/cli/cache.md @@ -0,0 +1,70 @@ +npm-cache(1) -- Manipulates packages cache +========================================== + +## SYNOPSIS + + npm cache add <tarball file> + npm cache add <folder> + npm cache add <tarball url> + npm cache add <name>@<version> + + npm cache ls [<path>] + + npm cache clean [<path>] + +## DESCRIPTION + +Used to add, list, or clear the npm cache folder. + +* add: + 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. + +* ls: + 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 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 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/: + A folder containing the package contents as they appear in the tarball. +* .../package.json: + The package.json file, as npm sees it, with overlays applied and a _id attribute. +* .../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 + +### cache + +Default: `$HOME/.npm` on Posix, or `$HOME/npm-cache` on Windows. + +The root cache folder. + +## SEE ALSO + +* npm-folders(1) +* npm-config(1) +* npm-install(1) +* npm-publish(1) +* npm-pack(1) diff --git a/deps/npm/doc/cli/changelog.md b/deps/npm/doc/cli/changelog.md new file mode 100644 index 0000000000..0115405ca0 --- /dev/null +++ b/deps/npm/doc/cli/changelog.md @@ -0,0 +1,36 @@ +npm-changelog(1) -- Changes +=========================== + +## HISTORY + +### 1.0 +* Greatly simplified folder structure +* Install locally (bundle by default) +* Drastic rearchitecture + +### 0.3 +* More correct permission/uid handling when running as root +* Require node 0.4.0 +* Reduce featureset +* Packages without "main" modules don't export modules +* Remove support for invalid JSON (since node doesn't support it) + +### 0.2 +* First allegedly "stable" release +* Most functionality implemented +* Used shim files and `name@version` symlinks +* Feature explosion +* Kind of a mess + +### 0.1 +* push to beta, and announce +* Solaris and Cygwin support + +### 0.0 +* Lots of sketches and false starts; abandoned a few times +* Core functionality established + +## SEE ALSO + +* npm(1) +* npm-faq(1) diff --git a/deps/npm/doc/cli/coding-style.md b/deps/npm/doc/cli/coding-style.md new file mode 100644 index 0000000000..f0640c85cd --- /dev/null +++ b/deps/npm/doc/cli/coding-style.md @@ -0,0 +1,190 @@ +npm-coding-style(1) -- npm's "funny" coding style +================================================= + +## DESCRIPTION + +npm's coding style is a bit unconventional. It is not different for +difference's sake, but rather a carefully crafted style that is +designed to reduce visual clutter and make bugs more apparent. + +If you want to contribute to npm (which is very encouraged), you should +make your code conform to npm's style. + +## Line Length + +Keep lines shorter than 80 characters. It's better for lines to be +too short than to be too long. Break up long lists, objects, and other +statements onto multiple lines. + +## Indentation + +Two-spaces. Tabs are better, but they look like hell in web browsers +(and on github), and node uses 2 spaces, so that's that. + +Configure your editor appropriately. + +## Curly braces + +Curly braces belong on the same line as the thing that necessitates them. + +Bad: + + function () + { + +Good: + + function () { + +If a block needs to wrap to the next line, use a curly brace. Don't +use it if it doesn't. + +Bad: + + if (foo) { bar() } + while (foo) + bar() + +Good: + + if (foo) bar() + while (foo) { + bar() + } + +## Semicolons + +Don't use them except in four situations: + +* `for (;;)` loops. They're actually required. +* null loops like: `while (something) ;` (But you'd better have a good + reason for doing that.) +* case "foo": doSomething(); break +* In front of a leading ( or [ at the start of the line. + This prevents the expression from being interpreted + as a function call or property access, respectively. + +Some examples of good semicolon usage: + + ;(x || y).doSomething() + ;[a, b, c].forEach(doSomething) + for (var i = 0; i < 10; i ++) { + switch (state) { + case "begin": start(); continue + case "end": finish(); break + default: throw new Error("unknown state") + } + end() + } + +Note that starting lines with `-` and `+` also should be prefixed +with a semicolon, but this is much less common. + +## Comma First + +If there is a list of things separated by commas, and it wraps +across multiple lines, put the comma at the start of the next +line, directly below the token that starts the list. Put the +final token in the list on a line by itself. For example: + + var magicWords = [ "abracadabra" + , "gesundheit" + , "ventrilo" + ] + , spells = { "fireball" : function () { setOnFire() } + , "water" : function () { putOut() } + } + , a = 1 + , b = "abc" + , etc + , somethingElse + +## Whitespace + +Put a single space in front of ( for anything other than a function call. +Also use a single space wherever it makes things more readable. + +Don't leave trailing whitespace at the end of lines. Don't indent empty +lines. Don't use more spaces than are helpful. + +## Functions + +Use named functions. They make stack traces a lot easier to read. + +## Callbacks, Sync/async Style + +Use the asynchronous/non-blocking versions of things as much as possible. +It might make more sense for npm to use the synchronous fs APIs, but this +way, the fs and http and child process stuff all uses the same callback-passing +methodology. + +The callback should always be the last argument in the list. Its first +argument is the Error or null. + +Be very careful never to ever ever throw anything. It's worse than useless. +Just send the error message back as the first argument to the callback. + +## Errors + +Always create a new Error object with your message. Don't just return a +string message to the callback. Stack traces are handy. + +Use the `require("./utils/log").er` function. It takes a callback and an +error message, and returns an object that will report the message in the +event of a failure. It's quite handy. + + function myThing (args, cb) { + getData(args, function (er, data) { + if (er) return log.er(cb, "Couldn't get data")(er) + doSomethingElse(data, cb) + }) + } + function justHasToWork (cb) { + doSomething(log.er(cb, "the doSomething failed.")) + } + +## Logging + +Please clean up logs when they are no longer helpful. In particular, +logging the same object over and over again is not helpful. Logs should +report what's happening so that it's easier to track down where a fault +occurs. + +Use appropriate log levels. The default log() function logs at the +"info" level. See `npm-config(1)` and search for "loglevel". + +## Case, naming, etc. + +Use lowerCamelCase for multiword identifiers when they refer to objects, +functions, methods, members, or anything not specified in this section. + +Use UpperCamelCase for class names (things that you'd pass to "new"). + +Use all-lower-hyphen-css-case for multiword filenames and config keys. + +Use named functions. They make stack traces easier to follow. + +Use CAPS_SNAKE_CASE for constants, things that should never change +and are rarely used. + +Use a single uppercase letter for function names where the function +would normally be anonymous, but needs to call itself recursively. It +makes it clear that it's a "throwaway" function. + +## null, undefined, false, 0 + +Boolean variables and functions should always be either `true` or +`false`. Don't set it to 0 unless it's supposed to be a number. + +When something is intentionally missing or removed, set it to `null`. + +Don't set things to `undefined`. Reserve that value to mean "not yet +set to anything." + +Boolean objects are verboten. + +## SEE ALSO + +* npm-developers(1) +* npm-faq(1) +* npm(1) diff --git a/deps/npm/doc/cli/completion.md b/deps/npm/doc/cli/completion.md new file mode 100644 index 0000000000..48bc50fd87 --- /dev/null +++ b/deps/npm/doc/cli/completion.md @@ -0,0 +1,29 @@ +npm-completion(1) -- Tab Completion for npm +=========================================== + +## SYNOPSIS + + . <(npm completion) + +## DESCRIPTION + +Enables tab-completion in all npm commands. + +The synopsis above +loads the completions into your current shell. Adding it to +your ~/.bashrc or ~/.zshrc will make the completions available +everywhere. + +You may of course also pipe the output of npm completion to a file +such as `/usr/local/etc/bash_completion.d/npm` if you have a system +that will read that file for you. + +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. + +## SEE ALSO + +* npm-developers(1) +* npm-faq(1) +* npm(1) diff --git a/deps/npm/doc/cli/config.md b/deps/npm/doc/cli/config.md new file mode 100644 index 0000000000..1ede36292e --- /dev/null +++ b/deps/npm/doc/cli/config.md @@ -0,0 +1,665 @@ +npm-config(1) -- Manage the npm configuration file +================================================== + +## SYNOPSIS + + npm config set <key> <value> [--global] + npm config get <key> + npm config delete <key> + npm config list + npm config edit + npm get <key> + npm set <key> <value> [--global] + +## DESCRIPTION + +npm gets its configuration values from 6 sources, in this priority: + +### Command Line Flags + +Putting `--foo bar` on the command line sets the +`foo` configuration parameter to `"bar"`. A `--` argument tells the cli +parser to stop reading flags. A `--flag` parameter that is at the *end* of +the command will be given the value of `true`. + +### Environment Variables + +Any environment variables that start with `npm_config_` will be interpreted +as a configuration parameter. For example, putting `npm_config_foo=bar` in +your environment will set the `foo` configuration parameter to `bar`. Any +environment configurations that are not given a value will be given the value +of `true`. Config values are case-insensitive, so `NPM_CONFIG_FOO=bar` will +work the same. + +### Per-user config file + +`$HOME/.npmrc` (or the `userconfig` param, if set above) + +This file is an ini-file formatted list of `key = value` parameters. + +### Global config file + +`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): +This file is an ini-file formatted list of `key = value` parameters + +### Built-in config file + +`path/to/npm/itself/npmrc` + +This is an unchangeable "builtin" +configuration file that npm keeps consistent across updates. Set +fields in here using the `./configure` script that comes with npm. +This is primarily for distribution maintainers to override default +configs in a standard and consistent manner. + +### Default Configs + +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: + +### set + + npm config set key value + +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. + +### list + + npm config list + +Show all the config settings. + +### delete + + npm config delete key + +Deletes the key from all configuration files. + +### edit + + npm config edit + +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` +* `-m`: `--message` +* `-p`, `--porcelain`: `--parseable` +* `-reg`: `--registry` +* `-v`: `--version` +* `-f`: `--force` +* `-l`: `--long` +* `-desc`: `--description` +* `-S`: `--save` +* `-y`: `--yes` +* `-n`: `--yes false` +* `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 + +When running scripts (see `npm-scripts(1)`) +the package.json "config" keys are overwritten in the environment if +there is a config param of `<name>[@<version>]:<key>`. For example, if +the package.json has this: + + { "name" : "foo" + , "config" : { "port" : "8080" } + , "scripts" : { "start" : "node server.js" } } + +and the server.js is this: + + http.createServer(...).listen(process.env.npm_package_config_port) + +then the user could change the behavior by doing: + + npm config set foo:port 80 + +## Config Settings + +### always-auth + +* Default: false +* Type: Boolean + +Force npm to always require authentication when accessing the registry, +even for `GET` requests. + +### bin-publish + +* Default: false +* Type: Boolean + +If set to true, then binary packages will be created on publish. + +This is the way to opt into the "bindist" behavior described below. + +### bindist + +* Default: Unstable node versions, `null`, otherwise + `"<node version>-<platform>-<os release>"` +* Type: String or `null` + +Experimental: on stable versions of node, binary distributions will be +created with this tag. If a user then installs that package, and their +`bindist` tag is found in the list of binary distributions, they will +get that prebuilt version. + +Pre-build node packages have their preinstall, install, and postinstall +scripts stripped (since they are run prior to publishing), and do not +have their `build` directories automatically ignored. + +It's yet to be seen if this is a good idea. + +### browser + +* Default: OS X: `"open"`, others: `"google-chrome"` +* Type: String + +The browser that is called by the `npm docs` command to open websites. + +### ca + +* Default: The npm CA certificate +* Type: String or null + +The Certificate Authority signing certificate that is trusted for SSL +connections to the registry. + +Set to `null` to only allow "known" registrars, or to a specific CA cert +to trust only that specific signing authority. + +See also the `strict-ssl` config. + +### cache + +* Default: Windows: `~/npm-cache`, Posix: `~/.npm` +* Type: path + +The location of npm's cache directory. See `npm-cache(1)` + +### color + +* Default: true on Posix, false on Windows +* Type: Boolean or `"always"` + +If false, never shows colors. If `"always"` then always shows colors. +If true, then only prints color codes for tty file descriptors. + +### depth + +* Default: Infinity +* Type: Number + +The depth to go when recursing directories for `npm ls` and +`npm cache ls`. + +### description + +* Default: true +* Type: Boolean + +Show the description in `npm search` + +### dev + +* Default: false +* Type: Boolean + +Install `dev-dependencies` along with packages. + +Note that `dev-dependencies` are also installed if the `npat` flag is +set. + +### editor + +* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, + or `"notepad"` on Windows. +* Type: path + +The command to run for `npm edit` or `npm config edit`. + +### force + +* Default: false +* Type: Boolean + +Makes various commands more forceful. + +* 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. + +### global + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the +`prefix` folder instead of the current working directory. See +`npm-folders(1)` for more on the differences in behavior. + +* 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` + +### globalconfig + +* Default: {prefix}/etc/npmrc +* Type: path + +The config file to read for global config options. + +### globalignorefile + +* Default: {prefix}/etc/npmignore +* Type: path + +The config file to read for global ignore patterns to apply to all users +and all projects. + +If not found, but there is a "gitignore" file in the +same directory, then that will be used instead. + +### group + +* Default: GID of the current process +* Type: String or Number + +The group to use when running package scripts in global mode as the root +user. + +### https-proxy + +* Default: the `HTTPS_PROXY` or `https_proxy` or `HTTP_PROXY` or + `http_proxy` environment variables. +* Type: url + +A proxy to use for outgoing https requests. + +### ignore + +* Default: "" +* Type: string + +A white-space separated list of glob patterns of files to always exclude +from packages when building tarballs. + +### init.version + +* Default: "0.0.0" +* Type: semver + +The value `npm init` should use by default for the package version. + +### init.author.name + +* Default: "0.0.0" +* Type: String + +The value `npm init` should use by default for the package author's name. + +### init.author.email + +* Default: "" +* Type: String + +The value `npm init` should use by default for the package author's email. + +### init.author.url + +* Default: "" +* Type: String + +The value `npm init` should use by default for the package author's homepage. + +### link + +* Default: false +* Type: Boolean + +If true, then local installs will link if there is a suitable globally +installed package. + +Note that this means that local installs can cause things to be +installed into the global space at the same time. The link is only done +if one of the two conditions are met: + +* The package is not already installed globally, or +* the globally installed version is identical to the version that is + being installed locally. + +### logfd + +* Default: stderr file descriptor +* Type: Number or Stream + +The location to write log output. + +### loglevel + +* Default: "warn" +* Type: String +* Values: "silent", "win", "error", "warn", "info", "verbose", "silly" + +What level of logs to report. On failure, *all* logs are written to +`npm-debug.log` in the current working directory. + +### logprefix + +* Default: true on Posix, false on Windows +* Type: Boolean + +Whether or not to prefix log messages with "npm" and the log level. See +also "color" and "loglevel". + +### long + +* Default: false +* Type: Boolean + +Show extended information in `npm ls` + +### message + +* Default: "%s" +* Type: String + +Commit message which is used by `npm version` when creating version commit. + +Any "%s" in the message will be replaced with the version number. + +### node-version + +* Default: process.version +* Type: semver or false + +The node version to use when checking package's "engines" hash. + +### npat + +* Default: false +* Type: Boolean + +Run tests on installation and report results to the +`npaturl`. + +### npaturl + +* Default: Not yet implemented +* Type: url + +The url to report npat test results. + +### onload-script + +* Default: false +* Type: path + +A node module to `require()` when npm loads. Useful for programmatic +usage. + +### outfd + +* Default: standard output file descriptor +* Type: Number or Stream + +Where to write "normal" output. This has no effect on log output. + +### parseable + +* Default: false +* Type: Boolean + +Output parseable results from commands that write to +standard output. + +### prefix + +* Default: node's process.installPrefix +* Type: path + +The location to install global items. If set on the command line, then +it forces non-global commands to run in the specified folder. + +### production + +* Default: false +* Type: Boolean + +Set to true to run in "production" mode. + +1. devDependencies are not installed at the topmost level when running + local `npm install` without any arguments. +2. Set the NODE_ENV="production" for lifecycle scripts. + +### proxy + +* Default: `HTTP_PROXY` or `http_proxy` environment variable, or null +* Type: url + +A proxy to use for outgoing http requests. + +### rebuild-bundle + +* Default: true +* Type: Boolean + +Rebuild bundled dependencies after installation. + +### registry + +* Default: https://registry.npmjs.org/ +* Type: url + +The base URL of the npm package registry. + +### rollback + +* Default: true +* Type: Boolean + +Remove failed installs. + +### save + +* Default: false +* Type: Boolean + +Save installed packages to a package.json file as dependencies. + +Only works if there is already a package.json file present. + +### searchopts + +* Default: "" +* Type: String + +Space-separated options that are always passed to search. + +### searchexclude + +* Default: "" +* Type: String + +Space-separated options that limit the results from search. + +### shell + +* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on + Windows +* Type: path + +The shell to run for the `npm explore` command. + +### strict-ssl + +* Default: true +* Type: Boolean + +Whether or not to do SSL key validation when making requests to the +registry via https. + +See also the `ca` config. + +### tag + +* Default: latest +* Type: String + +If you ask npm to install a package and don't tell it a specific version, then +it will install the specified tag. + +Also the tag that is added to the package@version specified by the `npm +tag` command, if no explicit tag is given. + +### tmp + +* Default: TMPDIR environment variable, or "/tmp" +* Type: path + +Where to store temporary files and folders. All temp files are deleted +on success, but left behind on failure for forensic purposes. + +### unicode + +* Default: true +* Type: Boolean + +When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters to draw trees. + +### unsafe-perm + +* Default: false if running as root, true otherwise +* Type: Boolean + +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. + +### usage + +* Default: false +* Type: Boolean + +Set to show short usage output (like the -H output) +instead of complete help when doing `npm-help(1)`. + +### user + +* Default: "nobody" +* Type: String or Number + +The UID to set to when running package scripts as root. + +### username + +* Default: null +* Type: String + +The username on the npm registry. Set with `npm adduser` + +### userconfig + +* Default: ~/.npmrc +* Type: path + +The location of user-level configuration settings. + +### userignorefile + +* Default: ~/.npmignore +* Type: path + +The location of a user-level ignore file to apply to all packages. + +If not found, but there is a .gitignore file in the same directory, then +that will be used instead. + +### umask + +* Default: 022 +* Type: Octal numeric string + +The "umask" value to use when setting the file creation mode on files +and folders. + +Folders and executables are given a mode which is `0777` masked against +this value. Other files are given a mode which is `0666` masked against +this value. Thus, the defaults are `0755` and `0644` respectively. + +### version + +* Default: false +* Type: boolean + +If true, output the npm version and exit successfully. + +Only relevant when specified explicitly on the command line. + +### viewer + +* Default: "man" on Posix, "browser" on Windows +* Type: path + +The program to use to view help content. + +Set to `"browser"` to view html help content in the default web browser. + +### yes + +* Default: null +* Type: Boolean or null + +If set to `null`, then prompt the user for responses in some +circumstances. + +If set to `true`, then answer "yes" to any prompt. If set to `false` +then answer "no" to any prompt. + +## SEE ALSO + +* npm-folders(1) +* npm(1) diff --git a/deps/npm/doc/cli/deprecate.md b/deps/npm/doc/cli/deprecate.md new file mode 100644 index 0000000000..925337f21a --- /dev/null +++ b/deps/npm/doc/cli/deprecate.md @@ -0,0 +1,24 @@ +npm-deprecate(1) -- Deprecate a version of a package +==================================================== + +## SYNOPSIS + + npm deprecate <name>[@<version>] <message> + +## DESCRIPTION + +This command will update the npm registry entry for a package, providing +a deprecation warning to all who attempt to install it. + +It works on version ranges as well as specific versions, so you can do +something like this: + + npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3" + +Note that you must be the package owner to deprecate something. See the +`owner` and `adduser` help topics. + +## SEE ALSO + +* npm-publish(1) +* npm-registry(1) diff --git a/deps/npm/doc/cli/developers.md b/deps/npm/doc/cli/developers.md new file mode 100644 index 0000000000..0f0f94c588 --- /dev/null +++ b/deps/npm/doc/cli/developers.md @@ -0,0 +1,172 @@ +npm-developers(1) -- Developer Guide +==================================== + +## DESCRIPTION + +So, you've decided to use npm to develop (and maybe publish/deploy) +your project. + +Fantastic! + +There are a few things that you need to do above the simple steps +that your users will do to install your program. + +## About These Documents + +These are man pages. If you install npm, you should be able to +then do `man npm-thing` to get the documentation on a particular +topic, or `npm help thing` to see the same information. + +## What is a `package` + +A package is: + +* a) a folder containing a program described by a package.json file +* b) a gzipped tarball containing (a) +* c) a url that resolves to (b) +* d) a `<name>@<version>` that is published on the registry with (c) +* e) a `<name>@<tag>` that points to (d) +* f) a `<name>` that has a "latest" tag satisfying (e) + +Even if you never publish your package, you can still get a lot of +benefits of using npm if you just want to write a node program (a), and +perhaps if you also want to be able to easily install it elsewhere +after packing it up into a tarball (b). + +## The package.json File + +You need to have a `package.json` file in the root of your project to do +much of anything with npm. That is basically the whole interface. + +See `npm-json(1)` for details about what goes in that file. At the very +least, you need: + +* name: + This should be a string that identifies your project. Please do not + use the name to specify that it runs on node, or is in JavaScript. + You can use the "engines" field to explicitly state the versions of + node (or whatever else) that your program requires, and it's pretty + well assumed that it's javascript. + + It does not necessarily need to match your github repository name. + + So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better. + +* version: + A semver-compatible version. + +* engines: + Specify the versions of node (or whatever else) that your program + runs on. The node API changes a lot, and there may be bugs or new + functionality that you depend on. Be explicit. + +* author: + Take some credit. + +* scripts: + If you have a special compilation or installation script, then you + should put it in the `scripts` hash. You should definitely have at + least a basic smoke-test command as the "scripts.test" field. + See npm-scripts(1). + +* main: + If you have a single module that serves as the entry point to your + program (like what the "foo" package gives you at require("foo")), + then you need to specify that in the "main" field. + +* directories: + This is a hash of folders. The best ones to include are "lib" and + "doc", but if you specify a folder full of man pages in "man", then + they'll get installed just like these ones. + +You can use `npm init` in the root of your package in order to get you +started with a pretty basic package.json file. See `npm-init(1)` for +more info. + +## Keeping files *out* of your package + +Use a `.npmignore` file to keep stuff out of your package. If there's +no .npmignore file, but there *is* a .gitignore file, then npm will +ignore the stuff matched by the .gitignore file. If you *want* to +include something that is excluded by your .gitignore file, you can +create an empty .npmignore file to override it. + +## Link Packages + +`npm link` is designed to install a development package and see the +changes in real time without having to keep re-installing it. (You do +need to either re-link or `npm rebuild -g` to update compiled packages, +of course.) + +More info at `npm-link(1)`. + +## Before Publishing: Make Sure Your Package Installs and Works + +**This is important.** + +If you can not install it locally, you'll have +problems trying to publish it. Or, worse yet, you'll be able to +publish it, but you'll be publishing a broken or pointless package. +So don't do that. + +In the root of your package, do this: + + npm install . -g + +That'll show you that it's working. If you'd rather just create a symlink +package that points to your working directory, then do this: + + npm link + +Use `npm ls -g` to see if it's there. + +To test a local install, go into some other folder, and then do: + + cd ../some-other-folder + npm install ../my-package + +to install it locally into the node_modules folder in that other place. + +Then go into the node-repl, and try using require("my-thing") to +bring in your module's main module. + +## Create a User Account + +Create a user with the adduser command. It works like this: + + npm adduser + +and then follow the prompts. + +This is documented better in npm-adduser(1). + +## Publish your package + +This part's easy. IN the root of your folder, do this: + + npm publish + +You can give publish a url to a tarball, or a filename of a tarball, +or a path to a folder. + +Note that pretty much **everything in that folder will be exposed** +by default. So, if you have secret stuff in there, use a `.npminclude` +or `.npmignore` file to list out the globs to include/ignore, or publish +from a fresh checkout. + +## Brag about it + +Send emails, write blogs, blab in IRC. + +Tell the world how easy it is to install your program! + +## SEE ALSO + +* npm-faq(1) +* npm(1) +* npm-init(1) +* npm-json(1) +* npm-scripts(1) +* npm-publish(1) +* npm-adduser(1) +* npm-registry(1) diff --git a/deps/npm/doc/cli/docs.md b/deps/npm/doc/cli/docs.md new file mode 100644 index 0000000000..26b2455dd8 --- /dev/null +++ b/deps/npm/doc/cli/docs.md @@ -0,0 +1,38 @@ +npm-docs(1) -- Docs for a package in a web browser maybe +======================================================== + +## SYNOPSIS + + npm docs <pkgname> + npm home <pkgname> + +## DESCRIPTION + +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. + +## CONFIGURATION + +### browser + +* Default: OS X: `"open"`, others: `"google-chrome"` +* Type: String + +The browser that is called by the `npm docs` command to open websites. + +### registry + +* Default: https://registry.npmjs.org/ +* Type: url + +The base URL of the npm package registry. + + +## SEE ALSO + +* npm-view(1) +* npm-publish(1) +* npm-registry(1) +* npm-config(1) +* npm-json(1) diff --git a/deps/npm/doc/cli/edit.md b/deps/npm/doc/cli/edit.md new file mode 100644 index 0000000000..9eaccfc540 --- /dev/null +++ b/deps/npm/doc/cli/edit.md @@ -0,0 +1,35 @@ +npm-edit(1) -- Edit an installed package +======================================== + +## SYNOPSIS + + npm edit <name>[@<version>] + +## DESCRIPTION + +Opens the package folder in the default editor (or whatever you've +configured as the npm `editor` config -- see `npm-config(1)`.) + +After it has been edited, the package is rebuilt so as to pick up any +changes in compiled packages. + +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. + +## CONFIGURATION + +### editor + +* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, + or `"notepad"` on Windows. +* Type: path + +The command to run for `npm edit` or `npm config edit`. + +## SEE ALSO + +* npm-folders(1) +* npm-explore(1) +* npm-install(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/explore.md b/deps/npm/doc/cli/explore.md new file mode 100644 index 0000000000..00701b392a --- /dev/null +++ b/deps/npm/doc/cli/explore.md @@ -0,0 +1,40 @@ +npm-explore(1) -- Browse an installed package +============================================= + +## SYNOPSIS + + npm explore <name>[@<version>] [ -- <cmd>] + +## DESCRIPTION + +Spawn a subshell in the directory of the installed package specified. + +If a command is specified, then it is run in the subshell, which then +immediately terminates. + +This is particularly handy in the case of git submodules in the +`node_modules` folder: + + npm explore some-dependency -- git pull origin master + +Note that the package is *not* automatically rebuilt afterwards, so be +sure to use `npm rebuild <pkg>` if you make any changes. + +## CONFIGURATION + +### shell + +* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on + Windows +* Type: path + +The shell to run for the `npm explore` command. + +## SEE ALSO + +* npm-submodule(1) +* npm-folders(1) +* npm-edit(1) +* npm-rebuild(1) +* npm-build(1) +* npm-install(1) diff --git a/deps/npm/doc/cli/faq.md b/deps/npm/doc/cli/faq.md new file mode 100644 index 0000000000..15bb0c637d --- /dev/null +++ b/deps/npm/doc/cli/faq.md @@ -0,0 +1,223 @@ +npm-faq(1) -- Frequently Asked Questions +======================================== + +## Where can I find these docs in HTML? + +<http://npmjs.org/doc/>, or run: + + npm config set viewer browser + +to open these documents in your default web browser rather than `man`. + +## It didn't work. + +That's not really a question. + +## Why didn't it work? + +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. + +## Where does npm put stuff? + +See `npm-folders(1)` + +tl;dr: + +* Use the `npm root` command to see where modules go, and the `npm bin` + command to see where executables go +* Global installs are different from local installs. If you install + something with the `-g` flag, then its executables go in `npm bin -g` + and its modules go in `npm root -g`. + +## How do I install something everywhere? + +Install it globally by tacking `-g` or `--global` to the command. + +## I installed something globally, but I can't `require()` it + +Install it locally. + +## I don't wanna. + +Check out `npm link`. You might like it. + +## No, I really want 0.x style 'everything global' style. + +Ok, fine. Do this: + + echo 'export NODE_PATH="'$(npm root -g)'"' >> ~/.bashrc + . ~/.bashrc + npm config set global true + +This is not recommended. + +Many things **will not work** if you do this. Make sure you read and +understand `npm-config(1)` and `npm-global(1)` before you complain +about things being broken. + +When you realize what a mistake it was, do this to switch back: + + npm config delete global --local + +## If 'npm' is an acronym, why is it never capitalized? + +Contrary to the belief of many, "npm" is not in fact an abbreviation for +"Node Package Manager". It is a recursive bacronymic abbreviation for +"npm is not an acronym". (If it was "ninaa", then it would be an +acronym, and thus incorrectly named.) + +"NPM", however, *is* an acronym (more precisely, a capitonym) for the +National Association of Pastoral Musicians. You can learn more +about them at <http://npm.org/>. + +In software, "NPM" is a non-parametric mapping utility written by +Chris Rorden. You can analyze pictures of brains with it. Learn more +about the (capitalized) NPM program at <http://www.cabiatl.com/mricro/npm/>. + +The first seed that eventually grew into this flower was a bash utility +named "pm", which was a shortened descendent of "pkgmakeinst", a +bash function that was used to install various different things on different +platforms, most often using Yahoo's `yinst`. If `npm` was ever an +acronym for anything, it was `node pm` or maybe `new pm`. + +So, in all seriousness, the "npm" project is named after its command-line +utility, which was organically selected to be easily typed by a right-handed +programmer using a US QWERTY keyboard layout, ending with the +right-ring-finger in a postition to type the `-` key for flags and +other command-line arguments. That command-line utility is always +lower-case, though it starts most sentences it is a part of. + +## How do I list installed packages? + +`npm ls` + +## How do I search for packages? + +`npm search` + +Arguments are greps. `npm search jsdom` shows jsdom packages. + +## How do I update npm? + + npm update npm -g + +You can also update all outdated local packages by doing `npm update` without +any arguments, or global packages by doing `npm update -g`. + +Occasionally, the version of npm will progress such that the current +version cannot be properly installed with the version that you have +installed already. (Consider, if there is ever a bug in the `update` +command.) + +In those cases, you can do this: + + curl http://npmjs.org/install.sh | sh + +## What is a `package`? + +A package is: + +* a) a folder containing a program described by a package.json file +* b) a gzipped tarball containing (a) +* c) a url that resolves to (b) +* d) a `<name>@<version>` that is published on the registry with (c) +* e) a `<name>@<tag>` that points to (d) +* f) a `<name>` that has a "latest" tag satisfying (e) +* g) a `git` url that, when cloned, results in (a). + +Even if you never publish your package, you can still get a lot of +benefits of using npm if you just want to write a node program (a), and +perhaps if you also want to be able to easily install it elsewhere +after packing it up into a tarball (b). + +Git urls can be of the form: + + git://github.com/user/project.git#commit-ish + git+ssh://user@hostname:project.git#commit-ish + git+http://user@hostname/project/blah.git#commit-ish + git+https://user@hostname/project/blah.git#commit-ish + +The `commit-ish` can be any tag, sha, or branch which can be supplied as +an argument to `git checkout`. The default is `master`. + +## How do I install node with npm? + +You don't. Try one of these: + +* <http://github.com/isaacs/nave> +* <http://github.com/visionmedia/n> +* <http://github.com/creationix/nvm> + +## How can I use npm for development? + +See `npm-developers(1)` and `npm-json(1)`. + +You'll most likely want to `npm link` your development folder. That's +awesomely handy. + +To set up your own private registry, check out `npm-registry(1)`. + +## Can I list a url as a dependency? + +Yes. It should be a url to a gzipped tarball containing a single folder +that has a package.json in its root, or a git url. +(See "what is a package?" above.) + +## How do I symlink to a dev folder so I don't have to keep re-installing? + +See `npm-link(1)` + +## The package registry website. What is that exactly? + +See `npm-registry(1)`. + +## What's up with the insecure channel warnings? + +Until node 0.4.10, there were problems sending big files over HTTPS. That +means that publishes go over HTTP by default in those versions of node. + +## I forgot my password, and can't publish. How do I reset it? + +Go to <http://admin.npmjs.org/reset>. + +## I get ECONNREFUSED a lot. What's up? + +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/-/short> +in a web browser. This will also tell you if you are just unable to +access the internet for some reason. + +If the registry IS down, let me know by emailing or posting an issue. +We'll have someone kick it or something. + +## Who does npm? + +`npm view npm author` + +`npm view npm contributors` + +## I have a question or request not addressed here. Where should I put it? + +Discuss it on the mailing list, or post an issue. + +* <npm-@googlegroups.com> +* <http://github.com/isaacs/npm/issues> + +## Why does npm hate me? + +npm is not capable of hatred. It loves everyone, especially you. + +## SEE ALSO + +* npm(1) +* npm-developers(1) +* npm-json(1) +* npm-config(1) +* npm-folders(1) diff --git a/deps/npm/doc/cli/find.md b/deps/npm/doc/cli/find.md new file mode 120000 index 0000000000..9b687d1c19 --- /dev/null +++ b/deps/npm/doc/cli/find.md @@ -0,0 +1 @@ +search.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/folders.md b/deps/npm/doc/cli/folders.md new file mode 100644 index 0000000000..20358612ad --- /dev/null +++ b/deps/npm/doc/cli/folders.md @@ -0,0 +1,209 @@ +npm-folders(1) -- Folder Structures Used by npm +=============================================== + +## DESCRIPTION + +npm puts various things on your computer. That's its job. + +This document will tell you what it puts where. + +### tl;dr + +* Local install (default): puts stuff in `./node_modules` of the current + package root. +* Global install (with `-g`): puts stuff in /usr/local or wherever node + is installed. +* Install it **locally** if you're going to `require()` it. +* Install it **globally** if you're going to run it on the command line. +* If you need both, then install it in both places, or use `npm link`. + +### prefix Configuration + +The `prefix` config defaults to the location where node is installed. +On most systems, this is `/usr/local`, and most of the time is the same +as node's `process.installPrefix`. + +On windows, this is the exact location of the node.exe binary. On Unix +systems, it's one level up, since node is typically installed at +`{prefix}/bin/node` rather than `{prefix}/node.exe`. + +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. + +### Node Modules + +Packages are dropped 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/lib/path/to/sub/module")` to load other modules. + +Global installs on Unix systems go to `{prefix}/lib/node_modules`. +Global installs on Windows go to `{prefix}/node_modules` (that is, no +`lib` folder.) + +If you wish to `require()` a package, then install it locally. + +### Executables + +When in global mode, executables are linked into `{prefix}/bin` on Unix, +or directly into `{prefix}` on Windows. + +When in local mode, executables are linked into +`./node_modules/.bin` so that they can be made available to scripts run +through npm. (For example, so that a test runner will be in the path +when you run `npm test`.) + +### Man Pages + +When in global mode, man pages are linked into `{prefix}/share/man`. + +When in local mode, man pages are not installed. + +Man pages are not installed on Windows systems. + +### Cache + +See `npm-cache(1)`. Cache files are stored in `~/.npm` on Posix, or +`~/npm-cache` on Windows. + +This is controlled by the `cache` configuration param. + +### Temp Files + +Temporary files are stored by default in the folder specified by the +`tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment +variables, or `/tmp` on Unix and `c:\windows\temp` on Windows. + +Temp files are given a unique folder under this root for each run of the +program, and are deleted upon successful exit. + +## More Information + +When installing locally, npm first tries to find an appropriate +`prefix` folder. This is so that `npm install foo@1.2.3` will install +to the sensible root of your package, even if you happen to have `cd`ed +into some other folder. + +Starting at the $PWD, npm will walk up the folder tree checking for a +folder that contains either a `package.json` file, or a `node_modules` +folder. If such a thing is found, then that is treated as the effective +"current directory" for the purpose of running npm commands. (This +behavior is inspired by and similar to git's .git-folder seeking +logic when running git commands in a working dir.) + +If no package root is found, then the current folder is used. + +When you run `npm install foo@1.2.3`, then the package is loaded into +the cache, and then unpacked into `./node_modules/foo`. Then, any of +foo's dependencies are similarly unpacked into +`./node_modules/foo/node_modules/...`. + +Any bin files are symlinked to `./node_modules/.bin/`, so that they may +be found by npm scripts when necessary. + +### Global Installation + +If the `global` configuration is set to true, then npm will +install packages "globally". + +For global installation, packages are installed roughly the same way, +but using the folders described above. + +### 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. + +#### Example + +Consider this dependency graph: + + foo + +-- blerg@1.2.5 + +-- bar@1.2.3 + | +-- blerg@1.x (latest=1.3.7) + | +-- baz@2.x + | | `-- quux@3.x + | | `-- bar@1.2.3 (cycle) + | `-- asdf@* + `-- baz@1.2.3 + `-- quux@3.x + `-- bar + +In this case, we might expect a folder structure like this: + + foo + +-- node_modules + +-- blerg (1.2.5) <---[A] + +-- bar (1.2.3) <---[B] + | +-- node_modules + | | `-- baz (2.0.2) <---[C] + | | `-- node_modules + | | `-- quux (3.2.0) + | `-- asdf (2.3.4) + `-- baz (1.2.3) <---[D] + `-- node_modules + `-- quux (3.2.0) <---[E] + +Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are +installed in foo's `node_modules` folder. + +Even though the latest copy of blerg is 1.3.7, foo has a specific +dependency on version 1.2.5. So, that gets installed at [A]. Since the +parent installation of blerg satisfie's bar's dependency on blerg@1.x, +it does not install another copy under [B]. + +Bar [B] also has dependencies on baz and asdf, so those are installed in +bar's `node_modules` folder. Because it depends on `baz@2.x`, it cannot +re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D], +and must install its own copy [C]. + +Underneath bar, the `baz->quux->bar` dependency creates a cycle. +However, because `bar` is already in `quux`'s ancestry [B], it does not +unpack another copy of bar into that folder. + +Underneath `foo->baz` [D], quux's [E] folder tree is empty, because its +dependency on bar is satisfied by the parent folder copy installed at [B]. + +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 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. See `npm-json(1)` for more information. + +## SEE ALSO + +* npm-faq(1) +* npm-json(1) +* npm-install(1) +* npm-pack(1) +* npm-cache(1) +* npm-config(1) +* npm-publish(1) diff --git a/deps/npm/doc/cli/get.md b/deps/npm/doc/cli/get.md new file mode 120000 index 0000000000..3dc8737366 --- /dev/null +++ b/deps/npm/doc/cli/get.md @@ -0,0 +1 @@ +config.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/global.md b/deps/npm/doc/cli/global.md new file mode 120000 index 0000000000..c3598dd7df --- /dev/null +++ b/deps/npm/doc/cli/global.md @@ -0,0 +1 @@ +folders.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/help-search.md b/deps/npm/doc/cli/help-search.md new file mode 100644 index 0000000000..9c16901ebb --- /dev/null +++ b/deps/npm/doc/cli/help-search.md @@ -0,0 +1,35 @@ +npm-help-search(1) -- Search npm help documentation +=================================================== + +## SYNOPSIS + + npm help-search some search terms + +## DESCRIPTION + +This command will search the npm markdown documentation files for the +terms provided, and then list the results, sorted by relevance. + +If only one result is found, then it will show that help topic. + +If the argument to `npm help` is not a known help topic, then it will +call `help-search`. It is rarely if ever necessary to call this +command directly. + +## CONFIGURATION + +### long + +* Type: Boolean +* Default false + +If true, the "long" flag will cause help-search to output context around +where the terms were found in the documentation. + +If false, then help-search will just list out the help topics found. + +## SEE ALSO + +* npm(1) +* npm-faq(1) +* npm-help(1) diff --git a/deps/npm/doc/cli/help.md b/deps/npm/doc/cli/help.md new file mode 100644 index 0000000000..b51b0f1649 --- /dev/null +++ b/deps/npm/doc/cli/help.md @@ -0,0 +1,38 @@ +npm-help(1) -- Get help on npm +============================== + +## SYNOPSIS + + npm help <topic> + npm help some search terms + +## DESCRIPTION + +If supplied a topic, then show the appropriate documentation page. + +If the topic does not exist, or if multiple terms are provided, then run +the `help-search` command to find a match. Note that, if `help-search` +finds a single subject, then it will run `help` on that topic, so unique +matches are equivalent to specifying a topic name. + +## CONFIGURATION + +### viewer + +* Default: "man" on Posix, "browser" on Windows +* Type: path + +The program to use to view help content. + +Set to `"browser"` to view html help content in the default web browser. + +## SEE ALSO + +* npm(1) +* README +* npm-faq(1) +* npm-folders(1) +* npm-config(1) +* npm-json(1) +* npm-help-search(1) +* npm-index(1) diff --git a/deps/npm/doc/cli/home.md b/deps/npm/doc/cli/home.md new file mode 120000 index 0000000000..8828313f5b --- /dev/null +++ b/deps/npm/doc/cli/home.md @@ -0,0 +1 @@ +docs.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/init.md b/deps/npm/doc/cli/init.md new file mode 100644 index 0000000000..39297b4c4d --- /dev/null +++ b/deps/npm/doc/cli/init.md @@ -0,0 +1,24 @@ +npm-init(1) -- Interactively create a package.json file +======================================================= + +## SYNOPSIS + + npm init + +## DESCRIPTION + +This will ask you a bunch of questions, and then write a package.json for you. + +It attempts to make reasonable guesses about what you want things to be set to, +and then writes a package.json file with the options you've selected. + +If you already have a package.json file, it'll read that first, and default to +the options in there. + +It is strictly additive, so it does not delete options from your package.json +without a really good reason to do so. + +## SEE ALSO + +* npm-json(1) +* npm-version(1) diff --git a/deps/npm/doc/cli/install.md b/deps/npm/doc/cli/install.md new file mode 100644 index 0000000000..22eb8234e7 --- /dev/null +++ b/deps/npm/doc/cli/install.md @@ -0,0 +1,201 @@ +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> + npm install <name> + npm install <name>@<tag> + npm install <name>@<version> + npm install <name>@<version range> + +## DESCRIPTION + +This command installs a package, and any packages that it depends on. + +A `package` is: + +* a) a folder containing a program described by a package.json file +* b) a gzipped tarball containing (a) +* c) a url that resolves to (b) +* d) a `<name>@<version>` that is published on the registry with (c) +* e) a `<name>@<tag>` that points to (d) +* f) a `<name>` that has a "latest" tag satisfying (e) +* g) a `<git remote url>` that resolves to (b) + +Even if you never publish your package, you can still get a lot of +benefits of using npm if you just want to write a node program (a), and +perhaps if you also want to be able to easily install it elsewhere +after packing it up into a tarball (b). + + +* `npm install` (in package directory, no arguments): + Install the dependencies in the local node_modules folder. + + In global mode (ie, with `-g` or `--global` appended to the command), + it installs the current package context (ie, the current working + directory) as a global package. + +* `npm install <folder>`: + Install a package that is sitting in a folder on the filesystem. + +* `npm install <tarball file>`: + Install a package that is sitting on the filesystem. Note: if you just want + to link a dev directory into your npm root, you can do this more easily by + using `npm link`. + + Example: + + npm install ./package.tgz + +* `npm install <tarball url>`: + Fetch the tarball url, and then install it. In order to distinguish between + this and other options, the argument must start with "http://" or "https://" + + Example: + + npm install https://github.com/indexzero/forever/tarball/v0.5.6 + +* `npm install <name>`: + Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See + `npm-config(1)`) + + Example: + + npm install sax + + **Note**: If there is a file or folder named `<name>` in the current + working directory, then it will try to install that, and only try to + fetch the package by name if it is not valid. + +* `npm install <name>@<tag>`: + Install the version of the package that is referenced by the specified tag. + If the tag does not exist in the registry data for that package, then this + will fail. + + Example: + + npm install sax@latest + +* `npm install <name>@<version>`: + Install the specified version of the package. This will fail if the version + has not been published to the registry. + + Example: + + npm install sax@0.1.1 + +* `npm install <name>@<version range>`: + Install a version of the package matching the specified version range. This + will follow the same rules for resolving dependencies described in `npm-json(1)`. + + Note that most version ranges must be put in quotes so that your shell will + treat it as a single argument. + + Example: + + npm install sax@">=0.1.0 <0.2.0" + +* `npm install <git remote url>`: + + Install a package by cloning a git remote url. The format of the git + url is: + + <protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>] + + `<protocol>` is one of `git`, `git+ssh`, `git+http`, or + `git+https`. If no `<commit-ish>` is specified, then `master` is + used. + + Examples: + + git+ssh://git@github.com:isaacs/npm.git#v1.0.27 + git+https://isaacs@github.com/isaacs/npm.git + git://github.com/isaacs/npm.git#v1.0.27 + +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. + + npm install sax --force + +The `--global` argument will cause npm to install the package globally +rather than locally. See `npm-global(1)`. + +The `--link` argument will cause npm to link global installs into the +local space in some cases. + +See `npm-config(1)`. Many of the configuration params have some +effect on installation, since that's most of what npm does. + +## ALGORITHM + +To install a package, npm uses the following algorithm: + + install(where, what, family, ancestors) + fetch what, unpack to <where>/node_modules/<what> + for each dep in what.dependencies + resolve dep to precise version + for each dep@version in what.dependencies + not in <where>/node_modules/<what>/node_modules/* + and not in <family> + add precise version deps to <family> + install(<where>/node_modules/<what>, dep, family) + +For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`, +this algorithm produces: + + A + +-- B + `-- C + `-- D + +That is, the dependency from B to C is satisfied by the fact that A +already caused C to be installed at a higher level. + +See npm-folders(1) for a more detailed description of the specific +folder structures that npm creates. + +### Limitations of npm's Install Algorithm + +There are some very rare and pathological edge-cases where a cycle can +cause npm to try to install a never-ending tree of packages. Here is +the simplest case: + + A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ... + +where `A` is some version of a package, and `A'` is a different version +of the same package. Because `B` depends on a different version of `A` +than the one that is already in the tree, it must install a separate +copy. The same is true of `A'`, which must install `B'`. Because `B'` +depends on the original version of `A`, which has been overridden, the +cycle falls into infinite regress. + +To avoid this situation, npm flat-out refuses to install any +`name@version` that is already present anywhere in the tree of package +folder ancestors. A more correct, but more complex, solution would be +to symlink the existing version into the new location. If this ever +affects a real use-case, it will be investigated. + +## SEE ALSO + +* npm-folders(1) +* npm-update(1) +* npm-link(1) +* npm-rebuild(1) +* npm-scripts(1) +* npm-build(1) +* npm-config(1) +* npm-registry(1) +* npm-folders(1) +* npm-tag(1) +* npm-rm(1) diff --git a/deps/npm/doc/cli/json.md b/deps/npm/doc/cli/json.md new file mode 100644 index 0000000000..5f6e7ef621 --- /dev/null +++ b/deps/npm/doc/cli/json.md @@ -0,0 +1,472 @@ +npm-json(1) -- Specifics of npm's package.json handling +======================================================= + +## DESCRIPTION + +This document is all you need to know about what's required in your package.json +file. It must be actual JSON, not just a JavaScript object literal. + +A lot of the behavior described in this document is affected by the config +settings described in `npm-config(1)`. + +## DEFAULT VALUES + +npm will default some values based on package contents. + +* `"scripts": {"start": "node server.js"}` + + If there is a `server.js` file in the root of your package, then npm + will default the `start` command to `node server.js`. + +* `"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}` + + If there is a `wscript` file in the root of your package, npm will + default the `preinstall` command to compile using node-waf. + +* `"contributors": [...]` + + If there is an `AUTHORS` file in the root of your package, npm will + treat each line as a `Name <email> (url)` format, where email and url + are optional. Lines which start with a `#` or are blank, will be + ignored. + +## name + +The *most* important things in your package.json are the name and version fields. +Those are actually required, and your package won't install without +them. The name and version together form an identifier that is assumed +to be completely unique. Changes to the package should come along with +changes to the version. + +The name is what your thing is called. Some tips: + +* Don't put "js" or "node" in the name. It's assumed that it's js, since you're + writing a package.json file, and you can specify the engine using the "engines" + field. (See below.) +* The name ends up being part of a URL, an argument on the command line, and a + folder name. Any name with non-url-safe characters will be rejected. + Also, it can't start with a dot or an underscore. +* The name will probably be passed as an argument to require(), so it should + be something short, but also reasonably descriptive. +* You may want to check the npm registry to see if there's something by that name + already, before you get too attached to it. http://registry.npmjs.org/ + +## version + +The *most* important things in your package.json are the name and version fields. +Those are actually required, and your package won't install without +them. The name and version together form an identifier that is assumed +to be completely unique. Changes to the package should come along with +changes to the version. + +Version must be parseable by +[node-semver](https://github.com/isaacs/node-semver), which is bundled +with npm as a dependency. (`npm install semver` to use it yourself.) + +Here's how npm's semver implementation deviates from what's on semver.org: + +* Versions can start with "v" +* A numeric item separated from the main three-number version by a hyphen + will be interpreted as a "build" number, and will *increase* the version. + But, if the tag is not a number separated by a hyphen, then it's treated + as a pre-release tag, and is *less than* the version without a tag. + So, `0.1.2-7 > 0.1.2-7-beta > 0.1.2-6 > 0.1.2 > 0.1.2beta` + +This is a little bit confusing to explain, but matches what you see in practice +when people create tags in git like "v1.2.3" and then do "git describe" to generate +a patch version. + +## description + +Put a description in it. It's a string. This helps people discover your +package, as it's listed in `npm search`. + +## keywords + +Put keywords in it. It's an array of strings. This helps people +discover your package as it's listed in `npm search`. + +## homepage + +The url to the project homepage. + +**NOTE**: This is *not* the same as "url". If you put a "url" field, +then the registry will think it's a redirection to your package that has +been published somewhere else, and spit at you. + +Literally. Spit. I'm so not kidding. + +## bugs + +The url to your project's issue tracker and / or the email address to which +issues should be reported. These are helpful for people who encounter issues +with your package. + +It should look like this: + + { "url" : "http://github.com/owner/project/issues" + , "email" : "project@hostname.com" + } + +You can specify either one or both values. If you want to provide only a url, +you can specify the value for "bugs" as a simple string instead of an object. + +If a url is provided, it will be used by the `npm bugs` command. + +## people fields: author, contributors + +The "author" is one person. "contributors" is an array of people. A "person" +is an object with a "name" field and optionally "url" and "email", like this: + + { "name" : "Barney Rubble" + , "email" : "b@rubble.com" + , "url" : "http://barnyrubble.tumblr.com/" + } + +Or you can shorten that all into a single string, and npm will parse it for you: + + "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/) + +Both email and url are optional either way. + +npm also sets a top-level "maintainers" field with your npm user info. + +## files + +The "files" field is an array of files to include in your project. If +you name a folder in the array, then it will also include the files +inside that folder. (Unless they would be ignored by another rule.) + +You can also provide a ".npmignore" file in the root of your package, +which will keep files from being included, even if they would be picked +up by the files array. The ".npmignore" file works just like a +".gitignore". + +## main + +The main field is a module ID that is the primary entry point to your program. +That is, if your package is named `foo`, and a user installs it, and then does +`require("foo")`, then your main module's exports object will be returned. + +This should be a module ID relative to the root of your package folder. + +For most modules, it makes the most sense to have a main script and often not +much else. + +## bin + +A lot of packages have one or more executable files that they'd like to +install into the PATH. npm makes this pretty easy (in fact, it uses this +feature to install the "npm" executable.) + +To use this, supply a `bin` field in your package.json which is a map of +command name to local file name. On install, npm will symlink that file into +`prefix/bin` for global installs, or `./node_modules/.bin/` for local +installs. + + +For example, npm has this: + + { "bin" : { "npm" : "./cli.js" } } + +So, when you install npm, it'll create a symlink from the `cli.js` script to +`/usr/local/bin/npm`. + +If you have a single executable, and its name should be the name +of the package, then you can just supply it as a string. For example: + + { "name": "my-program" + , "version": "1.2.5" + , "bin": "./path/to/program" } + +would be the same as this: + + { "name": "my-program" + , "version": "1.2.5" + , "bin" : { "my-program" : "./path/to/program" } } + +## man + +Specify either a single file or an array of filenames to put in place for the +`man` program to find. + +If only a single file is provided, then it's installed such that it is the +result from `man <pkgname>`, regardless of its actual filename. For example: + + { "name" : "foo" + , "version" : "1.2.3" + , "description" : "A packaged foo fooer for fooing foos" + , "main" : "foo.js" + , "man" : "./man/doc.1" + } + +would link the `./man/doc.1` file in such that it is the target for `man foo` + +If the filename doesn't start with the package name, then it's prefixed. +So, this: + + { "name" : "foo" + , "version" : "1.2.3" + , "description" : "A packaged foo fooer for fooing foos" + , "main" : "foo.js" + , "man" : [ "./man/foo.1", "./man/bar.1" ] + } + +will create files to do `man foo` and `man foo-bar`. + +Man files must end with a number, and optionally a `.gz` suffix if they are +compressed. The number dictates which man section the file is installed into. + + { "name" : "foo" + , "version" : "1.2.3" + , "description" : "A packaged foo fooer for fooing foos" + , "main" : "foo.js" + , "man" : [ "./man/foo.1", "./man/foo.2" ] + } + +will create entries for `man foo` and `man 2 foo` + +## directories + +The CommonJS [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec details a +few ways that you can indicate the structure of your package using a `directories` +hash. If you look at [npm's package.json](http://registry.npmjs.org/npm/latest), +you'll see that it has directories for doc, lib, and man. + +In the future, this information may be used in other creative ways. + +### directories.lib + +Tell people where the bulk of your library is. Nothing special is done +with the lib folder in any way, but it's useful meta info. + +### directories.bin + +If you specify a "bin" directory, then all the files in that folder will +be used as the "bin" hash. + +If you have a "bin" hash already, then this has no effect. + +### directories.man + +A folder that is full of man pages. Sugar to generate a "man" array by +walking the folder. + +### directories.doc + +Put markdown files in here. Eventually, these will be displayed nicely, +maybe, someday. + +### directories.example + +Put example scripts in here. Someday, it might be exposed in some clever way. + +## repository + +Specify the place where your code lives. This is helpful for people who +want to contribute. If the git repo is on github, then the `npm docs` +command will be able to find you. + +Do it like this: + + "repository" : + { "type" : "git" + , "url" : "http://github.com/isaacs/npm.git" + } + + "repository" : + { "type" : "svn" + , "url" : "http://v8.googlecode.com/svn/trunk/" + } + +The URL should be a publicly available (perhaps read-only) url that can be handed +directly to a VCS program without any modification. It should not be a url to an +html project page that you put in your browser. It's for computers. + +## scripts + +The "scripts" member is an object hash of script commands that are run +at various times in the lifecycle of your package. The key is the lifecycle +event, and the value is the command to run at that point. + +See `npm-scripts(1)` to find out more about writing package scripts. + +## config + +A "config" hash can be used to set configuration +parameters used in package scripts that persist across upgrades. For +instance, if a package had the following: + + { "name" : "foo" + , "config" : { "port" : "8080" } } + +and then had a "start" command that then referenced the +`npm_package_config_port` environment variable, then the user could +override that by doing `npm config set foo:port 8001`. + +See `npm-config(1)` and `npm-scripts(1)` for more on package +configs. + +## dependencies + +Dependencies are specified with a simple hash of package name to version +range. The version range is EITHER a string which has one or more +space-separated descriptors, OR a range like "fromVersion - toVersion" + +**Please do not put test harnesses in your `dependencies` hash.** See +`devDependencies`, below. + +Version range descriptors may be any of the following styles, where "version" +is a semver compatible version identifier. + +* `version` Must match `version` exactly +* `=version` Same as just `version` +* `>version` Must be greater than `version` +* `>=version` etc +* `<version` +* `<=version` +* `~version` See 'Tilde Version Ranges' below +* `1.2.x` See 'X Version Ranges' below +* `http://...` See 'URLs as Dependencies' below +* `*` Matches any version +* `""` (just an empty string) Same as `*` +* `version1 - version2` Same as `>=version1 <=version2`. +* `range1 || range2` Passes if either range1 or range2 are satisfied. + +For example, these are all valid: + + { "dependencies" : + { "foo" : "1.0.0 - 2.9999.9999" + , "bar" : ">=1.0.2 <2.1.2" + , "baz" : ">1.0.2 <=2.3.4" + , "boo" : "2.0.1" + , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0" + , "asd" : "http://asdf.com/asdf.tar.gz" + , "til" : "~1.2" + , "elf" : "~1.2.3" + , "two" : "2.x" + , "thr" : "3.3.x" + } + } + +### Tilde Version Ranges + +A range specifier starting with a tilde `~` character is matched against +a version in the following fashion. + +* The version must be at least as high as the range. +* The version must be less than the next major revision above the range. + +For example, the following are equivalent: + +* `"~1.2.3" = ">=1.2.3 <1.3.0"` +* `"~1.2" = ">=1.2.0 <2.0.0"` +* `"~1" = ">=1.0.0 <2.0.0"` + +### X Version Ranges + +An "x" in a version range specifies that the version number must start +with the supplied digits, but any digit may be used in place of the x. + +The following are equivalent: + +* `"1.2.x" = ">=1.2.0 <1.3.0"` +* `"1.x.x" = ">=1.0.0 <2.0.0"` +* `"1.2" = "1.2.x"` +* `"1.x" = "1.x.x"` +* `"1" = "1.x.x"` + +You may not supply a comparator with a version containing an x. Any +digits after the first "x" are ignored. + +### URLs as Dependencies + +Starting with npm version 0.2.14, you may specify a tarball URL in place +of a version range. + +This tarball will be downloaded and installed locally to your package at +install time. + +## devDependencies + +If someone is planning on downloading and using your module in their +program, then they probably don't want or need to download and build +the external test or documentation framework that you use. + +In this case, it's best to list these additional items in a +`devDependencies` hash. + +These things will be installed whenever the `--dev` configuration flag +is set. This flag is set automatically when doing `npm link`, and can +be managed like any other npm configuration param. See `npm-config(1)` +for more on the topic. + +## bundledDependencies + +Array of package names that will be bundled when publishing the package. + +If this is spelled `"bundleDependencies"`, then that is also honorable. + +## engines + +You can specify the version of +node that your stuff works on: + + { "engines" : { "node" : ">=0.1.27 <0.1.30" } } + +And, like with dependencies, if you don't specify the version (or if you +specify "*" as the version), then any version of node will do. + +If you specify an "engines" field, then npm will require that "node" be +somewhere on that list. If "engines" is omitted, then npm will just assume +that it works on node. + +You can also use the "engines" field to specify which versions of npm +are capable of properly installing your program. For example: + + { "engines" : { "npm" : "~1.0.20" } } + +## preferGlobal + +If your package is primarily a command-line application that should be +installed globally, then set this value to `true` to provide a warning +if it is installed locally. + +It doesn't actually prevent users from installing it locally, but it +does help prevent some confusion if it doesn't work as expected. + +## private + +If you set `"private": true` in your package.json, then npm will refuse +to publish it. + +This is a way to prevent accidental publication of private repositories. +If you would like to ensure that a given package is only ever published +to a speciic registry (for example, an internal registry), +then use the `publishConfig` hash described below +to override the `registry` config param at publish-time. + +## publishConfig + +This is a set of config values that will be used at publish-time. It's +especially handy if you want to set the tag or registry, so that you can +ensure that a given package is not tagged with "latest" or published to +the global public registry by default. + +Any config values can be overridden, but of course only "tag" and +"registry" probably matter for the purposes of publishing. + +See `npm-config(1)` to see the list of config options that can be +overridden. + +## SEE ALSO + +* npm-semver(1) +* npm-init(1) +* npm-version(1) +* npm-config(1) +* npm-help(1) +* npm-faq(1) +* npm-install(1) +* npm-publish(1) +* npm-rm(1) diff --git a/deps/npm/doc/cli/link.md b/deps/npm/doc/cli/link.md new file mode 100644 index 0000000000..dd54792e29 --- /dev/null +++ b/deps/npm/doc/cli/link.md @@ -0,0 +1,57 @@ +npm-link(1) -- Symlink a package folder +======================================= + +## SYNOPSIS + + npm link (in package folder) + npm link <pkgname> + +## DESCRIPTION + +Package linking is a two-step process. + +First, `npm link` in a package folder will create a globally-installed +symbolic link from `prefix/package-name` to the current folder. + +Next, in some other location, `npm link package-name` will create a +symlink from the local `node_modules` folder to the global symlink. + +When creating tarballs for `npm publish`, the linked packages are +"snapshotted" to their current state by resolving the symbolic links. + +This is +handy for installing your own stuff, so that you can work on it and test it +iteratively without having to continually rebuild. + +For example: + + 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 + +Now, any changes to ~/projects/node-redis will be reflected in +~/projects/node-bloggy/node_modules/redis/ + +You may also shortcut the two steps in one. For example, to do the +above use-case in a shorter way: + + cd ~/projects/node-bloggy # go into the dir of your main project + npm link ../node-redis # link the dir of your dependency + +The second line is the equivalent of doing: + + (cd ../node-redis; npm link) + npm link redis + +That is, it first creates a global link, and then links the global +installation target into your project's `node_modules` folder. + +## SEE ALSO + +* npm-developers(1) +* npm-faq(1) +* npm-json(1) +* npm-install(1) +* npm-folders(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/list.md b/deps/npm/doc/cli/list.md new file mode 100644 index 0000000000..596349a815 --- /dev/null +++ b/deps/npm/doc/cli/list.md @@ -0,0 +1,55 @@ +npm-ls(1) -- List installed packages +====================================== + +## SYNOPSIS + + npm list + npm ls + npm la + npm ll + +## DESCRIPTION + +This command will print to stdout all the versions of packages that are +installed, as well as their dependencies, in a tree-structure. + +It does not take positional arguments, though you may set config flags +like with any other command, such as `-g` to list global packages. + +It will print out extraneous, missing, and invalid packages. + +When run as `ll` or `la`, it shows extended information by default. + +## CONFIGURATION + +### long + +* Default: false +* Type: Boolean + +Show extended information. + +### parseable + +* Default: false +* Type: Boolean + +Show parseable output instead of tree view. + +### global + +* Default: false +* Type: Boolean + +List packages in the global install prefix instead of in the current +project. + +## SEE ALSO + +* npm-config(1) +* npm-folders(1) +* npm-install(1) +* npm-link(1) +* npm-prune(1) +* npm-outdated(1) +* npm-update(1) diff --git a/deps/npm/doc/cli/ln.md b/deps/npm/doc/cli/ln.md new file mode 120000 index 0000000000..243f994145 --- /dev/null +++ b/deps/npm/doc/cli/ln.md @@ -0,0 +1 @@ +link.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/ls.md b/deps/npm/doc/cli/ls.md new file mode 120000 index 0000000000..eaad7acae2 --- /dev/null +++ b/deps/npm/doc/cli/ls.md @@ -0,0 +1 @@ +list.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/npm.md b/deps/npm/doc/cli/npm.md new file mode 100644 index 0000000000..cd3360d7c5 --- /dev/null +++ b/deps/npm/doc/cli/npm.md @@ -0,0 +1,155 @@ +npm(1) -- node package manager +============================== + +## SYNOPSIS + + npm <command> [args] + +## VERSION + +@VERSION@ + +## DESCRIPTION + +npm is the package manager for the Node JavaScript platform. It puts +modules in place so that node can find them, and manages dependency +conflicts intelligently. + +It is extremely configurable to support a wide variety of use cases. +Most commonly, it is used to publish, discover, install, and develop node +programs. + +Run `npm help` to get a list of available commands. + +## INTRODUCTION + +You probably got npm because you want to install stuff. + +Use `npm install blerg` to install the latest version of "blerg". Check out +`npm-install(1)` for more info. It can do a lot of stuff. + +Use the `npm search` command to show everything that's available. +Use `npm ls` to show everything you've installed. + +## DIRECTORIES + +See `npm-folders(1)` to learn about where npm puts stuff. + +In particular, npm has two modes of operation: + +* global mode: + npm installs packages into the install prefix at + `prefix/lib/node_modules` and bins are installed in `prefix/bin`. +* local mode: + npm installs packages into the current project directory, which + defaults to the current working directory. Packages are installed to + `./node_modules`, and bins are installed to `./node_modules/.bin`. + +Local mode is the default. Use `--global` or `-g` on any command to +operate in global mode instead. + +## DEVELOPER USAGE + +If you're using npm to develop and publish your code, check out the +following help topics: + +* json: + Make a package.json file. See `npm-json(1)`. +* link: + For linking your current working code into Node's path, so that you + don't have to reinstall every time you make a change. Use + `npm link` to do this. +* install: + It's a good idea to install things if you don't need the symbolic link. + Especially, installing other peoples code from the registry is done via + `npm install` +* adduser: + Create an account or log in. Creditials are stored in the + user config file. +* publish: + Use the `npm publish` command to upload your code to the registry. + +## CONFIGURATION + +npm is extremely configurable. It reads its configuration options from +5 places. + +* Command line switches: + Set a config with `--key val`. All keys take a value, even if they + are booleans (the config parser doesn't know what the options are at + the time of parsing.) If no value is provided, then the option is set + to boolean `true`. +* Environment Variables: + Set any config by prefixing the name in an environment variable with + `npm_config_`. For example, `export npm_config_key=val`. +* User Configs: + The file at $HOME/.npmrc is an ini-formatted list of configs. If + present, it is parsed. If the `userconfig` option is set in the cli + or env, then that will be used instead. +* Global Configs: + The file found at ../etc/npmrc (from the node executable, by default + this resolves to /usr/local/etc/npmrc) will be parsed if it is found. + If the `globalconfig` option is set in the cli, env, or user config, + then that file is parsed instead. +* Defaults: + npm's default configuration options are defined in + lib/utils/config-defs.js. These must not be changed. + +See `npm-config(1)` for much much more information. + +## CONTRIBUTIONS + +Patches welcome! + +* code: + Read through `npm-coding-style(1)` if you plan to submit code. + You don't have to agree with it, but you do have to follow it. +* docs: + If you find an error in the documentation, edit the appropriate markdown + file in the "doc" folder. (Don't worry about generating the man page.) + +Contributors are listed in npm's `package.json` file. You can view them +easily by doing `npm view npm contributors`. + +If you would like to contribute, but don't know what to work on, check +the issues list or ask on the mailing list. + +* <http://github.com/isaacs/npm/issues> +* <npm-@googlegroups.com> + +## BUGS + +When you find issues, please report them: + +* web: + <http://github.com/isaacs/npm/issues> +* email: + <npm-@googlegroups.com> + +Be sure to include *all* of the output from the npm command that didn't work +as expected. The `npm-debug.log` file is also helpful to provide. + +You can also look for isaacs in #node.js on irc://irc.freenode.net. He +will no doubt tell you to put the output in a gist or email. + +## HISTORY + +See npm-changelog(1) + +## AUTHOR + +[Isaac Z. Schlueter](http://blog.izs.me/) :: +[isaacs](https://github.com/isaacs/) :: +[@izs](http://twitter.com/izs) :: +<i@izs.me> + +## SEE ALSO + +* npm-help(1) +* npm-faq(1) +* README +* npm-json(1) +* npm-install(1) +* npm-config(1) +* npm-index(1) +* npm(3) diff --git a/deps/npm/doc/cli/outdated.md b/deps/npm/doc/cli/outdated.md new file mode 100644 index 0000000000..78df4a8b30 --- /dev/null +++ b/deps/npm/doc/cli/outdated.md @@ -0,0 +1,17 @@ +npm-outdated(1) -- Check for outdated packages +============================================== + +## SYNOPSIS + + npm outdated [<name> [<name> ...]] + +## DESCRIPTION + +This command will check the registry to see if any (or, specific) installed +packages are currently outdated. + +## SEE ALSO + +* npm-update(1) +* npm-registry(1) +* npm-folders(1) diff --git a/deps/npm/doc/cli/owner.md b/deps/npm/doc/cli/owner.md new file mode 100644 index 0000000000..8365da379e --- /dev/null +++ b/deps/npm/doc/cli/owner.md @@ -0,0 +1,32 @@ +npm-owner(1) -- Manage package owners +===================================== + +## SYNOPSIS + + npm owner ls <package name> + npm owner add <user> <package name> + npm owner rm <user> <package name> + +## DESCRIPTION + +Manage ownership of published packages. + +* 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. +* 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. +* rm: + Remove a user from the package owner list. This immediately revokes their + privileges. + +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. + +## SEE ALSO + +* npm-publish(1) +* npm-registry(1) +* npm-adduser(1) diff --git a/deps/npm/doc/cli/pack.md b/deps/npm/doc/cli/pack.md new file mode 100644 index 0000000000..98d8c81c50 --- /dev/null +++ b/deps/npm/doc/cli/pack.md @@ -0,0 +1,25 @@ +npm-pack(1) -- Create a tarball from a package +============================================== + +## SYNOPSIS + + npm pack [<pkg> [<pkg> ...]] + +## DESCRIPTION + +For anything that's installable (that is, a package folder, tarball, +tarball url, name@tag, name@version, or name), this command will fetch +it to the cache, and then copy the tarball to the current working +directory as `<name>-<version>.tgz`, and then write the filenames out to +stdout. + +If the same package is specified multiple times, then the file will be +overwritten the second time. + +If no arguments are supplied, then npm packs the current package folder. + +## SEE ALSO + +* npm-cache(1) +* npm-publish(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/prefix.md b/deps/npm/doc/cli/prefix.md new file mode 100644 index 0000000000..f6247cab12 --- /dev/null +++ b/deps/npm/doc/cli/prefix.md @@ -0,0 +1,17 @@ +npm-prefix(1) -- Display prefix +=============================== + +## SYNOPSIS + + npm prefix + +## DESCRIPTION + +Print the prefix to standard out. + +## SEE ALSO + +* npm-root(1) +* npm-bin(1) +* npm-folders(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/prune.md b/deps/npm/doc/cli/prune.md new file mode 100644 index 0000000000..8c4b957e6c --- /dev/null +++ b/deps/npm/doc/cli/prune.md @@ -0,0 +1,21 @@ +npm-prune(1) -- Remove extraneous packages +========================================== + +## SYNOPSIS + + npm prune [<name> [<name ...]] + +## DESCRIPTION + +This command removes "extraneous" packages. If a package name is +provided, then only packages matching one of the supplied names are +removed. + +Extraneous packages are packages that are not listed on the parent +package's dependencies list. + +## SEE ALSO + +* npm-rm(1) +* npm-folders(1) +* npm-list(1) diff --git a/deps/npm/doc/cli/publish.md b/deps/npm/doc/cli/publish.md new file mode 100644 index 0000000000..621932f07c --- /dev/null +++ b/deps/npm/doc/cli/publish.md @@ -0,0 +1,30 @@ +npm-publish(1) -- Publish a package +=================================== + + +## SYNOPSIS + + npm publish <tarball> + npm publish <folder> + +## DESCRIPTION + +Publishes a package to the registry so that it can be installed by name. + +* `<folder>`: + A folder containing a package.json file + +* `<tarball>`: + A url or file path to a gzipped tar archive containing a single folder + with a package.json file inside. + +Fails if the package name and version combination already exists in +the registry. Overwrites when the "--force" flag is set. + +## SEE ALSO + +* npm-registry(1) +* npm-adduser(1) +* npm-owner(1) +* npm-deprecate(1) +* npm-tag(1) diff --git a/deps/npm/doc/cli/rebuild.md b/deps/npm/doc/cli/rebuild.md new file mode 100644 index 0000000000..6985a7bdd7 --- /dev/null +++ b/deps/npm/doc/cli/rebuild.md @@ -0,0 +1,20 @@ +npm-rebuild(1) -- Rebuild a package +=================================== + +## SYNOPSIS + + npm rebuild [<name> [<name> ...]] + +* `<name>`: + The package to rebuild + +## DESCRIPTION + +This command runs the `npm build` command on the matched folders. This is useful +when you install a new version of node, and must recompile all your C++ addons with +the new binary. + +## SEE ALSO + +* npm-build(1) +* npm-install(1) diff --git a/deps/npm/doc/cli/registry.md b/deps/npm/doc/cli/registry.md new file mode 100644 index 0000000000..8073ea0820 --- /dev/null +++ b/deps/npm/doc/cli/registry.md @@ -0,0 +1,92 @@ +npm-registry(1) -- The JavaScript Package Registry +================================================== + +## DESCRIPTION + +To resolve packages by name and version, npm talks to a registry website +that implements the CommonJS Package Registry specification for reading +package info. + +Additionally, npm's package registry implementation supports several +write APIs as well, to allow for publishing packages and managing user +account information. + +The official public npm registry is at <http://registry.npmjs.org/>. It +is powered by a CouchDB database at +<http://isaacs.couchone.com/registry>. The code for the couchapp is +available at <http://github.com/isaacs/npmjs.org>. npm user accounts +are CouchDB users, stored in the <http://isaacs.couchone.com/_users> +database. + +The registry URL is supplied by the `registry` config parameter. See +`npm-config(1)` for more on managing npm's configuration. + +## Can I run my own private registry? + +Yes! + +The easiest way is to replicate the couch database, and use the same (or +similar) design doc to implement the APIs. + +If you set up continuous replication from the official CouchDB, and then +set your internal CouchDB as the registry config, then you'll be able +to read any published packages, in addition to your private ones, and by +default will only publish internally. If you then want to publish a +package for the whole world to see, you can simply override the +`--registry` config for that command. + +## I don't want my package published in the official registry. It's private. + +Set `"private": true` in your package.json to prevent it from being +published at all, or +`"publishConfig":{"registry":"http://my-internal-registry.local"}` +to force it to be published only to your internal registry. + +See `npm-json(1)` for more info on what goes in the package.json file. + +## Will you replicate from my registry into the public one? + +No. If you want things to be public, then publish them into the public +registry using npm. What little security there is would be for nought +otherwise. + +## Do I have to use couchdb to build a registry that npm can talk to? + +No, but it's way easier. + +## I published something elsewhere, and want to tell the npm registry about it. + +That is supported, but not using the npm client. You'll have to get +your hands dirty and do some HTTP. The request looks something like +this: + + PUT /my-foreign-package + content-type:application/json + accept:application/json + authorization:Basic $base_64_encoded + + { "name":"my-foreign-package" + , "maintainers":["owner","usernames"] + , "description":"A package that is hosted elsewhere" + , "keywords":["nih","my cheese smells the best"] + , "url":"http://my-different-registry.com/blerg/my-local-package" + } + +(Keywords and description are optional, but recommended. Name, +maintainers, and url are required.) + +Then, when a user tries to install "my-foreign-package", it'll redirect +to your registry. If that doesn't resolve to a valid package entry, +then it'll fail, so please make sure that you understand the spec, and +ask for help on the <npm-@googlegroups.com> mailing list. + +## Is there a website or something to see package docs and such? + +No, but such a thing is planned, and a tiny bit developed. + +Stay tuned! + +## SEE ALSO + +* npm-config(1) +* npm-developers(1) diff --git a/deps/npm/doc/cli/removing-npm.md b/deps/npm/doc/cli/removing-npm.md new file mode 100644 index 0000000000..bedd28a2fa --- /dev/null +++ b/deps/npm/doc/cli/removing-npm.md @@ -0,0 +1,54 @@ +npm-removal(1) -- Cleaning the Slate +==================================== + +## SYNOPSIS + +So sad to see you go. + + sudo npm uninstall npm -g + +Or, if that fails, get the npm source code, and do: + + sudo make uninstall + +## More Severe Uninstalling + +Usually, the above instructions are sufficient. That will remove +npm, but leave behind anything you've installed. + +If that doesn't work, or if you require more drastic measures, +continue reading. + +Note that this is only necessary for globally-installed packages. Local +installs are completely contained within a project's `node_modules` +folder. Delete that folder, and everything is gone (unless a package's +install script is particularly ill-behaved). + +This assumes that you installed node and npm in the default place. If +you configured node with a different `--prefix`, or installed npm with a +different prefix setting, then adjust the paths accordingly, replacing +`/usr/local` with your install prefix. + +To remove everything npm-related manually: + + rm -rf /usr/local/{lib/node{,/.npm,_modules},bin,share/man}/npm* + +If you installed things *with* npm, then your best bet is to uninstall +them with npm first, and then install them again once you have a +proper install. This can help find any symlinks that are lying +around: + + ls -laF /usr/local/{lib/node{,/.npm},bin,share/man} | grep npm + +Prior to version 0.3, npm used shim files for executables and node +modules. To track those down, you can do the following: + + find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ; + +(This is also in the README file.) + +## SEE ALSO + +* README +* npm-rm(1) +* npm-prune(1) diff --git a/deps/npm/doc/cli/restart.md b/deps/npm/doc/cli/restart.md new file mode 100644 index 0000000000..6139dbeefb --- /dev/null +++ b/deps/npm/doc/cli/restart.md @@ -0,0 +1,22 @@ +npm-restart(1) -- Start a package +================================= + +## SYNOPSIS + + npm restart <name> + +## DESCRIPTION + +This runs a package's "restart" script, if one was provided. +Otherwise it runs package's "stop" script, if one was provided, and then +the "start" script. + +If no version is specified, then it restarts the "active" version. + +## SEE ALSO + +* npm-run-script(1) +* npm-scripts(1) +* npm-test(1) +* npm-start(1) +* npm-stop(1) diff --git a/deps/npm/doc/cli/rm.md b/deps/npm/doc/cli/rm.md new file mode 120000 index 0000000000..32d3b511f9 --- /dev/null +++ b/deps/npm/doc/cli/rm.md @@ -0,0 +1 @@ +uninstall.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/root.md b/deps/npm/doc/cli/root.md new file mode 100644 index 0000000000..3e4199541e --- /dev/null +++ b/deps/npm/doc/cli/root.md @@ -0,0 +1,17 @@ +npm-root(1) -- Display npm root +=============================== + +## SYNOPSIS + + npm root + +## DESCRIPTION + +Print the effective `node_modules` folder to standard out. + +## SEE ALSO + +* npm-prefix(1) +* npm-bin(1) +* npm-folders(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/run-script.md b/deps/npm/doc/cli/run-script.md new file mode 100644 index 0000000000..41ef5e7872 --- /dev/null +++ b/deps/npm/doc/cli/run-script.md @@ -0,0 +1,21 @@ +npm-run-script(1) -- Run arbitrary package scripts +================================================== + +## SYNOPSIS + + npm run-script <script> <name> + +## DESCRIPTION + +This runs an arbitrary command from a package's "scripts" object. + +It is used by the test, start, restart, and stop commands, but can be +called directly, as well. + +## SEE ALSO + +* npm-scripts(1) +* npm-test(1) +* npm-start(1) +* npm-restart(1) +* npm-stop(1) diff --git a/deps/npm/doc/cli/scripts.md b/deps/npm/doc/cli/scripts.md new file mode 100644 index 0000000000..64b3ec41a0 --- /dev/null +++ b/deps/npm/doc/cli/scripts.md @@ -0,0 +1,182 @@ +npm-scripts(1) -- How npm handles the "scripts" field +===================================================== + +## DESCRIPTION + +npm supports the "scripts" member of the package.json script, for the +following scripts: + +* preinstall: + Run BEFORE the package is installed +* install, postinstall: + Run AFTER the package is installed. +* preuninstall, uninstall: + Run BEFORE the package is uninstalled. +* postuninstall: + Run AFTER the package is uninstalled. +* preupdate: + Run BEFORE the package is updated with the update command. +* update, postupdate: + Run AFTER the package is updated with the update command. +* prepublish: + Run BEFORE the package is published. +* publish, postpublish: + Run AFTER the package is published. +* pretest, test, posttest: + Run by the `npm test` command. +* prestop, stop, poststop: + Run by the `npm stop` command. +* prestart, start, poststart: + Run by the `npm start` command. +* prerestart, restart, postrestart: + Run by the `npm restart` command. Note: `npm restart` will run the + stop and start scripts if no `restart` script is provided. + +Additionally, arbitrary scrips can be run by doing +`npm run-script <stage> <pkg>`. + +## DEFAULT VALUES + +npm will default some script values based on package contents. + +* `"start": "node server.js"`: + + If there is a `server.js` file in the root of your package, then npm + will default the `start` command to `node server.js`. + +* `"preinstall": "node-waf clean || true; node-waf configure build"`: + + If there is a `wscript` file in the root of your package, npm will + default the `preinstall` command to compile using node-waf. + +## USER + +If npm was invoked with root privileges, then it will change the uid to +the user account or uid specified by the `user` config, which defaults +to `nobody`. Set the `unsafe-perm` flag to run scripts with root +privileges. + +## ENVIRONMENT + +Package scripts run in an environment where many pieces of information are +made available regarding the setup of npm and the current state of the +process. + +### package.json vars + +The package.json fields are tacked onto the `npm_package_` prefix. So, for +instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json +file, then your package scripts would have the `npm_package_name` environment +variable set to "foo", and the `npm_package_version` set to "1.2.5" + +### configuration + +Configuration parameters are put in the environment with the `npm_config_` +prefix. For instance, you can view the effective `root` config by checking the +`npm_config_root` environment variable. + +### Special: package.json "config" hash + +The package.json "config" keys are overwritten in the environment if +there is a config param of `<name>[@<version>]:<key>`. For example, if +the package.json has this: + + { "name" : "foo" + , "config" : { "port" : "8080" } + , "scripts" : { "start" : "node server.js" } } + +and the server.js is this: + + http.createServer(...).listen(process.env.npm_package_config_port) + +then the user could change the behavior by doing: + + npm config set foo:port 80 + +### current lifecycle event + +Lastly, the `npm_lifecycle_event` environment variable is set to whichever +stage of the cycle is being executed. So, you could have a single script used +for different parts of the process which switches based on what's currently +happening. + + +Objects are flattened following this format, so if you had +`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this +in the script: + + process.env.npm_package_scripts_install === "foo.js" + +## EXAMPLES + +For example, if your package.json contains this: + + { "scripts" : + { "install" : "scripts/install.js" + , "postinstall" : "scripts/install.js" + , "uninstall" : "scripts/uninstall.js" + } + } + +then the `scripts/install.js` will be called for the install, post-install, +stages of the lifecycle, and the `scripts/uninstall.js` would be +called when the package is uninstalled. Since `scripts/install.js` is running +for three different phases, it would be wise in this case to look at the +`npm_lifecycle_event` environment variable. + +If you want to run a make command, you can do so. This works just fine: + + { "scripts" : + { "preinstall" : "./configure" + , "install" : "make && make install" + , "test" : "make test" + } + } + +## EXITING + +Scripts are run by passing the line as a script argument to `sh`. + +If the script exits with a code other than 0, then this will abort the +process. + +Note that these script files don't have to be nodejs or even javascript +programs. They just have to be some kind of executable file. + +## HOOK SCRIPTS + +If you want to run a specific script at a specific lifecycle event for ALL +packages, then you can use a hook script. + +Place an executable file at `node_modules/.hooks/{eventname}`, and it'll get +run for all packages when they are going through that point in the package +lifecycle for any packages installed in that root. + +Hook scripts are run exactly the same way as package.json scripts. That is, +they are in a separate child process, with the env described above. + +## BEST PRACTICES + +* Don't exit with a non-zero error code unless you *really* mean it. + Except for uninstall scripts, this will cause the npm action + to fail, and potentially be rolled back. If the failure is minor or + only will prevent some optional features, then it's better to just + print a warning and exit successfully. +* Try not to use scripts to do what npm can do for you. Read through + `npm-json(1)` to see all the things that you can specify and enable + by simply describing your package appropriately. In general, this will + lead to a more robust and consistent state. +* Inspect the env to determine where to put things. For instance, if + the `npm_config_binroot` environ is set to `/home/user/bin`, then don't + try to install executables into `/usr/local/bin`. The user probably + set it up that way for a reason. +* Don't prefix your script commands with "sudo". If root permissions are + required for some reason, then it'll fail with that error, and the user + will sudo the npm command in question. + +## SEE ALSO + +* npm-run-script(1) +* npm-json(1) +* npm-developers(1) +* npm-install(1) diff --git a/deps/npm/doc/cli/search.md b/deps/npm/doc/cli/search.md new file mode 100644 index 0000000000..3b15e9b073 --- /dev/null +++ b/deps/npm/doc/cli/search.md @@ -0,0 +1,39 @@ +npm-search(1) -- Search for packages +==================================== + +## SYNOPSIS + + npm search [search terms ...] + +## DESCRIPTION + +Search the registry for packages matching the search terms. + +## CONFIGURATION + +### description + +* Default: true +* Type: Boolean + +Show the description in `npm search` + +### searchopts + +* Default: "" +* Type: String + +Space-separated options that are always passed to search. + +### searchexclude + +* Default: "" +* Type: String + +Space-separated options that limit the results from search. + +## SEE ALSO + +* npm-registry(1) +* npm-config(1) +* npm-view(1) diff --git a/deps/npm/doc/cli/semver.md b/deps/npm/doc/cli/semver.md new file mode 100644 index 0000000000..7eb2240639 --- /dev/null +++ b/deps/npm/doc/cli/semver.md @@ -0,0 +1,130 @@ +npm-semver(1) -- The semantic versioner for npm +=============================================== + +## SYNOPSIS + +The npm semantic versioning utility. + +## DESCRIPTION + +As a node module: + + $ npm install semver + + semver.valid('1.2.3') // true + semver.valid('a.b.c') // false + semver.clean(' =v1.2.3 ') // '1.2.3' + semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true + semver.gt('1.2.3', '9.8.7') // false + semver.lt('1.2.3', '9.8.7') // true + +As a command-line utility: + + $ npm install semver -g + $ semver -h + + Usage: semver -v <version> [-r <range>] + Test if version(s) satisfy the supplied range(s), + and sort them. + + Multiple versions or ranges may be supplied. + + Program exits successfully if any valid version satisfies + all supplied ranges, and prints all satisfying versions. + + If no versions are valid, or ranges are not satisfied, + then exits failure. + + Versions are printed in ascending order, so supplying + multiple versions to the utility will just sort them. + +## Versions + +A version is the following things, in this order: + +* a number (Major) +* a period +* a number (minor) +* a period +* a number (patch) +* OPTIONAL: a hyphen, followed by a number (build) +* OPTIONAL: a collection of pretty much any non-whitespace characters + (tag) + +A leading `"="` or `"v"` character is stripped off and ignored. + +## Comparisons + +The ordering of versions is done using the following algorithm, given +two versions and asked to find the greater of the two: + +* If the majors are numerically different, then take the one + with a bigger major number. `2.3.4 > 1.3.4` +* If the minors are numerically different, then take the one + with the bigger minor number. `2.3.4 > 2.2.4` +* If the patches are numerically different, then take the one with the + bigger patch number. `2.3.4 > 2.3.3` +* If only one of them has a build number, then take the one with the + build number. `2.3.4-0 > 2.3.4` +* If they both have build numbers, and the build numbers are numerically + different, then take the one with the bigger build number. + `2.3.4-10 > 2.3.4-9` +* If only one of them has a tag, then take the one without the tag. + `2.3.4 > 2.3.4-beta` +* If they both have tags, then take the one with the lexicographically + larger tag. `2.3.4-beta > 2.3.4-alpha` +* At this point, they're equal. + +## Ranges + +The following range styles are supported: + +* `>1.2.3` Greater than a specific version. +* `<1.2.3` Less than +* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` +* `~1.2.3` := `>=1.2.3 <1.3.0` +* `~1.2` := `>=1.2.0 <2.0.0` +* `~1` := `>=1.0.0 <2.0.0` +* `1.2.x` := `>=1.2.0 <1.3.0` +* `1.x` := `>=1.0.0 <2.0.0` + +Ranges can be joined with either a space (which implies "and") or a +`||` (which implies "or"). + +## Functions + +* valid(v): Return the parsed version, or null if it's not valid. +* inc(v, release): Return the version incremented by the release type + (major, minor, patch, or build), or null if it's not valid. + +### Comparison + +* gt(v1, v2): `v1 > v2` +* gte(v1, v2): `v1 >= v2` +* lt(v1, v2): `v1 < v2` +* lte(v1, v2): `v1 <= v2` +* eq(v1, v2): `v1 == v2` This is true if they're logically equivalent, + even if they're not the exact same string. You already know how to + compare strings. +* neq(v1, v2): `v1 != v2` The opposite of eq. +* cmp(v1, comparator, v2): Pass in a comparison string, and it'll call + the corresponding function above. `"==="` and `"!=="` do simple + string comparison, but are included for completeness. Throws if an + invalid comparison string is provided. +* compare(v1, v2): Return 0 if v1 == v2, or 1 if v1 is greater, or -1 if + v2 is greater. Sorts in ascending order if passed to Array.sort(). +* rcompare(v1, v2): The reverse of compare. Sorts an array of versions + in descending order when passed to Array.sort(). + + +### Ranges + +* validRange(range): Return the valid range or null if it's not valid +* satisfies(version, range): Return true if the version satisfies the + range. +* maxSatisfying(versions, range): Return the highest version in the list + that satisfies the range, or null if none of them do. + +## SEE ALSO + +* npm-json(1) diff --git a/deps/npm/doc/cli/set.md b/deps/npm/doc/cli/set.md new file mode 120000 index 0000000000..3dc8737366 --- /dev/null +++ b/deps/npm/doc/cli/set.md @@ -0,0 +1 @@ +config.md
\ No newline at end of file diff --git a/deps/npm/doc/cli/star.md b/deps/npm/doc/cli/star.md new file mode 100644 index 0000000000..5c076b3c3c --- /dev/null +++ b/deps/npm/doc/cli/star.md @@ -0,0 +1,22 @@ +npm-star(1) -- Mark your favorite packages +========================================== + +## SYNOPSIS + + npm star <pkgname> [<pkg>, ...] + npm unstar <pkgname> [<pkg>, ...] + +## DESCRIPTION + +"Starring" a package means that you have some interest in it. It's +a vaguely positive way to show that you care. + +"Unstarring" is the same thing, but in reverse. + +It's a boolean thing. Starring repeatedly has no additional effect. + +## SEE ALSO + +* npm-view(1) +* npm-whoami(1) +* npm-adduser(1) diff --git a/deps/npm/doc/cli/start.md b/deps/npm/doc/cli/start.md new file mode 100644 index 0000000000..cc897bbc09 --- /dev/null +++ b/deps/npm/doc/cli/start.md @@ -0,0 +1,18 @@ +npm-start(1) -- Start a package +=============================== + +## SYNOPSIS + + npm start <name> + +## DESCRIPTION + +This runs a package's "start" script, if one was provided. + +## SEE ALSO + +* npm-run-script(1) +* npm-scripts(1) +* npm-test(1) +* npm-restart(1) +* npm-stop(1) diff --git a/deps/npm/doc/cli/stop.md b/deps/npm/doc/cli/stop.md new file mode 100644 index 0000000000..1ab3e9975d --- /dev/null +++ b/deps/npm/doc/cli/stop.md @@ -0,0 +1,18 @@ +npm-stop(1) -- Stop a package +============================= + +## SYNOPSIS + + npm stop <name> + +## DESCRIPTION + +This runs a package's "stop" script, if one was provided. + +## SEE ALSO + +* npm-run-script(1) +* npm-scripts(1) +* npm-test(1) +* npm-start(1) +* npm-restart(1) diff --git a/deps/npm/doc/cli/submodule.md b/deps/npm/doc/cli/submodule.md new file mode 100644 index 0000000000..13ab1edd95 --- /dev/null +++ b/deps/npm/doc/cli/submodule.md @@ -0,0 +1,28 @@ +npm-submodule(1) -- Add a package as a git submodule +==================================================== + +## SYNOPSIS + + npm submodule <pkg> + +## DESCRIPTION + +If the specified package has a git repository url in its package.json +description, then this command will add it as a git submodule at +`node_modules/<pkg name>`. + +This is a convenience only. From then on, it's up to you to manage +updates by using the appropriate git commands. npm will stubbornly +refuse to update, modify, or remove anything with a `.git` subfolder +in it. + +This command also does not install missing dependencies, if the package +does not include them in its git repository. If `npm ls` reports that +things are missing, you can either install, link, or submodule them yourself, +or you can do `npm explore <pkgname> -- npm install` to install the +dependencies into the submodule folder. + +## SEE ALSO + +* npm-json(1) +* git help submodule diff --git a/deps/npm/doc/cli/tag.md b/deps/npm/doc/cli/tag.md new file mode 100644 index 0000000000..2f1ca4373e --- /dev/null +++ b/deps/npm/doc/cli/tag.md @@ -0,0 +1,17 @@ +npm-tag(1) -- Tag a published version +===================================== + +## SYNOPSIS + + npm tag <name>@<version> [<tag>] + +## DESCRIPTION + +Tags the specified version of the package with the specified tag, or the +`--tag` config if not specified. + +## SEE ALSO + +* npm-publish(1) +* npm-registry(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/test.md b/deps/npm/doc/cli/test.md new file mode 100644 index 0000000000..bc634efbf3 --- /dev/null +++ b/deps/npm/doc/cli/test.md @@ -0,0 +1,21 @@ +npm-test(1) -- Test a package +============================= + +## SYNOPSIS + + npm test <name> + +## DESCRIPTION + +This runs a package's "test" script, if one was provided. + +To run tests as a condition of installation, set the `npat` config to +true. + +## SEE ALSO + +* npm-run-script(1) +* npm-scripts(1) +* npm-start(1) +* npm-restart(1) +* npm-stop(1) diff --git a/deps/npm/doc/cli/uninstall.md b/deps/npm/doc/cli/uninstall.md new file mode 100644 index 0000000000..f7f743fae2 --- /dev/null +++ b/deps/npm/doc/cli/uninstall.md @@ -0,0 +1,19 @@ +npm-rm(1) -- Remove a package +============================= + +## SYNOPSIS + + npm rm <name> + npm uninstall <name> + +## DESCRIPTION + +This uninstalls a package, completely removing everything npm installed +on its behalf. + +## SEE ALSO + +* npm-prune(1) +* npm-install(1) +* npm-folders(1) +* npm-config(1) diff --git a/deps/npm/doc/cli/unpublish.md b/deps/npm/doc/cli/unpublish.md new file mode 100644 index 0000000000..0f4446c4ed --- /dev/null +++ b/deps/npm/doc/cli/unpublish.md @@ -0,0 +1,32 @@ +npm-unpublish(1) -- Remove a package from the registry +====================================================== + +## SYNOPSIS + + npm unpublish <name>[@<version>] + +## WARNING + +**It is generally considered bad behavior to remove versions of a library +that others are depending on!** + +Consider using the `deprecate` command +instead, if your intent is to encourage users to upgrade. + +There is plenty of room on the registry. + +## DESCRIPTION + +This removes a package version from the registry, deleting its +entry and removing the tarball. + +If no version is specified, or if all versions are removed then +the root package entry is removed from the registry entirely. + +## SEE ALSO + +* npm-deprecate(1) +* npm-publish(1) +* npm-registry(1) +* npm-adduser(1) +* npm-owner(1) diff --git a/deps/npm/doc/cli/update.md b/deps/npm/doc/cli/update.md new file mode 100644 index 0000000000..1de49f2e2f --- /dev/null +++ b/deps/npm/doc/cli/update.md @@ -0,0 +1,21 @@ +npm-update(1) -- Update a package +================================= + +## SYNOPSIS + + npm update [<name> [<name> ...]] + +## DESCRIPTION + +This command will update all the packages listed to the latest version +(specified by the `tag` config). + +It will also install missing packages. + +## SEE ALSO + +* npm-install(1) +* npm-outdated(1) +* npm-registry(1) +* npm-folders(1) +* npm-list(1) diff --git a/deps/npm/doc/cli/version.md b/deps/npm/doc/cli/version.md new file mode 100644 index 0000000000..480c90d3b4 --- /dev/null +++ b/deps/npm/doc/cli/version.md @@ -0,0 +1,27 @@ +npm-version(1) -- Bump a package version +======================================== + +## SYNOPSIS + + npm version <newversion> [--message commit-message] + +## DESCRIPTION + +Run this in a package directory to bump the version and write the new +data back to the package.json file. + +The `newversion` argument should be a valid semver string, *or* a valid +second argument to semver.inc (one of "patch", "minor", or "major"). In +the second case, the existing version will be incremented by that amount. + +If run in a git repo, it will also create a version commit and tag, and +fail if the repo is not clean. + +If supplied with `--message` (shorthand: `-m`) command line option, npm +will use it as a commit message when creating a version commit. + +## SEE ALSO + +* npm-init(1) +* npm-json(1) +* npm-semver(1) diff --git a/deps/npm/doc/cli/view.md b/deps/npm/doc/cli/view.md new file mode 100644 index 0000000000..5ec9dc0aca --- /dev/null +++ b/deps/npm/doc/cli/view.md @@ -0,0 +1,85 @@ +npm-view(1) -- View registry info +================================= + +## SYNOPSIS + + npm view <name>[@<version>] [<field>[.<subfield>]...] + +## DESCRIPTION + +This command shows data about a package and prints it to the stream +referenced by the `outfd` config, which defaults to stdout. + +To show the package registry entry for the `connect` package, you can do +this: + + npm view connect + +The default version is "latest" if unspecified. + +Field names can be specified after the package descriptor. +For example, to show the dependencies of the `ronn` package at version +0.3.5, you could do the following: + + npm view ronn@0.3.5 dependencies + +You can view child field by separating them with a period. +To view the git repository URL for the latest version of npm, you could +do this: + + npm view npm repository.url + +This makes it easy to view information about a dependency with a bit of +shell scripting. For example, to view all the data about the version of +opts that ronn depends on, you can do this: + + npm view opts@$(npm view ronn dependencies.opts) + +For fields that are arrays, requesting a non-numeric field will return +all of the values from the objects in the list. For example, to get all +the contributor names for the "express" project, you can do this: + + npm view express contributors.email + +You may also use numeric indices in square braces to specifically select +an item in an array field. To just get the email address of the first +contributor in the list, you can do this: + + npm view express contributors[0].email + +Multiple fields may be specified, and will be printed one after another. +For exampls, to get all the contributor names and email addresses, you +can do this: + + npm view express contributors.name contributors.email + +"Person" fields are shown as a string if they would be shown as an +object. So, for example, this will show the list of npm contributors in +the shortened string format. (See `npm-json(1)` for more on this.) + + npm view npm contributors + +If a version range is provided, then data will be printed for every +matching version of the package. This will show which version of jsdom +was required by each matching version of yui3: + + npm view yui3@'>0.5.4' dependencies.jsdom + +## OUTPUT + +If only a single string field for a single version is output, then it +will not be colorized or quoted, so as to enable piping the output to +another command. + +If the version range matches multiple versions, than each printed value +will be prefixed with the version it applies to. + +If multiple fields are requested, than each of them are prefixed with +the field name. + +## SEE ALSO + +* npm-search(1) +* npm-registry(1) +* npm-config(1) +* npm-docs(1) diff --git a/deps/npm/doc/cli/whoami.md b/deps/npm/doc/cli/whoami.md new file mode 100644 index 0000000000..7c39b1624a --- /dev/null +++ b/deps/npm/doc/cli/whoami.md @@ -0,0 +1,15 @@ +npm-whoami(1) -- Display npm username +===================================== + +## SYNOPSIS + + npm whoami + +## DESCRIPTION + +Print the `username` config to standard output. + +## SEE ALSO + +* npm-config(1) +* npm-adduser(1) |