Numerous Pulls Merged

    grunt-changelog

    0.3.2 • Public • Published

    npm version Build Status devDependency Status Dependency Status peerDependency Status

    grunt-changelog

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

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

    grunt.loadNpmTasks('grunt-changelog');

    The "changelog" task

    Overview

    In your project's Gruntfile, add a section named changelog to the data object passed into grunt.initConfig(). The task, by default, will go through the last 7 days of commit messages, looking for issues that were closed or fixed. It will then generate a template-based changelog with those changes and write them to a destination file.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {
            // Task-specific options go here.
          }
        }
      },
    })
    NEW:
    
      - Feature 1
      - Feature 2
      - Feature 3
    
    FIXES:
    
      - Fix 1
      - Fix 2
    

    Options

    options.fileHeader

    Type: String Default value: undefined

    The string will be placed on top of the changelog.

    options.after

    Type: String Default value: 7 days ago

    A date string, commit SHA, or tag that the git log will start at.

    options.before

    Type: String Default value: now

    A date string, commit SHA, or tag that the git log will end at. The type must match what was used for after (e.g. you cannot use a date string for after and a commit SHA for before).

    options.featureRegex

    Type: RegEx Default value: /^(.*)closes #\d+:?(.*)$/gim

    The regular expression used to match feature changes.

    options.fixRegex

    Type: RegEx Default value: /^(.*)fixes #\d+:?(.*)$/gim

    The regular expression used to match bug fix changes.

    options.log

    Type: String Default value: undefined

    The log file to parse for changes. If nothing is set, a git log command will be run.

    options.dest

    Type: String Default value: changelog

    The file path to write the changelog to.

    options.insertType

    Type: String Default value: undefined

    Can be set to prepend, or append. This will prepend / append the changelog to the file set by options.dest. If nothing is set, the options.dest file will be overwritten.

    options.template

    Type: String Default value: {{> features}}{{> fixes}}

    The Handlebars template used for creating the changelog.

    options.partials.features

    Type: String Default value: 'NEW:\n\n{{#if features}}{{#each features}}{{> feature}}{{/each}}{{else}}{{> empty}}{{/if}}\n'

    The Handlebars partial used for the list of features.

    options.partials.feature

    Type: String Default value: ' - {{{this}}}\n'

    The Handlebars partial used for each individual feature.

    options.partials.fixes

    Type: String Default value: 'FIXES:\n\n{{#if fixes}}{{#each fixes}}{{> fix}}{{/each}}{{else}}{{> empty}}{{/if}}'

    The Handlebars partial used for the list of fixes.

    options.partials.fix

    Type: String Default value: ' - {{{this}}}\n'

    The Handlebars partial used for each individual fix.

    options.partials.empty

    Type: String Default value: ' (none)\n'

    The Handlebars partial used by features or fixes when there are no changes.

    options.logArguments

    Type: Array Default value: ['--pretty=format:%s', '--no-merges']

    See http://git-scm.com/book/en/Git-Basics-Viewing-the-Commit-History

    Usage Examples

    Default Options

    In this example, the default options are used to create the changelog. A git log command will run for logs starting 7 days ago until now and the changelog will be generated matching commit messages with fixes and closes.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {}
        }
      },
    })

    changelog.txt

    NEW:
    
      - Feature 1
      - Feature 2
      - Feature 3
    
    FIXES:
    
      - Fix 1
      - Fix 2
    

    File header

    This examples uses the option fileHeader to prepend a custom string to the changelog.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {
           fileHeader: '# Changelog'
          }
        }
      },
    })

    changelog.txt

    # Changelog
    
    NEW:
    
      - Feature 1
      - Feature 2
      - Feature 3
    
    FIXES:
    
      - Fix 1
      - Fix 2
    

    Custom Range

    In this example, a custom date range is used to only show changes between March 1st and March 14th.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {
            after: '2013-03-01',
            before: '2013-03-14'
          }
        }
      },
    })

    You can also pass values for after and before directly.

    From 1/12/2014 to today

    $ grunt changelog:sample:1/12/2014
    

    From commit dffcc01 to 6408ff7

    $ grunt changelog:sample:dffcc01:6408ff7
    

    From tag 0.9.8 to HEAD

    $ grunt changelog:sample:0.9.8
    

    Custom Destination

    In this example, a custom destination is used to write the changelog to a different location.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {
            dest: 'release-notes/<%= package.version %>.txt'
          }
        }
      },
    })

    Custom Formatting

    In these examples, custom formatting is used to create a simple changelog with the list of features and fixes.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {
            dest: 'release-notes/<%= package.version %>.txt',
            template: '{{date}}\n\n{{> features}}{{> fixes}}'
          }
        }
      },
    })

    release-notes/1.0.0.txt

    2013-05-01
    
    NEW:
    
      - Feature 1
      - Feature 2
      - Feature 3
    
    FIXES:
    
      - Fix 1
      - Fix 2
    
    grunt.initConfig({
      changelog: {
        sample: {
          options: {
            dest: 'release-notes/<%= package.version %>.txt',
            partials: {
              features: '{{#each features}}{{> feature}}{{/each}}',
              feature: '[NEW] {{this}}\n',
              fixes: '{{#each fixes}}{{> fix}}{{/each}}',
              fix: '[FIX] {{this}}\n'
            }
          }
        }
      },
    })

    release-notes/1.0.0.txt

    [NEW] Feature 1
    [NEW] Feature 2
    [NEW] Feature 3
    [FIX] Fix 1
    [FIX] Fix 2
    

    Custom git log arguments

    The following example generates a simple changelog without separation of Commit types.

    grunt.initConfig({
      changelog: {
        sample: {
          options: {
            logArguments: [
              '--pretty=* %h - %ad: %s',
              '--no-merges',
              '--date=short'
            ],
            template: '{{> features}}',
            featureRegex: /^(.*)$/gim,
            partials: {
              features: '{{#if features}}{{#each features}}{{> feature}}{{/each}}{{else}}{{> empty}}{{/if}}\n',
              feature: '- {{this}} {{this.date}}\n'
            }
          }
        }
      },
    })

    changelog.txt

    * c0d309b - 2014-08-20: Fix typo in readme. 
    * 7d84867 - 2014-04-11: Bumped to 0.2.2 
    * 2280e9c - 2014-04-07: Optionally prepend or append the changelog.  Fixes #5
    

    Contributing

    Anyone and everyone is welcome to contribute. Please take a moment to review the guidelines for contributing.

    Install

    npm i grunt-changelog

    DownloadsWeekly Downloads

    99

    Version

    0.3.2

    License

    MIT

    Last publish

    Collaborators

    • ericmatthys
    • mischah