Updates the version
, date
, and other properties in your JSON files.
The properties are updated only when already present in the original JSON file.
The plugin also detects and preserves the original indentation style.
This is a Grunt 0.4 plugin. If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.
Use npm to install and save the plugin into devDependencies
.
npm install grunt-bumpup --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-bumpup');
In your project's Gruntfile, add a section named bumpup
to the data object passed into grunt.initConfig()
. This is a
simple task, and does not conform to multi task options & files input types! All available configuration styles are
described below.
This is the most verbose form of the configuration:
grunt.initConfig({
bumpup: {
options: {
// Options go here.
},
files: [
// JSON files go here.
],
},
});
Default options and one JSON file:
grunt.initConfig({
bumpup: 'package.json'
});
grunt.initConfig({
bumpup: {
file: 'package.json'
}
});
Default options, and multiple JSON files:
grunt.initConfig({
bumpup: ['package.json', 'component.json']
});
grunt.initConfig({
bumpup: {
files: ['package.json', 'component.json']
}
});
Custom options:
grunt.initConfig({
bumpup: {
options: {
dateformat: 'YYYY-MM-DD HH:mm',
normalize: false
},
files: ['package.json', 'component.json']
}
});
Type: Boolean
Default: true
Whether to normalize all JSON files to have the same version. The version that is than bumped up and saved into all files is taken from the first file passed into the files array.
Type: String
Default: YYYY-MM-DD HH:mm:ss Z
A date format string used by moment.js' .format()
method. To see all available format tokens,
read the moment.js' format documentation.
Following is the list of valid moment.js ISO-8601 (computer and human readable) date formats.
YYYY-MM-DD
YYYY-MM-DDTHH
YYYY-MM-DD HH
YYYY-MM-DDTHH:mm
YYYY-MM-DD HH:mm
YYYY-MM-DDTHH:mm:ss
YYYY-MM-DD HH:mm:ss
YYYY-MM-DDTHH:mm:ss.SSS
YYYY-MM-DD HH:mm:ss.SSS
YYYY-MM-DDTHH:mm:ss Z
YYYY-MM-DD HH:mm:ss Z
The dates are set in the UTC timezone, so including the Z token is recommended.
You can define your own property setters by passing them as a function in options object as a property name that should
be updated. For example, this will update the timestamp
property inside package.json
:
grunt.initConfig({
bumpup: {
options: {
timestamp: function (old) {
return +new Date();
}
},
file: 'package.json'
}
});
You can also override the default property setters for version
and date
properties if you want some more control,
or, lets say in a version
property, when you are not using a Semantic Versioning, and need to define a custom version
bumping style.
All setters receive the old property value as a first argument.
The version
setter receives the bump type from the CLI bumpup:type
as a 2nd argument. Example:
grunt.initConfig({
bumpup: {
options: {
version: function (old, type) {
return newVersion; // Bump based on a `type` argument
}
},
file: 'package.json'
}
});
The date
setter receives the option.dateformat
as a 2nd argument.
grunt.initConfig({
bumpup: {
options: {
date: function (old, dateformat) {
return moment.utc().format(dateformat);
}
},
file: 'package.json'
}
});
Each setter has to return the new property value, or when something went wrong, grunt.fail.warn()
an error and return
undefined
.
You call this task from the CLI with one argument, specifying the release type:
grunt bumpup:type
The default version
setter accepts these types:
- major: Will bump the major part of a version, resetting minor, patch, and build to 0.
- minor: Will bump the minor part of a version, resetting patch, and build to 0.
- patch: Will bump the patch part of a version, resetting build to 0.
- build: Will bump the build part of a version.
Version format: major.minor.patch-build
.
The build part is adjusted only when present. If you have a 1.0.0
version, the -build
part won't be appended unless
already present, or you've called the task with build
argument:
grunt bumpup:build
In this example, we create a "release" task alias that handles everything needed to build a new project release:
// Task configurations
grunt.initConfig({
jshint: ...,
uglify: ...,
bumpup: 'package.json'
});
// Loading the plugins
grunt.loadNpmTasks('grunt-contrib-jshint');
grunt.loadNpmTasks('grunt-contrib-uglify');
grunt.loadNpmTasks('grunt-bumpup');
// Alias task for release
grunt.registerTask('release', function (type) {
type = type ? type : 'patch'; // Set the release type
grunt.task.run('jshint'); // Lint stuff
grunt.task.run('uglify'); // Minify stuff
grunt.task.run('bumpup:' + type); // Bump up the version
});
And now you can call it from CLI like this:
grunt release:minor
After bumpup executes, it updates the JSON properties that other tasks in queue running after it might want to use. For
example, if you have a pkg
config property for easy access:
grunt.initConfig({
pkg: grunt.file.readJSON('package.json')
});
And you want to execute a task that uses this property immediately after bumpup, you have to tell grunt that this property has changed. You can update the property like this:
grunt.config.set('pkg', grunt.file.readJSON('package.json'));
But this has to be done in the grunt task queue right after the bumpup, otherwise it won't have any effect, as grunt
tasks are asynchronous. The solution is to place it into an alias task, add to queue right after bumpup. This is the
final release task using updating pkg
property:
// Task for updating the pkg config property. Needs to be run after
// bumpup so the next tasks in queue can work with updated values.
grunt.registerTask('updatePkg', function () {
grunt.config.set('pkg', grunt.file.readJSON('component.json'));
});
// Release task.
grunt.registerTask('release', function (type) {
type = type ? type : 'patch';
grunt.task.run('jshint');
grunt.task.run('bumpup:' + type);
grunt.task.run('updatePkg');
grunt.task.run('build');
grunt.task.run('tagrelease');
});