Docs/Git 与 GitHub

Git 与 GitHub

PocketCode 内置 Git：无需安装，也不用输入 git 命令。你可以按块暂存、提交、切换和合并分支、储藏、blame、交互式变基和 cherry-pick，还能查看并管理 GitHub 的拉取请求、议题和 CI。它运行在应用内的 JGit 库上，所有本地操作都可离线使用；只有与远端交互（clone、pull、push、GitHub）才需要联网。

它是什么，以及如何打开

Git 不是单独的一个界面：每个功能都在你平时工作的地方。请选择与你当前操作对应的入口。

位置	如何打开
源代码管理（编辑器）	打开编辑器的命令面板或菜单，进入 Git 分组并选择源代码管理。也可以在实体键盘上按 `Ctrl+Shift+G`，或点按状态栏中的分支名或 blame 文字。
GitHub PR 与 Issue（编辑器）	命令面板或编辑器菜单 → Git → GitHub PR 与 Issue。没有快捷键。
本地历史记录…和比较版本…（编辑器）	命令面板。两者都没有快捷键。
Git 面板（终端）	在终端中打开工具面板或终端菜单，选择 Git 面板。
项目卡片（项目）	点按卡片的箭头展开：Commit、Git、发布，项目有远端时还有 Pull / Push / Fetch。克隆是页面顶部的方块入口。
你的 GitHub 账号	设置 → 集成 → 已连接的服务 → GitHub。

底层原理

内置引擎。 Git 运行在应用内的 JGit 6.5.0 上，这是一个 Java 的 Git 库。本地终端没有 git 程序，所以它的 Git 面板使用同一个引擎；通过 SSH 连接时，面板运行的是主机自带的 git。
离线可用。 状态、暂存、提交、差异、blame、历史、储藏、合并、比较分支、变基、cherry-pick、分支、标签和本地历史记录都不需要网络。克隆、fetch、pull、push、发布以及 GitHub 上的一切操作则需要。
新项目还不是仓库。 用开始跟踪此项目（项目 → Git）或初始化仓库（终端的 Git 面板）开始跟踪。克隆得到的就是仓库。PocketCode 自己的 .pocketcode/ 文件夹不会计入你的更改。
其他入口。 AI 聊天可以替你运行 Git（status、commit、log、diff、branch、push 和 pull；push 会请你确认），工作流里也有 Git 步骤（status、commit、push、pull、checkout、log、diff）。两者都使用这同一个引擎，各自在单独的页面里介绍。

Ctrl+Shift+G 是唯一的 Git 快捷键。GitHub、本地历史记录、比较版本…和变基都没有快捷键。

界面一览

所有涉及 Git 的界面和面板，以及它们所在的位置。后面的章节会逐个介绍。

界面	如何进入	你可以做什么
源代码管理	编辑器 → Git → 源代码管理、`Ctrl+Shift+G`，或状态栏	查看分支和 ↑↓ 计数，暂存和取消暂存文件，查看差异，写提交信息并提交，pull 和 push。
AI 提交信息	源代码管理 → AI 消息	从四种风格中选一种，根据你的文件名生成建议信息。它只会填入信息框，不会提交。
按块暂存	源代码管理 → 更改下某个文件上的图标	选择文件中哪些代码块进入提交，哪些不进入。
合并分支	源代码管理 → 合并	把一个本地分支合并到当前分支。有冲突时，同一个对话框会列出有冲突的文件，让你逐个解决，也可以中止合并。
储藏	源代码管理 → 储藏	把更改先放到一边（可附带说明），之后可以应用、弹出或丢弃。
Blame	源代码管理 → Blame	查看打开的文件中每个代码块最后是谁修改的，并打开该提交的差异。
文件历史记录	源代码管理 → 文件历史记录	浏览改动过当前文件的最近 50 个提交，并打开每个提交的差异。
分支对比	源代码管理 → 对比	比较两个本地分支：领先和落后的提交，以及变更的文件。
差异查看器	在源代码管理中点按文件；也可从文件历史记录、Blame、本地历史记录和比较版本…进入	查看带行号的新增与删除行，以及 `+N −M` 合计；可交换两侧。
冲突解决器	合并分支对话框 → 有冲突的文件 → 手动编辑，或交互式变基因冲突而停下时 → 解决	为每个冲突块选择 Ours、Theirs 或 Both。
GitHub PR 与 Issue	编辑器 → Git → GitHub PR 与 Issue	四个标签页：拉取请求、议题、CI 和通知。筛选并打开拉取请求和议题；创建、合并、关闭和评论。
新建拉取请求	拉取请求标签页 → 从 … 新建拉取请求	标题、描述、基础分支和源分支、草稿与标签。
交互式变基	GitHub PR 与 Issue → ⋮ 菜单 → 交互式变基…	规划、确认并执行变基，附带可恢复的备份。
Cherry-Pick	GitHub PR 与 Issue → ⋮ 菜单 → 拣选提交…	把按哈希输入的提交应用到当前分支。
本地历史记录	命令面板 → 本地历史记录…	浏览打开文件先前保存的版本；复制或恢复其中一个。
比较版本…	命令面板 → 比较版本…	把打开的文件与磁盘、HEAD、剪贴板或另一个已打开的标签页做差异对比。
文件浏览器标记与状态栏	在仓库中始终可见	查看哪些文件有更改，以及分支和它的 ↑↓ 计数。
Git 面板	终端 → 工具面板 → Git 面板	状态、分支、日志和操作四个标签页：本地用内置引擎，SSH 下用主机的 `git`。
提交更改	项目卡片 → Commit	暂存和取消暂存文件、放弃某个文件的更改、amend、Commit 或 Commit & Push。
Git 设置	项目卡片 → Git	开始跟踪、关联或创建远端、上传、下载和检查远端；切换和创建分支；历史、标签；提交中显示的名字。
提交历史	Git 设置 → 历史	最近 100 个提交，带有 Revert、Reset Soft、Reset Hard 和 Cherry-pick。
标签	Git 设置 → 标签	创建标签（添加说明则为附注标签）、删除标签、推送标签。
发布到远程	项目卡片 → 发布	在 GitHub、GitLab 或 Bitbucket 上创建一个空仓库，并将其关联为 `origin`。不会 push。
克隆	项目页面 → 克隆	从你在 GitHub、GitLab 或 Bitbucket 上的仓库中选一个，下载为项目。
使用验证码登录	设置 → 集成 → 已连接的服务 → GitHub	用一个短代码连接你的 GitHub 账号，并在浏览器中批准。

克隆、发布并连接 GitHub

只有 PocketCode 拿到你的账号后，Git 才能与远端通信。克隆、发布、pull 和 push 都使用你在“已连接的服务”中连接的账号；无需为每个仓库单独配置。

连接你的 GitHub 账号

1打开设置 → 集成 → 已连接的服务，选择 GitHub。它的那一行写着使用验证码登录。
2点按向 GitHub 申请代码。PocketCode 会显示你的代码。
3点按打开 GitHub，在打开的页面（github.com/login/device）中输入代码并批准。
4保持面板打开。正在等待你的批准…会自动变成已连接的账号：无需把令牌复制回来。

你可以

全程无需接触令牌：PocketCode 使用 GitHub 的设备流程（device flow），它不需要客户端密钥，并且每隔几秒检查一次，直到你批准。
批准前可以看到请求的权限：repo、read:user 和 user:email。repo 用来访问私有仓库。
这一个账号用于 clone、发布、fetch、pull、push、GitHub PR 与 Issue面板和 CI 动态。

你不能做的事及原因

在 Free 上连接第二个 GitHub 账号（或任何服务的第二个账号）：每个服务的第一个账号免费，更多账号需要 Pro。Pro
在 GitHub 没有为 PocketCode 的 OAuth 应用开启验证码登录时使用它：此时面板会提示 GitHub 目前没有提供该方式。第三方

代码有效期约 15 分钟；过期后重新申请即可。令牌加密保存在设备上，按每个 PocketCode 账号和每个服务账号分别存放（见隐私与安全）。GitLab 和 Bitbucket 在同一界面连接；平台服务页面会分别介绍。

克隆仓库

1在项目页面点按克隆，选择从 GitHub 克隆、从 GitLab 克隆或从 Bitbucket 克隆。尚未连接的服务会显示未连接 — 点击以连接；它的连接按钮会带你到“已连接的服务”。
2搜索你的仓库（GitHub 上是搜索仓库…），然后点按其中一个的克隆。只需点按一次，不会再问别的：克隆始终保存在 PocketCode 自己的项目存储中，其他应用看不到。
3正在克隆仓库会显示进度。取消会停止并删除未完成的副本。
4仓库会作为新项目出现。如果已有同名项目，新项目会命名为 name (2)、name (3)……

你可以

只要对应账号已连接，就可以克隆 GitHub、GitLab 或 Bitbucket 上的私有仓库和公开仓库。
获得完整历史：克隆不是浅克隆。

你不能做的事及原因

通过 URL 克隆，或克隆不在你账号列表中的仓库。尚未提供
从其他主机克隆（GitHub Enterprise、自建 GitLab、Gitea、Codeberg 等）：只支持 github.com、gitlab.com 和 bitbucket.org。有意为之
在没有已连接账号时克隆，即使是公开仓库也不行。需要网络
获取子模块或 Git LFS 内容：子模块不会被克隆，LFS 文件仍是体积很小的文本指针。尚未提供
看到真实的进度：进度条是分段前进的，而不是按字节。尚未提供

发布本地项目

发布适用于目前只存在于你手机上的项目。

1展开项目卡片，点按发布。
2选择一个已连接的服务，然后填写仓库名称（默认是项目名），并选择公开或私有。默认是公开，如果代码不想让所有人看到，请改成私有。
3点按创建并关联。

你可以

发布到 GitHub、GitLab 或 Bitbucket。
通过 Git → 在 GitHub 上创建并连接得到同样的结果，或用关联我已有的仓库关联一个现有仓库（见项目卡片上的 Git）。

你不能做的事及原因

在没有连接任何服务时发布：面板会提示请先在“服务”中连接 GitHub、GitLab 或 Bitbucket，而且无法在那里直接连接。需要网络
发布到其他主机。有意为之

发布只会在该服务上创建空仓库，并将其关联为 origin。它不会提交，也不会 push。你的工作要在提交之后再用上传改动（或 Push）才会上传。

编辑器中的源代码管理

源代码管理是编辑器的 Git 面板，针对当前打开的项目。它显示分支和你的更改，覆盖日常循环：暂存、提交、pull、push。分支操作、储藏、blame 和历史是顶部的几个小标签。

提交、推送、拉取、合并和储藏结束时，编辑器会显示一条简短消息：发生了什么（例如已提交：…、已推送、已拉取、已合并：…、已储藏：…），或失败的原因（推送失败：…，冒号后面是原因）。每次操作之后，列表和 ↑↓ 计数都会刷新。

查看并暂存更改

副标题形如 main ↑2 ↓1 · 更改 · 3：分支、尚未 push（↑）和尚未 pull（↓）的提交数，以及更改数量。文件分为已暂存的更改、更改和未跟踪三组。

你可以

点按文件查看差异：新增和删除的行用颜色标出，带行号和 +N −M 合计。交换会对调两侧。
用文件行上的暂存 / 取消暂存移动单个文件（新文件用跟踪并暂存），或用暂存全部 / 取消暂存全部移动整组文件。
使用顶部的刷新、拉取和推送图标。拉取和推送会立即执行，不会再询问，结束时各显示一条消息（已推送或推送失败：…）。
没有可提交的内容时，会看到没有检测到更改（工作区是干净的。）。

你不能做的事及原因

在这里创建仓库：在尚未成为仓库的项目里，面板只会显示没有检测到更改。请从项目 → Git 或终端的 Git 面板开始跟踪。尚未提供
Fetch、创建或切换分支、amend、放弃某个文件的更改、编辑标签或远端：编辑器里没有对应的按钮。项目页面和终端能覆盖其中大部分（见下文）。尚未提供
相信 ↑↓ 计数始终是最新的：它们只在 pull 或 push 之后才会变化，因为编辑器不能 fetch。尚未提供

按块暂存

只提交文件的一部分。在更改下的文件上点按按块暂存。

你可以

每个变更块显示为代码块 @ 第 N 行，附带其删除和新增的行。
每个代码块起初都是暂存；对要排除的代码块点按跳过。已接受 N/M 个会统计数量。
当所有代码块都被选中时，底部按钮显示全部加入暂存，否则显示加入 N 项。它只会把这些代码块加入下一次提交，磁盘上的文件不受影响。

你不能做的事及原因

把一个代码块拆成单独的行。尚未提供
对新文件或已暂存的文件按块暂存：该图标只出现在更改下。尚未提供

该文件的暂存副本会根据上一次提交加上你选择的代码块重建，因此该文件之前已暂存的内容都会被它替换。

提交与建议信息

在提交信息…中输入信息，然后点按提交。只有在有信息，并且已暂存的更改下至少有一个文件时，按钮才可用。

你可以

点按 AI 消息获取灵感。选择一种风格（规范式、描述式、祈使式或表情符号），点按一条建议，再点使用此消息：它会填入信息框，你仍然需要点按提交。
以你自己的身份提交：编辑器中的提交带有仓库里保存的名字和邮箱，所以请先设置提交中显示的名字（项目 → Git）。

你不能做的事及原因

在编辑器中 amend 上一次提交：请使用项目 → Commit 里的修订上一次提交。尚未提供

AI 消息并不是 AI。它是一个本地的、基于规则的建议，根据你更改过的文件（已暂存、未暂存和新增的）的名称和更改类型生成。它不会读取你的差异，不调用任何模型，也不用密钥。

合并分支

1点按合并。合并分支对话框会显示当前：main，并列出你的其他本地分支；可用搜索分支…缩小范围。
2选择一个分支，点按合并到 main。
3一条消息会告诉你结果：快进合并：…、已合并：…、已是最新，或发生冲突时的合并在以下文件中有冲突：…。
4出现冲突后，对话框会变成检测到合并冲突，并显示N 个文件需要解决冲突。点按一个文件，选择采用当前版本、采用传入版本或两者都保留（每一项都会应用到该文件的所有冲突块，并暂存该文件），或选择手动编辑逐块处理。见冲突一节。
5中止合并会放弃这次合并：它会询问中止合并？（这将放弃正在进行的合并以及已完成的冲突解决，且无法撤销。），点按中止确认。解决完最后一个文件后，对话框会回到分支列表，之后你再从源代码管理中提交。

你不能做的事及原因

合并远程分支，或选择仅 fast-forward、禁用 fast-forward 或 squash。要引入远程的工作，请使用拉取。尚未提供

比较两个分支

1点按对比（分支对比）。
2选择基础分支和对比分支，然后点按比较分支。

你可以

查看领先和落后、文件、提交（列表最多显示 50 条，但领先是真实的数量）以及变更的路径。两个分支相同时会显示这两个分支之间没有差异。

你不能做的事及原因

在对比结果里打开某个文件的差异，或比较远程分支：只列出本地分支。尚未提供

储藏

储藏小标签会显示你有多少条记录。点按储藏，再点储藏更改，即可把你的更改放到一边；点按某条记录，可以应用、弹出或丢弃它。丢弃前会先询问：丢弃这条储藏？ — 该储藏条目将被永久删除，且无法撤销。

你可以

确认之前可以填写储藏说明（可选）：它会随记录一起保存，并作为这条记录在列表中的标题。不填的话，Git 会写上它自己的 WIP on … 标题。
结果以消息显示：已储藏：…、储藏已应用并移除（弹出）、储藏已应用（保留）（应用）或储藏已移除（丢弃）。

你不能做的事及原因

储藏新的（未跟踪的）文件：只有 Git 已经跟踪的文件的更改才会被放到一边。尚未提供
弹出指定的某一条：弹出总是应用并移除最新的一条，无论你打开的是哪一行。尚未提供
在应用的储藏发生冲突时解决冲突：它没有对应的解决器。尚未提供

要恢复某一条特定的记录，请对它使用应用，然后丢弃：这两个操作会按你选择的那一行执行。

Blame

你可以

打开文件后点按 Blame：来自同一提交的连续行会被归为一组，附带作者、第 N 行（或一个范围）和 7 位哈希。
点按一个区块，再点查看提交，即可查看该提交对此文件的差异。
看看状态栏：它会在分支名旁边显示光标所在行的“作者 · 多久以前”。点按其中任一个即可打开源代码管理。尚未提交的行显示 Not Committed Yet。

你不能做的事及原因

对其他分支或提交做 blame，或隐藏状态栏的 blame：没有对应的设置。尚未提供
用你的语言阅读这个相对时间：just now、5 min ago、yesterday 等始终是英文。尚未提供

文件历史记录

你可以

打开文件后点按文件历史记录，查看改动过它的最近 50 个提交（信息、哈希、作者、时间），再点查看差异查看每个提交在此文件中改了什么。
没有改动过的文件会显示此文件没有提交历史。

你不能做的事及原因

查看超过 50 个提交。有意为之
把文件恢复到旧版本，或在这一行上 revert：Revert 在项目 → Git → 历史里，而本地历史记录负责未保存的工作。尚未提供

文件浏览器和状态栏中的标记

你可以

在仓库中，文件浏览器会标出每个有更改的文件（已修改、新增、未跟踪、已删除或已重命名），标出含有更改的文件夹，并在底部显示分支、↑↓ 和有更改的文件数。它读取的状态与源代码管理相同。
状态栏中的分支名会打开源代码管理。
在 Git 仓库之外没有标记，也没有底部信息栏。

你不能做的事及原因

—

项目卡片上的 Git

有几个 Git 操作在项目页面的项目卡片上，而不在编辑器里：amend、切换和创建分支、标签、revert、reset、关联远端，以及提交中显示的名字。卡片本身在项目页面中介绍。

卡片告诉你什么

项目名旁边只有在需要处理时才会显示标签。

标签	含义
Pull	远端有你还没有的提交。
Push	你有远端还没有的提交，或者这个分支从未 push 过。
更改	你有未提交的更改（有远端的项目才会显示）。
冲突	双方都有新提交，所以你需要先下载。这并不表示存在合并冲突。

展开后，项目有远端时卡片会显示 Pull、Push 和 Fetch 小标签，项目是仓库时显示 Commit 按钮（有待处理更改时带一个圆点），以及 Git 和发布小标签。这些标签会在列表加载时以及你在编辑器中保存文件时刷新。同一时间只显示一个标签，且更改优先：有未提交的更改时只会看到更改，即使同时还有要拉取或推送的提交（仅有未跟踪的文件不算）。标签与远端最后一次已知的状态比较，因此只有在更新该状态之后才会出现 Pull（Fetch 小标签、检查远端、一次 pull 或 push）。

提交更改

点按卡片上的 Commit。面板标题为提交更改，并显示分支名。

你可以

用每个文件的复选框在已暂存 (n) 和未暂存 & 未跟踪 (n) 之间移动文件，或使用全部暂存 / 全部取消暂存。
输入提交信息并点按 Commit。它需要一条信息和至少一个已暂存的文件，而且不会替你暂存任何内容：没有已暂存文件时会提示没有已暂存的文件。使用 '全部暂存' 来添加更改。
勾选修订上一次提交（用当前更改修改上一次提交）：按钮会变成修订提交。
点按 Commit & Push 一次完成提交和上传（仅当项目有远端时）。
用文件行上的放弃更改图标，丢弃 Git 已跟踪文件的未提交更改。已暂存的文件和新文件不会显示该图标。
作者：仓库中保存的名字和邮箱；没有时，使用你的 PocketCode 账号的。

你不能做的事及原因

—

Git 设置

点按卡片上的 Git。状态卡片会说明项目当前的情况，可用的操作也随之变化。

卡片显示	你可以做什么
尚未纳入版本控制	开始跟踪此项目会创建一个本地仓库，并附带一个排除 `.pocketcode/` 的 `.gitignore`。关联我已有的仓库会创建仓库，并把 `origin` 设为你给出的 URL。
仅保存在本机	在 GitHub 上创建并连接（或 GitLab、Bitbucket）会创建一个空的私有或公开仓库并关联它；需要先有账号（请先在设置中连接 GitHub 账户）。关联我已有的仓库会把 `origin` 设为一个 URL。
已连接	上传改动（push）、下载改动（pull）和检查远端（fetch），以及分支、历史和标签几行。

你可以

分支：你的本地分支。点按一个分支即可切换过去，也可使用创建新分支：勾选切换到此分支（默认已勾选）会立即切换过去。
提交中显示的名字：设置仓库保存的 user.name 和 user.email。它们起初会从仓库、你已连接的服务或你的账号中自动填入。

你不能做的事及原因

在尚无远端的仓库中切换分支，或查看历史和标签：这些行只有存在 origin 之后才会出现。终端的 Git 面板可以在本地切换分支。尚未提供
删除或重命名分支，或列出远程分支：这里只有本地分支。尚未提供

提交历史、Revert 与 Reset

历史（提交历史）列出最近 100 个提交：信息、7 位哈希、作者和日期。点按某个提交会展开四个按钮。

按钮	作用
Revert	生成一个新提交来撤销该提交。历史不会被改写。
Reset Soft	把分支移回该提交，并把它之后的所有内容保留为已暂存的更改。
Reset Hard	把分支移回并丢弃它之后的所有内容，包括未提交的更改。
Cherry-pick	把该提交应用到当前分支之上，无需输入哈希。

你不能做的事及原因

做 mixed reset，或从旧提交恢复单个文件：只有 Reset Soft 和 Reset Hard。尚未提供

Reset Hard 点按后立即执行，没有确认步骤，并且会丢弃未提交的工作。请先提交或储藏。

终端里的 Git 面板

终端有自己的小型 Git 面板。当你已经在 shell 里时，这是创建仓库或提交的最快方式。

Git 面板

打开终端的工具面板（或菜单），选择 Git 面板。它有四个标签页：状态、分支、日志和操作。在本地 shell 中，它使用内置引擎，对从当前所在文件夹向上查找到的仓库进行操作，不会离开你自己的工作区。通过 SSH 连接时，它在远程主机上运行 git。

你可以

状态：已暂存、已修改和未跟踪文件的数量和列表，或者显示工作区干净。
分支：点按分支即可切换到它，或点按新建分支。
日志：最近 30 个提交。
操作：提交更改（询问信息并关闭面板）、Pull、Push、Stash、Stash Pop、Fetch、全部添加和 Reset（把所有内容移出暂存区）。
没有仓库时，此处没有 Git 仓库会提供初始化仓库。

你不能做的事及原因

在本地 shell 中使用 Diff 操作：它只在 SSH 下存在。有意为之
带说明的储藏、放弃单个文件、合并、变基、打标签或 blame：此面板中都没有。它自己也这么说：基于 JGit 的本地面板；完整的 git 请使用编辑器的源代码管理。尚未提供
在没有已连接账号时 push 或 pull：面板会显示 Git: … 及原因，不会打开登录界面。需要网络

冲突

冲突指的是两处更改改动了相同的行。PocketCode 有两种引导式的解决方式：源代码管理里的合并分支对话框（用于合并），以及交互式变基中的逐块解决器。pull、已应用的储藏或 cherry-pick 发生冲突时，你需要自己处理冲突标记。

合并之后逐个文件解决

1在源代码管理中合并一个分支。如果发生冲突，会有一条消息提示合并在以下文件中有冲突：…，合并分支对话框会显示检测到合并冲突、N 个文件需要解决冲突以及文件列表。
2点按一个文件展开它的选项：采用当前版本、采用传入版本、两者都保留或手动编辑。
3前三项会重写整个文件：每个冲突块都采用那一边（或两边都保留，当前版本在前），冲突标记消失，文件被暂存。一条消息会确认：冲突已解决：…。
4手动编辑会打开下面介绍的逐块面板：为每个块选择 Ours、Theirs 或 Both，然后点按应用。
5列表里没有文件之后，对话框会回到分支选择界面。已解决的文件处于暂存状态：写好提交信息，然后点按提交。

你可以

逐个解决文件，并看着剩余的数量减少。
用中止合并放弃：它会询问中止合并？，点按中止确认；消息会显示合并已中止。

你不能做的事及原因

—

变基时逐块解决

1当交互式变基因冲突而停下时，每个有冲突的文件都会显示解决。
2对每个块选择 Ours（Current (ours)）、Theirs（Incoming (theirs)）或 Both。顶部会统计你的进度：已解决 N / M。
3点按应用。文件会被保存，并在不再有冲突标记后被暂存。你没有选择的块会保留其标记。
4回到变基界面，点按继续（或跳过这个提交，或中止）。

你不能做的事及原因

为某个块选择共同祖先的版本，或在面板内手动编辑。尚未提供

这个面板中的文字（Conflict N、Current (ours)、Incoming (theirs)、Ours、Theirs、Both）始终是英文，与应用语言无关。

来自 pull、储藏或 cherry-pick 的冲突

在项目中，发生冲突的 pull 会提示：两边修改了相同的行。打开受影响的文件，保留你想要的版本，然后重试。在这里也是同样的做法。

你不能做的事及原因

对来自 pull、已应用的储藏或 cherry-pick 的冲突使用引导式解决器：只有合并分支对话框和交互式变基才有。尚未提供

这些情况没有引导式解决器。发生冲突的 pull 或已应用的储藏会在你的文件中留下冲突标记（<<<<<<<、=======、>>>>>>>）：打开这些文件，保留你想要的版本。

交互式变基与 cherry-pick

交互式变基和 cherry-pick 不能从源代码管理中打开：它们在 GitHub 面板里。打开 GitHub PR 与 Issue，使用它的 ⋮ 菜单 → 交互式变基…或拣选提交…。

只有当项目的 origin 远端在 github.com 上时，⋮ 菜单才可用。没有远端的项目，或 origin 在 GitLab、Bitbucket 或其他主机上的项目，无法打开变基或 cherry-pick。项目 → Git → 历史会对你点按的任意提交提供 Cherry-pick，无需输入哈希，并以消息提示结果。

交互式变基

1打开交互式变基…。面板从规划阶段开始：此时不会改动你的仓库。
2选择目标分支。存在 main 或 master 且它不是你当前分支时，默认选它。
3对每个提交选择保留、改写信息、压缩、合并且不留消息或丢弃，并用编辑提交信息修改某个提交的信息。
4如果你有未提交的更改，面板会提醒你；打开开始前把我的更改存入 stash，可以先把它们放到一边。变基完成后它们仍留在 stash 中（到储藏里应用）；如果中止，它们会自动恢复。
5点按开始变基。确认框会列出计划（例如两个保留和一个压缩）以及将从分支中移除的提交数量；它们仍保留在备份里。
6如果某个提交有冲突，变基会停下：停在 … · 第 N 步，共 M 步。对每个文件使用解决（见冲突一节），然后点继续；或者跳过这个提交，或者中止。每一项都会请你确认。
7结束时会显示变基完成（中止后则显示变基已撤销）。恢复备份会把分支恢复到变基之前的样子；再次变基会重新开始。

你可以

在任何改动发生之前，PocketCode 会把你分支当前的顶端保存为 refs/pocketcode/rebase-backup/<branch>。
有未提交的更改时，变基永远不会开始，除非你先把它们储藏起来。
中止会撤销一切（分支、暂存区和工作区），并重新应用你自己的 stash。
计划保存在 .git 中，所以即使期间应用被关闭，继续和跳过这个提交仍然可用。
恢复备份会把分支移回保存的顶端，但仅限工作区干净时；变基之后创建的提交此后只留在 Git 的 reflog 中。

你不能做的事及原因

重新排序提交：面板不允许这样做。有意为之
使用 Edit 操作：Git 会创建新提交而不是 amend，所以不提供它。有意为之
在你保留的第一个提交上选压缩或合并且不留消息，或者丢弃所有提交：面板两种情况都会拒绝。有意为之
变基到远程分支，或对不是当前所在分支的分支做变基：只提供本地分支，并且会拒绝分离的 HEAD。尚未提供
从源代码管理、没有远端的项目，或 origin 不在 github.com 的项目中打开它。尚未提供

Cherry-pick

1打开拣选提交…，在提交哈希中输入一个提交哈希并点按添加。可以添加任意多个；它们以小标签显示。
2点按 Cherry-Pick（或拣选 N 个提交）并确认：要把 N 个提交按顺序应用到当前分支吗？
3面板会报告成功挑选提交 …或挑选提交失败：…。

你不能做的事及原因

从列表中选择提交：你必须知道并输入哈希，唯一的检查是不能含有空格。尚未提供
在添加多个哈希时依赖顺序：它们是一起启动的，所以确认框里的“按顺序”并不保证成立。顺序重要时请一次 cherry-pick 一个。尚未提供
相信新提交：…：它显示的是你输入的哈希，而不是新创建的提交的 id。尚未提供
解决冲突：有冲突的 cherry-pick 只会报告失败，没有解决器。尚未提供

GitHub：拉取请求、议题、CI 与通知

GitHub PR 与 Issue与编辑器中打开的项目所对应的 GitHub 仓库通信。它读取项目的 origin 远端，并使用你在“已连接的服务”中连接的账号；请求直接从你的手机发往 api.github.com。顶部显示 owner/repo、一个在浏览器中打开仓库的图标，以及 ⋮ 菜单。

它只适用于 github.com 上的仓库：不支持 GitLab 合并请求、Bitbucket 拉取请求和 GitHub Enterprise。每个列表最多显示 300 条。

开始使用

你需要一个 origin 在 github.com 上的项目，以及一个已连接的 GitHub 账号。没有打开项目时，面板会显示未设置项目路径——请从编辑器中打开；其他情况见故障排查。它有四个标签页。

标签页	显示内容
拉取请求 · N	仓库的拉取请求，最近更新的在前。
议题 · N	它的议题（不含拉取请求）。
CI	你打开的那个拉取请求的检查。
通知 · N	你的 GitHub 通知；N 是未读数，在你第一次打开该标签页时加载。

分支菜单（基础分支、源分支，以及变基面板里的目标分支）在面板打开时就会填入你的本地分支。

拉取请求

你可以

用进行中、我的、请求我审阅、已关闭或全部筛选。我的和请求我审阅是在你手机上按你的 GitHub 登录名筛选的。
查看列表：状态（进行中、草稿、已合并、已关闭）、编号、标题、作者、时间、被请求的评审和标签。
打开其中一个：概览（描述、head → base、变更文件、+N / −M、提交、指派人、标签，以及带状态的检查和评审）、文件 · N（带 +/− 的路径）和评论 · N。
查看无法合并的原因：横幅显示无法合并：…，后面是适用的原因（存在合并冲突、有一项检查失败、有人要求修改）。
写评论…会发布一条对话评论。关闭 PR 会关闭该拉取请求。
合并提供合并提交、压缩并合并和变基并合并。应用会发送它展示给你的 head 提交，所以如果期间有人 push 了，GitHub 会拒绝，而不是合并你没见过的提交。
从 … 新建拉取请求（需要有当前分支）：标题、描述、基础分支和源分支、创建为草稿和标签，然后点创建拉取请求。

你不能做的事及原因

提交评审（批准或要求修改）、对某一行评论，或阅读拉取请求的差异：评审只显示、不可操作，文件只列出路径，无法打开。尚未提供
在创建拉取请求时选择评审人。尚未提供
重新打开拉取请求、编辑它的标题或描述、开启 auto-merge 或更新它的分支。尚未提供
使用 GitLab 合并请求、Bitbucket 拉取请求或 GitHub Enterprise：只会读取 github.com 的仓库。有意为之

议题

你可以

用进行中、我的议题（指派给你的）、已关闭或全部筛选。
查看列表（状态、编号、评论数、作者、标签），并打开其中一个查看正文、日期、指派人、标签、里程碑、评论和评论框。
关闭议题会把它作为已完成关闭。创建议题需要标题、描述和标签。

你不能做的事及原因

在创建议题时选择里程碑或指派人、重新打开议题、编辑它、事后加标签或搜索。尚未提供

CI

你可以

打开一个拉取请求，再进入 CI 标签页：它的 head 提交的检查（GitHub Actions 运行、其他应用的检查和传统状态）汇总在一个概要下，例如所有检查均已通过、部分检查失败或检查进行中。

你不能做的事及原因

不先打开拉取请求就查看 CI（该标签页会显示选择一个 PR 查看其 CI 状态）、阅读日志，或重新运行、取消某次运行。尚未提供

另外，选中一个项目时，PocketCode 会读取它的 origin 上最近一次 GitHub Actions、GitLab CI 或 Bitbucket Pipelines 运行，仅读取一次，并放入后端管理器的状态动态中。它需要连接对应服务，并且不会自动刷新。

通知

你可以

打开通知：你参与的 GitHub 通知。每一行有一个表示类型的图标（请求评审、已批准、要求修改、合并、评论、指派、提及、CI 通过或失败、发布）、标题和 仓库 · 原因。
点按未读的一条可将其标为已读，或点全部标为已读。没有未读时会显示全部已处理。

你不能做的事及原因

打开某条通知背后的拉取请求或议题：点按只会把它标为已读。尚未提供
使用细粒度令牌查看通知：GitHub 只对经典令牌或 OAuth 登录显示通知，面板也会这么提示。第三方

本地历史记录

本地历史记录在你的手机上保存文件的早期版本，不需要 Git、网络或账号。它是免费的。从命令面板打开：本地历史记录…。

它保存什么

你可以

每次成功保存后都会保存一个版本，并且仅当文本与上一个已保存版本不同时才保存。它对项目文件以及你从项目之外打开的文件都有效。
每个文件最多保留 50 个版本，总共 50 MB（按压缩后计算）。超过总量时，任何文件中最旧的版本会先被清除。没有按时间的过期。
版本存放在 PocketCode 的私有存储中，绝不在你的项目里面，所以永远不会显示为 Git 更改。重命名或移动文件时，历史会随之带走。

你不能做的事及原因

保留大文件的版本：编辑器对 512 KiB 以上、10,000 行以上或单行 2,000 个字符以上的文件会用轻量模式打开，这些文件不会被保存。有意为之
更改限制，或固定、标记某个版本。有意为之

浏览与恢复

1打开文件并选择本地历史记录…。副标题会显示版本数量，例如 12 个版本。
2每一行显示它的保存时间和大小。点按一行，可查看该版本与当前文本的差异。
3复制此版本会复制它的文本。恢复此版本会把它作为一次可撤销的编辑放入编辑器。在你保存之前不会写入磁盘。

你不能做的事及原因

把两个旧版本互相比较：它们总是与当前文本比较。尚未提供

列表为空时会显示暂无版本：还没有保存的版本。下次保存更改时会显示在这里。

比较版本…

打开命令面板并选择比较版本…，把打开的文件与其他内容做差异对比。结果是只读的。

选择比较对象

你可以

选择基准：磁盘版本（此文件已保存的版本）、HEAD（最近一次 git 提交）、剪贴板（已复制的文本）或其他已打开的标签页。
不可用的基准会说明原因：没有 Git 仓库、剪贴板为空或没有其他已打开的标签页。
差异标题形如 文件 ↔ 基准；交换会对调两侧。

你不能做的事及原因

在差异视图中编辑，或以双栏查看：它是一个统一的变更行列表。有意为之

HEAD 基准比较的是最近一次提交与磁盘上的文件，所以你尚未保存的修改不包括在内。

Free 与 Pro

Git 本身没有套餐限制。没有任何 Git 操作、GitHub 功能、本地历史记录、比较版本…或终端 Git 面板被锁在 Pro 之后，套餐也不限制仓库、分支、提交或操作的数量。围绕它的有两项限制确实取决于套餐。

功能	Free	Pro
源代码管理、储藏、blame、文件历史、比较分支	包含	包含
交互式变基、cherry-pick、冲突解决器	包含	包含
GitHub 拉取请求、议题、CI 和通知	包含	包含
本地历史记录	包含：每个文件 50 个版本，总共 50 MB	相同
终端里的 Git 面板、项目卡片上的 Git 面板、克隆和发布	包含	包含
你自己的项目（新建、导入、打开文件夹、从 GitLab 或 Bitbucket 克隆）	1 个。示例项目不计入	无限制
每个服务的已连接账号（GitHub、GitLab、Bitbucket 等）	1 个	无限制

第二个项目和某个服务的第二个账号，是仅有的与 Git 相关、需要 Pro 的两项。完整对照表见套餐与价格。

隐私与安全

令牌留在手机上。 你通过使用验证码登录得到的令牌，会用 Android Keystore 加密保存，并按每个 PocketCode 账号和每个服务账号分别存放。退出登录不会删除它；应用只是切换到另一个账号的存储。
令牌发往哪里。 Git 只会把它发送给 github.com、gitlab.com 和 bitbucket.org，并按完整主机名精确匹配：其他任何主机上的远端都拿不到凭据。GitHub PR 与 Issue面板直接从你的手机把它发送到 api.github.com。
用 GitHub 登录是另一回事。 如果你用 GitHub 登录 PocketCode 本身，那个 GitHub 令牌也会保存在 PocketCode 的服务器上，并以 GitHub 密钥的形式保存在设备上（它用于 Copilot，并在必要时作为克隆的后备）。push、pull 和 GitHub 面板使用的令牌是来自“已连接的服务”的那个，它只存放在设备上。
钩子永远不会运行。 Git 钩子和过滤器不会执行；导入项目（ZIP、模板、文件夹）时，它的 .git/config 中任何可能运行命令的内容都会被清除，钩子也会被清空。这是出于安全的决定。
本地历史记录留在设备上，存放在应用的私有存储中、项目之外，所以它不属于你的 Git 更改。
项目 ZIP 包含你的历史。 项目卡片上的导出会包含 .git 文件夹，所以你提交过的一切都会随文件一起带走。
提交会暴露什么。 每个提交都带有为仓库设置的名字和邮箱（从项目页面提交时则是你的 PocketCode 账号的）。任何能读取仓库的人都能看到它们。提交没有签名。

限制

哪些功能不可用，免得你措手不及。徽章会说明原因。

不支持 SSH 远端。 不支持 git@… 和 ssh:// 地址；请使用仓库的 HTTPS 地址。PocketCode 会在尝试之前就告诉你。有意为之
凭据只发送给三个主机： github.com、gitlab.com 和 bitbucket.org。GitHub Enterprise、自建 GitLab、Gitea、Codeberg 或 Azure DevOps 上的远端不会收到凭据，所以那里的私有仓库会失败。有意为之
拉取请求、议题、CI 和通知仅限 GitHub.com。有意为之
没有 Git LFS、没有子模块、没有提交签名（GPG 或 SSH）。 LFS 文件仍是小文本指针，克隆不会获取子模块，提交也没有签名。尚未提供
Git 钩子永远不会运行，导入的仓库的钩子会被删除。有意为之
本地终端没有 git 程序。 它的 Git 面板使用内置引擎，能做的事比 git 少。通过 SSH 时使用主机自己的 git。有意为之
只有本地分支会出现在合并、比较和变基的列表中。你不能从远程分支创建本地分支，也没有任何删除或重命名分支的功能。尚未提供
源代码管理不能创建仓库、不能 fetch，也不能创建或切换分支、amend、放弃更改、打标签或编辑远端。 项目页面和终端能覆盖其中大部分。尚未提供
引导式的冲突解决只用于合并和变基。 合并分支对话框和交互式变基有；发生冲突的 pull、已应用的储藏或 cherry-pick 会留下标记，需要你自己编辑。尚未提供
储藏： 新文件不包含在内，而且弹出总是取最新的一条。尚未提供
变基不能重新排序提交，也不能使用 Edit。有意为之
变基和 cherry-pick 只能从 GitHub 面板打开，并且仅当 origin 在 github.com 上时。尚未提供
Cherry-pick： 哈希需要手动输入，多个哈希不保证严格按顺序，新提交显示的是你输入的哈希，冲突没有解决器。尚未提供
无法提交拉取请求的评审，无法写行评论，也无法阅读拉取请求的差异。 创建内容时不能选择评审人、指派人和里程碑。尚未提供
GitHub 列表最多显示 300 条； 通知会加载六页，每页 50 条。有意为之
通知需要 GitHub 允许读取通知的令牌： 细粒度令牌会被拒绝。第三方
GitHub 的请求上限： 达到上限时，面板会提示你几分钟后再试。第三方
只有在 GitHub 为 PocketCode 的 OAuth 应用开启设备流程时，验证码登录才可用； 否则面板会提示 GitHub 没有提供该方式。第三方
克隆、fetch、pull、push、发布以及 GitHub 上的一切都需要网络。 其他功能都可离线使用。需要网络
终端 Git 面板： 本地没有 Diff，没有储藏说明，不能放弃单个文件，没有合并、变基、标签或 blame。尚未提供
项目页面： 不能删除或重命名分支，没有 mixed reset，不能从提交中恢复文件。尚未提供
本地历史记录： 每个文件 50 个版本、总共 50 MB，没有按时间的过期，并且轻量模式下的文件（大文件）不会保存任何版本。有意为之

故障排查

每个标题都是应用显示的消息。应用什么都不显示时，标题描述的是当时的情形。在 GitHub 面板中，横幅会先写出失败的内容，再写原因。

连接 GitHub

「代码在获批前已过期。请向 GitHub 重新申请。」

你花了超过约 15 分钟。点按重试获取新代码，然后批准它。

「该请求在 GitHub 上被拒绝，未保存任何内容。」

批准在 GitHub 的页面上被拒绝了，所以没有连接任何账号。点按重试，这次请批准。

「GitHub 目前未提供代码登录。请改为粘贴令牌，效果完全相同。」

获取代码的请求失败了。可能是 GitHub 没有为 PocketCode 的 OAuth 应用开启代码登录，这取决于 GitHub 的设置，与你的手机无关；请求发不出去（例如没有网络）时也会出现同一条提示。请先检查网络，再稍后重试。

「GitHub 未能完成授权。请重试，或改为粘贴令牌。」

登录结束时没有拿到令牌。点按重试并批准新的代码。

在项目页面克隆、push 和 pull

「此远程仓库使用 SSH，暂不支持。请改用仓库的 HTTPS 地址。」

PocketCode 只通过 HTTPS 与远端通信。请用 https://… 地址关联仓库；从克隆列表中克隆的仓库本来就使用它。

「此项目尚未配置远程仓库，请先在 Git 设置中关联。」

在项目卡片上打开 Git，使用关联我已有的仓库或在 GitHub 上创建并连接；或使用发布。

「尚未连接 GitHub 的账户。请在设置中连接后再上传或下载。」

先连接账号：设置 → 集成 → 已连接的服务。

「GitHub 拒绝了凭据。请在设置中重新连接账户。」

GitHub 不再接受已保存的令牌，例如因为它已过期或被撤销。请在“已连接的服务”中重新连接账号。

「无法连接 GitHub。请检查网络后重试。」

克隆、fetch、pull 和 push 需要网络。本地工作不需要。

「远端拒绝了本次上传。请先下载远端改动，然后重新上传。」

远端有你还没有的提交。点按下载改动，然后再次上传改动。

「你的分支和远程分支都有改动。」

先下载远程的改动，然后再上传：先下载改动，再上传改动。

「该项目与远程仓库没有共同的提交历史。」

通常是因为关联远端之前，文件夹里已有提交。请克隆到空文件夹，或关联其他远端。

「两边修改了相同的行。」

打开受影响的文件，保留你想要的版本，然后重试。pull 没有冲突解决器；在编辑器中发起的合并，在合并分支对话框里有（见冲突一节）。

GitHub PR 与 Issue

「“origin” 远程仓库不在 GitHub 上（…）。」

该面板只适用于 github.com。括号里的主机是 PocketCode 在 origin 中找到的那个。

「此项目没有 “origin” 远程仓库。添加一个 GitHub 远程仓库即可查看其拉取请求和议题。」

在项目卡片上使用 Git → 关联我已有的仓库，或发布。

「请在“服务”中连接你的 GitHub 账号，以查看 owner/repo 的拉取请求和议题。」

在未连接 GitHub 账号界面点按连接 GitHub 账号，或前往设置 → 集成 → 已连接的服务。

「GitHub 拒绝了该令牌。请在“服务”中重新连接你的 GitHub 账号。」

已保存的令牌被拒绝了。请在“已连接的服务”中重新连接账号。

「已连接的账号没有执行此操作的权限：…」

该账号能读取仓库，但不能执行这个操作。原因跟在冒号后面。

「未找到。如果仓库是私有的，已连接的账号可能无权访问。」

请确认已连接的账号就是能在 GitHub 上打开该仓库的那个账号。

「GitHub 拒绝了这些数据：…」

GitHub 没有接受发送的内容。原因跟在冒号后面。

「GitHub 暂时无法执行：…」

在当前情况下 GitHub 拒绝了这个操作。原因跟在冒号后面；如果拉取请求在你打开之后发生了变化，请重新打开它再试。

「已达到 GitHub 的请求上限。请在 … 分钟后重试。」

等待提示的分钟数。整屏的标题是 GitHub 已限制请求频率；时间过后点按重试。

「GitHub 出现问题（HTTP …）。请稍后再试。」

是 GitHub 自己返回了错误。你手机上没有任何问题。

「无法连接到 GitHub。请检查网络连接。」

GitHub 面板需要网络；Git 的其他部分不需要。

「GitHub 只向经典令牌或带有 "notifications" 权限的 OAuth 登录显示通知；细粒度令牌无法读取。」

只影响通知标签页；拉取请求、议题和 CI 仍然可用。

「拉取请求已创建，但无法添加审阅者或标签」

你的拉取请求已在 GitHub 上存在；只是附加项失败了。请在 GitHub 上打开它来添加。

交互式变基

「你不在任何分支上（分离的 HEAD）。请先切换到一个分支。」

切换到一个分支（项目 → Git → 分支，或终端的 Git 面板），然后重新开始。

「有未提交的更改：…」

提交它们，或打开开始前把我的更改存入 stash。

「此仓库中已有正在进行的合并或变基。」

请先完成或中止它。对于变基，面板里有继续、跳过这个提交和中止。

「变基会覆盖未跟踪的文件：…。请先移动或提交它们。未做任何更改。」

移动或提交消息中列出的文件，然后重新开始。

「加载列表后分支已发生变化。请重新加载。」

计划加载之后分支又有了新变化。重新打开交互式变基…来重新加载。

「Git 无法应用 …，已撤销变基。分支保持原样。」

没有丢失任何东西。消息中指出的那个提交无法应用到目标分支上。

「解决后这个提交变成了空提交。跳过它即可继续。」

你的解决结果没有留下任何可应用的内容。点按跳过这个提交。

「保留的第一个提交不能是“压缩”或“合并且不留消息”：前面没有可以合入的提交。」

给你保留的第一个提交选保留或改写信息。

「你正在丢弃所有提交。请至少保留一个。」

至少把一个提交从丢弃改成别的操作。

「这个分支没有变基备份。」

恢复备份只对 PocketCode 变基过、并且保存的顶端仍然存在的分支有效。

在编辑器和终端中

在编辑器中出现「推送失败：…」「拉取失败：…」或「提交失败：…」

冒号后面的内容是原因。push 和 pull 需要你已连接的账号；编辑器不会自己打开登录。项目页面（上传改动 / 下载改动）和终端的 Git 面板执行相同的操作，并用它们自己的措辞显示错误。

「合并在以下文件中有冲突：…」

合并因冲突而停下。再次打开合并分支：对话框会列出这些文件，让你逐个解决，或中止合并（见冲突一节）。

源代码管理显示没有检测到更改，但我改了文件

要么工作区是干净的，要么项目还不是仓库。在项目 → Git 中，尚未纳入版本控制表示你需要先开始跟踪此项目。

「此处没有 Git 仓库」

终端的 Git 面板在你工作的文件夹以及你工作区内它上面的文件夹中都没有找到 .git。点按初始化仓库。

「Git: …」

后面跟着原因。push 和 pull 需要你已连接的账号；面板自己不会打开登录界面。

下一步

代码编辑器编辑器的其余一切：标签页、搜索、语言服务器和运行器。项目项目页面：模板、导入、导出和项目卡片。Linux 终端Linux 终端、SSH，以及 Git 面板所在的工具面板。平台服务GitHub 和其他账号如何连接，以及每个账号能带来什么。