Back to Details

fork

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- ⛔⛔⛔ MANDATORY: READ THIS ENTIRE FILE BEFORE ANY ACTION ⛔⛔⛔ -->
<!-- ⛔⛔⛔ 强制要求：执行任何操作前请通读整个文件 ⛔⛔⛔ -->

Git-Town Fork Workflow — STOP AND READ

Git-Town Fork工作流 — 请先阅读再操作

DO NOT ACT ON ASSUMPTIONS. Read this file first.
This is a prescriptive, gated workflow. Every step requires:
  1. Preflight check - Verify preconditions
  2. User confirmation - AskUserQuestion before action
  3. Validation - Verify action succeeded
请勿凭假设操作，请先通读本文档。
这是一个规范性的 gated 工作流，每一步都需要：
  1. 前置检查 - 验证前置条件
  2. 用户确认 - 操作前询问用户意见
  3. 验证 - 确认操作执行成功

⛔ WORKFLOW PHILOSOPHY

⛔ 工作流原则

GIT-TOWN IS CANONICAL. RAW GIT IS FORBIDDEN FOR BRANCH OPERATIONS.
Operation✅ Use❌ Never Use
Create branch
git town hack
git checkout -b
Update branch
git town sync
git pull
, 
git merge
Create PR
git town propose
Manual web UI
Merge PR
git town ship
git merge
+ push
Switch branch
git town switch
git checkout
Exception: Raw git for commits, staging, log viewing, diff (git-town doesn't replace these).
GIT-TOWN是标准操作工具，分支操作禁止使用原生Git命令。
操作✅ 推荐使用❌ 禁止使用
创建分支
git town hack
git checkout -b
更新分支
git town sync
git pull
, 
git merge
创建PR
git town propose
手动通过网页UI创建
合并PR
git town ship
git merge
+ push
切换分支
git town switch
git checkout
例外情况：提交、暂存、查看日志、对比差异可以使用原生Git命令（git-town不会替代这些功能）。

Phase 0: Preflight — MANDATORY FIRST

阶段0: 前置检查 — 强制优先执行

Execute this BEFORE any other action.
执行任何其他操作前必须先完成本阶段。

Step 0.1: Create TodoWrite

步骤0.1: 创建待办清单

TodoWrite with todos:
- "[Fork] Phase 0: Check git-town installation" | in_progress
- "[Fork] Phase 0: Check GitHub CLI installation" | pending
- "[Fork] Phase 0: Detect current repository context" | pending
- "[Fork] Phase 0: Detect existing remotes" | pending
- "[Fork] Phase 0: Detect GitHub account(s)" | pending
- "[Fork] Phase 1: GATE - Present findings and get user confirmation" | pending
- "[Fork] Phase 2: Create fork (if needed)" | pending
- "[Fork] Phase 2: Configure remotes" | pending
- "[Fork] Phase 2: Initialize git-town" | pending
- "[Fork] Phase 3: Validate setup" | pending
- "[Fork] Phase 3: Display workflow cheatsheet" | pending
TodoWrite with todos:
- "[Fork] 阶段0: 检查git-town安装情况" | in_progress
- "[Fork] 阶段0: 检查GitHub CLI安装情况" | pending
- "[Fork] 阶段0: 检测当前仓库上下文" | pending
- "[Fork] 阶段0: 检测现有远程仓库" | pending
- "[Fork] 阶段0: 检测GitHub账号" | pending
- "[Fork] 阶段1: GATE - 展示检测结果并获取用户确认" | pending
- "[Fork] 阶段2: 按需创建fork" | pending
- "[Fork] 阶段2: 配置远程仓库" | pending
- "[Fork] 阶段2: 初始化git-town" | pending
- "[Fork] 阶段3: 验证配置" | pending
- "[Fork] 阶段3: 展示工作流速查表" | pending

Step 0.2: Check git-town Installation

步骤0.2: 检查git-town安装情况

bash
/usr/bin/env bash -c 'which git-town && git-town --version'
If NOT installed:
AskUserQuestion with questions:
- question: "git-town is not installed. Would you like to install it now?"
  header: "Install"
  options:
    - label: "Yes, install via Homebrew (Recommended)"
      description: "Run: brew install git-town"
    - label: "No, abort workflow"
      description: "Cannot proceed without git-town"
  multiSelect: false
If "Yes": Run 
brew install git-town
, then re-check. If "No": STOP. Do not proceed.
bash
/usr/bin/env bash -c 'which git-town && git-town --version'
如果未安装：
AskUserQuestion with questions:
- question: "git-town未安装，是否现在安装？"
  header: "安装"
  options:
    - label: "是，通过Homebrew安装（推荐）"
      description: "执行命令：brew install git-town"
    - label: "否，终止工作流"
      description: "缺少git-town无法继续操作"
  multiSelect: false
如果选择「是」：执行
brew install git-town
，然后重新检查。 如果选择「否」：终止操作，不要继续。

Step 0.3: Check GitHub CLI Installation

步骤0.3: 检查GitHub CLI安装情况

bash
/usr/bin/env bash -c 'which gh && gh --version && gh auth status'
If NOT installed or NOT authenticated:
AskUserQuestion with questions:
- question: "GitHub CLI is required for fork operations. How to proceed?"
  header: "GitHub CLI"
  options:
    - label: "Install and authenticate (Recommended)"
      description: "Run: brew install gh && gh auth login"
    - label: "I'll handle this manually"
      description: "Provide instructions and exit"
  multiSelect: false
bash
/usr/bin/env bash -c 'which gh && gh --version && gh auth status'
如果未安装或者未完成身份验证：
AskUserQuestion with questions:
- question: "fork操作需要GitHub CLI，如何继续？"
  header: "GitHub CLI"
  options:
    - label: "安装并完成身份验证（推荐）"
      description: "执行命令：brew install gh && gh auth login"
    - label: "我将手动处理"
      description: "提供操作说明后退出"
  multiSelect: false

Step 0.4: Detect Repository Context

步骤0.4: 检测仓库上下文

Run detection script BEFORE any AskUserQuestion:
bash
/usr/bin/env bash << 'DETECT_REPO_EOF'
echo "=== REPOSITORY DETECTION ==="
询问用户前先执行检测脚本：
bash
/usr/bin/env bash << 'DETECT_REPO_EOF'
echo "=== 仓库检测 ==="

Check if in git repo

检查是否处于git仓库中

if ! git rev-parse --git-dir &>/dev/null; then echo "ERROR: Not in a git repository" exit 1 fi
if ! git rev-parse --git-dir &>/dev/null; then echo "ERROR: 未处于Git仓库中" exit 1 fi

Detect remotes

检测远程仓库

echo "--- Existing Remotes ---" git remote -v
echo "--- 现有远程仓库 ---" git remote -v

Detect current branch

检测当前分支

echo "--- Current Branch ---" git branch --show-current
echo "--- 当前分支 ---" git branch --show-current

Detect repo URL patterns

检测仓库URL模式

echo "--- Remote URLs ---" ORIGIN_URL=$(git remote get-url origin 2>/dev/null || echo "NONE") UPSTREAM_URL=$(git remote get-url upstream 2>/dev/null || echo "NONE")
echo "origin: $ORIGIN_URL" echo "upstream: $UPSTREAM_URL"
echo "--- 远程仓库URL ---" ORIGIN_URL=$(git remote get-url origin 2>/dev/null || echo "NONE") UPSTREAM_URL=$(git remote get-url upstream 2>/dev/null || echo "NONE")
echo "origin: $ORIGIN_URL" echo "upstream: $UPSTREAM_URL"

Parse GitHub owner/repo from URLs

从URL解析GitHub所有者/仓库名

if [[ "$ORIGIN_URL" =~ github.com://([^/.]+) ]]; then echo "ORIGIN_OWNER=${BASH_REMATCH[1]}" echo "ORIGIN_REPO=${BASH_REMATCH[2]%.git}" fi
if [[ "$UPSTREAM_URL" =~ github.com://([^/.]+) ]]; then echo "UPSTREAM_OWNER=${BASH_REMATCH[1]}" echo "UPSTREAM_REPO=${BASH_REMATCH[2]%.git}" fi
if [[ "$ORIGIN_URL" =~ github.com://([^/.]+) ]]; then echo "ORIGIN_OWNER=${BASH_REMATCH[1]}" echo "ORIGIN_REPO=${BASH_REMATCH[2]%.git}" fi
if [[ "$UPSTREAM_URL" =~ github.com://([^/.]+) ]]; then echo "UPSTREAM_OWNER=${BASH_REMATCH[1]}" echo "UPSTREAM_REPO=${BASH_REMATCH[2]%.git}" fi

Check git-town config

检查git-town配置

echo "--- Git-Town Config ---" git town config 2>/dev/null || echo "git-town not configured"
DETECT_REPO_EOF
undefined
echo "--- Git-Town配置 ---" git town config 2>/dev/null || echo "git-town未配置"
DETECT_REPO_EOF
undefined

Step 0.5: Detect GitHub Account(s)

步骤0.5: 检测GitHub账号

bash
/usr/bin/env bash << 'DETECT_ACCOUNT_EOF'
echo "=== GITHUB ACCOUNT DETECTION ==="
bash
/usr/bin/env bash << 'DETECT_ACCOUNT_EOF'
echo "=== GitHub账号检测 ==="

Method 1: gh CLI auth status

方法1: gh CLI认证状态

echo "--- gh CLI Account ---" GH_USER=$(gh api user --jq '.login' 2>/dev/null || echo "NONE") echo "gh auth user: $GH_USER"
echo "--- gh CLI账号 ---" GH_USER=$(gh api user --jq '.login' 2>/dev/null || echo "NONE") echo "gh auth user: $GH_USER"

Method 2: SSH config

方法2: SSH配置

echo "--- SSH Config Hosts ---" grep -E "^Host github" ~/.ssh/config 2>/dev/null | head -5 || echo "No GitHub SSH hosts"
echo "--- SSH配置主机 ---" grep -E "^Host github" ~/.ssh/config 2>/dev/null | head -5 || echo "无GitHub SSH主机配置"

Method 3: Git global config

方法3: Git全局配置

echo "--- Git Global Config ---" git config --global user.name 2>/dev/null || echo "No global user.name" git config --global user.email 2>/dev/null || echo "No global user.email"
echo "--- Git全局配置 ---" git config --global user.name 2>/dev/null || echo "无全局user.name配置" git config --global user.email 2>/dev/null || echo "无全局user.email配置"

Method 4: mise env (if available)

方法4: mise环境变量（如果可用）

echo "--- mise env ---" mise env 2>/dev/null | grep -i github || echo "No GitHub vars in mise"
DETECT_ACCOUNT_EOF

---
echo "--- mise环境变量 ---" mise env 2>/dev/null | grep -i github || echo "mise中无GitHub相关变量"
DETECT_ACCOUNT_EOF

---

Phase 1: GATE — Present Findings

阶段1: GATE — 展示检测结果

MANDATORY: Present ALL detection results and get explicit user confirmation.
强制要求：展示所有检测结果并获取用户明确确认。

Step 1.1: Synthesize Findings

步骤1.1: 整合检测结果

Create a summary table of detected state:
AspectDetected ValueStatus
Repository{owner}/{repo}✅/❌
Origin remote{url}✅/❌
Upstream remote{url}✅/❌/MISSING
GitHub account{username}✅/❌
git-town configuredyes/no✅/❌
创建检测状态汇总表：
检测项检测值状态
仓库{owner}/{repo}✅/❌
Origin远程仓库{url}✅/❌
Upstream远程仓库{url}✅/❌/缺失
GitHub账号{username}✅/❌
git-town是否配置是/否✅/❌

Step 1.2: Determine Workflow Type

步骤1.2: 确定工作流类型

AskUserQuestion with questions:
- question: "What fork workflow do you need?"
  header: "Workflow"
  options:
    - label: "Fresh fork - Create new fork from upstream"
      description: "You want to fork someone else's repo to contribute"
    - label: "Fix existing - Reconfigure existing fork's remotes"
      description: "Origin/upstream are misconfigured, need to fix"
    - label: "Verify only - Check current setup is correct"
      description: "Just validate, don't change anything"
  multiSelect: false
AskUserQuestion with questions:
- question: "你需要哪种fork工作流？"
  header: "工作流"
  options:
    - label: "全新fork - 从上游仓库创建新的fork"
      description: "你需要fork他人的仓库进行贡献"
    - label: "修复现有配置 - 重新配置现有fork的远程仓库"
      description: "Origin/upstream配置错误，需要修复"
    - label: "仅验证 - 检查当前配置是否正确"
      description: "仅做验证，不修改任何配置"
  multiSelect: false

Step 1.3: Confirm Remote URLs (if Fresh Fork)

步骤1.3: 确认远程仓库URL（全新fork场景）

AskUserQuestion with questions:
- question: "Confirm the upstream repository (the original you're forking FROM):"
  header: "Upstream"
  options:
    - label: "{detected_upstream_owner}/{detected_upstream_repo} (Detected)"
      description: "Detected from current remotes"
    - label: "Enter different URL"
      description: "I want to fork a different repository"
  multiSelect: false
AskUserQuestion with questions:
- question: "确认上游仓库（你要fork的源仓库）："
  header: "上游仓库"
  options:
    - label: "{detected_upstream_owner}/{detected_upstream_repo}（检测到的）"
      description: "从当前远程仓库检测到"
    - label: "输入其他URL"
      description: "我要fork其他仓库"
  multiSelect: false

Step 1.4: Confirm Fork Destination

步骤1.4: 确认fork存放位置

AskUserQuestion with questions:
- question: "Where should the fork be created?"
  header: "Fork Owner"
  options:
    - label: "{gh_auth_user} (Your account - Recommended)"
      description: "Fork to your personal GitHub account"
    - label: "Organization account"
      description: "Fork to a GitHub organization you have access to"
  multiSelect: false
AskUserQuestion with questions:
- question: "fork要创建到哪里？"
  header: "Fork所有者"
  options:
    - label: "{gh_auth_user}（你的账号 - 推荐）"
      description: "Fork到你的个人GitHub账号"
    - label: "组织账号"
      description: "Fork到你有权限的GitHub组织"
  multiSelect: false

Step 1.5: Final Confirmation Gate

步骤1.5: 最终确认关口

AskUserQuestion with questions:
- question: "Ready to proceed with fork setup?"
  header: "Confirm"
  options:
    - label: "Yes, create/configure fork"
      description: "Proceed with: upstream={upstream_url}, fork_owner={fork_owner}"
    - label: "No, abort"
      description: "Cancel and make no changes"
  multiSelect: false
If "No, abort": STOP. Do not proceed.
AskUserQuestion with questions:
- question: "是否准备好继续进行fork配置？"
  header: "确认"
  options:
    - label: "是，创建/配置fork"
      description: "继续操作：上游仓库={upstream_url}, fork所有者={fork_owner}"
    - label: "否，终止"
      description: "取消操作，不做任何修改"
  multiSelect: false
如果选择「否，终止」：停止操作，不要继续。

Phase 2: Execute Fork Setup

阶段2: 执行Fork配置

Step 2.1: Create Fork (if needed)

步骤2.1: 按需创建Fork

Only if fork doesn't exist:
bash
/usr/bin/env bash -c 'gh repo fork {upstream_owner}/{upstream_repo} --clone=false --remote=false'
Validate:
bash
/usr/bin/env bash -c 'gh repo view {fork_owner}/{repo} --json url'
仅当fork不存在时执行：
bash
/usr/bin/env bash -c 'gh repo fork {upstream_owner}/{upstream_repo} --clone=false --remote=false'
验证：
bash
/usr/bin/env bash -c 'gh repo view {fork_owner}/{repo} --json url'

Step 2.2: Configure Remotes

步骤2.2: 配置远程仓库

Set origin to fork (SSH preferred):
bash
git remote set-url origin git@github.com:{fork_owner}/{repo}.git
Add upstream (if missing):
bash
git remote add upstream git@github.com:{upstream_owner}/{repo}.git
Or fix upstream (if wrong):
bash
git remote set-url upstream git@github.com:{upstream_owner}/{repo}.git
设置origin为fork地址（优先使用SSH）：
bash
git remote set-url origin git@github.com:{fork_owner}/{repo}.git
如果upstream缺失则添加：
bash
git remote add upstream git@github.com:{upstream_owner}/{repo}.git
如果upstream配置错误则修改：
bash
git remote set-url upstream git@github.com:{upstream_owner}/{repo}.git

Step 2.3: Initialize git-town

步骤2.3: 初始化git-town

bash
/usr/bin/env bash << 'INIT_GITTOWN_EOF'
bash
/usr/bin/env bash << 'INIT_GITTOWN_EOF'

Initialize git-town with fork settings

使用fork设置初始化git-town

git town config setup
git town config setup

Ensure sync-upstream is enabled

确保启用sync-upstream

git config git-town.sync-upstream true
git config git-town.sync-upstream true

Set dev-remote to origin (your fork)

设置dev-remote为origin（你的fork）

git config git-town.dev-remote origin
INIT_GITTOWN_EOF

---
git config git-town.dev-remote origin
INIT_GITTOWN_EOF

---

Phase 3: Validation

阶段3: 验证

Step 3.1: Verify Remote Configuration

步骤3.1: 验证远程仓库配置

bash
/usr/bin/env bash << 'VALIDATE_REMOTES_EOF'
echo "=== REMOTE VALIDATION ==="

ORIGIN=$(git remote get-url origin)
UPSTREAM=$(git remote get-url upstream)

echo "origin: $ORIGIN"
echo "upstream: $UPSTREAM"
bash
/usr/bin/env bash << 'VALIDATE_REMOTES_EOF'
echo "=== 远程仓库验证 ==="

ORIGIN=$(git remote get-url origin)
UPSTREAM=$(git remote get-url upstream)

echo "origin: $ORIGIN"
echo "upstream: $UPSTREAM"

Validate origin points to fork owner

验证origin指向fork所有者

if [[ "$ORIGIN" =~ {fork_owner} ]]; then echo "✅ origin correctly points to your fork" else echo "❌ origin does NOT point to your fork" exit 1 fi
if [[ "$ORIGIN" =~ {fork_owner} ]]; then echo "✅ origin正确指向你的fork" else echo "❌ origin未指向你的fork" exit 1 fi

Validate upstream points to original

验证upstream指向源仓库

if [[ "$UPSTREAM" =~ {upstream_owner} ]]; then echo "✅ upstream correctly points to original repo" else echo "❌ upstream does NOT point to original repo" exit 1 fi
VALIDATE_REMOTES_EOF
undefined
if [[ "$UPSTREAM" =~ {upstream_owner} ]]; then echo "✅ upstream正确指向源仓库" else echo "❌ upstream未指向源仓库" exit 1 fi
VALIDATE_REMOTES_EOF
undefined

Step 3.2: Verify git-town Configuration

步骤3.2: 验证git-town配置

bash
/usr/bin/env bash -c 'git town config'
Expected output should show:
  • sync-upstream: true
  • dev-remote: origin
bash
/usr/bin/env bash -c 'git town config'
预期输出应包含：
  • sync-upstream: true
  • dev-remote: origin

Step 3.3: Test git-town Sync

步骤3.3: 测试git-town同步

AskUserQuestion with questions:
- question: "Run a test sync to verify everything works?"
  header: "Test"
  options:
    - label: "Yes, run git town sync --dry-run"
      description: "Preview what sync would do (safe)"
    - label: "Yes, run git town sync for real"
      description: "Actually sync branches"
    - label: "Skip test"
      description: "I'll test manually later"
  multiSelect: false
If test selected:
bash
git town sync --dry-run  # or without --dry-run
AskUserQuestion with questions:
- question: "是否运行测试同步验证所有功能正常？"
  header: "测试"
  options:
    - label: "是，运行git town sync --dry-run"
      description: "预览同步操作（安全无修改）"
    - label: "是，正式运行git town sync"
      description: "实际执行分支同步"
    - label: "跳过测试"
      description: "我之后会手动测试"
  multiSelect: false
如果选择测试：
bash
git town sync --dry-run  # 或者不带--dry-run参数

Step 3.4: Display Workflow Cheatsheet

步骤3.4: 展示工作流速查表

Always display at end:
markdown
undefined
结束前必须展示：
markdown
undefined

✅ Fork Workflow Configured Successfully

✅ Fork工作流配置成功

Daily Commands (USE THESE, NOT RAW GIT)

日常命令（请使用这些命令，不要用原生Git）

TaskCommand
Create feature branch
git town hack feature-name
Update all branches
git town sync
Create PR to upstream
git town propose
Merge approved PR
git town ship
Switch branches
git town switch
任务命令
创建功能分支
git town hack 功能分支名
更新所有分支
git town sync
向上游仓库提交PR
git town propose
合并已审批的PR
git town ship
切换分支
git town switch

⚠️ FORBIDDEN (Will Break Workflow)

⚠️ 禁止操作（会破坏工作流）

❌ Never Use✅ Use Instead
git checkout -b
git town hack
git pull
git town sync
git merge
git town sync
or 
git town ship
git push origin main
git town sync
❌ 禁止使用✅ 替代方案
git checkout -b
git town hack
git pull
git town sync
git merge
git town sync
或 
git town ship
git push origin main
git town sync

Quick Reference

快速参考

  • Sync with upstream: 
    git town sync
    (automatic)
  • Create stacked branches: 
    git town append child-feature
  • Undo last git-town command: 
    git town undo
  • See branch hierarchy: 
    git town branch

---
  • 与上游仓库同步: 
    git town sync
    （自动完成）
  • 创建堆叠分支: 
    git town append 子功能分支名
  • 撤销上一次git-town命令: 
    git town undo
  • 查看分支层级: 
    git town branch

---

Error Handling

错误处理

If Fork Creation Fails

如果Fork创建失败

AskUserQuestion with questions:
- question: "Fork creation failed. How to proceed?"
  header: "Error"
  options:
    - label: "Retry"
      description: "Try creating the fork again"
    - label: "Fork exists - configure existing"
      description: "Fork already exists, just configure remotes"
    - label: "Abort"
      description: "Cancel and investigate manually"
  multiSelect: false
AskUserQuestion with questions:
- question: "Fork创建失败，如何继续？"
  header: "错误"
  options:
    - label: "重试"
      description: "尝试重新创建fork"
    - label: "Fork已存在 - 配置现有fork"
      description: "Fork已经存在，仅配置远程仓库"
    - label: "终止"
      description: "取消操作，手动排查问题"
  multiSelect: false

If Remote Configuration Fails

如果远程仓库配置失败

Display the error and provide manual commands:
bash
undefined
展示错误并提供手动修复命令：
bash
undefined

Manual fix commands:

手动修复命令:

git remote set-url origin git@github.com:{fork_owner}/{repo}.git git remote add upstream git@github.com:{upstream_owner}/{repo}.git

---
git remote set-url origin git@github.com:{fork_owner}/{repo}.git git remote add upstream git@github.com:{upstream_owner}/{repo}.git

---

Arguments

参数

  • [upstream-url]
    - Optional: URL of repository to fork
  • --check
    - Only run validation, don't make changes
  • --fix
    - Auto-fix detected issues without prompting
  • [upstream-url]
    - 可选：要fork的仓库URL
  • --check
    - 仅运行验证，不做任何修改
  • --fix
    - 自动修复检测到的问题，无需询问

Examples

示例

bash
undefined
bash
undefined

Fork a new repository

Fork一个新仓库

/git-town-workflow:fork https://github.com/EonLabs-Spartan/alpha-forge
/git-town-workflow:fork https://github.com/EonLabs-Spartan/alpha-forge

Check existing fork setup

检查现有fork配置

/git-town-workflow:fork --check
/git-town-workflow:fork --check

Auto-fix misconfigured remotes

自动修复配置错误的远程仓库

/git-town-workflow:fork --fix
undefined
/git-town-workflow:fork --fix
undefined

Troubleshooting

问题排查

IssueCauseSolution
gh fork failedAlready forked or no accessUse 
--check
to verify existing fork
Permission deniedSSH key not added to GitHubAdd SSH key or use HTTPS URL
Remote already existsOrigin/upstream already setUse 
git remote set-url
to update
Fork not detectedOrigin URL doesn't matchCheck 
git remote -v
for mismatch
Upstream sync failsDiverged histories
git town sync
to reconcile
"Not a fork" errorRepo is origin, not a forkFork first via 
gh repo fork
问题原因解决方案
gh fork失败已fork过或者无权限使用
--check
验证现有fork
权限被拒绝SSH密钥未添加到GitHub添加SSH密钥或者使用HTTPS URL
远程仓库已存在Origin/upstream已配置使用
git remote set-url
更新
未检测到ForkOrigin URL不匹配检查
git remote -v
是否有不匹配项
上游同步失败提交历史分叉执行
git town sync
合并
"非fork仓库"错误仓库是源仓库，不是fork先通过
gh repo fork
创建fork