mirror of
https://github.com/github/spec-kit.git
synced 2026-07-04 04:45:43 +08:00
1a9e4d1d8d
* feat: add git extension with hooks on all core commands - Create extensions/git/ with 5 commands: initialize, feature, validate, remote, commit - 18 hooks covering before/after for all 9 core commands - Scripts: create-new-feature, initialize-repo, auto-commit, git-common (bash + powershell) - Configurable: branch_numbering, init_commit_message, per-command auto-commit with custom messages - Add hooks to analyze, checklist, clarify, constitution, taskstoissues command templates - Allow hooks-only extensions (no commands required) - Bundle extension in wheel via pyproject.toml force-include - Resolve bundled extensions locally before catalog lookup - Remove planned-but-unimplemented before/after_commit hook refs - Update extension docs (API ref, dev guide, user guide) - 37 new tests covering manifest, install, all scripts (bash+pwsh), config reading, graceful degradation Stage 1: opt-in via 'specify extension add git'. No auto-install, no changes to specify.md or core git init code. Refs: #841, #1382, #1066, #1791, #1191 * fix: set git identity env vars in extension tests for CI runners * fix: address PR review comments - Fix commands property KeyError for hooks-only extensions - Fix has_git() operator precedence in git-common.sh - Align default commit message to '[Spec Kit] Initial commit' across config-template, extension.yml defaults, and both init scripts - Update README to reflect all 5 commands and 18 hooks * fix: address second round of PR review comments - Add type validation for provides.commands (must be list) and hooks (must be dict) in manifest _validate() - Tighten malformed timestamp detection in git-common.sh to catch 7-digit dates without trailing slug (e.g. 2026031-143022) - Pass REPO_ROOT to has_git/Test-HasGit in create-new-feature scripts - Fix initialize command docs: surface errors on git failures, only skip when git is not installed - Fix commit command docs: 'skips with a warning' not 'silently' - Add tests for commands:null and hooks:list rejection * fix: address third round of PR review comments - Remove scripts frontmatter from command files (CommandRegistrar rewrites ../../scripts/ to .specify/scripts/ which points at core scripts, not extension scripts) - Update speckit.git.commit command to derive event name from hook context rather than using a static example - Clarify that hook argument passthrough works via AI agent context (the agent carries conversation state including user's original feature description) * fix: address fourth round of PR review comments - Validate extension_id against ^[a-z0-9-]+$ in _locate_bundled_extension to prevent path traversal (security fix) - Move defaults under config.defaults in extension.yml to match ConfigManager._get_extension_defaults() schema - Ship git-config.yml in extension directory so it's copied during install (provides.config template isn't materialized by ExtensionManager) - Condition handling in hook templates: intentionally matches existing pattern from specify/plan/tasks/implement templates (not a new issue) * fix: add --allow-empty to git commit in initialize-repo scripts Ensures git init succeeds even on empty repos where nothing has been staged yet. * fix: resolve display names to bundled extensions before catalog download When 'specify extension add "Git Branching Workflow"' is used with a display name instead of the ID, the catalog resolver now runs first to map the name to an ID, then checks bundled extensions again with the resolved ID before falling back to network download. Also noted: EXECUTE_COMMAND_INVOCATION and condition handling match the existing pattern in specify/plan/tasks/implement templates (pre-existing, not introduced by this PR). * fix: handle before_/after_ prefixes in auto-commit message derivation - Strip both before_ and after_ prefixes when deriving command name (fixes misleading 'Auto-commit after before_plan' messages) - Include phase (before/after) in default commit messages - Clarify README config example is an override, not default behavior * fix: use portable grep -qw for word boundary in create-new-feature.sh BSD grep (macOS) doesn't support \b as a word boundary. Replace with grep -qw which is POSIX-portable. * fix: validate hook values, numeric --number, and PS warning routing - Validate each hook value is a dict with a 'command' field during manifest _validate() (prevents crash at install time) - Validate --number is a non-negative integer in bash create-new-feature (clear error instead of cryptic shell arithmetic failure) - Route PowerShell no-git warning to stderr in JSON mode so stdout stays valid JSON --------- Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com>
101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
# Git Branching Workflow Extension
|
|
|
|
Git repository initialization, feature branch creation, numbering (sequential/timestamp), validation, remote detection, and auto-commit for Spec Kit.
|
|
|
|
## Overview
|
|
|
|
This extension provides Git operations as an optional, self-contained module. It manages:
|
|
|
|
- **Repository initialization** with configurable commit messages
|
|
- **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering
|
|
- **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)
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `speckit.git.initialize` | Initialize a Git repository with a configurable commit message |
|
|
| `speckit.git.feature` | Create a feature branch with sequential or timestamp numbering |
|
|
| `speckit.git.validate` | Validate current branch follows feature branch naming conventions |
|
|
| `speckit.git.remote` | Detect Git remote URL for GitHub integration |
|
|
| `speckit.git.commit` | Auto-commit changes (configurable per-command enable/disable and messages) |
|
|
|
|
## Hooks
|
|
|
|
| Event | Command | Optional | Description |
|
|
|-------|---------|----------|-------------|
|
|
| `before_constitution` | `speckit.git.initialize` | No | Init git repo before constitution |
|
|
| `before_specify` | `speckit.git.feature` | No | Create feature branch before specification |
|
|
| `before_clarify` | `speckit.git.commit` | Yes | Commit outstanding changes before clarification |
|
|
| `before_plan` | `speckit.git.commit` | Yes | Commit outstanding changes before planning |
|
|
| `before_tasks` | `speckit.git.commit` | Yes | Commit outstanding changes before task generation |
|
|
| `before_implement` | `speckit.git.commit` | Yes | Commit outstanding changes before implementation |
|
|
| `before_checklist` | `speckit.git.commit` | Yes | Commit outstanding changes before checklist |
|
|
| `before_analyze` | `speckit.git.commit` | Yes | Commit outstanding changes before analysis |
|
|
| `before_taskstoissues` | `speckit.git.commit` | Yes | Commit outstanding changes before issue sync |
|
|
| `after_constitution` | `speckit.git.commit` | Yes | Auto-commit after constitution update |
|
|
| `after_specify` | `speckit.git.commit` | Yes | Auto-commit after specification |
|
|
| `after_clarify` | `speckit.git.commit` | Yes | Auto-commit after clarification |
|
|
| `after_plan` | `speckit.git.commit` | Yes | Auto-commit after planning |
|
|
| `after_tasks` | `speckit.git.commit` | Yes | Auto-commit after task generation |
|
|
| `after_implement` | `speckit.git.commit` | Yes | Auto-commit after implementation |
|
|
| `after_checklist` | `speckit.git.commit` | Yes | Auto-commit after checklist |
|
|
| `after_analyze` | `speckit.git.commit` | Yes | Auto-commit after analysis |
|
|
| `after_taskstoissues` | `speckit.git.commit` | Yes | Auto-commit after issue sync |
|
|
|
|
## Configuration
|
|
|
|
Configuration is stored in `.specify/extensions/git/git-config.yml`:
|
|
|
|
```yaml
|
|
# Branch numbering strategy: "sequential" or "timestamp"
|
|
branch_numbering: sequential
|
|
|
|
# Custom commit message for git init
|
|
init_commit_message: "[Spec Kit] Initial commit"
|
|
|
|
# Auto-commit per command (all disabled by default)
|
|
# Example: enable auto-commit after specify
|
|
auto_commit:
|
|
default: false
|
|
after_specify:
|
|
enabled: true
|
|
message: "[Spec Kit] Add specification"
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Install the bundled git extension (no network required)
|
|
specify extension add git
|
|
```
|
|
|
|
## Disabling
|
|
|
|
```bash
|
|
# Disable the git extension (spec creation continues without branching)
|
|
specify extension disable git
|
|
|
|
# Re-enable it
|
|
specify extension enable git
|
|
```
|
|
|
|
## Graceful Degradation
|
|
|
|
When Git is not installed or the directory is not a Git repository:
|
|
- Spec directories are still created under `specs/`
|
|
- Branch creation is skipped with a warning
|
|
- Branch validation is skipped with a warning
|
|
- Remote detection returns empty results
|
|
|
|
## Scripts
|
|
|
|
The extension bundles cross-platform scripts:
|
|
|
|
- `scripts/bash/create-new-feature.sh` — Bash implementation
|
|
- `scripts/bash/git-common.sh` — Shared Git utilities (Bash)
|
|
- `scripts/powershell/create-new-feature.ps1` — PowerShell implementation
|
|
- `scripts/powershell/git-common.ps1` — Shared Git utilities (PowerShell)
|