fix(cli): sync footer branch name on filesystems without fs.watch events

[manumishra12]

Summary

The footer Branch indicator does not update after a git checkout on filesystems where fs.watch delivers no change events — most notably WSL mounts of Windows drives (/mnt/c/...) and network shares. The displayed branch stays stuck on whatever was checked out when the CLI started.

Fixes #27957

This supersedes #28012, which was auto-closed by the stale bot after 14 days without a help wanted label on the linked issue (GitHub would not let me reopen it). The branch has been rebased onto the latest main; the diff is unchanged (+112/-7, 2 files). The fs.unwatchFile cleanup point raised by gemini-code-assist on #28012 is already addressed here (the poll listener is stored and passed explicitly to fs.unwatchFile).

Details

useGitBranchName already watches the git directory with fs.watch and re-fetches the branch when HEAD changes. But fs.watch relies on the OS notification layer (inotify on Linux, FSEvents on macOS), and on WSL mounts of Windows drives and on many network filesystems that layer delivers no events at all — so the watcher silently never fires and the branch is never refreshed (the environment in #27957 is WSL).

This adds a stat-based fs.watchFile poll on HEAD as a reliable fallback that works regardless of the underlying filesystem, running alongside the existing fs.watch (which remains the fast, event-driven path where it works):

• Both paths funnel into a single debounced scheduleRefresh() helper (no behavior change to the existing fast path).
• The poll only refreshes when HEAD's mtime actually changes, so steady state does no work.
• Poll interval is 2s (a single stat of a tiny file; negligible cost).
• The poll is torn down on unmount via fs.unwatchFile, passing the exact listener so only this hook instance's watcher is removed.

No changes are needed in the footer component or UI state — they already react to whatever the hook returns.

How to Validate

Manual (on WSL with the repo under /mnt/<drive>, on a network share, or any affected FS):

1. Start gemini in a git repo and note the branch shown in the footer.
2. Switch branches, e.g. ! git checkout -b some-branch (or in another shell).
3. Expected: within ~2s the footer reflects the new branch. Before this change it stayed on the old branch on affected filesystems.

Automated:

npm run --workspace packages/cli test -- src/ui/hooks/useGitBranchName.test.tsx

A new test covers the polling fallback (when fs.watch never fires), and the cleanup test is extended to assert the poll is removed on unmount.

Pre-Merge Checklist

• Prettier, ESLint (--max-warnings 0) and TypeScript typecheck pass for the changed files.
• Unit tests added and passing (useGitBranchName.test.tsx, plus Footer.test.tsx consumers).
• Change is scoped to a single hook; no public API changes.
• Linked issue: Checkout git branch not reflected in CLI UI #27957

[github-actions]

📊 PR Size: size/M

• Lines changed: 119
• Additions: +112
• Deletions: -7
• Files changed: 2

[gemini-code-assist]

Summary of Changes

Hello, 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 addresses an issue where the CLI's footer branch indicator fails to update on specific filesystems that do not emit fs.watch events. By implementing a secondary, polling-based monitoring strategy for the HEAD file, the hook now reliably detects branch changes across all environments while maintaining the existing event-driven path for performance where available.

Highlights

• Reliable Branch Updates: Introduced a stat-based polling fallback using fs.watchFile on the HEAD file to ensure the branch indicator updates correctly on filesystems where fs.watch events are not supported, such as WSL mounts and network shares.
• Efficient Polling: The new polling mechanism only triggers a refresh when the mtime of the HEAD file changes, ensuring minimal performance impact during steady-state operation.
• Improved Resource Management: Added explicit cleanup logic to tear down the polling watcher using fs.unwatchFile upon unmounting, preventing potential memory leaks or redundant processes.

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 the 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 counterproductive. 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.

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. ↩

[manumishra12]

Reviving this from #28012, which the stale bot auto-closed after 14 days before it could get a review (GitHub wouldn't let me reopen it, so this is a fresh PR rebased on the latest main).

#27957 is a bot-triaged kind/bug at priority/p2 (area/core, effort/medium) and is still unassigned. The fix is small and scoped to the useGitBranchName hook — a fs.watchFile HEAD-poll fallback for filesystems where fs.watch delivers no events (WSL /mnt drives, network shares) — with tests, and the gemini-code-assist review point from the earlier PR is already addressed.

Would a maintainer be open to labeling #27957 help wanted so this can be reviewed before the stale bot closes it again? cc @DavidAPierce — happy to adjust anything needed. Thanks!

[gemini-code-assist]

Code Review

This pull request introduces a fallback polling mechanism to the useGitBranchName hook using fs.watchFile to monitor changes to the Git HEAD file. This ensures that the branch name updates correctly on filesystems where fs.watch does not reliably deliver events, such as WSL mounts or network shares. Corresponding unit tests have been added and updated to verify the polling behavior and ensure proper cleanup of the file watcher on unmount. I have no feedback to provide.

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'.

This PR will be closed in 7 days if it remains without that designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.