gitmoji-changelog

🚀 Usage

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. gitmoji-changelog uses a preset system to handle different type of project. The preset used by default is the Node.js one that look for project's information in the package.json file.

with npx:

npx gitmoji-changelog

with npm:

npm install -g gitmoji-changelog

cd my-project
gitmoji-changelog

It exists a generic preset that works for every kind of project. It looks for information in a .gitmoji-changelogrc file at the root of your project. This file must contain three mandatory properties: name, description and version.

.gitmoji-changelogrc:

{
  "project": {
    "name": "gitmoji-changelog",
    "description": "A changelog generator for gitmoji 😜",
    "version": "2.0.1"
  }
}

You can change the preset used by gitmoji-changelog with the preset option.

npx gitmoji-changelog --preset generic

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.

Options

option	description	default value
--version	display version
--format	changelog format (markdown, json)	markdown
--preset	define preset mode	node
--output	output file path	./CHANGELOG.md 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

Example

Here an example output: CHANGELOG.md

📚 How it works

Behavior

CHANGELOG.md doesn't exist:

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

CHANGELOG.md exists:

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

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

Workflow

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)

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

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

⚙️ Presets

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

node (default preset)
generic
maven
cargo
helm

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

Existing presets

Node

The node preset looks for a package.json file.

{
  "name": "project-name",
  "version": "0.0.1",
  "description": "Some description",
}

Generic

The generic preset looks a gitmoji-changelogrc file.

{
  "project": {
    "name": "yvonnickfrin.dev",
    "description": "My blog",
    "version": "1.1.0"
  }
}

It must contain all mandatory properties in a project property. The gitmoji-changelogrc file can contain other configuration properties like a custom commit categorization.

Maven

The maven preset looks for 4 properties in you pom.xml:

groupid
artifactid
version
description

Cargo

The cargo preset looks for 3 properties in your Cargo.toml:

name
version
description

Helm

The helm preset looks for 3 properties in your Chart.yaml:

name
version
description

Python

The python preset looks for 3 properties in your pyproject.toml:

name
version
description

(The value taken is the first one found in your pyproject.toml that matches the expected key name given above.)

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 occurred.

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.packageJson) {
      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.packageJson) {
      throw Error('Empty package.json')
    }

    return {
      name: packageInfo.packageJson.name,
      description: packageInfo.packageJson.description,
      version: packageInfo.packageJson.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.

All preset needs at least 3 pieces of informations to work:

A project name
A current version
A description

They have their own way to get these.

🐳 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

yvonnick/gitmoji-changelog:latest

🐥 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 any bugs plus give feedback.

with npx:

npx gitmoji-changelog@canary --version

with npm:

npm install -g gitmoji-changelog@canary