Skip to content

git: add headLabelOverride to Repository API#306517

Open
RockyWearsAHat wants to merge 5 commits intomicrosoft:mainfrom
RockyWearsAHat:feature/git-head-label-override
Open

git: add headLabelOverride to Repository API#306517
RockyWearsAHat wants to merge 5 commits intomicrosoft:mainfrom
RockyWearsAHat:feature/git-head-label-override

Conversation

@RockyWearsAHat
Copy link
Copy Markdown

@RockyWearsAHat RockyWearsAHat commented Mar 30, 2026

Summary

Add headLabelOverride property to the Git extension's Repository API, allowing extensions to temporarily replace the label shown in the Source Control view's branch indicator.

Closes #306496

Problem

The Git extension derives its branch display label from the checked-out HEAD ref. Extensions that manage branch state externally — such as worktree managers, branch-per-chat session tools, or workspace isolation layers — cannot update the displayed branch name to reflect their logical context. This forces users to see misleading branch labels when the underlying checkout is managed programmatically.

Approach

Add a headLabelOverride property on the Repository interface:

repository.headLabelOverride = 'feature/my-work';   // override
repository.headLabelOverride = undefined;            // restore default

Implementation:

  • repository.ts: Private _headLabelOverride field with getter/setter. Setter fires _onDidChangeStatus so the Source Control view updates immediately. headLabel and headShortName getters check the override before falling back to HEAD state.
  • git.d.ts: headLabelOverride: string | undefined on the Repository interface.
  • api1.ts: Getter/setter on ApiRepository delegating to the internal repository.

Design notes:

  • The override is transient — it is not persisted across reloads. This is intentional: the extension that sets the override is responsible for re-applying it on activation.
  • Setting the override fires the same status-change event as a real branch switch, so existing listeners (status bar, SCM view) pick it up without additional wiring.
  • The override does NOT affect actual git operations. It is a display-only concern.

Use Cases

  • Worktree-based session isolation: An extension creates a worktree for each chat session and wants the SCM view to show the logical branch name rather than the detached-HEAD or worktree-internal branch.
  • Branch-per-chat workflows: When switching between chat contexts, the extension can instantly update the displayed branch without waiting for a real checkout.
  • Project scaffolding tools: During multi-step project setup, the tool can show a descriptive label like "Setting up..." instead of the actual branch name.
  • CI/CD preview branches: Extensions that spin up ephemeral branches for testing can label them meaningfully in the UI.

Testing

Manual verification that:

  1. Setting headLabelOverride updates the Source Control view branch label
  2. Setting it to undefined restores the original label
  3. Git operations use the real HEAD, not the override

@RockyWearsAHat
git: add headLabelOverride to Repository API
fd6dc2f 
Add a headLabelOverride property to the Git extension's Repository model.
When set, headLabel and headShortName return the override instead of the
real HEAD name. This is display-only — no git state is modified.

Use case: extensions managing worktrees per window/session need the status
bar to reflect the logical branch without actually checking it out.

Fixes microsoft#306496
Copilot AI review requested due to automatic review settings March 30, 2026 22:41
@RockyWearsAHat RockyWearsAHat mentioned this pull request Mar 30, 2026
Open
@vs-code-engineering
Copy link
Copy Markdown
Contributor

vs-code-engineering Bot commented Mar 30, 2026 •
edited
Loading

📬 CODENOTIFY

The following users are being notified based on files changed in this PR:

@lszomoru

Matched files:

  • extensions/git/src/api/api1.ts
  • extensions/git/src/api/git.d.ts
  • extensions/git/src/repository.ts
  • extensions/git/src/statusbar.ts

Copilot AI reviewed Mar 30, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Adds a new headLabelOverride property to the Git extension’s Repository API so extensions can temporarily override the branch label shown in SCM/status-bar display surfaces without changing the actual Git HEAD.

Changes:

  • Add headLabelOverride storage + getter/setter on the internal Repository model and have label getters consult it.
  • Expose headLabelOverride: string | undefined on the public Repository API type (git.d.ts).
  • Plumb the property through the API wrapper (ApiRepository) to the internal repository instance.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 4 comments.

File Description
extensions/git/src/repository.ts Implements the override field and wires it into headShortName/headLabel plus status-change event firing.
extensions/git/src/api/git.d.ts Extends the public Repository interface with the new headLabelOverride property and documentation.
extensions/git/src/api/api1.ts Adds getter/setter on ApiRepository to delegate headLabelOverride to the internal repository.

Comment thread extensions/git/src/repository.ts Outdated
Comment thread extensions/git/src/repository.ts Outdated
Comment thread extensions/git/src/repository.ts
Comment thread extensions/git/src/repository.ts Outdated
@RockyWearsAHat
fix: handle empty string override, no-op setter guard, document suffi…
d5d4f1e 
…x behavior

Address review feedback:
- Use !== undefined instead of truthiness check so empty string overrides work
- Add no-op guard in setter to avoid firing event when value unchanged
- Document in git.d.ts that override replaces entire label including suffixes
@RockyWearsAHat RockyWearsAHat force-pushed the feature/git-head-label-override branch from 074e0b7 to d5d4f1e Compare March 30, 2026 23:20
@RockyWearsAHat RockyWearsAHat requested a review from Copilot March 30, 2026 23:31
Copilot AI reviewed Mar 30, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 1 comment.

Comment thread extensions/git/src/repository.ts
@RockyWearsAHat
refactor: dedicated onDidChangeHeadLabel event for label overrides
72ad203 
Replace reuse of _onDidChangeStatus (onDidRunGitStatus) with a
dedicated _onDidChangeHeadLabel emitter so label changes are
semantically distinct from git-status refreshes.

- repository.ts: add _onDidChangeHeadLabel emitter, fire it from setter
- statusbar.ts: subscribe CheckoutStatusBar to onDidChangeHeadLabel
- api1.ts: forward onDidChangeHeadLabel to ApiRepository
- git.d.ts: expose onDidChangeHeadLabel in the public API
@RockyWearsAHat RockyWearsAHat requested a review from Copilot March 31, 2026 00:02
Copilot AI reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

Comment thread extensions/git/src/repository.ts
@RockyWearsAHat RockyWearsAHat requested a review from Copilot March 31, 2026 00:25
Copilot AI reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

Comment thread extensions/git/src/repository.ts
@RockyWearsAHat RockyWearsAHat requested a review from Copilot March 31, 2026 01:32
Copilot AI reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

At least 1 approving review is required to merge this pull request.

Assignees

@lszomoru lszomoru

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add headLabelOverride to Git Extension API

3 participants

@RockyWearsAHat @lszomoru