git-sumi

https://github.com/welpo/git-sumi
Admin
A non-opinionated Rust-based commit message linter that enforces customizable rules for conventional...
Tokens:15,203
Snippets:120
Trust Score:8.3
License:Apache-2.0
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install git-sumi using various package managers

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/index.md

Installs git-sumi using different package managers like Cargo, uv, pipx, pip, mise, and Chocolatey. Also includes instructions for pre-built binaries.

```bash
cargo install git-sumi
```

```bash
uv tool install git-sumi
```

```bash
pipx install git-sumi
```

```bash
pip install git-sumi
```

```bash
mise use github:welpo/git-sumi
```

```powershell
choco install git-sumi
```

```bash
Download the latest release from the [releases page](https://github.com/welpo/git-sumi/releases).
```

--------------------------------

### Website Development Setup

Source: https://github.com/welpo/git-sumi/blob/main/CONTRIBUTING.md

Commands to set up and run the project's website locally. This involves navigating to the website directory, installing Node.js dependencies, and starting the development server for Docusaurus.

```bash
cd website
npm install
npx docusaurus start
```

--------------------------------

### Initialize git-sumi

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/index.md

Initializes git-sumi from the root of your project, creating a default configuration file (sumi.toml) that can be customized.

```bash
git sumi --init
```

--------------------------------

### Install Git Sumi prepare-commit-msg Hook

Source: https://context7.com/welpo/git-sumi/llms.txt

Installs the git-sumi prepare-commit-msg hook. This hook displays enabled rules as comments when a user starts writing a commit message.

```bash
# Install the prepare-commit-msg hook
git sumi --init prepare-commit-msg

# When running `git commit`, you'll see:
# git-sumi rules enabled:
# Follow Conventional Commits format.
# Use the imperative mood in the description.
# Header length limit: 50
# List of allowed commit types: feat, fix, docs, refactor, test, chore
#
# Please enter the commit message for your changes...
```

--------------------------------

### git-sumi TOML Configuration File Example

Source: https://context7.com/welpo/git-sumi/llms.txt

A comprehensive TOML configuration file example demonstrating all available rules and options for git-sumi. This file can be placed in the repository root or home directory.

```toml
# sumi.toml - Place in repository root or home directory

# General options
quiet = false           # Suppress progress messages
display = true          # Display parsed commit after linting
format = "cli"          # Output format: cli, json, table, toml
split_lines = false     # Process each line as individual commit

# Conventional Commits
conventional = true     # Enforce Conventional Commits format
types_allowed = ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
scopes_allowed = ["api", "ui", "core", "deps"]  # Empty list allows all scopes

# Content rules
imperative = true              # Require imperative mood ("Add" not "Added")
description_case = "lower"     # Options: 'any', 'lower', 'upper'
no_period = true               # Disallow period at end of header
gitmoji = true                 # Require valid Gitmoji

# Length limits (0 disables)
max_header_length = 72
max_body_length = 100

# Whitespace
whitespace = true       # No leading/trailing/consecutive spaces

# Custom pattern matching
header_pattern = '^JIRA-\d+:'  # Require JIRA ticket prefix
strip_header_pattern = false    # Remove pattern before other validations
```

--------------------------------

### Example Git-Sumi Configuration with Header Stripping

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

Demonstrates a complete Git-Sumi configuration combining header pattern enforcement, imperative commit style, whitespace checks, and header pattern stripping. This example shows how `strip_header_pattern` affects subsequent validation rules.

```toml
header_pattern = "^JIRA-\d+ "
imperative = true
whitespace = true
strip_header_pattern = true

```

--------------------------------

### Install git-sumi using Cargo

Source: https://github.com/welpo/git-sumi/blob/main/README.md

Installs the git-sumi commit message linter using the Cargo package manager. This is the primary method for Rust developers to get the tool.

```bash
cargo install git-sumi
```

--------------------------------

### Set up git-sumi commit-msg hook

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/index.md

Sets up an automatic Git commit-msg hook to lint commit messages. This hook will interrupt commits that do not pass the configured rules.

```bash
git sumi --init commit-msg
```

--------------------------------

### Example Workflow with commit-msg Hook

Source: https://context7.com/welpo/git-sumi/llms.txt

Demonstrates the workflow after installing the commit-msg hook. Valid commit messages pass, while invalid ones are rejected with error messages.

```bash
# Example workflow after hook installation:
git commit -m "fix: resolve login timeout issue"
# Output on success:
# 💬 Input: "fix: resolve login timeout issue"
# ✅ All 5 checks passed.

# Output on failure:
git commit -m "fixed the bug"
# ❗ Commit must follow Conventional Commits format: <type>[optional scope]: <description>
# ❗ Found 1 linting error
# (commit is aborted)
```

--------------------------------

### Git Hooks Setup

Source: https://github.com/welpo/git-sumi/blob/main/CONTRIBUTING.md

Instructions for enabling Git hooks within the project. This involves configuring Git to use the hooks located in the .githooks directory, which can automate tasks before or after Git operations.

```bash
git config core.hooksPath .githooks
```

--------------------------------

### Install git-sumi using mise

Source: https://github.com/welpo/git-sumi/blob/main/README.md

Installs the git-sumi commit message linter using the mise tool version manager. This method is useful for managing multiple tool versions across projects.

```bash
mise use github:welpo/git-sumi
```

--------------------------------

### Configure Gitmoji and Header Pattern (TOML)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

Example TOML configuration for enforcing Gitmoji usage and a specific pattern for the commit header. The header pattern ensures the Gitmoji is the first element in the header.

```toml
gitmoji = true
header_pattern = '^(:\w+:|[\p\u{Emoji_Presentation}|[\p\u{Extended_Pictographic}\u200D\u8205D])'
```

--------------------------------

### Rust Project Setup and Commands

Source: https://github.com/welpo/git-sumi/blob/main/CONTRIBUTING.md

This section details essential Cargo commands for Rust projects. These commands are used for code formatting, checking, building, linting, and testing. They are fundamental for maintaining code quality and ensuring the project's integrity.

```bash
cargo fmt
cargo check
cargo build
cargo clippy
cargo test
```

--------------------------------

### Set Allowed Scopes (TOML)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

Example TOML configuration for specifying a list of allowed commit scopes. This helps maintain consistency in categorizing commits.

```toml
scopes_allowed = ["docs", "cli"]
```

--------------------------------

### Install git-sumi using Chocolatey

Source: https://github.com/welpo/git-sumi/blob/main/README.md

Installs the git-sumi commit message linter on Windows using the Chocolatey package manager. This provides a convenient way for Windows users to install the tool.

```bash
choco install git-sumi
```

--------------------------------

### Configure git-sumi rules in sumi.toml

Source: https://github.com/welpo/git-sumi/blob/main/README.md

Example TOML configuration for git-sumi, demonstrating how to set rules such as enforcing the imperative mood in commit descriptions and setting body line length limits.

```toml
# Rule: Use the imperative mood in the description.
# Example: 'Fix bug' instead of 'Fixed bug'.
imperative = true

# Rule: Body line length limit.

```

--------------------------------

### Install git-sumi using pip/uv/pipx

Source: https://github.com/welpo/git-sumi/blob/main/README.md

Installs the git-sumi commit message linter using Python package managers like uv, pipx, or pip. This allows users to leverage git-sumi within Python environments.

```bash
uv tool install git-sumi

```

```bash
pipx install git-sumi

```

```bash
pip install git-sumi
```

--------------------------------

### Set Allowed Types (TOML)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

Example TOML configuration for limiting commit types to a predefined list. This ensures uniformity in the nature of changes being committed.

```toml
types_allowed = ["feat", "fix"]
```

--------------------------------

### Install Git Sumi commit-msg Hook

Source: https://context7.com/welpo/git-sumi/llms.txt

Installs the git-sumi commit-msg hook, which automatically validates commit messages before they are finalized. The hook is placed in .git/hooks/commit-msg.

```bash
# Install the commit-msg hook
git sumi --init commit-msg

# The hook is created at .git/hooks/commit-msg with content like:
#!/bin/bash
# git-sumi commit-msg hook
git sumi --file "$1"
```

--------------------------------

### Validate commit message from command line

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/index.md

Validates a commit message directly from the command line using the `-c` or `--commit` flag. If the message passes all rules, it is committed; otherwise, errors are displayed.

```bash
git sumi -c '🎨 refactor: format JS with Prettier'
```

--------------------------------

### Code Coverage with Tarpaulin

Source: https://github.com/welpo/git-sumi/blob/main/CONTRIBUTING.md

Instructions for using Tarpaulin to measure code coverage in a Rust project. This includes installation and commands to generate reports in various formats, such as HTML and LCOV, which can be used for visualization and integration with other tools.

```bash
cargo install cargo-tarpaulin
cargo tarpaulin
cargo tarpaulin --out html --out lcov
```

--------------------------------

### Override Git Sumi Config with CLI Flags

Source: https://context7.com/welpo/git-sumi/llms.txt

Override settings from the configuration file using command-line arguments. This example enables Conventional Commits and sets a maximum header length.

```bash
GIT_SUMI_CONVENTIONAL=true git sumi --max-header-length 100 "feat: message"
```

--------------------------------

### Enforce Conventional Commits with Git Sumi

Source: https://context7.com/welpo/git-sumi/llms.txt

Validates commit messages against the Conventional Commits specification. Includes examples for valid commits, breaking changes, and invalid messages.

```bash
# Valid conventional commit
git sumi --conventional "feat(api): add user authentication endpoint"
# ✅ All 1 checks passed.

# Valid breaking change
git sumi --conventional "feat(api)!: change response format"
# ✅ All 1 checks passed.

# Invalid - missing type
git sumi --conventional "add user authentication"
# ❗ Commit must follow Conventional Commits format: <type>[optional scope]: <description>

# With type restrictions
git sumi --conventional --types-allowed "feat,fix,docs" "chore: update deps"
# ❗ Invalid type 'chore'. Allowed types: feat, fix, docs
```

--------------------------------

### Conditional Commit-Msg Hook for Main Branch (Bash)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/faq.md

This bash script is an example of a `.git/hooks/commit-msg` hook that conditionally runs `git sumi` only when commits are made to the 'main' branch. It includes logic to determine the current branch and exit early if not on 'main'.

```bash
#!/usr/bin/env bash

# Commit-msg hook generated by git-sumi.
# For more information and documentation, visit: https://sumi.rs

set -e  # Exit on any error. 

get_current_branch() {
    # Check if HEAD exists (i.e., if there are any commits).
    if git rev-parse --verify HEAD >/dev/null 2>&1; then
        git rev-parse --abbrev-ref HEAD
    else
        echo "main"  # Assume 'main' for initial commit.
    fi
}

current_branch=$(get_current_branch)

# Check if the current branch is 'main'.
if [ "$current_branch" != "main" ]; then
    exit 0  # Exit successfully without running git-sumi.
fi

# Check if git-sumi is installed.
if ! command -v git-sumi &> /dev/null
then
    echo "git-sumi is not installed. Please install it. See https://sumi.rs for instructions."
    echo "Alternatively, edit or remove the commit-msg hook in .git/hooks/commit-msg."
    exit 1
fi

# Run git-sumi on the commit message if on the 'main' branch.
git sumi -- "$(cat $1)"  # Exit with error if linting fails.

```

--------------------------------

### Validate Gitmoji Usage in Commit Messages

Source: https://context7.com/welpo/git-sumi/llms.txt

These examples demonstrate how git-sumi validates the presence and count of Gitmoji in commit messages. It checks for exactly one valid Gitmoji, either in standard format or shortcode.

```bash
# Valid Gitmoji usage
git sumi --gitmoji "✨ feat: add new feature"
git sumi --gitmoji "🐛 fix: resolve crash on startup"
git sumi --gitmoji ":sparkles: feat: add feature"  # Shortcode format

# Invalid - no Gitmoji
git sumi --gitmoji "feat: add new feature"
# ❗ Expected 1 gitmoji, found 0

# Invalid - multiple Gitmoji
git sumi --gitmoji "✨🐛 fix: multiple emojis"
# ❗ Expected 1 gitmoji, found 2

# Invalid - non-Gitmoji emoji
git sumi --gitmoji "😀 feat: invalid emoji"
# ❗ Invalid gitmoji: 😀. See https://gitmoji.dev for valid options
```

--------------------------------

### Git Sumi JSON Output Format

Source: https://context7.com/welpo/git-sumi/llms.txt

Parses commit data and outputs it in JSON format, suitable for programmatic processing. Includes an example of using `jq` to extract specific commit data.

```bash
# Parse and output as JSON
git sumi --display --format json "🐛 fix(auth)!: resolve token refresh issue

Fixes bug introduced in ce6df36 where the authentication token would
not refresh properly during a session, causing unexpected logouts.

Co-authored-by: John Doe <johndoe@example.com>"

# Output:
# {
#   "gitmoji": "🐛",
#   "commit_type": "fix",
#   "scope": "auth",
#   "description": "resolve token refresh issue",
#   "body": "Fixes bug introduced in ce6df36 where the authentication token would\nnot refresh properly during a session, causing unexpected logouts.",
#   "footers": ["Co-authored-by:John Doe <johndoe@example.com>"]
#   "is_breaking": true,
#   "breaking_description": "resolve token refresh issue",
#   "references": ["ce6df36"]
# }

# Use in scripts with jq
COMMIT_TYPE=$(git sumi -d -f json "feat: new feature" 2>/dev/null | jq -r '.commit_type')
echo "Commit type: $COMMIT_TYPE"  # Output: Commit type: feat
```

--------------------------------

### Initialize Git-Sumi Configuration

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

Generates a default `sumi.toml` configuration file in the current repository's root directory. This command is useful for quickly setting up a basic configuration.

```bash
git sumi --init config
```

--------------------------------

### Initialize git-sumi Configuration and Hooks

Source: https://context7.com/welpo/git-sumi/llms.txt

Sets up configuration files and Git hooks for automatic commit message validation. Supports creating default configuration, specific components like commit-msg or prepare-commit-msg hooks, and generating shell completions.

```bash
# Create default sumi.toml configuration
git sumi --init
# Creates: sumi.toml with all available options documented

# Initialize specific components
git sumi --init config        # Create configuration file only
git sumi --init commit-msg    # Create commit-msg hook
git sumi --init prepare-commit-msg  # Create prepare-commit-msg hook
git sumi --init hooks         # Create both hooks

# Generate shell completions
git sumi --generate-shell-completion bash >> ~/.bashrc
git sumi --generate-shell-completion zsh >> ~/.zshrc
git sumi --generate-shell-completion fish > ~/.config/fish/completions/git-sumi.fish
```

--------------------------------

### Initialize Git-Sumi prepare-commit-msg Hook

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/integration.md

Set up the prepare-commit-msg Git hook to display enabled Git-Sumi rules within the commit message template when you run 'git commit'. This helps users adhere to the defined commit message conventions.

```bash
git sumi --init prepare-commit-msg
```

--------------------------------

### git-sumi Environment Variables for Configuration

Source: https://context7.com/welpo/git-sumi/llms.txt

Demonstrates how to set git-sumi configuration options using environment variables, which is useful for CI/CD integration. All TOML configuration options can be mirrored by environment variables prefixed with GIT_SUMI_.

```bash
# Enable rules via environment variables
export GIT_SUMI_CONVENTIONAL=true
export GIT_SUMI_IMPERATIVE=true
export GIT_SUMI_MAX_HEADER_LENGTH=50
export GIT_SUMI_TYPES_ALLOWED="feat,fix,docs"
export GIT_SUMI_SCOPES_ALLOWED="api,ui"
export GIT_SUMI_GITMOJI=true
export GIT_SUMI_WHITESPACE=true
export GIT_SUMI_NO_PERIOD=true
export GIT_SUMI_DESCRIPTION_CASE=lower
export GIT_SUMI_HEADER_PATTERN='^JIRA-\d+:'
```

--------------------------------

### Configure Git-Sumi Pre-commit with Custom Arguments

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/integration.md

Customize the Git-Sumi pre-commit hook by overriding the 'args' to specify a custom configuration file or additional arguments. Remember to include '--file' as the last argument when overriding.

```yaml
repos:
  - repo: https://github.com/welpo/git-sumi
    rev: v0.2.0  # check latest version: https://github.com/welpo/git-sumi/tags
    hooks:
      - id: git-sumi
        args: [--config, .config/sumi.toml, --file]
```

--------------------------------

### Run Git Sumi with Environment Configuration

Source: https://context7.com/welpo/git-sumi/llms.txt

Execute git-sumi with a commit message. The tool will use environment variables for configuration if a config file is not explicitly provided.

```bash
git sumi "feat(api): add user endpoint"
```

--------------------------------

### Generate Shell Completion Script (Bash)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/faq.md

This bash command shows how to generate a shell completion script for `git sumi` for the bash shell. The output can be saved and sourced to enable tab completion.

```bash
git sumi --generate-shell-completion bash
```

--------------------------------

### Rust: Programmatic Commit Message Linting with Git-Sumi

Source: https://context7.com/welpo/git-sumi/llms.txt

This Rust code demonstrates how to use the git-sumi library to programmatically lint commit messages. It shows creating a configuration with various rules and then using `run_lint` for single messages and `run_lint_on_each_line` for multiple messages.

```rust
use git_sumi::lint::{run_lint, run_lint_on_each_line};
use git_sumi::config::Config;
use git_sumi::config::DescriptionCase;
use git_sumi::config::ParsedCommitDisplayFormat;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration with desired rules
    let config = Config {
        conventional: true,
        imperative: true,
        max_header_length: 72,
        max_body_length: 100,
        whitespace: true,
        no_period: true,
        gitmoji: false,
        types_allowed: vec!["feat".into(), "fix".into(), "docs".into()],
        scopes_allowed: vec![],
        description_case: DescriptionCase::Lower,
        header_pattern: String::new(),
        strip_header_pattern: false,
        display: false,
        quiet: true,
        split_lines: false,
        format: ParsedCommitDisplayFormat::Cli,
    };

    // Lint a single commit message
    let commit_msg = "feat(api): add user authentication endpoint";
    match run_lint(commit_msg, &config) {
        Ok(parsed_commit) => {
            println!("Valid commit!");
            println!("Type: {:?}", parsed_commit.commit_type);
            println!("Scope: {:?}", parsed_commit.scope);
            println!("Description: {}", parsed_commit.description);
        }
        Err(e) => {
            eprintln!("Linting failed: {}", e);
        }
    }

    // Lint multiple commits (one per line)
    let multi_line = "feat: first feature\nfix: bug fix\ndocs: update readme";
    let config_split = Config { split_lines: true, ..config };
    match run_lint_on_each_line(multi_line, &config_split) {
        Ok(parsed_commits) => {
            for pc in parsed_commits {
                println!("Parsed: {:?} - {}", pc.commit_type, pc.description);
            }
        }
        Err(e) => eprintln!("Errors found: {}", e),
    }

    Ok(())
}

```

--------------------------------

### Specify Configuration File for Git-Sumi

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

Allows the user to specify a custom TOML configuration file for git-sumi. This is useful when managing multiple configurations or when the default location is not suitable. The `--config` or `-c` flag is used for this purpose.

```bash
git sumi --config /path/to/sumi.toml
```

```bash
git sumi -c /path/to/sumi.toml
```

--------------------------------

### Force Commit with Git Sumi

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/faq.md

This command demonstrates how to bypass linting errors and force a commit using the `git sumi --force` command. It takes the commit message as an argument.

```bash
git sumi --force 'wip'
```

--------------------------------

### Display Commit Message in Various Formats (Git Sumi)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

This functionality allows users to specify the output format for parsed commit messages. Supported formats include 'cli', 'table', 'json', and 'toml'. Enabling this option also automatically sets the display to true. Configuration can be done via a TOML file, command-line arguments, or environment variables.

```toml
format = "json"
```

```bash
git sumi --format json
```

```bash
export GIT_SUMI_FORMAT=json
```

```txt
🐛 fix(auth)!: resolve token refresh issue

Fixes bug introduced in ce6df36 where the authentication token would
not refresh properly during a session, causing unexpected logouts.

Co-authored-by: John Doe <johndoe@example.com>
```

```txt
| Key                  | Value                                                                |
|----------------------|----------------------------------------------------------------------|
| Gitmoji              | 🐛                                                                   |
| Commit type          | fix                                                                  |
| Scope                | auth                                                                 |
| Description          | resolve token refresh issue                                          |
| Body                 | Fixes bug introduced in ce6df36 where the authentication token would |
|                      | not refresh properly during a session, causing unexpected logouts.   |
| Footers              | Co-authored-by:John Doe <johndoe@example.com>                        |
| Is breaking          | true                                                                 |
| Breaking description | resolve token refresh issue                                          |
| References           | ce6df36                                                              |
```

```txt
┌──────────────────────┬──────────────────────────────────────────────────────────────────────┐
│ Gitmoji              │ 🐛                                                                   │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Commit type          │ fix                                                                  │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Scope                │ auth                                                                 │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Description          │ resolve token refresh issue                                          │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Body                 │ Fixes bug introduced in ce6df36 where the authentication token would │
│                      │ not refresh properly during a session, causing unexpected logouts.   │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Footers              │ Co-authored-by:John Doe <johndoe@example.com>                        │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Is breaking          │ true                                                                 │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ Breaking description │ resolve token refresh issue                                          │
├──────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ References           │ ce6df36                                                              │
└──────────────────────┴──────────────────────────────────────────────────────────────────────┘
```

```json
{
  "body": "Fixes bug introduced in ce6df36 where the authentication token would\nnot refresh properly during a session, causing unexpected logouts.",
  "breaking_description": "resolve token refresh issue",
  "commit_type": "fix",
  "description": "resolve token refresh issue",
  "footers": [
    "Co-authored-by:John Doe <johndoe@example.com>"
  ],
  "gitmoji": "🐛",
  "is_breaking": true,
  "references": [
    "ce6df36"
  ],
  "scope": "auth"
}
```

```toml
gitmoji = "🐛"
commit_type = "fix"
scope = "auth"
description = "resolve token refresh issue"
body = """
Fixes bug introduced in ce6df36 where the authentication token would
not refresh properly during a session, causing unexpected logouts."""

```

--------------------------------

### Configure Git Sumi with pre-commit

Source: https://context7.com/welpo/git-sumi/llms.txt

Integrates git-sumi with the pre-commit framework by adding it to the .pre-commit-config.yaml file. This ensures consistent commit message enforcement across the team.

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/welpo/git-sumi
    rev: v0.2.0  # Use latest version from https://github.com/welpo/git-sumi/tags
    hooks:
      - id: git-sumi

# With custom configuration file
repos:
  - repo: https://github.com/welpo/git-sumi
    rev: v0.2.0
    hooks:
      - id: git-sumi
        args: [--config, .config/sumi.toml, --file]

# Install and test the hook
pre-commit install --hook-type commit-msg
git commit -m "feat: test pre-commit integration"
```

--------------------------------

### Integrate Git-Sumi with Pre-commit

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/integration.md

Add the Git-Sumi hook to your pre-commit configuration file (.pre-commit-config.yaml) to automatically lint commit messages. Ensure you specify the correct repository and revision.

```yaml
repos:
  - repo: https://github.com/welpo/git-sumi
    rev: v0.2.0  # check latest version: https://github.com/welpo/git-sumi/tags
    hooks:
      - id: git-sumi
```

--------------------------------

### Configure Git Sumi with Custom Config File

Source: https://context7.com/welpo/git-sumi/llms.txt

Set the GIT_SUMI_CONFIG environment variable to specify a custom configuration file for git-sumi. This allows for flexible configuration management.

```bash
export GIT_SUMI_CONFIG=/path/to/custom-sumi.toml
```

--------------------------------

### Use Default Git-Sumi Configuration

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

Disables the use of any custom configuration file and forces git-sumi to use its built-in default settings. This is achieved by passing the special value 'none' to the `--config` flag.

```bash
git sumi --config none
```

--------------------------------

### Custom Header Pattern Configuration (TOML)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/faq.md

This TOML snippet shows how to define a custom regular expression pattern for commit headers. This is useful for enforcing specific formats, such as including a JIRA issue key.

```toml
header_pattern = '^JIRA-\d+: +'
```

--------------------------------

### Configure Git-Sumi to Process Each Line as a Commit

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

The `split_lines` option processes each non-empty line of a commit message as an individual commit. This can be enabled in `sumi.toml` or by using the `--split-lines` or `-s` command-line flags.

```toml
split_lines = true
```

--------------------------------

### Commit with Linting using git-sumi CLI

Source: https://context7.com/welpo/git-sumi/llms.txt

Validates the commit message and creates a Git commit in one step. The `--force` flag can be used to commit even if linting fails.

```bash
# Lint and commit if validation passes
git sumi --commit "feat: add user authentication"
# Output:
# 💬 Input: "feat: add user authentication"
# ✅ All 3 checks passed.
# 🚀 Running git commit…
# 🎉 Commit successful!

# Force commit even if linting fails
git sumi --commit --force "WIP: work in progress"
# Output:
# 🚨 Forced commit with lint errors. Force flag is set, committing despite errors.
```

--------------------------------

### Configure Git-Sumi to Display Parsed Commit Messages

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

Enables the display of the parsed commit message after linting. This setting, `display`, can be configured in `sumi.toml` or activated using the `--display` or `-d` command-line options.

```toml
display = true
```

--------------------------------

### Conventional Commit Message Structure with Gitmoji

Source: https://github.com/welpo/git-sumi/blob/main/CONTRIBUTING.md

Demonstrates the standard format for commit messages using Gitmoji, including gitmoji, type, scope, and description. This format aids in quickly understanding the purpose of code changes.

```text
✨ feat(rules): add custom header pattern
^  ^--^^-----^  ^-----------------------
|  |   |        |
|  |   |        +-> Description in imperative and lowercase.
|  |   |
|  |   +-> The scope of the change.
|  |
|  +-------> Type: see above for the list we use.
|
+----------> A valid gitmoji.
```

--------------------------------

### Enforce Custom Header Patterns with Git-Sumi

Source: https://context7.com/welpo/git-sumi/llms.txt

This section shows how to use git-sumi to enforce custom regular expression patterns for commit headers, such as requiring a JIRA ticket prefix. It also demonstrates stripping the pattern before other validations.

```bash
# Require JIRA ticket prefix
git sumi --header-pattern '^JIRA-\d+:' "JIRA-123: fix authentication bug"
# ✅ All 1 checks passed.

# Pattern mismatch
git sumi --header-pattern '^JIRA-\d+:' "fix authentication bug"
# ❗ Header doesn't match required pattern: ^JIRA-\d+:

# Strip pattern before other validations
git sumi --header-pattern '^JIRA-\d+ ' --strip-header-pattern \
         --imperative "JIRA-123 fix the bug"
# ✅ Validates "fix the bug" for imperative mood (stripping "JIRA-123 ")

# Combine with Gitmoji position enforcement
git sumi --gitmoji --header-pattern '^(:w+:|[p{Emoji_Presentation}])' \
         "✨ feat: emoji must be first"
# ✅ All 2 checks passed.
```

--------------------------------

### Analyze Commit Header Lengths (Bash)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

Analyzes the lengths of commit headers in the last 100 commit messages to help determine an appropriate maximum header length. It outputs the mean, minimum, maximum, 80th percentile, and standard deviation of header lengths.

```bash
git log -n 100 --pretty=%s | awk '{ print length }' | sort -n | awk 'BEGIN {min = 999999; max = 0; count=0; sum=0; sumsq=0} {if ($1<min) min=$1; if ($1>max) max=$1; sum+=$1; sumsq+=$1*$1; count++} END {print "Mean: " sum/count; print "Min: " min; print "Max: " max; print "80th Percentile: " int(count*0.8 - 1); print "Standard Deviation: " sqrt(sumsq/count - (sum/count)^2)}'
```

--------------------------------

### Git Sumi TOML Output Format

Source: https://context7.com/welpo/git-sumi/llms.txt

Parses commit data and outputs it in TOML format. This format is useful for configurations or when TOML is the preferred data serialization format.

```bash
git sumi --display --format toml "feat(ui): add dark mode toggle"

# Output:
# commit_type = "feat"
# scope = "ui"
# description = "add dark mode toggle"
# is_breaking = false
```

--------------------------------

### Basic Commit Message Linting with git-sumi CLI

Source: https://context7.com/welpo/git-sumi/llms.txt

Validates a commit message against configured rules and displays detailed errors if validation fails. Supports direct input, stdin, file input, and CLI flags for specific rules. Can also display parsed commit structure and process multi-line messages.

```bash
# Lint a commit message directly
git sumi "fix: resolve authentication bug"

# Lint from stdin (useful in scripts)
echo "feat: add user login" | git sumi

# Lint from a file
git sumi --file .git/COMMIT_EDITMSG

# Lint with specific rules via CLI flags
git sumi --conventional --imperative --max-header-length 50 "feat: add new feature"

# Lint and display parsed commit structure
git sumi --display --format json "feat(auth): add OAuth support"
# Output:
# {
#   "commit_type": "feat",
#   "scope": "auth",
#   "description": "add OAuth support",
#   "is_breaking": false
# }

# Lint multiple lines as separate commits
git sumi --split-lines "feat: first feature
fix: bug fix
docs: update readme"

# Suppress progress messages
git sumi --quiet "fix: silent validation"
```

--------------------------------

### Tim Pope's Git Commit Message Configuration (TOML)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/examples.md

This TOML configuration follows Tim Pope's best practices for well-formed Git commit messages. It includes settings for splitting lines, description casing, imperative mood, and limits for header and body line lengths. A value of 0 for length limits disables the respective rule.

```toml
# Processes each non-empty line as an individual commit.
split_lines = false

# Rule: Description must start with the specified case.
# Options: 'any', 'lower', 'upper'.
description_case = "upper"

# Rule: Use the imperative mood in the description.
# Example: 'Fix bug' instead of 'Fixed bug'.
imperative = true

# Rule: Header length limit.
# A value of 0 disables the rule.
max_header_length = 50

# Rule: Body line length limit.
# A value of 0 disables the rule.
max_body_length = 72
```

--------------------------------

### Configure Git-Sumi to Suppress Progress Messages

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/configuration.md

This configuration option, `quiet`, suppresses progress messages during git-sumi operations. It can be set in the `sumi.toml` file or via the command line using `--quiet` or `-q`.

```toml
quiet = true
```

--------------------------------

### Linus Torvalds' Git Commit Message Configuration (TOML)

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/examples.md

This TOML configuration reflects Linus Torvalds' advice on writing good Git commit messages. It enforces the use of the imperative mood, sets a body line length limit, and ensures proper whitespace handling. The body line length limit is set to 74 characters.

```toml
# Rule: Use the imperative mood in the description.
# Example: 'Fix bug' instead of 'Fixed bug'.
imperative = true

# Rule: Body line length limit.
# A value of 0 disables the rule.
max_body_length = 74

# Rule: No leading, trailing, or consecutive spaces.
whitespace = true
```

--------------------------------

### GitHub Actions Workflow for PR Title Linting

Source: https://context7.com/welpo/git-sumi/llms.txt

A GitHub Actions workflow that uses the git-sumi-action to validate pull request titles. It runs on pull request events and requires the GITHUB_TOKEN secret.

```yaml
# .github/workflows/lint-pr-title.yml
name: Lint PR Title

on:
  pull_request:
    types: [opened, edited, synchronize, ready_for_review]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  pull-requests: read

jobs:
  lint:
    name: Validate PR Title
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint PR title with git-sumi
        uses: welpo/git-sumi-action@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Ensure sumi.toml exists in repository root with your rules
# The action will validate PR title against those rules
```

--------------------------------

### Enforce Allowed Scopes in Commit Messages

Source: https://context7.com/welpo/git-sumi/llms.txt

This command uses git-sumi to enforce that commit messages adhere to a predefined list of allowed scopes. If a commit message uses a scope not in the allowed list, it will fail validation.

```bash
git sumi --conventional --scopes-allowed "api,ui" "feat(db): add migration"
# ❗ Invalid scope 'db'. Allowed scopes: api, ui
```

--------------------------------

### Lint Pull Request Titles with GitHub Actions

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/integration.md

Integrate Git-Sumi into your GitHub Actions workflow to lint pull request titles, which are used as merge commit messages for squash-and-merge pull requests. This workflow uses the git-sumi-action to validate the title against your sumi.toml configuration.

```yaml
name: Lint pull request title

on:
  pull_request:
    types: 
      - opened
      - edited
      - synchronize
      - ready_for_review

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  pull-requests: read

jobs:
  main:
    name: Run git-sumi
    runs-on: ubuntu-latest
    steps:
      - uses: welpo/git-sumi-action@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Configure Header Pattern Regex in TOML

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

Enforces a specified regex pattern for commit message headers. This rule allows flexible validation to adhere to specific formatting guidelines, such as including JIRA issue keys. Ensure proper escaping of regex special characters.

```toml
header_pattern = '^JIRA-\d+:'

```

```toml
# Double backslashes with double quotes.
header_pattern = "^JIRA-\\d+"

```

```toml
# Literal string (single quotes).
header_pattern = '^JIRA-\d+:'

```

--------------------------------

### Enable Stripping Header Pattern in TOML

Source: https://github.com/welpo/git-sumi/blob/main/website/docs/rules.md

When enabled, this configuration removes the matched header pattern before applying content validation rules. This is useful for applying content checks to the actual commit description, excluding prefixes like JIRA ticket numbers. The default value is `false`.

```toml
strip_header_pattern = true

```
Tokens:
Raw