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

See Also

341       • npm help outdated
342
343       • npm help install
344
345       • npm help config
346
347       • npm help registry
348
349
350
351
352                                 January 2022                      NPM-DIFF(1)
Impressum