Describes current git commit
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Build Status NPM version


Describes git commit

Getting Started

This plugin requires Grunt ~0.4.0

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. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-git-describe --save-dev

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:


The "git-describe" task


In your project's Gruntfile, add a section named git-describe to the data object passed into grunt.initConfig().

  "git-describe": {
    "options": {
      // Task-specific options go here.
    "your_target": {
      // Target-specific file lists and/or options go here.

Note that since this is a multi-task you have to have at least one target defined for git-describe (otherwise the task won't run)



Type: String
Default value: '.'

A string value that is used to do set the current working directory when spawning the git command


Type: String
Default value: undefined

A string value that is used as commitish for git. Default is to use HEAD.


Type: String
Default value: {%=tag%}-{%=since%}-{%=object%}{%=dirty%}

A string value used to format the result of this task


Type: String Default value: undefined

Value for the --match command line option. If set, only consider tags matching this glob pattern, excluding the "refs/tags/" prefix.


Type: boolean
Default value: true

A boolean that allows Grunt to keep going if there's an error in this task. This is useful if your build isn't guaranteed to always be run from within a Git repo.

Saving Output

If you would like to save or otherwise use the retun value, use grunt.event.emit. Here is an example:

grunt.registerTask('saveRevision', function() {
    grunt.event.once('git-describe', function (rev) {
        grunt.log.writeln("Git Revision: " + rev);
        grunt.option('gitRevision', rev);

Returned Object

The rev object returned makes several specific properties available, in addition to the full toString description.

grunt.event.once('git-describe', function (rev) {
  grunt.log.writeln("Git rev tag: " + rev.tag);
  grunt.log.writeln("Git rev since: " + rev.since);
  grunt.log.writeln("Git rev object: " + rev.object); // The 6 character commit SHA by itself
  grunt.log.writeln("Git rev dirty: " + rev.dirty);   // A flag denoting whether all local changes are committed