codekingpro/portable-devtools
115k
1# libnpmversion
2
3[](https://npm.im/libnpmversion)
4[](https://npm.im/libnpmversion)
5[](https://github.com/npm/cli/actions/workflows/ci-libnpmversion.yml)
6
7Library to do the things that 'npm version' does.
8
9## USAGE
10
11```js
12const npmVersion = require('libnpmversion')
13
14// argument can be one of:
15// - any semver version string (set to that exact version)
16// - 'major', 'minor', 'patch', 'pre{major,minor,patch}' (increment at
17// that value)
18// - 'from-git' (set to the latest tag in git that looks like semver -
19// this skips gitTagVersion, but will still sign if asked)
20npmVersion(arg, {
21 path: '/path/to/my/pkg', // defaults to cwd
22
23 allowSameVersion: false, // allow tagging/etc to the current version
24 preid: '', // when arg=='pre', define the prerelease string, like 'beta' etc.
25 tagVersionPrefix: 'v', // tag as 'v1.2.3' when versioning to 1.2.3
26 commitHooks: true, // default true, run git commit hooks, default true
27 gitTagVersion: true, // default true, tag the version
28 signGitCommit: false, // default false, gpg sign the git commit
29 signGitTag: false, // default false, gpg sign the git tag
30 force: false, // push forward recklessly if any problems happen
31 ignoreScripts: false, // do not run pre/post/version lifecycle scripts
32 scriptShell: '/bin/bash', // shell to run lifecycle scripts in
33 message: 'v%s', // message for tag and commit, replace %s with the version
34}).then(newVersion => {
35 console.error('version updated!', newVersion)
36})
37```
38
39## Description
40
41Run this in a package directory to bump the version and write the new data
42back to `package.json`, `package-lock.json`, and, if present,
43`npm-shrinkwrap.json`.
44
45The `newversion` argument should be a valid semver string, a valid second
46argument to [semver.inc](https://github.com/npm/node-semver#functions) (one
47of `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`,
48`prerelease`), or `from-git`. In the second case, the existing version will
49be incremented by 1 in the specified field. `from-git` will try to read
50the latest git tag, and use that as the new npm version.
51
52If run in a git repo, it will also create a version commit and tag. This
53behavior is controlled by `gitTagVersion` (see below), and can be
54disabled by setting `gitTagVersion: false` in the options.
55It will fail if the working directory is not clean, unless `force: true` is
56set.
57
58If supplied with a `message` string option, it will
59use it as a commit message when creating a version commit. If the
60`message` option contains `%s` then that will be replaced with the
61resulting version number.
62
63If the `signGitTag` option is set, then the tag will be signed using
64the `-s` flag to git. Note that you must have a default GPG key set up in
65your git config for this to work properly.
66
67If `preversion`, `version`, or `postversion` are in the `scripts` property
68of the package.json, they will be executed in the appropriate sequence.
69
70The exact order of execution is as follows:
71
721. Check to make sure the git working directory is clean before we get
73 started. Your scripts may add files to the commit in future steps.
74 This step is skipped if the `force` flag is set.
752. Run the `preversion` script. These scripts have access to the old
76 `version` in package.json. A typical use would be running your full
77 test suite before deploying. Any files you want added to the commit
78 should be explicitly added using `git add`.
793. Bump `version` in `package.json` as requested (`patch`, `minor`,
80 `major`, explicit version number, etc).
814. Run the `version` script. These scripts have access to the new `version`
82 in package.json (so they can incorporate it into file headers in
83 generated files for example). Again, scripts should explicitly add
84 generated files to the commit using `git add`.
855. Commit and tag.
866. Run the `postversion` script. Use it to clean up the file system or
87 automatically push the commit and/or tag.
88
89Take the following example:
90
91```json
92{
93 "scripts": {
94 "preversion": "npm test",
95 "version": "npm run build && git add -A dist",
96 "postversion": "git push && git push --tags && rm -rf build/temp"
97 }
98}
99```
100
101This runs all your tests, and proceeds only if they pass. Then runs your
102`build` script, and adds everything in the `dist` directory to the commit.
103After the commit, it pushes the new commit and tag up to the server, and
104deletes the `build/temp` directory.
105
106## API
107
108### `npmVersion(newversion, options = {}) -> Promise<String>`
109
110Do the things. Returns a promise that resolves to the new version if
111all is well, or rejects if any errors are encountered.
112
113### Options
114
115#### `path` String
116
117The path to the package being versioned. Defaults to process.cwd().
118
119#### `allowSameVersion` Boolean
120
121Allow setting the version to the current version in package.json. Default
122`false`.
123
124#### `preid` String
125When the `newversion` is pre, premajor, preminor, or prepatch, this
126defines the prerelease string, like 'beta' etc.
127
128#### `tagVersionPrefix` String
129
130The prefix to add to the raw semver string for the tag name. Defaults to
131`'v'`. (So, by default it tags as 'v1.2.3' when versioning to 1.2.3.)
132
133#### `commitHooks` Boolean
134
135Run git commit hooks. Default true.
136
137#### `gitTagVersion` Boolean
138
139Tag the version, default true.
140
141#### `signGitCommit` Boolean
142
143GPG sign the git commit. Default `false`.
144
145#### `signGitTag` Boolean
146
147GPG sign the git tag. Default `false`.
148
149#### `force` Boolean
150
151Push forward recklessly if any problems happen. Default `false`.
152
153#### `ignoreScripts` Boolean
154
155Do not run pre/post/version lifecycle scripts. Default `false`.
156
157#### `scriptShell` String
158
159Path to the shell, which should execute the lifecycle scripts. Defaults to `/bin/sh` on unix, or `cmd.exe` on windows.
160
161#### `message` String
162
163The message for the git commit and annotated git tag that are created.
164