Negatory. Postpone Mission.
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Release Notes

    Generate release note pages from git commit history.


    It's preferable to install it globally through npm

    npm install -g git-release-notes

    It's also possible to use git-release-notes as a node module. Check the usage on usage as a module


    The basic usage from the command line is

    cd <your_git_project>
    git-release-notes <since>..<until> <template>


    • <since>..<until> specifies the range of commits as in git log, see gitrevisions(7)
    • <template> is an ejs template file used to generate the release notes

    Three sample templates are included as a reference in the templates folder

    This for example is the release notes generated for joyent/node by running

    git-release-notes v0.9.8..v0.9.9 html > changelog.html

    Node's release notes

    Custom template

    The second parameter of git-release-notes can be any path to a valid ejs template files.

    Template Variables

    Several template variables are made available to the script running inside the template.

    commits is an array of commits, each containing

    • sha1 commit hash (%H)
    • authorName author name (%an)
    • authorEmail author email (%ae)
    • authorDate author date (%aD)
    • committerName committer name (%cn)
    • committerEmail committer email (%ce)
    • committerDate committer date (%cD)
    • title subject (%s)
    • messageLines array of body lines (%b)

    dateFnsFormat is the date-fns format function. See the html-bootstrap for sample usage.

    range is the commits range as passed to the command line


    More advanced options are

    • p or path Git project path, defaults to the current working path
    • b or branch Git branch, defaults to master
    • t or title Regular expression to parse the commit title (see next chapter)
    • i or ignore-case Ignore case flag for title's regular expression. /.*/ becomes /.*/i
    • m or meaning Meaning of capturing block in title's regular expression
    • f or file JSON Configuration file, better option when you don't want to pass all parameters to the command line, for an example see options.json
    • s or script External script for post-processing commits
    • c or merge-commits List only merge commits, git log command is executed with the --merges flag instead of --no-merges
    • o or gitlog-option to add some additional git log options and ignores the merge-commits option, this is direct given to git log by adding a -- to each longname option from the array (e.g. -o first-parent).

    Title Parsing

    Some projects might have special naming conventions for the commit title.

    The options t and m allow to specify this logic and extract additional information from the title.

    For instance, Aria Templates has the following convention

    fix #123 Title of a bug fix commit
    feat #234 Title of a cool new feature

    In this case using

    git-release-notes -t "^([a-z]+) #(\d+) (.*)$" -m type -m issue -m title v1.3.6..HEAD html

    generates the additional fields on the commit object

    • type first capturing block
    • issue second capturing block
    • title third capturing block (redefines the title)

    Another project using similar conventions is AngularJs, commit message conventions.

    git-release-notes -t "^(\w*)(?:\(([\w\$\.]*)\))?\: (.*)$" -m type -m scope -m title v1.1.2..v1.1.3 markdown

    Post Processing

    The advanced options cover the most basic use cases, however sometimes you might need some additional processing, for instance to get commit metadata from external sources (Jira, GitHub, Waffle...)

    Using -s script_file.js you can invoke any arbitrary node script with the following signature:

    module.exports = function(data, callback) {
       * Here `data` contains exactly the same values your template will normally receive. e.g.
       * {
       *   commits: [], // the array of commits as described above
       *   range: '<since>..<until>',
       *   dateFnsFormat: function () {},
       *   debug: function() {}, // utility function to log debug messages
       * }
       * Do all the processing you need and when ready call the callback passing the new data structure
        extra: { additional: 'data' },

    The object passed to the callback will be merged with the input data and passed back to the template.

    For an example check samples/post-processing.js

    Usage as a module


    npm install --save-dev git-release-notes


    Inside your script file

    const releaseNotes = require('git-release-notes');
    const OPTIONS = {
      branch: 'master',
    const RANGE = 'v1.0.0..v2.0.0';
    const TEMPLATE = 'markdown';
    releaseNotes(OPTIONS, RANGE, TEMPLATE)
    .then((changelog) => {
      console.log(`Changelog between ${RANGE}\n\n${changelog}`);
    .catch((ex) => {


    The syntax reflects the command line parameters, so options is an object containing path, branch, title and so on. You can refer to the list of options in the command line usage section. You can use either the long or short syntax, the module will use the same defaults as the command line if an option is missing.


    If your post processing script or template throws an exception, the JSON data will be written to the file system in the same folder as the processing script.

    The DEBUG environment variable can also be useful for fault diagnosis:


    export DEBUG=release-notes:*
    git-release-notes ...


    SET DEBUG=release-notes:cli,release-notes:externalscript
    git-release-notes ...


    npm i git-release-notes

    Downloadsweekly downloads








    last publish


    • avatar
    • avatar