doc: note that hosted repo shortcuts can take commit-ishes

* improve the git "url" description
* move git documentation above hosted git shortcuts

doc/cli/npm-install.md

@@ -155,71 +155,70 @@ after packing it up into a tarball (b).
           npm install sax@">=0.1.0 <0.2.0"
           npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
 
-* `npm install <githubname>/<githubrepo>`:
+* `npm install <git remote url>`:
 
-    Install the package at `https://github.com/githubname/githubrepo` by
-    attempting to clone it using `git`.
+    Install a package by cloning a git remote url.  The format of the git
+    url is:
 
-    Example:
+          <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit-ish>]
 
-          npm install mygithubuser/myproject
+    `<protocol>` is one of `git`, `git+ssh`, `git+http`, or
+    `git+https`.  If no `<commit-ish>` is specified, then `master` is
+    used.
 
-   To reference a package in a generic git repo (not on GitHub), see git remote
-   urls below.
+    Examples:
 
-* `npm install github:<githubname>/<githubrepo>`:
+          git+ssh://git@github.com:npm/npm.git#v1.0.27
+          git+https://isaacs@github.com/npm/npm.git
+          git://github.com/npm/npm.git#v1.0.27
 
-    The same as the above, but explicitly marked as a GitHub dependency.
+* `npm install <githubname>/<githubrepo>[#<commit-ish>]`:
+* `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`:
 
-    Example:
+    Install the package at `https://github.com/githubname/githubrepo` by
+    attempting to clone it using `git`.
+
+    If you don't specify a *commit-ish* then `master` will be used.
+
+    Examples:
 
-          npm install github:npm/npm
+          npm install mygithubuser/myproject
+          npm install github:mygithubuser/myproject
 
-* `npm install gist:[<githubname>/]<gistID>`:
+* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>]`:
 
     Install the package at `https://gist.github.com/gistID` by attempting to
     clone it using `git`. The GitHub username associated with the gist is
     optional and will not be saved in `package.json` if `--save` is used.
 
+    If you don't specify a *commit-ish* then `master` will be used.
+
     Example:
 
           npm install gist:101a11beef
 
-* `npm install bitbucket:<bitbucketname>/<bitbucketrepo>`:
+* `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`:
 
     Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo`
     by attempting to clone it using `git`.
 
+    If you don't specify a *commit-ish* then `master` will be used.
+
     Example:
 
           npm install bitbucket:mybitbucketuser/myproject
 
-* `npm install gitlab:<gitlabname>/<gitlabrepo>`:
+* `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`:
 
     Install the package at `https://gitlab.com/gitlabname/gitlabrepo`
     by attempting to clone it using `git`.
 
+    If you don't specify a *commit-ish* then `master` will be used.
+
     Example:
 
           npm install gitlab:mygitlabuser/myproject
 
-* `npm install <git remote url>`:
-
-    Install a package by cloning a git remote url.  The format of the git
-    url is:
-
-          <protocol>://[<user>[:<password>]@]<hostname><separator><path>[#<commit-ish>]
-
-    `<protocol>` is one of `git`, `git+ssh`, `git+http`, or
-    `git+https`.  If no `<commit-ish>` is specified, then `master` is
-    used.
-
-    Examples:
-
-          git+ssh://git@github.com:npm/npm.git#v1.0.27
-          git+https://isaacs@github.com/npm/npm.git
-          git://github.com/npm/npm.git#v1.0.27
-
 You may combine multiple arguments, and even multiple types of arguments.
 For example: