gib

Gibberish git history analyser, a terminal utility that uses conventional commits to analyse your git history.

Goal

The aim of the utility is to provide tools for pipelines or locally to facilitate semantic version calculation, changelog generation for a project in an automated fashion using conventional commits on the checked out branch of a git repository.

Note: be aware that gib always uses the commmits of the checked out branch, hence shallow pulls can affect the outcome of the results.

Getting Started

You have the following options to obtain the utility:

• See releases for pre-built binaries that can be used for your own Dockerfile or directly on a machine.
• Docker images are available at Dockerhub and Github Packages (these are optimised to be as small as possible).
• Otherwise you can build it with Rust:

cargo build --release
./target/release/gib version # This binary can be moved to your path

Features

Currently supported commands:

Gibberish git history analyser, a terminal utility that uses conventional commits to analyse your git history

Usage: gib <COMMAND>

Commands:
  version    Command to calculate the semantic version based on the conventional commits of the current branch
  changelog  Command to generate a simple changelog markdown file based on the conventional commmits and tags of the current branch
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Version command options:

Command to calculate the semantic version based on the conventional commits of the current branch

Usage: gib version [OPTIONS]

Options:
  -p, --path <PATH>
          Specify the path of the git project, if not specified current directory will be used
      --major
          Bump current project version with a major increment
      --minor
          Bump current project version with a minor increment
      --patch
          Bump current project version with a patch increment
  -c, --commit-git-hook <COMMIT MESSAGE>
          Mechanism to provide the latest commit made to be included in project version calculation, this takes precedence when used inconjunction with either major, minor or patch flags
  -s, --scope-filter <SCOPE_REGEX_FILTER>
          Scope regex filter; provide mechanism for calculating the version of a project within a monorepo based of a regular expression
  -h, --help
          Print help

Tool for testing scope regular expressions with fancy-regex crate: Rustexp

Changelog command options:

Intent of this command is to provide a simple changelog that will meet most needs, if you want more customisation have a look at git-cliff.

Command to generate a simple changelog markdown file based on the conventional commmits and tags of the current branch

Usage: gib changelog [OPTIONS]

Options:
  -p, --path <PATH>
          Specify the path of the git project, if not specified current directory will be used
  -c, --commit-git-hook <COMMIT MESSAGE>
          Mechanism to provide the latest commit made to be included in changelog generation
  -s, --scope-filter <SCOPE_REGEX_FILTER>
          Scope regex filter; provide mechanism for generating a changelog for a specific project within a monorepo based of a regular expression
  -h, --help
          Print help

Tool for testing scope regular expressions with fancy-regex crate: Rustexp

Docker

Some notes regarding using gib with docker:

• Dockerhub - docker pull coenraadhuman/gib:latest
• Github Packages - docker pull ghcr.io/coenraadhuman/gib:latest

Image Additionals

The below were added to the image for convience on pipeline usage:

• bash
• sed
• git

Important - Work Directory

By default the work directory is set to /app this can be changed with the -w option on docker run to be the path of the mounted repository. It is important to update this when mounting to a different directory since the entry point for the container relies on the working directory to ensure gib runs with the correct Linux permissions.

Docker Run Examples

Run Version:

# The default work directory is /app
$ docker run -v $PWD:/app ghcr.io/coenraadhuman/gib:latest version
$ 0.10.1

Run Changelog (redirect standard output to file that can be stored):

# The default work directory is /app
$ docker run -v $PWD:/app ghcr.io/coenraadhuman/gib:latest changelog > CHANGELOG.md

Pipeline Examples:

• Github Actions

Further Reading

• Semantic Version
• Conventional Commits
• Conventional Commit Types