Options

See all the options for gren.

The global options are shared between the gren release and gren changelog commands, as gren changelog --generate can create release notes and a CHANGELOG.md file, instead of getting all the releases from project release notes.

To use an option in your terminal, prefix the name with -- (e.g. gren release --data-source=commits)

To pass it to the Gren class or in the configuration file they need to be camelCase (e.g. "dataSource": "commits").

Global

username

The username of the repo e.g. github-tools

short: -u value: <repo owner>

repo

The repository name e.g. github-release-notes

short: -r value: <repository name>

token

The token generated with repo access

short: -T value: <github token>

api-url

Override the GitHub API URL, allows gren to connect to a private GHE installation

short: -a value: <url>

override

Override the release notes if exist

short: -o

debug

Run the command in debugging mode

short: -B

limit

Just produce release notes for the <number> last releases.

short: -l value: <number>

data-source

The informations you want to use to build release notes.

short: -D value: <issues|commits|milestones|prs|prs-with-issues> default: issues

include-messages

Filter the messages added to the release notes. Only used when --data-source used is commits 

short: -N value: <merge|commits|all> default: commits

ignore-tags-with

Ignore tags that contain one of the specified strings.

short: -i value: <string1>,<string2>

ignore-commits-with

Ignore commits that contain one of the specified strings.

short: -C value: <string1>,<string2>

prefix

Add a prefix to the tag version. e.g. 'v'

short: -p value: <name prefix>

group-by

Group the issues using the labels as group headings. You can set custom headings for groups of labels from a configuration file.

short: -g value: <label>

ignore-labels

Ignore the specified labels.

short: -L value: <label1>,<label2>

ignore-issues-with

Ignore issues that contains one of the specified labels.

short: -I value: <label1>,<label2>

milestone-match

The title that the script needs to match to link the release to the milestone. e.g. v will match v0.1.0 

short: -M value: <prefix> default: Release {{tag_name}}

only-milestones

Add to the release bodies only the issues that have a milestone

short: -m

quiet

Run command without console logs.

short: -q

config

Specify a custom config filename

short: -c value: <string>

Release

draft

Set the release notes as a draft.

short: -d

prerelease

Set the release as a prerelease.

short: -P

Changelog

generate

Generate the changelog with gren rather than using the repo releases

short: -G

changelog-filename

The name of the changelog file.

short: -f value: <filename.md> default: CHANGELOG.md

Configuration file

You can create a configuration file where the task will be ran, where to specify your options. The options are the same on specified above but in camelCase e.g:

{
    "dataSource": "commits",
    "ignoreIssuesWith": [
        "wontfix",
        "duplicate"
    ],
    "template": {
        ...
    }
}

If you need help to create the configuration file, you can run the following command and follow the instructions

gren init

Group By

Via the configuration file you can have more complex grouping, using labels in a more creative way. gren will use the keys of the given Object as titles and group all the issues that contain one or more of the labels in the value Array. A bit complex to understand? Just see the example:

{
    "groupBy": {
        "Enhancements:": ["enhancement", "internal"],
        "Bug Fixes:": ["bug"]
    }
}

In this case gren will group all the issues labeled with enhancement and internal under the title “Enhancements: “ and all the ones with bug under the title “Bug Fixes: “.

Issues with multiple labels

In case an issue has more than a specified label (e.g. both “enhancement” and “bug”), gren will prioritise based on the order (i.e. the issue will only appear in the “Enhancements” group).

Extensions

The accepted file extensions are the following:

.grenrc
.grenrc.json
.grenrc.yml
.grenrc.yaml
.grenrc.js

Templates

You can configure the output of gren using templates. Set your own configuration inside the config file, which will be merged with the defaults, shown below:

module.exports = {
    "template": {
        commit: ({ message, url, author, name }) => `- [${message}](${url}) - ${author ? `@${author}` : name}`,
        issue: "- {{labels}} {{name}} [{{text}}]({{url}})",
        label: "[**{{label}}**]",
        noLabel: "closed",
        group: "\n#### {{heading}}\n",
        changelogTitle: "# Changelog\n\n",
        release: "## {{release}} ({{date}})\n{{body}}",
        releaseSeparator: "\n---\n\n"
    }
}

If you’re using a .grenrc.js config file, you can use JavaScript to manipulate the templates using functions as values. The function will have an object as first parameter, containing all the values to display. i.e.

/* .grenrc.js */

module.exports = {
    template: {
        issue: function (placeholders) {
            return '- ' + placeholders.labels + ' | ' + placeholders.name.toLowerCase();
        }
    }
}

🤖 gren