grunt-simple-git

A simple API for using git via 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-simple-git --save-dev

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

grunt.loadNpmTasks('grunt-simple-git');

Alternatively, install and use task-master, and it will handle this for you.

The "git" task

This plugin uses the simple-cli interface, so any of the options avaiable there will work with this plugin. A summary of the more salient points are included below.

Overview

The git task is a multiTask, where the target is (usually) the git command to run. Options to git can be supplied in the options object, and there are various options supported by the library itself which must be under options.simple.

Git Options

Generally speaking, options are supplied as camel-cased equivalents of the command line options. Specifically, you can do any/all of the following:

Long options

grunt.initConfig({
  git: {
    commit: {
      options: {
        message: '"Fix stuff"'
      }
    }
  }
});

This will run git commit --message "Fix stuff"

Boolean options

grunt.initConfig({
  git: {
    status: {
      options: {
        short: true
      }
    }
  }
});

This will run git status --short

Multi-word options

grunt.initConfig({
  git: {
    diff: {
      options: {
        nameOnly: true
      }
    }
  }
});

This will run git diff --name-only

Short options

grunt.initConfig({
  git: {
    commit: {
      options: {
        m: '"Fix stuff"'
      }
    }
  }
});

This will run git commit -m "Fix stuff"

Short boolean options

grunt.initConfig({
  git: {
    status: {
      options: {
        s: true
      }
    }
  }
});

This will run git status -s

Multiple short options grouped together

grunt.initConfig({
  git: {
    commit: {
      options: {
        a: true,
        n: true,
        m: '"Fix stuff"'
      }
    }
  }
});

This will run git commit -an -m "Fix stuff"

Options with equal signs

grunt.initConfig({
  git: {
    show: {
      options: {
        'format=': 'short'
      }
    }
  }
});

This will run git show --format=short

Arrays of options

I couldn't find a legitimate git command that would use this, but if such a thing exists, it would work.

grunt.initConfig({
  git: {
    fake: {
      options: {
        a: ['foo', 'bar'],
        greeting: ['hello', 'goodbye']
      }
    }
  }
});

This will run git fake -a foo -a bar --greeting hello --greeting goodbye, which, as previously mentioned, is nothing.

Task Options

Simple cli can be configured by specifying any of the following options under options.simple.

env

Supply additional environment variables to the child process.

grunt.initConfig({
  git: {
    status: {
      options: {
        simple: {
          env: {
            FOO: 'bar'
          }
        }
      }
    }
  }
});

cwd

Set the current working directory for the child process.

grunt.initConfig({
  git: {
    status: {
      options: {
        simple: {
          cwd: './test'
        }
      }
    }
  }
});

force

If the task fails, don't halt the entire task chain.

grunt.initConfig({
  git: {
    status: {
      options: {
        simple: {
          force: true
        }
      }
    }
  }
});

onComplete

A callback to handle the stdout and stderr streams. simple-cli aggregates the stdout and stderr data output and will supply the final strings to the onComplete function. This function should have the signature function(err, stdout, callback) where err is an error object containing the stderr stream (if any errors were reported) and the code returned by the child process (as err.code), stdout is a string, and callback is a function. The callback must be called with a falsy value to complete the task (calling it with a truthy value - e.g. 1 - will fail the task).

grunt.initConfig({
  git: {
    branch: {
      options: {
        simple: {
          onComplete: function(err, stdout, callback) {
            if (err) {
              grunt.fail.fatal(err.message, err.code);
            } else {
              grunt.config.set('cli output', stdout);
              callback();
            }
          }
        }
      }
    }
  }
});

cmd

An alternative sub-command to call on the cli. This is useful when you want to create multiple targets that call the same command with different options/parameters. If this value is present, it will be used instead of the grunt target as the first argument to the executable.

grunt.initConfig({
  // Using git as a real example
  git: {
    pushOrigin: {
      options: {
        simple: {
          cmd: 'push',
          args: ['origin', 'master']
        }
      }
    },
    pushHeroku: {
      options: {
        simple: {
          cmd: 'push',
          args: 'heroku master'
        }
      }
    }
  }
});

Running grunt git:pushOrigin will run git push origin master and running grunt git:pushHeroku will run git push heroku master.

args

Additional, non-flag arguments to pass to the executable. These can be passed as an array (as in git:pushOrigin above) or as a single string with arguments separated by a space (as in git:pushHeroku above).

rawArgs

rawArgs is a catch all for any arguments to git that can't be handled (for whatever reason) with the options above (e.g. the path arguments in some git commands: git checkout master -- config/production.json). Anything in rawArgs will be concatenated to the end of all the normal args.

grunt.initConfig({
  git: {
    checkout: {
      options: {
        simple: {
          args: ['master'],
          rawArgs: '-- config/production.json'
        }
      }
    }
  }
});

debug

Similar to --dry-run in many executables. This will log the command that will be spawned in a child process without actually spawning it. Additionally, if you have an onComplete handler, a fake stderr and stdout will be passed to this handler, simulating the real task. If you want to use specific stderr/stdout messages, debug can also be an object with stderr and stdout properties that will be passed to the onComplete handler.

grunt.initConfig({
  git: {
    branch: {
      options: {
        simple: {
          // Invoked with default fake stderr/stdout
          onComplete: function(err, stdout, callback) {
            console.log(arguments);
          },
          debug: true
        }
      }
    },
    status: {
      options: {
        simple: {
          // Invoked with 'foo' and 'bar'
          onComplete: function(err, stdout, callback) {
            console.log(arguments);
          },
          debug: {
            stderr: 'foo',
            stdout: 'bar'
          }
        }
      }
    }
  }
});

Additionally, you can pass the --debug option to grunt itself to enable the above behavior in an ad hoc manner.

Dynamic values

Sometimes you just don't know what values you want to supply to for an option until you're ready to use it (for instance, --message in a commit task). That makes it hard to put into a task. simple-cli supports dynamical values (via interpolation) which can be supplied in any of three ways:

via command line options to grunt (e.g. grunt.option)

Supply the value when you call the task itself.

grunt.initConfig({
  git: {
    push: {
      options: {
        simple: {
          // You can also do this as a string, but note that simple-cli splits
          // string args on space, so you wouldn't be able to put space INSIDE
          // the interpolation. You'd have to say args: '{{remote}} master'
          args: ['{{ remote }}', 'master']
        }
      }
    }
  }
});

If the above was invoked with grunt git:push --remote origin the final command would be git push origin master.

via grunt.config

This is primarily useful if you want the result of another task to determine the value of an argument. For instance, maybe in another task you say grunt.config.set('remote', 'heroku'), then the task above would run git push heroku master.

via prompt

If simple-cli can't find an interpolation value via grunt.option or grunt.config, it will prompt you for one on the terminal. Thus you could do something like:

grunt.initConfig({
  git: {
    commit: {
      options: {
        message: '{{ message }}'
      }
    }
  }
});

and automate commits, while still supplying an accurate commit message.

Shortcut configurations

For very simple tasks, you can define the task body as an array or string, rather than as an object, as all the above examples have been.

grunt.initConfig({
  git: {
    // will invoke "git push origin master"
    origin: ['push', 'origin', 'master'],

    // will invoke "git pull upstream master"
    upstream: 'pull upstream master'
  }
});