fix: integrate git hooks with pre-commit

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: Canonical Ltd.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+default_install_hook_types: [commit-msg, pre-push]
+
+repos:
+  - repo: local
+    hooks:
+      - id: gitlance-commit-msg
+        name: Validate commit message with gitlance
+        entry: bash githooks/commit-msg
+        language: system
+        stages: [commit-msg]
+      - id: gitlance-pre-push
+        name: Validate commits with gitlance
+        entry: python githooks/pre_commit_pre_push.py
+        language: python
+        stages: [pre-push]
+        always_run: true
+        pass_filenames: false

CONTRIBUTING.md

@@ -17,6 +17,21 @@ Contributions are welcome! Please follow these guidelines.
 5. Add `Signed-off-by` trailer to commits
 6. Open a pull request
 
+### Local commit validation
+
+Gitlance can validate commit messages and pushed commits locally. Install
+[pre-commit](https://pre-commit.com/#install), install the local Gitlance
+binary, and register both hooks:
+
+```console
+cargo install --path . --locked
+task install-githooks
+```
+
+The installation is idempotent. If a `commit-msg` or `pre-push` hook already
+exists, pre-commit preserves it as a legacy hook and runs it alongside
+Gitlance. Running `pre-commit uninstall` restores the previous hooks.
+
 ## Commit Requirements
 
 - Use conventional format: `feat:`, `fix:`, `docs:`, etc.

README.md

@@ -224,6 +224,38 @@ steps:
     run: exit 1
 ```
 
+## CLI Usage
+
+gitlance can also be run directly as a command-line tool, independent of GitHub
+Actions.
+
+### Validating a Single Commit Message
+
+Instead of a commit range, gitlance can validate a single commit message read
+from a file, using `--message-file`. This makes it convenient to use in a local
+`commit-msg` git hook, where git passes the path to the prepared message:
+
+```bash
+gitlance --message-file .git/COMMIT_EDITMSG
+```
+
+A specific check can also be selected:
+
+```bash
+gitlance conventional-commits --message-file .git/COMMIT_EDITMSG
+```
+
+### Validating Unpublished Commits
+
+With `--not-on-remotes`, gitlance validates only the commits reachable from
+`--head` that are not yet present on any remote. This makes it convenient to use
+in a local `pre-push` git hook. It exits successfully when there is nothing new
+to check:
+
+```bash
+gitlance --head <head_ref> --not-on-remotes
+```
+
 ## Installation
 
 ### GitHub Action

Taskfile.yml

@@ -21,13 +21,14 @@ tasks:
 
   install-githooks:
     desc: "Install git hooks for commit validation"
-    vars:
-      HOOKS_DIR:
-        sh: git rev-parse --git-path hooks
-    cmds:
-      - cp githooks/pre-push "{{.HOOKS_DIR}}/"
-      - chmod +x "{{.HOOKS_DIR}}/pre-push"
-      - echo "✓ Git hooks installed to {{.HOOKS_DIR}}"
+    preconditions:
+      - sh: pre-commit --version
+        msg: "pre-commit is required: https://pre-commit.com/#install"
+      - sh: gitlance --help
+        msg: "gitlance must be installed and available in PATH: cargo install --path . --locked"
+    cmds:
+      - pre-commit install
+      - echo "✓ Git hooks installed with pre-commit"
 
   setup:
     desc: "Setup Rust toolchain and development environment"

githooks/commit-msg

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# SPDX-FileCopyrightText: Canonical Ltd.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+set -e
+
+# Check that gitlance is available
+if ! command -v gitlance >/dev/null 2>&1; then
+    echo "Error: gitlance is not installed or not in PATH"
+    echo "To bypass: git commit --no-verify"
+    exit 1
+fi
+
+message_file="$1"
+
+if ! gitlance --message-file "$message_file"; then
+    echo
+    echo "Commit rejected: Message validation failed"
+    echo "To bypass: git commit --no-verify"
+    exit 1
+fi
+
+exit 0

githooks/pre-push

@@ -34,35 +34,34 @@ do
         continue
     fi
 
-    # Determine base commit
+    # Run gitlance
+    echo "Checking git commit logs with gitlance:"
+    echo
     if [ "$remote_oid" = "0000000000000000000000000000000000000000" ]; then
-        # New branch - try to find common ancestor with remote HEAD
-        base=""
-        if remote_head=$(git ls-remote "$remote" HEAD 2>/dev/null | awk '{print $1}') && [ -n "$remote_head" ]; then
-            base=$(git merge-base "$remote_head" "$local_oid" 2>/dev/null) || true
-        fi
-        # Fall back to root commit if no common ancestor found
-        if [ -z "$base" ]; then
-            base=$(git rev-list --max-parents=0 "$local_oid" | head -1)
+        # New branch: validate commits not yet present on any remote. gitlance
+        # derives the set from remote-tracking refs, which is more reliable than
+        # a single remote's HEAD (a stale remote would re-check known commits).
+        if ! gitlance --head "$local_oid" --not-on-remotes; then
+            echo ""
+            echo "Push rejected: Commit validation failed"
+            echo "To fix: git commit --amend, or git rebase -i"
+            echo "To bypass: git push --no-verify"
+            exit 1
         fi
     else
-        # Existing branch - find common ancestor to only check divergent commits
+        # Existing branch: check only commits that diverge from the remote.
         if ! base=$(git merge-base "$remote_oid" "$local_oid"); then
             echo "Error: Failed to find merge-base between remote and local commits"
             echo "To bypass: git push --no-verify"
             exit 1
         fi
-    fi
-
-    # Run gitlance
-    echo "Checking git commit logs with gitlance:"
-    echo
-    if ! gitlance --base "$base" --head "$local_oid"; then
-        echo ""
-        echo "Push rejected: Commit validation failed"
-        echo "To fix: git commit --amend, or git rebase -i $base"
-        echo "To bypass: git push --no-verify"
-        exit 1
+        if ! gitlance --base "$base" --head "$local_oid"; then
+            echo ""
+            echo "Push rejected: Commit validation failed"
+            echo "To fix: git commit --amend, or git rebase -i $base"
+            echo "To bypass: git push --no-verify"
+            exit 1
+        fi
     fi
 done
 

githooks/pre_commit_pre_push.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: Canonical Ltd.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import subprocess
+import sys
+
+
+def main() -> int:
+    local_branch = os.environ.get("PRE_COMMIT_LOCAL_BRANCH", "HEAD")
+    if local_branch != "HEAD" and not local_branch.startswith("refs/heads/"):
+        return 0
+
+    head = os.environ.get("PRE_COMMIT_TO_REF") or local_branch
+    return subprocess.call(
+        ["gitlance", "--head", head, "--not-on-remotes"],
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())