grunt-git

Git commands for grunt.

Getting Started

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 --save-dev

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

grunt.loadNpmTasks('grunt-git');

Upgrading from v0.2.x

The gitcommit command used to call git add for you. This is no longer the case. Be sure to add a gitadd task whenever there might be new files to commit. The ignoreEmpty option is no longer supported.

Universal options

The following options may be applied to any task

options.verbose

Type: BooleanDefault value: none

Console output from the git task will be piped to the output of the grunt script. Useful for debugging.

options.cwd

Type: stringDefault value: none

Change the current working directory before executing the git call. Useful for performing operations on repositories that are located in subdirectories.Note: When performing commands that provide files (e.g. gitcommit), it is also necessary to specify the cwd for the files explicitly.

Example:

grunt.initConfig({  gitcommit: {    your_target: {      options: {        cwd: "/path/to/repo"      },      files: [        {          src: ["fileone.txt", "filetwo.js"],          expand: true,          cwd: "/path/to/repo"        }      ]    }  },})

The "gitadd" task

Add file contents to the index

Options

options.all

Type: BooleanDefault value: false

Update the index not only where the working tree has a file matching but also where theindex already has an entry. This adds, modifies, and removes index entries to match the working tree.

options.force

Type: BooleanDefault value: false

Allow adding otherwise ignored files.

Usage Examples

grunt.initConfig({  gitadd: {    task: {      options: {        force: true      },      files: {        src: ['test.txt']      }    }  },});

The "gitcommit" task

Commits the working directory.

Overview

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

grunt.initConfig({  gitcommit: {    your_target: {      options: {        // Target-specific options go here.      },      files: {          // Specify the files you want to commit      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.message

Type: StringDefault value: 'Commit'

The commit message.

options.description

Type: StringDefault value: false

The commit description.

options.allowEmpty

Type: BooleanDefault value: false

When true, the task will not fail when there are no staged changes (optional).

options.noVerify

Type: BooleanDefault value: false

When true, the task will commit the changes with the --no-verify flag.

options.noStatus

Type: BooleanDefault value: false

When true, the task will commit the changes with the --no-status flag.

Usage Examples

Commit options:

• message: Commit message
• files: Files to commit
• noVerify: Bypass the pre-commit and commit-msg hooks when committing changes
• noStatus: Do not include the output of git-status in the commit message

grunt.initConfig({    gitcommit: {        task: {            options: {                message: 'Testing',                noVerify: true,                noStatus: false            },            files: {                src: ['test.txt']            }        }    },});

The "gitrebase" task

Rebases the current branch onto another branch

Options

options.branch (required)

Type: Stringthe name of the branch you want to rebase on to. For example if the current branch were codfish and you wanted to rebase it onto master, you would set this value to master.

options.theirs

Type: BooleanDefault value: false

When true, use the git equivalent of svn's theirs-conflict (--strategy=recursive -Xtheirs).

Usage Examples

grunt.initConfig({  gitrebase: {    task: {      options: {        branch: 'master'      }    }  },});

The "gittag" task

Creates (or deletes) a git tag.

Overview

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

grunt.initConfig({  gittag: {    your_target: {      options: {        // Target-specific options go here.      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.tag

Type: StringDefault value: ''

The name of the tag. E.g.: 0.0.1.

options.message

Type: StringDefault value: ''

The tag message (optional).

options.remove

Type: BooleanDefault value: false

Whether to delete the tag (optional).

options.annotated

Type: BooleanDefault value: false

Whether to create an annotated tag (optional).

options.force

Type: BooleanDefault value: false

Whether to force to create or update the tag (optional).

Usage Examples

grunt.initConfig({    gittag: {        addtag: {            options: {                tag: '0.0.1',                message: 'Testing'            }        },        deletetag: {            options: {                tag: '0.0.1',                remove: true            }        }    },});

The "gitcheckout" task

Creates a git branch using checkout -b, or checks out a given branch.

Overview

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

grunt.initConfig({  gitcheckout: {    your_target: {      options: {        // Target-specific options go here.      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.branch

Type: StringDefault value: ''

The name of the branch. E.g.: testing.

options.create

Type: BooleanDefault value: false

Whether the branch should be created (optional).

options.force

Type: BooleanDefault value: false

Whether the checkout should be forced in the case of git errors (optional)

options.overwrite

Type: BooleanDefault value: false

Whether the branch should be overwritten, or created if it doesn't already exist (optional).

NOTE: When enabled, this option overwrites the target branch with the current branch.

Usage Examples

grunt.initConfig({    gitcheckout: {        task: {            options: {                branch: 'testing',                create: true            }        }    },});

The "gitstash" task

Stash the changes in a dirty working directory away.

Overview

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

grunt.initConfig({  gitstash: {    your_target: {      options: {        // Target-specific options go here.      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.command

Type: StringDefault value: 'save'

The stash command to run. E.g.: save, apply.

options.stash

Type: IntegerDefault value: ''

The stash to apply. E.g.: 0 (optional).

options.staged

Type: BooleanDefault value: false

Whether the staged changes should be reapplied (optional).

Usage Examples

grunt.initConfig({    gittag: {        stash: {            options: {                create: true            }        },        apply: {            options: {                command: 'apply',                staged: true,                stash: '0'            }        }    },});

The "gitclone" task

Clones a git repo.

Overview

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

grunt.initConfig({  gitclone: {    your_target: {      options: {        // Target-specific options go here.      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.bare

Type: BooleanDefault value: none

Run git clone with the --bare option applied.

options.branch

Type: StringDefault value: none

Clone the repo with a specific branch checked out. (Cannot be used in conjunction with 'bare')

options.depth

Type: IntegerDefault value: none

Clone the repo with a limited revision history. (Such clones cannot be pushed from or pulled to.)

options.repository (required)

Type: StringDefault value: none

The path to the repository you want to clone.

options.directory

Type: StringDefault value: none

Clone the repo into a specific directory instead of the one git decides.

options.recursive

Type: BooleanDefault value: none

Pass the --recursive flag to the git clone command. This is equivalent to running git submodule update --init --recursive immediately after the clone is finished.

Usage Examples

grunt.initConfig({    gitclone: {        clone: {            options: {                repository: 'https://github.com/you/your-git-repo.git',                branch: 'my-branch',                directory: 'repo'            }        }    },});

The "gitreset" task

Creates a git branch using checkout -b, or checks out a given branch.

Overview

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

grunt.initConfig({  gitreset: {    your_target: {      options: {        // Target-specific options go here.      },      files: {        src: // Target-specific files go here.      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.mode

Type: StringDefault value: ''

The reset mode to run. E.g.: hard, merge.

options.commit

Type: StringDefault value: 'HEAD'

Which commit to reset to (optional).

Usage Examples

grunt.initConfig({    gitreset: {        task: {            options: {                mode: 'hard',                commit: 'HEAD~1'            }        }    },});

The "gitrm" task

Removes files from git's working tree and index.

Overview

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

grunt.initConfig({  gitrm: {    your_target: {      options: {        // Target-specific options go here.      },      files: {        src: // Target-specific files go here.      }    }  },})

Each target defines a specific git task that can be run. The different available tasks are listed below.

Options

options.force

Type: BooleanDefault value: false

Will force a removal of the files listed in the configuration.

options.recurse

Type: BooleanDefault value: false

Will recurse into subdirectories if specified in the configuration.

Usage Examples

grunt.initConfig({    gitrm: {        task: {            options: {                force: 'true'            },            files: {                src: ['dist/test.min.js']            }        }    },});

The "gitclean" task

Remove untracked files from the working tree.

Overview

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

grunt.initConfig({  gitclean: {    your_target: {      options: {        // Target-specific options go here.      },      files: {        src: // Target-specific paths go here (optional).      }    }  },})

Options

options.force

Type: BooleanDefault value: true

Force a run of the clean command (optional).

options.dry

Type: BooleanDefault value: false

Don't actually remove anything, just show what would be done (optional).

options.quiet

Type: BooleanDefault value: false

Be quiet, only report errors, but not the files that are successfully removed (optional).

options.exclude

Type: String/ArrayDefault value: false

In addition to those found in .gitignore (per directory) and $GIT_DIR/info/exclude, also consider the given patterns to be in the set of the ignore rules in effect (optional).

In case it's needed to provide multiple patterns one should use an array:

grunt.initConfig({  gitclean: {    your_target: {      options: {        exclude: ['.env', 'config.php']      },      ...    }  },})

options.onlyignorefiles

Type: BooleanDefault value: false

Remove only files ignored by Git. This may be useful to rebuild everything from scratch, but keep manually created files (optional).

options.nonstandard

Type: BooleanDefault value: false

Don't use the standard ignore rules read from .gitignore (per directory) and $GIT_DIR/info/exclude, but do still use the ignore rules given with this option. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with git reset) to create a pristine working directory to test a clean build (optional).

options.directories

Type: BooleanDefault value: false

Remove untracked directories in addition to untracked files. If an untracked directory is managed by a different Git repository, it is not removed by default (optional).

The "gitpush" task

Pushes to a remote.

Overview

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

grunt.initConfig({  gitpush: {    your_target: {      options: {        // Target-specific options go here.      }    }  },})

Options

options.remote

Type: StringDefault value: 'origin'

The remote where to push. E.g.: origin, heroku. The task will push to origin if left unset.

options.branch

Type: StringDefault value: null

The remote branch to push to. E.g.: master, develop. The task will push to the tracked branch if left unset.

options.all

Type: BooleanDefault value: false

Will add the --all flag to the push.

options.tags

Type: BooleanDefault value: false

Will add the --tags flag to the push.

options.upstream

Type: BooleanDefault value: false

Will add the --set-upstream flag to the push.

options.force

Type: BooleanDefault value: false

Will add the --force flag to the push.

The "gitpull" task

Pulls from a remote.

Overview

In your project's Gruntfile, add a section named gitpull to the data object passed into grunt.initConfig().You can change the remote (origin is by default), and you can add a branch you want to pull from.

grunt.initConfig({  gitpull: {    your_target: {      options: {      }    }  },})

Options

options.remote

Type: StringDefault value: origin

The remote to pull from. The task will not fail if the origin is left unset and pull the default remote git origin.

options.branch

Type: StringDefault value: master

The branch to pull from. E.g.: master, develop (optional).

The "gitfetch" task

Download objects and refs from a repo.

Overview

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

grunt.initConfig({  gitfetch: {    your_target: {      options: {        all: true      }    }  }})

Options

options.repository

Type: StringDefault value: null

The repository you want to fetch from. When no remote is specified, by default the origin remote will be used.

options.all

Type: BooleanDefault value: false

Adds the --all flag. Fetch all remotes.

options.append

Type: BooleanDefault value: false

Adds the --append flag. Append ref names and object names of fetched refs.

options.prune

Type: BooleanDefault value: false

Adds the --prune flag. After fetching, remove any remote-tracking references that no longer exist on the remote.

options.notags

Type: BooleanDefault value: false

Adds the --no-tags flag. Disables automatic tag following.

options.tags

Type: BooleanDefault value: false

Adds the --tags flag. Fetch all tags from the remote into local.

The "gitrevParse" task

Pick out and massage parameters.

Overview

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

grunt.initConfig({  gitrevParse: {    your_target: {      options: {        short: 7,        treeIsh: 'master',        prop: 'gitrevParse.your_target.result',        callback: function(result) {          grunt.gitrevParse.your_target.result = result;        }      }    }  }})

Options

options.short

Type: IntegerDefault value: none.

Adds the --short= option, set to the specified number of characters.

options.treeIsh

Type: StringDefault value: 'HEAD'

The tree or commit object to examine.

options.abbrevRef

Type: BooleanDefault value: false

Adds the --abbrev-ref flag. Try and output the abbreviated reference for the tree-ish object instead of the SHA-1 checksum.

options.prop

Type: StringDefault value: 'gitrevParse.<target name>.result'.

The grunt property in which to store the results.

options.callback

Type: FunctionDefault value: none.

A callback function that is called with the rev-parse results provided as the sole parameter.

The "gitmerge" task

Merges another branch into the current branch.

Overview

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

grunt.initConfig({  gitmerge: {    your_target: {      options: {        // Target-specific options go here.      }    }  },})

Options

options.branch

Type: StringDefault value: null

The branch to merge from. E.g.: master, develop. The task will fail if the branch if left unset.

options.ffOnly

Type: BooleanDefault value: false

Will add the --ff-only flag to the merge.

options.noff

Type: BooleanDefault value: false

Will add the --no-ff flag to the merge.

options.nolog

Type: BooleanDefault value: false

Will add the --no-log flag to the merge.

options.squash

Type: BooleanDefault value: false

Will add the --squash flag to the merge.

options.edit

Type: BooleanDefault value: false

Will add the --edit flag to the merge: this forces an editor to appear before committing the successful merge.

options.noEdit

Type: BooleanDefault value: false

Will add the --no-edit flag to the merge: this bypasses the editor from appearing before committing a successful merge.

options.message

Type: StringDefault value: null

Will add the -m flag followed by the value of this option to the merge: this string will be used as the commit message for the merge.

options.commit

Type: BooleanDefault value: false

Will add the --commit flag to the merge: this option can be used to override -no-commit in the git config.

options.noCommit

Type: BooleanDefault value: false

Will add the --no-commit flag to the merge: do not commit the merge.

options.strategy

Type: StringDefault value: null

Will add the -s flag followed by the value of this option to the merge: this string will be used to specify the strategy for the merge.

options.strategyOption

Type: StringDefault value: null

Will add the -X flag followed by the value of this option to the merge: this string will be used to specify a strategy-specific option for the merge.

The "gitarchive" task

Archives a branch.

Overview

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

grunt.initConfig({  gitarchive: {    master: {      options: {        format: 'tar.gz',        prefix: 'your-project-name/',        treeIsh: 'master',        output: '/tmp/your-project-name.tar.gz',        path: ['README', 'LICENSE']      }    }  }})

Options

options.treeIsh

Type: StringDefault