{"id":9774,"library":"git-cliff","title":"git-cliff","description":"git-cliff is a highly customizable changelog generator built in Rust with a convenient Python interface. It processes Git history to produce detailed, human-readable release notes based on conventional commits. Currently at version 2.12.0, the library maintains an active development pace with frequent updates and new features.","status":"active","version":"2.12.0","language":"python","source_language":"en","source_url":"https://github.com/orhun/git-cliff","tags":["changelog","git","release notes","automation","conventional commits"],"install":[{"cmd":"pip install git-cliff","lang":"bash","label":"Install git-cliff"}],"dependencies":[],"imports":[{"wrong":"from gitcliff import generate_changelog","symbol":"generate_changelog","correct":"from git_cliff import generate_changelog"}],"quickstart":{"code":"import os\nimport tempfile\nimport shutil\nimport subprocess\nfrom git_cliff import generate_changelog\n\n# Create a temporary directory to simulate a project environment\ntemp_dir = tempfile.mkdtemp()\noriginal_cwd = os.getcwd()\nos.chdir(temp_dir)\n\ntry:\n    # Initialize a dummy Git repository\n    subprocess.run([\"git\", \"init\", \"-b\", \"main\"], check=True, capture_output=True)\n    subprocess.run([\"git\", \"config\", \"user.name\", \"Test User\"], check=True, capture_output=True)\n    subprocess.run([\"git\", \"config\", \"user.email\", \"test@example.com\"], check=True, capture_output=True)\n\n    # Create some dummy commits with conventional commit messages\n    with open(\"file1.txt\", \"w\") as f:\n        f.write(\"initial content\")\n    subprocess.run([\"git\", \"add\", \".\"], check=True, capture_output=True)\n    subprocess.run([\"git\", \"commit\", \"-m\", \"feat: initial setup of the project\"], check=True, capture_output=True)\n\n    with open(\"file2.txt\", \"w\") as f:\n        f.write(\"more content\")\n    subprocess.run([\"git\", \"add\", \".\"], check=True, capture_output=True)\n    subprocess.run([\"git\", \"commit\", \"-m\", \"fix: resolve minor typo in file2\"], check=True, capture_output=True)\n\n    subprocess.run([\"git\", \"tag\", \"v1.0.0\"], check=True, capture_output=True)\n\n    with open(\"file3.txt\", \"w\") as f:\n        f.write(\"new feature\")\n    subprocess.run([\"git\", \"add\", \".\"], check=True, capture_output=True)\n    subprocess.run([\"git\", \"commit\", \"-m\", \"feat: implement new awesome feature\"], check=True, capture_output=True)\n\n    # Create a minimal .git-cliff.toml config file for predictable output\n    cliff_config_content = r\"\"\"\n[changelog]\nbody = \"\"\"\n{{% if version %}}\n## {{ version }} - {{ timestamp | date(format=\"%Y-%m-%d\") }}\n{{% else %}}\n## Unreleased\n{{% endif %}}\n{{% for group, commits in commits | group_by(attribute=\"group\") %}}\n### {{ group | upper_first }}\n{{% for commit in commits %}}\n- {{ commit.message | upper_first }} ([{{ commit.id | truncate(length=7, end=\"\") }}]({{ commit.id }}))\n{{% endfor %}}\n{{% endfor %}}\n\"\"\"\n\n[git]\nfilter_commits = true\nconventional_commits = true\n\n[git.mapper]\nfeat = \"Features\"\nfix = \"Bug Fixes\"\n\"\"\"\n    with open(\".git-cliff.toml\", \"w\") as f:\n        f.write(cliff_config_content)\n\n    # Generate the changelog using the Python interface\n    # It will automatically discover the .git-cliff.toml config and the git repo\n    changelog_output = generate_changelog(\n        config_path=\".git-cliff.toml\" # Specify the config file explicitly\n    )\n    print(\"\\n--- Generated Changelog ---\\n\")\n    print(changelog_output)\n\nfinally:\n    # Clean up the temporary directory\n    os.chdir(original_cwd)\n    shutil.rmtree(temp_dir)\n","lang":"python","description":"This quickstart demonstrates how to generate a changelog using `git-cliff`'s Python interface. It creates a temporary Git repository with dummy commits and a minimal configuration file to ensure a self-contained and runnable example."},"warnings":[{"fix":"Rename your configuration file from `cliff.toml` to `.git-cliff.toml`. Review the changelog for `v2.0.0` for any other potential syntax or section changes within the TOML structure that might require updates.","message":"Starting with `v2.0.0`, `git-cliff` officially transitioned its default configuration filename from `cliff.toml` to `.git-cliff.toml`. Existing configurations using the old filename may not be automatically discovered or used.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Adopt a consistent Git tagging strategy (e.g., semantic versioning like `vX.Y.Z`). Use `git tag` to verify existing tags. For generating changelogs for the latest commits without a tag, use arguments like `--unreleased` (if available via CLI or exposed in Python API) or generate to a specific tag range.","message":"`git-cliff` relies heavily on Git tags for version detection and changelog segmentation. If your repository lacks consistent tags (e.g., `v1.0.0`), the generated changelog might be incomplete, misleading, or include all history under an 'Unreleased' section.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When debugging complex configuration or templating issues, try running `git cliff --verbose` directly in your terminal with the same configuration file. This often provides more granular diagnostics and stack traces from the Rust engine that can pinpoint the exact problem area.","message":"The Python interface is a direct binding to the underlying Rust core. This means that detailed error messages, especially those related to configuration file parsing or template rendering (which uses Tera, a Jinja2-like engine), often originate from the Rust side and might require familiarity with `git-cliff`'s CLI output for full interpretation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.12.0':40 'activ':45 'autom':58 'base':33 'built':13 'changelog':11,54 'cliff':3,6 'commit':36,60 'conveni':18 'convent':35,59 'current':37 'customiz':10 'detail':27 'develop':46 'featur':53 'frequent':49 'generat':12 'git':2,5,23,55 'git-cliff':1,4 'high':9 'histori':24 'human':29 'human-read':28 'interfac':20 'librari':42 'maintain':43 'new':52 'note':32,57 'pace':47 'process':22 'produc':26 'python':19 'readabl':30 'releas':31,56 'rust':15 'updat':50 'version':39","created_at":"2026-04-17T01:20:39.347603+00:00","updated_at":"2026-04-17T01:20:39.347603+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'git_cliff'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.13.1","cli_name":"git-cliff","cli_version":"git-cliff 2.13.1","type":"library","homepage":"https://git-cliff.org","github":"https://github.com/orhun/git-cliff","docs":null,"changelog":null,"pypi":"https://pypi.org/project/git-cliff/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}