npm-diff

Compare two specific package versions

$ npm diff --diff [package_name]@[version1] --diff [package_name]@[version2]

$ npm diff

$ npm diff --diff [package_name]@[version]

$ npm diff --diff [package_name]

$ npm diff --diff-name-only --diff [package_name]@[version1] --diff [package_name]@[version2]

$ npm diff [path/to/file_or_directory] --diff [package_name]@[version1] --diff [package_name]@[version2]

$ npm diff --diff-ignore-all-space --diff [package_name]@[version1] --diff [package_name]@[version2]

npm diff [<@scope>/][@] [<@scope>/][@]
npm diff [--diff=] [--diff-path=] [] [-- ]

[<@scope>/][@]
    One or two package specifiers. A package specifier can be a package name, optionally prefixed with a scope (e.g., @myorg/) and suffixed with a version (e.g., @1.2.3). Used to identify specific packages or versions for comparison.

--diff=
    Specifies a package to compare the current working directory files against. If the package is not installed, it will be fetched from the npm registry.

--diff-path=
    Limits the diff to a specific file or directory path within the package(s) being compared. The path is relative to the package root.

--diff-ignore-untracked
    When comparing local changes, untracked files in the working directory are ignored and not included in the diff output.

--diff-cached
    Compares the files in the Git working directory against the Git index (staged changes). This option is only relevant when used within a Git repository.

--diff-name-only
    Outputs only the names of the files that have changed, without showing the actual content differences.

--diff-unified=
    Specifies the number of context lines (n) to show around each change in the diff output. The default is usually 3.

--diff-color / --diff-no-color
    Forces the diff output to be colored or explicitly disables colored output, respectively. Overrides default terminal settings.

--diff-base=
    Used when comparing within a Git repository. Specifies a Git reference (e.g., commit hash, branch name) to use as the base for the comparison.

--diff-head=
    Used when comparing within a Git repository. Specifies a Git reference to use as the head for the comparison.

--diff-exit-code
    Causes npm diff to exit with a non-zero status code (1) if differences are found, and 0 if no differences are detected. Useful for scripting.

--
    Separates npm diff options from options that should be passed directly to the underlying git diff command. This allows full access to git diff's extensive feature set.

The npm-diff command allows developers to inspect differences between various versions of packages or between a local working directory and an installed package. It primarily serves as a wrapper around the underlying git diff utility, adapting its extensive functionality for comparing JavaScript packages managed by npm. Users can compare:

1. Local changes vs. installed package: Without any arguments, npm diff compares the files in the current working directory with the version currently installed in node_modules.
2. Local changes vs. a specified package version: Using --diff=<pkg-spec>, it compares local files against a specific package version, potentially fetching it from the npm registry if not locally available.
3. Two different package versions: By providing two package specifiers, npm diff can compare the contents of two different versions of a package, typically fetched from the npm registry.

This utility is invaluable for debugging, understanding changes between package updates, or verifying the state of a package in development. It leverages git diff's powerful options, which can be passed through to customize the output.

The npm diff command relies heavily on Git's internal diffing mechanism. Consequently, its full functionality, especially when comparing local changes, requires Git to be installed and properly configured on the system. If Git is not available or the project is not a Git repository, some comparison modes or options may not work as expected. When comparing package versions from the registry, npm might need to download package tarballs, which can incur network usage.

npm diff intelligently determines the comparison mode based on the provided arguments:

• No arguments: Compares local working directory against the installed node_modules version of the current package.
• One package specifier (with --diff): Compares local working directory against the specified package version.
• Two package specifiers: Compares the two specified package versions against each other, fetching them from the registry if necessary.

Many of the npm diff options are direct pass-throughs for git diff. This integration means that users familiar with git diff can leverage that knowledge to perform sophisticated comparisons. For advanced git diff options not explicitly listed, they can be passed using the -- separator.

The npm diff command was introduced as part of npm v7.0.0 in October 2020. Its inclusion aimed to provide developers with a native npm way to compare package files, simplifying workflows that previously might have required manual package extraction and external diff tools or complex Git commands. It standardized the process of examining changes between package versions or local modifications.

npm(1), npm-install(1), npm-view(1), git-diff(1)