README
¶
Make your changelogs ✨
An opinionated GitHub Cli extension for creating changelogs that adhere to the keep a changelog specification.
What is supported?
gh-changelog is the tool for you if:
- You want to closely follow the keep a changelog specification
- You are using tags to mark releases
- You are following a pull-request workflow
Installation and Usage
Before you start make sure that:
- GitHub Cli is installed and authenticated
- You are inside a git repository
- The repository contains commits and has been pushed to GitHub
Install
gh extension install chelnak/gh-changelog
Upgrade
gh extension upgrade chelnak/gh-changelog
Create a changelog
Creating changelog is simple. Once you have installed the extension just run:
gh changelog new
There are also a few useful flags available.
--next-version
Allows you to specify the next version of your project if it has not been tagged.
gh changelog new --next-version v1.2.0
--from-version
Allows you to specify the version to start generating the changelog from.
gh changelog new --from-version v1.0.0
--latest
Creates a changelog that includes only the latest release.
This option can work well with --next-version.
gh changelog new --latest
Console output
You can switch between two spinner and console.
The default (spinner) can be overriden with the --logger flag.
gh changelog new --logger console
Behaviour in CI environments
If the extension detects that it is being ran in a CI environment, it will automatically switch to console logging mode.
This behaviour can be prevented by passing the flag --logger spinner.
View your changelog
You can view your changelog by running:
gh changelog show
The show command renders the changelog in your terminal.
Configuration
Configuration for gh changelog can be found at ~/.config/gh-changelog/config.yaml.
You can also view the configuration by running:
gh changelog config
To print out JSON instead of YAML use --output json flag.
gh changelog config --output json
Some sensible defaults are provided to help you get off to a flying start.
# Labels added here will be ommitted from the changelog
excluded_labels:
- maintenance
# This is the filename of the generated changelog
file_name: CHANGELOG.md
# This is where labels are mapped to the sections in a changelog entry
# The possible sections are restricted to: Added, Changed, Deprecated,
# Removed, Fixed, Security.
sections:
changed:
- backwards-incompatible
added:
- fixed
- enhancement
fixed:
- bug
- bugfix
- documentation
# When set to true, unlabelled entries will not be included in the changelog.
# By default they will be grouped in a section named "Other".
skip_entries_without_label: false
# Adds an unreleased section to the changelog. This will contain any qualifying entries
# that have been added since the last tag.
# Note: The unreleased section is not created when the --next-version flag is used.
show_unreleased: true
# If set to false, the tool will not check remotely for updates
check_for_updates: true
# Determines the logging mode. The default is spinner. The other option is console.
logger: spinner
You can also override any setting using environment variables. When configured from the environment,
properties are prefixed with CHANGELOG.
For example, overriding check_for_updates might look
something like this:
export CHANGELOG_CHECK_FOR_UPDATES=false
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd holds all top-level cobra commands.
|
Package cmd holds all top-level cobra commands. |
|
internal
|
|
|
configuration
Package configuration contains a number of methods that are used to provide configuration to the wider application.
|
Package configuration contains a number of methods that are used to provide configuration to the wider application. |
|
environment
Package environment provides helper methods for working with the current environment.
|
Package environment provides helper methods for working with the current environment. |
|
get
Package get retrieves a local changelog, parses it and returns the result.
|
Package get retrieves a local changelog, parses it and returns the result. |
|
gitclient
Package gitclient is responsible for providing an interface to the local git binary.
|
Package gitclient is responsible for providing an interface to the local git binary. |
|
githubclient
Package githubclient is a wrapper around the githubv4 client.
|
Package githubclient is a wrapper around the githubv4 client. |
|
logging
Package logging provides a simple logging interface for the application.
|
Package logging provides a simple logging interface for the application. |
|
show
Package show is responsible for rendering the contents of a given CHANGELOG.md file and displaying it in the terminal.
|
Package show is responsible for rendering the contents of a given CHANGELOG.md file and displaying it in the terminal. |
|
utils
Package utils contains a number generic of methods that are used throughout the application.
|
Package utils contains a number generic of methods that are used throughout the application. |
|
version
Package version contains a wrapper for parsing semantic versions with the semver library.
|
Package version contains a wrapper for parsing semantic versions with the semver library. |
|
writer
Package writer is responsible for parsing the given changelog struct into a go template and writing it to the given writer.
|
Package writer is responsible for parsing the given changelog struct into a go template and writing it to the given writer. |
|
pkg
|
|
|
builder
Package builder is responsible for building the changelog.
|
Package builder is responsible for building the changelog. |
|
changelog
Package changelog provides the datastructure that is responsible for holding the changelog data.
|
Package changelog provides the datastructure that is responsible for holding the changelog data. |
|
entry
Package entry provides a datastructure for changelog entries.
|
Package entry provides a datastructure for changelog entries. |
|
parser
Package parser provides a simple interface for parsing markdown changelogs.
|
Package parser provides a simple interface for parsing markdown changelogs. |