Skip to content

fix(settings): normalize and validate branch prefixes - #7772

Merged
nwparker merged 3 commits into
stablyai:mainfrom
yoelfme:fix/branch-prefix-trailing-slash
Jul 24, 2026
Merged

nwparker merged 3 commits into
stablyai:mainfrom
yoelfme:fix/branch-prefix-trailing-slash

Conversation

@yoelfme

@yoelfme yoelfme commented Jul 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes worktree creation failing with a cryptic fatal: 'team//main' is not a valid branch name git error when a custom branch prefix ends in a slash (e.g. team/).

ELI5

If you typed your branch prefix with a slash at the end — the natural way to write it — the app broke with a confusing error. Now it cleans up the prefix automatically and warns you right in Settings if it's still invalid.

Root cause & fix

The branch-name builder joins ${prefix}/${leaf}, so a trailing-slash prefix like team/ produced a double slash (team//main), and that computed name — unlike an explicit branch override — never passed through git check-ref-format, so it failed raw at git worktree add. A new shared helper (src/shared/branch-prefix.ts) normalizes prefixes (trim, strip leading/trailing and duplicate slashes) and validates them; worktree-create paths now use computeValidatedBranchName to fail fast with a clear "update it in Settings → Git" message. Live renderer feedback previews the resulting branch name and flags invalid characters. Best-effort background auto-rename intentionally keeps the non-throwing builder since the prefix is already validated at create time.

Evidence

Validated & rebased onto latest main during a bug-bash triage on 2026-07-23. Clean rebase onto origin/main (base 7ab601487c, head c8018405fd).

  • On branch (fix present): 114/114 tests pass across 4 suites.
  • Fail-when-reverted: reverting only the fix source (removing branch-prefix.ts and BranchPrefixFeedback.tsx) while keeping the new tests yields 11 failed / 69 passed — the tests genuinely capture the bug.
  • Key failing assertions when reverted: preview jdoe/feature (trailing-slash username normalization), Prefix cannot contain spaces (invalid-char warning), and No prefix will be applied (empty-after-normalize).
# fix present
Test Files  4 passed (4)
Tests       114 passed (114)

# fix source reverted, tests kept
Test Files  4 failed (4)
Tests       11 failed | 69 passed (80)
  • Lint clean: oxlint 1.71.0 exit 0, no warnings/errors on changed source.
  • i18n keys present in all 5 catalogs (en/es/ja/ko/zh).

Trade-offs

None — pure fix.

Regression risk

Zero-regression by construction: for valid prefixes computeValidatedBranchName returns the same value as the old computeBranchName; normalization only alters prefixes that were already broken (team/ → team//name). Only genuinely-invalid prefixes now throw a clear settings error instead of failing later at git check-ref-format (net improvement). Auto-rename retains its non-throwing path. Local and SSH worktree paths are both covered by the shared main-process builder. Proven by the passing test suite.


Original fix by @yoelfme. Validated, rebased, and reviewed via automated bug-bash triage on 2026-07-23; original fix design preserved.

@coderabbitai

coderabbitai Bot commented Jul 8, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

This PR adds shared branch-prefix normalization and validation utilities, a new BranchPrefixStrategy type, and computeValidatedBranchName for main-process worktree naming. Worktree and runtime paths now use the validated helper, while the renderer adds BranchPrefixFeedback to show prefix previews and validation messages in GitPane. New tests cover the shared helpers, main-process branch naming, the renderer component, and GitPane rendering. Locale files were updated with the new feedback strings.

Sequence Diagram(s)

Not applicable — the PR is split across utility, wiring, and UI changes rather than one single end-to-end flow.

Related Issues: Not specified.

Related PRs: Not specified.

Suggested labels: enhancement, main-process, renderer, i18n, tests

Suggested reviewers: Not specified.


Poem
Branch names trim their slashes neat,
Validation keeps the path complete.
A preview speaks in every tongue,
And tests keep all the pieces sprung.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description is informative but misses the required Screenshots, Testing, AI Review Report, Security Audit, and Notes sections. Reformat the PR body to the template and add the missing sections, including screenshots or 'No visual change', test status, AI review, security audit, and notes.
✅ Passed checks (4 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly summarizes the main change: branch prefix normalization and validation.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
src/main/runtime/orca-runtime.ts (1)

1429-1429: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use BranchPrefixSettings here and add a closed fallback. worktree-remote.ts already uses BranchPrefixSettings for the same helper, so the local { branchPrefix: string; branchPrefixCustom?: string } shape is what forces the as BranchPrefixStrategy cast. selectBranchPrefixInput also falls through on unexpected values, so a default: return null would make the fallback explicit.

src/renderer/src/components/settings/BranchPrefixFeedback.tsx (1)

9-9: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer ReactNode over JSX.Element for the return type.

Static analysis flags this: JSX.Element excludes null/strings/numbers that components commonly return. The component doesn't hit that case today, but constraining the return type this way makes future changes (e.g., returning null directly instead of always wrapping in <p>) a type error for no benefit.

🛠️ Proposed fix
-import type { JSX, ReactNode } from 'react'
+import type { ReactNode } from 'react'
 import { getBranchPrefixIssue, normalizeBranchPrefix } from '../../../../shared/branch-prefix'
 import { translate } from '`@/i18n/i18n`'

 type BranchPrefixFeedbackProps = {
   rawPrefix: string
 }

-export function BranchPrefixFeedback({ rawPrefix }: BranchPrefixFeedbackProps): JSX.Element {
+export function BranchPrefixFeedback({ rawPrefix }: BranchPrefixFeedbackProps): ReactNode {

Source: Linters/SAST tools


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8b6ea411-e5cd-49a3-904b-c9d63d5a0f0b

📥 Commits

Reviewing files that changed from the base of the PR and between 2ce77d9 and e29bfba0e6603fc68e890b8f90c9f30dc373114e.

📒 Files selected for processing (18)
  • src/main/agent-hooks/first-work-branch-rename.ts
  • src/main/ipc/worktree-branch-name.ts
  • src/main/ipc/worktree-logic.test.ts
  • src/main/ipc/worktree-logic.ts
  • src/main/ipc/worktree-remote.ts
  • src/main/runtime/orca-runtime.ts
  • src/renderer/src/components/settings/BranchPrefixFeedback.test.tsx
  • src/renderer/src/components/settings/BranchPrefixFeedback.tsx
  • src/renderer/src/components/settings/GitPane.test.tsx
  • src/renderer/src/components/settings/GitPane.tsx
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json
  • src/shared/branch-prefix.test.ts
  • src/shared/branch-prefix.ts
  • src/shared/types.ts

@yoelfme

yoelfme commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @coderabbitai — addressed the nitpicks:

  • BranchPrefixFeedback.tsx: changed the return type from JSX.Element to ReactNode. 👍

  • orca-runtime.ts cast: keeping the as BranchPrefixStrategy narrowing intentionally.

    • Switching the resolveCreateBranchName param to BranchPrefixSettings only moves the mismatch up to the caller, because RuntimeStore.getSettings() deliberately types branchPrefix loosely as string. Tightening that hand-rolled store interface would force changes in unrelated runtime test mocks (orca-runtime.test.ts, fit-override-integration.test.ts, mobile-presence-lock.test.ts, mobile-subscribe-integration.test.ts), which is out of scope for this PR.
    • The suggested default: return null in selectBranchPrefixInput isn't viable here: our switch-exhaustiveness-check lint runs with allowDefaultCaseForExhaustiveSwitch: false, so a default case on an already-exhaustive switch fails lint/CI.

@coderabbitai

coderabbitai Bot commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Tip

For best results, initiate chat on the files or code changes.

The PR description image (Screenshot 2026-07-07 at 10 26 45 PM) shows a "Branch Prefix" settings panel with options "Git Username", "Custom" (selected), and "None". A text input contains "core-team", with helper text below reading "Branches will be named core-team/feature".

The PR description image (Screenshot 2026-07-07 at 10 28 27 PM) shows the same panel with "Custom" selected and the input containing "core team" (with a space). Below the input, red validation text reads "Prefix cannot contain spaces or special characters like ~ ^ : ? * [ ".

@yoelfme Thanks for the detailed follow-up and for making the ReactNode change on BranchPrefixFeedback.tsx — that's the right type for this use case.

On the other two points, both explanations make sense to me:

  • orca-runtime.ts cast: Agreed, tightening RuntimeStore.getSettings() just to satisfy resolveCreateBranchName's parameter type would ripple into unrelated test mocks (orca-runtime.test.ts, fit-override-integration.test.ts, mobile-presence-lock.test.ts, mobile-subscribe-integration.test.ts) that are out of scope here. Keeping the explicit as BranchPrefixStrategy cast with the inline comment explaining why is a reasonable trade-off, and it's clearly documented so future readers won't be confused by it.

  • selectBranchPrefixInput default case: Makes sense — adding default: return null to an already-exhaustive switch would conflict with your switch-exhaustiveness-check lint rule (allowDefaultCaseForExhaustiveSwitch: false). No need to fight the linter here; the exhaustive switch without a default is the correct pattern for that config.

Thanks for walking through the reasoning on both — nothing further needed from me on these two.

(◕‿◕)

@yoelfme yoelfme changed the title Normalize branch prefixes and flag invalid ones in settings Normalize and validate branch prefixes Jul 8, 2026
@yoelfme yoelfme changed the title Normalize and validate branch prefixes fix(settings): normalize and validate branch prefixes Jul 8, 2026
@nwparker
nwparker force-pushed the fix/branch-prefix-trailing-slash branch from c801840 to c5d2030 Compare July 23, 2026 11:48
yoelfme and others added 3 commits July 24, 2026 00:32
A custom branch prefix ending in a slash (e.g. "team/") produced a
double-slashed branch name like "team//feature" that git rejects, and
the raw check-ref-format error gave no hint that the prefix caused it.

- Normalize the configured prefix (trim whitespace, strip leading/
  trailing and duplicate slashes) in the shared branch-name builder so
  the common trailing-slash case just works, for local and SSH worktrees.
- Validate the prefix on the worktree-create path (computeValidatedBranchName)
  so a genuinely invalid prefix fails fast with a clear
  "update it in Settings -> Git" message instead of an opaque git error.
- Add a live BranchPrefixFeedback under the Branch Prefix setting: previews
  the resulting branch name, warns on invalid characters, and notes when a
  prefix collapses to none.
- Keep the background first-work rename on the non-throwing builder since the
  prefix is already validated at create time.
The custom branch prefix input was directly controlled by settings, but
updateSettings persists through an async IPC round-trip, so the value
updated a tick late and React re-assigned it, snapping the caret to the
end on mid-string edits. Drive the input from a local draft and only
adopt genuine external settings changes so the caret stays put (and fast
typing survives slow SSH round-trips).

Co-authored-by: Cursor <cursoragent@cursor.com>
JSX.Element needlessly excludes null/string/number returns; ReactNode
keeps the component's return type from over-constraining future changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
@nwparker
nwparker force-pushed the fix/branch-prefix-trailing-slash branch from c5d2030 to ba10d01 Compare July 24, 2026 07:33
@nwparker
nwparker merged commit d1ccfcf into stablyai:main Jul 24, 2026
@nwparker

Copy link
Copy Markdown
Contributor

Thanks so much @yoelfme — the branch-prefix normalize/validate fix (no more team//main git errors). Resolved a fresh import conflict with main, verified 117 tests pass, and merged. 🙏

enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
* Normalize branch prefixes and flag invalid ones in settings

A custom branch prefix ending in a slash (e.g. "team/") produced a
double-slashed branch name like "team//feature" that git rejects, and
the raw check-ref-format error gave no hint that the prefix caused it.

- Normalize the configured prefix (trim whitespace, strip leading/
  trailing and duplicate slashes) in the shared branch-name builder so
  the common trailing-slash case just works, for local and SSH worktrees.
- Validate the prefix on the worktree-create path (computeValidatedBranchName)
  so a genuinely invalid prefix fails fast with a clear
  "update it in Settings -> Git" message instead of an opaque git error.
- Add a live BranchPrefixFeedback under the Branch Prefix setting: previews
  the resulting branch name, warns on invalid characters, and notes when a
  prefix collapses to none.
- Keep the background first-work rename on the non-throwing builder since the
  prefix is already validated at create time.

* Keep caret in place when editing the branch prefix

The custom branch prefix input was directly controlled by settings, but
updateSettings persists through an async IPC round-trip, so the value
updated a tick late and React re-assigned it, snapping the caret to the
end on mid-string edits. Drive the input from a local draft and only
adopt genuine external settings changes so the caret stays put (and fast
typing survives slow SSH round-trips).

Co-authored-by: Cursor <cursoragent@cursor.com>

* Return ReactNode from BranchPrefixFeedback

JSX.Element needlessly excludes null/string/number returns; ReactNode
keeps the component's return type from over-constraining future changes.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants