feat: add Gitea pull request support (gpr:)

Add support for Gitea pull requests via the new `gpr:<number>` syntax.

- Introduce `GiteaProvider` and `src/git/remote_ref/gitea.rs` to fetch PR metadata via the `tea` CLI.
- Add `PlatformData::Gitea` and wire Gitea handling into remote-ref resolution and branch creation logic.
- Expose `GiteaProvider` from `remote_ref` module and update PR remote discovery to handle GitHub/Gitea.
- Teach switch command parsing to accept `gpr:` shortcuts and update CLI docs/help text.
- Surface CLI syntax in error messages by adding `syntax` to relevant `GitError` variants.
- Add integration tests and snapshots for `gpr:` behavior, and unit tests for Gitea parsing helpers.
- Documentation updates to reference `gpr:` and note `tea` CLI requirement.

No breaking changes. The `gpr:` flow requires the `tea` CLI to be installed and authenticated.

Author: SjB

docs/content/switch.md

@@ -28,6 +28,7 @@ wt switch -                      # Previous worktree (like cd -)
 wt switch --create new-feature   # Create new branch and worktree
 wt switch --create hotfix --base production
 wt switch pr:123                 # Switch to PR #123's branch
+wt switch gpr:123                # Switch to Gitea PR #123's branch
 ```
 
 ## Creating a branch
@@ -64,13 +65,15 @@ wt switch --create temp --no-verify      # Skip hooks
 | `@` | Current branch/worktree |
 | `-` | Previous worktree (like `cd -`) |
 | `pr:{N}` | GitHub PR #N's branch |
+| `gpr:{N}` | Gitea PR #N's branch |
 | `mr:{N}` | GitLab MR !N's branch |
 
 ```bash
 wt switch -                      # Back to previous
 wt switch ^                      # Default branch worktree
 wt switch --create fix --base=@  # Branch from current HEAD
 wt switch pr:123                 # PR #123's branch
+wt switch gpr:123                # Gitea PR #123's branch
 wt switch mr:101                 # MR !101's branch
 ```
 
@@ -128,6 +131,18 @@ Requires `gh` CLI to be installed and authenticated. The `--create` flag cannot
 
 **Fork PRs:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
 
+## Gitea pull requests
+
+The `gpr:<number>` syntax resolves the branch for a Gitea pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches `refs/pull/N/head` and configures `pushRemote` to the fork URL.
+
+```bash
+wt switch gpr:101                # Checkout Gitea PR #101
+```
+
+Requires `tea` CLI to be installed and authenticated. The `--create` flag cannot be used with `gpr:` syntax since the branch already exists.
+
+**Fork PRs:** The local branch uses the PR's branch name directly, so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
+
 ## GitLab merge requests
 
 The `mr:<number>` syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches `refs/merge-requests/N/head` and configures `pushRemote` to the fork URL.
@@ -166,8 +181,8 @@ Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <spa
           Branch name or shortcut
 
           Opens interactive picker if omitted. Shortcuts: &#39;^&#39; (default branch),
-          &#39;-&#39; (previous), &#39;@&#39; (current), &#39;pr:{N}&#39; (GitHub PR), &#39;mr:{N}&#39; (GitLab
-          MR)
+          &#39;-&#39; (previous), &#39;@&#39; (current), &#39;pr:{N}&#39; (GitHub PR), &#39;gpr:{N}&#39; (Gitea
+          PR), &#39;mr:{N}&#39; (GitLab MR)
 
   <span class=c>[EXECUTE_ARGS]...</span>
           Additional arguments for --execute command (after --)

skills/worktrunk/reference/switch.md

@@ -12,6 +12,7 @@ wt switch -                      # Previous worktree (like cd -)
 wt switch --create new-feature   # Create new branch and worktree
 wt switch --create hotfix --base production
 wt switch pr:123                 # Switch to PR #123's branch
+wt switch gpr:123                # Switch to Gitea PR #123's branch
 ```
 
 ## Creating a branch
@@ -48,13 +49,15 @@ wt switch --create temp --no-verify      # Skip hooks
 | `@` | Current branch/worktree |
 | `-` | Previous worktree (like `cd -`) |
 | `pr:{N}` | GitHub PR #N's branch |
+| `gpr:{N}` | Gitea PR #N's branch |
 | `mr:{N}` | GitLab MR !N's branch |
 
 ```bash
 wt switch -                      # Back to previous
 wt switch ^                      # Default branch worktree
 wt switch --create fix --base=@  # Branch from current HEAD
 wt switch pr:123                 # PR #123's branch
+wt switch gpr:123                # Gitea PR #123's branch
 wt switch mr:101                 # MR !101's branch
 ```
 
@@ -105,6 +108,18 @@ Requires `gh` CLI to be installed and authenticated. The `--create` flag cannot
 
 **Fork PRs:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
 
+## Gitea pull requests
+
+The `gpr:<number>` syntax resolves the branch for a Gitea pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches `refs/pull/N/head` and configures `pushRemote` to the fork URL.
+
+```bash
+wt switch gpr:101                # Checkout Gitea PR #101
+```
+
+Requires `tea` CLI to be installed and authenticated. The `--create` flag cannot be used with `gpr:` syntax since the branch already exists.
+
+**Fork PRs:** The local branch uses the PR's branch name directly, so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
+
 ## GitLab merge requests
 
 The `mr:<number>` syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches `refs/merge-requests/N/head` and configures `pushRemote` to the fork URL.
@@ -136,8 +151,8 @@ Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <spa
           Branch name or shortcut
 
           Opens interactive picker if omitted. Shortcuts: &#39;^&#39; (default branch),
-          &#39;-&#39; (previous), &#39;@&#39; (current), &#39;pr:{N}&#39; (GitHub PR), &#39;mr:{N}&#39; (GitLab
-          MR)
+          &#39;-&#39; (previous), &#39;@&#39; (current), &#39;pr:{N}&#39; (GitHub PR), &#39;gpr:{N}&#39; (Gitea
+          PR), &#39;mr:{N}&#39; (GitLab MR)
 
   <span class=c>[EXECUTE_ARGS]...</span>
           Additional arguments for --execute command (after --)

src/cli/mod.rs

@@ -260,6 +260,7 @@ wt switch -                      # Previous worktree (like cd -)
 wt switch --create new-feature   # Create new branch and worktree
 wt switch --create hotfix --base production
 wt switch pr:123                 # Switch to PR #123's branch
+wt switch gpr:123                # Switch to Gitea PR #123's branch
 ```
 
 ## Creating a branch
@@ -296,13 +297,15 @@ wt switch --create temp --no-verify      # Skip hooks
 | `@` | Current branch/worktree |
 | `-` | Previous worktree (like `cd -`) |
 | `pr:{N}` | GitHub PR #N's branch |
+| `gpr:{N}` | Gitea PR #N's branch |
 | `mr:{N}` | GitLab MR !N's branch |
 
 ```console
 wt switch -                      # Back to previous
 wt switch ^                      # Default branch worktree
 wt switch --create fix --base=@  # Branch from current HEAD
 wt switch pr:123                 # PR #123's branch
+wt switch gpr:123                # Gitea PR #123's branch
 wt switch mr:101                 # MR !101's branch
 ```
 
@@ -354,6 +357,18 @@ Requires `gh` CLI to be installed and authenticated. The `--create` flag cannot
 
 **Fork PRs:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
 
+## Gitea pull requests
+
+The `gpr:<number>` syntax resolves the branch for a Gitea pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches `refs/pull/N/head` and configures `pushRemote` to the fork URL.
+
+```console
+wt switch gpr:101                # Checkout Gitea PR #101
+```
+
+Requires `tea` CLI to be installed and authenticated. The `--create` flag cannot be used with `gpr:` syntax since the branch already exists.
+
+**Fork PRs:** The local branch uses the PR's branch name directly, so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
+
 ## GitLab merge requests
 
 The `mr:<number>` syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches `refs/merge-requests/N/head` and configures `pushRemote` to the fork URL.
@@ -385,7 +400,7 @@ To change which branch a worktree is on, use `git switch` inside that worktree.
         /// Branch name or shortcut
         ///
         /// Opens interactive picker if omitted.
-        /// Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
+        /// Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'gpr:{N}' (Gitea PR), 'mr:{N}' (GitLab MR)
         #[arg(add = crate::completion::worktree_branch_completer())]
         branch: Option<String>,
 

src/commands/worktree/switch.rs

@@ -9,7 +9,7 @@ use color_print::cformat;
 use dunce::canonicalize;
 use worktrunk::config::UserConfig;
 use worktrunk::git::remote_ref::{
-    self, GitHubProvider, GitLabProvider, RemoteRefInfo, RemoteRefProvider,
+    self, GitHubProvider, GitLabProvider, GiteaProvider, RemoteRefInfo, RemoteRefProvider,
 };
 use worktrunk::git::{GitError, RefContext, RefType, Repository};
 use worktrunk::styling::{
@@ -57,6 +57,7 @@ fn format_ref_context(ctx: &impl RefContext) -> String {
 fn resolve_remote_ref(
     repo: &Repository,
     provider: &dyn RemoteRefProvider,
+    syntax: &'static str,
     number: u32,
     create: bool,
     base: Option<&str>,
@@ -66,7 +67,12 @@ fn resolve_remote_ref(
 
     // --base is invalid with pr:/mr: syntax (check early, no network needed)
     if base.is_some() {
-        return Err(GitError::RefBaseConflict { ref_type, number }.into());
+        return Err(GitError::RefBaseConflict {
+            ref_type,
+            syntax,
+            number,
+        }
+        .into());
     }
 
     // Fetch ref info (network call via gh/glab CLI)
@@ -85,6 +91,7 @@ fn resolve_remote_ref(
     if create {
         return Err(GitError::RefCreateConflict {
             ref_type,
+            syntax,
             number,
             branch: info.source_branch.clone(),
         }
@@ -131,7 +138,7 @@ fn resolve_fork_ref(
             });
         }
 
-        // Branch exists but doesn't track this ref - try prefixed name (GitHub only)
+        // Branch exists but doesn't track this ref - try prefixed name (GitHub/Gitea)
         if let Some(prefixed) = info.prefixed_local_branch_name() {
             if let Some(prefixed_tracks) =
                 remote_ref::branch_tracks_ref(repo_root, &prefixed, provider, number)
@@ -162,8 +169,8 @@ fn resolve_fork_ref(
             }
 
             // Use prefixed branch name; push won't work (None for fork_push_url)
-            // This is GitHub-only (GitLab doesn't support prefixed names)
-            let remote = find_github_remote(repo, info)?;
+            // GitLab doesn't support prefixed names
+            let remote = find_pr_remote(repo, info)?;
             return Ok(ResolvedTarget {
                 branch: prefixed,
                 method: CreationMethod::ForkRef {
@@ -190,8 +197,8 @@ fn resolve_fork_ref(
     // Resolve remote and URLs based on platform.
     let (fork_push_url, remote) = match ref_type {
         RefType::Pr => {
-            // GitHub: URLs already in info, just find remote
-            let remote = find_github_remote(repo, info)?;
+            // GitHub/Gitea: URLs already in info, just find remote
+            let remote = find_pr_remote(repo, info)?;
             (info.fork_push_url.clone(), remote)
         }
         RefType::Mr => {
@@ -240,24 +247,38 @@ fn resolve_fork_ref(
     })
 }
 
-/// Find the remote for a GitHub PR (where PR refs live).
-fn find_github_remote(repo: &Repository, info: &RemoteRefInfo) -> anyhow::Result<String> {
+/// Find the remote for a PR (GitHub/Gitea) where PR refs live.
+fn find_pr_remote(repo: &Repository, info: &RemoteRefInfo) -> anyhow::Result<String> {
     use worktrunk::git::remote_ref::PlatformData;
 
-    let PlatformData::GitHub {
-        host,
-        base_owner,
-        base_repo,
-        ..
-    } = &info.platform_data
-    else {
-        anyhow::bail!("find_github_remote called on non-GitHub ref");
+    let (host, base_owner, base_repo, suggested_url) = match &info.platform_data {
+        PlatformData::GitHub {
+            host,
+            base_owner,
+            base_repo,
+            ..
+        } => (
+            host,
+            base_owner,
+            base_repo,
+            worktrunk::git::remote_ref::github::fork_remote_url(host, base_owner, base_repo),
+        ),
+        PlatformData::Gitea {
+            host,
+            base_owner,
+            base_repo,
+            ..
+        } => (
+            host,
+            base_owner,
+            base_repo,
+            worktrunk::git::remote_ref::gitea::fork_remote_url(host, base_owner, base_repo),
+        ),
+        _ => anyhow::bail!("find_pr_remote called on non-PR ref"),
     };
 
     repo.find_remote_for_repo(Some(host), base_owner, base_repo)
         .ok_or_else(|| {
-            let suggested_url =
-                worktrunk::git::remote_ref::github::fork_remote_url(host, base_owner, base_repo);
             GitError::NoRemoteForRepo {
                 owner: base_owner.clone(),
                 repo: base_repo.clone(),
@@ -293,6 +314,21 @@ fn resolve_same_repo_ref(
                     suggested_url,
                 })?
         }
+        PlatformData::Gitea {
+            host,
+            base_owner,
+            base_repo,
+            ..
+        } => {
+            let suggested_url =
+                worktrunk::git::remote_ref::gitea::fork_remote_url(host, base_owner, base_repo);
+            repo.find_remote_for_repo(Some(host), base_owner, base_repo)
+                .ok_or_else(|| GitError::NoRemoteForRepo {
+                    owner: base_owner.clone(),
+                    repo: base_repo.clone(),
+                    suggested_url,
+                })?
+        }
         PlatformData::GitLab {
             host,
             base_owner,
@@ -342,14 +378,21 @@ fn resolve_switch_target(
     if let Some(suffix) = branch.strip_prefix("pr:")
         && let Ok(number) = suffix.parse::<u32>()
     {
-        return resolve_remote_ref(repo, &GitHubProvider, number, create, base);
+        return resolve_remote_ref(repo, &GitHubProvider, "pr:", number, create, base);
+    }
+
+    // Handle gpr:<number> syntax (Gitea PRs)
+    if let Some(suffix) = branch.strip_prefix("gpr:")
+        && let Ok(number) = suffix.parse::<u32>()
+    {
+        return resolve_remote_ref(repo, &GiteaProvider, "gpr:", number, create, base);
     }
 
     // Handle mr:<number> syntax (GitLab MRs)
     if let Some(suffix) = branch.strip_prefix("mr:")
         && let Ok(number) = suffix.parse::<u32>()
     {
-        return resolve_remote_ref(repo, &GitLabProvider, number, create, base);
+        return resolve_remote_ref(repo, &GitLabProvider, "mr:", number, create, base);
     }
 
     // Regular branch switch

src/git/error.rs

@@ -279,12 +279,16 @@ pub enum GitError {
     /// --create flag used with pr:/mr: syntax (conflict - branch already exists)
     RefCreateConflict {
         ref_type: RefType,
+        /// CLI syntax used (e.g., "pr:", "gpr:", "mr:")
+        syntax: &'static str,
         number: u32,
         branch: String,
     },
     /// --base flag used with pr:/mr: syntax (conflict - base is predetermined)
     RefBaseConflict {
         ref_type: RefType,
+        /// CLI syntax used (e.g., "pr:", "gpr:", "mr:")
+        syntax: &'static str,
         number: u32,
     },
     /// Branch exists but is tracking a different PR/MR
@@ -811,11 +815,11 @@ impl GitError {
 
             GitError::RefCreateConflict {
                 ref_type,
+                syntax,
                 number,
                 branch,
             } => {
                 let name = ref_type.name();
-                let syntax = ref_type.syntax();
                 write!(
                     f,
                     "{}\n{}",
@@ -828,8 +832,11 @@ impl GitError {
                 )
             }
 
-            GitError::RefBaseConflict { ref_type, number } => {
-                let syntax = ref_type.syntax();
+            GitError::RefBaseConflict {
+                ref_type,
+                syntax,
+                number,
+            } => {
                 let name_plural = ref_type.name_plural();
                 write!(
                     f,