Install via PyPI

Install git-cliff from PyPI using pip.

Quick Install

pip install git-cliff

Installation Steps

Ensure Python is installed

Check your Python version:

python --version
# or
python3 --version

Python 3.7 or higher is recommended.

Install git-cliff

System-wide
Virtual Environment
User Install
pipx

Install globally:

pip install git-cliff

Or with Python 3:

pip3 install git-cliff

Install in a virtual environment (recommended):

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Install git-cliff
pip install git-cliff

Install for current user only:

pip install --user git-cliff

User installations go to ~/.local/bin on Linux/macOS. Ensure this is in your PATH.

Install with pipx for isolated environments:

# Install pipx if needed
pip install pipx
pipx ensurepath

# Install git-cliff
pipx install git-cliff

Verify installation

git-cliff --version

Expected output:

git-cliff 2.7.0

Test in a repository

cd /path/to/your/git/repo
git-cliff --help

Using in Python Projects

Add to requirements.txt

requirements.txt

git-cliff==2.7.0

Install dependencies:

pip install -r requirements.txt

Add to pyproject.toml

pyproject.toml

[project.optional-dependencies]
dev = [
    "git-cliff>=2.7.0",
]

Install with dev dependencies:

pip install -e ".[dev]"

Add to setup.py

setup.py

from setuptools import setup

setup(
    name="your-package",
    extras_require={
        "dev": [
            "git-cliff>=2.7.0",
        ],
    },
)

Integration Examples

Python Script
Release Script
Pre-commit Hook

Call git-cliff from Python:

generate_changelog.py

#!/usr/bin/env python3
import subprocess
import sys

def generate_changelog(output_file="CHANGELOG.md"):
    """Generate changelog using git-cliff."""
    try:
        result = subprocess.run(
            ["git-cliff", "-o", output_file],
            check=True,
            capture_output=True,
            text=True,
        )
        print(f"Changelog generated: {output_file}")
        return result.returncode
    except subprocess.CalledProcessError as e:
        print(f"Error generating changelog: {e.stderr}", file=sys.stderr)
        return e.returncode
    except FileNotFoundError:
        print("Error: git-cliff not found. Install with 'pip install git-cliff'", file=sys.stderr)
        return 1

if __name__ == "__main__":
    sys.exit(generate_changelog())

Usage:

python generate_changelog.py

Automate releases with Python:

release.py

#!/usr/bin/env python3
import subprocess
import sys
from pathlib import Path

def run_command(cmd, **kwargs):
    """Run a shell command."""
    result = subprocess.run(cmd, shell=True, text=True, capture_output=True, **kwargs)
    if result.returncode != 0:
        print(f"Error: {result.stderr}", file=sys.stderr)
        sys.exit(result.returncode)
    return result.stdout.strip()

def release(version):
    """Create a new release."""
    print(f"Creating release {version}...")
    
    # Generate changelog
    print("Generating changelog...")
    run_command(f"git-cliff --tag v{version} -o CHANGELOG.md")
    
    # Commit changelog
    print("Committing changelog...")
    run_command("git add CHANGELOG.md")
    run_command(f'git commit -m "chore: release v{version}"')
    
    # Create tag
    print(f"Creating tag v{version}...")
    run_command(f'git tag -a v{version} -m "Release v{version}"')
    
    print(f"\nRelease v{version} created successfully!")
    print("Don't forget to push: git push && git push --tags")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python release.py <version>", file=sys.stderr)
        sys.exit(1)
    
    release(sys.argv[1])

Usage:

python release.py 1.2.0

Use with pre-commit:

.pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: git-cliff
        name: Generate changelog
        entry: git-cliff
        args: ['-o', 'CHANGELOG.md', '--unreleased']
        language: system
        pass_filenames: false
        stages: [commit]

Install pre-commit:

pip install pre-commit
pre-commit install

Upgrading

Upgrade to the latest version:

pip install --upgrade git-cliff

Upgrade to a specific version:

pip install --upgrade git-cliff==2.7.0

Uninstalling

Remove git-cliff:

pip uninstall git-cliff

Troubleshooting

pip: command not found

Install pip:Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install python3-pip

Linux (Fedora):

sudo dnf install python3-pip

macOS:

python3 -m ensurepip --upgrade

git-cliff: command not found after installation

The installation directory may not be in your PATH.Check installation location:

pip show -f git-cliff

Add to PATH (Linux/macOS):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Add to PATH (Windows): Add %USERPROFILE%\AppData\Local\Programs\Python\Python3x\Scripts to your PATH environment variable.

Permission denied errors

If you get permission errors during installation:

Use --user flag:
```
pip install --user git-cliff
```

Or use a virtual environment:

python -m venv venv
source venv/bin/activate
pip install git-cliff

Avoid using sudo pip install as it can cause issues.

Conflicts with other packages

Use pipx for isolated installation:

pip install pipx
pipx install git-cliff

Or use a virtual environment for your project.

SSL certificate verification failed

If you encounter SSL errors:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org git-cliff

Better solution: Update your CA certificates:

pip install --upgrade certifi

Get Started

Installation

Usage

Configuration

Templating

Install via PyPI

Install via PyPI

Quick Install

Installation Steps

Using in Python Projects

Add to requirements.txt

Add to pyproject.toml

Add to setup.py

Integration Examples

Upgrading

Uninstalling

Troubleshooting

Next Steps

Configuration

Usage Examples

Build docs developers (and LLMs) love

Get Started

Installation

Usage

Configuration

Templating

​Install via PyPI

​Quick Install

​Installation Steps

​Using in Python Projects

​Add to requirements.txt

​Add to pyproject.toml

​Add to setup.py

​Integration Examples

​Upgrading

​Uninstalling

​Troubleshooting

​Next Steps

Configuration

Usage Examples

Build docs developers (and LLMs) love

Install via PyPI

Quick Install

Installation Steps

Using in Python Projects

Add to requirements.txt

Add to pyproject.toml

Add to setup.py

Integration Examples

Upgrading

Uninstalling

Troubleshooting

Next Steps