Visualize and manage Git worktrees and submodules in Files

[dnviti]

Problem / Motivation

Developers using Git worktrees and submodules cannot understand repository relationships, inspect important state, or manage these resources from Files. They must leave the app and rely on terminal workflows that lack the app’s navigation, safeguards, recovery, and activity context.

These workflows arise infrequently for many users, but the friction is substantial and recurring when they do arise—especially when parallel agent work spans multiple worktrees or a repository contains nested submodules.

Goal

Make Files the place where workspace owners can visualize, browse, and safely manage Git worktrees and submodules across desktop and phone.

The experience makes complex repository topology understandable through progressive disclosure, preserves at-risk work before destructive actions, supports recovery when operations fail, and keeps ordinary file browsing available when repository-specific functionality encounters an error.

Scope

Repository topology

• Add an expandable repository topology to Files, anchored at the outermost repository containing the current session.
• Present worktrees as top-level roots and submodules inline beneath the worktree that contains them.
• Discover nested submodules recursively for every worktree and reveal deeper levels only when the user expands them.
• For an ordinary repository, show topology roots only when an additional linked worktree or a submodule exists. Otherwise, retain today’s ordinary file tree.
• Expand the current worktree initially and collapse other worktrees and submodules initially.
• Use progressive disclosure so the overview remains readable while every entry remains discoverable.
• Show a topology-only root for a bare repository.
• Refresh topology when Files opens, when associated agent activity becomes idle, after a successful action, and when the user requests it.
• Keep ordinary file browsing usable if topology inspection or an individual repository action fails.
• Show the full listed details for registered worktrees outside the user’s browsable area, while keeping those entries view-only and preventing navigation or management.

Each worktree shows:

• Whether it is the current worktree and where it is located.
• Its branch or detached revision.
• Whether it contains tracked or untracked changes.
• Whether its branch is ahead of or behind its upstream.
• Whether it is locked.
• Whether its registration is stale or eligible for pruning.

Each submodule shows:

• Its name and location.
• Whether it is initialized or missing.
• Its checked-out revision compared with the revision recorded by its parent repository.
• Whether it contains tracked or untracked changes.
• Its branch or detached revision.
• Its remote identity and divergence when available.

Worktree management

Workspace owners can:

• Browse an accessible worktree.
• Create a worktree from an existing branch, a new branch, a commit, or a tag.
• Lock and unlock a worktree.
• Remove a worktree.
• Prune stale worktree registrations.

Locations for worktrees created by the app are managed by the app. By default, each repository may have up to 20 app-created worktrees; the installer may change this limit. Existing worktrees and worktrees created outside the app remain visible and manageable after the limit is reached.

Before creation, refresh remote branch information. If that refresh fails, explain that the available information may be stale, offer retry, and allow creation from locally known revisions. If the selected branch is already checked out, direct the user to its existing worktree instead of creating a duplicate.

Creating a worktree adds it to the topology without moving the user away from their current position in Files.

When active sessions or agents use a worktree selected for removal, offer to stop that work before continuing. A locked worktree can be unlocked and removed through one explicit destructive confirmation.

Worktree removal may also delete its associated branch. Deleting a branch whose commits are not merged elsewhere requires automatic recovery and an additional destructive confirmation.

Submodule management

Workspace owners can:

• Browse an accessible initialized submodule.
• Initialize a submodule.
• Restore it to the revision recorded by its parent repository.
• Update it from its remote.
• Synchronize its saved remote identity.
• Deinitialize it.

Updating from a remote uses the submodule’s configured tracking branch and otherwise falls back to the remote’s default branch. The action previews the resulting revision before applying it.

Actions affect the selected submodule by default. The user may explicitly include nested submodules. A recursive action stops at its first failure, keeps completed changes, identifies untouched entries, and offers retry for the remainder.

Safe actions and recovery

• Require confirmation for actions that remove resources, discard work, update from a remote, or otherwise create meaningful risk. Safe actions run directly.
• Show progress for longer actions, allow cancellation while cancellation remains safe, and offer retry after failure.
• Before an action can discard unmerged or otherwise at-risk work, preserve all affected tracked and untracked work automatically on a uniquely named recovery branch that never overwrites an existing branch.
• Preserve remotely using the affected branch’s tracking remote, falling back to the repository’s primary remote.
• If remote preservation fails during an ordinary user action, retain the recovery locally, explain that it is not protected remotely, and continue.
• Keep a recovery list covering the entire outer repository, including recoveries created inside submodules, grouped by worktree and submodule.
• Retain recovery points until a workspace owner deliberately deletes them.
• Block restoration when the destination contains newer uncommitted work.
• Delete both local and remote recovery copies after confirmation, but refuse deletion when either copy has changed since it was displayed.
• Refuse an action whose displayed repository state has become stale, refresh the topology, and require a new decision.
• Leave repository state unchanged when an individual remote management action fails, explain the failure, and offer retry.
• Keep local inspection and local-only management available while offline.

Project lifecycle

• Preserve and recreate app-managed worktrees when a repository-backed project is rebuilt or reclaimed.
• Restore the previously initialized submodule topology and selected revisions, while leaving recovered dirty work unapplied for deliberate review.
• If dirty work cannot be preserved remotely before a rebuild, explain exactly what remains unprotected and allow the user to explicitly discard it and continue.
• If one linked worktree cannot be recreated, keep the project available, show that entry as unavailable with its reason, and offer retry or removal.

Access and operational history

• Every workspace owner can manage repositories within their browsing permissions.
• Registered worktrees outside those permissions remain view-only even though their topology details are visible.
• Keep a durable, per-repository history showing each management action, its outcome, any recovery created, and who initiated it.
• Make history visible to the workspace owner and installer.
• Retain history for 90 days. Only the installer may delete history before the retention period ends.
• Treat this history as an operational record only. Add no usage analytics or telemetry.

Cross-device and inclusive use

• Provide the complete topology, management, error, and recovery experience on desktop and phone.
• Give keyboard, screen-reader, touch, and non-color cues equivalent access to topology, state, actions, progress, errors, and recovery.
• Make all new user-facing content ready for translation.

Non-goals

• Turning Files into a general-purpose Git client beyond the branch actions required for worktree creation, removal, and recovery.
• Adding a commit-history graph.
• Moving worktrees or repairing registrations after folders are moved outside the app.
• Adding or removing submodule declarations.
• Cloning repositories or discovering unrelated repositories globally.
• Sharing worktrees, submodules, or recovery points directly between users.
• Providing equivalent management through a terminal interface, command-line interface, or public API.
• Introducing product usage analytics or telemetry.

Security / Safety Considerations

• Repository management actions respect the user’s existing browsing permissions.
• Showing the full details of an inaccessible registered worktree is a deliberate visibility choice; it never grants file access or management capability.
• Destructive and potentially destructive actions identify exactly what will change before confirmation.
• Recovery branches never overwrite existing branches.
• Pushing a recovery branch sends the preserved work to the repository’s configured remote and may make it visible to collaborators with access to that remote. The preservation target is shown before confirmation.
• Recovery restoration never overwrites newer uncommitted work.
• Recovery deletion requires confirmation and current-state verification for both local and remote copies.
• Stopping active sessions or agents is explicit and occurs before removing their worktree.
• A project rebuild never silently discards work that could not be preserved remotely.
• Operational history remains limited to the workspace owner and installer, expires after 90 days, and is not used as telemetry.

Acceptance Criteria

• Files shows worktrees as top-level roots and submodules inline beneath their containing worktrees, anchored at the outermost repository containing the session.
• An ordinary repository with no additional linked worktree and no submodule retains today’s file tree without an extra topology layer.
• The topology recursively reveals nested submodules for every worktree as the user expands them.
• The current worktree starts expanded; other worktrees and nested submodules start collapsed.
• A bare repository shows topology and management without pretending it has ordinary files to browse.
• Every worktree displays its current marker, location, branch or detached revision, tracked and untracked state, upstream divergence, lock state, and stale or prunable state.
• Every submodule displays its name, location, availability, recorded and checked-out revisions, tracked and untracked state, branch or detached revision, remote identity, and available divergence.
• Topology refreshes when Files opens, after associated agent activity becomes idle, after successful actions, and on manual request.
• Large topologies progressively reveal all entries without locking the Files experience or silently omitting results.
• A topology or action failure remains scoped to the affected experience, explains the failure, offers retry, and leaves ordinary file browsing usable.
• Inaccessible registered worktrees show their full topology details but provide no browsing or management actions.
• Workspace owners can create, browse, lock, unlock, remove, and prune worktrees within their permissions.
• Worktree creation supports existing branches, new branches, commits, and tags, uses an app-managed location, and leaves the user at their current Files position.
• The default limit of 20 app-created worktrees per repository is enforced and installer-configurable without hiding or disabling existing or externally created worktrees.
• Worktree creation refreshes remote branch information, continues with locally known revisions after an explained refresh failure, and redirects to the existing worktree when the branch is already checked out.
• Worktree removal can stop active sessions or agents after confirmation.
• A locked worktree can be unlocked and removed through one explicit destructive confirmation.
• Worktree removal offers associated-branch deletion, and deleting an unmerged branch requires recovery plus an additional destructive confirmation.
• Workspace owners can browse, initialize, restore, remotely update, synchronize, and deinitialize accessible submodules.
• A submodule remote update previews the resulting revision and uses its configured tracking branch or the remote default branch.
• Submodule actions target only the selected entry by default, with explicit recursive opt-in.
• A failed recursive submodule action keeps completed work, stops at the first failure, reports the remainder, and supports retry.
• Risky actions preserve all affected tracked and untracked work on unique, non-overwriting recovery branches using the agreed remote and local-fallback behavior.
• The recovery list covers the outer repository and nested submodules, groups recovery points by worktree and submodule, and retains them until deliberate deletion.
• Recovery restoration is blocked when newer uncommitted work exists at the destination.
• Recovery deletion removes local and remote copies after confirmation and is refused when either displayed copy is stale.
• Stale action dialogs refresh before retrying, and a failed individual remote action explains the failure without applying its requested state change.
• Longer actions show progress, support cancellation while safe, and support retry after failure.
• Local inspection and local-only actions remain usable offline.
• Rebuilding or reclaiming a project recreates app-managed worktrees and the prior initialized submodule topology and selected revisions without automatically applying recovered dirty work.
• Failed pre-rebuild remote preservation identifies the unprotected work and requires explicit permission before discarding it.
• A failed worktree recreation does not block the project from opening and offers retry or removal for that unavailable entry.
• Successful actions refresh topology and appear in the repository’s operational history with their outcome, initiator, and associated recovery.
• Operational history is visible to the workspace owner and installer, retained for 90 days, and deletable early only by the installer.
• No usage analytics or telemetry is introduced.
• Desktop and phone provide equivalent topology, browsing, management, error, and recovery capabilities.
• All functionality is operable by keyboard, screen reader, and touch, and no meaning depends on color alone.
• User-facing content is ready for translation.
• User documentation explains topology states, management actions, recovery behavior, permissions, limits, and project-rebuild behavior.
• A changelog entry, support notes, and desktop and phone screenshots are complete.
• A combined real-world demonstration covers detached, dirty, locked, and stale worktrees plus recursive submodules in clean, changed, missing, and revision-mismatched states.
• Any project maintainer can verify these criteria and sign off on completion.

Suggested Phasing

1. Topology and browsing — deliver the expandable Files topology, complete state visibility, permission-aware browsing, progressive loading, refresh behavior, and scoped failures.
2. Management and recovery — deliver worktree and submodule actions, safeguards, progress and retry behavior, recovery branches, project recreation behavior, and offline local workflows.
3. History and readiness — deliver operational history, desktop and phone parity, accessibility and translation readiness, documentation, changelog, support notes, screenshots, and the combined workflow demonstration.