# Gemini CLI Git Worktrees Discussion Transcript ## Overview This document captures a discussion regarding the new experimental native Git Worktree support in the Gemini CLI and whether it makes the custom `_ux_git-worktree` skill obsolete for the UX team. ### Skill Information **Path:** `packages/extensions/ux-extension/skills/_ux_git-worktree/SKILL.md` **High-Level Description:** The `_ux_git-worktree` skill manages a specific "Base Folder Strategy" for the engineering team. Rather than nesting worktrees inside a hidden `.gemini` folder, it enforces that all functional work occurs in sibling sub-directories (e.g., `main/`, `feature-name/`). It automates creating new task branches, checking out GitHub PRs into semantically named folders (e.g., `pr-123-fix-core-bug`), and automatically running `npm install` to ensure the isolated environment is immediately ready for development. It also handles macOS sandbox pathing requirements. --- ## Discussion Transcript **User:** Take a look at this new feature of Gemini CLI, and let me know if you think it makes our git-worktree skill obsolete. https://geminicli.com/docs/cli/git-worktrees/ **Gemini CLI:** Based on the documentation for the new native Git Worktree feature and the specific rules defined in your `_ux_git-worktree` skill, **no, it does not make your custom skill obsolete.** While the new native feature is great for general-purpose isolation, your `_ux_git-worktree` skill enforces highly specific, project-tailored workflows that the native feature doesn't cover out-of-the-box: 1. **Directory Structure (The "Base Folder" Strategy):** The native CLI creates worktrees hidden away in `.gemini/worktrees/`. Your skill strictly enforces that worktrees must be **sibling directories** to `main/` (e.g., `../feature-name/`). 2. **Semantic PR Checkouts:** Your skill uses a custom `worktree-manager.sh` script to automatically fetch PR titles and create human-readable, semantic directory names (like `pr-123-fix-core-bug`). The native CLI does not integrate with GitHub PRs in this way. 3. **Mandatory Environment Setup:** Your skill enforces a mandatory `npm install` immediately after a worktree is created to ensure the environment is ready for development. 4. **macOS Sandbox Management:** Because your worktrees live outside the immediate repository container as sibling folders, your skill includes specific logic to ensure the primary `../main/.git` path is added to the trusted environment to bypass macOS sandbox restrictions. **Recommendation:** The native `--worktree` flag is an excellent feature for standard use cases, but for the rigorous, standardized workflows required by the UX Extension in this repository, you should continue using your custom `_ux_git-worktree` skill to maintain compliance with the "Base Folder" architecture. **User:** Let's back up a step. My goal is for the UX team that uses this extension to be able to use git worktrees following the standard team convention (i.e. the whole eng team will use this worktrees feature). We don't want to duplicate or recreate the feature with our skill, nor do we want to diverge from standard team practice. The exception is that I'd like the UX team (and end users potentially) to be able to create and use worktrees with natural language. Let's take a user-journey approach to designing the experience. Start by creating a list of the use-cases/journeys that users will want to do with worktrees. My current behavior is: 1. I want to create a new worktree to work on a new feature. I have a name in mind, and I want to start from main. Its nice that I can use gemini cli interactive mode and say 'new worktree called blahblah' and i dont have to remember a specific syntax, but also the startup time maybe means I should just learn the syntax. It seems simple. Its convenient that it runs npm install to save me a step, but not critical. 2. I want to create a new worktree by cloning someone's branch/PR to my local machine. Its easy for me to run gemini cli interactive mode and say 'create a new worktree from http://PRURL and call it blahblah. Again, the npm install is convenient. In this case Im not sure how to do this in noninteractive mode. 3. I want to see all the worktrees ive created locally, and its handy i can look at my folders, becuase it basically represents a list of my projects/features im working on. Im not sure how this could be done in noninteractive mode, so I would worry about losing my work in progress. its kind of confusing if my worktrees are in gemini's hidden folder. It would be great if there was a way to see my worktrees within gemini cli interactive and non interactive mode. So as a worktree novice, and someone who has not tested this experimental feature still, I may be misunderstanding things. Would you please create a list of use-cases that includes mine, as well as any key ones im missing? Under each use-case, identify whether its supported by the experimental feature in both interactive and noninteractive modes. **Gemini CLI:** This is a great approach. Stepping back to look at the user journey is the best way to determine if a feature genuinely serves the team's workflow or just adds unnecessary complexity. Based on your current workflow, the documentation for the new experimental feature, and standard Git worktree lifecycles, here is a breakdown of the key user journeys. ### 1. Create a new worktree for a new feature (from `main`) **User Goal:** Spin up an isolated environment to start fresh work, optionally with a specific name, without messing up the primary `main` branch. - **Experimental Native Feature (Non-Interactive):** **Supported.** You launch Gemini with `gemini --worktree `. It automatically creates a new branch and a linked directory in `.gemini/worktrees/`. _(Note: It does not automatically run `npm install` like your current skill does)._ - **Experimental Native Feature (Interactive):** **Partially Supported.** You cannot start a standard `gemini` session and then type a native slash command (like `/worktree new`) to instantly pivot the current session into a worktree. You must use the `--worktree` flag _when launching_ the CLI. However, once inside any interactive session, you can always just ask the agent in natural language to run standard `git worktree add` commands for you. ### 2. Create a worktree from a remote branch or PR **User Goal:** Review a teammate's PR or continue work on a remote branch without stashing current local changes. - **Experimental Native Feature (Non-Interactive):** **Not Supported Natively.** The `--worktree` flag only creates _new_ branches from your current HEAD. It does not accept a PR URL or remote branch name. You would have to manually fetch the remote branch and use standard `git worktree add` commands before launching Gemini. - **Experimental Native Feature (Interactive):** **Not Supported Natively.** Again, the native feature lacks a "PR-to-worktree" pipeline. To do this with natural language, you still rely on the AI agent running shell commands (which is exactly what your `_ux_git-worktree` skill automates so reliably). ### 3. Discoverability: View existing local worktrees **User Goal:** See a list of all active projects/features currently in progress. - **Experimental Native Feature (Non-Interactive):** **Supported (but hidden).** The native feature stores worktrees inside `.gemini/worktrees/`. Because this is a hidden directory, you won't see your projects when doing a standard `ls` in your file explorer. You have to explicitly check that hidden path or run standard `git worktree list`. - **Experimental Native Feature (Interactive):** **Supported.** You can ask the agent, "What worktrees do I have open?" and it will run `git worktree list` to tell you. ### 4. Resume work on an existing worktree _(Missing Use-Case)_ **User Goal:** Switch context back to a feature you started yesterday. - **Experimental Native Feature (Non-Interactive):** **Supported.** You have to manually `cd` into the hidden `.gemini/worktrees/` directory and run `gemini` again. - **Experimental Native Feature (Interactive):** **Supported.** If you want to resume the exact AI conversation you were having in that worktree, you navigate to the hidden folder and launch with `gemini --resume `. ### 5. Clean up / Delete a finished worktree _(Missing Use-Case)_ **User Goal:** After a PR is merged, delete the local branch and the isolated folder to free up space. - **Experimental Native Feature (Non-Interactive):** **Not Supported.** The documentation explicitly states Gemini does not automatically clean up worktrees. You must manually run `git worktree remove --force` and `git branch -D `. - **Experimental Native Feature (Interactive):** **Not Supported Natively.** You can ask the AI agent to run the cleanup commands for you, but there is no native garbage collection. --- ### The Verdict for Your Team You are not misunderstanding things; your concerns are spot on. The new native `--worktree` feature is designed primarily for **AI isolation**—giving the agent a safe sandbox so it doesn't break the user's main repository while generating code. Because it hides these folders in `.gemini/worktrees/`, it treats them as ephemeral AI scratchpads rather than primary developer workspaces. Your team's **"Base Folder Strategy"** (creating sibling folders like `../feature-name/`) is designed for **Developer ergonomics**. It keeps projects visible, integrates directly with PR workflows, and handles environment setup (`npm install`). **Conclusion:** The native feature does _not_ replace your skill. If you adopt the native feature, your team will lose the PR checkout automation, the automatic dependency installation, and the visibility of having worktrees as top-level sibling folders. You should keep your `_ux_git-worktree` skill to maintain your team's specific, natural-language-driven engineering standards.