Repositories & Git Worktrees

The sidebar and everything in it: adding projects, and creating, opening, archiving, and deleting git worktrees — the unit of work you hand to an agent.

Keywords:repositoryrepoworktreebranchsidebaradd repositorynew worktreearchivedeletepinplain foldernon-gitbase branchgit-wtwt

Related: concepts · terminal · custom-actions · github-pull-requests · settings-fields

What it is#

The left sidebar lists your repositories, each expandable into its worktrees. A repository is a git project (or a plain non-git folder) you’ve added. A worktree is one branch checked out into its own directory, so multiple branches are live on disk at once — ideal for giving each agent its own branch.

Within a repository, worktrees are grouped: Main (the repo root), Pinned, Pending (being created), and the rest. Each row shows the name, branch detail, an unread-notification bell, and run/agent status.

Repository kinds#

A plain folder can’t expand; clicking it just opens a terminal there. Prowl auto-detects which kind a path is when you add it (it runs git to find the repo root; “not a git repository” → plain folder). If you later run git init in an open plain folder, Prowl automatically upgrades it to a git repository and refreshes the sidebar.

Adding a repository#

• Shortcut: ⌘⇧O (open_repository)
• Toolbar: the Add… button (folder-with-plus icon) at the top of the sidebar. Use the popover to browse for a local folder, drag a folder onto the drop zone, clone a remote git URL into a chosen directory, or start workspace creation.
• Command Palette: “Open Repository”.

Pick one or more directories. Prowl detects git vs plain, de-duplicates, and persists the list. Paths that don’t exist or can’t be read are reported in an alert after the load. Repositories added after the initial app load are selected automatically. If a repository was added through a symbolic link, Prowl resolves and stores its actual git root so branches and worktrees continue to load.

Creating a worktree#

• Shortcut: ⌘N (new_worktree)
• Button: the + on a repository’s header (only for git repos that support worktrees).
• Context menu: right-click a repository header → “New Worktree”.
• Command Palette: “New Worktree”.

By default a creation prompt appears (controlled by promptForWorktreeCreation) where you:

• enter a branch name (leave blank to auto-generate, e.g. bold-cat-523). On devices with Apple Intelligence, an on-device AI suggestion may appear below the field based on your repository context and recent terminal activity — click Use to adopt it,
• choose the base ref (branch/tag) to branch from,
• optionally fetch the remote first.

An optional, default-collapsed Advanced section lets you override where the worktree lands:

• Worktree name — the leaf folder name (defaults to the branch name).
• Parent folder — the directory it’s created in (defaults to the repo’s resolved base directory).

Leave both blank to keep the default base/<branch> placement. The footer shows the full destination path as you type, or an inline error (the worktree name is a single folder, so slashes, ./.., and .git are rejected).

Press ↩ to create, Esc to cancel. Branch names are validated live (git check-ref-format).

Creation runs through the bundled wt CLI (Resources/git-wt) and streams progress through stages: reading local branches → choosing a name → checking repo mode → resolving the base ref → fetching → creating. A Pending row shows the live status until it’s ready.

Copying uncommitted files: new worktrees can optionally copy .gitignore’d files (copyIgnoredOnWorktreeCreate) and/or untracked files (copyUntrackedOnWorktreeCreate) from the source — set globally or per repo.

Setup script: if the repo defines a setup script, it runs automatically in the new worktree (see custom-actions).

Selecting & switching worktrees#

• Click a row to select it (focuses its terminal).
• ⌃1–⌃9 jump to worktree 1–9.
• ⌘⌃↓ / ⌘⌃↑ select next / previous worktree.
• ⌘⌥[ / ⌘⌥] go back / forward through worktree selection history.
• ⌘⇧L reveals the currently focused worktree in the sidebar.

Pinning & ordering#

• Pin / Unpin: hover a worktree → pin button, or right-click → “Pin to top” / “Unpin”. Pinned worktrees sit in a section above the rest. (Not available for the main worktree.)
• Reorder: drag repositories or worktrees to rearrange; a thin accent line shows the drop target. Order is persisted.
• Expand / Collapse: click the chevron on a repo header, or cycle the sidebar’s header button: from all-collapsed it offers Expand Active (double chevron » — expands only repos/workspaces that have open terminal tabs), then Expand All (single chevron ›), then Collapse All (chevron rotated down). Expand Active is skipped when no repo (or every repo) has open tabs. Collapsed state is remembered.
• Tab count badges: a collapsed repo header shows its total open-tab count; expanding a git repo moves the count onto the individual worktree rows (hidden at zero). Workspaces and plain folders always show the count on the header.

Archiving a worktree#

Archiving hides a worktree from the main list without deleting it.

• Right-click the row → “Archive Worktree” (or “Archive Selected Worktrees” with a multi-selection). No default keyboard shortcut.
• If the branch is already merged, Prowl archives immediately without asking.
• If the repo defines an archive script, it runs first (live progress); if it fails, archiving stops and the worktree stays active.
• View archived: ⌘⌃A toggles the Archived Worktrees panel (press again to return to the previous worktree), grouped by repo, with Unarchive and Delete Selected (⌘⇧⌫) buttons.
• Auto-delete: if archivedAutoDeletePeriod is set, archived worktrees older than the period are deleted automatically.

The main worktree cannot be archived.

Deleting a worktree#

Deleting removes the worktree directory (and optionally its branch).

• Right-click the row → “Delete Worktree”, or ⌘⇧⌫.
• A confirmation dialog offers an “Also delete local branch” toggle (its tooltip notes git branch -d). The toggle remembers the last confirmed choice (deleteBranchOnManualWorktreeDelete in UserDefaults; defaults to off).
• Prowl removes the worktree (relocating + git worktree prune if needed), then verifies that Git no longer registers it. Cleanup failures keep the worktree visible and show Git’s error. If branch deletion is rejected because the branch isn’t merged, Prowl offers a force delete (git branch -D).
• Protected branches (main, master, and the detected default) are guarded.

The main worktree cannot be deleted.

Removing a repository#

Right-click a repo header → “Remove Repository” (or the ⋯ menu). This removes it from Prowl (closing its open terminals); it does not delete files on disk.

Opening a worktree in another app#

⌘O opens the worktree with the selected open action. When the action is Automatic (the default), Prowl inspects the worktree’s top-level files and prefers an app matching the project type: Flutter (pubspec.yaml with a flutter: key) → Android Studio (then IntelliJ, then the VS Code family), React Native (package.json depending on react-native plus an ios/ or android/ folder) → VS Code family (then WebStorm, then Android Studio), Unity (ProjectSettings/ProjectVersion.txt at the root or one folder down, covering SDK repos that keep the Unity project beside tooling manifests) → Rider (then the VS Code family), .xcodeproj/.xcworkspace/ Package.swift/Project.swift → Xcode, Gradle files → Android Studio (then IntelliJ IDEA, then IDEA EAP), *.sln/*.csproj → Rider, pom.xml → IntelliJ IDEA (then IDEA EAP), go.mod → GoLand, Cargo.toml → RustRover, CMakeLists.txt → CLion, composer.json → PhpStorm, Gemfile → RubyMine, Python manifests → PyCharm, package.json → WebStorm. If the matching app isn’t installed (or no project type is detected), it falls back to the generic priority — your first installed editor (Cursor → Zed → Zed Preview → VS Code → Windsurf → …), falling through to Xcode and then Finder only when no preferred app is found. Use the Open dropdown in the worktree’s detail toolbar to pick a different app (this pins it for the repo), or pick Automatic at the top of that dropdown to clear the pin and return to project-aware selection. You can also set a per-repo default (openActionID) / global default (defaultEditorID). Prowl detects: Finder, Terminal, $EDITOR, VS Code (+ Insiders), VSCodium, Cursor, Zed (+ Preview), Windsurf, Antigravity, Sublime Text, Nova, Xcode, Android Studio, JetBrains IDEs (IntelliJ IDEA and IDEA EAP, WebStorm, PyCharm, RustRover, Rider, GoLand, CLion, PhpStorm, RubyMine), GitHub Desktop / Fork / Tower / GitKraken / Sourcetree / Sublime Merge / SmartGit / GitUp, and terminals (Alacritty, Ghostty, iTerm2, Kitty, Warp, WezTerm). If the chosen app isn’t installed, Prowl shows an alert.

Other per-row context-menu items: Rename Branch… (⌘⇧M; the context menu targets that row, while the shortcut targets the selected worktree or focused Canvas card and is unavailable during bulk selection, worktree creation, or another modal prompt), New Terminal Tab (selects the worktree and opens a tab at the worktree root — unlike a plain new tab, it never inherits the focused tab’s current directory), Stop Running Script (only while a Prowl-tracked run script is running), Copy Path, Copy Branch Name, Reveal in Finder, Open Pull Request (only when the worktree has a PR), and Close All Tabs (disabled when the worktree has no tabs; uses the same active-agent / long-running-command confirmation as the tab bar’s “Close All”, and the confirmation names the target worktree).

The repository header menu (right-click, or the ⋯ button) offers New Worktree (git repos only), Repo Settings…, and Remove Repository. Plain folders and workspaces get Copy Path / Reveal in Finder instead of New Worktree; git repo headers deliberately have no path actions because a repository’s root can be a bare directory — use the worktree rows for paths.

Repository appearance (icon & color)#

In Repo Settings you can give each repository an icon (any SF Symbol from a curated set, a bundled asset, or your own image) and a color (10 presets or a custom color). The color tints the icon, the name, the Shelf spine (if shelfSpineTintFollowsRepositoryColor), and the window chrome (if windowTintMode = repositoryColor). You can also set a custom display title (customTitle) that overrides the folder name.

Automatic icon detection (detectRepositoryIconsAutomatically, default on): when a repository or folder is newly added, Prowl scans it locally in the background for a high-confidence product icon — an Icon Composer .icon bundle (flattened via QuickLook) or AppIcon.appiconset raster for Apple projects, an Android launcher raster, the iOS/Android assets of a Flutter or React Native project, Tauri bundle icons from src-tauri/tauri.conf.json, a package.json "icon" declaration, or a web manifest icon / rel=icon favicon / root logo for web projects — and silently sets it as the repo icon. For any other repository, a last generic tier accepts a near-square icon/logo/appicon image (svg/png/webp) at the root, assets/, or .github/; wide wordmark logos and banners are rejected by an aspect-ratio gate. Detection never runs for existing repositories, workspaces, or repos that already have an icon, and it never replaces a manual choice. Clear Icon removes a detected icon and suppresses re-detection; only removing and re-adding the repository triggers a fresh scan. Detected icons keep their original colors (they are never tinted, unlike user-picked SVGs/symbols).

Suggest an Icon… (Repository Icon menu): generates SF Symbol suggestions for the repository on-device from its README (falling back to the package manifest description, then the repo name). The picker sheet opens immediately with an inline loading state; results show the best pick plus four alternates, a reasoning line, and the input source. When Apple Intelligence is unavailable the results are labeled Keyword suggestions. Nothing is applied until you pick a symbol and confirm. Results are cached in memory for the session; Regenerate runs a fresh pass.

Lifecycle states (what the row can show)#

• Pending — worktree is being created (grey row, live stage text).
• Creating / Archiving / Removing — transient loading states with progress.
• Running — a Run Script or agent task is active in that worktree.
• Unread bell — the worktree has unseen notifications.

Settings that affect this area#

Global (Settings → Worktree / General) and per-repository (Repo Settings) — see reference/settings-fields.md for the full list. Highlights:

• promptForWorktreeCreation, fetchOriginBeforeWorktreeCreation
• defaultWorktreeBaseDirectoryPath / per-repo worktreeBaseDirectoryPath
• per-repo worktreeBaseRef (default base branch)
• copyIgnoredOnWorktreeCreate, copyUntrackedOnWorktreeCreate
• deleteBranchOnAutomaticCleanup, mergedWorktreeAction, archivedAutoDeletePeriod
• per-repo setupScript, archiveScript, openActionID, customTitle

Gotchas for agents#

• The main worktree (isMain) is special: no archive/delete/rename.
• Worktree names are auto-generated (adjective-animal-number) unless the user named them — don’t assume the name reflects the branch’s purpose.
• Removing a repository does not delete files; deleting a worktree does remove its directory (and optionally its branch).
• A worktree’s id is its path (with trailing-slash normalization) — the same identifier the prowl CLI uses.