-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathgit.html
More file actions
169 lines (160 loc) · 24.2 KB
/
Copy pathgit.html
File metadata and controls
169 lines (160 loc) · 24.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Git 基础与 Worktree 高频操作</title>
<!-- guide:theme-bootstrap:start -->
<script src="assets/theme.js"></script>
<!-- guide:theme-bootstrap:end -->
<link rel="stylesheet" href="assets/site.css">
<!-- guide:metadata:start -->
<meta name="description" content="从够用的 Git 基础进入 Worktree：保护 Local、用 CLI 创建独立任务目录、验证、交接并安全清理。">
<meta name="guide-build" content="ee947e14a0a9">
<link rel="icon" href="favicon.svg" type="image/svg+xml">
<link rel="canonical" href="https://whojay0609.github.io/codex-usage-guide/git.html">
<meta property="og:type" content="website">
<meta property="og:locale" content="zh_CN">
<meta property="og:site_name" content="Codex 使用指南">
<meta property="og:title" content="Git 基础与 Worktree 高频操作">
<meta property="og:description" content="从够用的 Git 基础进入 Worktree：保护 Local、用 CLI 创建独立任务目录、验证、交接并安全清理。">
<meta property="og:url" content="https://whojay0609.github.io/codex-usage-guide/git.html">
<meta property="og:image" content="https://whojay0609.github.io/codex-usage-guide/figures/social-preview.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Codex 使用指南">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Git 基础与 Worktree 高频操作">
<meta name="twitter:description" content="从够用的 Git 基础进入 Worktree：保护 Local、用 CLI 创建独立任务目录、验证、交接并安全清理。">
<meta name="twitter:image" content="https://whojay0609.github.io/codex-usage-guide/figures/social-preview.png">
<meta name="twitter:image:alt" content="Codex 使用指南">
<!-- guide:metadata:end -->
</head>
<body>
<!-- guide:header:start -->
<script src="assets/site-data.js"></script><a class="skip-link" href="#main-content">跳到正文</a><header class="topbar"><div class="topbar-inner"><a class="brand" href="index.html"><span class="brand-mark" aria-hidden="true"></span><span>Codex 使用指南</span></a><div class="topbar-actions"><label class="theme-control"><span class="sr-only">主题</span><select class="theme-select" id="theme-select" name="theme" aria-label="主题"><option value="light" selected>浅色</option><option value="dark">深色</option></select></label><span class="theme-status sr-only" aria-live="polite"></span><button class="search-trigger" type="button" aria-haspopup="dialog" aria-controls="site-search-dialog">搜索</button><button class="menu-toggle" type="button" aria-controls="global-nav" aria-expanded="false">目录</button></div></div></header><dialog class="search-dialog" id="site-search-dialog" role="dialog" aria-modal="true" aria-labelledby="site-search-title"><div class="search-dialog-panel"><div class="search-dialog-head"><p class="search-title" id="site-search-title">搜索全站</p><button class="search-close" type="button" aria-label="关闭搜索">关闭</button></div><label class="search-label" for="site-search-input">搜索标题、正文和可复用 prompt</label><input class="search-input" id="site-search-input" type="search" role="combobox" autocomplete="off" aria-autocomplete="list" aria-controls="site-search-results" aria-describedby="site-search-status" aria-expanded="false"><p class="search-message" id="site-search-status" aria-live="polite">输入关键词开始搜索。</p><ul class="search-results" id="site-search-results" role="listbox" aria-label="搜索结果"></ul></div></dialog>
<!-- guide:header:end -->
<!-- guide:shell-open:start -->
<div class="toolbook-shell"><aside class="global-nav" id="global-nav" aria-label="全站导航"><section class="global-nav-group"><strong>开始</strong><a data-nav href="index.html">首页</a><a data-nav href="install-desktop.html">安装</a><a data-nav href="desktop-cli.html">Desktop</a></section><section class="global-nav-group"><strong>基础概念</strong><a data-nav href="codex.html">Codex</a><a data-nav href="git.html" aria-current="page">Git</a><a data-nav href="worktrees.html">Worktrees</a><a data-nav href="permissions.html">权限</a><a data-nav href="agents-md.html">AGENTS.md</a><a data-nav href="skills.html">Skills</a><a data-nav href="mcp.html">MCP</a><a data-nav href="subagents.html">Subagents</a><a data-nav href="goal.html">Goal</a></section><section class="global-nav-group"><strong>任务路径</strong><a data-nav href="workflows.html">任务</a><a data-nav href="daily-workflow.html">日常</a><a data-nav href="engineering.html">工程</a><a data-nav href="research.html">学术</a><a data-nav href="automation.html">定时任务</a></section><section class="global-nav-group"><strong>扩展与资料</strong><a data-nav href="compound-engineering.html">Compound</a><details class="global-nav-disclosure"><summary>Skills 仓库</summary><a data-nav href="skills-repositories.html">全部仓库</a><a href="skills-repositories.html#compound-engineering">Compound Engineering</a><a href="skills-repositories.html#mattpocock-skills">Matt Pocock skills</a><a href="skills-repositories.html#academic-research-skills-codex">ARS</a><a href="skills-repositories.html#aris-auto-claude-code-research-in-sleep">ARIS</a><a href="skills-repositories.html#refine-user-prompt">refine-user-prompt</a></details><a data-nav href="prompt-guidance.html">提示词</a><a data-nav href="resources.html">资料</a></section></aside><div class="toolbook-main"><nav class="breadcrumbs" aria-label="面包屑"><a href="index.html">首页</a><span aria-hidden="true">/</span><span>基础概念</span><span aria-hidden="true">/</span><span aria-current="page">Git</span></nav><div class="page-freshness"><span>页面更新：<time datetime="2026-08-11">2026-08-11</time></span><span>事实核验：<time datetime="2026-08-11">2026-08-11</time></span></div><aside class="page-sources" aria-label="本页资料依据"><strong>本页依据</strong><a class="page-source-link external-link" href="https://git-scm.com/docs/gittutorial" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span><span class="source-kind">第三方上游</span>Git tutorial</a><a class="page-source-link external-link" href="https://git-scm.com/docs/git-worktree" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span><span class="source-kind">第三方上游</span>git-worktree</a><a class="page-source-link external-link" href="https://learn.chatgpt.com/docs/environments/git-worktrees" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span><span class="source-kind">OpenAI 官方</span>Git worktrees</a></aside><aside class="page-toc" aria-label="本页目录"><details><summary>本页目录</summary><nav><a class="toc-h2" href="#git-mental-model">Git 只保留四个概念</a><a class="toc-h2" href="#git-inspection">先看工作树，再决定是否开 Worktree</a><a class="toc-h2" href="#git-worktree-model">Worktree 才是任务隔离主线</a><a class="toc-h2" href="#git-worktree-workflow">保留 Local，创建 clean Worktree，再交付</a><a class="toc-h2" href="#git-worktree-safety">Worktree 最容易踩的五个坑</a><a class="toc-h2" href="#git-project-operations">匿名案例：为什么高频使用 Worktree</a><a class="toc-h2" href="#git-codex-prompt">可复制的 Worktree 任务请求</a><a class="toc-h2" href="#git-boundaries">事实、案例与项目规则分开</a></nav></details></aside>
<!-- guide:shell-open:end -->
<main id="main-content">
<section class="hero compact">
<div class="hero-copy">
<p class="hero-kicker">Git 基础 · Worktree 主线</p>
<h1>Git 基础与 Worktree 高频操作</h1>
<p class="lead">分支只需要理解到“任务有自己的提交线”即可。真正适合 Codex 高频任务的隔离单位是 <strong>Worktree</strong>：保留 Codex Desktop 当前前台主工作区（<strong>Local</strong>），再给新任务一份独立目录、独立 index 和独立 HEAD，最后统一验证与交接。</p>
</div>
</section>
<div class="doc-layout">
<article class="doc-content">
<aside class="callout"><strong>先记结论：</strong>这里的 <strong>Local</strong> 指 Codex Desktop 当前前台打开的主工作区（main worktree）：你在 Desktop 中看到、编辑和运行命令的目录。Git 页只保留紧凑的 Git/command loop；Desktop 菜单、任务生命周期和隔离边界详见 <a href="worktrees.html#desktop-start">Worktrees 专页</a>。Branch 是 Git 历史上的指针；Worktree 是你真正打开、编辑和运行命令的独立目录。创建 Worktree 时通常会附着一个任务 branch，也可以使用 detached HEAD，但日常操作重点是<strong>目录隔离、现场保护和验证交接</strong>，不是反复切 branch。</aside>
<section class="content-block" id="what">
<p class="section-kicker">够用的 Git 基础</p>
<span class="fragment-alias" id="heading-git-1" data-canonical-fragment="git-mental-model" aria-hidden="true"></span><h2 id="git-mental-model">Git 只保留四个概念<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-mental-model" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<div class="route-strip">
<div class="route-pill"><strong>Repository</strong><span>保存 commits、refs 和共享 Git 对象的仓库。</span></div>
<div class="route-pill"><strong>Working tree</strong><span>磁盘上真正可编辑、可运行的项目文件。</span></div>
<div class="route-pill"><strong>Index</strong><span>下一次 commit 准备包含的精确快照。</span></div>
<div class="route-pill"><strong>Commit</strong><span>可以比较、审查和交接的历史节点。</span></div>
</div>
<p><code>HEAD</code> 表示当前 checkout 的提交；branch 让一条提交线有名字；remote 是远程仓库别名；<strong>PR 不是 Git 对象</strong>，而是托管平台上的审查流程。理解这些已经足够进入 Worktree。</p>
</section>
<section class="content-block" id="when">
<p class="section-kicker">先读现场</p>
<span class="fragment-alias" id="heading-git-2" data-canonical-fragment="git-inspection" aria-hidden="true"></span><h2 id="git-inspection">先看工作树，再决定是否开 Worktree<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-inspection" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<pre><code>git status --short --branch
git diff
git diff --cached
git worktree list
git remote</code></pre>
<div class="bento">
<article class="card span-4"><strong>Local 是否有现场</strong><p>有不认识的修改或未跟踪文件时先停下确认归属，不要 reset、restore 或“清理干净”。</p></article>
<article class="card span-4"><strong>已有 Worktree</strong><p><code>git worktree list</code> 会列出主工作树、linked worktrees、各自 checkout 和是否为 detached HEAD。</p></article>
<article class="card span-4"><strong>新任务是否独立</strong><p>新功能、长测试、并行修复或需要保持 Local 不动时，优先新建 Worktree。</p></article>
</div>
<p><code>git remote</code> 只列远程名称。完整 URL 可能含凭据或 token，不要回显、复制或贴进 prompt、日志和报告。</p>
</section>
<section class="content-block" id="examples">
<p class="section-kicker">核心模型</p>
<span class="fragment-alias" id="heading-git-3" data-canonical-fragment="git-worktree-model" aria-hidden="true"></span><span class="fragment-alias" id="git-lifecycle" data-canonical-fragment="git-worktree-model" aria-hidden="true"></span><h2 id="git-worktree-model">Worktree 才是任务隔离主线<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-worktree-model" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<p>一个 Git repository 可以拥有一个 main worktree 和多个 linked worktrees。每个 Worktree 有<strong>独立目录、独立 index、独立 HEAD 和独立未提交状态</strong>；它们共享 commits、常规 refs 和大部分仓库配置。这样，新任务不必覆盖或暂存 Local 的现场。</p>
<figure class="figure-card article-illustration">
<img src="assets/worktree-guide/worktree-isolation.png" alt="手绘示意图：一个共享 Git 仓库连接三个边界清晰的独立工作区，左侧 Local 保留杂乱现场，另外两个 Worktree 保持整洁并分别完成验证" loading="lazy" decoding="async" width="1672" height="941">
<figcaption>图意：多个 Worktree 共享同一份 Git 历史，但工作目录、index、HEAD 和未提交改动彼此独立。</figcaption>
</figure>
<aside class="callout"><strong>Worktree 不是安全沙箱：</strong>它隔离 checkout 文件和 per-worktree Git 状态，但可能共享 credentials、Git config、ignored 文件来源、进程、端口、数据库和外部服务。敏感任务仍要遵守权限与安全规则。</aside>
</section>
<section class="content-block" id="sync">
<p class="section-kicker">高频闭环</p>
<span class="fragment-alias" id="heading-git-4" data-canonical-fragment="git-worktree-workflow" aria-hidden="true"></span><span class="fragment-alias" id="git-fetch-pull" data-canonical-fragment="git-worktree-workflow" aria-hidden="true"></span><h2 id="git-worktree-workflow">保留 Local，创建 clean Worktree，再交付<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-worktree-workflow" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<div class="steps">
<article class="step"><strong>1 · 保护 Local</strong><p>记录 <code>git status</code>，不回滚、不 stash、不吸收用户已有修改。</p></article>
<article class="step"><strong>2 · 选定基线</strong><p>确认后 fetch 远程状态，以项目规则指定的 <code><base></code> 为新任务起点。</p></article>
<article class="step"><strong>3 · 新建 Worktree</strong><p>创建独立目录并附着任务名称；分支命名只是承载任务，不是这一步的学习重点。</p></article>
<article class="step"><strong>4 · 窄改与验证</strong><p>在新目录只改目标文件，运行 focused checks，审查 diff 和暂存快照。</p></article>
<article class="step"><strong>5 · 交接后再清理</strong><p>commit、PR 或 <strong>Hand off</strong> 完成后先确认无独有工作；删除 Worktree 必须有明确授权。</p></article>
</div>
<pre><code>git status --short --branch
git worktree list
git fetch origin
cd "$(git rev-parse --show-toplevel)"
git worktree add -b codex/<task> "../<repo>-<task>" origin/<base>
git -C "../<repo>-<task>" status --short --branch
git -C "../<repo>-<task>" diff</code></pre>
<p>把占位符替换成自己的值：<code><repo></code> 是当前仓库目录名，<code><task></code> 是简短且未占用的任务标识，<code><base></code> 是项目规则确认的起点分支名（例如 <code>main</code>，命令会从 <code>origin/<base></code> 取基线）。相对目标路径 <code>../<repo>-<task></code> 应位于当前仓库根目录外的 sibling；上面的 <code>cd</code> 会先把 shell 切到仓库根目录，所以即使前面的检查从子目录开始也不会把 Worktree 放错位置。</p>
<p>创建后用 <code>git -C "../<repo>-<task>" status --short --branch</code> 做稳定检查：结果应表明当前位于预期任务 branch（或明确为 detached HEAD），且工作树为 <strong>clean</strong>、没有未提交文件；这里只看 branch 与 clean-state 的含义，不要匹配某个 Git 版本的固定输出。如果提示目标路径已存在或名称冲突，停止并改用未占用的 <code><task></code> 或目标路径，不要覆盖已有目录。</p>
<p><code>git fetch origin</code> 不会改 working-tree 文件，也不会修改远程仓库；它会更新本地 remote-tracking refs、<code>FETCH_HEAD</code> 等 Git 元数据，因此执行前仍要确认操作边界。</p>
<figure class="figure-card article-illustration">
<img src="assets/worktree-guide/worktree-delivery-loop.png" alt="手绘流程图：受保护的脏 Local 保持不动，旁边创建干净 Worktree，随后进行窄改、放大镜验证和交付，最后 Local 现场仍完整保留" loading="lazy" decoding="async" width="1672" height="941">
<figcaption>图意：先封存 Local 现场，再在 clean Worktree 中编辑和验证；交付发生在独立任务目录，Local 始终不被覆盖。</figcaption>
</figure>
<p>在 Codex Desktop 中可直接为新任务选择 <strong>Worktree</strong>；需要回到本机前台继续时使用 <strong>Hand off</strong>。完整界面操作、detached HEAD 和 <code>.worktreeinclude</code> 说明见 <a href="worktrees.html#desktop-start">Worktrees 专页</a>。</p>
</section>
<section class="content-block" id="recovery">
<p class="section-kicker">安全边界</p>
<span class="fragment-alias" id="heading-git-5" data-canonical-fragment="git-worktree-safety" aria-hidden="true"></span><span class="fragment-alias" id="git-recovery" data-canonical-fragment="git-worktree-safety" aria-hidden="true"></span><h2 id="git-worktree-safety">Worktree 最容易踩的五个坑<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-worktree-safety" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<ul class="mini-list">
<li><strong>同一 branch 不能同时 checkout</strong><span>Git 默认拒绝把同一 branch 放进两个 Worktree；不要用 <code>--force</code> 绕过保护。</span></li>
<li><strong>共享历史仍会互相可见</strong><span>一个 Worktree 新建 commit 或 branch 后，其他 Worktree 能看到这些 Git 对象；独立的是工作目录，不是另一个 repository。</span></li>
<li><strong>Ignored 文件不一定自动出现</strong><span>本地配置、依赖目录和未跟踪资产要按项目规则重新准备，不能假设新 Worktree 与 Local 完全相同。</span></li>
<li><strong>不要直接删除目录</strong><span>先用 <code>git worktree list</code> 定位，再确认 clean、已交接且获授权，最后才执行 <code>git worktree remove <path></code>。</span></li>
<li><strong>不要把 <code>--force</code> 当清理按钮</strong><span>强制删除可能丢失未提交和未跟踪文件；不确定时保留 Worktree 并报告 blocker。</span></li>
</ul>
</section>
<section class="content-block" id="real-example">
<p class="section-kicker">匿名历史案例 · 只读历史会话</p>
<span class="fragment-alias" id="heading-git-6" data-canonical-fragment="git-project-operations" aria-hidden="true"></span><h2 id="git-project-operations">匿名案例：为什么高频使用 Worktree<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-project-operations" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<p>只读历史会话反复出现同一类现场：Local 正在跑实验、保留人工修改或等待验证，此时又来了独立修复。安全做法不是先研究如何切换 branch，而是<strong>保留 Local → 从确认过的 base 创建 clean Worktree → 窄改 → 验证 → 由主线程统一交付</strong>。源项目未被修改，也不向本页提供修改权限。</p>
<div class="decision-row"><strong>Local</strong><span>保留当前未完成工作、运行环境和人工上下文。</span></div>
<div class="decision-row"><strong>Task Worktree</strong><span>只承载一个目标、一个写域和对应验证证据。</span></div>
<div class="decision-row"><strong>主线程</strong><span>检查完整 diff、处理冲突、决定 commit／PR／<strong>Hand off</strong>；清理另行授权。</span></div>
</section>
<section class="content-block" id="prompt">
<p class="section-kicker">与 Codex 协作 · CLI / 手动路径</p>
<span class="fragment-alias" id="heading-git-7" data-canonical-fragment="git-codex-prompt" aria-hidden="true"></span><h2 id="git-codex-prompt">可复制的 Worktree 任务请求<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-codex-prompt" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<aside class="callout"><strong>适用范围：</strong>下面是 CLI / 手动创建 Worktree 的请求模板。若你已在 Codex Desktop 新建任务时选择 <strong>Worktree</strong>，不要再次要求 Codex 创建第二个 Worktree；请改用 <a href="worktrees.html#desktop-start">Worktrees 专页</a> 的 Desktop 路径。</aside>
<pre><code>我有一个新的独立任务，请优先判断是否需要 Worktree。
先只读检查 git status --short --branch 和 git worktree list。
如果 Local 有无关改动，必须完整保留，不要 stash、reset、restore 或清理。
从项目规则指定的 <base> 创建 clean Worktree；只修改 <目标文件>。
在新 Worktree 运行 <focused checks>，报告 diff、验证结果和剩余风险。
不要自行删除 Worktree、branch、未跟踪文件，也不要 push 或创建 PR；需要时先请求授权。
最终给出：Worktree 路径、改动文件、验证证据、交接方式和清理前置条件。</code></pre>
</section>
<section class="content-block" id="sources-note">
<p class="section-kicker">资料边界</p>
<span class="fragment-alias" id="heading-git-8" data-canonical-fragment="git-boundaries" aria-hidden="true"></span><h2 id="git-boundaries">事实、案例与项目规则分开<a class="heading-permalink" data-heading-permalink data-search-exclude href="#git-boundaries" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2>
<p>Git 对多个 working trees 的共享/独立边界来自上游 <a href="https://git-scm.com/docs/git-worktree" class="external-link" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span>git-worktree 文档</a>；Codex Desktop 的 Worktree 与 <strong>Hand off</strong> 行为来自 <a href="https://learn.chatgpt.com/docs/environments/git-worktrees" class="external-link" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span>OpenAI Worktrees 文档</a>。匿名案例只来自只读历史会话，应用前仍要读取自己仓库当前的 <code>AGENTS.md</code>、验证命令与清理授权规则。</p>
</section>
</article>
</div>
</main>
<!-- guide:shell-close:start -->
<nav class="page-sequence" aria-label="前后页"><a rel="prev" href="codex.html">← Codex</a><a rel="next" href="worktrees.html">Worktrees →</a></nav></div></div>
<!-- guide:shell-close:end -->
<footer class="footer"><p><strong>Codex 使用指南</strong></p></footer>
<!-- guide:runtime:start -->
<script src="assets/site.js"></script>
<!-- guide:runtime:end -->
</body>
</html>