feat: add npm diff

- As proposed in RFC: npm/rfcs#144

Author: ruyadorno

docs/content/commands/npm-diff.md

@@ -0,0 +1,165 @@
+---
+title: npm-diff
+section: 1
+description: The registry diff command
+---
+
+### Synopsis
+
+```bash
+npm diff
+npm diff --diff=<pkg-name>
+npm diff --diff=<version-a> [--diff=<version-b>]
+npm diff --diff=<spec-a> [--diff=<spec-b>]
+```
+
+### Description
+
+Similar to its `git diff` counterpart, this command will print diff patches
+of files for packages published to the npm registry.
+
+* `npm diff --diff=<spec-a> --diff=<spec-b>`
+
+ Compares two package versions using their registry specifiers, e.g:
+ `npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0`. It's also possible to
+ compare across forks of any package,
+ e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0`.
+
+ Any valid spec can be used, so that it's also possible to compare
+ directories or git repositories,
+ e.g: `npm diff --diff=pkg@latest --diff=./packages/pkg`
+
+* `npm diff` (in a package directory, no arguments):
+
+ If the package is published to the registry, `npm diff` will fetch the
+ tarball version tagged as `latest` (this value can be configured using the
+ `tag` option) and proceed to compare the contents of files present in that
+ tarball, with the current files in your local file system.
+
+ This workflow provides a handy way for package authors to see what
+ package-tracked files have been changed in comparison with the latest
+ published version of that package.
+
+* `npm diff --diff=<pkg-name>` (in a package directory):
+
+ When using a single package name (with no version or tag specifier) as an
+ argument, `npm diff` will work in a similar way to
+ [`npm-outdated`](npm-outdated) and reach for the registry to figure out
+ what current published version of the package named <pkg-name> will satisfy
+ its dependent declared semver-range. Once that specific version is known
+ `npm diff` will print diff patches comparing the current version of
+ <pkg-name> found in the local file system with that specific version
+ returned by the registry.
+
+* `npm diff --diff=<spec-a>` (in a package directory):
+
+ Similar to using only a single package name, it's also possible to declare
+ a full registry specifier version if you wish to compare the local version
+ of a installed package with the specific version/tag/semver-range provided
+ in `<spec-a>`. e.g: (assuming pkg@1.0.0 is installed in the current
+ `node_modules` folder) running `npm diff --diff=pkg@2.0.0` will effectively
+ be an alias to `npm diff --diff=pkg@1.0.0 --diff=pkg@2.0.0`.
+
+* `npm diff --diff=<semver-a> [--diff=<semver-b>]` (in a package directory):
+
+ Using `npm diff` along with semver-valid version numbers is a shorthand
+ to compare different versions of the current package. It needs to be run
+ from a package directory, such that for a package named `pkg` running
+ `npm diff --diff=1.0.0 --diff=1.0.1` is the same as running
+ `npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1`. If only a single argument
+ `<version-a>` is provided, then the current local file system is going to
+ be compared against that version.
+
+Note that tag names are not valid `--diff` argument values, if you wish to
+compare against a published tag, you must use the `pkg@tagname` syntax.
+
+#### Filtering files
+
+It's possible to also specify positional arguments using file names or globs
+pattern matching in order to limit the result of diff patches to only a subset
+of files for a given package, e.g:
+
+`npm diff --diff=pkg@2 ./lib/ CHANGELOG.md`
+
+### Configuration
+
+#### diff
+
+* Type: String, Array, null
+* Default: null
+
+Defines up to two npm valid package specifiers in which to compare.
+
+#### diff-name-only
+
+* Type: Boolean
+* Default: false
+
+When set to `true` running `npm diff` only returns the names of the files that
+have any difference.
+
+#### diff-unified
+
+* Type: number
+* Default: `3`
+
+The number of lines of context to print in the unified diff format output.
+
+#### diff-ignore-all-space
+
+* Type: Boolean
+* Default: false
+
+Ignore whitespace when comparing lines. This ignores differences even if one
+line has whitespace where the other line has none.
+
+#### diff-no-prefix
+
+* Type: Boolean
+* Default: false
+
+Do not show any source or destination prefix.
+
+#### diff-src-prefix
+
+* Type: String
+* Default: `"a/"`
+
+Show the given source prefix in diff patches headers instead of using "a/".
+
+#### diff-dst-prefix
+
+* Type: String
+* Default: `"b/"`
+
+Show the given source prefix in diff patches headers instead of using "b/".
+
+#### diff-text
+
+* Type: Boolean
+* Default: false
+
+Treat all files as text.
+
+#### global
+
+* Default: false
+* Type: Boolean
+
+Uses packages from the global space as source for comparison.
+
+#### tag
+
+* Type: String
+* Default: `"latest"`
+
+The tag used to fetch the tarball that will be compared with local file system
+files when running npm diff with no arguments.
+
+
+## See Also
+
+* [npm outdated](/commands/npm-outdated)
+* [npm install](/commands/npm-install)
+* [npm config](/commands/npm-config)
+* [npm registry](/using-npm/registry)

docs/content/using-npm/config.md

@@ -379,6 +379,63 @@ commands that modify your local installation, eg, `install`, `update`,
 `dedupe`, `uninstall`. This is NOT currently honored by some network related
 commands, eg `dist-tags`, `owner`, etc.
 
+#### diff
+
+* Default: null
+* Type: String, Array, null
+
+Define arguments to compare in `npm diff`.
+
+#### diff-name-only
+
+* Default: false
+* Type: Boolean
+
+Prints only filenames when using `npm diff`.
+
+#### diff-unified
+
+* Type: number
+* Default: `3`
+
+The number of lines of context to print in `npm diff`.
+
+#### diff-ignore-all-space
+
+* Type: Boolean
+* Default: false
+
+Ignore whitespace when comparing lines in `npm diff.
+
+#### diff-no-prefix
+
+* Type: Boolean
+* Default: false
+
+Do not show any source or destination prefix in `npm diff` output.
+
+#### diff-src-prefix
+
+* Type: String
+* Default: `"a/"`
+
+Source prefix to be used in `npm diff` output.
+
+#### diff-dst-prefix
+
+* Type: String
+* Default: `"b/"`
+
+Destination prefix to be used in `npm diff` output.
+
+#### diff-text
+
+* Alias: `-a`
+* Type: Boolean
+* Default: false
+
+Treat all files as text in `npm diff`.
+
 #### editor
 
 * Default: `EDITOR` environment variable if set, or `"vi"` on Posix,