ghif, an issues formatter for Github's CLI gh issue list

Maintaining a project's changelog shouldn't be a chore yet it often ends up being one. Having to repetitively cut and paste from our Github issues into our project's changelog and then having to format everything in a consistent manner can be a significant task in its own right. That's where ghif steps in to radically reduce the effort of changelog maintenance.

ghif is a simple command line utility that takes the issues output from Github's gh issue list --json "number,title,labels" command, formats them according to any additional ghif formatting options that you provide (please see below), and then sends the formatted output to stdout.

⚠️ ghif expects gh issue list to return JSON and for issue objects to contain the number, title and labels fields and will fail to run otherwise. Therefor the minimum gh issue list command required is the following:

> gh issue list --json "number,title,labels"

You can, of course, include any of the gh issue list filters that support your project's use case, such as status (-s), repository (--repo), milestone (-m), etc.

Installation

⚠️ ghif requires the Github CLI

> npm i -g 4awpawz/ghif

Supported output formats and examples

Plain text

> gh issue list --json "number,title,labels" | ghif --text --header="v1.3.0"

Example: a list of issues with a heading

v1.3.0

#98: Unresolved token reporting drops the last closing brace for include tokens. [bug, revision]
#97: Log warning to the console if user project does not have a 404.html document. [feature, revision]
#96: Though template front matter is documented as a requirement, this is not enforced in the codebase. [wontfix, revision]
#95: Update to Node v18.18.0 LTS and address all related issues. [revision]
#94: Include cache bust metric when release is called without the --verbose option and is called with the --cache-bust option. [revision]
#93: Refactor the cli help to accommodate multiple command options. [feature]
#92: Provide CLI --verbose logging option. [feature, revision]
#91: Update Buster dependency to v1.1.0. [revision]

Markdown

As a list:

> gh issue list --json "number,title,labels" | ghif --markdown-list --header="## v1.3.0"

Example: a list of issues with a h2 header

## v1.3.0

#98: Unresolved token reporting drops the last closing brace for include tokens. [bug, revision]

#97: Log warning to the console if user project does not have a 404.html document. [feature, revision]

#96: Though template front matter is documented as a requirement, this is not enforced in the codebase. [wontfix, revision]

#95: Update to Node v18.18.0 LTS and address all related issues. [revision]

#94: Include cache bust metric when release is called without the --verbose option and is called with the --cache-bust option. [revision]

#93: Refactor the cli help to accommodate multiple command options. [feature]

#92: Provide CLI --verbose logging option. [feature, revision]

#91: Update Buster dependency to v1.1.0. [revision]

As an unordered list:

> gh issue list --json "number,title,labels" | ghif --markdown-unordered-list

Example: an unordered list of issues

- #98: Unresolved token reporting drops the last closing brace for include tokens. [bug, revision]
- #97: Log warning to the console if user project does not have a 404.html document. [feature, revision]
- #96: Though template front matter is documented as a requirement, this is not enforced in the codebase. [wontfix, revision]
- #95: Update to Node v18.18.0 LTS and address all related issues. [revision]
- #94: Include cache bust metric when release is called without the --verbose option and is called with the --cache-bust option. [revision]
- #93: Refactor the cli help to accommodate multiple command options. [feature]
- #92: Provide CLI --verbose logging option. [feature, revision]
- #91: Update Buster dependency to v1.1.0. [revision]

As an ordered list:

> gh issue list --json "number,title,labels" | ghif --markdown-ordered-list

Example: an ordered list of issues

1. #98: Unresolved token reporting drops the last closing brace for include tokens. [bug, revision]
1. #97: Log warning to the console if user project does not have a 404.html document. [feature, revision]
1. #96: Though template front matter is documented as a requirement, this is not enforced in the codebase. [wontfix, revision]
1. #95: Update to Node v18.18.0 LTS and address all related issues. [revision]
1. #94: Include cache bust metric when release is called without the --verbose option and is called with the --cache-bust option. [revision]
1. #93: Refactor the cli help to accommodate multiple command options. [feature]
1. #92: Provide CLI --verbose logging option. [feature, revision]
1. #91: Update Buster dependency to v1.1.0. [revision]

Usage examples

Output text to the terminal

> gh issue list -s closed -m "v1.3.0" --json "number,title,labels" --repo 4awpawz/fusion.ssg | ghif --text

Pipe text output to a text file

> gh issue list -s closed -m "v1.3.0" --json "number,title,labels" --repo 4awpawz/fusion.ssg | ghif --text > issues.txt

Pipe markdown output to a markdown file

> gh issue list -s closed -m "v1.3.0" --json "number,title,labels" --repo 4awpawz/fusion.ssg | ghif --markdown-unordered-list --blank-line-between-issues > issues.md

Formatting options

• --colored-labels: colorize labels, ignored if output format is not markdown
• --blank-line-between-issues: output a blank line between issues
• --text: output a list of issues as plain text
• --markdown-list: output a list of issues in markdown
• --markdown-unordered-list: output an unordered list of issues in markdown
• --markdown-ordered-list: output an ordered list of issues in markdown
• --header: prepend a header (e.g. V1.0.3) to the output, supports markdown headers and plain text headings

Show some love ❤️

If using ghif provides you value then please click on the repository's Star button.

If you would like to be notified when there are changes then please click on the repository's Watch button.