server/sa-charts
14
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

swarm

Browse Source
This commit is contained in:
marsal wang
2023-07-26 10:07:34 +08:00
parent f884cb1020
commit 1e5a703cce
5384 changed files with 618283 additions and 4002 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1732
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/config.7 generated vendored Normal file
View File

File diff suppressed because it is too large Load Diff

291
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/developers.7 generated vendored Normal file
View File

@ -0,0 +1,291 @@
.TH "DEVELOPERS" "7" "August 2021" "" ""
.SH "NAME"
\fBdevelopers\fR \- Developer Guide
.SS Description
.P
So, you've decided to use npm to develop (and maybe publish/deploy)
your project\.
.P
Fantastic!
.P
There are a few things that you need to do above the simple steps
that your users will do to install your program\.
.SS About These Documents
.P
These are man pages\. If you install npm, you should be able to
then do \fBman npm\-thing\fP to get the documentation on a particular
topic, or \fBnpm help thing\fP to see the same information\.
.SS What is a package
.P
A package is:
.RS 0
.IP \(bu 2
a) a folder containing a program described by a package\.json file
.IP \(bu 2
b) a gzipped tarball containing (a)
.IP \(bu 2
c) a url that resolves to (b)
.IP \(bu 2
d) a \fB<name>@<version>\fP that is published on the registry with (c)
.IP \(bu 2
e) a \fB<name>@<tag>\fP that points to (d)
.IP \(bu 2
f) a \fB<name>\fP that has a "latest" tag satisfying (e)
.IP \(bu 2
g) a \fBgit\fP url that, when cloned, results in (a)\.
.RE
.P
Even if you never publish your package, you can still get a lot of
benefits of using npm if you just want to write a node program (a), and
perhaps if you also want to be able to easily install it elsewhere
after packing it up into a tarball (b)\.
.P
Git urls can be of the form:
.P
.RS 2
.nf
git://github\.com/user/project\.git#commit\-ish
git+ssh://user@hostname:project\.git#commit\-ish
git+http://user@hostname/project/blah\.git#commit\-ish
git+https://user@hostname/project/blah\.git#commit\-ish
.fi
.RE
.P
The \fBcommit\-ish\fP can be any tag, sha, or branch which can be supplied as
an argument to \fBgit checkout\fP\|\. The default is \fBmaster\fP\|\.
.SS The package\.json File
.P
You need to have a \fBpackage\.json\fP file in the root of your project to do
much of anything with npm\. That is basically the whole interface\.
.P
See npm help \fBpackage\.json\fP for details about what goes in that file\. At the very
least, you need:
.RS 0
.IP \(bu 2
name:
This should be a string that identifies your project\. Please do not
use the name to specify that it runs on node, or is in JavaScript\.
You can use the "engines" field to explicitly state the versions of
node (or whatever else) that your program requires, and it's pretty
well assumed that it's JavaScript\.
It does not necessarily need to match your github repository name\.
So, \fBnode\-foo\fP and \fBbar\-js\fP are bad names\. \fBfoo\fP or \fBbar\fP are better\.
.IP \(bu 2
version:
A semver\-compatible version\.
.IP \(bu 2
engines:
Specify the versions of node (or whatever else) that your program
runs on\. The node API changes a lot, and there may be bugs or new
functionality that you depend on\. Be explicit\.
.IP \(bu 2
author:
Take some credit\.
.IP \(bu 2
scripts:
If you have a special compilation or installation script, then you
should put it in the \fBscripts\fP object\. You should definitely have at
least a basic smoke\-test command as the "scripts\.test" field\.
See npm help scripts\.
.IP \(bu 2
main:
If you have a single module that serves as the entry point to your
program (like what the "foo" package gives you at require("foo")),
then you need to specify that in the "main" field\.
.IP \(bu 2
directories:
This is an object mapping names to folders\. The best ones to include are
"lib" and "doc", but if you use "man" to specify a folder full of man pages,
they'll get installed just like these ones\.
.RE
.P
You can use \fBnpm init\fP in the root of your package in order to get you
started with a pretty basic package\.json file\. See npm help \fBinit\fP for
more info\.
.SS Keeping files \fIout\fR of your package
.P
Use a \fB\|\.npmignore\fP file to keep stuff out of your package\. If there's
no \fB\|\.npmignore\fP file, but there \fIis\fR a \fB\|\.gitignore\fP file, then npm will
ignore the stuff matched by the \fB\|\.gitignore\fP file\. If you \fIwant\fR to
include something that is excluded by your \fB\|\.gitignore\fP file, you can
create an empty \fB\|\.npmignore\fP file to override it\. Like \fBgit\fP, \fBnpm\fP looks
for \fB\|\.npmignore\fP and \fB\|\.gitignore\fP files in all subdirectories of your
package, not only the root directory\.
.P
\fB\|\.npmignore\fP files follow the same pattern rules \fIhttps://git\-scm\.com/book/en/v2/Git\-Basics\-Recording\-Changes\-to\-the\-Repository#Ignoring\-Files\fR
as \fB\|\.gitignore\fP files:
.RS 0
.IP \(bu 2
Blank lines or lines starting with \fB#\fP are ignored\.
.IP \(bu 2
Standard glob patterns work\.
.IP \(bu 2
You can end patterns with a forward slash \fB/\fP to specify a directory\.
.IP \(bu 2
You can negate a pattern by starting it with an exclamation point \fB!\fP\|\.
.RE
.P
By default, the following paths and files are ignored, so there's no
need to add them to \fB\|\.npmignore\fP explicitly:
.RS 0
.IP \(bu 2
\fB\|\.*\.swp\fP
.IP \(bu 2
\fB\|\._*\fP
.IP \(bu 2
\fB\|\.DS_Store\fP
.IP \(bu 2
\fB\|\.git\fP
.IP \(bu 2
\fB\|\.hg\fP
.IP \(bu 2
\fB\|\.npmrc\fP
.IP \(bu 2
\fB\|\.lock\-wscript\fP
.IP \(bu 2
\fB\|\.svn\fP
.IP \(bu 2
\fB\|\.wafpickle\-*\fP
.IP \(bu 2
\fBconfig\.gypi\fP
.IP \(bu 2
\fBCVS\fP
.IP \(bu 2
\fBnpm\-debug\.log\fP
.RE
.P
Additionally, everything in \fBnode_modules\fP is ignored, except for
bundled dependencies\. npm automatically handles this for you, so don't
bother adding \fBnode_modules\fP to \fB\|\.npmignore\fP\|\.
.P
The following paths and files are never ignored, so adding them to
\fB\|\.npmignore\fP is pointless:
.RS 0
.IP \(bu 2
\fBpackage\.json\fP
.IP \(bu 2
\fBREADME\fP (and its variants)
.IP \(bu 2
\fBCHANGELOG\fP (and its variants)
.IP \(bu 2
\fBLICENSE\fP / \fBLICENCE\fP
.RE
.P
If, given the structure of your project, you find \fB\|\.npmignore\fP to be a
maintenance headache, you might instead try populating the \fBfiles\fP
property of \fBpackage\.json\fP, which is an array of file or directory names
that should be included in your package\. Sometimes a whitelist is easier
to manage than a blacklist\.
.SS Testing whether your \fB\|\.npmignore\fP or \fBfiles\fP config works
.P
If you want to double check that your package will include only the files
you intend it to when published, you can run the \fBnpm pack\fP command locally
which will generate a tarball in the working directory, the same way it
does for publishing\.
.SS Link Packages
.P
\fBnpm link\fP is designed to install a development package and see the
changes in real time without having to keep re\-installing it\. (You do
need to either re\-link or \fBnpm rebuild \-g\fP to update compiled packages,
of course\.)
.P
More info at npm help \fBlink\fP\|\.
.SS Before Publishing: Make Sure Your Package Installs and Works
.P
\fBThis is important\.\fR
.P
If you can not install it locally, you'll have
problems trying to publish it\. Or, worse yet, you'll be able to
publish it, but you'll be publishing a broken or pointless package\.
So don't do that\.
.P
In the root of your package, do this:
.P
.RS 2
.nf
npm install \. \-g
.fi
.RE
.P
That'll show you that it's working\. If you'd rather just create a symlink
package that points to your working directory, then do this:
.P
.RS 2
.nf
npm link
.fi
.RE
.P
Use \fBnpm ls \-g\fP to see if it's there\.
.P
To test a local install, go into some other folder, and then do:
.P
.RS 2
.nf
cd \.\./some\-other\-folder
npm install \.\./my\-package
.fi
.RE
.P
to install it locally into the node_modules folder in that other place\.
.P
Then go into the node\-repl, and try using require("my\-thing") to
bring in your module's main module\.
.SS Create a User Account
.P
Create a user with the adduser command\. It works like this:
.P
.RS 2
.nf
npm adduser
.fi
.RE
.P
and then follow the prompts\.
.P
This is documented better in npm help adduser\.
.SS Publish your package
.P
This part's easy\. In the root of your folder, do this:
.P
.RS 2
.nf
npm publish
.fi
.RE
.P
You can give publish a url to a tarball, or a filename of a tarball,
or a path to a folder\.
.P
Note that pretty much \fBeverything in that folder will be exposed\fR
by default\. So, if you have secret stuff in there, use a
\fB\|\.npmignore\fP file to list out the globs to ignore, or publish
from a fresh checkout\.
.SS Brag about it
.P
Send emails, write blogs, blab in IRC\.
.P
Tell the world how easy it is to install your program!
.SS See also
.RS 0
.IP \(bu 2
npm help npm
.IP \(bu 2
npm help init
.IP \(bu 2
npm help package\.json
.IP \(bu 2
npm help scripts
.IP \(bu 2
npm help publish
.IP \(bu 2
npm help adduser
.IP \(bu 2
npm help registry
.RE

149
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/disputes.7 generated vendored Normal file
View File

@ -0,0 +1,149 @@
.TH "DISPUTES" "7" "August 2021" "" ""
.SH "NAME"
\fBdisputes\fR \- Handling Module Name Disputes
.P
This document describes the steps that you should take to resolve module name
disputes with other npm publishers\. It also describes special steps you should
take about names you think infringe your trademarks\.
.P
This document is a clarification of the acceptable behavior outlined in the
npm Code of Conduct \fIhttps://www\.npmjs\.com/policies/conduct\fR, and nothing in
this document should be interpreted to contradict any aspect of the npm Code of
Conduct\.
.SS TL;DR
.RS 0
.IP 1. 3
Get the author email with \fBnpm owner ls <pkgname>\fP
.IP 2. 3
Email the author, CC support@npmjs\.com
.IP 3. 3
After a few weeks, if there's no resolution, we'll sort it out\.
.RE
.P
Don't squat on package names\. Publish code or move out of the way\.
.SS Description
.P
There sometimes arise cases where a user publishes a module, and then later,
some other user wants to use that name\. Here are some common ways that happens
(each of these is based on actual events\.)
.RS 0
.IP 1. 3
Alice writes a JavaScript module \fBfoo\fP, which is not node\-specific\. Alice
doesn't use node at all\. Yusuf wants to use \fBfoo\fP in node, so he wraps it in
an npm module\. Some time later, Alice starts using node, and wants to take
over management of her program\.
.IP 2. 3
Yusuf writes an npm module \fBfoo\fP, and publishes it\. Perhaps much later, Alice
finds a bug in \fBfoo\fP, and fixes it\. She sends a pull request to Yusuf, but
Yusuf doesn't have the time to deal with it, because he has a new job and a
new baby and is focused on his new Erlang project, and kind of not involved
with node any more\. Alice would like to publish a new \fBfoo\fP, but can't,
because the name is taken\.
.IP 3. 3
Yusuf writes a 10\-line flow\-control library, and calls it \fBfoo\fP, and
publishes it to the npm registry\. Being a simple little thing, it never
really has to be updated\. Alice works for Foo Inc, the makers of the
critically acclaimed and widely\-marketed \fBfoo\fP JavaScript toolkit framework\.
They publish it to npm as \fBfoojs\fP, but people are routinely confused when
\fBnpm install foo\fP is some different thing\.
.IP 4. 3
Yusuf writes a parser for the widely\-known \fBfoo\fP file format, because he
needs it for work\. Then, he gets a new job, and never updates the prototype\.
Later on, Alice writes a much more complete \fBfoo\fP parser, but can't publish,
because Yusuf's \fBfoo\fP is in the way\.
.IP 5. 3
\fBnpm owner ls foo\fP\|\. This will tell Alice the email address of the owner
(Yusuf)\.
.IP 6. 3
Alice emails Yusuf, explaining the situation \fBas respectfully as possible\fR,
and what she would like to do with the module name\. She adds the npm support
staff support@npmjs\.com to the CC list of the email\. Mention in the email
that Yusuf can run npm owner \fBadd alice foo\fP to add Alice as an owner of the
foo package\.
.IP 7. 3
After a reasonable amount of time, if Yusuf has not responded, or if Yusuf
and Alice can't come to any sort of resolution, email support
support@npmjs\.com and we'll sort it out\. ("Reasonable" is usually at least
4 weeks\.)
.RE
.SS Reasoning
.P
In almost every case so far, the parties involved have been able to reach an
amicable resolution without any major intervention\. Most people really do want
to be reasonable, and are probably not even aware that they're in your way\.
.P
Module ecosystems are most vibrant and powerful when they are as self\-directed
as possible\. If an admin one day deletes something you had worked on, then that
is going to make most people quite upset, regardless of the justification\. When
humans solve their problems by talking to other humans with respect, everyone
has the chance to end up feeling good about the interaction\.
.SS Exceptions
.P
Some things are not allowed, and will be removed without discussion if they are
brought to the attention of the npm registry admins, including but not limited
to:
.RS 0
.IP 1. 3
Malware (that is, a package designed to exploit or harm the machine on which
it is installed)\.
.IP 2. 3
Violations of copyright or licenses (for example, cloning an MIT\-licensed
program, and then removing or changing the copyright and license statement)\.
.IP 3. 3
Illegal content\.
.IP 4. 3
"Squatting" on a package name that you plan to use, but aren't actually
using\. Sorry, I don't care how great the name is, or how perfect a fit it is
for the thing that someday might happen\. If someone wants to use it today,
and you're just taking up space with an empty tarball, you're going to be
evicted\.
.IP 5. 3
Putting empty packages in the registry\. Packages must have SOME
functionality\. It can be silly, but it can't be nothing\. (See also:
squatting\.)
.IP 6. 3
Doing weird things with the registry, like using it as your own personal
application database or otherwise putting non\-packagey things into it\.
.IP 7. 3
Other things forbidden by the npm
Code of Conduct \fIhttps://www\.npmjs\.com/policies/conduct\fR such as hateful
language, pornographic content, or harassment\.
.RE
.P
If you see bad behavior like this, please report it to abuse@npmjs\.com right
away\. \fBYou are never expected to resolve abusive behavior on your own\. We are
here to help\.\fR
.SS Trademarks
.P
If you think another npm publisher is infringing your trademark, such as by
using a confusingly similar package name, email abuse@npmjs\.com with a link to
the package or user account on https://www\.npmjs\.com/ \fIhttps://www\.npmjs\.com/\fR\|\.
Attach a copy of your trademark registration certificate\.
.P
If we see that the package's publisher is intentionally misleading others by
misusing your registered mark without permission, we will transfer the package
name to you\. Otherwise, we will contact the package publisher and ask them to
clear up any confusion with changes to their package's \fBREADME\fP file or
metadata\.
.SS Changes
.P
This is a living document and may be updated from time to time\. Please refer to
the git history for this document \fIhttps://github\.com/npm/cli/commits/latest/doc/misc/npm\-disputes\.md\fR
to view the changes\.
.SS License
.P
Copyright (C) npm, Inc\., All rights reserved
.P
This document may be reused under a Creative Commons Attribution\-ShareAlike
License\.
.SS See also
.RS 0
.IP \(bu 2
npm help registry
.IP \(bu 2
npm help owner
.RE

146
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/orgs.7 generated vendored Normal file
View File

@ -0,0 +1,146 @@
.TH "ORGS" "7" "August 2021" "" ""
.SH "NAME"
\fBorgs\fR \- Working with Teams & Orgs
.SS Description
.P
There are three levels of org users:
.RS 0
.IP 1. 3
Super admin, controls billing & adding people to the org\.
.IP 2. 3
Team admin, manages team membership & package access\.
.IP 3. 3
Developer, works on packages they are given access to\.
.RE
.P
The super admin is the only person who can add users to the org because it impacts the monthly bill\. The super admin will use the website to manage membership\. Every org has a \fBdevelopers\fP team that all users are automatically added to\.
.P
The team admin is the person who manages team creation, team membership, and package access for teams\. The team admin grants package access to teams, not individuals\.
.P
The developer will be able to access packages based on the teams they are on\. Access is either read\-write or read\-only\.
.P
There are two main commands:
.RS 0
.IP 1. 3
\fBnpm team\fP see npm help team for more details
.IP 2. 3
\fBnpm access\fP see npm help access for more details
.RE
.SS Team Admins create teams
.RS 0
.IP \(bu 2
Check who you’ve added to your org:
.RE
.P
.RS 2
.nf
npm team ls <org>:developers
.fi
.RE
.RS 0
.IP \(bu 2
Each org is automatically given a \fBdevelopers\fP team, so you can see the whole list of team members in your org\. This team automatically gets read\-write access to all packages, but you can change that with the \fBaccess\fP command\.
.IP \(bu 2
Create a new team:
.RE
.P
.RS 2
.nf
npm team create <org:team>
.fi
.RE
.RS 0
.IP \(bu 2
Add members to that team:
.RE
.P
.RS 2
.nf
npm team add <org:team> <user>
.fi
.RE
.SS Publish a package and adjust package access
.RS 0
.IP \(bu 2
In package directory, run
.RE
.P
.RS 2
.nf
npm init \-\-scope=<org>
.fi
.RE
.P
to scope it for your org & publish as usual
.RS 0
.IP \(bu 2
Grant access:
.RE
.P
.RS 2
.nf
npm access grant <read\-only|read\-write> <org:team> [<package>]
.fi
.RE
.RS 0
.IP \(bu 2
Revoke access:
.RE
.P
.RS 2
.nf
npm access revoke <org:team> [<package>]
.fi
.RE
.SS Monitor your package access
.RS 0
.IP \(bu 2
See what org packages a team member can access:
.RE
.P
.RS 2
.nf
npm access ls\-packages <org> <user>
.fi
.RE
.RS 0
.IP \(bu 2
See packages available to a specific team:
.RE
.P
.RS 2
.nf
npm access ls\-packages <org:team>
.fi
.RE
.RS 0
.IP \(bu 2
Check which teams are collaborating on a package:
.RE
.P
.RS 2
.nf
npm access ls\-collaborators <pkg>
.fi
.RE
.SS See also
.RS 0
.IP \(bu 2
npm help team
.IP \(bu 2
npm help access
.IP \(bu 2
npm help scope
.RE

104
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/registry.7 generated vendored Normal file
View File

@ -0,0 +1,104 @@
.TH "REGISTRY" "7" "August 2021" "" ""
.SH "NAME"
\fBregistry\fR \- The JavaScript Package Registry
.SS Description
.P
To resolve packages by name and version, npm talks to a registry website
that implements the CommonJS Package Registry specification for reading
package info\.
.P
npm is configured to use npm, Inc\.'s public registry at
https://registry\.npmjs\.org by default\. Use of the npm public registry is
subject to terms of use available at https://www\.npmjs\.com/policies/terms\|\.
.P
You can configure npm to use any compatible registry you like, and even run
your own registry\. Use of someone else's registry may be governed by their
terms of use\.
.P
npm's package registry implementation supports several
write APIs as well, to allow for publishing packages and managing user
account information\.
.P
The npm public registry is powered by a CouchDB database,
of which there is a public mirror at
https://skimdb\.npmjs\.com/registry\|\. The code for the couchapp is
available at https://github\.com/npm/npm\-registry\-couchapp\|\.
.P
The registry URL used is determined by the scope of the package (see
npm help \fBscope\fP\|\. If no scope is specified, the default registry is used, which is
supplied by the \fBregistry\fP config parameter\. See npm help \fBconfig\fP,
npm help \fBnpmrc\fP, and npm help \fBconfig\fP for more on managing npm's configuration\.
.SS Does npm send any information about me back to the registry?
.P
Yes\.
.P
When making requests of the registry npm adds two headers with information
about your environment:
.RS 0
.IP \(bu 2
\fBNpm\-Scope\fP – If your project is scoped, this header will contain its
scope\. In the future npm hopes to build registry features that use this
information to allow you to customize your experience for your
organization\.
.IP \(bu 2
\fBNpm\-In\-CI\fP – Set to "true" if npm believes this install is running in a
continuous integration environment, "false" otherwise\. This is detected by
looking for the following environment variables: \fBCI\fP, \fBTDDIUM\fP,
\fBJENKINS_URL\fP, \fBbamboo\.buildKey\fP\|\. If you'd like to learn more you may find
the original PR \fIhttps://github\.com/npm/npm\-registry\-client/pull/129\fR
interesting\.
This is used to gather better metrics on how npm is used by humans, versus
build farms\.
.RE
.P
The npm registry does not try to correlate the information in these headers
with any authenticated accounts that may be used in the same requests\.
.SS Can I run my own private registry?
.P
Yes!
.P
The easiest way is to replicate the couch database, and use the same (or
similar) design doc to implement the APIs\.
.P
If you set up continuous replication from the official CouchDB, and then
set your internal CouchDB as the registry config, then you'll be able
to read any published packages, in addition to your private ones, and by
default will only publish internally\.
.P
If you then want to publish a package for the whole world to see, you can
simply override the \fB\-\-registry\fP option for that \fBpublish\fP command\.
.SS I don't want my package published in the official registry\. It's private\.
.P
Set \fB"private": true\fP in your package\.json to prevent it from being
published at all, or
\fB"publishConfig":{"registry":"http://my\-internal\-registry\.local"}\fP
to force it to be published only to your internal registry\.
.P
See npm help \fBpackage\.json\fP for more info on what goes in the package\.json file\.
.SS Will you replicate from my registry into the public one?
.P
No\. If you want things to be public, then publish them into the public
registry using npm\. What little security there is would be for nought
otherwise\.
.SS Do I have to use couchdb to build a registry that npm can talk to?
.P
No, but it's way easier\. Basically, yes, you do, or you have to
effectively implement the entire CouchDB API anyway\.
.SS Is there a website or something to see package docs and such?
.P
Yes, head over to https://www\.npmjs\.com/
.SS See also
.RS 0
.IP \(bu 2
npm help config
.IP \(bu 2
npm help config
.IP \(bu 2
npm help npmrc
.IP \(bu 2
npm help developers
.IP \(bu 2
npm help disputes
.RE

75
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/removal.7 generated vendored Normal file
View File

@ -0,0 +1,75 @@
.TH "REMOVAL" "7" "August 2021" "" ""
.SH "NAME"
\fBremoval\fR \- Cleaning the Slate
.SS Synopsis
.P
So sad to see you go\.
.P
.RS 2
.nf
sudo npm uninstall npm \-g
.fi
.RE
.P
Or, if that fails, get the npm source code, and do:
.P
.RS 2
.nf
sudo make uninstall
.fi
.RE
.SS More Severe Uninstalling
.P
Usually, the above instructions are sufficient\. That will remove
npm, but leave behind anything you've installed\.
.P
If that doesn't work, or if you require more drastic measures,
continue reading\.
.P
Note that this is only necessary for globally\-installed packages\. Local
installs are completely contained within a project's \fBnode_modules\fP
folder\. Delete that folder, and everything is gone less a package's
install script is particularly ill\-behaved)\.
.P
This assumes that you installed node and npm in the default place\. If
you configured node with a different \fB\-\-prefix\fP, or installed npm with a
different prefix setting, then adjust the paths accordingly, replacing
\fB/usr/local\fP with your install prefix\.
.P
To remove everything npm\-related manually:
.P
.RS 2
.nf
rm \-rf /usr/local/{lib/node{,/\.npm,_modules},bin,share/man}/npm*
.fi
.RE
.P
If you installed things \fIwith\fR npm, then your best bet is to uninstall
them with npm first, and then install them again once you have a
proper install\. This can help find any symlinks that are lying
around:
.P
.RS 2
.nf
ls \-laF /usr/local/{lib/node{,/\.npm},bin,share/man} | grep npm
.fi
.RE
.P
Prior to version 0\.3, npm used shim files for executables and node
modules\. To track those down, you can do the following:
.P
.RS 2
.nf
find /usr/local/{lib/node,bin} \-exec grep \-l npm \\{\\} \\; ;
.fi
.RE
.P
(This is also in the README file\.)
.SS See also
.RS 0
.IP \(bu 2
npm help uninstall
.IP \(bu 2
npm help prune
.RE

136
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/scope.7 generated vendored Normal file
View File

@ -0,0 +1,136 @@
.TH "SCOPE" "7" "August 2021" "" ""
.SH "NAME"
\fBscope\fR \- Scoped packages
.SS Description
.P
All npm packages have a name\. Some package names also have a scope\. A scope
follows the usual rules for package names (URL\-safe characters, no leading dots
or underscores)\. When used in package names, scopes are preceded by an \fB@\fP symbol
and followed by a slash, e\.g\.
.P
.RS 2
.nf
@somescope/somepackagename
.fi
.RE
.P
Scopes are a way of grouping related packages together, and also affect a few
things about the way npm treats the package\.
.P
Each npm user/organization has their own scope, and only you can add packages
in your scope\. This means you don't have to worry about someone taking your
package name ahead of you\. Thus it is also a good way to signal official packages
for organizations\.
.P
Scoped packages can be published and installed as of \fBnpm@2\fP and are supported
by the primary npm registry\. Unscoped packages can depend on scoped packages and
vice versa\. The npm client is backwards\-compatible with unscoped registries,
so it can be used to work with scoped and unscoped registries at the same time\.
.SS Installing scoped packages
.P
Scoped packages are installed to a sub\-folder of the regular installation
folder, e\.g\. if your other packages are installed in \fBnode_modules/packagename\fP,
scoped modules will be installed in \fBnode_modules/@myorg/packagename\fP\|\. The scope
folder (\fB@myorg\fP) is simply the name of the scope preceded by an \fB@\fP symbol, and can
contain any number of scoped packages\.
.P
A scoped package is installed by referencing it by name, preceded by an
\fB@\fP symbol, in \fBnpm install\fP:
.P
.RS 2
.nf
npm install @myorg/mypackage
.fi
.RE
.P
Or in \fBpackage\.json\fP:
.P
.RS 2
.nf
"dependencies": {
"@myorg/mypackage": "^1\.3\.0"
}
.fi
.RE
.P
Note that if the \fB@\fP symbol is omitted, in either case, npm will instead attempt to
install from GitHub; see npm help \fBinstall\fP\|\.
.SS Requiring scoped packages
.P
Because scoped packages are installed into a scope folder, you have to
include the name of the scope when requiring them in your code, e\.g\.
.P
.RS 2
.nf
require('@myorg/mypackage')
.fi
.RE
.P
There is nothing special about the way Node treats scope folders\. This
simply requires the \fBmypackage\fP module in the folder named \fB@myorg\fP\|\.
.SS Publishing scoped packages
.P
Scoped packages can be published from the CLI as of \fBnpm@2\fP and can be
published to any registry that supports them, including the primary npm
registry\.
.P
(As of 2015\-04\-19, and with npm 2\.0 or better, the primary npm registry
\fBdoes\fR support scoped packages\.)
.P
If you wish, you may associate a scope with a registry; see below\.
.SS Publishing public scoped packages to the primary npm registry
.P
To publish a public scoped package, you must specify \fB\-\-access public\fP with
the initial publication\. This will publish the package and set access
to \fBpublic\fP as if you had run \fBnpm access public\fP after publishing\.
.SS Publishing private scoped packages to the npm registry
.P
To publish a private scoped package to the npm registry, you must have
an npm Private Modules \fIhttps://docs\.npmjs\.com/private\-modules/intro\fR
account\.
.P
You can then publish the module with \fBnpm publish\fP or \fBnpm publish
\-\-access restricted\fP, and it will be present in the npm registry, with
restricted access\. You can then change the access permissions, if
desired, with \fBnpm access\fP or on the npmjs\.com website\.
.SS Associating a scope with a registry
.P
Scopes can be associated with a separate registry\. This allows you to
seamlessly use a mix of packages from the primary npm registry and one or more
private registries, such as npm Enterprise\.
.P
You can associate a scope with a registry at login, e\.g\.
.P
.RS 2
.nf
npm login \-\-registry=http://reg\.example\.com \-\-scope=@myco
.fi
.RE
.P
Scopes have a many\-to\-one relationship with registries: one registry can
host multiple scopes, but a scope only ever points to one registry\.
.P
You can also associate a scope with a registry using \fBnpm config\fP:
.P
.RS 2
.nf
npm config set @myco:registry http://reg\.example\.com
.fi
.RE
.P
Once a scope is associated with a registry, any \fBnpm install\fP for a package
with that scope will request packages from that registry instead\. Any
\fBnpm publish\fP for a package name that contains the scope will be published to
that registry instead\.
.SS See also
.RS 0
.IP \(bu 2
npm help install
.IP \(bu 2
npm help publish
.IP \(bu 2
npm help access
.IP \(bu 2
npm help registry
.RE

376
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/scripts.7 generated vendored Normal file
View File

@ -0,0 +1,376 @@
.TH "SCRIPTS" "7" "August 2021" "" ""
.SH "NAME"
\fBscripts\fR \- How npm handles the "scripts" field
.SS Description
.P
The \fB"scripts"\fP property of of your \fBpackage\.json\fP file supports a number of built\-in scripts and their preset life cycle events as well as arbitrary scripts\. These all can be executed by running \fBnpm run\-script <stage>\fP or \fBnpm run <stage>\fP for short\. \fIPre\fR and \fIpost\fR commands with matching names will be run for those as well (e\.g\. \fBpremyscript\fP, \fBmyscript\fP, \fBpostmyscript\fP)\. Scripts from dependencies can be run with \fBnpm explore <pkg> \-\- npm run <stage>\fP\|\.
.SS Pre & Post Scripts
.P
To create "pre" or "post" scripts for any scripts defined in the \fB"scripts"\fP section of the \fBpackage\.json\fP, simply create another script \fIwith a matching name\fR and add "pre" or "post" to the beginning of them\.
.P
.RS 2
.nf
{
"scripts": {
"precompress": "{{ executes BEFORE the `compress` script }}",
"compress": "{{ run command to compress files }}",
"postcompress": "{{ executes AFTER `compress` script }}"
}
}
.fi
.RE
.SS Life Cycle Scripts
.P
There are some special life cycle scripts that happen only in certain situations\. These scripts happen in addtion to the "pre" and "post" script\.
.RS 0
.IP \(bu 2
\fBprepare\fP, \fBprepublish\fP, \fBprepublishOnly\fP, \fBprepack\fP, \fBpostpack\fP
.RE
.P
\fBprepare\fR (since \fBnpm@4\.0\.0\fP)
.RS 0
.IP \(bu 2
Runs BEFORE the package is packed
.IP \(bu 2
Runs BEFORE the package is published
.IP \(bu 2
Runs on local \fBnpm install\fP without any arguments
.IP \(bu 2
Run AFTER \fBprepublish\fP, but BEFORE \fBprepublishOnly\fP
.IP \(bu 2
NOTE: If a package being installed through git contains a \fBprepare\fP script, its \fBdependencies\fP and \fBdevDependencies\fP will be installed, and the prepare script will be run, before the package is packaged and installed\.
.RE
.P
\fBprepublish\fR (DEPRECATED)
.RS 0
.IP \(bu 2
Same as \fBprepare\fP
.RE
.P
\fBprepublishOnly\fR
.RS 0
.IP \(bu 2
Runs BEFORE the package is prepared and packed, ONLY on \fBnpm publish\fP\|\.
.RE
.P
\fBprepack\fR
.RS 0
.IP \(bu 2
Runs BEFORE a tarball is packed (on "\fBnpm pack\fP", "\fBnpm publish\fP", and when installing a git dependencies)\.
.IP \(bu 2
NOTE: "\fBnpm run pack\fP" is NOT the same as "\fBnpm pack\fP"\. "\fBnpm run pack\fP" is an arbitrary user defined script name, where as, "\fBnpm pack\fP" is a CLI defined command\.
.RE
.P
\fBpostpack\fR
.RS 0
.IP \(bu 2
Runs AFTER the tarball has been generated and moved to its final destination\.
.RE
.SS Prepare and Prepublish
.P
\fBDeprecation Note: prepublish\fR
.P
Since \fBnpm@1\.1\.71\fP, the npm CLI has run the \fBprepublish\fP script for both \fBnpm publish\fP and \fBnpm install\fP, because it's a convenient way to prepare a package for use (some common use cases are described in the section below)\. It has also turned out to be, in practice, very confusing \fIhttps://github\.com/npm/npm/issues/10074\fR\|\. As of \fBnpm@4\.0\.0\fP, a new event has been introduced, \fBprepare\fP, that preserves this existing behavior\. A \fInew\fR event, \fBprepublishOnly\fP has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on \fBnpm publish\fP (for instance, running the tests one last time to ensure they're in good shape)\.
.P
See https://github\.com/npm/npm/issues/10074 for a much lengthier justification, with further reading, for this change\.
.P
\fBUse Cases\fR
.P
If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a \fBprepublish\fP script\. This includes tasks such as:
.RS 0
.IP \(bu 2
Compiling CoffeeScript source code into JavaScript\.
.IP \(bu 2
Creating minified versions of JavaScript source code\.
.IP \(bu 2
Fetching remote resources that your package will use\.
.RE
.P
The advantage of doing these things at \fBprepublish\fP time is that they can be done once, in a single place, thus reducing complexity and variability\. Additionally, this means that:
.RS 0
.IP \(bu 2
You can depend on \fBcoffee\-script\fP as a \fBdevDependency\fP, and thus
your users don't need to have it installed\.
.IP \(bu 2
You don't need to include minifiers in your package, reducing
the size for your users\.
.IP \(bu 2
You don't need to rely on your users having \fBcurl\fP or \fBwget\fP or
other system tools on the target machines\.
.RE
.SS Life Cycle Operation Order
.SS npm help \fBpublish\fP
.RS 0
.IP \(bu 2
\fBprepublishOnly\fP
.IP \(bu 2
\fBprepare\fP
.IP \(bu 2
\fBprepublish\fP
.IP \(bu 2
\fBpublish\fP
.IP \(bu 2
\fBpostpublish\fP
.RE
.SS npm help \fBpack\fP
.RS 0
.IP \(bu 2
\fBprepack\fP
.IP \(bu 2
\fBpostpack\fP
.RE
.SS npm help \fBinstall\fP
.RS 0
.IP \(bu 2
\fBpreinstall\fP
.IP \(bu 2
\fBinstall\fP
.IP \(bu 2
\fBpostinstall\fP
.RE
.P
Also triggers
.RS 0
.IP \(bu 2
\fBprepublish\fP (when on local)
.IP \(bu 2
\fBprepare\fP (when on local)
.RE
.SS npm help \fBstart\fP
.P
\fBnpm run start\fP has an \fBnpm start\fP shorthand\.
.RS 0
.IP \(bu 2
\fBprestart\fP
.IP \(bu 2
\fBstart\fP
.IP \(bu 2
\fBpoststart\fP
.RE
.SS Default Values
.P
npm will default some script values based on package contents\.
.RS 0
.IP \(bu 2
\fB"start": "node server\.js"\fP:
If there is a \fBserver\.js\fP file in the root of your package, then npm
will default the \fBstart\fP command to \fBnode server\.js\fP\|\.
.IP \(bu 2
\fB"install": "node\-gyp rebuild"\fP:
If there is a \fBbinding\.gyp\fP file in the root of your package and you
haven't defined your own \fBinstall\fP or \fBpreinstall\fP scripts, npm will
default the \fBinstall\fP command to compile using node\-gyp\.
.RE
.SS User
.P
If npm was invoked with root privileges, then it will change the uid
to the user account or uid specified by the \fBuser\fP config, which
defaults to \fBnobody\fP\|\. Set the \fBunsafe\-perm\fP flag to run scripts with
root privileges\.
.SS Environment
.P
Package scripts run in an environment where many pieces of information
are made available regarding the setup of npm and the current state of
the process\.
.SS path
.P
If you depend on modules that define executable scripts, like test
suites, then those executables will be added to the \fBPATH\fP for
executing the scripts\. So, if your package\.json has this:
.P
.RS 2
.nf
{
"name" : "foo",
"dependencies" : {
"bar" : "0\.1\.x"
},
"scripts": {
"start" : "bar \./test"
}
}
.fi
.RE
.P
then you could run \fBnpm start\fP to execute the \fBbar\fP script, which is
exported into the \fBnode_modules/\.bin\fP directory on \fBnpm install\fP\|\.
.SS package\.json vars
.P
The package\.json fields are tacked onto the \fBnpm_package_\fP prefix\. So,
for instance, if you had \fB{"name":"foo", "version":"1\.2\.5"}\fP in your
package\.json file, then your package scripts would have the
\fBnpm_package_name\fP environment variable set to "foo", and the
\fBnpm_package_version\fP set to "1\.2\.5"\. You can access these variables
in your code with \fBprocess\.env\.npm_package_name\fP and
\fBprocess\.env\.npm_package_version\fP, and so on for other fields\.
.SS configuration
.P
Configuration parameters are put in the environment with the
\fBnpm_config_\fP prefix\. For instance, you can view the effective \fBroot\fP
config by checking the \fBnpm_config_root\fP environment variable\.
.SS Special: package\.json "config" object
.P
The package\.json "config" keys are overwritten in the environment if
there is a config param of \fB<name>[@<version>]:<key>\fP\|\. For example,
if the package\.json has this:
.P
.RS 2
.nf
{
"name" : "foo",
"config" : {
"port" : "8080"
},
"scripts" : {
"start" : "node server\.js"
}
}
.fi
.RE
.P
and the server\.js is this:
.P
.RS 2
.nf
http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
.fi
.RE
.P
then the user could change the behavior by doing:
.P
.RS 2
.nf
npm config set foo:port 80
.fi
.RE
.SS current lifecycle event
.P
Lastly, the \fBnpm_lifecycle_event\fP environment variable is set to
whichever stage of the cycle is being executed\. So, you could have a
single script used for different parts of the process which switches
based on what's currently happening\.
.P
Objects are flattened following this format, so if you had
\fB{"scripts":{"install":"foo\.js"}}\fP in your package\.json, then you'd
see this in the script:
.P
.RS 2
.nf
process\.env\.npm_package_scripts_install === "foo\.js"
.fi
.RE
.SS Examples
.P
For example, if your package\.json contains this:
.P
.RS 2
.nf
{
"scripts" : {
"install" : "scripts/install\.js",
"postinstall" : "scripts/install\.js",
"uninstall" : "scripts/uninstall\.js"
}
}
.fi
.RE
.P
then \fBscripts/install\.js\fP will be called for the install
and post\-install stages of the lifecycle, and \fBscripts/uninstall\.js\fP
will be called when the package is uninstalled\. Since
\fBscripts/install\.js\fP is running for two different phases, it would
be wise in this case to look at the \fBnpm_lifecycle_event\fP environment
variable\.
.P
If you want to run a make command, you can do so\. This works just
fine:
.P
.RS 2
.nf
{
"scripts" : {
"preinstall" : "\./configure",
"install" : "make && make install",
"test" : "make test"
}
}
.fi
.RE
.SS Exiting
.P
Scripts are run by passing the line as a script argument to \fBsh\fP\|\.
.P
If the script exits with a code other than 0, then this will abort the
process\.
.P
Note that these script files don't have to be nodejs or even
javascript programs\. They just have to be some kind of executable
file\.
.SS Hook Scripts
.P
If you want to run a specific script at a specific lifecycle event for
ALL packages, then you can use a hook script\.
.P
Place an executable file at \fBnode_modules/\.hooks/{eventname}\fP, and
it'll get run for all packages when they are going through that point
in the package lifecycle for any packages installed in that root\.
.P
Hook scripts are run exactly the same way as package\.json scripts\.
That is, they are in a separate child process, with the env described
above\.
.SS Best Practices
.RS 0
.IP \(bu 2
Don't exit with a non\-zero error code unless you \fIreally\fR mean it\.
Except for uninstall scripts, this will cause the npm action to
fail, and potentially be rolled back\. If the failure is minor or
only will prevent some optional features, then it's better to just
print a warning and exit successfully\.
.IP \(bu 2
Try not to use scripts to do what npm can do for you\. Read through
npm help \fBpackage\.json\fP to see all the things that you can specify and enable
by simply describing your package appropriately\. In general, this
will lead to a more robust and consistent state\.
.IP \(bu 2
Inspect the env to determine where to put things\. For instance, if
the \fBnpm_config_binroot\fP environment variable is set to \fB/home/user/bin\fP, then
don't try to install executables into \fB/usr/local/bin\fP\|\. The user
probably set it up that way for a reason\.
.IP \(bu 2
Don't prefix your script commands with "sudo"\. If root permissions
are required for some reason, then it'll fail with that error, and
the user will sudo the npm command in question\.
.IP \(bu 2
Don't use \fBinstall\fP\|\. Use a \fB\|\.gyp\fP file for compilation, and \fBprepublish\fP
for anything else\. You should almost never have to explicitly set a
preinstall or install script\. If you are doing this, please consider if
there is another option\. The only valid use of \fBinstall\fP or \fBpreinstall\fP
scripts is for compilation which must be done on the target architecture\.
.RE
.SS See Also
.RS 0
.IP \(bu 2
npm help run\-script
.IP \(bu 2
npm help package\.json
.IP \(bu 2
npm help developers
.IP \(bu 2
npm help install
.RE

510
builder-docker/jenkins/node-v12.22.8-linux-x64/lib/node_modules/npm/man/man7/semver.7 generated vendored Normal file
View File

@ -0,0 +1,510 @@
.TH "SEMVER" "7" "August 2021" "" ""
.SH "NAME"
\fBsemver\fR \- The semantic versioner for npm
.SH Install
.P
.RS 2
.nf
npm install \-\-save semver
.fi
.RE
.SH Usage
.P
As a node module:
.P
.RS 2
.nf
const semver = require('semver')
semver\.valid('1\.2\.3') // '1\.2\.3'
semver\.valid('a\.b\.c') // null
semver\.clean(' =v1\.2\.3 ') // '1\.2\.3'
semver\.satisfies('1\.2\.3', '1\.x || >=2\.5\.0 || 5\.0\.0 \- 7\.2\.3') // true
semver\.gt('1\.2\.3', '9\.8\.7') // false
semver\.lt('1\.2\.3', '9\.8\.7') // true
semver\.minVersion('>=1\.0\.0') // '1\.0\.0'
semver\.valid(semver\.coerce('v2')) // '2\.0\.0'
semver\.valid(semver\.coerce('42\.6\.7\.9\.3\-alpha')) // '42\.6\.7'
.fi
.RE
.P
As a command\-line utility:
.P
.RS 2
.nf
$ semver \-h
A JavaScript implementation of the https://semver\.org/ specification
Copyright Isaac Z\. Schlueter
Usage: semver [options] <version> [<version> [\.\.\.]]
Prints valid versions sorted by SemVer precedence
Options:
\-r \-\-range <range>
Print versions that match the specified range\.
\-i \-\-increment [<level>]
Increment a version by the specified level\. Level can
be one of: major, minor, patch, premajor, preminor,
prepatch, or prerelease\. Default level is 'patch'\.
Only one version may be specified\.
\-\-preid <identifier>
Identifier to be used to prefix premajor, preminor,
prepatch or prerelease version increments\.
\-l \-\-loose
Interpret versions and ranges loosely
\-p \-\-include\-prerelease
Always include prerelease versions in range matching
\-c \-\-coerce
Coerce a string into SemVer if possible
(does not imply \-\-loose)
Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions\.
If no satisfying versions are found, then exits failure\.
Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them\.
.fi
.RE
.SH Versions
.P
A "version" is described by the \fBv2\.0\.0\fP specification found at
https://semver\.org/\|\.
.P
A leading \fB"="\fP or \fB"v"\fP character is stripped off and ignored\.
.SH Ranges
.P
A \fBversion range\fP is a set of \fBcomparators\fP which specify versions
that satisfy the range\.
.P
A \fBcomparator\fP is composed of an \fBoperator\fP and a \fBversion\fP\|\. The set
of primitive \fBoperators\fP is:
.RS 0
.IP \(bu 2
\fB<\fP Less than
.IP \(bu 2
\fB<=\fP Less than or equal to
.IP \(bu 2
\fB>\fP Greater than
.IP \(bu 2
\fB>=\fP Greater than or equal to
.IP \(bu 2
\fB=\fP Equal\. If no operator is specified, then equality is assumed,
so this operator is optional, but MAY be included\.
.RE
.P
For example, the comparator \fB>=1\.2\.7\fP would match the versions
\fB1\.2\.7\fP, \fB1\.2\.8\fP, \fB2\.5\.3\fP, and \fB1\.3\.9\fP, but not the versions \fB1\.2\.6\fP
or \fB1\.1\.0\fP\|\.
.P
Comparators can be joined by whitespace to form a \fBcomparator set\fP,
which is satisfied by the \fBintersection\fR of all of the comparators
it includes\.
.P
A range is composed of one or more comparator sets, joined by \fB||\fP\|\. A
version matches a range if and only if every comparator in at least
one of the \fB||\fP\-separated comparator sets is satisfied by the version\.
.P
For example, the range \fB>=1\.2\.7 <1\.3\.0\fP would match the versions
\fB1\.2\.7\fP, \fB1\.2\.8\fP, and \fB1\.2\.99\fP, but not the versions \fB1\.2\.6\fP, \fB1\.3\.0\fP,
or \fB1\.1\.0\fP\|\.
.P
The range \fB1\.2\.7 || >=1\.2\.9 <2\.0\.0\fP would match the versions \fB1\.2\.7\fP,
\fB1\.2\.9\fP, and \fB1\.4\.6\fP, but not the versions \fB1\.2\.8\fP or \fB2\.0\.0\fP\|\.
.SS Prerelease Tags
.P
If a version has a prerelease tag (for example, \fB1\.2\.3\-alpha\.3\fP) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same \fB[major, minor, patch]\fP tuple also has a
prerelease tag\.
.P
For example, the range \fB>1\.2\.3\-alpha\.3\fP would be allowed to match the
version \fB1\.2\.3\-alpha\.7\fP, but it would \fInot\fR be satisfied by
\fB3\.4\.5\-alpha\.9\fP, even though \fB3\.4\.5\-alpha\.9\fP is technically "greater
than" \fB1\.2\.3\-alpha\.3\fP according to the SemVer sort rules\. The version
range only accepts prerelease tags on the \fB1\.2\.3\fP version\. The
version \fB3\.4\.5\fP \fIwould\fR satisfy the range, because it does not have a
prerelease flag, and \fB3\.4\.5\fP is greater than \fB1\.2\.3\-alpha\.7\fP\|\.
.P
The purpose for this behavior is twofold\. First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption\.
Therefore, by default, they are excluded from range matching
semantics\.
.P
Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use \fIthat specific\fR set of
alpha/beta/rc versions\. By including a prerelease tag in the range,
the user is indicating that they are aware of the risk\. However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the \fInext\fR set of prerelease versions\.
.P
Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the \fBincludePrerelease\fP flag on the options
object to any
functions \fIhttps://github\.com/npm/node\-semver#functions\fR that do
range matching\.
.SS Prerelease Identifiers
.P
The method \fB\|\.inc\fP takes an additional \fBidentifier\fP string argument that
will append the value of the string as a prerelease identifier:
.P
.RS 2
.nf
semver\.inc('1\.2\.3', 'prerelease', 'beta')
// '1\.2\.4\-beta\.0'
.fi
.RE
.P
command\-line example:
.P
.RS 2
.nf
$ semver 1\.2\.3 \-i prerelease \-\-preid beta
1\.2\.4\-beta\.0
.fi
.RE
.P
Which then can be used to increment further:
.P
.RS 2
.nf
$ semver 1\.2\.4\-beta\.0 \-i prerelease
1\.2\.4\-beta\.1
.fi
.RE
.SS Advanced Range Syntax
.P
Advanced range syntax desugars to primitive comparators in
deterministic ways\.
.P
Advanced ranges may be combined in the same way as primitive
comparators using white space or \fB||\fP\|\.
.SS Hyphen Ranges \fBX\.Y\.Z \- A\.B\.C\fP
.P
Specifies an inclusive set\.
.RS 0
.IP \(bu 2
\fB1\.2\.3 \- 2\.3\.4\fP := \fB>=1\.2\.3 <=2\.3\.4\fP
.RE
.P
If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes\.
.RS 0
.IP \(bu 2
\fB1\.2 \- 2\.3\.4\fP := \fB>=1\.2\.0 <=2\.3\.4\fP
.RE
.P
If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts\.
.RS 0
.IP \(bu 2
\fB1\.2\.3 \- 2\.3\fP := \fB>=1\.2\.3 <2\.4\.0\fP
.IP \(bu 2
\fB1\.2\.3 \- 2\fP := \fB>=1\.2\.3 <3\.0\.0\fP
.RE
.SS X\-Ranges \fB1\.2\.x\fP \fB1\.X\fP \fB1\.2\.*\fP \fB*\fP
.P
Any of \fBX\fP, \fBx\fP, or \fB*\fP may be used to "stand in" for one of the
numeric values in the \fB[major, minor, patch]\fP tuple\.
.RS 0
.IP \(bu 2
\fB*\fP := \fB>=0\.0\.0\fP (Any version satisfies)
.IP \(bu 2
\fB1\.x\fP := \fB>=1\.0\.0 <2\.0\.0\fP (Matching major version)
.IP \(bu 2
\fB1\.2\.x\fP := \fB>=1\.2\.0 <1\.3\.0\fP (Matching major and minor versions)
.RE
.P
A partial version range is treated as an X\-Range, so the special
character is in fact optional\.
.RS 0
.IP \(bu 2
\fB""\fP (empty string) := \fB*\fP := \fB>=0\.0\.0\fP
.IP \(bu 2
\fB1\fP := \fB1\.x\.x\fP := \fB>=1\.0\.0 <2\.0\.0\fP
.IP \(bu 2
\fB1\.2\fP := \fB1\.2\.x\fP := \fB>=1\.2\.0 <1\.3\.0\fP
.RE
.SS Tilde Ranges \fB~1\.2\.3\fP \fB~1\.2\fP \fB~1\fP
.P
Allows patch\-level changes if a minor version is specified on the
comparator\. Allows minor\-level changes if not\.
.RS 0
.IP \(bu 2
\fB~1\.2\.3\fP := \fB>=1\.2\.3 <1\.(2+1)\.0\fP := \fB>=1\.2\.3 <1\.3\.0\fP
.IP \(bu 2
\fB~1\.2\fP := \fB>=1\.2\.0 <1\.(2+1)\.0\fP := \fB>=1\.2\.0 <1\.3\.0\fP (Same as \fB1\.2\.x\fP)
.IP \(bu 2
\fB~1\fP := \fB>=1\.0\.0 <(1+1)\.0\.0\fP := \fB>=1\.0\.0 <2\.0\.0\fP (Same as \fB1\.x\fP)
.IP \(bu 2
\fB~0\.2\.3\fP := \fB>=0\.2\.3 <0\.(2+1)\.0\fP := \fB>=0\.2\.3 <0\.3\.0\fP
.IP \(bu 2
\fB~0\.2\fP := \fB>=0\.2\.0 <0\.(2+1)\.0\fP := \fB>=0\.2\.0 <0\.3\.0\fP (Same as \fB0\.2\.x\fP)
.IP \(bu 2
\fB~0\fP := \fB>=0\.0\.0 <(0+1)\.0\.0\fP := \fB>=0\.0\.0 <1\.0\.0\fP (Same as \fB0\.x\fP)
.IP \(bu 2
\fB~1\.2\.3\-beta\.2\fP := \fB>=1\.2\.3\-beta\.2 <1\.3\.0\fP Note that prereleases in
the \fB1\.2\.3\fP version will be allowed, if they are greater than or
equal to \fBbeta\.2\fP\|\. So, \fB1\.2\.3\-beta\.4\fP would be allowed, but
\fB1\.2\.4\-beta\.2\fP would not, because it is a prerelease of a
different \fB[major, minor, patch]\fP tuple\.
.RE
.SS Caret Ranges \fB^1\.2\.3\fP \fB^0\.2\.5\fP \fB^0\.0\.4\fP
.P
Allows changes that do not modify the left\-most non\-zero digit in the
\fB[major, minor, patch]\fP tuple\. In other words, this allows patch and
minor updates for versions \fB1\.0\.0\fP and above, patch updates for
versions \fB0\.X >=0\.1\.0\fP, and \fIno\fR updates for versions \fB0\.0\.X\fP\|\.
.P
Many authors treat a \fB0\.x\fP version as if the \fBx\fP were the major
"breaking\-change" indicator\.
.P
Caret ranges are ideal when an author may make breaking changes
between \fB0\.2\.4\fP and \fB0\.3\.0\fP releases, which is a common practice\.
However, it presumes that there will \fInot\fR be breaking changes between
\fB0\.2\.4\fP and \fB0\.2\.5\fP\|\. It allows for changes that are presumed to be
additive (but non\-breaking), according to commonly observed practices\.
.RS 0
.IP \(bu 2
\fB^1\.2\.3\fP := \fB>=1\.2\.3 <2\.0\.0\fP
.IP \(bu 2
\fB^0\.2\.3\fP := \fB>=0\.2\.3 <0\.3\.0\fP
.IP \(bu 2
\fB^0\.0\.3\fP := \fB>=0\.0\.3 <0\.0\.4\fP
.IP \(bu 2
\fB^1\.2\.3\-beta\.2\fP := \fB>=1\.2\.3\-beta\.2 <2\.0\.0\fP Note that prereleases in
the \fB1\.2\.3\fP version will be allowed, if they are greater than or
equal to \fBbeta\.2\fP\|\. So, \fB1\.2\.3\-beta\.4\fP would be allowed, but
\fB1\.2\.4\-beta\.2\fP would not, because it is a prerelease of a
different \fB[major, minor, patch]\fP tuple\.
.IP \(bu 2
\fB^0\.0\.3\-beta\fP := \fB>=0\.0\.3\-beta <0\.0\.4\fP Note that prereleases in the
\fB0\.0\.3\fP version \fIonly\fR will be allowed, if they are greater than or
equal to \fBbeta\fP\|\. So, \fB0\.0\.3\-pr\.2\fP would be allowed\.
.RE
.P
When parsing caret ranges, a missing \fBpatch\fP value desugars to the
number \fB0\fP, but will allow flexibility within that value, even if the
major and minor versions are both \fB0\fP\|\.
.RS 0
.IP \(bu 2
\fB^1\.2\.x\fP := \fB>=1\.2\.0 <2\.0\.0\fP
.IP \(bu 2
\fB^0\.0\.x\fP := \fB>=0\.0\.0 <0\.1\.0\fP
.IP \(bu 2
\fB^0\.0\fP := \fB>=0\.0\.0 <0\.1\.0\fP
.RE
.P
A missing \fBminor\fP and \fBpatch\fP values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero\.
.RS 0
.IP \(bu 2
\fB^1\.x\fP := \fB>=1\.0\.0 <2\.0\.0\fP
.IP \(bu 2
\fB^0\.x\fP := \fB>=0\.0\.0 <1\.0\.0\fP
.RE
.SS Range Grammar
.P
Putting all this together, here is a Backus\-Naur grammar for ranges,
for the benefit of parser authors:
.P
.RS 2
.nf
range\-set ::= range ( logical\-or range ) *
logical\-or ::= ( ' ' ) * '||' ( ' ' ) *
range ::= hyphen | simple ( ' ' simple ) * | ''
hyphen ::= partial ' \- ' partial
simple ::= primitive | partial | tilde | caret
primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial ::= xr ( '\.' xr ( '\.' xr qualifier ? )? )?
xr ::= 'x' | 'X' | '*' | nr
nr ::= '0' | ['1'\-'9'] ( ['0'\-'9'] ) *
tilde ::= '~' partial
caret ::= '^' partial
qualifier ::= ( '\-' pre )? ( '+' build )?
pre ::= parts
build ::= parts
parts ::= part ( '\.' part ) *
part ::= nr | [\-0\-9A\-Za\-z]+
.fi
.RE
.SH Functions
.P
All methods and classes take a final \fBoptions\fP object argument\. All
options in this object are \fBfalse\fP by default\. The options supported
are:
.RS 0
.IP \(bu 2
\fBloose\fP Be more forgiving about not\-quite\-valid semver strings\.
(Any resulting output will always be 100% strict compliant, of
course\.) For backwards compatibility reasons, if the \fBoptions\fP
argument is a boolean value instead of an object, it is interpreted
to be the \fBloose\fP param\.
.IP \(bu 2
\fBincludePrerelease\fP Set to suppress the default
behavior \fIhttps://github\.com/npm/node\-semver#prerelease\-tags\fR of
excluding prerelease tagged versions from ranges unless they are
explicitly opted into\.
.RE
.P
Strict\-mode Comparators and Ranges will be strict about the SemVer
strings that they parse\.
.RS 0
.IP \(bu 2
\fBvalid(v)\fP: Return the parsed version, or null if it's not valid\.
.IP \(bu 2
\fBinc(v, release)\fP: Return the version incremented by the release
type (\fBmajor\fP, \fBpremajor\fP, \fBminor\fP, \fBpreminor\fP, \fBpatch\fP,
\fBprepatch\fP, or \fBprerelease\fP), or null if it's not valid
.RS
.IP \(bu 2
\fBpremajor\fP in one call will bump the version up to the next major
version and down to a prerelease of that major version\.
\fBpreminor\fP, and \fBprepatch\fP work the same way\.
.IP \(bu 2
If called from a non\-prerelease version, the \fBprerelease\fP will work the
same as \fBprepatch\fP\|\. It increments the patch version, then makes a
prerelease\. If the input version is already a prerelease it simply
increments it\.
.RE
.IP \(bu 2
\fBprerelease(v)\fP: Returns an array of prerelease components, or null
if none exist\. Example: \fBprerelease('1\.2\.3\-alpha\.1') \-> ['alpha', 1]\fP
.IP \(bu 2
\fBmajor(v)\fP: Return the major version number\.
.IP \(bu 2
\fBminor(v)\fP: Return the minor version number\.
.IP \(bu 2
\fBpatch(v)\fP: Return the patch version number\.
.IP \(bu 2
\fBintersects(r1, r2, loose)\fP: Return true if the two supplied ranges
or comparators intersect\.
.IP \(bu 2
\fBparse(v)\fP: Attempt to parse a string as a semantic version, returning either
a \fBSemVer\fP object or \fBnull\fP\|\.
.RE
.SS Comparison
.RS 0
.IP \(bu 2
\fBgt(v1, v2)\fP: \fBv1 > v2\fP
.IP \(bu 2
\fBgte(v1, v2)\fP: \fBv1 >= v2\fP
.IP \(bu 2
\fBlt(v1, v2)\fP: \fBv1 < v2\fP
.IP \(bu 2
\fBlte(v1, v2)\fP: \fBv1 <= v2\fP
.IP \(bu 2
\fBeq(v1, v2)\fP: \fBv1 == v2\fP This is true if they're logically equivalent,
even if they're not the exact same string\. You already know how to
compare strings\.
.IP \(bu 2
\fBneq(v1, v2)\fP: \fBv1 != v2\fP The opposite of \fBeq\fP\|\.
.IP \(bu 2
\fBcmp(v1, comparator, v2)\fP: Pass in a comparison string, and it'll call
the corresponding function above\. \fB"==="\fP and \fB"!=="\fP do simple
string comparison, but are included for completeness\. Throws if an
invalid comparison string is provided\.
.IP \(bu 2
\fBcompare(v1, v2)\fP: Return \fB0\fP if \fBv1 == v2\fP, or \fB1\fP if \fBv1\fP is greater, or \fB\-1\fP if
\fBv2\fP is greater\. Sorts in ascending order if passed to \fBArray\.sort()\fP\|\.
.IP \(bu 2
\fBrcompare(v1, v2)\fP: The reverse of compare\. Sorts an array of versions
in descending order when passed to \fBArray\.sort()\fP\|\.
.IP \(bu 2
\fBdiff(v1, v2)\fP: Returns difference between two versions by the release type
(\fBmajor\fP, \fBpremajor\fP, \fBminor\fP, \fBpreminor\fP, \fBpatch\fP, \fBprepatch\fP, or \fBprerelease\fP),
or null if the versions are the same\.
.RE
.SS Comparators
.RS 0
.IP \(bu 2
\fBintersects(comparator)\fP: Return true if the comparators intersect
.RE
.SS Ranges
.RS 0
.IP \(bu 2
\fBvalidRange(range)\fP: Return the valid range or null if it's not valid
.IP \(bu 2
\fBsatisfies(version, range)\fP: Return true if the version satisfies the
range\.
.IP \(bu 2
\fBmaxSatisfying(versions, range)\fP: Return the highest version in the list
that satisfies the range, or \fBnull\fP if none of them do\.
.IP \(bu 2
\fBminSatisfying(versions, range)\fP: Return the lowest version in the list
that satisfies the range, or \fBnull\fP if none of them do\.
.IP \(bu 2
\fBminVersion(range)\fP: Return the lowest version that can possibly match
the given range\.
.IP \(bu 2
\fBgtr(version, range)\fP: Return \fBtrue\fP if version is greater than all the
versions possible in the range\.
.IP \(bu 2
\fBltr(version, range)\fP: Return \fBtrue\fP if version is less than all the
versions possible in the range\.
.IP \(bu 2
\fBoutside(version, range, hilo)\fP: Return true if the version is outside
the bounds of the range in either the high or low direction\. The
\fBhilo\fP argument must be either the string \fB\|'>'\fP or \fB\|'<'\fP\|\. (This is
the function called by \fBgtr\fP and \fBltr\fP\|\.)
.IP \(bu 2
\fBintersects(range)\fP: Return true if any of the ranges comparators intersect
.RE
.P
Note that, since ranges may be non\-contiguous, a version might not be
greater than a range, less than a range, \fIor\fR satisfy a range! For
example, the range \fB1\.2 <1\.2\.9 || >2\.0\.0\fP would have a hole from \fB1\.2\.9\fP
until \fB2\.0\.0\fP, so the version \fB1\.2\.10\fP would not be greater than the
range (because \fB2\.0\.1\fP satisfies, which is higher), nor less than the
range (since \fB1\.2\.8\fP satisfies, which is lower), and it also does not
satisfy the range\.
.P
If you want to know if a version satisfies or does not satisfy a
range, use the \fBsatisfies(version, range)\fP function\.
.SS Coercion
.RS 0
.IP \(bu 2
\fBcoerce(version)\fP: Coerces a string to semver if possible
.RE
.P
This aims to provide a very forgiving translation of a non\-semver string to
semver\. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e\.g\., \fB1\fP,
\fB1\.2\fP, \fB1\.2\.3\fP) up to the max permitted length (256 characters)\. Longer
versions are simply truncated (\fB4\.6\.3\.9\.2\-alpha2\fP becomes \fB4\.6\.3\fP)\. All
surrounding text is simply ignored (\fBv3\.4 replaces v3\.3\.1\fP becomes
\fB3\.4\.0\fP)\. Only text which lacks digits will fail coercion (\fBversion one\fP
is not valid)\. The maximum length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(\fB10000000000000000\.4\.7\.4\fP becomes \fB4\.7\.4\fP)\. The maximum value for any
semver component is \fBNumber\.MAX_SAFE_INTEGER || (2**53 \- 1)\fP; higher value
components are invalid (\fB9999999999999999\.4\.7\.4\fP is likely invalid)\.