Git Versioner

---
config:
  theme: default
  gitGraph:
    mainBranchName: "trunk"
---
gitGraph:
   checkout "trunk"
   commit id: "0.1.0-pre.1"
   commit id: "0.1.0-pre.2" tag: "v1.0.0"
   branch "release/1.0.0"
   checkout "trunk"
   commit id: "1.1.0-pre.1"
   checkout "release/1.0.0"
   commit id: "1.0.1-pre.1"
   commit id: "1.0.1-pre.2" tag: "v1.0.1"
   commit id: "1.0.2-pre.1"
   commit id: "1.0.2-pre.2" tag: "v1.0.2"
   checkout "trunk"
   commit id: "1.1.0-pre.2"
   branch "release/1.1.0"
   checkout "trunk"
   commit id: "1.2.0-pre.1"
   checkout "release/1.1.0"
   commit id: "1.1.0-pre.3"
   commit id: "1.1.0-pre.4" tag: "v1.1.0"
   commit id: "1.1.1-pre.1"
   commit id: "1.1.1-pre.2" tag: "v1.1.1"
   checkout "trunk"
   commit id: "1.2.0-pre.2"
   branch "release/1.2.0"
   checkout "trunk"
   commit id: "1.3.0-pre.1"
   checkout "release/1.2.0"
   commit id: "1.2.0-pre.3"
   commit id: "1.2.0-pre.4" tag: "v1.2.0"
   commit id: "1.2.1-pre.1"
   commit id: "1.2.1-pre.2" tag: "v1.2.1"
   checkout "trunk"
   commit id: "1.3.0-pre.2" tag: "v1.3.0"
   commit id: "1.4.0-pre.1"
   commit id: "1.4.0-pre.2"
   branch "release/2.0.0"
   commit id: "2.0.0-pre.1"
   checkout "trunk"
   commit id: "2.1.0-pre.1"

A Rust application designed to automatically calculate version numbers for Git repositories employing trunk-based development with release branches.

Table of Contents

• Introduction
• Features
• Installation
• Usage
• Configuration
• Contributing
• License
• Inspiration

Introduction

Git Versioner is a command-line tool developed in Rust that facilitates automated versioning in Git repositories. It is particularly suited for workflows using trunk-based development, where the primary branch (referred to as "trunk") serves as the main line of integration, and release branches are created to stabilize specific versions. The tool analyzes the repository's commit history, branches, and tags to derive semantic version numbers, including pre-release identifiers such as "-pre.X" for development builds.

This project aims to streamline release management by eliminating manual version updates, ensuring consistency, and supporting parallel development on multiple release lines. It draws inspiration from established versioning tools while focusing on simplicity and integration with modern Git practices.

Features

• Automated Version Calculation: Derives version numbers based on commit history, branch structure, and existing tags.
• Support for Trunk-Based Development: Recognizes the "trunk" as the main branch and handles release branches (e.g., "release/1.0.0") for patch and minor updates.
• Semantic Versioning Compliance: Generates versions in the format MAJOR.MINOR.PATCH-pre.X for pre-releases and MAJOR.MINOR.PATCH for stable tags.
• Tag Management: Identifies and applies tags for stable releases (e.g., "v1.0.0").
• Configurable Branch Naming: Allows customization of the main branch name (default: "trunk").
• Integration-Friendly: Suitable for use in continuous integration/continuous deployment (CI/CD) pipelines.

Installation

To install Git Versioner, ensure you have Rust and Cargo installed on your system. Rust can be obtained via rustup.

From Cargo (Recommended)

You can install Git Versioner directly from crates.io:

cargo install git-versioner

GitHub Action

Git Versioner can be used directly as a GitHub Action. It will automatically export the calculated version components to GITHUB_OUTPUT. Outputs are available with a GitVersion_ prefix (e.g., GitVersion_SemVer) and also in PascalCase without prefix (e.g., SemVer).

- name: Determine Version
  uses: crown0815/git-versioner@v1
  id: versioner
  with:
    # Optional configuration (see below for available inputs)
    as-release: true

Example workflow

name: CI
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required to see all tags and history

      - name: Determine Version
        id: versioner
        uses: crown0815/git-versioner@v1

      - name: Use Version
        run: echo "The version is ${{ steps.versioner.outputs.SemVer }}"

From Source

1. Clone the repository:

   git clone https://github.com/Crown0815/git-versioner.git
   cd git-versioner
   

2. Build and install:

   cargo install --path .
   

The executable will be available in the target/release directory or in your Cargo bin path if installed globally.

Usage

Once installed, run Git Versioner from the root of your Git repository to compute the current version:

git-versioner

This command will output the calculated version string based on the repository's state.

Command-Line Options

• --config <PATH>: Specify a custom configuration file (default: none).
• --branch <NAME>: Override the main branch name (default: "trunk").
• --help: Display usage information.

For integration in scripts or CI/CD, capture the output for use in build artifacts or tags.

The command line options allow overwriting of configuration options using (see also Configuration) and some additional options:

  -p, --path <PATH>
          Path to the repository to calculate the version for
      --main-branch <MAIN_BRANCH>
          Regex to detect the main branch
      --release-branch <RELEASE_BRANCH>
          Regex to detect the release branch(es)
      --feature-branch <FEATURE_BRANCH>
          Regex to detect the feature branch(es)
      --tag-prefix <TAG_PREFIX>
          Regex to detect version tag(s)
      --pre-release-tag <PRE_RELEASE_TAG>
          Regex to detect pre-release version tag(s)
      --continuous-delivery
          Calculate version using continuous delivery mode
      --commit-message-incrementing <COMMIT_MESSAGE_INCREMENTING>
          Increment based on conventional commits (set to 'Enabled' or 'Disabled')
  -a, --as-release
          Forces release generation instead of pre-release
      --show-config
          Print effective configuration and exit
  -v, --verbose
          
  -c, --config <CONFIG_FILE>
          Path to a configuration file (TOML or YAML)
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

For integration in scripts or CI/CD, capture the output for use in build artifacts or tags.

Configuration

Git Versioner supports a YAML or TOML configuration file to customize its behavior. Create a file named .git-versioner.toml, .git-versioner.yaml, or .git-versioner.yml in the repository root. All fields are optional and will fall back to internal defaults if not specified.

The default configuration is as follows:

MainBranch: ^(trunk|main|master)$
ReleaseBranch: ^releases?[/-](?<BranchName>.+)$
FeatureBranch: ^features?[/-](?<BranchName>.+)$
TagPrefix: '[vV]?'
PreReleaseTag: pre
CommitMessageIncrementing: Disabled

Configuration Fields

• MainBranch: Specifies the pattern of the main development branch (default: ^(trunk|main|master)$).
• ReleaseBranch: Defines the pattern for release branches (default: ^releases?[/-](?<BranchName>.+)$).
• FeatureBranch: Defines the pattern for feature branches (default: ^features?[/-](?<BranchName>.+)$).
• TagPrefix: Defines the prefix of versions on tags and release branches' BranchName (default: ^[vV]?).
• PreReleaseTag: The identifier used for pre-release versions (default: pre).

Additional options may be added in future releases to support advanced versioning rules.

Contributing

Contributions are welcome to enhance Git Versioner. To contribute:

1. Fork the repository on GitHub.
2. Create a new branch for your feature or bug fix: git checkout -b feature/your-feature.
3. Commit your changes with clear messages.
4. Push to your fork: git push origin feature/your-feature.
5. Open a pull request, describing the changes and referencing any related issues.

Please adhere to Rust's coding standards, include tests for new features. For major changes, discuss them in an issue first.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Inspiration

This tool is heavily inspired and mimics the outputs generated by GitVersion.