版本控制（简易 Git）

Git、GitHub 与云

Git 是本地的。它是一个在你电脑上运行的免费程序，把版本历史保存在文件夹本身里的隐藏文件夹 .git 中。启用版本控制不会向互联网发送任何内容，也不需要任何账号：版本只保存在这台电脑上——如果硬盘损坏或电脑丢失，版本也会一起丢失。

GitHub 则是另一回事：它是一项云服务，保存仓库的一份副本。同步时，LightNote 会把版本发送到 GitHub 或类似的服务。有了这份放在别处的副本，你就有了备份，还可以在另一台电脑上使用同一批笔记：在一台上发送，在另一台上接收。GitHub 个人使用免费，可以创建无限个只有你能看到的私有仓库。

总之：Git 是你电脑上的版本；远程是它们在别处的一份副本——可以是 GitHub、其他服务、OneDrive 或 Google Drive 的文件夹，或你自己的服务器。只要文件夹还没有远程，版本控制面板就会显示版本只在这台电脑上。，并提供下文介绍的备份并同步…链接。

克隆仓库

要在已有的仓库上工作，请使用文件 → 克隆 Git 仓库...——这一项也在起始界面上，以及尚未成为仓库的文件夹的版本控制面板里。粘贴仓库页面显示的 HTTPS 或 SSH 地址；页面本身的网址也可以，整条复制的 git clone ... 命令同样可以。选择父文件夹和文件夹名：向导会显示它将创建在哪里，并在那里已经有东西时提醒你。高级选项里有分支、浅克隆（只取最后一个提交）和子模块。

当服务器要求登录时，LightNote 会在一个窗口里询问：用户名和令牌、SSH 密钥的密码短语，或者对这台电脑从未见过的服务器密钥的确认——这时窗口会显示指纹以及该服务公布清单的链接，默认是不信任。回答直接交给 Git，LightNote 不会保存；保存它的是 Git 的凭据管理器，前提是它已安装（Git for Windows 自带 Git Credential Manager）。信任该密钥会把它写入 ~/.ssh/known_hosts，就像 ssh 自己会做的那样。

如果克隆失败，界面会说明发生了什么并给出出路：SSH 密钥被拒绝时改用 HTTPS，公司代理检查 HTTPS 时使用 Windows 证书，连接中途断开时只下载最后一个提交，Windows 不让创建文件时使用长路径。技术细节里有 Git 的消息，无法识别的内容可以交给 AI。结束后，向导会在本窗口或新窗口中打开克隆好的文件夹。

对打开的文件夹做版本控制

版本控制按工作区选择启用。在工具 → 工作区 → 工作区配置...中 启用后，LightNote 会创建一个 Git 仓库（如果还没有），并显示 版本控制侧边栏（Ctrl+Shift+G）。

在自动模式下，LightNote 会在常规设置中选定的时机（保存时・关闭标签时・ 关闭窗口时）自动保存版本（提交）。会话期间，提交中只包含 LightNote 写入的内容——AI 的 CLI 或其他程序更改的内容保持待定，由更改它的一方自己提交；Ctrl+S 会立即保存版本，自动保存写入的内容每 10 分钟提交一次。关闭窗口时（默认开启）的提交会包含文件夹中所有的更改，包括在 LightNote 之外的更改：这是会话结束时的安全网。在手动模式下， 你在面板中写一条消息来保存版本。状态栏的指示器会显示状态 （无更改、X 项更改…），单击会打开 Git 菜单（见下文）；在尚未启用版本控制的文件夹中，会打开工作区设置的集成页。 你可以查看每个文件的差异，并还原（放弃）未保存的更改。

自动化按文件夹分为 3 个级别（在工作区设置中）:手动（不自动）、 自动提交（自动保存版本，但不同步）和全自动（提交并同步——提交后 推送＋定期拉取；需要无提示的 Git 凭据）。面板会显示相对于远程的↑ 待发送 / ↓ 待接收 状态行；当有待发送的版本时，主按钮会从提交变为同步——这样就能清楚地看出， 保存之后还需要同步。

Git 面板和树的 Git 菜单提供按文件的 添加 (git add) 和 还原 (git restore)，以及唯一的 查看更改，它会打开比较界面。面板列表按路径的自然顺序排列，文件的右键菜单还提供 复制... 和 在资源管理器中显示（已删除的文件不可用）。

比较界面把两个版本并排对齐显示：相同的内容始终两两相对，每一侧显示各自文件的行号。被替换的行显示为琥珀色，行内改动的部分会被高亮。统一视图按钮切换到补丁格式，交换两侧更换比较基准，F8 / Shift+F8 在各处更改之间跳转。

状态栏中的 Git 菜单。在已启用版本控制的文件夹中，指示器显示分支，并在旁边显示尚待同步的内容（↓ 待接收，↑ 待发送）；全部已保存为版本时圆点为绿色，有待处理的更改时为琥珀色，有冲突文件时为红色。单击会打开一个菜单，开头是完整的状态，并提供 保存全部为一个版本（提交）…（包含文件夹中的所有更改，包括其他程序做出的更改；消息留空则自动生成）、打开 Git 面板，以及在有远程仓库时的 同步（接收并发送）、接收（以合并方式 pull）、发送（push） 和 检查远程（fetch）。接收始终使用合并（merge），无论这台机器上的 Git 如何配置，都不会变基；如果合并出现冲突，不会进行发送，菜单会提供 撤销有冲突的合并…。在 自动操作 中，你无需打开设置就能切换文件夹的自动化级别。在 高级 中，运行 git 命令… 会在仓库文件夹中运行任意命令并显示输出——没有终端，因此需要输入的命令（消息编辑器、控制台中的密码）会直接放弃而不是等待；这类命令请使用终端。如果没有安装 Git，单击会打开安装指南。

移动和重命名。在 LightNote 中移动或重命名文件或文件夹时 (在树中拖动、剪切并粘贴、重命名)，版本会同时记录新旧两处，Git 将其记为重命名。只有已经纳入版本管理的内容会进入；移动的文件夹中的新文件和其他文件一样等待。规则与 Ctrl+S 相同：关闭保存时提交后，移动会等到下一次提交。大文件不会进入，见大文件与各服务的限制。

历史与变更条

代码编辑器和笔记工具栏上有两个管理文件版本的按钮。保存版本 会写入文件并保留这个版本：在用 Git 管理的文件夹中，它只提交此文件（其他程序或 AI 会话在其他文件中的改动不会被带进去）；在仓库之外，它会在本地历史中记下一个点。自上一版本以来没有任何更改时，它会变灰，原因显示在提示中。

版本 会打开当前文件的版本列表（就是侧边栏的同一个部分），它的箭头菜单提供 带消息保存版本…、查看自上一版本以来的更改 和 放弃自上一版本以来的更改…；最后一项会把文件恢复到上一版本（无论有没有 Git），放弃的文本保留在本地历史中，Ctrl+Z 也能将它找回。列表汇集 提交 和 本地保存：LightNote 每次 Ctrl+S 记录一个，自动保存时每个文件最多每 10 分钟记录一个，并保留第一次写入之前的文件，因此在不是仓库的文件夹里也能用。每一行显示主题、作者、时间以及增删的行数；圆点用于区分你自己的提交、LightNote 自身的保存和来自 AI 会话的提交。若有未提交的更改，它就是第一行。点击某个版本会显示该版本中的更改；打开整个版本、与当前版本比较、比较选中的两个版本都在右键菜单里。

页边的彩色条标出自上一版本以来更改的行 —— 代码编辑器和笔记都有，并且它会跟随你的输入：撤销回原样时它就消失，不必等到保存。上一版本是你打开文件时的最后一次提交（没有 Git 时，就是打开时的文件）。保存和自动提交不会移动它：标记会一直保留，直到你点击 保存版本 或关闭标签页。要关闭请用视图 → 更改条；关闭后它不只是被隐藏 —— 根本不会进行计算。点击色条会显示该片段原来的样子，并提供 还原此片段（Ctrl+Z 可撤销）、复制原内容，以及 在差异中查看——直接打开定位到该行的完整比较。当打开的文件在 LightNote 之外被修改时（例如 AI 的 CLI 正在写入），没有未保存编辑的标签页会静默重新加载，色条显示改动；如果你的编辑在其他位置，两者会被合并（Ctrl+Z 可撤销）；如果两者改了相同的行，标签页顶部会出现黄色横条，提供 比较、使用磁盘上的版本 和 保留我的版本——在你做出选择前，自动保存不会写入该文件，被舍弃的版本保留在本地历史中。关于本地历史有一点要注意：它按路径保存，因此重命名文件会丢失它的本地保存 —— Git 的提交不会。

行的作者与切换分支

这一行是谁写的。在状态栏的 Git 菜单中，行的作者 (blame) 会在光标所在行的末尾显示是谁、何时写的，以及版本摘要——例如 Ana · 3 天前 · 修正合计。只标注光标所在的行，标注会跟随光标。尚未进入任何版本的行显示 未纳入版本控制；有未保存的更改时，标注会提示 保存后可查看作者，因为磁盘上文件的行已与屏幕上的不一致。

切换分支。同一菜单中有子菜单 分支：main（显示当前分支名），列出本地分支：当前分支带勾选标记，点击其他分支即切换过去（git checkout）。创建分支… 会询问名称，在调用 Git 之前先检查（不能有空格和 ..，也不能以 - 开头），然后从当前分支创建新分支并在其上继续工作。有文件冲突或同步正在进行时，无法切换。

备份与同步：GitHub 分步指南

面板上的备份并同步…链接（与面板 ⋯ 菜单和状态栏 Git 菜单中的添加远程仓库…相同）会打开备份与同步界面，提供三种方式：推荐的 GitHub；其他服务；以及同步文件夹（OneDrive、Google Drive、Dropbox、U 盘或网络文件夹）。它们都可用；要在多台电脑上使用笔记，GitHub 最简单，作为备份也最安全。使用 GitHub：

1. 在 github.com/signup 创建账号：填写邮箱、密码和用户名；GitHub 会发送验证码确认邮箱。Free 方案就够用。
2. 在 github.com/new 创建仓库：起个名字（例如 notes），选择 Private，不要勾选 Add a README、.gitignore 或许可证。仓库必须为空：如果带有 README，第一次发送会被拒绝，因为 GitHub 上已经有了一段不属于你的历史。
3. 复制页面显示的 HTTPS 地址（类似 https://github.com/你/notes.git），粘贴到 LightNote 界面的仓库地址中。保持勾选立即发送版本，然后点击连接。
4. 登录：第一次发送时，Git 会打开 GitHub 窗口，让你在浏览器中授权。之后 Windows 会保存访问权限——由 Git for Windows 自带的 Git Credential Manager 保存——你无需再次登录。
5. 在另一台电脑上，安装 Git 和 LightNote，用同一个地址执行文件 → 克隆 Git 仓库...。此后，同步会接收另一台电脑发送的内容，并发送你在这里做的更改。

如果不想记着手动同步，可在文件夹设置中选择全自动：LightNote 会在每次提交后发送，并定期接收。有两个限制值得了解：GitHub 拒绝超过 100 MB 的文件，并建议仓库不超过约 1 GB——视频和大文件请放在受版本控制的文件夹之外。另外，私有意味着只有你（以及你邀请的人）能看到仓库，但内容存放在 GitHub 的服务器上：机密内容请使用安全 Markdown，它在离开电脑之前就已加密。

在手机上。连接远程仓库后，在手机上打开…（面板的 ⋯ 菜单和状态栏的 Git 菜单中）会显示一个二维码。在手机上的 LightNote 中点按工作区名称，选择扫描电脑上的二维码：该仓库会成为手机上的新工作区。二维码只包含地址，从不包含密码——如果仓库是私有的，手机会使用它为该服务器保存的 Git 账户，或要求输入访问令牌。手机通过 HTTPS 克隆：作为此电脑上文件夹的远程仓库（下文的 OneDrive）无法到达手机。

大文件与各服务的限制

限制。GitHub 对单个文件从 50 MB 起发出警告，并拒绝超过 100 MB 的文件；GitLab、Bitbucket 和 Azure Repos 同样拒绝超过 100 MB 的文件。对整个仓库，GitHub 建议不超过约 1 GB (最多 5 GB)，Bitbucket 的免费方案提供 1 GB。同步文件夹 (OneDrive、Google Drive) 没有这个上限。

为什么要在提交时注意。限制适用于历史中的每个版本，而不只是今天的文件：一个 120 MB 的文件一旦进入某个版本，推送就会被拒绝；即使之后删除该文件，旧版本仍包含它，推送依然会被拒绝。

LightNote 的做法。超过 100 MB 的文件不会进入应用保存的任何版本 (自动提交、Ctrl+S、保存版本、关闭窗口时的提交、快照以及手机同步)。文件仍留在文件夹中，提示框提供 在 Git 中忽略 (.gitignore)。超过 50 MB 的文件会进入版本，并在状态栏中提示。标记为 Git LFS 的文件 (仓库中只保存指针) 不会被拦下。

如果推送已被拒绝 (版本是在 LightNote 之外、在终端中保存的)，Git 面板会说明。删除文件并不能解决。如果该版本尚未发送，请在状态栏 Git 菜单的高级 → 运行 git 命令…中运行 reset @{u}：未发送的版本会被撤销，文件保持不变；把大文件加入 .gitignore，再保存一次版本。要把文件保存在仓库中，请使用 Git LFS (git-lfs.com)。

其他服务、OneDrive/Google Drive 和自己的服务器

其他服务。Git 在任何服务上的用法都一样，区别只在于你在哪里创建仓库。最知名的有：GitLab（gitlab.com，免费，每个私有仓库最多 10 GB）、Bitbucket（bitbucket.org，最多 5 个用户免费，总共 1 GB）、Azure DevOps（dev.azure.com，微软出品，最多 5 个用户免费，私有仓库不限数量）和 Codeberg（codeberg.org，非营利，但只面向开源项目——不适合私人笔记）。在那里创建一个空的私有仓库，复制地址，然后在备份与同步界面中选择其他服务。各方案的限制会随时间变化，请到各服务的网站上确认。

OneDrive、Google Drive 或 Dropbox，无需新账号。选择同步文件夹，指向这台电脑上该服务的文件夹（例如 C:\Users\你\OneDrive 或 G:\我的云端硬盘）。LightNote 会在其中创建一个裸仓库——一个只保存版本、不含工作文件的 Notes.git 文件夹——并把它用作远程；复制这个文件夹的工作由云服务完成。在另一台电脑上，等该文件夹同步出现后，粘贴它的路径，执行文件 → 克隆 Git 仓库...。同样的方式也适用于 U 盘或网络文件夹，用作备份。

• 为什么用裸仓库，而不是把整个笔记文件夹放进 OneDrive？工作时 .git 文件夹一直在变化，两台电脑通过云同步它可能会损坏它。裸仓库只有发送时才会写入，写入的内容之后也不会再改变。
• 一次只用一台电脑。在另一台电脑上工作之前，请等 OneDrive 或 Drive 同步完成；在此之前从两边同时发送，可能会产生冲突副本。如果经常发生，改用 GitHub 会省心得多。
• 如果工作文件夹已经在云里——Windows 常把“文档”文件夹放进 OneDrive——界面会给出提醒。只有一台电脑时，OneDrive 可以充当备份；要在多台电脑上使用笔记，请改用 GitHub，或把笔记文件夹移出云端，只把裸仓库留在那里。
• 不用 Git 也可以：用云服务同步整个笔记文件夹，并保持版本控制关闭——本地历史仍会保存每个文件的版本。这就是在手机上使用你的笔记中介绍的方式。

自己的服务器。如果不想依赖任何公司，可以自己托管 Git 服务器。Gitea 和 Forgejo 很轻量，有类似 GitHub 的网页界面，可以在 Docker 中运行——放在家里的电脑、树莓派、NAS 或租用的 VPS 上。最简单的做法是一台支持 SSH 的服务器，加上用 git init --bare 创建的仓库。代价是要自己维护服务器：安装、更新和备份；安装指南见各项目的网站。服务器就绪后，仓库地址和其他地址一样填入其他服务。