Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: document forge detection design and SSH alias gap (#1793)
worktrunk-bote55850186c3f
diff --git a/src/git/repository/remotes.rs b/src/git/repository/remotes.rsindex 13955f24b..5e4560239 100644--- a/src/git/repository/remotes.rs+++ b/src/git/repository/remotes.rs@@ -1,21 +1,72 @@//! Remote and URL operations for Repository.//!-//! # Forge resolution and `url.insteadOf`+//! # Forge detection//!-//! Worktrunk needs to identify the forge (GitHub, GitLab) behind a remote URL-//! for PR status, API calls, and push-remote detection. This is straightforward-//! when the raw URL contains a recognized hostname (`github.com`, `gitlab.com`,-//! etc.), but breaks when users configure `url.insteadOf` for multi-key SSH-//! setups — the raw URL may contain a custom hostname like `github-work`.+//! Worktrunk needs three pieces of information from remote URLs://!-//! All forge-aware lookups use [`effective_remote_url`](Repository::effective_remote_url),-//! which runs `git remote get-url <name>` to get the URL with `url.insteadOf`-//! rewrites applied. This is a local operation (no network I/O). Results are-//! cached per-remote in [`RepoCache`](super::RepoCache), so repeated lookups-//! for the same remote cost nothing after the first call.+//! 1. **Platform** — GitHub or GitLab (determines which CLI/API to use)+//! 2. **Hostname** — which server to talk to (for `gh api --hostname`,+//! `glab auth status --hostname`)+//! 3. **Owner/repo** — the project path (for API calls and remote matching)//!-//! When no `insteadOf` rules are configured, the effective URL equals the raw-//! config URL — there is no behavioral difference.+//! All three are extracted from the remote URL's hostname via substring+//! matching: [`is_github()`](super::GitRemoteUrl::is_github) checks if the+//! host contains `"github"`, [`is_gitlab()`](super::GitRemoteUrl::is_gitlab)+//! checks for `"gitlab"`. This covers `github.com`, GitHub Enterprise+//! (`github.mycompany.com`), `gitlab.com`, and self-hosted GitLab+//! (`gitlab.example.com`).+//!+//! ## Where each piece is resolved+//!+//! | Need | `wt switch pr:N` | `wt list` CI status |+//! |------|------------------|---------------------|+//! | Platform | Implicit (user typed `pr:` or `mr:`) | [`platform_for_repo`] in `ci_status::platform` |+//! | Hostname | [`fetch_pr_info`] extracts from effective URL | `gh`/`glab` infer from `current_dir` |+//! | Owner/repo | API response provides it | [`github_owner_repo`] / [`find_forge_remote`] |+//! | Remote matching | [`find_remote_for_repo`] matches API response back to local remote | Not needed |+//!+//! [`platform_for_repo`]: crate::commands::list::ci_status::platform::platform_for_repo+//! [`fetch_pr_info`]: crate::git::remote_ref::github+//! [`github_owner_repo`]: crate::commands::list::ci_status::github+//!+//! ## SSH host aliases+//!+//! Multi-account SSH setups use host aliases (`git@github-personal:owner/repo`)+//! where SSH resolves `github-personal` → `github.com` via `~/.ssh/config`.+//! Git operations work, but the literal hostname breaks forge detection:+//!+//! - **Platform detection** fails if the alias doesn't contain `"github"` or+//! `"gitlab"` (e.g., `work`). Override with `ci.platform` in project config.+//! - **`gh api --hostname`** receives the alias instead of the real hostname.+//! If the alias contains `"github"` (e.g., `github-personal`), `gh` gets+//! `--hostname github-personal` and fails. If not (e.g., `work`), we fall+//! back to `github.com` which works for non-Enterprise repos.+//! - **Remote matching** fails when comparing `github.com` (from API response)+//! against `github-personal` (from local remote URL).+//!+//! ### `url.insteadOf` (current solution)+//!+//! Git's `url.insteadOf` rewrites URLs before any tool sees them:+//!+//! ```text+//! git config url."[email protected]:".insteadOf "git@github-personal:"+//! ```+//!+//! After this, [`effective_remote_url`](Repository::effective_remote_url)+//! (which runs `git remote get-url`) returns the rewritten URL with the real+//! hostname. All forge detection, API calls, and remote matching work.+//!+//! Trade-off: `url.insteadOf` also affects SSH, which sees `github.com`+//! instead of the alias and can't select the correct `IdentityFile`. Users+//! must pair it with per-repo `core.sshCommand` to restore key routing.+//!+//! ### Known gap+//!+//! SSH host aliases without `url.insteadOf` are partially unsupported. The+//! hostname and remote matching steps fail because `effective_remote_url`+//! returns the alias unchanged. Owner/repo extraction is unaffected (aliases+//! only change the host, not the path). A future fix could resolve aliases+//! via `ssh -G <host>` or a config option; see issue #1790.//!//! ## URL methods//!@@ -24,6 +75,8 @@//! - `effective_remote_url` — `git remote get-url`, with `insteadOf` applied//! (cached; use for all forge detection)//! - `find_forge_remote(pred)` — search all remotes using effective URLs+//! - `find_remote_for_repo(host, owner, repo)` — match API response back to+//! local remote (checks both raw and effective URLs)use anyhow::Context;