git-consistent

Give consistency to your project's git logs.

git-consistent helps you and your team maintain a consistent and readable git commit history by enforcing a configurable commit message format.

Supported Node.js versions:

Features

• Interactive & Inline Modes: Create commits interactively or directly from the command line.
• Customizable Commit Format: Define your own commit message structure with a simple YAML configuration file (.git_consistent).
• Validation Rules: Enforce standards like case rules for the subject, character limits, and more.
• Dynamic Variables: Automatically insert values like issue numbers into your commit messages.
• Branch Name Parsing: Extract information (e.g., issue IDs) directly from your git branch name.
• Emoji Support: Easily include emojis in your commit types.
• git-duet Integration: Works with git-duet for pair programming commits.

Installation

npm install -g git-consistent

Optional: Set up a Git Alias

For easier access, you can create a git alias.

git config --global alias.con "consistent -i"

This allows you to run git con instead of git consistent -i.

Optional: Configure Your Editor

For multiline commit bodies, git-consistent uses the editor defined in your environment variables.

# For Visual Studio Code
export EDITOR='code -w'

# For Cursor
export EDITOR='cursor -w'

Getting Started

1. Initialize Configuration

Run the init command in your project repository.

git consistent --init

This will ask you a few questions and generate two files:

• .git_consistent: Your configuration file.
• .gitcommit_template: The template for your commit messages.

Feel free to edit these files to match your project's conventions.

2. Create a Commit

You can create commits in several ways.

Interactive Mode

Run git consistent in interactive mode to be prompted for each part of the commit message.

$ git consistent -i
? Select type: feat
? Enter subject: implement new feature
? Enter body multiline:
This is an amazing new feature.

You can also combine interactive mode with command-line arguments. The tool will only prompt for the missing parts.

$ git consistent -i --subject="implement new feature"
? Select type: feat
? Enter body multiline:
This is an amazing new feature.

Inline Mode

Provide all the information using command-line flags.

git consistent --type="feat" --subject="implement new feature" --body="This is an amazing feature."

Configuration (.git_consistent)

The .git_consistent file allows you to define and customize the structure of your commit messages. It uses a simple YAML-like format.

Here is the basic structure:

<term>:
  <option key>: <option value>
  <option key>: <option value>
<term>:
  <option key>: <option value>

Each <term> corresponds to a variable in your .gitcommit_template file.

Configuration Options

Key	Description	Possible Values
type	The input type for the term.	enum, string, text, variable, branch
required	Whether the term is mandatory.	true, false
description	A description shown in interactive mode.	string
values	A list of options for enum type.	Array of { name, description } objects
prefix	A string to add before the input value.	string
suffix	A string to add after the input value.	string
default	A default value for the term.	string
origin	(type: variable only) The source term for the variable's value.	string (name of another term)
regExp	(type: branch only) A regex to extract a value from the branch name.	string
regExpMatchNum	(type: branch only) The match group index from regExp.	integer
regExpFlag	(type: branch only) A flag for the regex (e.g., i for case-insensitive).	string
rules	A set of validation rules for the input.	Object

Validation Rules (rules)

Rule	Description	Possible Values
firstLetter	Enforces the case of the first letter.	upper, lower
dotAtEnd	Requires or disallows a dot at the end.	true, false
nonAscii	Allows or disallows non-ASCII characters.	true, false
numberOnly	Restricts the input to numbers only.	true, false
maxLength	The maximum allowed length of the string.	integer
minLength	The minimum allowed length of the string.	integer

Examples

Decorators

Add a prefix and suffix to a scope field.

scope:
  type: text
  required: false
  description: 'The scope could be specifying place of the commit change.'
  prefix: '('
  suffix: ')'

Validation

Enforce that a subject starts with a lowercase letter and has no dot at the end.

subject:
  type: string
  required: true
  description: 'The subject contains succinct description of the change'
  rules:
    firstLetter: lower
    dotAtEnd: false

Variables

Create a githubIssueUrl variable based on a githubIssueNum input.

.gitcommit_template:

<githubIssueNum> <subject>

<githubIssueUrl>
<body>

.git_consistent:

githubIssueNum:
  type: string
  required: false
  description: 'GitHub issue number'
  prefix: 'fix #'
subject:
  type: string
  required: true
  description: 'The subject contains succinct description of the change'
githubIssueUrl:
  type: variable
  origin: githubIssueNum
  description: 'GitHub issue URL'
  prefix: 'https://github.com/isuke/git-consistent/issues/'
body:
  type: text
  default: ''
  required: false
  description: 'The body contains details of the change'

$ git consistent -i --subject="test" --body="This is test."
Enter githubIssueNum: 12

$ git log -n 1
commit a9d6457f3674c8620fbe72c769cee09ba5459f02
Author: isuke <[email protected]>
Date:   Sat Feb 10 17:40:33 2018 +0900

    fix #12 test

    https://github.com/isuke/git-consistent/issues/12
    This is test.

Extracting from Branch Name

Automatically generate an issue link from a branch name like issue/123-feature-name.

.gitcommit_template:

<subject>

<issueLink>
<body>

.git_consistent:

issueLink:
  type: branch
  required: false
  description: 'GitHub issue link'
  regExp: 'issue/([0-9]+)'
  regExpMatchNum: 1
  prefix: 'https://github.com/you/repository/issues/'
  suffix: "\n"

$ git branch
* issue123_hoge
  master

$ git consistent -i --subject="test" --body="This is test."

$ git log -n 1
commit a9d6457f3674c8620fbe72c769cee09ba5459f02
Author: isuke <[email protected]>
Date:   Sat Feb 10 17:40:33 2018 +0900

    test

    https://github.com/you/repository/issues/123
    This is test.

Emoji Support

Use an enum to provide a list of emojis for the commit type.

emoji:
  type: enum
  required: true
  description: 'Commit type'
  values:
    - name: ':heavy_plus_sign:'
      description: 'When implementing a new feature'
    - name: ':sunny:'
      description: 'When fixing a bug'
    - name: ':art:'
      description: 'When refactoring code'

This will display a selectable list in interactive mode:

Integrations

git-duet

Use the -d or --duet flag to commit with git-duet authors.

git consistent -d --type="feat" --subject="duet test"

This will add a Signed-off-by: trailer to the commit message.

Command Reference

Option	Alias	Description
--duet	-d	Run in git-duet mode.
--dry-run	-D	Run in dry-run mode (don't commit).
--interactive	-i	Run in interactive mode.
--silent	-S	Don't show the final git commit command.
--init	-I	Generate configuration files.
--version	-V	Output the version number.
--help	-h	Output usage information.
--type <type>		Set the commit type.
--subject <subject>	-m	Set the commit subject.
--body [body]		Set the commit body.

Samples

See more examples and advanced use cases:

• Commitizen Sample
• Issue Link Sample
• Issue Link from Branch Name Sample
• Emoji Sample
• Sample Type List

Badge for Your Project

Show that your project uses git-consistent by adding this badge to your README.md.

Markdown

[![git-consistent friendly](https://img.shields.io/badge/git--consistent-friendly-brightgreen.svg)](https://github.com/isuke/git-consistent)

reStructuredText

.. image:: https://img.shields.io/badge/git--consistent-friendly-brightgreen.svg
   :alt: git-consistent friendly
   :target: https://github.com/isuke/git-consistent

AsciiDoc

image:https://img.shields.io/badge/git--consistent-friendly-brightgreen.svg["git-consistent friendly",link="https://github.com/isuke/git-consistent"]