{"id":17675323,"url":"https://github.com/numandev1/release-notes-cli","last_synced_at":"2025-05-12T22:15:15.912Z","repository":{"id":57962340,"uuid":"529221983","full_name":"numandev1/release-notes-cli","owner":"numandev1","description":"Generate release notes from git commit history either commit range or tag range.","archived":false,"fork":false,"pushed_at":"2022-10-07T05:57:06.000Z","size":347,"stargazers_count":10,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-12T22:14:57.643Z","etag":null,"topics":["appstore","changelog","changelog-generator","commit","commitlint","git","github-changelog","github-changelog-generator","markdown","notes","playstore","release","release-notes","release-notes-generator","tag"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/numandev1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-26T10:58:58.000Z","updated_at":"2025-04-29T13:49:49.000Z","dependencies_parsed_at":"2022-08-29T17:51:05.418Z","dependency_job_id":null,"html_url":"https://github.com/numandev1/release-notes-cli","commit_stats":null,"previous_names":["nomi9995/release-notes-cli"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numandev1%2Frelease-notes-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numandev1%2Frelease-notes-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numandev1%2Frelease-notes-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numandev1%2Frelease-notes-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numandev1","download_url":"https://codeload.github.com/numandev1/release-notes-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253831001,"owners_count":21971007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appstore","changelog","changelog-generator","commit","commitlint","git","github-changelog","github-changelog-generator","markdown","notes","playstore","release","release-notes","release-notes-generator","tag"],"created_at":"2024-10-24T07:10:45.866Z","updated_at":"2025-05-12T22:15:15.889Z","avatar_url":"https://github.com/numandev1.png","language":"TypeScript","readme":"### Would you like to support me?\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://github.com/numandev1?tab=followers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/followers/numandev1?label=Follow%20%40numandev1\u0026style=social\" height=\"36\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://www.youtube.com/channel/UCYCUspfN7ZevgCj3W5GlFAw\"\u003e\u003cimg src=\"https://img.shields.io/youtube/channel/subscribers/UCYCUspfN7ZevgCj3W5GlFAw?style=social\" height=\"36\" /\u003e\u003ca/\u003e\n\u003c/br\u003e\n\u003ca href=\"https://www.buymeacoffee.com/numan.dev\" target=\"_blank\"\u003e\u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: auto !important;width: auto !important;\" \u003e\u003c/a\u003e\n\u003c/div\u003e\n\n## Release Notes\n\nGenerate release notes from git commit history either **commit range** or **tag range**.\n\n| ![](media/appstore.png) | ![](media/changeLog.png) |\n| :---------------------: | :----------------------: |\n|   App Store Template    |    Changelog Template    |\n\n### Installation\n\nIt's preferable to install it globally through [`npm`](https://www.npmjs.com/package/release-notes-cli)\n\n    npm install -g release-notes-cli\n\nIt's also possible to use `release-notes-cli` as a node module. Check the usage on [usage as a module](#Usage_as_a_module)\n\n### Usage\n\nyou can call this cli by **release-notes-cli** / **release-notes** / **rn**\nThe basic usage from the command line is\n\n```\nrelease-notes \u003csince\u003e..\u003cuntil\u003e \u003ctemplate\u003e --copy\n\n# like this\nrelease-notes v1.4.0..v1.5.2 appstore --copy\n```\n\nWhere\n\n- `\u003csince\u003e..\u003cuntil\u003e` specifies the range of commits as in `git log`, see [gitrevisions(7)](http://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html)\n- `\u003ctemplate\u003e` is an [ejs](https://github.com/visionmedia/ejs) template file used to generate the release notes\n- `--copy` will copy the log into clipboard\n\nThree sample templates are included as a reference in the `templates` folder\n\n- `appstore` [(sample)](https://github.com/numandev1/release-notes-cli/blob/master/samples/output-appstore.txt)\n- `changelog` [(sample)](https://github.com/numandev1/release-notes-cli/blob/master/samples/output-changelog.md)\n- `markdown` [(sample)](https://github.com/numandev1/release-notes-cli/blob/master/samples/output-markdown.md)\n- `html` [(sample)](http://htmlpreview.github.io/?https://github.com/numandev1/release-notes-cli/blob/master/samples/output-html.html)\n- `html-bootstrap` [(sample)](http://htmlpreview.github.io/?https://github.com/numandev1/release-notes-cli/blob/master/samples/output-html-bootstrap.html)\n\nThis for example is the release notes generated for `joyent/node` by running\n\n    release-notes-cli v0.9.8..v0.9.9 html \u003e changelog.html\n\n[\u003cimg src=\"https://github.com/numandev1/release-notes-cli/raw/master/samples/node_thumb.png\" alt=\"Node's release notes\"\u003e](https://github.com/numandev1/release-notes-cli/raw/master/samples/node.png)\n\n#### App Store Template\n\n**Note:** for appstore release notes, commits title should be have [Commitlint header](https://github.com/conventional-changelog/commitlint#what-is-commitlint) format like\n\n```\nchore: run tests on travis ci\n```\n\n```\nfix(server): send cors headers\n```\n\n```\nfeat(blog): add comment section\n```\n\n#### Changelog Template\n\nYou need to get **GitHub personal** access token from github for setting committer username like this: [@numandev1](https://github.com/numandev1)\n\nSince `release-notes-cli` interacts with the GitHub API you may run into rate\nlimiting issues which can be resolved by supplying a \"personal access token\":\n\n```\nexport GITHUB_AUTH=\"...\"\n```\n\nYou'll need a [personal access token](https://github.com/settings/tokens)\nfor the GitHub API with the `repo` scope for private repositories or just\n`public_repo` scope for public repositories.\n\n**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\n\n#### Custom template\n\nThe second parameter of `release-notes-cli` can be any path to a valid ejs template files.\n\n##### Template Variables\n\nSeveral template variables are made available to the script running inside the template.\n\n`commits` is an array of commits, each containing\n\n- `sha1` commit hash (%H)\n- `authorName` author name (%an)\n- `authorEmail` author email (%ae)\n- `authorDate` author date (%aD)\n- `committerName` committer name (%cn)\n- `committerEmail` committer email (%ce)\n- `committerDate` committer date (%cD)\n- `title` subject (%s)\n- `tag` tag (%D)\n- `messageLines` array of body lines (%b)\n\n`dateFnsFormat` is the date-fns [format](https://date-fns.org/docs/format) function. See the [html-bootstrap](https://github.com/numandev1/release-notes-cli/blob/master/templates/html-bootstrap.ejs) for sample usage.\n\n`range` is the commits range as passed to the command line\n\n### Options\n\nMore advanced options are\n\n- `p` or `path` Git project path, defaults to the current working path\n- `b` or `branch` Git branch, defaults to `master`\n- `t` or `title` Regular expression to parse the commit title (see next chapter)\n- `i` or `ignore-case` Ignore case flag for title's regular expression. `/.*/` becomes `/.*/i`\n- `m` or `meaning` Meaning of capturing block in title's regular expression\n- `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](https://github.com/numandev1/release-notes-cli/blob/master/options.json)\n- `s` or `script` External script for post-processing commits\n- `mg` or `merge-commits` List only merge commits, `git log` command is executed with the `--merges` flag instead of `--no-merges`\n- `c` or `copy` uses for copy the log\n- `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`).\n\n#### Title Parsing\n\nSome projects might have special naming conventions for the commit title.\n\nThe options `t` and `m` allow to specify this logic and extract additional information from the title.\n\nFor instance, [Aria Templates](https://github.com/numandev1/numandev1) has the following convention\n\n    fix #123 Title of a bug fix commit\n    feat #234 Title of a cool new feature\n\nIn this case using\n\n```\nrelease-notes-cli -t \"^([a-z]+) #(\\d+) (.*)$\" -m type -m issue -m title v1.3.6..HEAD html\n```\n\ngenerates the additional fields on the commit object\n\n- `type` first capturing block\n- `issue` second capturing block\n- `title` third capturing block (redefines the title)\n\nAnother project using similar conventions is [AngularJs](https://github.com/angular/angular.js), [commit message conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#).\n\n```\nrelease-notes-cli -t \"^(\\w*)(?:\\(([\\w\\$\\.]*)\\))?\\: (.*)$\" -m type -m scope -m title v1.1.2..v1.1.3 markdown\n```\n\n#### Post Processing\n\nThe 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...)\n\nUsing `-s script_file.js` you can invoke any arbitrary node script with the following signature:\n\n```js\nmodule.exports = function (data, callback) {\n  /**\n   * Here `data` contains exactly the same values your template will normally receive. e.g.\n   *\n   * {\n   *   commits: [], // the array of commits as described above\n   *   range: '\u003csince\u003e..\u003cuntil\u003e',\n   *   dateFnsFormat: function () {},\n   *   debug: function() {}, // utility function to log debug messages\n   * }\n   *\n   * Do all the processing you need and when ready call the callback passing the new data structure\n   */\n  callback({\n    commits: data.commits.map(doSomething),\n    extra: { additional: \"data\" },\n  });\n  //\n};\n```\n\nThe object passed to the callback will be merged with the input data and passed back to the template.\n\nFor an example check `samples/post-processing.js`\n\n### Usage as a module\n\n#### Installation\n\nnpm install --save-dev release-notes-cli\n\n#### Usage\n\nInside your script file\n\n```js\nconst releaseNotes = require(\"release-notes-cli\");\n\nconst OPTIONS = {\n  branch: \"master\",\n};\nconst RANGE = \"v1.0.0..v2.0.0\";\nconst TEMPLATE = \"markdown\";\n\nreleaseNotes(OPTIONS, RANGE, TEMPLATE)\n  .then(changelog =\u003e {\n    console.log(`Changelog between ${RANGE}\\n\\n${changelog}`);\n  })\n  .catch(ex =\u003e {\n    console.error(ex);\n    process.exit(1);\n  });\n```\n\n#### Options\n\nThe 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.\n\nHowever, 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:\n\n```js\nreleaseNotes(\n  {\n    branch: \"master\",\n    script: (data, callback) =\u003e {\n      callback({\n        foo: \"bar\",\n      });\n    },\n  },\n  RANGE,\n  TEMPLATE\n);\n```\n\n### Typescript\n\n`release-notes-cli` includes [Typescript](http://www.typescriptlang.org/) definitions.\n\n```ts\nimport * as releaseNotes from \"release-notes-cli\";\nreleaseNotes({ path }, range, TEMPLATE);\n```\n\n### Debug\n\nIf 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.\n\nThe DEBUG environment variable can also be useful for fault diagnosis:\n\n#### Linux\n\n    export DEBUG=release-notes:*\n    release-notes-cli ...\n\n#### Windows\n\n    SET DEBUG=release-notes:cli,release-notes:externalscript\n    release-notes-cli ...\n","funding_links":["https://www.buymeacoffee.com/numan.dev"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumandev1%2Frelease-notes-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumandev1%2Frelease-notes-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumandev1%2Frelease-notes-cli/lists"}