mirror of https://github.com/github/spec-kit.git synced 2026-07-05 13:34:06 +08:00

Files

Manfred Riem 2972dec85c feat: Git extension stage 2 — GIT_BRANCH_NAME override, --force for existing dirs, auto-install tests (#1940 ) (#2117 )

* feat: Git extension stage 2 — GIT_BRANCH_NAME override, --force for existing dirs, auto-install tests (#1940)

- Add GIT_BRANCH_NAME env var override to create-new-feature.sh/.ps1
  for exact branch naming (bypasses all prefix/suffix generation)
- Fix --force flag for 'specify init <dir>' into existing directories
- Add TestGitExtensionAutoInstall tests (auto-install, --no-git skip,
  commands registered)
- Add TestFeatureDirectoryResolution tests (env var, feature.json,
  priority, branch fallback)
- Document GIT_BRANCH_NAME in speckit.git.feature.md and specify.md

* fix: remove unused Tuple import (ruff F401)

* fix: address Copilot review feedback (#2117)

- Fix timestamp regex ordering: check YYYYMMDD-HHMMSS before generic
  numeric prefix in both bash and PowerShell
- Set BRANCH_SUFFIX in GIT_BRANCH_NAME override path so 244-byte
  truncation logic works correctly
- Add 244-byte length check for GIT_BRANCH_NAME in PowerShell
- Use existing_items for non-empty dir warning with --force
- Skip git extension install if already installed (idempotent --force)
- Wrap PowerShell feature.json parsing in try/catch for malformed JSON
- Fix PS comment: 'prefix lookup' -> 'exact mapping via Get-FeatureDir'
- Remove non-functional SPECIFY_SPEC_DIRECTORY from specify.md template

* fix: address second round of Copilot review feedback (#2117)

- Guard shutil.rmtree on init failure: skip cleanup when --force merged
  into a pre-existing directory (prevents data loss)
- Bash: error on GIT_BRANCH_NAME >244 bytes instead of broken truncation
- Fix malformed numbered list in specify.md (restore missing step 1)
- Add claude_skills.exists() assert before iterdir() in test

* fix: use UTF-8 byte count for 244-byte branch name limit (#2117)

- Bash: use LC_ALL=C wc -c for byte length instead of ${#VAR}
- PowerShell: use [System.Text.Encoding]::UTF8.GetByteCount() instead
  of .Length (UTF-16 code units)

* fix: address third round of review feedback (#2117)

- Update --dry-run help text in bash and PowerShell (branch name only)
- Fix specify.md JSON example: use concrete path, not literal variable
- Add TestForceExistingDirectory tests (merge + error without --force)
- Add PowerShell Get-FeaturePathsEnv tests (env var + feature.json)

* fix: normalize relative paths and fix Test-HasGit compat (#2117)

- Bash common.sh: normalize SPECIFY_FEATURE_DIRECTORY and feature.json
  relative paths to absolute under repo root
- PowerShell common.ps1: same normalization using IsPathRooted + Join-Path
- PowerShell create-new-feature.ps1: call Test-HasGit without -RepoRoot
  for compatibility with core common.ps1 (no param) and git-common.ps1
  (optional param with default)

* test: add GIT_BRANCH_NAME automated tests for bash and PowerShell (#2117)

- TestGitBranchNameOverrideBash: 5 tests (exact name, sequential prefix,
  timestamp prefix, overlong rejection, dry-run)
- TestGitBranchNameOverridePowerShell: 4 tests (exact name, sequential
  prefix, timestamp prefix, overlong rejection)
- Tests use extension scripts (not core) via new ext_git_repo and
  ext_ps_git_repo fixtures

* fix: restore git init during specify init + review fixes (#2117)

- Restore is_git_repo() and init_git_repo() functions removed in stage 2
- specify init now runs git init AND installs git extension (not just
  extension install alone)
- Add is_dir() guard for non-here path to prevent uncontrolled error
  when target exists but is a file
- Add python3 JSON fallback in common.sh for multi-line feature.json
  (grep pipeline fails on pretty-printed JSON without jq)

* fix: use init_git_repo error_msg in failure output (#2117)

* fix: ensure_executable_scripts also covers .specify/extensions/ (#2117)

Extension .sh scripts (e.g. create-new-feature.sh, initialize-repo.sh)
may lack execute bits after install. Scan both .specify/scripts/ and
.specify/extensions/ for permission fixing.

* fix: move chmod after extension install + sanitize error_msg (#2117)

- ensure_executable_scripts() now runs after git extension install so
  extension .sh files get execute bits in the same init run
- Sanitize init_git_repo error_msg to single line (replace newlines,
  truncate to 120 chars) to prevent garbled StepTracker output

* fix: use tracker.error for git init/extension failures (#2117)

Git init failure and extension install failure were reported as
tracker.complete (showing green) even on error. Now track a
git_has_error flag and call tracker.error when any step fails,
so the UI correctly reflects the failure state.

* fix: sanitize ext_err in git step tracker for consistent rendering (#2117)

2026-04-08 13:48:36 -05:00

3.2 KiB

Raw Blame History

description

description
Create a feature branch with sequential or timestamp numbering

Create Feature Branch

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.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Environment Variable Override

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:

The script uses the exact value as the branch name, bypassing all prefix/suffix generation
--short-name, --number, and --timestamp flags are ignored
FEATURE_NUM is extracted from the name if it starts with a numeric prefix, otherwise set to the full branch name

Prerequisites

Verify Git is available by running git rev-parse --is-inside-work-tree 2>/dev/null
If Git is not available, warn the user and skip branch creation

Branch Numbering Mode

Determine the branch numbering strategy by checking configuration in this order:

Check .specify/extensions/git/git-config.yml for branch_numbering value
Check .specify/init-options.json for branch_numbering value (backward compatibility)
Default to sequential if neither exists

Execution

Generate a concise short name (2-4 words) for the branch:

Analyze the feature description and extract the most meaningful keywords
Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)

Run the appropriate script based on your platform:

Bash: .specify/extensions/git/scripts/bash/create-new-feature.sh --json --short-name "<short-name>" "<feature description>"
Bash (timestamp): .specify/extensions/git/scripts/bash/create-new-feature.sh --json --timestamp --short-name "<short-name>" "<feature description>"
PowerShell: .specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -ShortName "<short-name>" "<feature description>"
PowerShell (timestamp): .specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"

IMPORTANT:

Do NOT pass --number — the script determines the correct next number automatically
Always include the JSON flag (--json for Bash, -Json for PowerShell) so the output can be parsed reliably
You must only ever run this script once per feature
The JSON output will contain BRANCH_NAME and FEATURE_NUM

Graceful Degradation

If Git is not installed or the current directory is not a Git repository:

Branch creation is skipped with a warning: [specify] Warning: Git repository not detected; skipped branch creation
The script still outputs BRANCH_NAME and FEATURE_NUM so the caller can reference them

Output

The script outputs JSON with:

BRANCH_NAME: The branch name (e.g., 003-user-auth or 20260319-143022-user-auth)
FEATURE_NUM: The numeric or timestamp prefix used

3.2 KiB Raw Blame History