forgejo-commit-path-rules

A tool to enforce consistency between commit messages and file changes in your repository.

Overview

This tool validates that commits follow specific patterns and include changes to required files or directories. It's particularly useful for ensuring that:

1. Feature commits include documentation updates
2. Documentation commits only modify documentation files
3. Specific types of changes are properly reflected in the codebase
4. Git commands execute reliably with proper timeout handling
5. Git commit SHAs are properly formatted and validated
6. Error messages provide detailed diagnostic information
7. Rule violations include helpful suggestions for fixing issues
8. Supports any or all matching strategies for file paths

Table of Contents

• Installation
• Usage
  • Command Line
  • Forgejo Actions
  • GitHub/GitLab CI (untested)
• Configuration
  • Rule Format
  • Templates
• Features
  • Rule Violation Suggestions
  • Regex Pattern Validation
  • Verbose Logging
  • Configuration Validation
  • Error Diagnostics
• Development
• License
• Contributing

Installation

Using Cargo

cargo install forgejo-commit-path-rules

Requirements

• Rust 2024 edition or later (for building from source)

Usage

Command Line

forgejo-commit-path-rules --workspace /path/to/your/repo --no-colour

Options:

• --workspace: Root directory of the project to be scanned (optional, defaults to current directory)
• --verbose: Enable verbose logging for detailed output
• --no-color: Disabled colours in logs

If no --workspace argument is provided, the tool will use the current working directory as the workspace.

Forgejo Actions

name: Validate Commit Path Rules

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ next ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Run forgejo-commit-path-rules
        uses: kemitix/commit-path-rules@v0.1.4
        with:
          args: --verbose # Enable verbose logging in actions (optional)

If the action is invoked for other events than push or pull-request, then it will return a pass result.

GitHub/GitLab CI (untested)

You should be able to use this with GitHub and/or GitLab, although it hasn't been tested.

forgejo-commit-path-rules looks for the following environment variables:

• GITHUB_WORKSPACE: The absolute path to the repository workspace directory
• GITHUB_EVENT_NAME: The name of the event that triggered the workflow (e.g., "push", "pull_request")
• GITHUB_BASE_REF: The target branch of a pull request (used for pull request events)
• GITHUB_HEAD_REF: The source branch of a pull request (used for pull request events)
• GITHUB_SHA: The sha of the commit being pushed (used for puhs events)

validate_commits:
  stage: test
  script:
    - cargo install forgejo-commit-path-rules
    - forgejo-commit-path-rules

Configuration

Create a .forgejo/commit-path-rules.toml file in your repository with rules:

# Use built-in templates
use_templates = ["custom-docs", "docs", "feature", "tests"]

# Define custom templates
[templates]
# All documentation commits must update the custom docs
custom_docs = { path = "custom-docs/", commit = "^docs:" }

[[rules]]
# All docs commits must include an update to the README
commit = "^docs:"
path = "README.md"

[[rules]]
# all features and docs commits must update the documentation
commit = "^(feat|docs):"
path = "docs/"

[[rules]]
# all fixes must only modify source files
commit = "^fix:"
path = "src/"
matching = "all"
suggestion = "All changes must be in src/"

Rule Format

Each rule consists of:

• commit: A regex pattern matching commit messages that trigger this rule
• path: A regex pattern matching file paths that should be modified
• suggestion: (Optional) Custom suggestion message for rule violations
• matching : (Optional) Whether 'any' file (1 or more) can match, or 'all' files must match (default: any)

When a commit matches the commit pattern, at least one file matching the path pattern must be modified.

Templates

The tool provides built-in templates for common patterns:

• docs: Ensures documentation commits only modify documentation files
• feature: Ensures feature commits include both code and documentation changes
• tests: Ensures test commits only modify test files
• fixes: Ensures fix commits also update test files

You can use these templates by adding them to the use_templates array in your configuration file.

You can also define custom templates in the templates section of your configuration file.

Features

Rule Violation Suggestions

The tool provides helpful suggestions when rules are violated:

• Offers specific guidance on how to fix rule violations
• Explains which files should be modified to satisfy the rule
• Provides context about why the rule exists
• Example:

[WARN] Rule violated: ^docs:: README.md
[INFO]   Commits matched pattern: ^docs:
[INFO]   But paths didn't match pattern: README.md
[INFO]   Suggestion: Documentation commits that match '^docs:' should include changes to paths matching 'README.md'. Please update the documentation accordingly.

Regex Pattern Validation

The tool validates regex patterns in configuration files:

• Provides clear error messages for invalid regex patterns
• Includes the problematic pattern in error messages
• Adds context about which part of the rule (path or commit) has an issue:

  Error: Invalid regex pattern for path: '[unclosed'
  Error: Invalid regex pattern for commit: '(unclosed'
  

Verbose Logging

The tool supports verbose logging for detailed debugging:

• Enable with the --verbose flag (-v)
• Shows additional diagnostic information during execution
• Logs configuration loading and validation steps
• Provides details about Git command execution
• Shows information about template expansion
• Skips verbose messages when verbose mode is disabled

Configuration Validation

The tool provides comprehensive configuration validation:

• Validates all configuration settings before execution
• Provides clear error messages for invalid configurations
• Checks for proper formatting of regex patterns
• Ensures template references exist and are properly defined
• Prevents common configuration mistakes with helpful suggestions

Error Diagnostics

The tool provides robust error handling with comprehensive diagnostics:

• Line number references in error messages for easier troubleshooting
• Detailed capture group validation for file pattern matching
• Informative error messages for empty Git output
• Includes Git stderr output in error messages when available
• Contextual error messages for failed regex captures and pattern matching

Development

Building from source

git clone https://codeberg.org/kemitix/forgejo-commit-path-rules.git
cd forgejo-commit-path-rules
cargo build --release

Running tests

cargo test

Configuration Options

• workspace: This is automatically detected but can be overridden as a parameter.
• verbose: Enable verbose logging to get detailed information about the validation process.

• no-colour: Disable colour highlighting in log output.

Best Practices

1. Start Simple: Begin with a few essential rules and expand as needed
2. Be Specific: Use precise regex patterns to avoid false positives
3. Document Rules: Add comments in your TOML file explaining each rule's purpose
4. Test Locally: Run the tool locally before pushing to avoid CI failures
5. Provide Examples: Document example commit messages that satisfy your rules

Troubleshooting

Common Issues

1. "Configuration file not found": Ensure the config file is at .forgejo/commit-path-rules.toml
2. "Failed to parse config file": Check your TOML syntax
3. "Invalid rule: regex parse error": Fix the regex pattern in your rule

License

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

Contributing

Contributions are welcome via the repository at https://codeberg.org/kemitix/forgejo-commit-path-rules