From a4ca78665475365196d5e50fa16c0ceda4125c7c Mon Sep 17 00:00:00 2001 From: dhruv-15-03 Date: Wed, 8 Jul 2026 22:08:46 +0530 Subject: [PATCH] feat(git-extension): add configurable Conventional Commit support Adds a commit_style option (fixed | conventional) to the git extension's auto-commit config. When set to conventional, the speckit.git.commit hook instructs the agent to generate a Conventional Commit message from the diff and pass it to auto-commit.sh / auto-commit.ps1 as an explicit argument. If no message is supplied in conventional mode, the scripts fail loudly (stderr + exit 1) instead of silently falling back to the fixed message, but still short-circuit cleanly when there are no changes to commit. - extensions/git/config-template.yml, git-config.yml: new commit_style: fixed (default) / conventional option. - extensions/git/scripts/bash/auto-commit.sh: optional [generated_message] arg, commit_style parsing, conventional-mode enforcement. - extensions/git/scripts/powershell/auto-commit.ps1: mirrored PowerShell implementation. - extensions/git/commands/speckit.git.commit.md: documents commit message styles and updated execution/config guidance. - extensions/git/README.md: documents the new option. - tests/extensions/git/test_git_extension.py: regression tests for fixed default, conventional success, conventional missing-message failure, and no-changes short-circuit (bash + PowerShell). Fixes #3390 Assisted-by: GitHub Copilot (model: claude-sonnet-5, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- extensions/git/README.md | 7 +- extensions/git/commands/speckit.git.commit.md | 23 ++- extensions/git/config-template.yml | 7 + extensions/git/git-config.yml | 7 + extensions/git/scripts/bash/auto-commit.sh | 25 ++- .../git/scripts/powershell/auto-commit.ps1 | 30 +++- tests/extensions/git/test_git_extension.py | 156 ++++++++++++++++++ 7 files changed, 246 insertions(+), 9 deletions(-) diff --git a/extensions/git/README.md b/extensions/git/README.md index b5df3e31ee..c0cb7b5d00 100644 --- a/extensions/git/README.md +++ b/extensions/git/README.md @@ -10,7 +10,7 @@ This extension provides Git operations as an optional, self-contained module. It - **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering and optional templates for branch namespaces - **Branch validation** to ensure branches follow naming conventions - **Git remote detection** for GitHub integration (e.g., issue creation) -- **Auto-commit** after core commands (configurable per-command with custom messages) +- **Auto-commit** after core commands (configurable per-command with custom messages, or Conventional Commit messages generated by the agent) ## Commands @@ -66,6 +66,11 @@ branch_prefix: "" # Custom commit message for git init init_commit_message: "[Spec Kit] Initial commit" +# Commit message style for auto-commit hooks: "fixed" (default) uses the +# messages below; "conventional" asks the agent to generate a Conventional +# Commit message (e.g. "feat: add OAuth spec") from the diff instead. +commit_style: fixed + # Auto-commit per command (all disabled by default) # Example: enable auto-commit after specify auto_commit: diff --git a/extensions/git/commands/speckit.git.commit.md b/extensions/git/commands/speckit.git.commit.md index e606f911df..893b3adb85 100644 --- a/extensions/git/commands/speckit.git.commit.md +++ b/extensions/git/commands/speckit.git.commit.md @@ -14,23 +14,37 @@ This command is invoked as a hook after (or before) core commands. It: 2. Checks `.specify/extensions/git/git-config.yml` for the `auto_commit` section 3. Looks up the specific event key to see if auto-commit is enabled 4. Falls back to `auto_commit.default` if no event-specific key exists -5. Uses the per-command `message` if configured, otherwise a default message +5. Determines the commit message based on `commit_style` (see below) 6. If enabled and there are uncommitted changes, runs `git add .` + `git commit` +## Commit Message Styles + +Controlled by the `commit_style` key in `.specify/extensions/git/git-config.yml`: + +- **`fixed`** (default): use the per-command `message` if configured, otherwise a generic `[Spec Kit] Auto-commit ` message. +- **`conventional`**: inspect the actual changes (`git diff` / `git status`) since the last commit and generate a single-line [Conventional Commit](https://www.conventionalcommits.org/) message (`type(scope): subject`, e.g. `feat: add OAuth specification` or `docs: update implementation plan`) that accurately summarizes the change. Pass this message as the script's second argument. The configured `message` values are ignored in this mode. + ## Execution Determine the event name from the hook that triggered this command, then run the script: -- **Bash**: `.specify/extensions/git/scripts/bash/auto-commit.sh ` -- **PowerShell**: `.specify/extensions/git/scripts/powershell/auto-commit.ps1 ` +- **Bash**: `.specify/extensions/git/scripts/bash/auto-commit.sh [""]` +- **PowerShell**: `.specify/extensions/git/scripts/powershell/auto-commit.ps1 [""]` -Replace `` with the actual hook event (e.g., `after_specify`, `before_plan`, `after_implement`). +Replace `` with the actual hook event (e.g., `after_specify`, `before_plan`, `after_implement`). Only pass `` when `commit_style: conventional` is configured — first check `.specify/extensions/git/git-config.yml` for the value of `commit_style`: + +- If `conventional`: inspect the diff, generate a Conventional Commit message, and pass it as the second argument. +- If `fixed` or absent: run the script with just ``; it uses the configured/static message. ## Configuration In `.specify/extensions/git/git-config.yml`: ```yaml +# "fixed" (default) uses the messages below; "conventional" asks the agent +# to generate a Conventional Commit message from the diff instead. +commit_style: fixed + auto_commit: default: false # Global toggle — set true to enable for all commands after_specify: @@ -46,3 +60,4 @@ auto_commit: - If Git is not available or the current directory is not a repository: skips with a warning - If no config file exists: skips (disabled by default) - If no changes to commit: skips with a message +- If `commit_style: conventional` is set and no generated message was supplied: fails with a clear error instead of silently falling back to the fixed message format diff --git a/extensions/git/config-template.yml b/extensions/git/config-template.yml index 99e3d31692..2ea3471742 100644 --- a/extensions/git/config-template.yml +++ b/extensions/git/config-template.yml @@ -17,6 +17,13 @@ branch_prefix: "" # Commit message used by `git commit` during repository initialization init_commit_message: "[Spec Kit] Initial commit" +# Commit message style used by auto-commit hooks (speckit.git.commit): +# "fixed" - default; use the configured/static messages below. +# "conventional" - ask the agent to inspect the diff and generate a +# Conventional Commit message (e.g. "feat: add OAuth spec") +# instead of using the messages configured below. +commit_style: fixed + # Auto-commit before/after core commands. # Set "default" to enable for all commands, then override per-command. # Each key can be true/false. Message is customizable per-command. diff --git a/extensions/git/git-config.yml b/extensions/git/git-config.yml index 99e3d31692..2ea3471742 100644 --- a/extensions/git/git-config.yml +++ b/extensions/git/git-config.yml @@ -17,6 +17,13 @@ branch_prefix: "" # Commit message used by `git commit` during repository initialization init_commit_message: "[Spec Kit] Initial commit" +# Commit message style used by auto-commit hooks (speckit.git.commit): +# "fixed" - default; use the configured/static messages below. +# "conventional" - ask the agent to inspect the diff and generate a +# Conventional Commit message (e.g. "feat: add OAuth spec") +# instead of using the messages configured below. +commit_style: fixed + # Auto-commit before/after core commands. # Set "default" to enable for all commands, then override per-command. # Each key can be true/false. Message is customizable per-command. diff --git a/extensions/git/scripts/bash/auto-commit.sh b/extensions/git/scripts/bash/auto-commit.sh index f0b423187b..145f46b922 100755 --- a/extensions/git/scripts/bash/auto-commit.sh +++ b/extensions/git/scripts/bash/auto-commit.sh @@ -3,17 +3,22 @@ # Automatically commit changes after a Spec Kit command completes. # Checks per-command config keys in git-config.yml before committing. # -# Usage: auto-commit.sh +# Usage: auto-commit.sh [generated_message] # e.g.: auto-commit.sh after_specify +# e.g.: auto-commit.sh after_specify "feat: add OAuth specification" (commit_style: conventional) set -e EVENT_NAME="${1:-}" if [ -z "$EVENT_NAME" ]; then - echo "Usage: $0 " >&2 + echo "Usage: $0 [generated_message]" >&2 exit 1 fi +# Optional second argument: an agent-generated commit message (used when +# commit_style: conventional is configured). +GENERATED_MESSAGE="${2:-}" + SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" _find_project_root() { @@ -46,8 +51,13 @@ fi _config_file="$REPO_ROOT/.specify/extensions/git/git-config.yml" _enabled=false _commit_msg="" +_commit_style="fixed" if [ -f "$_config_file" ]; then + # Top-level scalar key: commit_style (fixed | conventional) + _style_val=$(grep '^commit_style:' "$_config_file" 2>/dev/null | sed 's/^commit_style:[[:space:]]*//' | sed 's/^["'\'']//' | sed 's/["'\'']*$//' | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]') + [ -n "$_style_val" ] && _commit_style="$_style_val" + # Parse the auto_commit section for this event. # Look for auto_commit..enabled and .message # Also check auto_commit.default as fallback. @@ -123,6 +133,17 @@ if git diff --quiet HEAD 2>/dev/null && git diff --cached --quiet 2>/dev/null && exit 0 fi +# In conventional mode, the commit message must be supplied by the agent +# (via the generated_message argument); never fall back to the fixed message. +if [ "$_commit_style" = "conventional" ]; then + if [ -n "$GENERATED_MESSAGE" ]; then + _commit_msg="$GENERATED_MESSAGE" + else + echo "[specify] Error: commit_style is 'conventional' but no generated commit message was supplied; skipped auto-commit" >&2 + exit 1 + fi +fi + # Derive a human-readable command name from the event # e.g., after_specify -> specify, before_plan -> plan _command_name=$(echo "$EVENT_NAME" | sed 's/^after_//' | sed 's/^before_//') diff --git a/extensions/git/scripts/powershell/auto-commit.ps1 b/extensions/git/scripts/powershell/auto-commit.ps1 index 34767f8a36..c4c378f3f3 100644 --- a/extensions/git/scripts/powershell/auto-commit.ps1 +++ b/extensions/git/scripts/powershell/auto-commit.ps1 @@ -3,11 +3,16 @@ # Automatically commit changes after a Spec Kit command completes. # Checks per-command config keys in git-config.yml before committing. # -# Usage: auto-commit.ps1 +# Usage: auto-commit.ps1 [generated_message] # e.g.: auto-commit.ps1 after_specify +# e.g.: auto-commit.ps1 after_specify "feat: add OAuth specification" (commit_style: conventional) param( [Parameter(Position = 0, Mandatory = $true)] - [string]$EventName + [string]$EventName, + + # Optional agent-generated commit message (used when commit_style: conventional is configured). + [Parameter(Position = 1, Mandatory = $false)] + [string]$GeneratedMessage = "" ) $ErrorActionPreference = 'Stop' @@ -55,8 +60,18 @@ if (-not $isRepo) { $configFile = Join-Path $repoRoot ".specify/extensions/git/git-config.yml" $enabled = $false $commitMsg = "" +$commitStyle = "fixed" if (Test-Path $configFile) { + # Top-level scalar key: commit_style (fixed | conventional) + foreach ($line in Get-Content $configFile) { + if ($line -match '^commit_style:\s*(.+)$') { + $styleVal = $matches[1].Trim() -replace '^["'']' -replace '["'']$' + if ($styleVal) { $commitStyle = $styleVal.ToLower() } + break + } + } + # Parse YAML to find auto_commit section $inAutoCommit = $false $inEvent = $false @@ -140,6 +155,17 @@ if ($d1 -eq 0 -and $d2 -eq 0 -and -not $untracked) { exit 0 } +# In conventional mode, the commit message must be supplied by the agent +# (via the GeneratedMessage argument); never fall back to the fixed message. +if ($commitStyle -eq 'conventional') { + if ($GeneratedMessage) { + $commitMsg = $GeneratedMessage + } else { + Write-Warning "[specify] Error: commit_style is 'conventional' but no generated commit message was supplied; skipped auto-commit" + exit 1 + } +} + # Derive a human-readable command name from the event $commandName = $EventName -replace '^after_', '' -replace '^before_', '' $phase = if ($EventName -match '^before_') { 'before' } else { 'after' } diff --git a/tests/extensions/git/test_git_extension.py b/tests/extensions/git/test_git_extension.py index 71dfd02223..dadb5aa14a 100644 --- a/tests/extensions/git/test_git_extension.py +++ b/tests/extensions/git/test_git_extension.py @@ -1091,6 +1091,93 @@ def test_success_message_no_unicode_checkmark(self, tmp_path: Path): assert "\u2713" not in result.stderr, "Must not use Unicode checkmark" +@requires_bash +class TestAutoCommitBashCommitStyle: + """Tests for the `commit_style: conventional` option (issue #3390).""" + + def test_fixed_is_default_when_commit_style_absent(self, tmp_path: Path): + """Omitting commit_style preserves the fixed/static message behavior.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + ' message: "[Spec Kit] Add specification"\n' + )) + (project / "new-file.txt").write_text("content") + result = _run_bash("auto-commit.sh", project, "after_specify") + assert result.returncode == 0 + log = subprocess.run( + ["git", "log", "--oneline", "-1"], + cwd=project, capture_output=True, text=True, + ) + assert "[Spec Kit] Add specification" in log.stdout + + def test_conventional_uses_generated_message(self, tmp_path: Path): + """commit_style: conventional uses the generated_message argument as the commit message.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "commit_style: conventional\n" + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + ' message: "[Spec Kit] Add specification"\n' + )) + (project / "new-file.txt").write_text("content") + result = _run_bash( + "auto-commit.sh", project, "after_specify", "feat: add OAuth specification" + ) + assert result.returncode == 0 + log = subprocess.run( + ["git", "log", "--oneline", "-1"], + cwd=project, capture_output=True, text=True, + ) + assert "feat: add OAuth specification" in log.stdout + assert "[Spec Kit] Add specification" not in log.stdout + + def test_conventional_without_generated_message_fails(self, tmp_path: Path): + """commit_style: conventional fails clearly instead of falling back to the fixed message.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "commit_style: conventional\n" + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + ' message: "[Spec Kit] Add specification"\n' + )) + (project / "new-file.txt").write_text("content") + result = _run_bash("auto-commit.sh", project, "after_specify") + assert result.returncode != 0 + assert "conventional" in result.stderr.lower() + + # No commit should have been made, and the fixed message must not be used. + log = subprocess.run( + ["git", "log", "--oneline"], + cwd=project, capture_output=True, text=True, + ) + assert "[Spec Kit] Add specification" not in log.stdout + + def test_conventional_skips_cleanly_with_no_changes(self, tmp_path: Path): + """No pending changes short-circuits before the missing-message failure.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "commit_style: conventional\n" + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + )) + subprocess.run(["git", "add", "."], cwd=project, check=True) + subprocess.run(["git", "commit", "-m", "setup", "-q"], cwd=project, check=True) + + result = _run_bash("auto-commit.sh", project, "after_specify") + assert result.returncode == 0 + assert "No changes" in result.stderr + + @pytest.mark.skipif(not HAS_PWSH, reason="pwsh not available") class TestAutoCommitPowerShell: def test_disabled_by_default(self, tmp_path: Path): @@ -1151,6 +1238,75 @@ def test_success_message_no_unicode_checkmark(self, tmp_path: Path): assert "\u2713" not in result.stdout, "Must not use Unicode checkmark" +@pytest.mark.skipif(not HAS_PWSH, reason="pwsh not available") +class TestAutoCommitPowerShellCommitStyle: + """Tests for the `commit_style: conventional` option (issue #3390).""" + + def test_fixed_is_default_when_commit_style_absent(self, tmp_path: Path): + """Omitting commit_style preserves the fixed/static message behavior.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + ' message: "[Spec Kit] Add specification"\n' + )) + (project / "new-file.txt").write_text("content") + result = _run_pwsh("auto-commit.ps1", project, "after_specify") + assert result.returncode == 0 + log = subprocess.run( + ["git", "log", "--oneline", "-1"], + cwd=project, capture_output=True, text=True, + ) + assert "[Spec Kit] Add specification" in log.stdout + + def test_conventional_uses_generated_message(self, tmp_path: Path): + """commit_style: conventional uses the generated_message argument as the commit message.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "commit_style: conventional\n" + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + ' message: "[Spec Kit] Add specification"\n' + )) + (project / "new-file.txt").write_text("content") + result = _run_pwsh( + "auto-commit.ps1", project, "after_specify", "feat: add OAuth specification" + ) + assert result.returncode == 0 + log = subprocess.run( + ["git", "log", "--oneline", "-1"], + cwd=project, capture_output=True, text=True, + ) + assert "feat: add OAuth specification" in log.stdout + assert "[Spec Kit] Add specification" not in log.stdout + + def test_conventional_without_generated_message_fails(self, tmp_path: Path): + """commit_style: conventional fails clearly instead of falling back to the fixed message.""" + project = _setup_project(tmp_path) + _write_config(project, ( + "commit_style: conventional\n" + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + ' message: "[Spec Kit] Add specification"\n' + )) + (project / "new-file.txt").write_text("content") + result = _run_pwsh("auto-commit.ps1", project, "after_specify") + assert result.returncode != 0 + assert "conventional" in result.stderr.lower() + + log = subprocess.run( + ["git", "log", "--oneline"], + cwd=project, capture_output=True, text=True, + ) + assert "[Spec Kit] Add specification" not in log.stdout + + # ── auto-commit.ps1 CRLF warning tests (issue #2253) ────────────────────────