Customizable Branch Naming Templates #1511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

TechPreacher wants to merge 13 commits into github:main from TechPreacher:saschac/flexible-branch-names

CHANGELOG.md

-Original file line number
+Diff line change
@@ Expand Up @@
     The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
     and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+    ## [0.0.24] - 2026-01-26
+    ### Fixed
+    - **Branch Name Truncation**: Fixed truncation logic in `create-new-feature.sh` and `create-new-feature.ps1` to correctly guarantee GitHub's 244-byte branch name limit. The calculation now properly computes the maximum allowed length for the `{short_name}` segment based on the template overhead after resolving `{number}`.
+    - **Interactive Settings Overwrite Prompt**: When `.specify/settings.toml` already exists and `--force` is not provided, the CLI now prompts with "Overwrite? [y/N]" instead of simply exiting. This aligns with standard CLI behavior for file overwrites.
+    ## [0.0.23] - 2026-01-23
+    ### Added
+    - **Customizable Branch Naming Templates**: Teams can now configure branch naming patterns via `.specify/settings.toml`
+      - New `branch.template` setting supports placeholders: `{number}`, `{short_name}`, `{username}`, `{email_prefix}`
+      - Per-user number scoping: When using `{username}` prefix, each team member gets their own independent number sequence
+      - Automatic username resolution from Git config with OS username fallback
+      - Examples:
+        - `"{number}-{short_name}"` → `001-add-login` (default, solo developer)
+        - `"{username}/{number}-{short_name}"` → `johndoe/001-add-login` (team)
+        - `"feature/{username}/{number}-{short_name}"` → `feature/johndoe/001-add-login`
+      - Full backward compatibility: Projects without settings files work identically to before
+    - **Settings File Generation**: New `specify init --settings` command generates a documented settings file
+      - Use `--force` to overwrite existing settings files
+      - Settings file includes comprehensive documentation and examples
+    - **Branch Name Validation**: Generated branch names are validated against Git naming rules before creation
+      - Validates against forbidden characters, path rules, and GitHub's 244-byte limit
+      - Clear error messages for invalid configurations
+    ### Changed
+    - `create-new-feature.sh` and `create-new-feature.ps1` now source common utility functions
+    - Enhanced error messages for template configuration issues (FR-006)
     ## [0.0.22] - 2025-11-07
     - Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.
@@ Expand Down @@

README.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -188,6 +188,7 @@ The `specify` command supports the following options: @@
     | `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                                                                                                                                  |
     | `--debug`              | Flag     | Enable detailed debug output for troubleshooting                                                                                                                                             |
     | `--github-token`       | Option   | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)                                                                                                                    |
+    | `--settings`           | Flag     | Generate `.specify/settings.toml` for branch template customization. Can be combined with other flags.                                                                                       |
     ### Examples
@@ Expand Down Expand Up / @@ -238,10 +239,49 @@ specify init my-project --ai claude --debug @@
     # Use GitHub token for API requests (helpful for corporate environments)
     specify init my-project --ai claude --github-token ghp_your_token_here
+    # Generate settings file for branch template customization
+    specify init --settings
     # Check system requirements
     specify check
     ```
+    ### Branch Template Configuration
+    Teams can customize branch naming patterns by creating a `.specify/settings.toml` file:
+    ```bash
+    # Generate a settings file with documented options
+    specify init --settings
+    ```
+    The settings file supports the following template variables:
+    | Variable         | Description                                                    | Example Output    |
+    | ---------------- | -------------------------------------------------------------- | ----------------- |
+    | `{number}`       | Auto-incrementing 3-digit feature number                       | `001`, `002`      |
+    | `{short_name}`   | Generated or provided short feature name                       | `add-login`       |
+    | `{username}`     | Git user.name, normalized (lowercase, hyphens)                 | `jane-smith`      |
+    | `{email_prefix}` | Portion of Git user.email before the @ symbol                  | `jsmith`          |
+    **Example templates:**
+    ```toml
+    # Solo developer (default)
+    template = "{number}-{short_name}"
+    # Result: 001-add-login
+    # Team with username prefix
+    template = "{username}/{number}-{short_name}"
+    # Result: johndoe/001-add-login
+    # Team with feature prefix
+    template = "feature/{username}/{number}-{short_name}"
+    # Result: feature/johndoe/001-add-login
+    ```
+    When using `{username}` or a static prefix, each prefix gets its own independent number sequence, avoiding conflicts between team members.
     ### Available Slash Commands
     After running `specify init`, your AI coding agent will have access to these slash commands for structured development:
@@ Expand Down @@

docs/installation.md

-Original file line number
+Diff line change
@@ Expand Up @@
     uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude --ignore-agent-tools
     ```
+    ### Initialize Settings File
+    Teams can customize branch naming patterns by initializing a settings file:
+    ```bash
+    # Settings file only (in current directory)
+    uvx --from git+https://github.com/github/spec-kit.git specify init --settings
+    # Combined with full project initialization
+    uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --settings --ai copilot
+    # Or with --here flag for existing projects
+    uvx --from git+https://github.com/github/spec-kit.git specify init --here --settings --force
+    ```
+    This creates `.specify/settings.toml` where you can configure the branch template:
+    ```toml
+    [branch]
+    template = "{username}/{number}-{short_name}"  # e.g., jsmith/001-my-feature
+    ```
+    Available template variables: `{number}`, `{short_name}`, `{username}`, `{email_prefix}`
     ## Verification
     After initialization, you should see the following commands available in your AI agent:
@@ Expand Down @@

docs/quickstart.md

-Original file line number
+Diff line change
@@ Expand Up @@
     uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh  # Force POSIX shell
     ```
+    #### Customizing Branch Names
+    Teams can customize how feature branches are named by initializing a settings file:
+    ```bash
+    # Settings file only (current directory)
+    uvx --from git+https://github.com/github/spec-kit.git specify init --settings
+    # Combined with full project init
+    uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --settings --ai copilot
+    # Or with --here flag
+    uvx --from git+https://github.com/github/spec-kit.git specify init --here --settings --ai claude
+    ```
+    This creates `.specify/settings.toml` where you can configure the branch template:
+    ```toml
+    [branch]
+    template = "{username}/{number}-{short_name}"  # e.g., jsmith/001-my-feature
+    ```
+    Available template variables:
+    | Variable | Description | Example |
+    |----------|-------------|---------|
+    | `{number}` | Auto-incrementing 3-digit number | `001` |
+    | `{short_name}` | Kebab-case feature name | `my-feature` |
+    | `{username}` | Git user.name or OS username | `jsmith` |
+    | `{email_prefix}` | Part before @ in Git email | `john.smith` |
     ### Step 2: Define Your Constitution
     **In your AI Agent's chat interface**, use the `/speckit.constitution` slash command to establish the core rules and principles for your project. You should provide your project's specific principles as arguments.
@@ Expand Down @@

docs/upgrade.md

-Original file line number
+Diff line change
@@ Expand Up @@
     - ✅ **Your specifications** (`specs/001-my-feature/spec.md`, etc.) - **CONFIRMED SAFE**
     - ✅ **Your implementation plans** (`specs/001-my-feature/plan.md`, `tasks.md`, etc.) - **CONFIRMED SAFE**
+    - ✅ **Your settings file** (`.specify/settings.toml`) - **CONFIRMED SAFE**
     - ✅ **Your source code** - **CONFIRMED SAFE**
     - ✅ **Your git history** - **CONFIRMED SAFE**
@@ Expand Down @@

pyproject.toml

-Original file line number
+Diff line change
@@ -1,6 +1,6 @@
     [project]
     name = "specify-cli"
-    version = "0.0.22"
+    version = "0.0.23"
     description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
     requires-python = ">=3.11"
     dependencies = [
@@ Expand Down @@

scripts/bash/check-prerequisites.sh

-Original file line number
+Diff line change
@@ Expand Up / @@ -80,7 +80,7 @@ source "$SCRIPT_DIR/common.sh" @@
     # Get feature paths and validate branch
     eval $(get_feature_paths)
-    check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+    check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" "$REPO_ROOT" || exit 1
     # If paths-only mode, output paths and exit (support JSON + paths-only combined)
     if $PATHS_ONLY; then
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Customizable Branch Naming Templates #1511

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Customizable Branch Naming Templates #1511

Are you sure you want to change the base?

Uh oh!

Customizable Branch Naming Templates #1511

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!