git-changelog
Generate a changelog from Git history
TLDR
Update existing file or create a new History.md file with the commit messages since the latest Git tag
List commits from the current version
List a range of commits from the tag named 2.1.0 to now
List pretty formatted range of commits between the tag 0.5.0 and the tag 1.0.0
List pretty formatted range of commits between the commit 0b97430 and the tag 1.0.0
Specify CHANGELOG.md as the output file
Replace contents of current changelog file entirely
SYNOPSIS
`git changelog [options]`
PARAMETERS
--help
Display help information.
--version
Show version information.
-o, --output
Specify the output file (default: CHANGELOG.md).
-t, --template
Specify the template file to use for rendering the changelog. Often uses a templating engine like Handlebars or Jinja2.
--tag-prefix
Filter tags by a prefix.
--commit-path
Path to the Git repository (default: current directory).
--next-version
Specify the next version to include in changelog generation.
--remote
The remote from which to fetch tags (default: origin)
--merge
Include merge commits in changelog.
--no-merges
Exclude merge commits in changelog.
DESCRIPTION
The `git-changelog` command (likely a third-party tool or script, not a core Git command) is designed to automate the creation of changelogs based on the commit history within a Git repository. It parses commit messages, identifies features, fixes, and breaking changes, and formats them into a human-readable changelog file (typically `CHANGELOG.md`). The tool often uses conventions within commit messages (e.g., prefixes like `feat:`, `fix:`, `BREAKING CHANGE:`) to categorize changes. It aims to reduce the manual effort involved in maintaining changelogs, ensuring accuracy and consistency. Configuration options allow users to customize the changelog format, the types of commits included, and the overall structure. Common uses include generating changelogs for software releases, documenting API changes, and providing a clear history of project development for users and contributors.
The output is usually formatted in Markdown for easy integration into documentation systems like GitHub or GitLab.
CAVEATS
The effectiveness of `git-changelog` depends heavily on consistent commit message conventions. Without proper commit message formatting, the generated changelog may be inaccurate or incomplete. It is a third-party tool, so installation methods and options can vary significantly. Requires Git to be installed and configured.
COMMIT MESSAGE CONVENTIONS
Most `git-changelog` tools rely on structured commit messages to categorize changes. A common convention is the Angular Commit Message Guidelines, which suggest prefixes like `feat:` (for features), `fix:` (for bug fixes), `docs:` (for documentation), `style:` (for code style changes), `refactor:` (for refactoring), `test:` (for tests), and `chore:` (for maintenance). `BREAKING CHANGE:` is used to indicate a backward-incompatible change.
TEMPLATING
Changelog formats can be extensively customized using templating engines. Commonly used engines include Handlebars, Jinja2, and Mustache. These allow developers to control the structure, style, and content of the generated changelog.
HISTORY
The concept of automating changelog generation emerged as software projects grew in complexity, requiring better tools for tracking and communicating changes. `git-changelog` and similar tools arose as solutions to reduce the manual effort of changelog maintenance. Its usage has become increasingly popular with the rise of CI/CD pipelines and the need for automated release processes.
Many implementations exist, often written in scripting languages like Node.js, Python, or Ruby.