grunt-git-readme

Create a README file, track changed files, and package for delivery.

Getting Started

This plugin requires Grunt.

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:

NOTE: this is a temporary url. This will change once it is a public module

npm install grunt-git-readme --save-dev

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

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

The "readme" task

Overview

This plugin works by passing in a git commit hash (EX: 36f4ddfa643feb92c55463094e3544258040aa60) and comparing the difference between this commit and the HEAD of your branch. You are able to pass in the commit as a parameter in the grunt call like so:

grunt package:HASH

Then, inside the "initConfig" method object, add the following code:

// package
readme: {
  options: {
    readmeTitle: 'Title of Project', // Default 'Title'
    src: ['<%= config.dev %>/'], // Default ['www/']
    dest: '<%= config.dev %>/packages/', // Default 'www/packages'
    author: '[e-mail]', // Default '[e-mail]'
    projectCode: 'Project Name', // Default 'README'
    gitDiffFile: true, // Default true
    showSnippets: true // Default true
  }
}

From here, you can register a specific task to call when you are ready to deploy. At the bottom of the file, after you have loaded the module add this:

grunt.registerTask('package', 'Creates a directory based on commit diffs.', function (commit) {
    // this commit is set in the command line as a property. Example: 'grunt package:COMMIT HASH'
    grunt.task.run('readme:' + commit);
  });

Example Gruntfile

'use strict';

module.exports = function (grunt) {
  // load all npm grunt tasks
  require('load-grunt-tasks')(grunt);

  // Project configuration.
  grunt.initConfig({
    readme: {
      options: {
        readmeTitle: 'Title of Project', // Default 'Title'
        src: ['<%= config.dev %>/'], // Default ['www/']
        dest: '<%= config.dev %>/packages/', // Default 'www/packages/'
        author: '[e-mail]', // Default '[e-mail]'
        projectCode: 'Project Name', // Default 'README'
        gitDiffFile: true, // Default true
        showSnippets: true // Default true
      }
    },
  });

  // Actually load this plugin's task(s).
  grunt.loadTasks('tasks');

  grunt.registerTask('package', 'Creates a directory based on commit diffs.', function (commit) {
    // this commit is set in the command line as a property. Example: 'grunt package:COMMIT HASH'
    grunt.task.run('clean', 'readme:' + commit);
  });

  // By default, lint and run all tests.
  grunt.registerTask('default', ['jshint']);

};

Options

readmeTitle

Type: String Default value: 'Title'

A string value that sets the title inside of your newly created README file.

src

Type: Array Default value: ['www/']

An array that determines which files should be added to the diff. EX: If you have a development directory (app/) and a production directory (www/) and only want to check against the production directory, set the value to ['www/'].

If you want to use include both the development directory and the production directory, set the value to ['www/', 'app/']. But feel free to add as many values as you would like.

EX: ['www/', 'www/assets/', 'www/tools/']

dest

Type: String Default value: 'www/packages/'

A string value that sets the destination of your newly created package.

author

Type: String Default value: '[e-mail]'

A string value that sets the name of the author deploying the code changes. This appears in the README file.

projectCode

Type: String Default value: 'README'

A string value that sets the name of the newly created directory. The output will be something like README yyyy-mm-dd. NOTE: You only have to set the title, the date is automatically added.

gitDiffFile

Type: Boolean Default value: true

If set to true, this will add a file to the directory that contains a full diff of all the file changes between the two commits.

showSnippets

Type: Boolean Default value: true

If set to true, this include code snippets for all modified files in the README.

TODO

Add the ability to compare two branches.

Release History

(Nothing yet)

License

Copyright (c) 2016 MCD Partners. Licensed under the MIT license.