v1.3.10.tar.gz~dfsg/0000755000000000000000000000000012212013731012720 5ustar rootrootv1.3.10.tar.gz~dfsg/doc/0000755000000000000000000000000012212013731013465 5ustar rootrootv1.3.10.tar.gz~dfsg/doc/misc/0000755000000000000000000000000012212013731014420 5ustar rootrootv1.3.10.tar.gz~dfsg/doc/misc/semver.md0000644000000000000000000001034212212013731016243 0ustar rootrootsemver(7) -- The semantic versioner for npm =========================================== ## Usage $ npm install semver semver.valid('1.2.3') // '1.2.3' semver.valid('a.b.c') // null 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: $ semver -h Usage: semver [ [...]] [-r | -i | -d ] Test if version(s) satisfy the supplied range(s), and sort them. Multiple versions or ranges may be supplied, unless increment or decrement options are specified. In that case, only a single version may be used, and it is incremented by the specified level 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 described by the v2.0.0 specification found at . A leading `"="` or `"v"` character is stripped off and ignored. ## Ranges The following range styles are supported: * `1.2.3` A specific version. When nothing else will do. Note that build metadata is still ignored, so `1.2.3+build2012` will satisfy this range. * `>1.2.3` Greater than a specific version. * `<1.2.3` Less than a specific version. If there is no prerelease tag on the version range, then no prerelease version will be allowed either, even though these are technically "less than". * `>=1.2.3` Greater than or equal to. Note that prerelease versions are NOT equal to their "normal" equivalents, so `1.2.3-beta` will not satisfy this range, but `2.3.0-beta` will. * `<=1.2.3` Less than or equal to. In this case, prerelease versions ARE allowed, so `1.2.3-beta` would satisfy. * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` * `~1.2.3` := `>=1.2.3-0 <1.3.0-0` "Reasonably close to 1.2.3". When using tilde operators, prerelease versions are supported as well, but a prerelease of the next significant digit will NOT be satisfactory, so `1.3.0-beta` will not satisfy `~1.2.3`. * `~1.2` := `>=1.2.0-0 <1.3.0-0` "Any version starting with 1.2" * `1.2.x` := `>=1.2.0-0 <1.3.0-0` "Any version starting with 1.2" * `~1` := `>=1.0.0-0 <2.0.0-0` "Any version starting with 1" * `1.x` := `>=1.0.0-0 <2.0.0-0` "Any version starting with 1" Ranges can be joined with either a space (which implies "and") or a `||` (which implies "or"). ## Functions All methods and classes take a final `loose` boolean argument that, if true, will be more forgiving about not-quite-valid semver strings. The resulting output will always be 100% strict, of course. Strict-mode Comparators and Ranges will be strict about the SemVer strings that they parse. * 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 prerelease), 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. v1.3.10.tar.gz~dfsg/doc/misc/npm-registry.md0000644000000000000000000000463412212013731017411 0ustar rootrootnpm-registry(7) -- 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 . It is powered by a CouchDB database at . The code for the couchapp is available at . npm user accounts are CouchDB users, stored in the database. The registry URL is supplied by the `registry` config parameter. See `npm-config(1)`, `npmrc(5)`, and `npm-config(7)` 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 `package.json(5)` 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. Basically, yes, you do, or you have to effectively implement the entire CouchDB API anyway. ## Is there a website or something to see package docs and such? Yes, head over to ## SEE ALSO * npm-config(1) * npm-config(7) * npmrc(5) * npm-developers(7) * npm-disputes(7) v1.3.10.tar.gz~dfsg/doc/misc/npm-disputes.md0000644000000000000000000001072212212013731017374 0ustar rootrootnpm-disputes(7) -- Handling Module Name Disputes ================================================ ## SYNOPSIS 1. Get the author email with `npm owner ls ` 2. Email the author, CC . 3. After a few weeks, if there's no resolution, we'll sort it out. Don't squat on package names. Publish code or move out of the way. ## DESCRIPTION There sometimes arise cases where a user publishes a module, and then later, some other user wants to use that name. Here are some common ways that happens (each of these is based on actual events.) 1. Joe writes a JavaScript module `foo`, which is not node-specific. Joe doesn't use node at all. Bob wants to use `foo` in node, so he wraps it in an npm module. Some time later, Joe starts using node, and wants to take over management of his program. 2. Bob writes an npm module `foo`, and publishes it. Perhaps much later, Joe finds a bug in `foo`, and fixes it. He sends a pull request to Bob, but Bob doesn't have the time to deal with it, because he has a new job and a new baby and is focused on his new erlang project, and kind of not involved with node any more. Joe would like to publish a new `foo`, but can't, because the name is taken. 3. Bob writes a 10-line flow-control library, and calls it `foo`, and publishes it to the npm registry. Being a simple little thing, it never really has to be updated. Joe works for Foo Inc, the makers of the critically acclaimed and widely-marketed `foo` JavaScript toolkit framework. They publish it to npm as `foojs`, but people are routinely confused when `npm install foo` is some different thing. 4. Bob writes a parser for the widely-known `foo` file format, because he needs it for work. Then, he gets a new job, and never updates the prototype. Later on, Joe writes a much more complete `foo` parser, but can't publish, because Bob's `foo` is in the way. The validity of Joe's claim in each situation can be debated. However, Joe's appropriate course of action in each case is the same. 1. `npm owner ls foo`. This will tell Joe the email address of the owner (Bob). 2. Joe emails Bob, explaining the situation **as respectfully as possible**, and what he would like to do with the module name. He adds isaacs to the CC list of the email. Mention in the email that Bob can run `npm owner add joe foo` to add Joe as an owner of the `foo` package. 3. After a reasonable amount of time, if Bob has not responded, or if Bob and Joe can't come to any sort of resolution, email isaacs and we'll sort it out. ("Reasonable" is usually about 4 weeks, but extra time is allowed around common holidays.) ## REASONING In almost every case so far, the parties involved have been able to reach an amicable resolution without any major intervention. Most people really do want to be reasonable, and are probably not even aware that they're in your way. Module ecosystems are most vibrant and powerful when they are as self-directed as possible. If an admin one day deletes something you had worked on, then that is going to make most people quite upset, regardless of the justification. When humans solve their problems by talking to other humans with respect, everyone has the chance to end up feeling good about the interaction. ## EXCEPTIONS Some things are not allowed, and will be removed without discussion if they are brought to the attention of the npm registry admins, including but not limited to: 1. Malware (that is, a package designed to exploit or harm the machine on which it is installed). 2. Violations of copyright or licenses (for example, cloning an MIT-licensed program, and then removing or changing the copyright and license statement). 3. Illegal content. 4. "Squatting" on a package name that you *plan* to use, but aren't actually using. Sorry, I don't care how great the name is, or how perfect a fit it is for the thing that someday might happen. If someone wants to use it today, and you're just taking up space with an empty tarball, you're going to be evicted. 5. Putting empty packages in the registry. Packages must have SOME functionality. It can be silly, but it can't be *nothing*. (See also: squatting.) 6. Doing weird things with the registry, like using it as your own personal application database or otherwise putting non-packagey things into it. If you see bad behavior like this, please report it right away. ## SEE ALSO * npm-registry(7) * npm-owner(1) v1.3.10.tar.gz~dfsg/doc/misc/npm-config.md0000644000000000000000000004377412212013731017016 0ustar rootrootnpm-config(7) -- More than you probably want to know about npm configuration ============================================================================ ## 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. ### npmrc Files The three relevant files are: * per-user config file (~/.npmrc) * global config file ($PREFIX/npmrc) * npm builtin config file (/path/to/npm/npmrc) See npmrc(5) for more details. ### Default Configs A set of configuration parameters that are internal to npm, and are defaults if nothing else is specified. ## Shorthands and Other CLI Niceties The following shorthands are parsed on the command-line: * `-v`: `--version` * `-h`, `-?`, `--help`, `-H`: `--usage` * `-s`, `--silent`: `--loglevel silent` * `-q`, `--quiet`: `--loglevel warn` * `-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` * `-desc`: `--description` * `-S`: `--save` * `-D`: `--save-dev` * `-O`: `--save-optional` * `-B`: `--save-bundle` * `-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(7)`) the package.json "config" keys are overwritten in the environment if there is a config param of `[@]:`. 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 See package.json(5) for more information. ## Config Settings ### always-auth * Default: false * Type: Boolean Force npm to always require authentication when accessing the registry, even for `GET` requests. ### bin-links * Default: `true` * Type: Boolean Tells npm to create symlinks (or `.cmd` shims on Windows) for package executables. Set to false to have it not do this. This can be used to work around the fact that some file systems don't support symlinks, even on ostensibly Unix systems. ### browser * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` * 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: `%APPDATA%\npm-cache`, Posix: `~/.npm` * Type: path The location of npm's cache directory. See `npm-cache(1)` ### cache-lock-stale * Default: 60000 (1 minute) * Type: Number The number of ms before cache folder lockfiles are considered stale. ### cache-lock-retries * Default: 10 * Type: Number Number of times to retry to acquire a lock on cache folder lockfiles. ### cache-lock-wait * Default: 10000 (10 seconds) * Type: Number Number of ms to wait for cache lock files to expire. ### cache-max * Default: Infinity * Type: Number The maximum time (in seconds) to keep items in the registry cache before re-checking against the registry. Note that no purging is done unless the `npm cache clean` command is explicitly used, and that only GET requests use the cache. ### cache-min * Default: 10 * Type: Number The minimum time (in seconds) to keep items in the registry cache before re-checking against the registry. Note that no purging is done unless the `npm cache clean` command is explicitly used, and that only GET requests use the cache. ### 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. ### coverage * Default: false * Type: Boolean A flag to tell test-harness to run with their coverage options enabled, if they respond to the `npm_config_coverage` environment variable. ### 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`. ### engine-strict * Default: false * Type: Boolean If set to true, then npm will stubbornly refuse to install (or even consider installing) any package that claims to not be compatible with the current Node.js version. ### 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. ### fetch-retries * Default: 2 * Type: Number The "retries" config for the `retry` module to use when fetching packages from the registry. ### fetch-retry-factor * Default: 10 * Type: Number The "factor" config for the `retry` module to use when fetching packages. ### fetch-retry-mintimeout * Default: 10000 (10 seconds) * Type: Number The "minTimeout" config for the `retry` module to use when fetching packages. ### fetch-retry-maxtimeout * Default: 60000 (1 minute) * Type: Number The "maxTimeout" config for the `retry` module to use when fetching packages. ### git * Default: `"git"` * Type: String The command to use for git commands. If git is installed on the computer, but is not in the `PATH`, then set this to the full path to the git binary. ### 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(5)` for more on the differences in behavior. * packages are installed into the `{prefix}/lib/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. ### user-agent * Default: node/{process.version} {process.platform} {process.arch} * Type: String Sets a User-Agent to the request header ### ignore * Default: "" * Type: string A white-space separated list of glob patterns of files to always exclude from packages when building tarballs. ### init-module * Default: ~/.npm-init.js * Type: path A module that will be loaded by the `npm init` command. See the documentation for the [init-package-json](https://github.com/isaacs/init-package-json) module for more information, or npm-init(1). ### init.version * Default: "0.0.0" * Type: semver The value `npm init` should use by default for the package version. ### init.author.name * Default: "" * 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. ### json * Default: false * Type: Boolean Whether or not to output JSON data, rather than the normal output. This feature is currently experimental, and the output data structures for many commands is either not implemented in JSON yet, or subject to change. Only the output from `npm ls --json` is currently valid. ### 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. ### loglevel * Default: "http" * Type: String * Values: "silent", "win", "error", "warn", "http", "info", "verbose", "silly" What level of logs to report. On failure, *all* logs are written to `npm-debug.log` in the current working directory. Any logs of a higher level than the setting are shown. The default is "http", which shows http, warn, and error output. ### logstream * Default: process.stderr * Type: Stream This is the stream that is passed to the [npmlog](https://github.com/isaacs/npmlog) module at run time. It cannot be set from the command line, but if you are using npm programmatically, you may wish to send logs to somewhere other than stderr. If the `color` config is set to true, then this stream will receive colored output if it is a TTY. ### 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. ### optional * Default: true * Type: Boolean Attempt to install packages in the `optionalDependencies` hash. Note that if these packages fail to install, the overall installation process is not aborted. ### parseable * Default: false * Type: Boolean Output parseable results from commands that write to standard output. ### prefix * Default: see npm-folders(5) * 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. ### proprietary-attribs * Default: true * Type: Boolean Whether or not to include proprietary extended attributes in the tarballs created by npm. Unless you are expecting to unpack package tarballs with something other than npm -- particularly a very outdated tar implementation -- leave this as true. ### 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. When used with the `npm rm` command, it removes it from the dependencies hash. Only works if there is already a package.json file present. ### save-bundle * Default: false * Type: Boolean If a package would be saved at install time by the use of `--save`, `--save-dev`, or `--save-optional`, then also put it in the `bundleDependencies` list. When used with the `npm rm` command, it removes it from the bundledDependencies list. ### save-dev * Default: false * Type: Boolean Save installed packages to a package.json file as devDependencies. When used with the `npm rm` command, it removes it from the devDependencies hash. Only works if there is already a package.json file present. ### save-optional * Default: false * Type: Boolean Save installed packages to a package.json file as optionalDependencies. When used with the `npm rm` command, it removes it from the devDependencies hash. 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. ### searchsort * Default: "name" * Type: String * Values: "name", "-name", "date", "-date", "description", "-description", "keywords", "-keywords" Indication of which field to sort search results by. Prefix with a `-` character to indicate reverse sort. ### shell * Default: SHELL environment variable, or "bash" on Posix, or "cmd" on Windows * Type: path The shell to run for the `npm explore` command. ### shrinkwrap * Default: true * Type: Boolean If set to false, then ignore `npm-shrinkwrap.json` files when installing. ### sign-git-tag * Default: false * Type: Boolean If set to true, then the `npm version` command will tag the version using `-s` to add a signature. Note that git requires you to have set up GPG keys in your git configs for this to work properly. ### 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. ### versions * Default: false * Type: boolean If true, output the npm version as well as node's `process.versions` hash, 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-config(1) * npm-config(7) * npmrc(5) * npm-scripts(7) * npm-folders(5) * npm(1) v1.3.10.tar.gz~dfsg/doc/misc/npm-scripts.md0000644000000000000000000002100412212013731017216 0ustar rootrootnpm-scripts(7) -- How npm handles the "scripts" field ===================================================== ## DESCRIPTION npm supports the "scripts" member of the package.json script, for the following scripts: * prepublish: Run BEFORE the package is published. (Also run on local `npm install` without any arguments.) * publish, postpublish: Run AFTER the package is published. * 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. * 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 scripts can be run by doing `npm run-script `. ## NOTE: INSTALL SCRIPTS ARE AN ANTIPATTERN **tl;dr** Don't use `install`. Use a `.gyp` file for compilation, and `prepublish` for anything else. You should almost never have to explicitly set a `preinstall` or `install` script. If you are doing this, please consider if there is another option. The only valid use of `install` or `preinstall` scripts is for compilation which must be done on the target architecture. In early versions of node, this was often done using the `node-waf` scripts, or a standalone `Makefile`, and early versions of npm required that it be explicitly set in package.json. This was not portable, and harder to do properly. In the current version of node, the standard way to do this is using a `.gyp` file. If you have a file with a `.gyp` extension in the root of your package, then npm will run the appropriate `node-gyp` commands automatically at install time. This is the only officially supported method for compiling binary addons, and does not require that you add anything to your package.json file. If you have to do other things before your package is used, in a way that is not dependent on the operating system or architecture of the target system, then use a `prepublish` script instead. This includes tasks such as: * Compile CoffeeScript source code into JavaScript. * Create minified versions of JavaScript source code. * Fetching remote resources that your package will use. The advantage of doing these things at `prepublish` time instead of `preinstall` or `install` time is that they can be done once, in a single place, and thus greatly reduce complexity and variability. Additionally, this means that: * You can depend on `coffee-script` as a `devDependency`, and thus your users don't need to have it installed. * You don't need to include the minifiers in your package, reducing the size for your users. * You don't need to rely on your users having `curl` or `wget` or other system tools on the target machines. ## 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. ### path If you depend on modules that define executable scripts, like test suites, then those executables will be added to the `PATH` for executing the scripts. So, if your package.json has this: { "name" : "foo" , "dependencies" : { "bar" : "0.1.x" } , "scripts": { "start" : "bar ./test" } } then you could run `npm start` to execute the `bar` script, which is exported into the `node_modules/.bin` directory on `npm install`. ### 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 `[@]:`. 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 `package.json(5)` 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) * package.json(5) * npm-developers(7) * npm-install(1) v1.3.10.tar.gz~dfsg/doc/misc/npm-developers.md0000644000000000000000000001406112212013731017704 0ustar rootrootnpm-developers(7) -- 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 `@` that is published on the registry with (c) * e) a `@` that points to (d) * f) a `` 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`. ## 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 `package.json(5)` 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(7). * 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. By default, the following paths and files are ignored, so there's no need to add them to `.npmignore` explicitly: * `.*.swp` * `._*` * `.DS_Store` * `.git` * `.hg` * `.lock-wscript` * `.svn` * `.wafpickle-*` * `CVS` * `npm-debug.log` Additionally, everything in `node_modules` is ignored, except for bundled dependencies. npm automatically handles this for you, so don't bother adding `node_modules` to `.npmignore`. The following paths and files are never ignored, so adding them to `.npmignore` is pointless: * `package.json` * `README.*` ## 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 `.npmignore` file to list out the globs to 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(7) * npm(1) * npm-init(1) * package.json(5) * npm-scripts(7) * npm-publish(1) * npm-adduser(1) * npm-registry(7) v1.3.10.tar.gz~dfsg/doc/misc/npm-coding-style.md0000644000000000000000000001204112212013731020131 0ustar rootrootnpm-coding-style(7) -- 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. Note: this concerns npm's code not the specific packages at npmjs.org ## 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. ## Logging Logging is done using the [npmlog](https://github.com/isaacs/npmlog) utility. 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. See `npm-config(7)` 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(7) * npm-faq(7) * npm(1) v1.3.10.tar.gz~dfsg/doc/misc/npm-faq.md0000644000000000000000000003054612212013731016311 0ustar rootrootnpm-faq(7) -- Frequently Asked Questions ======================================== ## Where can I find these docs in HTML? , 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(5)` 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 on my computer in a central location? Install it globally by tacking `-g` or `--global` to the command. (This is especially important for command line utilities that need to add their bins to the global system `PATH`.) ## I installed something globally, but I can't `require()` it Install it locally. The global install location is a place for command-line utilities to put their bins in the system `PATH`. It's not for use with `require()`. If you `require()` a module in your code, then that means it's a dependency, and a part of your program. You need to install it locally in your program. ## Why can't npm just put everything in one place, like other package managers? Not every change is an improvement, but every improvement is a change. This would be like asking git to do network IO for every commit. It's not going to happen, because it's a terrible idea that causes more problems than it solves. It is much harder to avoid dependency conflicts without nesting dependencies. This is fundamental to the way that npm works, and has proven to be an extremely successful approach. See `npm-folders(5)` for more details. If you want a package to be installed in one place, and have all your programs reference the same copy of it, then use the `npm link` command. That's what it's for. Install it globally, then link it into each program that uses it. ## Whatever, I really want the old style 'everything global' style. Write your own package manager, then. It's not that hard. npm will not help you do something that is known to be a bad idea. ## Should I check my `node_modules` folder into git? Mikeal Rogers answered this question very well: tl;dr * Check `node_modules` into git for things you **deploy**, such as websites and apps. * Do not check `node_modules` into git for libraries and modules intended to be reused. * Use npm to manage dependencies in your dev environment, but not in your deployment scripts. ## Is it 'npm' or 'NPM' or 'Npm'? npm should never be capitalized unless it is being displayed in a location that is customarily all-caps (such as the title of man pages.) ## 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 . 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 . 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 https://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 `@` that is published on the registry with (c) * e) a `@` that points to (d) * f) a `` 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`. ## What is a `module`? A module is anything that can be loaded with `require()` in a Node.js program. The following things are all examples of things that can be loaded as modules: * A folder with a `package.json` file containing a `main` field. * A folder with an `index.js` file in it. * A JavaScript file. Most npm packages are modules, because they are libraries that you load with `require`. However, there's no requirement that an npm package be a module! Some only contain an executable command-line interface, and don't provide a `main` field for use in Node programs. Almost all npm packages (at least, those that are Node programs) *contain* many modules within them (because every file they load with `require()` is a module). In the context of a Node program, the `module` is also the thing that was loaded *from* a file. For example, in the following program: var req = require('request') we might say that "The variable `req` refers to the `request` module". ## So, why is it the "`node_modules`" folder, but "`package.json`" file? Why not `node_packages` or `module.json`? The `package.json` file defines the package. (See "What is a package?" above.) The `node_modules` folder is the place Node.js looks for modules. (See "What is a module?" above.) For example, if you create a file at `node_modules/foo.js` and then had a program that did `var f = require('foo.js')` then it would load the module. However, `foo.js` is not a "package" in this case, because it does not have a package.json. Alternatively, if you create a package which does not have an `index.js` or a `"main"` field in the `package.json` file, then it is not a module. Even if it's installed in `node_modules`, it can't be an argument to `require()`. ## `"node_modules"` is the name of my deity's arch-rival, and a Forbidden Word in my religion. Can I configure npm to use a different folder? No. This will never happen. This question comes up sometimes, because it seems silly from the outside that npm couldn't just be configured to put stuff somewhere else, and then npm could load them from there. It's an arbitrary spelling choice, right? What's the big deal? At the time of this writing, the string `'node_modules'` appears 151 times in 53 separate files in npm and node core (excluding tests and documentation). Some of these references are in node's built-in module loader. Since npm is not involved **at all** at run-time, node itself would have to be configured to know where you've decided to stick stuff. Complexity hurdle #1. Since the Node module system is locked, this cannot be changed, and is enough to kill this request. But I'll continue, in deference to your deity's delicate feelings regarding spelling. Many of the others are in dependencies that npm uses, which are not necessarily tightly coupled to npm (in the sense that they do not read npm's configuration files, etc.) Each of these would have to be configured to take the name of the `node_modules` folder as a parameter. Complexity hurdle #2. Furthermore, npm has the ability to "bundle" dependencies by adding the dep names to the `"bundledDependencies"` list in package.json, which causes the folder to be included in the package tarball. What if the author of a module bundles its dependencies, and they use a different spelling for `node_modules`? npm would have to rename the folder at publish time, and then be smart enough to unpack it using your locally configured name. Complexity hurdle #3. Furthermore, what happens when you *change* this name? Fine, it's easy enough the first time, just rename the `node_modules` folders to `./blergyblerp/` or whatever name you choose. But what about when you change it again? npm doesn't currently track any state about past configuration settings, so this would be rather difficult to do properly. It would have to track every previous value for this config, and always accept any of them, or else yesterday's install may be broken tomorrow. Complexity hurdle #5. Never going to happen. The folder is named `node_modules`. It is written indelibly in the Node Way, handed down from the ancient times of Node 0.3. ## How do I install node with npm? You don't. Try one of these node version managers: Unix: * * * Windows: * * ## How can I use npm for development? See `npm-developers(7)` and `package.json(5)`. 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(7)`. ## 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(7)`. ## I forgot my password, and can't publish. How do I reset it? Go to . ## I get ECONNREFUSED a lot. What's up? Either the registry is down, or node's DNS isn't able to reach out. To check if the registry is down, open up in a web browser. This will also tell you if you are just unable to access the internet for some reason. If the registry IS down, let me know by emailing or posting an issue at . We'll have someone kick it or something. ## Why no namespaces? Please see this discussion: tl;dr - It doesn't actually make things better, and can make them worse. If you want to namespace your own packages, you may: simply use the `-` character to separate the names. npm is a mostly anarchic system. There is not sufficient need to impose namespace rules on everyone. ## 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? Post an issue on the github project: * ## Why does npm hate me? npm is not capable of hatred. It loves everyone, especially you. ## SEE ALSO * npm(1) * npm-developers(7) * package.json(5) * npm-config(1) * npm-config(7) * npmrc(5) * npm-config(7) * npm-folders(5) v1.3.10.tar.gz~dfsg/doc/misc/removing-npm.md0000644000000000000000000000313212212013731017357 0ustar rootrootnpm-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) v1.3.10.tar.gz~dfsg/doc/files/0000755000000000000000000000000012212013731014567 5ustar rootrootv1.3.10.tar.gz~dfsg/doc/files/package.json.md0000644000000000000000000004445312212013731017466 0ustar rootrootpackage.json(5) -- 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(7)`. ## 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. * `"scripts":{"preinstall": "node-gyp rebuild"}` If there is a `binding.gyp` file in the root of your package, npm will default the `preinstall` command to compile using node-gyp. * `"contributors": [...]` If there is an `AUTHORS` file in the root of your package, npm will treat each line as a `Name (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.) More on version numbers and ranges at semver(7). ## 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. ## license You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it. The simplest way, assuming you're using a common license such as BSD or MIT, is to just specify the name of the license you're using, like this: { "license" : "BSD" } If you have more complex licensing terms, or you want to provide more detail in your package.json file, you can use the more verbose plural form, like this: "licenses" : [ { "type" : "MyLicense" , "url" : "http://github.com/owner/project/path/to/license" } ] It's also a good idea to include a license file at the top level in your package. ## 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 (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 `, 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(7)` 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(7)` and `npm-scripts(7)` for more on package configs. ## dependencies Dependencies are specified with a simple hash of package name to version range. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or git URL. **Please do not put test harnesses or transpilers in your `dependencies` hash.** See `devDependencies`, below. See semver(7) for more details about specifying version ranges. * `version` Must match `version` exactly * `>version` Must be greater than `version` * `>=version` etc * `=version1 <=version2`. * `range1 || range2` Passes if either range1 or range2 are satisfied. * `git...` See 'Git URLs as Dependencies' below * `user/repo` See 'GitHub URLs' below 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" } } ### URLs as Dependencies 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. ### Git URLs as Dependencies Git urls can be of the form: git://github.com/user/project.git#commit-ish git+ssh://user@hostname: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`. ## GitHub URLs As of version 1.1.65, you can refer to GitHub urls as just "foo": "user/foo-project". For example: ```json { "name": "foo", "version": "0.0.0", "dependencies": { "express": "visionmedia/express" } } ``` ## 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 when doing `npm link` or `npm install` from the root of a package, and can be managed like any other npm configuration param. See `npm-config(7)` for more on the topic. For build steps that are not platform-specific, such as compiling CoffeeScript or other languages to JavaScript, use the `prepublish` script to do this, and make the required package a devDependency. For example: ```json { "name": "ethopia-waza", "description": "a delightfully fruity coffee varietal", "version": "1.2.3", "devDependencies": { "coffee-script": "~1.6.3" }, "scripts": { "prepublish": "coffee -o lib/ -c src/waza.coffee" }, "main": "lib/waza.js" } ``` The `prepublish` script will be run before publishing, so that users can consume the functionality without requiring them to compile it themselves. In dev mode (ie, locally running `npm install`), it'll run this script as well, so that you can test it easily. ## bundledDependencies Array of package names that will be bundled when publishing the package. If this is spelled `"bundleDependencies"`, then that is also honorable. ## optionalDependencies If a dependency can be used, but you would like npm to proceed if it cannot be found or fails to install, then you may put it in the `optionalDependencies` hash. This is a map of package name to version or url, just like the `dependencies` hash. The difference is that failure is tolerated. It is still your program's responsibility to handle the lack of the dependency. For example, something like this: try { var foo = require('foo') var fooVersion = require('foo/package.json').version } catch (er) { foo = null } if ( notGoodFooVersion(fooVersion) ) { foo = null } // .. then later in your program .. if (foo) { foo.doFooThings() } Entries in `optionalDependencies` will override entries of the same name in `dependencies`, so it's usually best to only put in one place. ## engines You can specify the version of node that your stuff works on: { "engines" : { "node" : ">=0.10.3 <0.12" } } 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" } } Note that, unless the user has set the `engine-strict` config flag, this field is advisory only. ## engineStrict If you are sure that your module will *definitely not* run properly on versions of Node/npm other than those specified in the `engines` hash, then you can set `"engineStrict": true` in your package.json file. This will override the user's `engine-strict` config setting. Please do not do this unless you are really very very sure. If your engines hash is something overly restrictive, you can quite easily and inadvertently lock yourself into obscurity and prevent your users from updating to new versions of Node. Consider this choice carefully. If people abuse it, it will be removed in a future version of npm. ## os You can specify which operating systems your module will run on: "os" : [ "darwin", "linux" ] You can also blacklist instead of whitelist operating systems, just prepend the blacklisted os with a '!': "os" : [ "!win32" ] The host operating system is determined by `process.platform` It is allowed to both blacklist, and whitelist, although there isn't any good reason to do this. ## cpu If your code only runs on certain cpu architectures, you can specify which ones. "cpu" : [ "x64", "ia32" ] Like the `os` option, you can also blacklist architectures: "cpu" : [ "!arm", "!mips" ] The host architecture is determined by `process.arch` ## 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 specific 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(7)` to see the list of config options that can be overridden. ## SEE ALSO * semver(7) * npm-init(1) * npm-version(1) * npm-config(1) * npm-config(7) * npm-help(1) * npm-faq(7) * npm-install(1) * npm-publish(1) * npm-rm(1) v1.3.10.tar.gz~dfsg/doc/files/npmrc.md0000644000000000000000000000314412212013731016232 0ustar rootrootnpmrc(5) -- The npm config files ================================ ## DESCRIPTION npm gets its config settings from the command line, environment variables, and `npmrc` files. The `npm config` command can be used to update and edit the contents of the user and global npmrc files. For a list of available configuration options, see npm-config(7). ## FILES The three relevant files are: * per-user config file (~/.npmrc) * global config file ($PREFIX/npmrc) * npm builtin config file (/path/to/npm/npmrc) All npm config files are an ini-formatted list of `key = value` parameters. Environment variables can be replaced using `${VARIABLE_NAME}`. For example: prefix = ${HOME}/.npm-packages Each of these files is loaded, and config options are resolved in priority order. For example, a setting in the userconfig file would override the setting in the globalconfig file. ### Per-user config file `$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on the command line) ### 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. Environment variables can be replaced as above. ### 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. ## SEE ALSO * npm-folders(5) * npm-config(1) * npm-config(7) * package.json(5) * npm(1) v1.3.10.tar.gz~dfsg/doc/files/npm-folders.md0000644000000000000000000001655112212013731017347 0ustar rootrootnpm-folders(5) -- 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 satisfies 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 `package.json(5)` for more information. ## SEE ALSO * npm-faq(7) * package.json(5) * npm-install(1) * npm-pack(1) * npm-cache(1) * npm-config(1) * npmrc(5) * npm-config(7) * npm-publish(1) v1.3.10.tar.gz~dfsg/doc/api/0000755000000000000000000000000012212013731014236 5ustar rootrootv1.3.10.tar.gz~dfsg/doc/api/npm-pack.md0000644000000000000000000000116712212013731016273 0ustar rootrootnpm-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 `-.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. v1.3.10.tar.gz~dfsg/doc/api/npm-install.md0000644000000000000000000000116212212013731017016 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-owner.md0000644000000000000000000000175712212013731016514 0ustar rootrootnpm-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(7) v1.3.10.tar.gz~dfsg/doc/api/npm-commands.md0000644000000000000000000000114612212013731017153 0ustar rootrootnpm-commands(3) -- npm commands =============================== ## SYNOPSIS npm.commands[](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-` for command-line usage, or `man 3 npm-` for programmatic usage. ## SEE ALSO * npm-index(7) v1.3.10.tar.gz~dfsg/doc/api/npm-update.md0000644000000000000000000000056212212013731016635 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-version.md0000644000000000000000000000112112212013731017030 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-stop.md0000644000000000000000000000044312212013731016336 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-submodule.md0000644000000000000000000000166112212013731017353 0ustar rootrootnpm-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/`. 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 -- npm install` to install the dependencies into the submodule folder. ## SEE ALSO * npm help json * git help submodule v1.3.10.tar.gz~dfsg/doc/api/npm-view.md0000644000000000000000000000635012212013731016326 0ustar rootrootnpm-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: { : { : , ... } , ... } corresponding to the list of fields selected. v1.3.10.tar.gz~dfsg/doc/api/npm-outdated.md0000644000000000000000000000052212212013731017160 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-start.md0000644000000000000000000000045212212013731016506 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-publish.md0000644000000000000000000000137212212013731017021 0ustar rootrootnpm-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: * ``: A folder containing a package.json file * ``: 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(7) * npm-adduser(1) * npm-owner(3) v1.3.10.tar.gz~dfsg/doc/api/npm-load.md0000644000000000000000000000126212212013731016270 0ustar rootrootnpm-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` v1.3.10.tar.gz~dfsg/doc/api/npm-help-search.md0000644000000000000000000000165412212013731017551 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/repo.md0000644000000000000000000000113512212013731015525 0ustar rootrootnpm-repo(3) -- Open package repository page in the browser ======================================================== ## SYNOPSIS npm.commands.repo(package, callback) ## DESCRIPTION This command tries to guess at the likely location of a package's repository 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. v1.3.10.tar.gz~dfsg/doc/api/npm-edit.md0000644000000000000000000000146412212013731016302 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-root.md0000644000000000000000000000053212212013731016333 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-init.md0000644000000000000000000000176212212013731016321 0ustar rootrootnpm 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 package.json(5) v1.3.10.tar.gz~dfsg/doc/api/npm-config.md0000644000000000000000000000224212212013731016615 0ustar rootrootnpm-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) v1.3.10.tar.gz~dfsg/doc/api/npm-prune.md0000644000000000000000000000067112212013731016505 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-test.md0000644000000000000000000000056312212013731016333 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-unpublish.md0000644000000000000000000000115712212013731017365 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-explore.md0000644000000000000000000000123512212013731017027 0ustar rootrootnpm-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 ` 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. v1.3.10.tar.gz~dfsg/doc/api/npm-prefix.md0000644000000000000000000000050212212013731016642 0ustar rootrootnpm-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 v1.3.10.tar.gz~dfsg/doc/api/npm-shrinkwrap.md0000644000000000000000000000124712212013731017544 0ustar rootrootnpm-shrinkwrap(3) -- programmatically generate package shrinkwrap file ==================================================== ## SYNOPSIS npm.commands.shrinkwrap(args, [silent,] callback) ## DESCRIPTION This acts much the same ways as shrinkwrapping on the command-line. 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. If the 'silent' parameter is set to true, nothing will be output to the screen, but the shrinkwrap file will still be written. Finally, 'callback' is a function that will be called when the shrinkwrap has been saved. v1.3.10.tar.gz~dfsg/doc/api/npm-ls.md0000644000000000000000000000313312212013731015766 0ustar rootrootnpm-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. Callback is provided an error if one occurred, the full data about which packages are installed and which dependencies they will receive, and a "lite" data object which just shows which versions are installed where. Note that the full data object is a circular structure, so care must be taken if it is serialized to JSON. ## 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. v1.3.10.tar.gz~dfsg/doc/api/npm-rebuild.md0000644000000000000000000000070312212013731016776 0ustar rootrootnpm-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` v1.3.10.tar.gz~dfsg/doc/api/npm.md0000644000000000000000000000635212212013731015360 0ustar rootrootnpm(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. If you provide `configObject` as an object hash of top-level configs, they override the values stored in the various config locations. 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)`, `npm-config(7)`, and `npmrc(5)` for more information. After that, each of the functions are accessible in the commands object: `npm.commands.`. See `npm-index(7)` 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" v1.3.10.tar.gz~dfsg/doc/api/npm-restart.md0000644000000000000000000000077612212013731017046 0ustar rootrootnpm-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) v1.3.10.tar.gz~dfsg/doc/api/npm-run-script.md0000644000000000000000000000144012212013731017455 0ustar rootrootnpm-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(7) * npm-test(3) * npm-start(3) * npm-restart(3) * npm-stop(3) v1.3.10.tar.gz~dfsg/doc/api/npm-uninstall.md0000644000000000000000000000100012212013731017350 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-tag.md0000644000000000000000000000147212212013731016127 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-search.md0000644000000000000000000000235412212013731016621 0ustar rootrootnpm-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). v1.3.10.tar.gz~dfsg/doc/api/npm-bugs.md0000644000000000000000000000113412212013731016307 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-deprecate.md0000644000000000000000000000154212212013731017306 0ustar rootrootnpm-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. To un-deprecate a package, specify an empty string (`""`) for the `message` argument. ## SEE ALSO * npm-publish(3) * npm-unpublish(3) * npm-registry(7) v1.3.10.tar.gz~dfsg/doc/api/npm-whoami.md0000644000000000000000000000053412212013731016636 0ustar rootrootnpm-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 v1.3.10.tar.gz~dfsg/doc/api/npm-bin.md0000644000000000000000000000043712212013731016124 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/api/npm-link.md0000644000000000000000000000201512212013731016303 0ustar rootrootnpm-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 v1.3.10.tar.gz~dfsg/doc/api/npm-docs.md0000644000000000000000000000113612212013731016301 0ustar rootrootnpm-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. v1.3.10.tar.gz~dfsg/doc/cli/0000755000000000000000000000000012212013731014234 5ustar rootrootv1.3.10.tar.gz~dfsg/doc/cli/npm-pack.md0000644000000000000000000000130512212013731016263 0ustar rootrootnpm-pack(1) -- Create a tarball from a package ============================================== ## SYNOPSIS npm pack [ [ ...]] ## 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 `-.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) * npm-config(7) * npmrc(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-rm.md0000644000000000000000000000055212212013731015766 0ustar rootrootnpm-rm(1) -- Remove a package ============================= ## SYNOPSIS npm rm npm r npm uninstall npm un ## DESCRIPTION This uninstalls a package, completely removing everything npm installed on its behalf. ## SEE ALSO * npm-prune(1) * npm-install(1) * npm-folders(5) * npm-config(1) * npm-config(7) * npmrc(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-install.md0000644000000000000000000001670212212013731017022 0ustar rootrootnpm-install(1) -- Install a package =================================== ## SYNOPSIS npm install (with no args in a package dir) npm install npm install npm install npm install [--save|--save-dev|--save-optional] npm install @ npm install @ npm install @ npm i (with any of the previous argument usage) ## DESCRIPTION This command installs a package, and any packages that it depends on. If the package has a shrinkwrap file, the installation of dependencies will be driven by that. See npm-shrinkwrap(1). 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 `@` that is published on the registry with (c) * e) a `@` that points to (d) * f) a `` that has a "latest" tag satisfying (e) * g) a `` 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 `: Install a package that is sitting in a folder on the filesystem. * `npm install `: 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 `: 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 [--save|--save-dev|--save-optional]`: Do a `@` install, where `` is the "tag" config. (See `npm-config(7)`.) In most cases, this will install the latest version of the module published on npm. Example: npm install sax `npm install` takes 3 exclusive, optional flags which save or update the package version in your main package.json: * `--save`: Package will appear in your `dependencies`. * `--save-dev`: Package will appear in your `devDependencies`. * `--save-optional`: Package will appear in your `optionalDependencies`. Examples: npm install sax --save npm install node-tap --save-dev npm install dtrace-provider --save-optional **Note**: If there is a file or folder named `` 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 @`: 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 @`: 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 @`: Install a version of the package matching the specified version range. This will follow the same rules for resolving dependencies described in `package.json(5)`. 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 `: Install a package by cloning a git remote url. The format of the git url is: ://[@][#] `` is one of `git`, `git+ssh`, `git+http`, or `git+https`. If no `` 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-folders(5)`. The `--link` argument will cause npm to link global installs into the local space in some cases. The `--no-bin-links` argument will prevent npm from creating symlinks for any binaries the package might contain. The `--no-shrinkwrap` argument, which will ignore an available shrinkwrap file and use the package.json instead. The `--nodedir=/path/to/node/source` argument will allow npm to find the node source code so that npm can compile native modules. See `npm-config(7)`. 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 /node_modules/ for each dep in what.dependencies resolve dep to precise version for each dep@version in what.dependencies not in /node_modules//node_modules/* and not in add precise version deps to install(/node_modules/, 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(5) 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(5) * npm-update(1) * npm-link(1) * npm-rebuild(1) * npm-scripts(7) * npm-build(1) * npm-config(1) * npm-config(7) * npmrc(5) * npm-registry(7) * npm-folders(5) * npm-tag(1) * npm-rm(1) * npm-shrinkwrap(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-owner.md0000644000000000000000000000162512212013731016504 0ustar rootrootnpm-owner(1) -- Manage package owners ===================================== ## SYNOPSIS npm owner ls npm owner add npm owner rm ## 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(7) * npm-adduser(1) * npm-disputes(7) v1.3.10.tar.gz~dfsg/doc/cli/npm-update.md0000644000000000000000000000107612212013731016634 0ustar rootrootnpm-update(1) -- Update a package ================================= ## SYNOPSIS npm update [-g] [ [ ...]] ## DESCRIPTION This command will update all the packages listed to the latest version (specified by the `tag` config). It will also install missing packages. If the `-g` flag is specified, this command will update globally installed packages. If no package name is specified, all packages in the specified location (global or local) will be updated. ## SEE ALSO * npm-install(1) * npm-outdated(1) * npm-registry(7) * npm-folders(5) * npm-ls(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-version.md0000644000000000000000000000263612212013731017042 0ustar rootrootnpm-version(1) -- Bump a package version ======================================== ## SYNOPSIS npm version [ | major | minor | patch | build] ## 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 "build", "patch", "minor", or "major"). In the second case, the existing version will be incremented by 1 in the specified field. 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`) config option, npm will use it as a commit message when creating a version commit. If the `message` config contains `%s` then that will be replaced with the resulting version number. For example: npm version patch -m "Upgrade to %s for reasons" If the `sign-git-tag` config is set, then the tag will be signed using the `-s` flag to git. Note that you must have a default GPG key set up in your git config for this to work properly. For example: $ npm config set sign-git-tag true $ npm version patch You need a passphrase to unlock the secret key for user: "isaacs (http://blog.izs.me/) " 2048-bit RSA key, ID 6C481CF6, created 2010-08-31 Enter passphrase: ## SEE ALSO * npm-init(1) * package.json(5) * semver(7) v1.3.10.tar.gz~dfsg/doc/cli/npm-stop.md0000644000000000000000000000041212212013731016330 0ustar rootrootnpm-stop(1) -- Stop a package ============================= ## SYNOPSIS npm stop ## DESCRIPTION This runs a package's "stop" script, if one was provided. ## SEE ALSO * npm-run-script(1) * npm-scripts(7) * npm-test(1) * npm-start(1) * npm-restart(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-submodule.md0000644000000000000000000000162712212013731017353 0ustar rootrootnpm-submodule(1) -- Add a package as a git submodule ==================================================== ## SYNOPSIS npm submodule ## 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/`. 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 -- npm install` to install the dependencies into the submodule folder. ## SEE ALSO * package.json(5) * git help submodule v1.3.10.tar.gz~dfsg/doc/cli/npm-view.md0000644000000000000000000000554512212013731016331 0ustar rootrootnpm-view(1) -- View registry info ================================= ## SYNOPSIS npm view [@] [[.]...] npm v [@] [[.]...] ## 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 `package.json(5)` 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 field is an object, it will be output as a JavaScript object literal. If the --json flag is given, the outputted fields will be JSON. 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(7) * npm-config(1) * npm-config(7) * npmrc(5) * npm-docs(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-outdated.md0000644000000000000000000000052212212013731017156 0ustar rootrootnpm-outdated(1) -- Check for outdated packages ============================================== ## SYNOPSIS npm outdated [ [ ...]] ## 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(7) * npm-folders(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-start.md0000644000000000000000000000041712212013731016505 0ustar rootrootnpm-start(1) -- Start a package =============================== ## SYNOPSIS npm start ## DESCRIPTION This runs a package's "start" script, if one was provided. ## SEE ALSO * npm-run-script(1) * npm-scripts(7) * npm-test(1) * npm-restart(1) * npm-stop(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-publish.md0000644000000000000000000000117012212013731017013 0ustar rootrootnpm-publish(1) -- Publish a package =================================== ## SYNOPSIS npm publish npm publish ## DESCRIPTION Publishes a package to the registry so that it can be installed by name. * ``: A folder containing a package.json file * ``: 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(7) * npm-adduser(1) * npm-owner(1) * npm-deprecate(1) * npm-tag(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-help-search.md0000644000000000000000000000147612212013731017551 0ustar rootrootnpm-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(7) * npm-help(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-completion.md0000644000000000000000000000134512212013731017522 0ustar rootrootnpm-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(7) * npm-faq(7) * npm(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-cache.md0000644000000000000000000000367112212013731016420 0ustar rootrootnpm-cache(1) -- Manipulates packages cache ========================================== ## SYNOPSIS npm cache add npm cache add npm cache add npm cache add @ npm cache ls [] npm cache clean [] ## 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(5) * npm-config(1) * npm-config(7) * npmrc(5) * npm-install(1) * npm-publish(1) * npm-pack(1) v1.3.10.tar.gz~dfsg/doc/cli/repo.md0000644000000000000000000000104112212013731015517 0ustar rootrootnpm-repo(1) -- Open package repository page in the browser ======================================================== ## SYNOPSIS npm repo ## DESCRIPTION This command tries to guess at the likely location of a package's repository URL, and then tries to open it using the `--browser` config param. ## CONFIGURATION ### browser * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` * Type: String The browser that is called by the `npm repo` command to open websites. ## SEE ALSO * npm-docs(1) * npm-config(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-edit.md0000644000000000000000000000152312212013731016274 0ustar rootrootnpm-edit(1) -- Edit an installed package ======================================== ## SYNOPSIS npm edit [@] ## DESCRIPTION Opens the package folder in the default editor (or whatever you've configured as the npm `editor` config -- see `npm-config(7)`.) 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(5) * npm-explore(1) * npm-install(1) * npm-config(1) * npm-config(7) * npmrc(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-root.md0000644000000000000000000000041612212013731016332 0ustar rootrootnpm-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(5) * npm-config(1) * npm-config(7) * npmrc(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-init.md0000644000000000000000000000127712212013731016320 0ustar rootrootnpm-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 * * package.json(5) * npm-version(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-config.md0000644000000000000000000000247612212013731016624 0ustar rootrootnpm-config(1) -- Manage the npm configuration files =================================================== ## SYNOPSIS npm config set [--global] npm config get npm config delete npm config list npm config edit npm c [set|get|delete|list] npm get npm set [--global] ## DESCRIPTION npm gets its config settings from the command line, environment variables, `npmrc` files, and in some cases, the `package.json` file. See npmrc(5) for more information about the npmrc files. See `npm-config(7)` for a more thorough discussion of the mechanisms involved. The `npm config` command can be used to update and edit the contents of the user and global npmrc files. ## 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. ## SEE ALSO * npm-folders(5) * npm-config(7) * package.json(5) * npmrc(5) * npm(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-build.md0000644000000000000000000000062012212013731016443 0ustar rootrootnpm-build(1) -- Build a package =============================== ## SYNOPSIS npm build * ``: 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(7) * package.json(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-help.md0000644000000000000000000000152112212013731016275 0ustar rootrootnpm-help(1) -- Get help on npm ============================== ## SYNOPSIS npm help 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(7) * npm-folders(5) * npm-config(1) * npm-config(7) * npmrc(5) * package.json(5) * npm-help-search(1) * npm-index(7) v1.3.10.tar.gz~dfsg/doc/cli/npm-prune.md0000644000000000000000000000067712212013731016511 0ustar rootrootnpm-prune(1) -- Remove extraneous packages ========================================== ## SYNOPSIS npm prune [ [` 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 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(7) * npm-config(1) * npm-config(7) * npmrc(5) * npm-owner(1) * npm-whoami(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-test.md0000644000000000000000000000055612212013731016333 0ustar rootrootnpm-test(1) -- Test a package ============================= ## SYNOPSIS npm test npm tst ## 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(7) * npm-start(1) * npm-restart(1) * npm-stop(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-unpublish.md0000644000000000000000000000136712212013731017366 0ustar rootrootnpm-unpublish(1) -- Remove a package from the registry ====================================================== ## SYNOPSIS npm unpublish [@] ## 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(7) * npm-adduser(1) * npm-owner(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-explore.md0000644000000000000000000000160112212013731017022 0ustar rootrootnpm-explore(1) -- Browse an installed package ============================================= ## SYNOPSIS npm explore [@] [ -- ] ## 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 ` 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(5) * npm-edit(1) * npm-rebuild(1) * npm-build(1) * npm-install(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-prefix.md0000644000000000000000000000036512212013731016647 0ustar rootrootnpm-prefix(1) -- Display prefix =============================== ## SYNOPSIS npm prefix ## DESCRIPTION Print the prefix to standard out. ## SEE ALSO * npm-root(1) * npm-bin(1) * npm-folders(5) * npm-config(1) * npm-config(7) * npmrc(5) v1.3.10.tar.gz~dfsg/doc/cli/npm-shrinkwrap.md0000644000000000000000000001450012212013731017536 0ustar rootrootnpm-shrinkwrap(1) -- Lock down dependency versions ===================================================== ## SYNOPSIS npm shrinkwrap ## DESCRIPTION This command locks down the versions of a package's dependencies so that you can control exactly which versions of each dependency will be used when your package is installed. The "package.json" file is still required if you want to use "npm install". By default, "npm install" recursively installs the target's dependencies (as specified in package.json), choosing the latest available version that satisfies the dependency's semver pattern. In some situations, particularly when shipping software where each change is tightly managed, it's desirable to fully specify each version of each dependency recursively so that subsequent builds and deploys do not inadvertently pick up newer versions of a dependency that satisfy the semver pattern. Specifying specific semver patterns in each dependency's package.json would facilitate this, but that's not always possible or desirable, as when another author owns the npm package. It's also possible to check dependencies directly into source control, but that may be undesirable for other reasons. As an example, consider package A: { "name": "A", "version": "0.1.0", "dependencies": { "B": "<0.1.0" } } package B: { "name": "B", "version": "0.0.1", "dependencies": { "C": "<0.1.0" } } and package C: { "name": "C, "version": "0.0.1" } If these are the only versions of A, B, and C available in the registry, then a normal "npm install A" will install: A@0.1.0 `-- B@0.0.1 `-- C@0.0.1 However, if B@0.0.2 is published, then a fresh "npm install A" will install: A@0.1.0 `-- B@0.0.2 `-- C@0.0.1 assuming the new version did not modify B's dependencies. Of course, the new version of B could include a new version of C and any number of new dependencies. If such changes are undesirable, the author of A could specify a dependency on B@0.0.1. However, if A's author and B's author are not the same person, there's no way for A's author to say that he or she does not want to pull in newly published versions of C when B hasn't changed at all. In this case, A's author can run npm shrinkwrap This generates npm-shrinkwrap.json, which will look something like this: { "name": "A", "version": "0.1.0", "dependencies": { "B": { "version": "0.0.1", "dependencies": { "C": { "version": "0.1.0" } } } } } The shrinkwrap command has locked down the dependencies based on what's currently installed in node_modules. When "npm install" installs a package with a npm-shrinkwrap.json file in the package root, the shrinkwrap file (rather than package.json files) completely drives the installation of that package and all of its dependencies (recursively). So now the author publishes A@0.1.0, and subsequent installs of this package will use B@0.0.1 and C@0.1.0, regardless the dependencies and versions listed in A's, B's, and C's package.json files. ### Using shrinkwrapped packages Using a shrinkwrapped package is no different than using any other package: you can "npm install" it by hand, or add a dependency to your package.json file and "npm install" it. ### Building shrinkwrapped packages To shrinkwrap an existing package: 1. Run "npm install" in the package root to install the current versions of all dependencies. 2. Validate that the package works as expected with these versions. 3. Run "npm shrinkwrap", add npm-shrinkwrap.json to git, and publish your package. To add or update a dependency in a shrinkwrapped package: 1. Run "npm install" in the package root to install the current versions of all dependencies. 2. Add or update dependencies. "npm install" each new or updated package individually and then update package.json. Note that they must be explicitly named in order to be installed: running `npm install` with no arguments will merely reproduce the existing shrinkwrap. 3. Validate that the package works as expected with the new dependencies. 4. Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and publish your package. You can use npm-outdated(1) to view dependencies with newer versions available. ### Other Notes A shrinkwrap file must be consistent with the package's package.json file. "npm shrinkwrap" will fail if required dependencies are not already installed, since that would result in a shrinkwrap that wouldn't actually work. Similarly, the command will fail if there are extraneous packages (not referenced by package.json), since that would indicate that package.json is not correct. Since "npm shrinkwrap" is intended to lock down your dependencies for production use, `devDependencies` will not be included unless you explicitly set the `--dev` flag when you run `npm shrinkwrap`. If installed `devDependencies` are excluded, then npm will print a warning. If you want them to be installed with your module by default, please consider adding them to `dependencies` instead. If shrinkwrapped package A depends on shrinkwrapped package B, B's shrinkwrap will not be used as part of the installation of A. However, because A's shrinkwrap is constructed from a valid installation of B and recursively specifies all dependencies, the contents of B's shrinkwrap will implicitly be included in A's shrinkwrap. ### Caveats Shrinkwrap files only lock down package versions, not actual package contents. While discouraged, a package author can republish an existing version of a package, causing shrinkwrapped packages using that version to pick up different code than they were before. If you want to avoid any risk that a byzantine author replaces a package you're using with code that breaks your application, you could modify the shrinkwrap file to use git URL references rather than version numbers so that npm always fetches all packages from git. If you wish to lock down the specific bytes included in a package, for example to have 100% confidence in being able to reproduce a deployment or build, then you ought to check your dependencies into source control, or pursue some other mechanism that can verify contents rather than versions. ## SEE ALSO * npm-install(1) * package.json(5) * npm-ls(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-ls.md0000644000000000000000000000303612212013731015766 0ustar rootrootnpm-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. Positional arguments are `name@version-range` identifiers, which will limit the results to only the paths to the packages named. Note that nested packages will *also* show the paths to the specified packages. For example, running `npm ls promzard` in npm's source tree will show: npm@@VERSION@ /path/to/npm └─┬ init-package-json@0.0.4 └── promzard@0.1.5 It will print out extraneous, missing, and invalid packages. If a project specifies git urls for dependencies these are shown in parentheses after the name@version to make it easier for users to recognize potential forks of a project. When run as `ll` or `la`, it shows extended information by default. ## CONFIGURATION ### json * Default: false * Type: Boolean Show information in JSON format. ### 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-config(7) * npmrc(5) * npm-folders(5) * npm-install(1) * npm-link(1) * npm-prune(1) * npm-outdated(1) * npm-update(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-rebuild.md0000644000000000000000000000067012212013731016777 0ustar rootrootnpm-rebuild(1) -- Rebuild a package =================================== ## SYNOPSIS npm rebuild [ [ ...]] npm rb [ [ ...]] * ``: 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) v1.3.10.tar.gz~dfsg/doc/cli/npm-bundle.md0000644000000000000000000000052312212013731016617 0ustar rootrootnpm-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) v1.3.10.tar.gz~dfsg/doc/cli/npm.md0000644000000000000000000001105412212013731015351 0ustar rootrootnpm(1) -- node package manager ============================== ## SYNOPSIS npm [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(5)` 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 `package.json(5)`. * 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. Credentials 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(7)` for much much more information. ## CONTRIBUTIONS Patches welcome! * code: Read through `npm-coding-style(7)` 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. * * ## BUGS When you find issues, please report them: * web: * email: 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) :: ## SEE ALSO * npm-help(1) * npm-faq(7) * README * package.json(5) * npm-install(1) * npm-config(1) * npm-config(7) * npmrc(5) * npm-index(7) * npm(3) v1.3.10.tar.gz~dfsg/doc/cli/npm-restart.md0000644000000000000000000000066612212013731017042 0ustar rootrootnpm-restart(1) -- Start a package ================================= ## SYNOPSIS npm restart ## 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(7) * npm-test(1) * npm-start(1) * npm-stop(1) v1.3.10.tar.gz~dfsg/doc/cli/npm-run-script.md0000644000000000000000000000064612212013731017462 0ustar rootrootnpm-run-script(1) -- Run arbitrary package scripts ================================================== ## SYNOPSIS npm run-script v1.3.10.tar.gz~dfsg/.gitignore0000644000000000000000000000062012212013731014706 0ustar rootroot*.swp npm-debug.log /test/bin /test/output.log /test/*/*/node_modules /test/packages/npm-test-depends-on-spark/which-spark.log /test/packages/test-package/random-data.txt /test/root /node_modules/ronn /node_modules/tap /node_modules/.bin /node_modules/npm-registry-mock /html/api/ /html/doc/ /man/ /doc/*/npm-index.md /npmrc /release/ /npm-*.tgz /node_modules/npm-registry-client/test/fixtures *.pyc v1.3.10.tar.gz~dfsg/scripts/0000755000000000000000000000000012212013731014407 5ustar rootrootv1.3.10.tar.gz~dfsg/scripts/install.sh0000755000000000000000000001731212212013731016420 0ustar rootroot#!/bin/sh # A word about this shell script: # # It must work everywhere, including on systems that lack # a /bin/bash, map 'sh' to ksh, ksh97, bash, ash, or zsh, # and potentially have either a posix shell or bourne # shell living at /bin/sh. # # See this helpful document on writing portable shell scripts: # http://www.gnu.org/s/hello/manual/autoconf/Portable-Shell.html # # The only shell it won't ever work on is cmd.exe. if [ "x$0" = "xsh" ]; then # run as curl | sh # on some systems, you can just do cat>npm-install.sh # which is a bit cuter. But on others, &1 is already closed, # so catting to another script file won't do anything. curl -s https://npmjs.org/install.sh > npm-install-$$.sh sh npm-install-$$.sh ret=$? rm npm-install-$$.sh exit $ret fi # See what "npm_config_*" things there are in the env, # and make them permanent. # If this fails, it's not such a big deal. configures="`env | grep 'npm_config_' | sed -e 's|^npm_config_||g'`" npm_config_loglevel="error" if [ "x$npm_debug" = "x" ]; then (exit 0) else echo "Running in debug mode." echo "Note that this requires bash or zsh." set -o xtrace set -o pipefail npm_config_loglevel="verbose" fi export npm_config_loglevel # make sure that node exists node=`which node 2>&1` ret=$? if [ $ret -eq 0 ] && [ -x "$node" ]; then (exit 0) else echo "npm cannot be installed without nodejs." >&2 echo "Install node first, and then try again." >&2 echo "" >&2 echo "Maybe node is installed, but not in the PATH?" >&2 echo "Note that running as sudo can change envs." >&2 echo "" echo "PATH=$PATH" >&2 exit $ret fi # set the temp dir TMP="${TMPDIR}" if [ "x$TMP" = "x" ]; then TMP="/tmp" fi TMP="${TMP}/npm.$$" rm -rf "$TMP" || true mkdir "$TMP" if [ $? -ne 0 ]; then echo "failed to mkdir $TMP" >&2 exit 1 fi BACK="$PWD" ret=0 tar="${TAR}" if [ -z "$tar" ]; then tar="${npm_config_tar}" fi if [ -z "$tar" ]; then tar=`which tar 2>&1` ret=$? fi if [ $ret -eq 0 ] && [ -x "$tar" ]; then echo "tar=$tar" echo "version:" $tar --version ret=$? fi if [ $ret -eq 0 ]; then (exit 0) else echo "No suitable tar program found." exit 1 fi # Try to find a suitable make # If the MAKE environment var is set, use that. # otherwise, try to find gmake, and then make. # If no make is found, then just execute the necessary commands. # XXX For some reason, make is building all the docs every time. This # is an annoying source of bugs. Figure out why this happens. MAKE=NOMAKE if [ "x$MAKE" = "x" ]; then make=`which gmake 2>&1` if [ $? -eq 0 ] && [ -x $make ]; then (exit 0) else make=`which make 2>&1` if [ $? -eq 0 ] && [ -x $make ]; then (exit 0) else make=NOMAKE fi fi else make="$MAKE" fi if [ -x "$make" ]; then (exit 0) else # echo "Installing without make. This may fail." >&2 make=NOMAKE fi # If there's no bash, then don't even try to clean if [ -x "/bin/bash" ]; then (exit 0) else clean="no" fi node_version=`"$node" --version 2>&1` ret=$? if [ $ret -ne 0 ]; then echo "You need node to run this program." >&2 echo "node --version reports: $node_version" >&2 echo "with exit code = $ret" >&2 echo "Please install node before continuing." >&2 exit $ret fi t="${npm_install}" if [ -z "$t" ]; then # switch based on node version. # note that we can only use strict sh-compatible patterns here. case $node_version in 0.[0123].* | v0.[0123].*) echo "You are using an outdated and unsupported version of" >&2 echo "node ($node_version). Please update node and try again." >&2 exit 99 ;; v0.[45].* | 0.[45].*) echo "install npm@1.0" t=1.0 ;; v0.[678].* | 0.[678].*) echo "install npm@1.1" t=1.1 ;; *) echo "install npm@latest" t="latest" ;; esac fi # the npmca cert cacert=' -----BEGIN CERTIFICATE----- MIIChzCCAfACCQDauvz/KHp8ejANBgkqhkiG9w0BAQUFADCBhzELMAkGA1UEBhMC VVMxCzAJBgNVBAgTAkNBMRAwDgYDVQQHEwdPYWtsYW5kMQwwCgYDVQQKEwNucG0x IjAgBgNVBAsTGW5wbSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkxDjAMBgNVBAMTBW5w bUNBMRcwFQYJKoZIhvcNAQkBFghpQGl6cy5tZTAeFw0xMTA5MDUwMTQ3MTdaFw0y MTA5MDIwMTQ3MTdaMIGHMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExEDAOBgNV BAcTB09ha2xhbmQxDDAKBgNVBAoTA25wbTEiMCAGA1UECxMZbnBtIENlcnRpZmlj YXRlIEF1dGhvcml0eTEOMAwGA1UEAxMFbnBtQ0ExFzAVBgkqhkiG9w0BCQEWCGlA aXpzLm1lMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDLI4tIqPpRW+ACw9GE OgBlJZwK5f8nnKCLK629Pv5yJpQKs3DENExAyOgDcyaF0HD0zk8zTp+ZsLaNdKOz Gn2U181KGprGKAXP6DU6ByOJDWmTlY6+Ad1laYT0m64fERSpHw/hjD3D+iX4aMOl y0HdbT5m1ZGh6SJz3ZqxavhHLQIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAC4ySDbC l7W1WpLmtLGEQ/yuMLUf6Jy/vr+CRp4h+UzL+IQpCv8FfxsYE7dhf/bmWTEupBkv yNL18lipt2jSvR3v6oAHAReotvdjqhxddpe5Holns6EQd1/xEZ7sB1YhQKJtvUrl ZNufy1Jf1r0ldEGeA+0ISck7s+xSh9rQD2Op -----END CERTIFICATE----- ' echo "$cacert" > "$TMP/cafile.crt" cacert="$TMP/cafile.crt" # need to echo "" after, because Posix sed doesn't treat EOF # as an implied end of line. url=`(curl -SsL --cacert "$cacert" https://registry.npmjs.org/npm/$t; echo "") \ | sed -e 's/^.*tarball":"//' \ | sed -e 's/".*$//'` ret=$? if [ "x$url" = "x" ]; then ret=125 # try without the -e arg to sed. url=`(curl -SsL --cacert "$cacert" https://registry.npmjs.org/npm/$t; echo "") \ | sed 's/^.*tarball":"//' \ | sed 's/".*$//'` ret=$? if [ "x$url" = "x" ]; then ret=125 fi fi if [ $ret -ne 0 ]; then echo "Failed to get tarball url for npm/$t" >&2 exit $ret fi echo "fetching: $url" >&2 cd "$TMP" \ && curl -SsL --cacert "$cacert" "$url" \ | $tar -xzf - \ && rm "$cacert" \ && cd "$TMP"/* \ && (req=`"$node" bin/read-package-json.js package.json engines.node` if [ -d node_modules ]; then "$node" node_modules/semver/bin/semver -v "$node_version" -r "$req" ret=$? else "$node" bin/semver.js -v "$node_version" -r "$req" ret=$? fi if [ $ret -ne 0 ]; then echo "You need node $req to run this program." >&2 echo "node --version reports: $node_version" >&2 echo "Please upgrade node before continuing." >&2 exit $ret fi) \ && (ver=`"$node" bin/read-package-json.js package.json version` isnpm10=0 if [ $ret -eq 0 ]; then req=`"$node" bin/read-package-json.js package.json engines.node` if [ -d node_modules ]; then if "$node" node_modules/semver/bin/semver -v "$ver" -r "1" then isnpm10=1 fi else if "$node" bin/semver -v "$ver" -r ">=1.0"; then isnpm10=1 fi fi fi ret=0 if [ $isnpm10 -eq 1 ] && [ -f "scripts/clean-old.sh" ]; then if [ "x$skipclean" = "x" ]; then (exit 0) else clean=no fi if [ "x$clean" = "xno" ] \ || [ "x$clean" = "xn" ]; then echo "Skipping 0.x cruft clean" >&2 ret=0 elif [ "x$clean" = "xy" ] || [ "x$clean" = "xyes" ]; then NODE="$node" /bin/bash "scripts/clean-old.sh" "-y" ret=$? else NODE="$node" /bin/bash "scripts/clean-old.sh" &2 exit $ret fi) \ && (if [ "x$configures" = "x" ]; then (exit 0) else echo "./configure "$configures echo "$configures" > npmrc fi) \ && (if [ "$make" = "NOMAKE" ]; then (exit 0) elif "$make" uninstall install; then (exit 0) else make="NOMAKE" fi if [ "$make" = "NOMAKE" ]; then "$node" cli.js rm npm -gf "$node" cli.js install -gf fi) \ && cd "$BACK" \ && rm -rf "$TMP" \ && echo "It worked" ret=$? if [ $ret -ne 0 ]; then echo "It failed" >&2 fi exit $ret v1.3.10.tar.gz~dfsg/scripts/doc-build.sh0000755000000000000000000000470512212013731016616 0ustar rootroot#!/usr/bin/env bash if [[ $DEBUG != "" ]]; then set -x fi set -o errexit set -o pipefail if ! [ -x node_modules/.bin/ronn ]; then ps=0 if [ -f .building_ronn ]; then pid=$(cat .building_ronn) ps=$(ps -p $pid | grep $pid | wc -l) || true fi if [ -f .building_ronn ] && [ $ps != 0 ]; then while [ -f .building_ronn ]; do sleep 1 done else # a race to see which make process will be the one to install ronn echo $$ > .building_ronn sleep 1 if [ $(cat .building_ronn) == $$ ]; then make node_modules/.bin/ronn rm .building_ronn else while [ -f .building_ronn ]; do sleep 1 done fi fi fi src=$1 dest=$2 name=$(basename ${src%.*}) date=$(date -u +'%Y-%M-%d %H:%m:%S') version=$(node cli.js -v) mkdir -p $(dirname $dest) case $dest in *.[1357]) ./node_modules/.bin/ronn --roff $src \ | sed "s|@VERSION@|$version|g" \ | perl -pi -e 's/(npm\\-)?([^\(]*)\(1\)/npm help \2/g' \ | perl -pi -e 's/(npm\\-)?([^\(]*)\([57]\)/npm help \3 \2/g' \ | perl -pi -e 's/(npm\\-)?([^\(]*)\(3\)/npm apihelp \2/g' \ | perl -pi -e 's/npm\(1\)/npm help npm/g' \ | perl -pi -e 's/npm\(3\)/npm apihelp npm/g' \ > $dest exit $? ;; *.html) (cat html/dochead.html && \ ./node_modules/.bin/ronn -f $src && cat html/docfoot.html)\ | sed "s|@NAME@|$name|g" \ | sed "s|@DATE@|$date|g" \ | sed "s|@VERSION@|$version|g" \ | perl -pi -e 's/

([^\(]*\([0-9]\)) -- (.*?)<\/h1>/

\1<\/h1>

\2<\/p>/g' \ | perl -pi -e 's/npm-npm/npm/g' \ | perl -pi -e 's/([^"-])(npm-)?README(\(1\))?/\1README<\/a>/g' \ | perl -pi -e 's/<a href="[^"]+README.html">README<\/a><\/title>/<title>README<\/title>/g' \ | perl -pi -e 's/([^"-])([^\(> ]+)(\(1\))/\1<a href="..\/cli\/\2.html">\2\3<\/a>/g' \ | perl -pi -e 's/([^"-])([^\(> ]+)(\(3\))/\1<a href="..\/api\/\2.html">\2\3<\/a>/g' \ | perl -pi -e 's/([^"-])([^\(> ]+)(\(5\))/\1<a href="..\/files\/\2.html">\2\3<\/a>/g' \ | perl -pi -e 's/([^"-])([^\(> ]+)(\(7\))/\1<a href="..\/misc\/\2.html">\2\3<\/a>/g' \ | perl -pi -e 's/\([1357]\)<\/a><\/h1>/<\/a><\/h1>/g' \ | (if [ $(basename $(dirname $dest)) == "doc" ]; then perl -pi -e 's/ href="\.\.\// href="/g' else cat fi) \ > $dest \ && cat html/docfoot-script.html >> $dest exit $? ;; *) echo "Invalid destination type: $dest" >&2 exit 1 ;; esac �����������������������������������������������������������v1.3.10.tar.gz~dfsg/scripts/index-build.js����������������������������������������������������������0000755�0000000�0000000�00000003032�12212013731�017152� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#!/usr/bin/env node var fs = require("fs") , path = require("path") , root = path.resolve(__dirname, "..") , glob = require("glob") , conversion = { "cli": 1, "api": 3, "files": 5, "misc": 7 } glob(root + "/{README.md,doc/*/*.md}", function (er, files) { if (er) throw er output(files.map(function (f) { var b = path.basename(f) if (b === "README.md") return [0, b] if (b === "index.md") return null var s = conversion[path.basename(path.dirname(f))] return [s, f] }).filter(function (f) { return f }).sort(function (a, b) { return (a[0] === b[0]) ? ( path.basename(a[1]) === "npm.md" ? -1 : path.basename(b[1]) === "npm.md" ? 1 : a[1] > b[1] ? 1 : -1 ) : a[0] - b[0] })) }) return function output (files) { console.log( "npm-index(7) -- Index of all npm documentation\n" + "==============================================\n") writeLines(files, 0) writeLines(files, 1, "Command Line Documentation") writeLines(files, 3, "API Documentation") writeLines(files, 5, "Files") writeLines(files, 7, "Misc") } function writeLines (files, sxn, heading) { if (heading) console.log("# %s\n", heading) files.filter(function (f) { return f[0] === sxn }).forEach(writeLine) } function writeLine (sd) { var sxn = sd[0] || 1 , doc = sd[1] , d = path.basename(doc, ".md") var content = fs.readFileSync(doc, "utf8").split("\n")[0].split("-- ")[1] console.log("## %s(%d)\n", d, sxn) console.log(content + "\n") } ������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������v1.3.10.tar.gz~dfsg/scripts/release.sh��������������������������������������������������������������0000644�0000000�0000000�00000001156�12212013731�016366� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#!/bin/bash # script for creating a zip and tarball for inclusion in node unset CDPATH set -e rm -rf release *.tgz || true mkdir release npm pack --loglevel error >/dev/null mv *.tgz release cd release tar xzf *.tgz mkdir node_modules mv package node_modules/npm # make the zip for windows users cp node_modules/npm/bin/*.cmd . zipname=npm-$(npm -v).zip zip -q -9 -r -X "$zipname" *.cmd node_modules # make the tar for node's deps cd node_modules tarname=npm-$(npm -v).tgz tar czf "$tarname" npm cd .. mv "node_modules/$tarname" . rm -rf *.cmd rm -rf node_modules echo "release/$tarname" echo "release/$zipname" ������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������v1.3.10.tar.gz~dfsg/scripts/relocate.sh�������������������������������������������������������������0000755�0000000�0000000�00000001231�12212013731�016541� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#!/bin/bash # Change the cli shebang to point at the specified node # Useful for when the program is moved around after install. # Also used by the default 'make install' in node to point # npm at the newly installed node, rather than the first one # in the PATH, which would be the default otherwise. # bash /path/to/npm/scripts/relocate.sh $nodepath # If $nodepath is blank, then it'll use /usr/bin/env dir="$(dirname "$(dirname "$0")")" cli="$dir"/bin/npm-cli.js tmp="$cli".tmp node="$1" if [ "x$node" = "x" ]; then node="/usr/bin/env node" fi node="#!$node" sed -e 1d "$cli" > "$tmp" echo "$node" > "$cli" cat "$tmp" >> "$cli" rm "$tmp" chmod ogu+x $cli �����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������v1.3.10.tar.gz~dfsg/scripts/clean-old.sh������������������������������������������������������������0000755�0000000�0000000�00000010242�12212013731�016603� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#!/bin/bash # look for old 0.x cruft, and get rid of it. # Should already be sitting in the npm folder. # This doesn't have to be quite as cross-platform as install.sh. # There are some bash-isms, because maintaining *two* # fully-portable posix/bourne sh scripts is too much for # one project with a sane maintainer. # If readlink isn't available, then this is just too tricky. # However, greadlink is fine, so Solaris can join the party, too. readlink="readlink" which $readlink >/dev/null 2>/dev/null if [ $? -ne 0 ]; then readlink="greadlink" which $readlink >/dev/null 2>/dev/null if [ $? -ne 0 ]; then echo "Can't find the readlink or greadlink command. Aborting." exit 1 fi fi if [ "x$npm_config_prefix" != "x" ]; then PREFIXES=$npm_config_prefix else node="$NODE" if [ "x$node" = "x" ]; then node=`which node` fi if [ "x$node" = "x" ]; then echo "Can't find node to determine prefix. Aborting." exit 1 fi PREFIX=`dirname $node` PREFIX=`dirname $PREFIX` echo "cleanup prefix=$PREFIX" PREFIXES=$PREFIX altprefix=`"$node" -e process.installPrefix` if [ "x$altprefix" != "x" ] && [ "x$altprefix" != "x$PREFIX" ]; then echo "altprefix=$altprefix" PREFIXES="$PREFIX $altprefix" fi fi # now prefix is where npm would be rooted by default # go hunting. packages= for prefix in $PREFIXES; do packages="$packages "`ls "$prefix"/lib/node/.npm 2>/dev/null | grep -v .cache` done packages=`echo $packages` filelist=() fid=0 for prefix in $PREFIXES; do # remove any links into the .npm dir, or links to # version-named shims/symlinks. for folder in share/man bin lib/node; do find $prefix/$folder -type l | while read file; do target=`$readlink $file | grep '/\.npm/'` if [ "x$target" != "x" ]; then # found one! filelist[$fid]="$file" let 'fid++' # also remove any symlinks to this file. base=`basename "$file"` base=`echo "$base" | awk -F@ '{print $1}'` if [ "x$base" != "x" ]; then find "`dirname $file`" -type l -name "$base"'*' \ | while read l; do target=`$readlink "$l" | grep "$base"` if [ "x$target" != "x" ]; then filelist[$fid]="$1" let 'fid++' fi done fi fi done # Scour for shim files. These are relics of 0.2 npm installs. # note: grep -r is not portable. find $prefix/$folder -type f \ | xargs grep -sl '// generated by npm' \ | while read file; do filelist[$fid]="$file" let 'fid++' done done # now remove the package modules, and the .npm folder itself. if [ "x$packages" != "x" ]; then for pkg in $packages; do filelist[$fid]="$prefix/lib/node/$pkg" let 'fid++' for i in $prefix/lib/node/$pkg\@*; do filelist[$fid]="$i" let 'fid++' done done fi for folder in lib/node/.npm lib/npm share/npm; do if [ -d $prefix/$folder ]; then filelist[$fid]="$prefix/$folder" let 'fid++' fi done done # now actually clean, but only if there's anything TO clean if [ "${#filelist[@]}" -gt 0 ]; then echo "" echo "This script will find and eliminate any shims, symbolic" echo "links, and other cruft that was installed by npm 0.x." echo "" if [ "x$packages" != "x" ]; then echo "The following packages appear to have been installed with" echo "an old version of npm, and will be removed forcibly:" for pkg in $packages; do echo " $pkg" done echo "Make a note of these. You may want to install them" echo "with npm 1.0 when this process is completed." echo "" fi OK= if [ "x$1" = "x-y" ]; then OK="yes" fi while [ "$OK" != "y" ] && [ "$OK" != "yes" ] && [ "$OK" != "no" ]; do echo "Is this OK?" echo " enter 'yes' or 'no'" echo " or 'show' to see a list of files " read OK if [ "x$OK" = "xshow" ] || [ "x$OK" = "xs" ]; then for i in "${filelist[@]}"; do echo "$i" done fi done if [ "$OK" = "no" ]; then echo "Aborting" exit 1 fi for i in "${filelist[@]}"; do rm -rf "$i" done fi echo "" echo 'All clean!' exit 0 ��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������v1.3.10.tar.gz~dfsg/cli.js��������������������������������������������������������������������������0000755�0000000�0000000�00000000060�12212013731�014024� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#!/usr/bin/env node require("./bin/npm-cli.js") ��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������v1.3.10.tar.gz~dfsg/.npmignore����������������������������������������������������������������������0000644�0000000�0000000�00000000674�12212013731�014726� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������*.swp .*.swp npm-debug.log /test/bin /test/output.log /test/packages/*/node_modules /test/packages/npm-test-depends-on-spark/which-spark.log /test/packages/test-package/random-data.txt /test/root node_modules/ronn node_modules/tap node_modules/.bin node_modules/npm-registry-mock /npmrc /release/ # don't need these in the npm package. html/*.png # don't ignore .npmignore files # these are used in some tests. !.npmignore /npm-*.tgz *.pyc ��������������������������������������������������������������������v1.3.10.tar.gz~dfsg/package.json��������������������������������������������������������������������0000644�0000000�0000000�00000005715�12212013731�015216� 0����������������������������������������������������������������������������������������������������ustar �root����������������������������root�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������{ "version": "1.3.10", "name": "npm", "publishConfig": { "proprietary-attribs": false }, "description": "A package manager for node", "keywords": [ "package manager", "modules", "install", "package.json" ], "preferGlobal": true, "config": { "publishtest": false }, "homepage": "https://npmjs.org/doc/", "author": "Isaac Z. Schlueter <i@izs.me> (http://blog.izs.me)", "repository": { "type": "git", "url": "https://github.com/isaacs/npm" }, "bugs": { "email": "npm-@googlegroups.com", "url": "http://github.com/isaacs/npm/issues" }, "directories": { "doc": "./doc", "man": "./man", "lib": "./lib", "bin": "./bin" }, "main": "./lib/npm.js", "bin": "./bin/npm-cli.js", "dependencies": { "semver": "~2.1.0", "ini": "~1.1.0", "slide": "~1.1.4", "abbrev": "~1.0.4", "graceful-fs": "~2.0.0", "minimatch": "~0.2.12", "nopt": "~2.1.2", "rimraf": "~2.2.0", "request": "~2.25.0", "which": "1", "tar": "~0.1.18", "fstream": "~0.1.23", "block-stream": "0.0.7", "mkdirp": "~0.3.3", "read": "~1.0.4", "lru-cache": "~2.3.0", "node-gyp": "~0.10.9", "fstream-npm": "~0.1.3", "uid-number": "0", "archy": "0", "chownr": "0", "npmlog": "0.0.4", "ansi": "~0.1.2", "npm-registry-client": "~0.2.28", "read-package-json": "~1.1.3", "read-installed": "~0.2.2", "glob": "~3.2.6", "init-package-json": "0.0.11", "osenv": "0", "lockfile": "~0.4.0", "retry": "~0.6.0", "once": "~1.1.1", "npmconf": "~0.1.2", "opener": "~1.3.0", "chmodr": "~0.1.0", "cmd-shim": "~1.0.1", "sha": "~1.2.1", "editor": "0.0.4", "child-process-close": "~0.1.1", "npm-user-validate": "0.0.3", "github-url-from-git": "1.1.1" }, "bundleDependencies": [ "semver", "ini", "slide", "abbrev", "graceful-fs", "minimatch", "nopt", "rimraf", "request", "which", "tar", "fstream", "block-stream", "inherits", "mkdirp", "read", "lru-cache", "node-gyp", "fstream-npm", "uid-number", "archy", "chownr", "npmlog", "ansi", "npm-registry-client", "read-package-json", "read-installed", "glob", "init-package-json", "osenv", "lockfile", "retry", "once", "npmconf", "opener", "chmodr", "cmd-shim", "sha", "child-process-close", "editor", "npm-user-validate", "github-url-from-git" ], "devDependencies": { "ronn": "~0.3.6", "tap": "~0.4.0", "npm-registry-mock": "~0.3.0" }, "engines": { "node": ">=0.6", "npm": "1" }, "scripts": { "test": "node ./test/run.js && tap test/tap/*.js", "tap": "tap test/tap/*.js", "prepublish": "node bin/npm-cli.js prune ; rm -rf test/*/*/node_modules ; make -j4 doc", "dumpconf": "env | grep npm | sort | uniq", "echo": "node bin/npm-cli.js" }, "license": "Artistic-2.0" } �������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������