orhun/git-cliff
Git Cliff
This project is a version control documentation tool designed to automate the generation of release notes and changelogs. It functions as a pipeline-based engine that parses repository history, categorizes commits, and transforms them into structured documentation. By leveraging conventional commit patterns or custom regular expressions, it provides a consistent method for tracking project evolution and managing semantic versioning.
What distinguishes this tool is its highly flexible template-driven architecture, which allows for deep customization of output formatting, grouping, and sorting. It supports complex project structures, including monorepos and nested submodules, by enabling path-based scoping and multi-repository aggregation. Users can enrich their documentation with external metadata from remote hosting services or maintain strict control over the process by operating in a fully offline, local-first mode.
The system offers extensive configuration options to tailor the documentation lifecycle, including commit preprocessing, filtering, and environment-specific settings. It integrates into continuous integration pipelines to automate updates, supports the export of documentation to formats like PDF, and provides diagnostic tools to monitor performance during the generation process.
Features
- Release Changelog Generators - Automatically generates structured release notes by parsing commit history and repository metadata.
- Repository Documentation Generators - Extracts and transforms repository history into professional documentation formats like Markdown or PDF.
- Release Automation - Automates semantic version calculation and release documentation generation within CI pipelines.
- Data-Driven Templates - Injects processed commit metadata into customizable text templates to generate structured documentation.
- Commit Standards - Analyzes commit messages using conventional patterns to categorize changes for project history.
- Monorepo Changelog Generators - Generates isolated or unified changelogs by filtering commit history across specific subdirectories and submodules.
- Developer Tools - Customizable changelog generator.
- Entwicklungstools - Highly customizable changelog generator for conventional commits.
- Output Template Engines - Provides a flexible template engine with conditional logic and variable injection for formatting documentation output.
- Version Control and Repository Tools - Combines commit histories from multiple distinct repositories into a single unified document to track changes across an entire project ecosystem.
- Semantic Versioning Systems - Calculates and suggests next version numbers based on unreleased changes to ensure consistent release numbering.
- Pipeline Architectures - Organizes commit analysis and documentation generation into a sequential, decoupled pipeline of transformation steps.
- CI/CD Integrations - Executes documentation creation within continuous integration pipelines to automate updates.
- Changelog Metadata Retrievers - Retrieves commit and release details from hosted version control services to enrich automated changelogs with external data.
- Template-Driven Reporters - Transforms raw commit data into highly formatted documents using flexible templates.
- Remote Service Clients - Extracts pull request details from hosting services to enrich documentation with external context.
- Filters - Generates documentation for specific subdirectories by focusing analysis on relevant file paths.
- Changelog Renderers - Enables definition of document structure and content through customizable templates to match project standards.
- Local-First Architectures - Prioritizes local repository analysis for high performance and offline functionality while optionally integrating remote data.
- Path-Based Filtering Rules - Filters commits based on modified file paths to focus documentation on specific project areas.
- Regex Categorization Rules - Groups commits into specific sections based on regex matching against commit metadata and messages.
- Changelog File Managers - Creates new documentation files or prepends updates to existing files for ongoing maintenance.
- Repository Hosting Integrations - Connects to remote hosting services via authentication tokens to retrieve metadata for automated changelog generation.
- Submodule Management Tools - Incorporates commit history from nested version control submodules into the primary project documentation.
- Continuous Integration Pipelines - Integrates documentation generation into automated CI pipelines to produce updated history files.
- Offline Build Environments - Produces version history reports using only local repository data to avoid network dependencies.
- Declarative Configurations - Uses structured configuration files to define the behavior and formatting rules of the changelog generation process.
- Regex-Based Parsers - Uses regular expressions to parse and categorize raw commit messages into structured data segments.
