Generate release notes from git commit history either commit range or tag range.

Overview

Would you like to support me?

Release Notes

Generate release notes from git commit history either commit range or tag range.

App Store Template Changelog Template

Installation

It's preferable to install it globally through npm

npm install -g release-notes-cli

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

Usage

you can call this cli by release-notes-cli / release-notes / rn The basic usage from the command line is

release-notes <since>..<until> <template> --copy

# like this
release-notes v1.4.0..v1.5.2 appstore --copy

Where

  • <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
  • --copy will copy the log into clipboard

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

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

Node's release notes

App Store Template

Note: for appstore release notes, commits title should be have Commitlint header format like

chore: run tests on travis ci
fix(server): send cors headers
feat(blog): add comment section

Changelog Template

You need to get GitHub personal access token from github for setting committer username like this: @nomi9995

Since release-notes-cli interacts with the GitHub API you may run into rate limiting issues which can be resolved by supplying a "personal access token":

export GITHUB_AUTH="..."

You'll need a personal access token for the GitHub API with the repo scope for private repositories or just public_repo scope for public repositories.

Note: if you dont set GITHUB_AUTH then it will not print committer username for all commits, it will print email instead of github username

Custom template

The second parameter of release-notes-cli 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)
  • tag tag (%D)
  • 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

Options

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
  • mg or merge-commits List only merge commits, git log command is executed with the --merges flag instead of --no-merges
  • c or copy uses for copy the log
  • 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

release-notes-cli -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.

release-notes-cli -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
   */
  callback({
    commits: data.commits.map(doSomething),
    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

Installation

npm install --save-dev release-notes-cli

Usage

Inside your script file

const releaseNotes = require("release-notes-cli");

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 => {
    console.error(ex);
    process.exit(1);
  });

Options

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.

However, there is a little difference between module usage and CLI of the script parameter. When used as CLI, it receives a path link to a JS module file, but used as a module, it receives a function:

releaseNotes(
  {
    branch: "master",
    script: (data, callback) => {
      callback({
        foo: "bar",
      });
    },
  },
  RANGE,
  TEMPLATE
);

Typescript

release-notes-cli includes Typescript definitions.

import * as releaseNotes from "release-notes-cli";
releaseNotes({ path }, range, TEMPLATE);

Debug

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:

Linux

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

Windows

SET DEBUG=release-notes:cli,release-notes:externalscript
release-notes-cli ...
You might also like...

Easily publish notes to the web This plugin integrates with obsius.site to publish markdown notes on the web.

Easily publish notes to the web  This plugin integrates with obsius.site to publish markdown notes on the web.

Obsius Publish Easily publish notes to the web This plugin integrates with obsius.site to publish markdown notes on the web. Limitations The type of c

Dec 20, 2022

An Obsidian plugin for automatically creating notes when linking to non-existing notes

Note Auto Creator for Obsidian Automatically create notes when links are created to them. How to use After enabling the plugin in the settings menu, y

Dec 14, 2022

A service for sharing encrypted Markdown notes from Obsidian. Notes are end-to-end-encrypted and are only stored temporarily.

A service for sharing encrypted Markdown notes from Obsidian. Notes are end-to-end-encrypted and are only stored temporarily.

📝 Noteshare.space Noteshare.space is a service for sharing encrypted Markdown notes from Obsidian. Notes are end-to-end-encrypted and are only stored

Dec 26, 2022

It's an AI Tag (Prompt) generator for magic drawer! We have many tags and support to generate prompts easily!

It's an AI Tag (Prompt) generator for magic drawer! We have many tags and support to generate prompts easily!

魔导绪论 AI 魔咒生成器, 使用由 B 站 UP 主 十二今天也很可爱 提供的 4 万个 tag 并提供中文检索,并提供了魔咒社区方便魔法师们直接复制生成。永远免费,永无广告,无商业。 v2 版本更新内容 使用 Netlify 的云函数提供更为快速的社区数据操作!(暂时不知道花费多少) 查看自己的

Jan 1, 2023

Solidity starter combining foundry and hardhat because both are great and I can't live without either...

Combination Pizza Hut & Taco Bell Foundry && HardHat starter template. Motivation I like them both. With this set-up we get: Unit tests written in sol

Aug 23, 2022

Package fetcher is a bot messenger which gather npm packages by uploading either a json file (package.json) or a picture representing package.json. To continue...

package-fetcher Ce projet contient un boilerplate pour un bot messenger et l'executable Windows ngrok qui va permettre de créer un tunnel https pour c

Mar 29, 2022

HackFest is a 36-hour long hackathon wherein you have to put on your hacker hats and build anything that falls in either or both the domain of full-stack web development

HackFest is a 36-hour long hackathon wherein you have to put on your hacker hats and build anything that falls in either or both the domain of full-stack web development

HackFest is a 36-hour long hackathon wherein you have to put on your hacker hats and build anything that falls in either or both the domain of full-stack web development (the stack we learn in full-stack web developer roadmap on codedamn).

Jun 6, 2022

This is an app that will service the ASD community to help them communicate what they want. The individual can be either verbal or non-verbal.

This is a Next.js project bootstrapped with create-next-app. Getting Started First, run the development server: npm run dev # or yarn dev Open http://

Jun 28, 2022
Comments
  • changelog template header formatting

    changelog template header formatting

    Hey there,

    I've been searching for simple changelog generator and found this to be quite ideal. I am wondering if you were intentionally formatting the changelog template to not include spaces between the hashes and the title?

    At first I was expecting something akin to this

    Fix

    • update thing
    • fix that

    But it is formatted as

    ###Fix

    • update thing
    • fix that

    If intentional, that's fine, I'll work off my own fork. Else I'll send over a PR. Just let me know. Thanks!

    opened by rennerom 1
Releases(v0.0.3)
Owner
Numan
Software engineer. JavaScript | React Native | React | NodeJS | Algorithms
Numan
Easily open daily notes and periodic notes in new pane; customize periodic notes background; quick append new line to daily notes.

Obsidian daily notes opener This plugin adds a command for opening daily notes in a new pane (so that a keyboard shortcut could be used!) and gives ex

Xiao Meng 16 Dec 26, 2022
An interactive git visualization and tutorial. Aspiring students of git can use this app to educate and challenge themselves towards mastery of git!

LearnGitBranching LearnGitBranching is a git repository visualizer, sandbox, and a series of educational tutorials and challenges. Its primary purpose

Peter Cottle 26.4k Jan 3, 2023
History.js gracefully supports the HTML5 History/State APIs (pushState, replaceState, onPopState) in all browsers. Including continued support for data, titles, replaceState

History.js gracefully supports the HTML5 History/State APIs (pushState, replaceState, onPopState) in all browsers. Including continued support for data, titles, replaceState. Supports jQuery, MooTools and Prototype.

Browser State 10.8k Dec 26, 2022
GitHub Action to create a release PR using cargo-release

Action: (Cargo) release-pr A GitHub Action for creating "Release PRs" for Cargo projects. Purpose This action uses cargo-release to perform a release

null 18 Nov 16, 2022
Visualize the Directed Acyclic Graph that Git creates to connect Commit, Tree and Blob objects internally.

Git Graph Visualize the Directed Acyclic Graph that Git creates to connect Commit, Tree and Blob objects. Hosted at HarshKapadia2.github.io/git-graph.

Harsh Kapadia 15 Aug 21, 2022
Get a diff view of your Obsidian Sync, File Recovery and Git version history

Version History Diff (for Sync and File Recovery Core plugins and Git) Note This plugin uses private APIs, so it may break at any time. Use at your ow

null 39 Dec 26, 2022
This is the frontend/UI of git history analyzing tool Who Touched What

Who Touched What? This a git analysis tool for you to see how many edits were done to each file and by whom. A quick and straight forward way to track

Haoran Zhang 4 Aug 17, 2022
A lightweight (~2kB) library to create range sliders that can capture a value or a range of values with one or two drag handles

range-slider-input A lightweight (~2kB) library to create range sliders that can capture a value or a range of values with one or two drag handles. Ex

Utkarsh Verma 42 Dec 24, 2022
📝 You Can Create Your Own Short Notes With The Help of Sticky-Notes Website.

Hi ?? , I'm Sneh Agrawal A passionate Web developer from India ?? I’m currently working on Chatting Website Chit-Chat ?? How to reach me on My Gmail A

Sneh (Smilyboyy) 1 Feb 23, 2022
A Zotero add-on that scans your Markdown reading notes, tags the associated Zotero items, and lets you open notes for the Zotero items in Obsidian.

Zotero Obsidian Citations Adds colored tags to Zotero items that have associated Markdown notes stored in an external folder. Open an associated Markd

Dae 210 Jan 4, 2023