Version read/write plugin for release-it
npm install @release-it/bumperThis plugin reads and/or writes version/manifest files.
``sh`
npm install --save-dev @release-it/bumper
In [release-it][1] config:
`json`
"plugins": {
"@release-it/bumper": {
"in": "composer.json",
"out": "composer.json",
}
}
- Use only the in option to _read_ the version from this file in the release-it process.out
- Use only the option to _write_ the version that was determined by release-it to this file.version
- Use both to read _and_ write the property from/to this file.
The version from the in file will take precedence over the latest Git tag (and the version from package.json if
it exists) in release-it to determine the latest version.
Note that using package.json as out file may conflict with the npm plugin in release-it. Remove it from the out
file(s), or use [][2].
The supported file types are:
| Type | Extension(s) | Mime-type |
| ---- | ----------------- | --------------------------------------------------------- |
| JSON | .json | application/json |.yaml
| YAML | or .yml | text/yaml or application-x-yaml or application/yaml |.toml
| TOML | | text/toml or application/toml |.ini
| INI | | text/x-properties |.xml
| XML | | text/xml or application/xml |.html
| HTML | | text/html or application/xhtml+xml |.txt
| TEXT | | text/* |
Explicitly providing the (mime) type takes precedence over the file extension.
The fallback type is text if the file extension and/or type is not known (e.g. index.php).
`json`
"plugins": {
"@release-it/bumper": {
"in": {
"file": "VERSION",
"type": "text/plain"
},
"out": {
"file": "VERSION",
"type": "text/plain"
}
}
}
To replace all occurences of the current version with the new version in any text file:
`json`
"plugins": {
"@release-it/bumper": {
"out": {
"file": "file.php",
"type": "text/php"
}
}
}
\:warning: the operation is a search-and-replace; if the current version is not found in the file, the new version
cannot be written out.
To instead always consume the entire file, that is, the whole and only content of the file is the version number, set
consumeWholeFile: true for the out option:
`json`
"plugins": {
"@release-it/bumper": {
"out": {
"file": "VERSION",
"type": "text/plain",
"consumeWholeFile": true
}
}
}
The version number is then written to the output file, overwriting it completely instead of a search-and-replace.
\:bulb: Setting consumeWholeFile: true precludes the use of prefixes, such as v1.0.1 in the output file.
The out option can also be an array of files:
`json`
"plugins": {
"@release-it/bumper": {
"out": ["manifest.json", "bower.json"]
}
}
The out option is parsed with [fast-glob][3], so glob patterns can be used to match files to write to:
`json`
"plugins": {
"@release-it/bumper": {
"out": "dist/*.json"
}
}
The path option (default: "version") can be used to change a different property. The following example will set thecurrent.version property to the new version in manifest.json:
`json`
"plugins": {
"@release-it/bumper": {
"out": {
"file": "manifest.json",
"path": "current.version"
}
}
}
> For the xml type, the path option must be in the form of a unique [css selector][4]. The following example willproject > version
> set the property to the new version in pom.xml:
`json`
"plugins": {
"@release-it/bumper": {
"out": {
"file": "pom.xml",
"path": "project > version",
"type": "application/xml"
}
}
}
For the html type, the path option must be in the form of a unique [css selector][4]. The following example will set#version
the element text content with the css attribute to the new version in foo.html:
`json`
"plugins": {
"@release-it/bumper": {
"out": {
"file": "foo.html",
"path": "#version",
"type": "text/html"
}
}
}
Multiple paths can be provided using an array.
The versionPrefix option (default: '') can be used in cases where you'd like to maintain a specific prefix for yourpackage.json
version number (for example, in where you might want versions like ^1.0.0). This will prepend the
specified prefix to the bumped version:
`json`
"plugins": {
"@release-it/bumper": {
"out": {
"file": "package.json",
"path": "version",
"prefix": "^"
}
}
}
With the above configuration, if release-it determines the new version to be 1.0.0, it'll be saved as ^1.0.0 in the
targeted file.
Options for this plugin can be set from the command line. Some examples:
`
release-it --plugins.@release-it/bumper.in=composer.json
release-it --plugins.@release-it/bumper.out=composer.json --plugins.@release-it/bumper.out=manifest.json
- Keys are separated by dots.
- Values can be negated by prefixing the key with no-.'
- Arguments may need to be single-quoted () such as --'deep.key=value' or '--deep.key=value'`
Depending on your shell or OS this may differ.
[1]: https://github.com/release-it/release-it
[2]: https://github.com/release-it/release-it/blob/master/docs/npm.md#extra-arguments
[3]: https://github.com/mrmlnc/fast-glob
[4]: https://www.w3.org/TR/selectors-4/#overview