gitag 0.0.2

A CLI tool for automatic git tagging based on commit messages

🚀 gitag

gitag is a modern CLI tool that parses commit messages following Conventional Commits and applies Semantic Versioning automatically — perfect for CI/CD pipelines.

Commit Pattern	Bump Level	Version Change
!:, BREAKING CHANGE:	major	1.2.3 → 2.0.0
feat(...), feature(...)	minor	1.2.3 → 1.3.0
fix(...), perf(...), refactor(...), docs(...), style(...), chore(...), test(...), ci(...), build(...)	patch	1.2.3 → 1.2.4

---

📖 Table of Contents

• ⚡ Quickstart
• ✨ Features
• 🛠️ Commit Mapping & Version Bumps
• 📦 Installation
• 🔧 CLI Reference
• 🤖 GitHub Actions Example
• ⚙️ Configuration
• 📚 Deep Dive Documentation
• 🤝 Contributing & 📄 License

---

Quickstart

1. Install 📦

   pip install gitag
   

2. Preview tag 🔍

   gitag --dry-run
   

3. Tag & Changelog 🔁

   gitag --ci --changelog
   

For development:

git clone https://github.com/henrymanke/gitag.git
cd gitag
pip install -e .[dev]

---

Features

• ✅ Semantic Versioning (major, minor, patch)
• 🔍 Detect latest Git tag
• 🧠 Commit-based bump detection via Conventional Commits
• 📄 (BETA) Optional CHANGELOG.md generation
• 🔁 Dry-run & CI modes
• 🚀 Push tags via GITHUB_TOKEN
• ⚙️ Configurable via pyproject.toml
• 🔀 Flexible merge commit strategies
• 🧪 100% tested with pytest and mocks

---

Commit Mapping & Version Bumps

Commit Type	Bump Level	Example	Spec Reference
BREAKING CHANGE:	major	BREAKING CHANGE: update API method	SemVer
feat: / feature:	minor	feat: add new export feature	Conventional Commits
fix: / chore:	patch	fix: correct typo in docs	Conventional Commits

---

Installation

Install from PyPI:

pip install gitag

Or install for development:

git clone https://github.com/henrymanke/gitag.git
cd gitag
pip install -e .[dev]

---

CLI Reference

Command	Description
--dry-run	Preview the next tag without applying it
--changelog	Generate or update CHANGELOG.md
--push	Push the new tag to the remote repository
--pre <label>	Add a pre-release label (e.g. alpha.1)
--build <meta>	Include build metadata (e.g. 123abc)
--config <path>	Path to pyproject.toml (default: project root)
--merge-strategy	Override bump strategy (auto, always, merge_only)

See Advanced CLI Options for full list.

---

GitHub Actions Example

Save as .github/workflows/auto-tag.yml:

name: Auto Tag

on:
  push:
    branches: [main]

jobs:
  tag:
    runs-on: ubuntu-latest

    # Allow this workflow to push tags and artifacts
    permissions:
      contents: write

    # GitHub token for pushing tags and uploading artifacts
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # or use a personal token for cross-repo support

    steps:
      # 1. Checkout the full repository (including all tags and history)
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0          # Needed to find the latest tag
          token: ${{ env.GH_TOKEN }}

      # 2. Set up Python 3.11 environment
      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      # 3. Install the gitag CLI tool
      - name: Install gitag
        run: pip install gitag

      # 4. Run gitag in CI mode and generate the changelog
      - name: Run gitag (CI mode + changelog)
        run: gitag --ci --debug --changelog

      # 5. Upload the generated CHANGELOG.md as a build artifact
      - name: Upload generated changelog
        uses: actions/upload-artifact@v4
        with:
          name: changelog
          path: CHANGELOG.md

Commit and push — workflow runs on every push to main.

---

Configuration

Add to pyproject.toml:

[tool.gitag]
prefix = "v"
merge_strategy = "auto"

[tool.gitag.bump_keywords]
major = ["BREAKING CHANGE"]
minor = ["feat:"]
patch = ["fix:"]

See Config Reference for details.

---

Deep Dive Documentation

• Config Reference
• CHANGELOG Guide
• Default Config
• Architecture Overview

---

Contributing & License

Contributions are welcome! Read CONTRIBUTING.md.

Licensed under the MIT License — see LICENSE for details.