Skip to main content
Thank you for your interest in contributing to git-cliff! This guide will help you get started with development, testing, and submitting contributions.

​
Before You Start

Before making significant changes:

​
Development Setup

1

Install Rust

Install Rust 1.85.1 or later:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Verify installation:
rustc --version
2

Install nightly toolchain

The nightly toolchain is required for rustfmt:
rustup toolchain install nightly
Optionally, configure your editor/IDE to use the nightly toolchain for formatting in this repository.
3

Fork and clone

Fork the repository on GitHub, then clone your fork:
git clone https://github.com/{username}/git-cliff
cd git-cliff
Or using SSH:
git clone [email protected]:{username}/git-cliff
cd git-cliff
4

Fetch tags

Tags are required for tests to pass:
git fetch --tags https://github.com/orhun/git-cliff
5

Build the project

Build git-cliff to ensure everything is set up correctly:
cargo build
This will compile both the git-cliff-core library and the git-cliff CLI binary.

​
Development Workflow

​
Making Changes

  1. Create a branch from main: 
    git checkout -b feature/my-new-feature
  2. Follow Conventional Commits: All commits should follow the Conventional Commits specification: 
    <type>(<scope>): <description>

[optional body]

[optional footer]
    Types: feat, fix, docs, refactor, test, chore, ci, perf, style Examples: 
    git commit -m "feat(parser): add support for custom footers"
git commit -m "fix(template): handle empty release versions"
git commit -m "docs: update configuration examples"
  3. Write or update tests: Add tests for new features or update existing tests for changes: 
    cargo test
    All tests must pass before submitting a PR.

​
Testing

​
Run all tests

cargo test

​
Update snapshot tests

If you’ve changed output formats or templates, update snapshots: 
env UPDATE_EXPECT=1 cargo test
Snapshot tests use the expect-test crate to verify output matches expected values.

​
Run specific tests

# Test a specific module
cargo test --package git-cliff-core --lib changelog

# Test with a pattern
cargo test conventional_commit

​
Test with features

# Test without default features
cargo test --no-default-features

# Test with specific features
cargo test --features github,gitlab

​
Code Quality Checks

Before submitting a PR, run all quality checks locally:

​
Clippy (required)

Run Clippy with warnings treated as errors: 
cargo clippy --tests --verbose -- -D warnings
All warnings must be resolved. For additional linting guidance: 
cargo clippy --all-targets --verbose -- -W clippy::pedantic
Pedantic lints are optional but recommended for new code. You may allow specific pedantic lints with clear justification in comments.

​
Formatting (required)

Check formatting with nightly rustfmt: 
cargo +nightly fmt --all -- --check --verbose
If formatting fails, auto-format the code: 
cargo +nightly fmt --all
The project uses unstable rustfmt options that require the nightly toolchain. Make sure you’re using cargo +nightly fmt.

​
Project Structure

Understand the workspace layout: 
git-cliff/
├── git-cliff-core/          # Core library
│   ├── src/
│   │   ├── changelog.rs     # Changelog generation
│   │   ├── commit.rs        # Commit parsing
│   │   ├── config.rs        # Configuration
│   │   ├── template.rs      # Template engine
│   │   ├── release.rs       # Release management
│   │   ├── remote/          # Remote integrations
│   │   └── ...
│   └── Cargo.toml
├── git-cliff/               # CLI binary
│   ├── src/
│   │   ├── main.rs          # Entry point
│   │   ├── args.rs          # CLI arguments
│   │   └── lib.rs           # Core CLI logic
│   └── Cargo.toml
└── Cargo.toml               # Workspace manifest
See the Architecture page for detailed module information.

​
Submitting a Pull Request

1

Ensure all checks pass

Before submitting, verify:
  • ✅ All tests pass: cargo test
  • ✅ Clippy succeeds: cargo clippy --tests -- -D warnings
  • ✅ Code is formatted: cargo +nightly fmt --all -- --check
  • ✅ Documentation is updated (if applicable)
2

Push your changes

Push your branch to your fork:
git push origin feature/my-new-feature
3

Create pull request

  1. Go to the git-cliff repository
  2. Click “New Pull Request”
  3. Select your fork and branch
  4. Fill out the PR template
4

Address feedback

  • Respond to review comments
  • Make requested changes
  • Push updates to the same branch
  • Re-run all checks after changes

​
Pull Request Guidelines

​
PR Description

Provide a clear description that includes:
  • What changed
  • Why the change was made
  • How it was implemented
  • Testing performed
  • Related issues (e.g., “Fixes #123”)

​
Documentation

Update documentation if your changes affect:
  • User-facing features
  • Configuration options
  • Command-line arguments
  • API interfaces

​
Breaking Changes

If your PR includes breaking changes:
  1. Mark commits with BREAKING CHANGE: in the footer
  2. Clearly explain the breaking change in the PR description
  3. Provide migration guidance for users

​
Code Style

​
Rust Conventions

  • Follow the Rust API Guidelines
  • Use descriptive variable and function names
  • Add doc comments for public APIs
  • Prefer Result over unwrap() (enforced by clippy)
  • Use ? operator for error propagation

​
Documentation Comments

Write documentation for public items: 
/// Generates a changelog from the given releases.
///
/// # Arguments
///
/// * `releases` - Vector of releases to include
/// * `config` - Configuration for generation
///
/// # Errors
///
/// Returns an error if template rendering fails.
pub fn generate_changelog(releases: Vec<Release>, config: Config) -> Result<String> {
    // ...
}

​
Error Handling

Use the project’s Result type: 
use crate::error::Result;

fn process_commit(commit: &Commit) -> Result<String> {
    let message = commit.message.ok_or(Error::MissingCommitMessage)?;
    Ok(message.trim().to_string())
}

​
Toolchain Information

​
Stable vs Nightly

  • Stable Rust (1.85.1+): Used for builds and tests
  • Nightly Rust: Required only for formatting with unstable rustfmt options
CI runs both stable and nightly checks.

​
Rust Edition

The project uses Rust 2024 edition: 
edition = "2024"
rust-version = "1.85.1"

​
Getting Help

If you need assistance:

​
License

By contributing, you agree that your contributions will be licensed under: You may choose either license for your use.

​
Recognition

All contributors are recognized in: Thank you for contributing to git-cliff!

Build docs developers (and LLMs) love

Get started for freeTalk to us