Skip to content

Commit 1e794d8

Browse files
committed
feat: Git extension stage 2 — GIT_BRANCH_NAME override, --force for existing dirs, auto-install tests (github#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
1 parent 6536bc4 commit 1e794d8

10 files changed

Lines changed: 421 additions & 268 deletions

File tree

‎extensions/git/commands/speckit.git.feature.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: "Create a feature branch with sequential or timestamp numbering"
44

55
# Create Feature Branch
66

7-
Create a new feature branch for the given specification.
7+
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.
88

99
## User Input
1010

@@ -14,10 +14,17 @@ $ARGUMENTS
1414

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

17+
## Environment Variable Override
18+
19+
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:
20+
- The script uses the exact value as the branch name, bypassing all prefix/suffix generation
21+
- `--short-name`, `--number`, and `--timestamp` flags are ignored
22+
- `FEATURE_NUM` is extracted from the name if it starts with a numeric prefix, otherwise set to the full branch name
23+
1724
## Prerequisites
1825

1926
- Verify Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
20-
- If Git is not available, warn the user and skip branch creation (spec directory will still be created)
27+
- If Git is not available, warn the user and skip branch creation
2128

2229
## Branch Numbering Mode
2330

@@ -45,22 +52,16 @@ Run the appropriate script based on your platform:
4552
- Do NOT pass `--number` — the script determines the correct next number automatically
4653
- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
4754
- You must only ever run this script once per feature
48-
- The JSON output will contain BRANCH_NAME and SPEC_FILE paths
49-
50-
If the extension scripts are not found at the `.specify/extensions/git/` path, fall back to:
51-
- **Bash**: `scripts/bash/create-new-feature.sh`
52-
- **PowerShell**: `scripts/powershell/create-new-feature.ps1`
55+
- The JSON output will contain `BRANCH_NAME` and `FEATURE_NUM`
5356

5457
## Graceful Degradation
5558

5659
If Git is not installed or the current directory is not a Git repository:
57-
- The script will still create the spec directory under `specs/`
58-
- A warning will be printed: `[specify] Warning: Git repository not detected; skipped branch creation`
59-
- The workflow continues normally without branch creation
60+
- Branch creation is skipped with a warning: `[specify] Warning: Git repository not detected; skipped branch creation`
61+
- The script still outputs `BRANCH_NAME` and `FEATURE_NUM` so the caller can reference them
6062

6163
## Output
6264

6365
The script outputs JSON with:
64-
- `BRANCH_NAME`: The created branch name (e.g., `003-user-auth` or `20260319-143022-user-auth`)
65-
- `SPEC_FILE`: Path to the created spec file
66+
- `BRANCH_NAME`: The branch name (e.g., `003-user-auth` or `20260319-143022-user-auth`)
6667
- `FEATURE_NUM`: The numeric or timestamp prefix used

‎extensions/git/scripts/bash/create-new-feature.sh‎

Lines changed: 50 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -71,10 +71,14 @@ while [ $i -le $# ]; do
7171
echo " --timestamp Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
7272
echo " --help, -h Show this help message"
7373
echo ""
74+
echo "Environment variables:"
75+
echo " GIT_BRANCH_NAME Use this exact branch name, bypassing all prefix/suffix generation"
76+
echo ""
7477
echo "Examples:"
7578
echo " $0 'Add user authentication system' --short-name 'user-auth'"
7679
echo " $0 'Implement OAuth2 integration for API' --number 5"
7780
echo " $0 --timestamp --short-name 'user-auth' 'Add user authentication'"
81+
echo " GIT_BRANCH_NAME=my-branch $0 'feature description'"
7882
exit 0
7983
;;
8084
*)
@@ -258,9 +262,6 @@ fi
258262
cd "$REPO_ROOT"
259263

260264
SPECS_DIR="$REPO_ROOT/specs"
261-
if [ "$DRY_RUN" != true ]; then
262-
mkdir -p "$SPECS_DIR"
263-
fi
264265

265266
# Function to generate branch name with stop word filtering
266267
generate_branch_name() {
@@ -301,40 +302,53 @@ generate_branch_name() {
301302
fi
302303
}
303304

304-
# Generate branch name
305-
if [ -n "$SHORT_NAME" ]; then
306-
BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
305+
# Check for GIT_BRANCH_NAME env var override (exact branch name, no prefix/suffix)
306+
if [ -n "${GIT_BRANCH_NAME:-}" ]; then
307+
BRANCH_NAME="$GIT_BRANCH_NAME"
308+
# Extract FEATURE_NUM from the branch name if it starts with a numeric prefix
309+
if echo "$BRANCH_NAME" | grep -Eq '^[0-9]+-'; then
310+
FEATURE_NUM=$(echo "$BRANCH_NAME" | grep -Eo '^[0-9]+')
311+
elif echo "$BRANCH_NAME" | grep -Eq '^[0-9]{8}-[0-9]{6}-'; then
312+
FEATURE_NUM=$(echo "$BRANCH_NAME" | grep -Eo '^[0-9]{8}-[0-9]{6}')
313+
else
314+
FEATURE_NUM="$BRANCH_NAME"
315+
fi
307316
else
308-
BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
309-
fi
317+
# Generate branch name
318+
if [ -n "$SHORT_NAME" ]; then
319+
BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
320+
else
321+
BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
322+
fi
310323

311-
# Warn if --number and --timestamp are both specified
312-
if [ "$USE_TIMESTAMP" = true ] && [ -n "$BRANCH_NUMBER" ]; then
313-
>&2 echo "[specify] Warning: --number is ignored when --timestamp is used"
314-
BRANCH_NUMBER=""
315-
fi
324+
# Warn if --number and --timestamp are both specified
325+
if [ "$USE_TIMESTAMP" = true ] && [ -n "$BRANCH_NUMBER" ]; then
326+
>&2 echo "[specify] Warning: --number is ignored when --timestamp is used"
327+
BRANCH_NUMBER=""
328+
fi
316329

317-
# Determine branch prefix
318-
if [ "$USE_TIMESTAMP" = true ]; then
319-
FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
320-
BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
321-
else
322-
if [ -z "$BRANCH_NUMBER" ]; then
323-
if [ "$DRY_RUN" = true ] && [ "$HAS_GIT" = true ]; then
324-
BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR" true)
325-
elif [ "$DRY_RUN" = true ]; then
326-
HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
327-
BRANCH_NUMBER=$((HIGHEST + 1))
328-
elif [ "$HAS_GIT" = true ]; then
329-
BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
330-
else
331-
HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
332-
BRANCH_NUMBER=$((HIGHEST + 1))
330+
# Determine branch prefix
331+
if [ "$USE_TIMESTAMP" = true ]; then
332+
FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
333+
BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
334+
else
335+
if [ -z "$BRANCH_NUMBER" ]; then
336+
if [ "$DRY_RUN" = true ] && [ "$HAS_GIT" = true ]; then
337+
BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR" true)
338+
elif [ "$DRY_RUN" = true ]; then
339+
HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
340+
BRANCH_NUMBER=$((HIGHEST + 1))
341+
elif [ "$HAS_GIT" = true ]; then
342+
BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
343+
else
344+
HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
345+
BRANCH_NUMBER=$((HIGHEST + 1))
346+
fi
333347
fi
334-
fi
335348

336-
FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
337-
BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
349+
FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
350+
BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
351+
fi
338352
fi
339353

340354
# GitHub enforces a 244-byte limit on branch names
@@ -354,9 +368,6 @@ if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
354368
>&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
355369
fi
356370

357-
FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
358-
SPEC_FILE="$FEATURE_DIR/spec.md"
359-
360371
if [ "$DRY_RUN" != true ]; then
361372
if [ "$HAS_GIT" = true ]; then
362373
branch_create_error=""
@@ -391,22 +402,6 @@ if [ "$DRY_RUN" != true ]; then
391402
>&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
392403
fi
393404

394-
mkdir -p "$FEATURE_DIR"
395-
396-
if [ ! -f "$SPEC_FILE" ]; then
397-
if type resolve_template >/dev/null 2>&1; then
398-
TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
399-
else
400-
TEMPLATE=""
401-
fi
402-
if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
403-
cp "$TEMPLATE" "$SPEC_FILE"
404-
else
405-
echo "Warning: Spec template not found; created empty spec file" >&2
406-
touch "$SPEC_FILE"
407-
fi
408-
fi
409-
410405
printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
411406
fi
412407

@@ -415,35 +410,30 @@ if $JSON_MODE; then
415410
if [ "$DRY_RUN" = true ]; then
416411
jq -cn \
417412
--arg branch_name "$BRANCH_NAME" \
418-
--arg spec_file "$SPEC_FILE" \
419413
--arg feature_num "$FEATURE_NUM" \
420-
'{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num,DRY_RUN:true}'
414+
'{BRANCH_NAME:$branch_name,FEATURE_NUM:$feature_num,DRY_RUN:true}'
421415
else
422416
jq -cn \
423417
--arg branch_name "$BRANCH_NAME" \
424-
--arg spec_file "$SPEC_FILE" \
425418
--arg feature_num "$FEATURE_NUM" \
426-
'{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num}'
419+
'{BRANCH_NAME:$branch_name,FEATURE_NUM:$feature_num}'
427420
fi
428421
else
429422
if type json_escape >/dev/null 2>&1; then
430423
_je_branch=$(json_escape "$BRANCH_NAME")
431-
_je_spec=$(json_escape "$SPEC_FILE")
432424
_je_num=$(json_escape "$FEATURE_NUM")
433425
else
434426
_je_branch="$BRANCH_NAME"
435-
_je_spec="$SPEC_FILE"
436427
_je_num="$FEATURE_NUM"
437428
fi
438429
if [ "$DRY_RUN" = true ]; then
439-
printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","DRY_RUN":true}\n' "$_je_branch" "$_je_spec" "$_je_num"
430+
printf '{"BRANCH_NAME":"%s","FEATURE_NUM":"%s","DRY_RUN":true}\n' "$_je_branch" "$_je_num"
440431
else
441-
printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$_je_branch" "$_je_spec" "$_je_num"
432+
printf '{"BRANCH_NAME":"%s","FEATURE_NUM":"%s"}\n' "$_je_branch" "$_je_num"
442433
fi
443434
fi
444435
else
445436
echo "BRANCH_NAME: $BRANCH_NAME"
446-
echo "SPEC_FILE: $SPEC_FILE"
447437
echo "FEATURE_NUM: $FEATURE_NUM"
448438
if [ "$DRY_RUN" != true ]; then
449439
printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"

‎extensions/git/scripts/powershell/create-new-feature.ps1‎

Lines changed: 41 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ if ($Help) {
2929
Write-Host " -Number N Specify branch number manually (overrides auto-detection)"
3030
Write-Host " -Timestamp Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
3131
Write-Host " -Help Show this help message"
32+
Write-Host ""
33+
Write-Host "Environment variables:"
34+
Write-Host " GIT_BRANCH_NAME Use this exact branch name, bypassing all prefix/suffix generation"
35+
Write-Host ""
3236
exit 0
3337
}
3438

@@ -216,9 +220,6 @@ if (Get-Command Test-HasGit -ErrorAction SilentlyContinue) {
216220
Set-Location $repoRoot
217221

218222
$specsDir = Join-Path $repoRoot 'specs'
219-
if (-not $DryRun) {
220-
New-Item -ItemType Directory -Path $specsDir -Force | Out-Null
221-
}
222223

223224
function Get-BranchName {
224225
param([string]$Description)
@@ -255,35 +256,48 @@ function Get-BranchName {
255256
}
256257
}
257258

258-
if ($ShortName) {
259-
$branchSuffix = ConvertTo-CleanBranchName -Name $ShortName
259+
# Check for GIT_BRANCH_NAME env var override (exact branch name, no prefix/suffix)
260+
if ($env:GIT_BRANCH_NAME) {
261+
$branchName = $env:GIT_BRANCH_NAME
262+
# Extract FEATURE_NUM from the branch name if it starts with a numeric prefix
263+
if ($branchName -match '^(\d+)-') {
264+
$featureNum = $matches[1]
265+
} elseif ($branchName -match '^(\d{8}-\d{6})-') {
266+
$featureNum = $matches[1]
267+
} else {
268+
$featureNum = $branchName
269+
}
260270
} else {
261-
$branchSuffix = Get-BranchName -Description $featureDesc
262-
}
271+
if ($ShortName) {
272+
$branchSuffix = ConvertTo-CleanBranchName -Name $ShortName
273+
} else {
274+
$branchSuffix = Get-BranchName -Description $featureDesc
275+
}
263276

264-
if ($Timestamp -and $Number -ne 0) {
265-
Write-Warning "[specify] Warning: -Number is ignored when -Timestamp is used"
266-
$Number = 0
267-
}
277+
if ($Timestamp -and $Number -ne 0) {
278+
Write-Warning "[specify] Warning: -Number is ignored when -Timestamp is used"
279+
$Number = 0
280+
}
268281

269-
if ($Timestamp) {
270-
$featureNum = Get-Date -Format 'yyyyMMdd-HHmmss'
271-
$branchName = "$featureNum-$branchSuffix"
272-
} else {
273-
if ($Number -eq 0) {
274-
if ($DryRun -and $hasGit) {
275-
$Number = Get-NextBranchNumber -SpecsDir $specsDir -SkipFetch
276-
} elseif ($DryRun) {
277-
$Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
278-
} elseif ($hasGit) {
279-
$Number = Get-NextBranchNumber -SpecsDir $specsDir
280-
} else {
281-
$Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
282+
if ($Timestamp) {
283+
$featureNum = Get-Date -Format 'yyyyMMdd-HHmmss'
284+
$branchName = "$featureNum-$branchSuffix"
285+
} else {
286+
if ($Number -eq 0) {
287+
if ($DryRun -and $hasGit) {
288+
$Number = Get-NextBranchNumber -SpecsDir $specsDir -SkipFetch
289+
} elseif ($DryRun) {
290+
$Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
291+
} elseif ($hasGit) {
292+
$Number = Get-NextBranchNumber -SpecsDir $specsDir
293+
} else {
294+
$Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
295+
}
282296
}
283-
}
284297

285-
$featureNum = ('{0:000}' -f $Number)
286-
$branchName = "$featureNum-$branchSuffix"
298+
$featureNum = ('{0:000}' -f $Number)
299+
$branchName = "$featureNum-$branchSuffix"
300+
}
287301
}
288302

289303
$maxBranchLength = 244
@@ -302,9 +316,6 @@ if ($branchName.Length -gt $maxBranchLength) {
302316
Write-Warning "[specify] Truncated to: $branchName ($($branchName.Length) bytes)"
303317
}
304318

305-
$featureDir = Join-Path $specsDir $branchName
306-
$specFile = Join-Path $featureDir 'spec.md'
307-
308319
if (-not $DryRun) {
309320
if ($hasGit) {
310321
$branchCreated = $false
@@ -357,28 +368,12 @@ if (-not $DryRun) {
357368
}
358369
}
359370

360-
New-Item -ItemType Directory -Path $featureDir -Force | Out-Null
361-
362-
if (-not (Test-Path -PathType Leaf $specFile)) {
363-
if (Get-Command Resolve-Template -ErrorAction SilentlyContinue) {
364-
$template = Resolve-Template -TemplateName 'spec-template' -RepoRoot $repoRoot
365-
} else {
366-
$template = $null
367-
}
368-
if ($template -and (Test-Path $template)) {
369-
Copy-Item $template $specFile -Force
370-
} else {
371-
New-Item -ItemType File -Path $specFile -Force | Out-Null
372-
}
373-
}
374-
375371
$env:SPECIFY_FEATURE = $branchName
376372
}
377373

378374
if ($Json) {
379375
$obj = [PSCustomObject]@{
380376
BRANCH_NAME = $branchName
381-
SPEC_FILE = $specFile
382377
FEATURE_NUM = $featureNum
383378
HAS_GIT = $hasGit
384379
}
@@ -388,7 +383,6 @@ if ($Json) {
388383
$obj | ConvertTo-Json -Compress
389384
} else {
390385
Write-Output "BRANCH_NAME: $branchName"
391-
Write-Output "SPEC_FILE: $specFile"
392386
Write-Output "FEATURE_NUM: $featureNum"
393387
Write-Output "HAS_GIT: $hasGit"
394388
if (-not $DryRun) {

0 commit comments

Comments
 (0)