Changes to reflect scoped package support.

14 files changed, 200 insertions, 42 deletions

diff --git a/doc/cli/npm-adduser.md b/doc/cli/npm-adduser.md
index 68f3a3c00..d60d6e9a0 100644
--- a/doc/cli/npm-adduser.md
+++ b/doc/cli/npm-adduser.md
@@ -3,30 +3,47 @@ npm-adduser(1) -- Add a registry user account
 
 ## SYNOPSIS
 
-    npm adduser
+    npm adduser [--registry=url] [--scope=@orgname]
 
 ## DESCRIPTION
 
-Create or verify a user named `<username>` in the npm registry, and
-save the credentials to the `.npmrc` file.
+Create or verify a user named `<username>` in the specified registry, and
+save the credentials to the `.npmrc` file. If no registry is specified,
+the default registry will be used (see `npm-config(7)`).
 
 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 <https://npmjs.org/forgot>
+To reset your password, go to <https://www.npmjs.org/forgot>
 
 You may use this command multiple times with the same user account to
 authorize on a new machine.
 
+`npm login` is an alias to `adduser` and behaves exactly the same way.
+
 ## CONFIGURATION
 
 ### registry
 
 Default: http://registry.npmjs.org/
 
-The base URL of the npm package registry.
+The base URL of the npm package registry. If `scope` is also specified,
+this registry will only be used for packages with that scope. See `npm-scope(7)`.
+
+### scope
+
+Default: none
+
+If specified, the user and login credentials given will be associated
+with the specified scope. See `npm-scope(7)`. You can use both at the same time,
+e.g.
+
+    npm adduser --registry=http://myregistry.example.com --scope=@myco
+
+This will set a registry for the given scope and login or create a user for
+that registry at the same time.
 
 ## SEE ALSO
 
diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md
index 62eec2d8e..2d4271637 100644
--- a/doc/cli/npm-install.md
+++ b/doc/cli/npm-install.md
@@ -7,10 +7,10 @@ npm-install(1) -- Install a package
     npm install <tarball file>
     npm install <tarball url>
     npm install <folder>
-    npm install <name> [--save|--save-dev|--save-optional] [--save-exact]
-    npm install <name>@<tag>
-    npm install <name>@<version>
-    npm install <name>@<version range>
+    npm install [@<scope>/]<name> [--save|--save-dev|--save-optional] [--save-exact]
+    npm install [@<scope>/]<name>@<tag>
+    npm install [@<scope>/]<name>@<version>
+    npm install [@<scope>/]<name>@<version range>
     npm i (with any of the previous argument usage)
 
 ## DESCRIPTION
@@ -70,7 +70,7 @@ after packing it up into a tarball (b).
 
           npm install https://github.com/indexzero/forever/tarball/v0.5.6
 
-* `npm install <name> [--save|--save-dev|--save-optional]`:
+* `npm install [@<scope>/]<name> [--save|--save-dev|--save-optional]`:
 
     Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
     `npm-config(7)`.)
@@ -98,9 +98,19 @@ after packing it up into a tarball (b).
       exact version rather than using npm's default semver range
       operator.
 
+    `<scope>` is optional. The package will be downloaded from the registry
+    associated with the specified scope. If no registry is associated with
+    the given scope the default registry is assumed. See `npm-scope(7)`.
+
+    Note: if you do not include the @-symbol on your scope name, npm will
+    interpret this as a GitHub repository instead, see below. Scopes names
+    must also be followed by a slash.
+
     Examples:
 
           npm install sax --save
+          npm install githubname/reponame
+          npm install @myorg/privatepackage
           npm install node-tap --save-dev
           npm install dtrace-provider --save-optional
           npm install readable-stream --save --save-exact
@@ -110,7 +120,7 @@ after packing it up into a tarball (b).
     working directory, then it will try to install that, and only try to
     fetch the package by name if it is not valid.
 
-* `npm install <name>@<tag>`:
+* `npm install [@<scope>/]<name>@<tag>`:
 
     Install the version of the package that is referenced by the specified tag.
     If the tag does not exist in the registry data for that package, then this
@@ -119,17 +129,19 @@ after packing it up into a tarball (b).
     Example:
 
           npm install sax@latest
+          npm install @myorg/mypackage@latest
 
-* `npm install <name>@<version>`:
+* `npm install [@<scope>/]<name>@<version>`:
 
-    Install the specified version of the package.  This will fail if the version
-    has not been published to the registry.
+    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 @myorg/privatepackage@1.5.0
 
-* `npm install <name>@<version range>`:
+* `npm install [@<scope>/]<name>@<version range>`:
 
     Install a version of the package matching the specified version range.  This
     will follow the same rules for resolving dependencies described in `package.json(5)`.
@@ -140,6 +152,19 @@ after packing it up into a tarball (b).
     Example:
 
           npm install sax@">=0.1.0 <0.2.0"
+          npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
+
+* `npm install <githubname>/<githubrepo>`:
+
+    Install the package at `https://github.com/githubname/githubrepo" by
+    attempting to clone it using `git`.
+
+    Example:
+
+          npm install mygithubuser/myproject
+
+   To reference a package in a git repo that is not on GitHub, see git
+   remote urls below.
 
 * `npm install <git remote url>`:
 
diff --git a/doc/cli/npm-link.md b/doc/cli/npm-link.md
index c0fc01eb2..a6c274790 100644
--- a/doc/cli/npm-link.md
+++ b/doc/cli/npm-link.md
@@ -4,7 +4,7 @@ npm-link(1) -- Symlink a package folder
 ## SYNOPSIS
 
     npm link (in package folder)
-    npm link <pkgname>
+    npm link [@<scope>/]<pkgname>
     npm ln (with any of the previous argument usage)
 
 ## DESCRIPTION
@@ -12,7 +12,8 @@ npm-link(1) -- Symlink a package folder
 Package linking is a two-step process.
 
 First, `npm link` in a package folder will create a globally-installed
-symbolic link from `prefix/package-name` to the current folder.
+symbolic link from `prefix/package-name` to the current folder (see
+`npm-config(7)` for the value of `prefix`).
 
 Next, in some other location, `npm link package-name` will create a
 symlink from the local `node_modules` folder to the global symlink.
@@ -20,12 +21,14 @@ symlink from the local `node_modules` folder to the global symlink.
 Note that `package-name` is taken from `package.json`,
 not from directory name.
 
+The package name can be optionally prefixed with a scope. See `npm-scope(7)`.
+The scope must by preceded by an @-symbol and followed by a slash.
+
 When creating tarballs for `npm publish`, the linked packages are
 "snapshotted" to their current state by resolving the symbolic links.
 
-This is
-handy for installing your own stuff, so that you can work on it and test it
-iteratively without having to continually rebuild.
+This 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:
 
@@ -51,6 +54,11 @@ The second line is the equivalent of doing:
 That is, it first creates a global link, and then links the global
 installation target into your project's `node_modules` folder.
 
+If your linked package is scoped (see `npm-scope(7)`) your link command must
+include that scope, e.g.
+
+    npm link @myorg/privatepackage
+
 ## SEE ALSO
 
 * npm-developers(7)
diff --git a/doc/cli/npm-ls.md b/doc/cli/npm-ls.md
index 21f54264c..0f0d79489 100644
--- a/doc/cli/npm-ls.md
+++ b/doc/cli/npm-ls.md
@@ -3,10 +3,10 @@ npm-ls(1) -- List installed packages
 
 ## SYNOPSIS
 
-    npm list [<pkg> ...]
-    npm ls [<pkg> ...]
-    npm la [<pkg> ...]
-    npm ll [<pkg> ...]
+    npm list [[@<scope>/]<pkg> ...]
+    npm ls [[@<scope>/]<pkg> ...]
+    npm la [[@<scope>/]<pkg> ...]
+    npm ll [[@<scope>/]<pkg> ...]
 
 ## DESCRIPTION
 
diff --git a/doc/cli/npm-prefix.md b/doc/cli/npm-prefix.md
index f99a401d1..f262a36a7 100644
--- a/doc/cli/npm-prefix.md
+++ b/doc/cli/npm-prefix.md
@@ -3,11 +3,15 @@ npm-prefix(1) -- Display prefix
 
 ## SYNOPSIS
 
-    npm prefix
+    npm prefix [-g]
 
 ## DESCRIPTION
 
-Print the prefix to standard out.
+Print the local prefix to standard out. This is the closest parent directory
+to contain a package.json file unless `-g` is also specified.
+
+If `-g` is specified, this will be the value of the global prefix. See
+`npm-config(7)` for more detail.
 
 ## SEE ALSO
 
diff --git a/doc/cli/npm-publish.md b/doc/cli/npm-publish.md
index 338728e3e..8860b88fc 100644
--- a/doc/cli/npm-publish.md
+++ b/doc/cli/npm-publish.md
@@ -11,6 +11,10 @@ npm-publish(1) -- Publish a package
 
 Publishes a package to the registry so that it can be installed by name.
 
+By default npm will publish to the public registry. This can be overridden by
+specifying a different default registry or using a `npm-scope(7)` in the name
+(see `package.json(5)`).
+
 * `<folder>`:
   A folder containing a package.json file
 
@@ -24,7 +28,7 @@ Publishes a package to the registry so that it can be installed by name.
   and `npm install` installs the `latest` tag.
 
 Fails if the package name and version combination already exists in
-the registry.
+the specified registry.
 
 Once a package is published with a given name and version, that
 specific name and version combination can never be used again, even if
diff --git a/doc/cli/npm-uninstall.md b/doc/cli/npm-uninstall.md
index e24815bec..bfa667c3e 100644
--- a/doc/cli/npm-uninstall.md
+++ b/doc/cli/npm-uninstall.md
@@ -3,7 +3,7 @@ npm-rm(1) -- Remove a package
 
 ## SYNOPSIS
 
-    npm uninstall <name> [--save|--save-dev|--save-optional]
+    npm uninstall [@<scope>/]<package> [--save|--save-dev|--save-optional]
     npm rm (with any of the previous argument usage)
 
 ## DESCRIPTION
@@ -27,9 +27,12 @@ the package version in your main package.json:
 
 * `--save-optional`: Package will be removed from your `optionalDependencies`.
 
+Scope is optional and follows the usual rules for `npm-scope(7)`.
+
 Examples:
 
     npm uninstall sax --save
+    npm uninstall @myorg/privatepackage --save
     npm uninstall node-tap --save-dev
     npm uninstall dtrace-provider --save-optional
 
diff --git a/doc/cli/npm-unpublish.md b/doc/cli/npm-unpublish.md
index 45026197e..1d5fe9287 100644
--- a/doc/cli/npm-unpublish.md
+++ b/doc/cli/npm-unpublish.md
@@ -3,7 +3,7 @@ npm-unpublish(1) -- Remove a package from the registry
 
 ## SYNOPSIS
 
-    npm unpublish <name>[@<version>]
+    npm unpublish [@<scope>/]<name>[@<version>]
 
 ## WARNING
 
@@ -27,6 +27,8 @@ Even if a package version is unpublished, that specific name and
 version combination can never be reused.  In order to publish the
 package again, a new version number must be used.
 
+The scope is optional and follows the usual rules for `npm-scope(7)`.
+
 ## SEE ALSO
 
 * npm-deprecate(1)
diff --git a/doc/cli/npm-update.md b/doc/cli/npm-update.md
index 1ea6b6275..a53d29459 100644
--- a/doc/cli/npm-update.md
+++ b/doc/cli/npm-update.md
@@ -12,8 +12,11 @@ This command will update all the packages listed to the latest version
 
 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.
+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
 
diff --git a/doc/cli/npm-view.md b/doc/cli/npm-view.md
index 1d19fe88d..8f52a85a9 100644
--- a/doc/cli/npm-view.md
+++ b/doc/cli/npm-view.md
@@ -3,8 +3,8 @@ npm-view(1) -- View registry info
 
 ## SYNOPSIS
 
-    npm view <name>[@<version>] [<field>[.<subfield>]...]
-    npm v <name>[@<version>] [<field>[.<subfield>]...]
+    npm view [@<scope>/]<name>[@<version>] [<field>[.<subfield>]...]
+    npm v [@<scope>/]<name>[@<version>] [<field>[.<subfield>]...]
 
 ## DESCRIPTION
 
diff --git a/doc/files/npm-folders.md b/doc/files/npm-folders.md
index 1b1485d5e..1fb21b1a3 100644
--- a/doc/files/npm-folders.md
+++ b/doc/files/npm-folders.md
@@ -42,6 +42,12 @@ 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.)
 
+Scoped packages are installed the same way, except they are grouped together
+in a sub-folder of the relevant `node_modules` folder with the name of that
+scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place
+the package in `{prefix}/node_modules/@myorg/package`. See `scopes(7)` for
+more details.
+
 If you wish to `require()` a package, then install it locally.
 
 ### Executables
diff --git a/doc/files/package.json.md b/doc/files/package.json.md
index af10cc962..266adfe05 100644
--- a/doc/files/package.json.md
+++ b/doc/files/package.json.md
@@ -30,6 +30,9 @@ The name is what your thing is called.  Some tips:
 * 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/
 
+A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See
+`npm-scope(7)` for more detail.
+
 ## version
 
 The *most* important things in your package.json are the name and version fields.
diff --git a/doc/misc/npm-registry.md b/doc/misc/npm-registry.md
index a8c4b0200..42cec5944 100644
--- a/doc/misc/npm-registry.md
+++ b/doc/misc/npm-registry.md
@@ -12,15 +12,14 @@ write APIs as well, to allow for publishing packages and managing user
 account information.
 
 The official public npm registry is at <http://registry.npmjs.org/>.  It
-is powered by a CouchDB database at
-<http://isaacs.iriscouch.com/registry>.  The code for the couchapp is
-available at <http://github.com/npm/npmjs.org>.  npm user accounts
-are CouchDB users, stored in the <http://isaacs.iriscouch.com/_users>
-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.
+is powered by a CouchDB database, of which there is a public mirror at
+<http://skimdb.npmjs.com/registry>.  The code for the couchapp is
+available at <http://github.com/npm/npm-registry-couchapp>.
+
+The registry URL used is determined by the scope of the package (see
+`npm-scope(7)`). If no scope is specified, the default registry is used, which 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?
 
diff --git a/doc/misc/npm-scope.md b/doc/misc/npm-scope.md
new file mode 100644
index 000000000..a4ee1a082
--- /dev/null
+++ b/doc/misc/npm-scope.md
@@ -0,0 +1,84 @@
+npm-scope(7) -- Scoped packages
+===============================
+
+## DESCRIPTION
+
+All npm packages have a name. Some package names also have a scope. A scope
+follows the usual rules for package names (url-safe characters, no leading dots
+or underscores). When used in package names, preceded by an @-symbol and
+followed by a slash, e.g.
+
+    @somescope/somepackagename
+
+Scopes are a way of grouping related packages together, and also affect a few
+things about the way npm treats the package.
+
+**As of 2014-09-03, scoped packages are not supported by the public npm registry**.
+However, the npm client is backwards-compatible with un-scoped registries, so
+it can be used to work with scoped and un-scoped registries at the same time.
+
+## Installing scoped packages
+
+Scoped packages are installed to a sub-folder of the regular installation
+folder, e.g. if your other packages are installed in `node_modules/packagename`,
+scoped modules will be in `node_modules/@myorg/packagename`. The scope folder
+(`@myorg`) is simply the name of the scope preceded by an @-symbol, and can
+contain any number of scoped packages.
+
+A scoped package is install by referencing it by name, preceded by an @-symbol,
+in `npm install`:
+
+    npm install @myorg/mypackage
+
+Or in `package.json`:
+
+    "dependencies": {
+      "@myorg/mypackage": "^1.3.0"
+    }
+
+Note that if the @-symbol is omitted in either case npm will instead attempt to
+install from GitHub; see `npm-install(1)`.
+
+## Requiring scoped packages
+
+Because scoped packages are installed into a scope folder, you have to
+include the name of the scope when requiring them in your code, e.g.
+
+    require('@myorg/mypackage')
+
+There is nothing special about the way Node treats scope folders, this is
+just specifying to require the module `mypackage` in the folder called `@myorg`.
+
+## Publishing scoped packages
+
+Scoped packages can be published to any registry that supports them.
+*As of 2014-09-03, the public npm registry does not support scoped packages*,
+so attempting to publish a scoped package to the registry will fail unless
+you have associated that scope with a different registry, see below.
+
+## Associating a scope with a registry
+
+Scopes can be associated with a separate registry. This allows you to
+seamlessly use a mix of packages from the public npm registry and one or more
+private registries, such as npm Enterprise.
+
+You can associate a scope with a registry at login, e.g.
+
+    npm login --registry=http://reg.example.com --scope=@myco
+
+Scopes have a many-to-one relationship with registries: one registry can
+host multiple scopes, but a scope only ever points to one registry.
+
+You can also associate a scope with a registry using `npm config`:
+
+    npm config set @myco:registry http://reg.example.com
+
+Once a scope is associated with a registry, any `npm install` for a package
+with that scope will request packages from that registry instead. Any
+`npm publish` for a package name that contains the scope will be published to
+that registry instead.
+
+## SEE ALSO
+
+* npm-install(1)
+* npm-publish(1)
\ No newline at end of file