ccc7425 · cryptotaxi247/documentation

cli/v8

+1 -1

@@ -1 +1 @@

1 -Subproject commit f2340f816f5a137038945229bf8a0d30160e76e8

1 +Subproject commit 69fa5ff515982d3bfee65f1dbadc71090c1796c9

content/cli/v8/commands/npm-cache.md

+2 -5

@@ -21,11 +21,7 @@ github_path: docs/content/commands/npm-cache.md

21

22

23 ```bash

24 -npm cache add <tarball file>

25 -npm cache add <folder>

26 -npm cache add <tarball url>

27 -npm cache add <git url>

28 -npm cache add <name>@<version>

24 +npm cache add <package-spec>

25 npm cache clean [<key>]

26 npm cache ls [<name>@<version>]

27 npm cache verify

@@ -111,6 +107,7 @@ cache`](/cli/v8/commands/npm-cache)

107

108 ### See Also

109

110 +* [package spec](/cli/v8/using-npm/package-spec)

111 * [npm folders](/cli/v8/configuring-npm/folders)

112 * [npm config](/cli/v8/commands/npm-config)

113 * [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-ci.md

+1 -1

@@ -143,7 +143,7 @@ will *not* run any pre- or post-scripts.

143 * Type: null or String

144

145 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

146 -init <pkg>` commands.

146 +init <package-spec>` commands.

147

148

149

content/cli/v8/commands/npm-deprecate.md

+4 -3

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-deprecate.md

21

22

23 ```bash

24 -npm deprecate <pkg>[@<version>] <message>

24 +npm deprecate <package-spec> <message>

25 ```

26

27

@@ -55,8 +55,8 @@ In this case, a version `my-thing@1.0.0-beta.0` will also be deprecated.

55 You must be the package owner to deprecate something. See the `owner` and

56 `adduser` help topics.

57

58 -To un-deprecate a package, specify an empty string (`""`) for the `message`

59 -argument. Note that you must use double quotes with no space between them to

58 +To un-deprecate a package, specify an empty string (`""`) for the `message`

59 +argument. Note that you must use double quotes with no space between them to

60 format an empty string.

61

62 ### Configuration

@@ -92,6 +92,7 @@ password, npm will prompt on the command line for one.

92

93 ### See Also

94

95 +* [package spec](/cli/v8/using-npm/package-spec)

96 * [npm publish](/cli/v8/commands/npm-publish)

97 * [npm registry](/cli/v8/using-npm/registry)

98 * [npm owner](/cli/v8/commands/npm-owner)

content/cli/v8/commands/npm-dist-tag.md

+9 -8

@@ -21,9 +21,9 @@ github_path: docs/content/commands/npm-dist-tag.md

21

22

23 ```bash

24 -npm dist-tag add <pkg>@<version> [<tag>]

25 -npm dist-tag rm <pkg> <tag>

26 -npm dist-tag ls [<pkg>]

24 +npm dist-tag add <package-spec (with version)> [<tag>]

25 +npm dist-tag rm <package-spec> <tag>

26 +npm dist-tag ls [<package-spec>]

27

28 alias: dist-tags

29 ```

@@ -37,11 +37,11 @@ alias: dist-tags

37

38 Add, remove, and enumerate distribution tags on a package:

39

40 -* add: Tags the specified version of the package with the specified tag, or

41 - the `--tag` config if not specified. If you have two-factor

42 - authentication on auth-and-writes then you’ll need to include a one-time

43 - password on the command line with `--otp <one-time password>`, or at the

44 - OTP prompt.

40 +* add: Tags the specified version of the package with the specified tag,

41 + or the `--tag` config if not specified. If you have two-factor

42 + authentication on auth-and-writes then you’ll need to include a

43 + one-time password on the command line with

44 + `--otp <one-time password>`, or at the OTP prompt.

45

46 * rm: Clear a tag that is no longer in use from the package. If you have

47 two-factor authentication on auth-and-writes then you’ll need to include

@@ -178,6 +178,7 @@ This value is not exported to the environment for child processes.

178

179 ### See Also

180

181 +* [package spec](/cli/v8/using-npm/package-spec)

182 * [npm publish](/cli/v8/commands/npm-publish)

183 * [npm install](/cli/v8/commands/npm-install)

184 * [npm dedupe](/cli/v8/commands/npm-dedupe)

content/cli/v8/commands/npm-explain.md

+6 -4

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-explain.md

21

22

23 ```bash

24 -npm explain <folder | specifier>

24 +npm explain <package-spec>

25

26 alias: why

27 ```

@@ -36,9 +36,10 @@ alias: why

36 This command will print the chain of dependencies causing a given package

37 to be installed in the current project.

38

39 -Positional arguments can be either folders within `node_modules`, or

40 -`name@version-range` specifiers, which will select the dependency

41 -relationships to explain.

39 +If one or more package specs are provided, then only packages matching

40 +one of the specifiers will have their relationships explained.

41 +

42 +The package spec can also refer to a folder within `./node_modules`

43

44 For example, running `npm explain glob` within npm's source tree will show:

45

@@ -120,6 +121,7 @@ This value is not exported to the environment for child processes.

121

122 ### See Also

123

124 +* [package spec](/cli/v8/using-npm/package-spec)

125 * [npm config](/cli/v8/commands/npm-config)

126 * [npmrc](/cli/v8/configuring-npm/npmrc)

127 * [npm folders](/cli/v8/configuring-npm/folders)

content/cli/v8/commands/npm-fund.md

+13 -12

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-fund.md

21

22

23 ```bash

24 -npm fund [[<@scope>/]<pkg>]

24 +npm fund [<package-spec>]

25 ```

26

27

@@ -33,22 +33,22 @@ npm fund [[<@scope>/]<pkg>]

33

34 This command retrieves information on how to fund the dependencies of a

35 given project. If no package name is provided, it will list all

36 -dependencies that are looking for funding in a tree structure, listing the

37 -type of funding and the url to visit. If a package name is provided then it

38 -tries to open its funding url using the `--browser` config param; if there

39 -are multiple funding sources for the package, the user will be instructed

40 -to pass the `--which` option to disambiguate.

36 +dependencies that are looking for funding in a tree structure, listing

37 +the type of funding and the url to visit. If a package name is provided

38 +then it tries to open its funding url using the `--browser` config

39 +param; if there are multiple funding sources for the package, the user

40 +will be instructed to pass the `--which` option to disambiguate.

41

42 The list will avoid duplicated entries and will stack all packages that

43 -share the same url as a single entry. Thus, the list does not have the same

44 -shape of the output from `npm ls`.

43 +share the same url as a single entry. Thus, the list does not have the

44 +same shape of the output from `npm ls`.

45

46 #### Example

47

48 ### Workspaces support

49

50 -It's possible to filter the results to only include a single workspace and its

51 -dependencies using the `workspace` config option.

50 +It's possible to filter the results to only include a single workspace

51 +and its dependencies using the `workspace` config option.

52

53 #### Example:

54

@@ -68,8 +68,8 @@ test-workspaces-fund@1.0.0

68 `-- bar@2.0.0

69 ```

70

71 -And here is an example of the expected result when filtering only by

72 -a specific workspace `a` in the same project:

71 +And here is an example of the expected result when filtering only by a

72 +specific workspace `a` in the same project:

73

74 ```bash

75 $ npm fund -w a

@@ -166,6 +166,7 @@ If there are multiple funding sources, which 1-indexed source URL to open.

166

167 ## See Also

168

169 +* [package spec](/cli/v8/using-npm/package-spec)

170 * [npm install](/cli/v8/commands/npm-install)

171 * [npm docs](/cli/v8/commands/npm-docs)

172 * [npm ls](/cli/v8/commands/npm-ls)

content/cli/v8/commands/npm-init.md

+35 -2

@@ -21,9 +21,8 @@ github_path: docs/content/commands/npm-init.md

21

22

23 ```bash

24 -npm init [--force|-f|--yes|-y|--scope]

24 +npm init <package-spec> (same as `npx <package-spec>)

25 npm init <@scope> (same as `npx <@scope>/create`)

26 -npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)

26

27 aliases: create, innit

28 ```

@@ -214,6 +213,39 @@ mistakes, unnecessary performance degradation, and malicious input.

213 If you don't have a clear idea of what you want to do, it is strongly

214 recommended that you do not use this option!

215

216 +

217 +

218 +

219 +#### `scope`

220 +

221 +* Default: the scope of the current project, if any, or ""

222 +* Type: String

223 +

224 +Associate an operation with a scope for a scoped registry.

225 +

226 +Useful when logging in to or out of a private registry:

227 +

228 +```

229 +# log in, linking the scope to the custom registry

230 +npm login --scope=@mycorp --registry=https://registry.mycorp.com

231 +

232 +# log out, removing the link and the auth token

233 +npm logout --scope=@mycorp

234 +```

235 +

236 +This will cause `@mycorp` to be mapped to the registry for future

237 +installation of packages specified according to the pattern

238 +`@mycorp/package`.

239 +

240 +This will also cause `npm init` to create a scoped package.

241 +

242 +```

243 +# accept all defaults, and create a package named "@foo/whatever",

244 +# instead of just named "whatever"

245 +npm init --scope=@foo --yes

246 +```

247 +

248 +

249

250

251

@@ -294,6 +326,7 @@ This value is not exported to the environment for child processes.

326

327 ### See Also

328

329 +* [package spec](/cli/v8/using-npm/package-spec)

330 * [init-package-json module](http://npm.im/init-package-json)

331 * [package.json](/cli/v8/configuring-npm/package-json)

332 * [npm version](/cli/v8/commands/npm-version)

content/cli/v8/commands/npm-install-ci-test.md

+1 -1

@@ -89,7 +89,7 @@ will *not* run any pre- or post-scripts.

89 * Type: null or String

90

91 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

92 -init <pkg>` commands.

92 +init <package-spec>` commands.

93

94

95

content/cli/v8/commands/npm-install-test.md

+1 -10

@@ -21,16 +21,7 @@ github_path: docs/content/commands/npm-install-test.md

21

22

23 ```bash

24 -npm install-test [<@scope>/]<pkg>

25 -npm install-test [<@scope>/]<pkg>@<tag>

26 -npm install-test [<@scope>/]<pkg>@<version>

27 -npm install-test [<@scope>/]<pkg>@<version range>

28 -npm install-test <alias>@npm:<name>

29 -npm install-test <folder>

30 -npm install-test <tarball file>

31 -npm install-test <tarball url>

32 -npm install-test <git:// url>

33 -npm install-test <github username>/<github project>

24 +npm install-test [<package-spec> ...]

25

26 alias: it

27 ```

content/cli/v8/commands/npm-install.md

+1 -10

@@ -22,16 +22,7 @@ github_path: docs/content/commands/npm-install.md

22

23

24 ```bash

25 -npm install [<@scope>/]<pkg>

26 -npm install [<@scope>/]<pkg>@<tag>

27 -npm install [<@scope>/]<pkg>@<version>

28 -npm install [<@scope>/]<pkg>@<version range>

29 -npm install <alias>@npm:<name>

30 -npm install <folder>

31 -npm install <tarball file>

32 -npm install <tarball url>

33 -npm install <git:// url>

34 -npm install <github username>/<github project>

25 +npm install [<package-spec> ...]

26

27 aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall

28 ```

content/cli/v8/commands/npm-link.md

+7 -7

@@ -21,8 +21,7 @@ github_path: docs/content/commands/npm-link.md

21

22

23 ```bash

24 -npm link (in package dir)

25 -npm link [<@scope>/]<pkg>[@<version>]

24 +npm link [<package-spec>]

25

26 alias: ln

27 ```

@@ -39,11 +38,11 @@ test iteratively without having to continually rebuild.

38

39 Package linking is a two-step process.

40

42 -First, `npm link` in a package folder will create a symlink in the global

43 -folder `{prefix}/lib/node_modules/<package>` that links to the package

44 -where the `npm link` command was executed. It will also link any bins in

45 -the package to `{prefix}/bin/{name}`. Note that `npm link` uses the global

46 -prefix (see `npm prefix -g` for its value).

41 +First, `npm link` in a package folder with no arguments will create a

42 +symlink in the global folder `{prefix}/lib/node_modules/<package>` that

43 +links to the package where the `npm link` command was executed. It will

44 +also link any bins in the package to `{prefix}/bin/{name}`. Note that

45 +`npm link` uses the global prefix (see `npm prefix -g` for its value).

46

47 Next, in some other location, `npm link package-name` will create a

48 symbolic link from globally-installed `package-name` to `node_modules/` of

@@ -409,6 +408,7 @@ symlink. This option has no effect on workspaces.

408

409 ### See Also

410

411 +* [package spec](/cli/v8/using-npm/package-spec)

412 * [npm developers](/cli/v8/using-npm/developers)

413 * [package.json](/cli/v8/configuring-npm/package-json)

414 * [npm install](/cli/v8/commands/npm-install)

content/cli/v8/commands/npm-ls.md

+2 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-ls.md

21

22

23 ```bash

24 -npm ls [[<@scope>/]<pkg> ...]

24 +npm ls <package-spec>

25

26 alias: list

27 ```

@@ -311,6 +311,7 @@ symlink. This option has no effect on workspaces.

311

312 ### See Also

313

314 +* [package spec](/cli/v8/using-npm/package-spec)

315 * [npm explain](/cli/v8/commands/npm-explain)

316 * [npm config](/cli/v8/commands/npm-config)

317 * [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-outdated.md

+2 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-outdated.md

21

22

23 ```bash

24 -npm outdated [[<@scope>/]<pkg> ...]

24 +npm outdated [<package-spec> ...]

25 ```

26

27

@@ -202,6 +202,7 @@ This value is not exported to the environment for child processes.

202

203 ### See Also

204

205 +* [package spec](/cli/v8/using-npm/package-spec)

206 * [npm update](/cli/v8/commands/npm-update)

207 * [npm dist-tag](/cli/v8/commands/npm-dist-tag)

208 * [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/commands/npm-owner.md

+4 -3

@@ -21,9 +21,9 @@ github_path: docs/content/commands/npm-owner.md

21

22

23 ```bash

24 -npm owner add <user> [<@scope>/]<pkg>

25 -npm owner rm <user> [<@scope>/]<pkg>

26 -npm owner ls [<@scope>/]<pkg>

24 +npm owner add <user> <package-spec>

25 +npm owner rm <user> <package-spec>

26 +npm owner ls <package-spec>

27

28 alias: author

29 ```

@@ -133,6 +133,7 @@ This value is not exported to the environment for child processes.

133

134 ### See Also

135

136 +* [package spec](/cli/v8/using-npm/package-spec)

137 * [npm profile](/cli/v8/commands/npm-profile)

138 * [npm publish](/cli/v8/commands/npm-publish)

139 * [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/commands/npm-pack.md

+2 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-pack.md

21

22

23 ```bash

24 -npm pack [[<@scope>/]<pkg>...]

24 +npm pack <package-spec>

25 ```

26

27

@@ -154,6 +154,7 @@ If no arguments are supplied, then npm packs the current package folder.

154

155 ### See Also

156

157 +* [package spec](/cli/v8/using-npm/package-spec)

158 * [npm-packlist package](http://npm.im/npm-packlist)

159 * [npm cache](/cli/v8/commands/npm-cache)

160 * [npm publish](/cli/v8/commands/npm-publish)

content/cli/v8/commands/npm-publish.md

+18 -33

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-publish.md

21

22

23 ```bash

24 -npm publish [<folder>]

24 +npm publish <package-spec>

25 ```

26

27

@@ -33,42 +33,26 @@ npm publish [<folder>]

33

34 Publishes a package to the registry so that it can be installed by name.

35

36 -By default npm will publish to the public registry. This can be overridden

37 -by specifying a different default registry or using a

38 -[`scope`](/cli/v8/using-npm/scope) in the name (see

36 +By default npm will publish to the public registry. This can be

37 +overridden by specifying a different default registry or using a

38 +[`scope`](/cli/v8/using-npm/scope) in the name, combined with a

39 +scope-configured registry (see

40 [`package.json`](/cli/v8/configuring-npm/package-json)).

41

41 -* `<folder>`: A folder containing a package.json file

42

43 -* `<tarball>`: A url or file path to a gzipped tar archive containing a

44 - single folder with a package.json file inside.

43 +A `package` is interpreted the same way as other commands (like

44 +`npm install` and can be:

45

46 -* `[--tag <tag>]`: Registers the published package with the given tag, such

47 - that `npm install <name>@<tag>` will install this version. By default,

48 - `npm publish` updates and `npm install` installs the `latest` tag. See

49 - [`npm-dist-tag`](npm-dist-tag) for details about tags.

50 -

51 -* `[--access <public|restricted>]`: Tells the registry whether this package

52 - should be published as public or restricted. Only applies to scoped

53 - packages, which default to `restricted`. If you don't have a paid

54 - account, you must publish with `--access public` to publish scoped

55 - packages.

56 -

57 -* `[--otp <otpcode>]`: If you have two-factor authentication enabled in

58 - `auth-and-writes` mode then you can provide a code from your

59 - authenticator with this. If you don't include this and you're running

60 - from a TTY then you'll be prompted.

61 -

62 -* `[--dry-run]`: As of `npm@6`, does everything publish would do except

63 - actually publishing to the registry. Reports the details of what would

64 - have been published.

65 -

66 -* `[--workspaces]`: Enables workspace context while publishing. All

67 - workspace packages will be published.

68 -

69 -* `[--workspace]`: Enables workspaces context and limits results to only

70 - those specified by this config item. Only the packages in the

71 - workspaces given will be published.

46 +* a) a folder containing a program described by a

47 + [`package.json`](/cli/v8/configuring-npm/package-json) file

48 +* b) a gzipped tarball containing (a)

49 +* c) a url that resolves to (b)

50 +* d) a `<name>@<version>` that is published on the registry (see

51 + [`registry`](/cli/v8/using-npm/registry)) with (c)

52 +* e) a `<name>@<tag>` (see [`npm dist-tag`](/cli/v8/commands/npm-dist-tag)) that

53 + points to (d)

54 +* f) a `<name>` that has a "latest" tag satisfying (e)

55 +* g) a `<git remote url>` that resolves to (a)

56

57 The publish will fail if the package name and version combination already

58 exists in the specified registry.

@@ -257,6 +241,7 @@ This value is not exported to the environment for child processes.

241

242 ### See Also

243

244 +* [package spec](/cli/v8/using-npm/package-spec)

245 * [npm-packlist package](http://npm.im/npm-packlist)

246 * [npm registry](/cli/v8/using-npm/registry)

247 * [npm scope](/cli/v8/using-npm/scope)

content/cli/v8/commands/npm-rebuild.md

+4 -4

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-rebuild.md

21

22

23 ```bash

24 -npm rebuild [[<@scope>/]<name>[@<version>] ...]

24 +npm rebuild [<package-spec>] ...]

25

26 alias: rb

27 ```

@@ -39,9 +39,8 @@ C++ addons with the new binary. It is also useful when installing with

39 `--ignore-scripts` and `--no-bin-links`, to explicitly choose which

40 packages to build and/or link bins.

41

42 -If one or more package names (and optionally version ranges) are provided,

43 -then only packages with a name and version matching one of the specifiers

44 -will be rebuilt.

42 +If one or more package specs are provided, then only packages with a

43 +name and version matching one of the specifiers will be rebuilt.

44

45 ### Configuration

46

@@ -188,4 +187,5 @@ symlink. This option has no effect on workspaces.

187

188 ### See Also

189

190 +* [package spec](/cli/v8/using-npm/package-spec)

191 * [npm install](/cli/v8/commands/npm-install)

content/cli/v8/commands/npm-restart.md

+1 -1

@@ -79,7 +79,7 @@ will *not* run any pre- or post-scripts.

79 * Type: null or String

80

81 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

82 -init <pkg>` commands.

82 +init <package-spec>` commands.

83

84

85

content/cli/v8/commands/npm-run-script.md

+1 -1

@@ -256,7 +256,7 @@ will *not* run any pre- or post-scripts.

256 * Type: null or String

257

258 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

259 -init <pkg>` commands.

259 +init <package-spec>` commands.

260

261

262

content/cli/v8/commands/npm-star.md

+2 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-star.md

21

22

23 ```bash

24 -npm star [<pkg>...]

24 +npm star [<package-spec>...]

25 ```

26

27

@@ -97,6 +97,7 @@ password, npm will prompt on the command line for one.

97

98 ### See Also

99

100 +* [package spec](/cli/v8/using-npm/package-spec)

101 * [npm unstar](/cli/v8/commands/npm-unstar)

102 * [npm stars](/cli/v8/commands/npm-stars)

103 * [npm view](/cli/v8/commands/npm-view)

content/cli/v8/commands/npm-start.md

+1 -1

@@ -90,7 +90,7 @@ will *not* run any pre- or post-scripts.

90 * Type: null or String

91

92 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

93 -init <pkg>` commands.

93 +init <package-spec>` commands.

94

95

96

content/cli/v8/commands/npm-stop.md

+1 -1

@@ -83,7 +83,7 @@ will *not* run any pre- or post-scripts.

83 * Type: null or String

84

85 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

86 -init <pkg>` commands.

86 +init <package-spec>` commands.

87

88

89

content/cli/v8/commands/npm-test.md

+1 -1

@@ -80,7 +80,7 @@ will *not* run any pre- or post-scripts.

80 * Type: null or String

81

82 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

83 -init <pkg>` commands.

83 +init <package-spec>` commands.

84

85

86

content/cli/v8/commands/npm-unpublish.md

+2 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-unpublish.md

21

22

23 ```bash

24 -npm unpublish [<@scope>/]<pkg>[@<version>]

24 +npm unpublish [<package-spec>]

25 ```

26

27

@@ -156,6 +156,7 @@ This value is not exported to the environment for child processes.

156

157 ### See Also

158

159 +* [package spec](/cli/v8/using-npm/package-spec)

160 * [npm deprecate](/cli/v8/commands/npm-deprecate)

161 * [npm publish](/cli/v8/commands/npm-publish)

162 * [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/commands/npm-unstar.md

+1 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-unstar.md

21

22

23 ```bash

24 -npm unstar [<pkg>...]

24 +npm unstar [<package-spec>...]

25 ```

26

27

content/cli/v8/commands/npm-view.md

+2 -1

@@ -21,7 +21,7 @@ github_path: docs/content/commands/npm-view.md

21

22

23 ```bash

24 -npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]

24 +npm view [<package-spec>] [<field>[.subfield]...]

25

26 aliases: info, show, v

27 ```

@@ -213,6 +213,7 @@ the field name.

213

214 ### See Also

215

216 +* [package spec](/cli/v8/using-npm/package-spec)

217 * [npm search](/cli/v8/commands/npm-search)

218 * [npm registry](/cli/v8/using-npm/registry)

219 * [npm config](/cli/v8/commands/npm-config)

content/cli/v8/configuring-npm/package-json.md

+1 -1

@@ -232,7 +232,7 @@ npm also sets a top-level "maintainers" field with your npm user info.

232

233 ### funding

234

235 -You can specify an object containing an URL that provides up-to-date

235 +You can specify an object containing a URL that provides up-to-date

236 information about ways to help fund development of your package, or a

237 string URL, or an array of these:

238

content/cli/v8/using-npm/config.md

+1 -1

@@ -1526,7 +1526,7 @@ npm init --scope=@foo --yes

1526 * Type: null or String

1527

1528 The shell to use for scripts run with the `npm exec`, `npm run` and `npm

1529 -init <pkg>` commands.

1529 +init <package-spec>` commands.

1530

1531

1532

content/cli/v8/using-npm/package-spec.md new

+114

@@ -0,0 +1,114 @@

1 +---

2 +title: package-spec

3 +section: 7

4 +description: Package name specifier

5 +redirect_from:

6 + - /using-npm/package-spec

7 + - /using-npm/package-spec.html

8 + - /misc/package-spec

9 + - /misc/package-spec.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/package-spec.md

13 +---

14 +

15 +

16 +### Description

17 +

18 +Commands like `npm install` and the dependency sections in the

19 +`package.json` use a package name specifier. This can be many different

20 +things that all refer to a "package". Examples include a package name,

21 +git url, tarball, or local directory. These will generally be referred

22 +to as `<package-spec>` in the help output for the npm commands that use

23 +this package name specifier.

24 +

25 +### Package name

26 +

27 +* `[<@scope>/]<pkg>`

28 +* `[<@scope>/]<pkg>@<tag>`

29 +* `[<@scope>/]<pkg>@<version>`

30 +* `[<@scope>/]<pkg>@<version range>`

31 +

32 +Refers to a package by name, with or without a scope, and optionally

33 +tag, version, or version range. This is typically used in combination

34 +with the [registry](/cli/v8/using-npm/config#registry) config to refer to a

35 +package in a registry.

36 +

37 +Examples:

38 +* `npm`

39 +* `@npmcli/arborist`

40 +* `@npmcli/arborist@latest`

41 +* `npm@6.13.1`

42 +* `npm@^4.0.0`

43 +

44 +### Aliases

45 +

46 +* `<alias>@npm:<name>`

47 +

48 +Primarily used by commands like `npm install` and in the dependency

49 +sections in the `package.json`, this refers to a package by an alias.

50 +The `<alias>` is the name of the package as it is reified in the

51 +`node_modules` folder, and the `<name>` refers to a package name as

52 +found in the configured registry.

53 +

54 +See `Package name` above for more info on referring to a package by

55 +name, and [registry](/cli/v8/using-npm/config#registry) for configuring which

56 +registry is used when referring to a package by name.

57 +

58 +Examples:

59 +* `semver:@npm:@npmcli/semver-with-patch`

60 +* `semver:@npm:semver@7.2.2`

61 +* `semver:@npm:semver@legacy`

62 +

63 +### Folders

64 +

65 +* `<folder>`

66 +

67 +This refers to a package on the local filesystem. Specifically this is

68 +a folder with a `package.json` file in it. This *should* always be

69 +prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion.

70 +npm currently will parse a string with more than one `/` in it as a

71 +folder, but this is legacy behavior that may be removed in a future

72 +version.

73 +

74 +Examples:

75 +

76 +* `./my-package`

77 +* `/opt/npm/my-package`

78 +

79 +### Tarballs

80 +

81 +* `<tarball file>`

82 +* `<tarball url>`

83 +

84 +Examples:

85 +

86 +* `./my-package.tgz`

87 +* `https://registry.npmjs.org/semver/-/semver-1.0.0.tgz`

88 +

89 +Refers to a package in a tarball format, either on the local filesystem

90 +or remotely via url. This is the format that packages exist in when

91 +uploaded to a registry.

92 +

93 +### git urls

94 +

95 +* `<git:// url>`

96 +* `<github username>/<github project>`

97 +

98 +Refers to a package in a git repo. This can be a full git url, git

99 +shorthand, or a username/package on GitHub. You can specify a

100 +git tag, branch, or other git ref by appending `#ref`.

101 +

102 +Examples:

103 +

104 +* `https://github.com/npm/cli.git`

105 +* `git@github.com:npm/cli.git`

106 +* `git+ssh://git@github.com/npm/cli#v6.0.0`

107 +* `github:npm/cli#HEAD`

108 +* `npm/cli#c12ea07`

109 +

110 +### See also

111 +

112 +[npm-package-arg](https://npm.im/npm-package-arg)

113 +[scope](/cli/v8/using-npm/scope)

114 +[config](/cli/v8/using-npm/config)

src/gatsby-theme-doctornpm/nav.yml

+3

@@ -1007,6 +1007,9 @@

1007 - title: Registry

1008 url: /cli/v8/using-npm/registry

1009 description: The JavaScript Package Registry

1010 + - title: Package spec

1011 + url: /cli/v8/using-npm/package-spec

1012 + description: Package name specifier

1013 - title: Config

1014 url: /cli/v8/using-npm/config

1015 description: About npm configuration

CLI documentation update from CI