|
| 1 | +--- |
| 2 | +name: speckit-git-feature |
| 3 | +description: Create a feature branch with sequential or timestamp numbering |
| 4 | +compatibility: Requires spec-kit project structure with .specify/ directory |
| 5 | +metadata: |
| 6 | + author: github-spec-kit |
| 7 | + source: git:commands/speckit.git.feature.md |
| 8 | +--- |
| 9 | + |
| 10 | +# Create Feature Branch |
| 11 | + |
| 12 | +Create and switch to a new git feature branch for the given specification. This command handles **branch creation only** — the spec directory and files are created by the core `/speckit.specify` workflow. |
| 13 | + |
| 14 | +## User Input |
| 15 | + |
| 16 | +```text |
| 17 | +$ARGUMENTS |
| 18 | +``` |
| 19 | + |
| 20 | +You **MUST** consider the user input before proceeding (if not empty). |
| 21 | + |
| 22 | +## Environment Variable Override |
| 23 | + |
| 24 | +If the user explicitly provided `GIT_BRANCH_NAME` (e.g., via environment variable, argument, or in their request), pass it through to the script by setting the `GIT_BRANCH_NAME` environment variable before invoking the script. When `GIT_BRANCH_NAME` is set: |
| 25 | +- The script uses the exact value as the branch name, bypassing all prefix/suffix generation |
| 26 | +- `--short-name`, `--number`, and `--timestamp` flags are ignored |
| 27 | +- `FEATURE_NUM` is extracted from the name if it starts with a numeric prefix, otherwise set to the full branch name |
| 28 | + |
| 29 | +## Prerequisites |
| 30 | + |
| 31 | +- Verify Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null` |
| 32 | +- If Git is not available, warn the user and skip branch creation |
| 33 | + |
| 34 | +## Branch Numbering Mode |
| 35 | + |
| 36 | +Determine the branch numbering strategy by checking configuration in this order: |
| 37 | + |
| 38 | +1. Check `.specify/extensions/git/git-config.yml` for `branch_numbering` value |
| 39 | +2. Check `.specify/init-options.json` for `branch_numbering` value (backward compatibility) |
| 40 | +3. Default to `sequential` if neither exists |
| 41 | + |
| 42 | +## Execution |
| 43 | + |
| 44 | +Generate a concise short name (2-4 words) for the branch: |
| 45 | +- Analyze the feature description and extract the most meaningful keywords |
| 46 | +- Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug") |
| 47 | +- Preserve technical terms and acronyms (OAuth2, API, JWT, etc.) |
| 48 | + |
| 49 | +Run the appropriate script based on your platform: |
| 50 | + |
| 51 | +- **Bash**: `.specify/extensions/git/scripts/bash/create-new-feature.sh --json --short-name "<short-name>" "<feature description>"` |
| 52 | +- **Bash (timestamp)**: `.specify/extensions/git/scripts/bash/create-new-feature.sh --json --timestamp --short-name "<short-name>" "<feature description>"` |
| 53 | +- **PowerShell**: `.specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -ShortName "<short-name>" "<feature description>"` |
| 54 | +- **PowerShell (timestamp)**: `.specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"` |
| 55 | + |
| 56 | +**IMPORTANT**: |
| 57 | +- Do NOT pass `--number` — the script determines the correct next number automatically |
| 58 | +- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably |
| 59 | +- You must only ever run this script once per feature |
| 60 | +- The JSON output will contain `BRANCH_NAME` and `FEATURE_NUM` |
| 61 | + |
| 62 | +## Graceful Degradation |
| 63 | + |
| 64 | +If Git is not installed or the current directory is not a Git repository: |
| 65 | +- Branch creation is skipped with a warning: `[specify] Warning: Git repository not detected; skipped branch creation` |
| 66 | +- The script still outputs `BRANCH_NAME` and `FEATURE_NUM` so the caller can reference them |
| 67 | + |
| 68 | +## Output |
| 69 | + |
| 70 | +The script outputs JSON with: |
| 71 | +- `BRANCH_NAME`: The branch name (e.g., `003-user-auth` or `20260319-143022-user-auth`) |
| 72 | +- `FEATURE_NUM`: The numeric or timestamp prefix used |
0 commit comments