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
override
Override the release notes if exist
debug
Run the command in debugging mode
Write release notes for <new-tag> using data collected until <old-tag>. If only one tag is specified, will use data until the previous tag. To run gren for all the tags, use --tags=all
short: -t |
value: <new-tag>..<old-tag> |
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 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.
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
quiet
Run command without console logs.
config
Specify a custom config filename
short: -c |
value: <string> |
Release
draft
Set the release notes as a draft.
prerelease
Set the release as a prerelease.
Changelog
generate
Generate the changelog with gren rather than using the repo releases
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
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();
}
}
}