Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
181 lines (125 sloc) 6.17 KB



Make sure you have npx installed (npx is shipped by default since npm 5.2.0)

Run the following command at the root of your project and answer questions.

with npx:

npx gitmoji-changelog

with npm:

npm install -g gitmoji-changelog

cd my-project

Available commands

gitmoji-changelog [release]
gitmoji-changelog init
gitmoji-changelog update [release]

The first command listed above is the idiomatic usage of gitmoji-changelog (read the How it works for more information).

release argument is by default valued to from-package. It will retrieve the version from the selected preset (read Presets for more information). You can overwrite it with the tag you want to generate in the changelog.


option description default value
--version display version
--format changelog format (markdown, json) markdown
--preset define preset mode node
--output output file path ./ or ./CHANGELOG.json
--group-similar-commits [⚗️,- beta] try to group similar commits false
--author add the author in changelog lines false
--interactive -i select commits manually false
--help display help


Here an example output:

How it works

Behavior doesn't exist:

The CLI will generate all previous changelog based on semver tags of your repo. exists:

All previous semvers tags remain unchanged. The CLI will add each tag since the last semver tag found in the file.

By default when you generate your changelog with gitmoji-changelog, the following mapping is used to group commits: groupMapping.js


Here the recommended workflow to generate your changelog file using gitmoji-changelog:

Important: Before generating, be sure to have all tags locally (e.g. git fetch origin)

  1. Make changes and commit: git commit -m ":sparkles: my awesome feature"
  2. Bump version (ex: 1.0.0) in package.json using semver convention
  3. Run gitmoji-changelog, then the file is created or updated with all changes
  4. You can freely edit the new release in the changelog file, it will not be overwrite with the next generation
  5. Commit package.json and file
  6. Tag your release: git tag -a v1.0.0 -m "v1.0.0" (or create a Github release)
  7. Push to the remote git push

This workflow is related to the node preset but can be adapted to your own technology.


gitmoji-changelog use presets to get project meta data useful for its smooth operation. Here is the list of available presets:

  • node (default preset)

You didn't the preset you need in the list? Consider adding it. Presets are stored in a presets folder in the cli package.

Add a preset

A preset need to export a function. When called this function must return three mandatory information about the project in which the cli has been called. The name of the project, a short description of it and its current version.

Let's dissect the node preset to see how it works. First of all the module must export a function. In case something went wrong return null. The cli will tell the user a problem occured.

module.exports = () => {
  return null

There is a package called read-pkg-up to get the first package.json in the parent folder structure. It returns its content as a JavaScript object. If we can't find a package.json or it is empty we return null.

const readPkgUp = require('read-pkg-up')

module.exports = async () => {
  try {
    const packageInfo = await readPkgUp()

    if (!packageInfo.pkg) {
      throw Error('Empty package.json')
  } catch (e) {
    return null

If everything went fine we return the three mandatory information (name, description, version).

const readPkgUp = require('read-pkg-up')

module.exports = async () => {
  try {
    const packageInfo = await readPkgUp()

    if (!packageInfo.pkg) {
      throw Error('Empty package.json')

    return {
      description: packageInfo.pkg.description,
      version: packageInfo.pkg.version,
  } catch (e) {
    return null

That's it. Feel free to open an issue to ask for a new preset or open a pull request to add one.

🐳 Using Docker image

Launch gitmoji-changelog using the official Docker image:

docker container run -it -v $(pwd):/app --rm yvonnick/gitmoji-changelog:latest

/app is the directory where gitmoji-changelog expect your project in the container.

You can also build the image locally and use it directly:

# build the image:
docker image build -t yvonnick/gitmoji-changelog:dev .
# use it:
docker container run -it -v $(pwd):/app --rm yvonnick/gitmoji-changelog:dev

Supported tags and respective Dockerfile links

🐥 Canary version

If you want to test the incoming release of gitmoji-changelog, you can use or install the canary version. Be aware, it's a development in progress version, feel free to report bug or give feedback.

with npx:

npx gitmoji-changelog@canary --version

with npm:

npm install -g gitmoji-changelog@canary
You can’t perform that action at this time.