npm-diff(1)

1NPM-DIFF(1)                                                        NPM-DIFF(1)
2
3
4

NAME

6       npm-diff - The registry diff command
7
8   Synopsis
9         npm diff [...<paths>]
10
11   Description
12       Similar  to  its  git  diff  counterpart,  this command will print diff
13       patches of files for packages published to the npm registry.
14
15       •   npm diff --diff=<spec-a> --diff=<spec-b>
16
17       Compares two package versions using their registry specifiers, e.g: npm
18       diff  --diff=pkg@1.0.0 --diff=pkg@^2.0.0. It's also possible to compare
19       across forks of any package, e.g: npm diff --diff=pkg@1.0.0 --diff=pkg-
20       fork@1.0.0.
21
22       Any  valid  spec can be used, so that it's also possible to compare di‐
23       rectories  or  git  repositories,  e.g:  npm   diff   --diff=pkg@latest
24       --diff=./packages/pkg
25
26       Here's  an  example comparing two different versions of a package named
27       abbrev from the registry:
28
29         npm diff --diff=abbrev@1.1.0 --diff=abbrev@1.1.1
30
31       On success, output looks like:
32
33         diff --git a/package.json b/package.json
34         index v1.1.0..v1.1.1 100644
35         --- a/package.json
36         +++ b/package.json
37         @@ -1,6 +1,6 @@
38          {
39            "name": "abbrev",
40         -  "version": "1.1.0",
41         +  "version": "1.1.1",
42            "description": "Like ruby's abbrev module, but in js",
43            "author": "Isaac Z. Schlueter <i@izs.me>",
44            "main": "abbrev.js",
45
46       Given the flexible nature of npm specs, you can also target  local  di‐
47       rectories or git repos just like when using npm install:
48
49         npm diff --diff=https://github.com/npm/libnpmdiff --diff=./local-path
50
51       In  the  example above we can compare the contents from the package in‐
52       stalled from the git repo at github.com/npm/libnpmdiff  with  the  con‐
53       tents of the ./local-path that contains a valid package, such as a mod‐
54       ified copy of the original.
55
56       •   npm diff (in a package directory, no arguments):
57
58       If the package is published to the registry, npm diff  will  fetch  the
59       tarball  version  tagged  as latest (this value can be configured using
60       the tag option) and proceed to compare the contents of files present in
61       that tarball, with the current files in your local file system.
62
63       This  workflow  provides  a  handy  way for package authors to see what
64       package-tracked files have been changed in comparison with  the  latest
65       published version of that package.
66
67       •   npm diff --diff=<pkg-name> (in a package directory):
68
69       When  using a single package name (with no version or tag specifier) as
70       an argument, npm diff will work in a similar way to npm-outdated  ⟨npm-
71       outdated⟩  and  reach  for the registry to figure out what current pub‐
72       lished version of the package named <pkg-name> will satisfy its  depen‐
73       dent  declared  semver-range.  Once  that specific version is known npm
74       diff will print diff patches comparing the  current  version  of  <pkg-
75       name>  found  in  the  local file system with that specific version re‐
76       turned by the registry.
77
78       Given a package named abbrev that is currently installed:
79
80         npm diff --diff=abbrev
81
82       That will request from the registry its most up  to  date  version  and
83       will  print  a diff output comparing the currently installed version to
84       this newer one if the version numbers are not the same.
85
86       •   npm diff --diff=<spec-a> (in a package directory):
87
88       Similar to using only a single package name, it's also possible to  de‐
89       clare  a full registry specifier version if you wish to compare the lo‐
90       cal  version  of  an  installed  package   with   the   specific   ver‐
91       sion/tag/semver-range provided in <spec-a>.
92
93       An example: assuming pkg@1.0.0 is installed in the current node_modules
94       folder, running:
95
96         npm diff --diff=pkg@2.0.0
97
98       It  will  effectively  be  an  alias  to  npm   diff   --diff=pkg@1.0.0
99       --diff=pkg@2.0.0.
100
101       •   npm diff --diff=<semver-a> [--diff=<semver-b>] (in a package direc‐
102           tory):
103
104       Using npm diff along with semver-valid version numbers is  a  shorthand
105       to compare different versions of the current package.
106
107       It  needs  to  be run from a package directory, such that for a package
108       named pkg running npm diff --diff=1.0.0 --diff=1.0.1  is  the  same  as
109       running npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1.
110
111       If only a single argument <version-a> is provided, then the current lo‐
112       cal file system is going to be compared against that version.
113
114       Here's an example comparing two specific  versions  (published  to  the
115       configured registry) of the current project directory:
116
117         npm diff --diff=1.0.0 --diff=1.1.0
118
119
120       Note  that  tag names are not valid --diff argument values, if you wish
121       to compare to a published tag, you must use the pkg@tagname syntax.
122
123   Filtering files
124       It's possible to also specify positional arguments using file names  or
125       globs  pattern matching in order to limit the result of diff patches to
126       only a subset of files for a given package, e.g:
127
128         npm diff --diff=pkg@2 ./lib/ CHANGELOG.md
129
130       In the example above the diff output is only going to print contents of
131       files located within the folder ./lib/ and changed lines of code within
132       the CHANGELOG.md file.
133
134   Configuration
135   diff
136       •   Default:
137
138       •   Type: String (can be set multiple times)
139
140
141       Define arguments to compare in npm diff.
142
143   diff-name-only
144       •   Default: false
145
146       •   Type: Boolean
147
148
149       Prints only filenames when using npm diff.
150
151   diff-unified
152       •   Default: 3
153
154       •   Type: Number
155
156
157       The number of lines of context to print in npm diff.
158
159   diff-ignore-all-space
160       •   Default: false
161
162       •   Type: Boolean
163
164
165       Ignore whitespace when comparing lines in npm diff.
166
167   diff-no-prefix
168       •   Default: false
169
170       •   Type: Boolean
171
172
173       Do not show any source or destination prefix in npm diff output.
174
175       Note: this causes npm diff to ignore the --diff-src-prefix and  --diff-
176       dst-prefix configs.
177
178   diff-src-prefix
179       •   Default: "a/"
180
181       •   Type: String
182
183
184       Source prefix to be used in npm diff output.
185
186   diff-dst-prefix
187       •   Default: "b/"
188
189       •   Type: String
190
191
192       Destination prefix to be used in npm diff output.
193
194   diff-text
195       •   Default: false
196
197       •   Type: Boolean
198
199
200       Treat all files as text in npm diff.
201
202   global
203       •   Default: false
204
205       •   Type: Boolean
206
207
208       Operates in "global" mode, so that packages are installed into the pre‐
209       fix folder instead of the current working directory. See npm help fold‐
210       ers for more on the differences in behavior.
211
212       •   packages  are  installed into the {prefix}/lib/node_modules folder,
213           instead of the current working directory.
214
215       •   bin files are linked to {prefix}/bin
216
217       •   man pages are linked to {prefix}/share/man
218
219
220   tag
221       •   Default: "latest"
222
223       •   Type: String
224
225
226       If you ask npm to install a package and don't tell it a  specific  ver‐
227       sion, then it will install the specified tag.
228
229       Also  the tag that is added to the package@version specified by the npm
230       tag command, if no explicit tag is given.
231
232       When used by the npm diff command, this is the tag used  to  fetch  the
233       tarball that will be compared with the local files by default.
234
235   workspace
236       •   Default:
237
238       •   Type: String (can be set multiple times)
239
240
241       Enable running a command in the context of the configured workspaces of
242       the current project while filtering by running only the workspaces  de‐
243       fined by this configuration option.
244
245       Valid values for the workspace config are either:
246
247       •   Workspace names
248
249       •   Path to a workspace directory
250
251       •   Path  to a parent workspace directory (will result in selecting all
252           workspaces within that folder)
253
254
255       When set for the npm init command, this may be set to the folder  of  a
256       workspace  which does not yet exist, to create the folder and set it up
257       as a brand new workspace within the project.
258
259       This value is not exported to the environment for child processes.
260
261   workspaces
262       •   Default: null
263
264       •   Type: null or Boolean
265
266
267       Set to true to run  the  command  in  the  context  of  all  configured
268       workspaces.
269
270       Explicitly  setting  this  to false will cause commands like install to
271       ignore workspaces altogether. When not set explicitly:
272
273       •   Commands that operate on the node_modules  tree  (install,  update,
274           etc.) will link workspaces into the node_modules folder. - Commands
275           that do other things (test, exec, publish, etc.)  will  operate  on
276           the  root  project,  unless one or more workspaces are specified in
277           the workspace config.
278
279
280       This value is not exported to the environment for child processes.
281
282   include-workspace-root
283       •   Default: false
284
285       •   Type: Boolean
286
287
288       Include the workspace root when workspaces are enabled for a command.
289
290       When false, specifying individual workspaces via the workspace  config,
291       or  all  workspaces  via the workspaces flag, will cause npm to operate
292       only on the specified workspaces, and not on the root project.
293
294       This value is not exported to the environment for child processes.
295

NAME

SEE ALSO