git-commit-guard 0.15.1__tar.gz → 0.17.0__tar.gz

git_commit_guard-0.17.0/.github/workflows/coverage-baseline.yml

@@ -0,0 +1,33 @@
+---
+name: Coverage Baseline
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        # yamllint disable-line rule:line-length
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # ratchet:actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Install uv
+        # yamllint disable-line rule:line-length
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # ratchet:astral-sh/setup-uv@v7
+      - name: Cache NLTK data
+        # yamllint disable-line rule:line-length
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae  # ratchet:actions/cache@v5
+        with:
+          path: ~/nltk_data
+          key: nltk-averaged-perceptron-tagger-punkt
+      - name: Run tests with coverage
+        run: uv run --dev pytest tests/ --cov=git_commit_guard --cov-report=xml
+      - name: Upload coverage baseline
+        # yamllint disable-line rule:line-length
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # ratchet:actions/upload-artifact@v4
+        with:
+          name: main-coverage
+          path: coverage.xml

git_commit_guard-0.17.0/.github/workflows/coverage-comment.yml

@@ -0,0 +1,97 @@
+---
+name: Coverage Comment
+on:  # yamllint disable-line rule:truthy  # zizmor: ignore[dangerous-triggers]
+  workflow_run:
+    workflows: [Test]
+    types: [completed]
+permissions:
+  actions: read
+  pull-requests: write
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    steps:
+      - name: Download artifact
+        # yamllint disable-line rule:line-length
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # ratchet:actions/download-artifact@v4
+        with:
+          run-id: ${{ github.event.workflow_run.id }}
+          name: pr
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Read PR number
+        id: pr
+        run: |
+          pr_number=$(cat NR)
+          if ! [[ "$pr_number" =~ ^[0-9]+$ ]]; then
+            echo "Invalid PR number: $pr_number" >&2
+            exit 1
+          fi
+          echo "number=$pr_number" >> "$GITHUB_OUTPUT"
+      - name: Find baseline run
+        id: baseline
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python3 - <<'PYEOF'
+          import json, os, urllib.request
+          token = os.environ['GITHUB_TOKEN']
+          repo = os.environ['GITHUB_REPOSITORY']
+          url = (
+              f'https://api.github.com/repos/{repo}/actions/workflows'
+              f'/coverage-baseline.yml/runs'
+              f'?branch=main&status=success&per_page=1'
+          )
+          req = urllib.request.Request(url, headers={
+              'Authorization': f'Bearer {token}',
+              'Accept': 'application/vnd.github+json',
+          })
+          with urllib.request.urlopen(req) as r:
+              runs = json.loads(r.read()).get('workflow_runs', [])
+          run_id = str(runs[0]['id']) if runs else ''
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write(f'run-id={run_id}\n')
+          PYEOF
+      - name: Download baseline coverage
+        if: steps.baseline.outputs.run-id != ''
+        # yamllint disable-line rule:line-length
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # ratchet:actions/download-artifact@v4
+        with:
+          run-id: ${{ steps.baseline.outputs.run-id }}
+          name: main-coverage
+          path: main/
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Compute coverage delta
+        id: delta
+        if: steps.baseline.outputs.run-id != ''
+        run: |
+          python3 - <<'PYEOF'
+          import xml.etree.ElementTree as ET
+          import os, sys
+          try:
+              pr_rate = ET.parse('coverage.xml').getroot().get('line-rate')
+              main_xml = ET.parse('main/coverage.xml').getroot()
+              main_rate = main_xml.get('line-rate')
+              pr = float(pr_rate) * 100
+              main = float(main_rate) * 100
+              delta = pr - main
+              if not (-100 <= delta <= 100):
+                  raise ValueError(f"delta out of range: {delta}")
+              sign = '+' if delta >= 0 else ''
+              title = f"Coverage Report (Δ {sign}{delta:.1f}%)"
+          except Exception as e:
+              print(f"Warning: could not compute delta: {e}", file=sys.stderr)
+              title = "Coverage Report"
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write(f"title={title}\n")
+          PYEOF
+      - name: Post coverage comment
+        # yamllint disable-line rule:line-length
+        uses: MishaKav/pytest-coverage-comment@dd5b80bde6d16941f336518e92929e89069d8451  # ratchet:MishaKav/pytest-coverage-comment@v1.7.2
+        with:
+          pytest-xml-coverage-path: coverage.xml
+          unique-id-for-comment: coverage
+          issue-number: ${{ steps.pr.outputs.number }}
+          title: ${{ steps.delta.outputs.title || 'Coverage Report' }}

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/.github/workflows/lint-commits.yml

@@ -22,7 +22,7 @@ jobs:
           key: nltk-averaged-perceptron-tagger-punkt
       - name: Lint commits
         # yamllint disable-line rule:line-length
-        uses: benner/commit-guard@c3ca496e477d64051d06fdb3aac44d8ffec7e852  # v0.14.1
+        uses: benner/commit-guard@064132b8b0cf5ec26083de7193f4e78d37a615d4  # v0.15.1
         with:
           range: origin/${{ github.base_ref }}..HEAD
           disable: signature

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Generate release notes
         id: git-cliff
         # yamllint disable-line rule:line-length
-        uses: orhun/git-cliff-action@c93ef52f3d0ddcdcc9bd5447d98d458a11cd4f72  # v4.7.1
+        uses: orhun/git-cliff-action@f50e11560dce63f7c33227798f90b924471a88b5  # ratchet:orhun/git-cliff-action@v4.8.0
         with:
           args: --current
       - name: Create GitHub Release

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/.github/workflows/test.yml

@@ -24,4 +24,16 @@ jobs:
       - name: Run tests with coverage
         run: |-
           uv run --dev pytest \
-            tests/ --cov=git_commit_guard --cov-report=term-missing
+            tests/ --cov=git_commit_guard --cov-report=term-missing \
+            --cov-report=xml
+      - name: Save coverage artifact
+        run: |
+          mkdir -p ./pr
+          echo ${{ github.event.number }} > ./pr/NR
+          cp coverage.xml ./pr/
+      - name: Upload PR artifact
+        # yamllint disable-line rule:line-length
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # ratchet:actions/upload-artifact@v4
+        with:
+          name: pr
+          path: pr/

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-commit-guard
-Version: 0.15.1
+Version: 0.17.0
 Summary: Opinionated conventional commit message linter with imperative mood detection
 Project-URL: Homepage, https://github.com/benner/commit-guard
 Project-URL: Repository, https://github.com/benner/commit-guard
@@ -96,7 +96,7 @@ Available checks:
 * `subject` - Format matches `type(scope): description`, valid type,
     lowercase start, no trailing period, max 72 chars
 * `imperative` - First word is an imperative verb (for example `add` not `added`)
-* `body` - Body is present after a blank line
+* `body` - Blank line separates subject from body, and body is non-empty
 * `signed-off` - `Signed-off-by:` trailer exists
 * `signature` - Verify GPG or SSH signature
 
@@ -116,6 +116,41 @@ By default there is no minimum description length. Enforce one with
 commit-guard --min-description-length 10
 ```
 
+### Subject format
+
+By default the description must start with a lowercase letter. To allow
+uppercase descriptions:
+
+```bash
+commit-guard --no-require-lowercase
+```
+
+In `.commit-guard.toml`:
+
+```toml
+require-lowercase = false
+```
+
+By default trailing `.` is forbidden. To change the set of forbidden trailing
+characters (any character is valid, including space):
+
+```bash
+commit-guard --no-trailing-chars ".,"
+commit-guard --no-trailing-chars ".,!"
+```
+
+In `.commit-guard.toml`:
+
+```toml
+no-trailing-chars = [".", "!"]
+```
+
+Pass an empty list to disable the check entirely:
+
+```toml
+no-trailing-chars = []
+```
+
 ### Type validation
 
 By default the standard conventional commit types are accepted. Use `--types`
@@ -170,7 +205,8 @@ independently of `--enable`/`--disable`.
 
 Place `.commit-guard.toml` in your project root (or any parent directory) to
 set defaults for `enable`, `disable`, `scopes`, `require-scope`, `types`,
-`max-subject-length`, `min-description-length`, and `require-trailers`.
+`max-subject-length`, `min-description-length`, `require-lowercase`,
+`no-trailing-chars`, and `require-trailers`.
 commit-guard searches upward from the working directory and uses the first
 file found.
 
@@ -182,6 +218,8 @@ require-scope = true
 types = ["feat", "fix", "chore", "wip"]
 max-subject-length = 100
 min-description-length = 10
+require-lowercase = false
+no-trailing-chars = [".", "!"]
 require-trailers = ["Closes", "Reviewed-by"]
 ```
 
@@ -191,7 +229,8 @@ enable = ["subject", "imperative"]
 ```
 
 CLI flags (`--enable`, `--disable`, `--scopes`, `--require-scope`, `--types`,
-`--max-subject-length`, `--min-description-length`, `--require-trailer`) take
+`--max-subject-length`, `--min-description-length`, `--no-require-lowercase`,
+`--no-trailing-chars`, `--require-trailer`) take
 full precedence and ignore config file values when provided.
 
 ### Environment variables
@@ -207,7 +246,7 @@ COMMIT_GUARD_GIT_TIMEOUT=30 commit-guard --range origin/main..HEAD
 In GitHub Actions, set it at the step or job level:
 
 ```yaml
-- uses: benner/commit-guard@v0.15.0
+- uses: benner/commit-guard@v0.17.0
   env:
     COMMIT_GUARD_GIT_TIMEOUT: 30
   with:
@@ -280,6 +319,10 @@ commit-guard --range origin/main..HEAD --output-file results.jsonl
 `--output-file` is independent of `--output`: combining both writes JSONL to
 both stdout and the file.
 
+In GitHub Actions, `output-file` is the recommended way to get machine-readable
+results — text stays in the CI log and the file is accessible to subsequent steps
+via `steps.<id>.outputs.output-file`.
+
 ### GitHub Actions
 
 ```yaml
@@ -287,7 +330,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.15.0
+  - uses: benner/commit-guard@v0.17.0
 ```
 
 Check all commits in a pull request:
@@ -303,11 +346,19 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.15.0
+      - uses: benner/commit-guard@v0.17.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
 
+Check a specific commit SHA (mirrors the positional CLI argument):
+
+```yaml
+      - uses: benner/commit-guard@v0.17.0
+        with:
+          rev: ${{ github.sha }}
+```
+
 All inputs are optional and mirror the CLI flags:
 
 ```yaml
@@ -321,7 +372,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.15.0
+      - uses: benner/commit-guard@v0.17.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -330,13 +381,17 @@ jobs:
           require-trailer: 'Closes,Reviewed-by'
           max-subject-length: '100'
           min-description-length: '10'
+          no-require-lowercase: 'true'
+          no-trailing-chars: '.,!'
+          allow-empty: 'true'
+          include-merges: 'true'
           output-file: results.jsonl
 ```
 
 When `output-file` is set the action exposes the path as an output:
 
 ```yaml
-      - uses: benner/commit-guard@v0.15.0
+      - uses: benner/commit-guard@v0.17.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -352,7 +407,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.15.0
+    rev: v0.17.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/README.md

@@ -75,7 +75,7 @@ Available checks:
 * `subject` - Format matches `type(scope): description`, valid type,
     lowercase start, no trailing period, max 72 chars
 * `imperative` - First word is an imperative verb (for example `add` not `added`)
-* `body` - Body is present after a blank line
+* `body` - Blank line separates subject from body, and body is non-empty
 * `signed-off` - `Signed-off-by:` trailer exists
 * `signature` - Verify GPG or SSH signature
 
@@ -95,6 +95,41 @@ By default there is no minimum description length. Enforce one with
 commit-guard --min-description-length 10
 ```
 
+### Subject format
+
+By default the description must start with a lowercase letter. To allow
+uppercase descriptions:
+
+```bash
+commit-guard --no-require-lowercase
+```
+
+In `.commit-guard.toml`:
+
+```toml
+require-lowercase = false
+```
+
+By default trailing `.` is forbidden. To change the set of forbidden trailing
+characters (any character is valid, including space):
+
+```bash
+commit-guard --no-trailing-chars ".,"
+commit-guard --no-trailing-chars ".,!"
+```
+
+In `.commit-guard.toml`:
+
+```toml
+no-trailing-chars = [".", "!"]
+```
+
+Pass an empty list to disable the check entirely:
+
+```toml
+no-trailing-chars = []
+```
+
 ### Type validation
 
 By default the standard conventional commit types are accepted. Use `--types`
@@ -149,7 +184,8 @@ independently of `--enable`/`--disable`.
 
 Place `.commit-guard.toml` in your project root (or any parent directory) to
 set defaults for `enable`, `disable`, `scopes`, `require-scope`, `types`,
-`max-subject-length`, `min-description-length`, and `require-trailers`.
+`max-subject-length`, `min-description-length`, `require-lowercase`,
+`no-trailing-chars`, and `require-trailers`.
 commit-guard searches upward from the working directory and uses the first
 file found.
 
@@ -161,6 +197,8 @@ require-scope = true
 types = ["feat", "fix", "chore", "wip"]
 max-subject-length = 100
 min-description-length = 10
+require-lowercase = false
+no-trailing-chars = [".", "!"]
 require-trailers = ["Closes", "Reviewed-by"]
 ```
 
@@ -170,7 +208,8 @@ enable = ["subject", "imperative"]
 ```
 
 CLI flags (`--enable`, `--disable`, `--scopes`, `--require-scope`, `--types`,
-`--max-subject-length`, `--min-description-length`, `--require-trailer`) take
+`--max-subject-length`, `--min-description-length`, `--no-require-lowercase`,
+`--no-trailing-chars`, `--require-trailer`) take
 full precedence and ignore config file values when provided.
 
 ### Environment variables
@@ -186,7 +225,7 @@ COMMIT_GUARD_GIT_TIMEOUT=30 commit-guard --range origin/main..HEAD
 In GitHub Actions, set it at the step or job level:
 
 ```yaml
-- uses: benner/commit-guard@v0.15.0
+- uses: benner/commit-guard@v0.17.0
   env:
     COMMIT_GUARD_GIT_TIMEOUT: 30
   with:
@@ -259,6 +298,10 @@ commit-guard --range origin/main..HEAD --output-file results.jsonl
 `--output-file` is independent of `--output`: combining both writes JSONL to
 both stdout and the file.
 
+In GitHub Actions, `output-file` is the recommended way to get machine-readable
+results — text stays in the CI log and the file is accessible to subsequent steps
+via `steps.<id>.outputs.output-file`.
+
 ### GitHub Actions
 
 ```yaml
@@ -266,7 +309,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.15.0
+  - uses: benner/commit-guard@v0.17.0
 ```
 
 Check all commits in a pull request:
@@ -282,11 +325,19 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.15.0
+      - uses: benner/commit-guard@v0.17.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
 
+Check a specific commit SHA (mirrors the positional CLI argument):
+
+```yaml
+      - uses: benner/commit-guard@v0.17.0
+        with:
+          rev: ${{ github.sha }}
+```
+
 All inputs are optional and mirror the CLI flags:
 
 ```yaml
@@ -300,7 +351,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.15.0
+      - uses: benner/commit-guard@v0.17.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -309,13 +360,17 @@ jobs:
           require-trailer: 'Closes,Reviewed-by'
           max-subject-length: '100'
           min-description-length: '10'
+          no-require-lowercase: 'true'
+          no-trailing-chars: '.,!'
+          allow-empty: 'true'
+          include-merges: 'true'
           output-file: results.jsonl
 ```
 
 When `output-file` is set the action exposes the path as an output:
 
 ```yaml
-      - uses: benner/commit-guard@v0.15.0
+      - uses: benner/commit-guard@v0.17.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -331,7 +386,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.15.0
+    rev: v0.17.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/action.yml

@@ -34,6 +34,13 @@ inputs:
   min-description-length:
     description: Minimum description length in characters (default 0, off)
     required: false
+  no-require-lowercase:
+    description: Allow description to start with uppercase (default false)
+    required: false
+    default: 'false'
+  no-trailing-chars:
+    description: Forbidden trailing characters, comma-separated (default '.')
+    required: false
   allow-empty:
     description: Exit 0 when --range yields no commits
     required: false
@@ -75,6 +82,8 @@ runs:
         CG_TYPES: ${{ inputs.types }}
         CG_MAX_SUBJECT_LENGTH: ${{ inputs.max-subject-length }}
         CG_MIN_DESCRIPTION_LENGTH: ${{ inputs.min-description-length }}
+        CG_NO_REQUIRE_LOWERCASE: ${{ inputs.no-require-lowercase }}
+        CG_NO_TRAILING_CHARS: ${{ inputs.no-trailing-chars }}
         CG_ALLOW_EMPTY: ${{ inputs.allow-empty }}
         CG_INCLUDE_MERGES: ${{ inputs.include-merges }}
         CG_REQUIRE_TRAILER: ${{ inputs.require-trailer }}
@@ -92,6 +101,8 @@ runs:
             ARGS+=(--max-subject-length "$CG_MAX_SUBJECT_LENGTH")
         [[ -n "$CG_MIN_DESCRIPTION_LENGTH" ]] && \
             ARGS+=(--min-description-length "$CG_MIN_DESCRIPTION_LENGTH")
+        [[ "$CG_NO_REQUIRE_LOWERCASE" == "true" ]] && ARGS+=(--no-require-lowercase)
+        [[ -n "$CG_NO_TRAILING_CHARS" ]] && ARGS+=(--no-trailing-chars "$CG_NO_TRAILING_CHARS")
         [[ "$CG_ALLOW_EMPTY" == "true" ]] && ARGS+=(--allow-empty)
         [[ "$CG_INCLUDE_MERGES" == "true" ]] && ARGS+=(--include-merges)
         [[ -n "$CG_REQUIRE_TRAILER" ]] && ARGS+=(--require-trailer "$CG_REQUIRE_TRAILER")

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/docs/index.html

@@ -332,7 +332,10 @@ $ commit-guard abc1234
 $ commit-guard --range origin/main..HEAD
 
 # read from a file (for git hooks)
-$ commit-guard --message-file .git/COMMIT_EDITMSG</code></pre>
+$ commit-guard --message-file .git/COMMIT_EDITMSG
+
+# pipe message via stdin
+$ echo "fix(auth): add token refresh" | commit-guard</code></pre>
 
         <h3>Checks</h3>
         <p>
@@ -351,8 +354,11 @@ $ commit-guard --message-file .git/COMMIT_EDITMSG</code></pre>
               <tr>
                 <td><code>subject</code></td>
                 <td>
-                  Format matches <code>type(scope): description</code>, valid
-                  type, lowercase start, no trailing period, max 72 chars
+                  <a href="https://www.conventionalcommits.org/" target="_blank" rel="noopener">Conventional Commits</a>
+                  format: valid type, lowercase start, no trailing period,
+                  max length (default 72). All limits are configurable. Use
+                  <code>!</code> before the colon for breaking changes:
+                  <code>feat!: remove endpoint</code>
                 </td>
               </tr>
               <tr>
@@ -363,7 +369,7 @@ $ commit-guard --message-file .git/COMMIT_EDITMSG</code></pre>
               </tr>
               <tr>
                 <td><code>body</code></td>
-                <td>Body is present after a blank line</td>
+                <td>Blank line separates subject from body, and body is non-empty</td>
               </tr>
               <tr>
                 <td><code>signed-off</code></td>
@@ -381,8 +387,9 @@ $ commit-guard --message-file .git/COMMIT_EDITMSG</code></pre>
       <section id="configuration">
         <h2>Configuration <a href="#configuration" class="anchor">#</a></h2>
         <p>
-          Place <code>.commit-guard.toml</code> in your project root. CLI flags
-          always take precedence over the config file.
+          Place <code>.commit-guard.toml</code> in your project root or any
+          parent directory — commit-guard searches upward and uses the first
+          file found. CLI flags always take precedence.
         </p>
         <pre><code class="language-toml"># .commit-guard.toml
 disable = ["signature", "body"]
@@ -391,7 +398,72 @@ require-scope = true
 types = ["feat", "fix", "chore", "wip"]
 max-subject-length = 100
 min-description-length = 10
+require-lowercase = false
+no-trailing-chars = [".", "!"]
 require-trailers = ["Closes", "Reviewed-by"]</code></pre>
+
+        <h3>Required trailers</h3>
+        <p>
+          Require arbitrary trailers in the commit message. Accepts a
+          comma-separated list; matching is case-sensitive and requires a
+          non-empty value after the colon (e.g. <code>Closes: #42</code>):
+        </p>
+        <pre><code class="language-bash">commit-guard --require-trailer "Closes,Reviewed-by"</code></pre>
+
+        <h3>Range options</h3>
+        <p>
+          When using <code>--range</code>, merge commits are excluded by
+          default. Use <code>--include-merges</code> to check them. An empty
+          range exits non-zero by default — use <code>--allow-empty</code> to
+          exit 0 instead:
+        </p>
+        <pre><code class="language-bash">commit-guard --range origin/main..HEAD --include-merges --allow-empty</code></pre>
+
+        <h3>Environment variables</h3>
+        <figure>
+          <table>
+            <thead>
+              <tr>
+                <th>Variable</th>
+                <th>Default</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td><code>COMMIT_GUARD_GIT_TIMEOUT</code></td>
+                <td><code>10</code></td>
+                <td>Timeout in seconds for git subprocess calls</td>
+              </tr>
+            </tbody>
+          </table>
+        </figure>
+      </section>
+
+      <section id="output">
+        <h2>Output <a href="#output" class="anchor">#</a></h2>
+        <p>
+          Use <code>--output jsonl</code> to emit one JSON line per commit to
+          stdout instead of the default human-readable text:
+        </p>
+        <pre><code class="language-bash">commit-guard --range origin/main..HEAD --output jsonl | jq 'select(.ok == false)'</code></pre>
+        <p>Each line is a JSON object:</p>
+        <pre><code>{
+  "sha": "abc1234...",
+  "subject": "feat: add thing",
+  "ok": false,
+  "results": [{"check": "body", "level": "error", "message": "missing body"}]
+}</code></pre>
+        <p>
+          <code>sha</code> is <code>null</code> when reading from a file or
+          stdin. <code>results</code> is empty when all checks pass.
+        </p>
+        <p>
+          Use <code>--output-file FILE</code> to write JSONL to a file while
+          keeping human-readable text on stdout — useful in CI where you want
+          readable logs and structured results for downstream steps:
+        </p>
+        <pre><code class="language-bash">commit-guard --range origin/main..HEAD --output-file results.jsonl</code></pre>
       </section>
 
       <section id="github-actions">
@@ -407,18 +479,37 @@ require-trailers = ["Closes", "Reviewed-by"]</code></pre>
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.14.1
+      - uses: benner/commit-guard@v0.17.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature</code></pre>
 
+        <p>Check a specific commit SHA:</p>
+        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.17.0
+        with:
+          rev: ${{ github.sha }}</code></pre>
+
         <p>
-          All inputs mirror the CLI flags: <code>enable</code>,
-          <code>disable</code>, <code>scopes</code>, <code>require-scope</code>,
-          <code>types</code>, <code>max-subject-length</code>,
-          <code>min-description-length</code>, <code>require-trailer</code>,
+          All inputs mirror the CLI flags: <code>rev</code>,
+          <code>range</code>, <code>enable</code>, <code>disable</code>,
+          <code>scopes</code>, <code>require-scope</code>, <code>types</code>,
+          <code>max-subject-length</code>, <code>min-description-length</code>,
+          <code>no-require-lowercase</code>, <code>no-trailing-chars</code>,
+          <code>require-trailer</code>,
+          <code>allow-empty</code>, <code>include-merges</code>,
           <code>output-file</code>.
         </p>
+
+        <p>
+          When <code>output-file</code> is set the action exposes the path as
+          a step output, making JSONL results available to subsequent steps:
+        </p>
+        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.17.0
+        id: cg
+        with:
+          range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
+          output-file: results.jsonl
+      - run: jq 'select(.ok == false)' "${{ steps.cg.outputs.output-file }}"</code></pre>
       </section>
 
       <section id="pre-commit">
@@ -426,7 +517,7 @@ require-trailers = ["Closes", "Reviewed-by"]</code></pre>
         <p>Add to <code>.pre-commit-config.yaml</code>:</p>
         <pre><code class="language-yaml">repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.14.1
+    rev: v0.17.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature</code></pre>
@@ -596,7 +687,7 @@ require-trailers = ["Closes", "Reviewed-by"]</code></pre>
       });
 
       document.querySelectorAll(
-        "#configuration pre code, #github-actions pre code, #pre-commit pre code"
+        "#configuration pre code, #output pre code, #github-actions pre code, #pre-commit pre code"
       ).forEach((code) => {
         const text = code.innerText.trim();
         const isConfig = code.className.includes("language-");

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/src/git_commit_guard/__init__.py

@@ -146,15 +146,17 @@ def _strip_comments(message):
     )
 
 
-def check_subject(  # noqa: PLR0913 Too many arguments in function definition (7 > 5)
+def check_subject(  # noqa: PLR0913 Too many arguments in function definition (9 > 5)
     line,
     result,
     allowed_scopes=frozenset(),
     allowed_types=TYPES,
     max_subject_length=MAX_SUBJECT_LEN,
     min_description_length=0,
+    no_trailing_chars=frozenset("."),
     *,
     require_scope=False,
+    require_lowercase=True,
 ):
     m = SUBJECT_RE.match(line)
     if not m:
@@ -174,10 +176,10 @@ def check_subject(  # noqa: PLR0913 Too many arguments in function definition (7
         result.error(f"unknown scope: {scope}", check=Check.SUBJECT)
 
     desc = m.group("desc")
-    if desc[0].isupper():
+    if require_lowercase and desc[0].isupper():
         result.error("description must not start with uppercase", check=Check.SUBJECT)
-    if desc.endswith("."):
-        result.error("description must not end with period", check=Check.SUBJECT)
+    if no_trailing_chars and desc[-1] in no_trailing_chars:
+        result.error(f"description must not end with {desc[-1]!r}", check=Check.SUBJECT)
     if len(line) > max_subject_length:
         result.error(
             f"subject too long: {len(line)} > {max_subject_length}", check=Check.SUBJECT
@@ -220,11 +222,15 @@ def check_imperative(desc, result):
 
 
 def check_body(lines, result):
-    if len(lines) < 3:  # noqa: PLR2004
+    if len(lines) == 1:
         result.error("missing body", check=Check.BODY)
         return
     if lines[1].strip():
         result.error("missing blank line between subject and body", check=Check.BODY)
+        return
+    if len(lines) == 2:  # noqa: PLR2004 Magic value used in comparison, consider replacing 2 with a constant variable
+        result.error("missing body", check=Check.BODY)
+        return
     body_lines = [ln for ln in lines[2:] if not _TRAILER_RE.match(ln)]
     if not any(ln.strip() for ln in body_lines):
         result.error("missing body", check=Check.BODY)
@@ -301,6 +307,8 @@ class Args:
     allowed_types: frozenset
     max_subject_length: int
     min_description_length: int
+    require_lowercase: bool
+    no_trailing_chars: frozenset
     rev_range: str | None
     allow_empty: bool
     include_merges: bool
@@ -341,6 +349,22 @@ def _resolve_min_description_length(args, config):
     return 0
 
 
+def _resolve_require_lowercase(args, config):
+    if args.require_lowercase is not None:
+        return args.require_lowercase
+    if "require-lowercase" in config:
+        return config["require-lowercase"]
+    return True
+
+
+def _resolve_no_trailing_chars(args, config):
+    if args.no_trailing_chars is not None:
+        return frozenset(c for c in args.no_trailing_chars.split(",") if c)
+    if "no-trailing-chars" in config:
+        return frozenset(config["no-trailing-chars"])
+    return frozenset(".")
+
+
 def _resolve_required_trailers(args, config):
     if args.require_trailer:
         return [t.strip() for t in args.require_trailer.split(",")]
@@ -427,6 +451,19 @@ def _parse_args():
         metavar="N",
         help="minimum description length in characters (default: 0, off)",
     )
+    parser.add_argument(
+        "--no-require-lowercase",
+        dest="require_lowercase",
+        action="store_false",
+        default=None,
+        help="allow description to start with uppercase (default: disallowed)",
+    )
+    parser.add_argument(
+        "--no-trailing-chars",
+        default=None,
+        metavar="CHAR[,CHAR,...]",
+        help="forbidden trailing characters in description (default: '.')",
+    )
     parser.add_argument(
         "--range",
         dest="rev_range",
@@ -469,6 +506,8 @@ def _parse_args():
     allowed_types = _resolve_types(args, config)
     max_subject_length = _resolve_max_subject_length(args, config)
     min_description_length = _resolve_min_description_length(args, config)
+    require_lowercase = _resolve_require_lowercase(args, config)
+    no_trailing_chars = _resolve_no_trailing_chars(args, config)
     required_trailers = _resolve_required_trailers(args, config)
 
     if args.allow_empty and not args.rev_range:
@@ -503,6 +542,8 @@ def _parse_args():
         allowed_types=allowed_types,
         max_subject_length=max_subject_length,
         min_description_length=min_description_length,
+        require_lowercase=require_lowercase,
+        no_trailing_chars=no_trailing_chars,
         rev_range=args.rev_range,
         allow_empty=args.allow_empty,
         include_merges=args.include_merges,
@@ -556,7 +597,9 @@ def _run_checks(args, rev, message, result):
             args.allowed_types,
             args.max_subject_length,
             args.min_description_length,
+            args.no_trailing_chars,
             require_scope=args.require_scope,
+            require_lowercase=args.require_lowercase,
         )
     if Check.IMPERATIVE in args.enabled:
         if desc is None:

{git_commit_guard-0.15.1 → git_commit_guard-0.17.0}/tests/test_git_commit_guard.py

@@ -113,11 +113,41 @@ class TestCheckSubject:
         check_subject("fix: Add token", r)
         assert not r.ok
 
+    def test_uppercase_description_allowed(self):
+        r = Result()
+        check_subject("fix: Add token", r, require_lowercase=False)
+        assert r.ok
+
+    def test_lowercase_required_by_default(self):
+        r = Result()
+        check_subject("fix: add token", r)
+        assert r.ok
+
     def test_trailing_period(self):
         r = Result()
         check_subject("fix: add token.", r)
         assert not r.ok
 
+    def test_trailing_char_custom(self):
+        r = Result()
+        check_subject("fix: add token!", r, no_trailing_chars=frozenset("!"))
+        assert not r.ok
+
+    def test_trailing_char_space(self):
+        r = Result()
+        check_subject("fix: add token ", r, no_trailing_chars=frozenset(". "))
+        assert not r.ok
+
+    def test_trailing_chars_empty_disables_check(self):
+        r = Result()
+        check_subject("fix: add token.", r, no_trailing_chars=frozenset())
+        assert r.ok
+
+    def test_trailing_chars_multiple(self):
+        r = Result()
+        check_subject("fix: add token!", r, no_trailing_chars=frozenset(".!"))
+        assert not r.ok
+
     def test_subject_too_long(self):
         r = Result()
         check_subject("fix: " + "a" * 68, r)  # 73 chars total
@@ -237,6 +267,12 @@ class TestCheckBody:
         check_body(["fix: add thing", "body text", "more"], r)
         assert not r.ok
 
+    def test_missing_blank_line_two_lines(self):
+        r = Result()
+        check_body(["fix: add thing", "body text"], r)
+        assert not r.ok
+        assert any("blank line" in msg for _, _, msg in r.errors)
+
     def test_blank_body_content(self):
         r = Result()
         check_body(["fix: add thing", "", "   "], r)