fix(scripts): add empty description validation and branch checkout error handling

[nsalvacao]

Summary

Intake of upstream PR #1559 (cherry-picked with git cherry-pick -x).

Author: zaheer15351 <zaheer15351@gmail.com>

Changes

Two critical improvements to both Bash and PowerShell feature creation scripts:

1. Post-trim whitespace validation — prevents creating features with whitespace-only descriptions (e.g., specify create " ")
2. Branch checkout error handling — provides clear error messages when branch creation fails (e.g., branch already exists) instead of silently continuing

Verification

• git cherry-pick -x 2ff4adde — authorship preserved ✅
• 317 passed, 22 skipped — no regressions ✅
• Both bash and PS1 covered in the upstream commit ✅

Closes #61

[github-actions]

📝 AI PR Summary

Summary

Add validation to ensure feature description is not empty or whitespace-only and improve error handling when creating git branches that already exist in both bash and PowerShell scripts.

Changes

• Trim and validate feature description input; exit with error if empty or whitespace.
• Enhance git branch creation error handling to detect existing branches and provide clearer error messages.
• Consistent behavior added to both create-new-feature.sh and create-new-feature.ps1.

Impact

• Prevents creation of features with invalid descriptions.
• Provides clearer feedback when git branch creation fails due to existing branches or git issues.
• Improves robustness and user experience of feature creation scripts.

---

🤖 Auto-generated · openai/gpt-4.1-mini · GitHub Models free tier · 0 premium requests

[gemini-code-assist]

Summary of Changes

Hello @nsalvacao, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the robustness and user experience of the feature creation scripts by addressing two key areas. It ensures that feature descriptions are meaningful by validating against empty or whitespace-only inputs after trimming, and it provides more informative feedback to users when Git branch creation encounters issues, such as a branch already existing, preventing silent failures and guiding users to resolve problems.

Highlights

• Description Validation: Implemented post-trim whitespace validation to prevent the creation of features with empty or whitespace-only descriptions in both Bash and PowerShell scripts.
• Branch Creation Error Handling: Enhanced error handling for Git branch creation, providing clear messages when a branch already exists or if creation fails for other reasons, instead of silently continuing.

Changelog

• scripts/bash/create-new-feature.sh
  • Added a step to trim whitespace from the FEATURE_DESCRIPTION and validate that it's not empty afterwards.
  • Modified the git checkout -b command to include error handling, checking if the branch already exists or if branch creation generally failed.
• scripts/powershell/create-new-feature.ps1
  • Introduced a validation check using [string]::IsNullOrWhiteSpace for the $featureDesc variable after trimming.
  • Refactored the Git branch creation logic to explicitly check for existing branches and general creation failures, providing specific error messages.

Activity

• Cherry-picked upstream PR fix(scripts): add empty description validation and branch checkout error handling github/spec-kit#1559, preserving original authorship.
• Verified that all existing tests passed, indicating no regressions.
• Confirmed that both Bash and PowerShell scripts are covered by the changes.
• Closed issue intake: upstream #1559 (intake/lote-A-pr-1559) #61.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

🔍 AI Code Review

Security Vulnerabilities

🔵 Info
No direct security vulnerabilities are present in this diff. The scripts do not handle sensitive data, nor do they introduce unsafe shell or PowerShell constructs.

---

Bugs

🟡 Warning
Bash Script:

• The use of git checkout -b "$BRANCH_NAME" 2>/dev/null suppresses all error output, which may make debugging harder if there are unexpected git errors unrelated to branch existence. Consider logging the error output for troubleshooting.

• The check for branch existence uses git branch --list "$BRANCH_NAME" | grep -q ., which works, but if the branch name contains special characters or spaces, it could cause issues. Consider quoting and validating branch names more strictly.

PowerShell Script:

• $LASTEXITCODE is checked after git checkout -b $branchName, but if the command fails and throws an exception, $LASTEXITCODE may not be reliable. The catch block does not set $branchCreated to $false, so if an exception occurs, the script may not behave as intended.
  Recommendation: Set $branchCreated = $false in the catch block to ensure correct logic.

• The check for branch existence uses git branch --list $branchName 2>$null, but if $branchName contains spaces or special characters, it may not match correctly. Consider quoting branch names.

---

Best Practice Violations

🟡 Warning
Bash Script:

• Using xargs to trim whitespace is common, but it may not handle multiline input or special characters robustly. Consider using awk '{$1=$1;print}' or sed for more robust trimming if needed.

• Error messages are sent to stderr, which is good, but consider also logging to a file for auditability if this script is used in CI/CD.

PowerShell Script:

• The script uses exit 1 for errors, which is correct, but Write-Error does not always terminate the script unless -ErrorAction Stop is used. The explicit exit 1 mitigates this, but be aware of PowerShell error handling nuances.

• git branch --list $branchName should be quoted: git branch --list "$branchName" to avoid issues with branch names containing spaces.

---

Summary Table

Issue	Severity	Recommendation
Suppressed git errors in Bash	🟡 Warning	Log error output for troubleshooting
Branch name quoting (both scripts)	🟡 Warning	Quote branch names in git commands
PowerShell $LASTEXITCODE reliability	🟡 Warning	Set $branchCreated = $false in catch block
Bash whitespace trimming robustness	🟡 Warning	Consider more robust trimming methods
PowerShell error handling nuances	🔵 Info	Ensure exit 1 is always reached after errors

---

Overall:
The changes improve input validation and error handling, but minor improvements in quoting, error output handling, and robustness are recommended. No critical bugs or vulnerabilities detected.

---

🤖 AI Review · openai/gpt-4.1 · 1598 tokens · GitHub Models free tier · 0 premium requests

[gemini-code-assist]

Code Review

This pull request enhances the feature creation scripts for both Bash and PowerShell by adding validation against empty or whitespace-only descriptions and by improving error handling during Git branch creation. The changes are a good step forward. My review includes a suggestion for the Bash script to use a more robust method for trimming whitespace to avoid potential side effects. For the PowerShell script, I've pointed out a redundant check and a potential unhandled exception in the new error handling logic, with suggestions to improve its robustness and clarity.

[github-actions]

📝 AI PR Summary

Summary

Add validation to ensure feature descriptions are not empty or whitespace-only and improve error handling when creating git branches in both Bash and PowerShell scripts.

Changes

• Trim and validate feature description input to reject empty or whitespace-only values.
• Enhance git branch creation logic to detect if branch already exists and provide clearer error messages.
• Exit with error if branch creation fails for other reasons.

Impact

• create-new-feature.sh and create-new-feature.ps1 scripts for creating new feature branches and descriptions.
• Prevents invalid feature descriptions and improves user feedback on git branch creation failures.

---

🤖 Auto-generated · openai/gpt-4.1-mini · GitHub Models free tier · 0 premium requests

[github-actions]

🔍 AI Code Review

Review Summary

Security Vulnerabilities

🔵 Info

• No direct security vulnerabilities detected in this diff. The scripts do not handle sensitive data, nor do they invoke commands with user-supplied input in a way that could lead to command injection.

---

Bugs

🟡 Warning
Bash Script:

• The use of git checkout -b "$BRANCH_NAME" 2>/dev/null suppresses all error output. If the error is not branch-exists, the user receives a generic message. This is generally fine, but could obscure useful error details (e.g., permission issues, repo corruption). Consider logging the actual error message for troubleshooting.

PowerShell Script:

• The $branchCreated flag is set to $true only if no exception occurs. However, git checkout -b $branchName 2>&1 | Out-Null does not throw exceptions on git errors (it just returns a non-zero exit code). As a result, $branchCreated will always be $true unless PowerShell itself throws (e.g., command not found), and branch creation failures (like branch already exists) will not be caught.
  • Severity: 🟡 Warning
  • Fix: Check the exit code of the git command, not just exceptions. Example:

    $result = git checkout -b $branchName 2>&1
    if ($LASTEXITCODE -ne 0) {
        # handle error
    }

---

Best Practice Violations

🔵 Info

• Bash: The use of sed for trimming whitespace is correct, but consider using awk or bash parameter expansion for portability and performance.
• PowerShell: Use of [string]::IsNullOrWhiteSpace($featureDesc) is good practice.

🟡 Warning

• Error Handling: Both scripts could benefit from logging the actual error output from git when branch creation fails, to aid debugging.
• Exit Codes: Both scripts use exit 1 for errors, which is good. However, PowerShell's exit may not always behave as expected in all contexts (e.g., in some shells, it may not terminate the script). Consider using throw or return for script termination in PowerShell.

---

Positive Notes

🔵 Info

• The addition of whitespace trimming and validation for feature descriptions is a good improvement for input hygiene.
• Improved error messages for branch creation failures enhance user experience.

---

Recommendations

1. PowerShell: Check git command exit code, not just exceptions, to reliably detect branch creation failures.
2. Bash/PowerShell: Consider logging actual git error output for easier troubleshooting.
3. Bash: Consider using bash parameter expansion for trimming whitespace for portability.

---

Example Fix for PowerShell

$result = git checkout -b $branchName 2>&1
if ($LASTEXITCODE -ne 0) {
    $existingBranch = git branch --list $branchName 2>$null
    if ($existingBranch) {
        Write-Error "Error: Branch '$branchName' already exists. Please use a different feature name or specify a different number with -Number."
    } else {
        Write-Error "Error: Failed to create git branch '$branchName'. Please check your git configuration and try again."
    }
    exit 1
}

---

Overall:

• No critical issues found.
• One bug in PowerShell error detection.
• Minor best practice improvements suggested.

---

🤖 AI Review · openai/gpt-4.1 · 1744 tokens · GitHub Models free tier · 0 premium requests

[nsalvacao]

GPT-4.1 Review Response

PS1 bug (LASTEXITCODE removed): GPT-4.1 está correto. $ErrorActionPreference = 'Stop' não lança exceções para comandos nativos (git) — apenas para cmdlets PowerShell. A sugestão da Gemini de remover o $LASTEXITCODE check introduziu um bug real: $branchCreated = $true corria sempre, mesmo quando git falhava. O bloco de error handling nunca seria executado.

✅ Restaurado if ($LASTEXITCODE -eq 0) guard — $branchCreated só é $true quando git retorna exit code 0.

✅ Quoting — git branch --list "$branchName" agora quoted corretamente.

Bash 2>/dev/null suppression: Upstream code (zaheer15351, cherry-pick -x). O stderr suprimido é intencional — o erro relevante (branch exists vs. other) é diagnosticado depois via git branch --list. Ponto válido mas não alteramos upstream sem necessidade.

Bash awk vs sed trimming: Já aplicado sed (Gemini suggestion anterior). Suficiente para este caso.

No more blockers.

[github-actions]

📝 AI PR Summary

Summary

Add validation to ensure feature descriptions are not empty or whitespace-only and improve error handling when git branch creation fails due to existing branches or other git issues.

Changes

• Trim and validate feature description input in both Bash and PowerShell scripts.
• Provide clear error messages if the feature description is empty after trimming.
• Enhance git branch creation logic to detect if a branch already exists and output specific error messages.
• Exit with error if branch creation fails for reasons other than an existing branch.

Impact

• Feature creation scripts (create-new-feature.sh and create-new-feature.ps1) now prevent invalid descriptions and handle git branch creation errors more gracefully, improving user feedback and robustness.

---

🤖 Auto-generated · openai/gpt-4.1-mini · GitHub Models free tier · 0 premium requests