Git 与 Overleaf

确认项目与连接方式

建议把 Overleaf 项目作为独立的论文 Git 仓库管理。可以让 ChatGPT 在这份本地仓库中修改 LaTeX、检查差异和编译，再通过 Git 与 Overleaf 同步。

开始前，确认自己对 Overleaf 项目有访问权限，并且项目可以使用 Git integration。Overleaf 的 Git integration 与 GitHub synchronization 是不同的功能：前者用于本地 Git 与 Overleaf 之间同步，后者用于 Overleaf 与 GitHub 仓库之间同步。这里介绍前者，不要求再建立一个 GitHub 副本。Overleaf 集成说明

在项目的 Git 入口复制实际连接地址，不根据项目名称猜地址或分支。若当前项目没有这一入口，先确认可用权限或请维护者协助。

建立本地论文仓库

新连接通常从克隆已有 Overleaf 项目开始。已有本地论文目录时，先检查它是否已经连接到同一远端，不要直接用新的克隆覆盖原文件。

Overleaf 使用 Git authentication token 认证。按其账号设置生成和管理令牌，在认证提示中输入；不要把令牌写进聊天指令、仓库地址或论文文件。可以通过 Git credential helper 使用系统凭据存储来保存认证信息。认证说明

请协助连接我的 Overleaf 论文项目。
目标本地目录：【论文目录绝对路径】
Overleaf Git 地址：【从项目 Git 入口复制的地址，不包含令牌】

先检查目标目录是否存在、是否已是 Git 仓库，以及是否已有远端或未提交文件。
已有内容时不要覆盖或重复克隆；先说明它与目标项目的关系。
需要认证时，请告诉我如何在正常认证入口输入令牌，并检查当前系统支持的 Git 凭据安全存储方式，不把令牌写入项目文件或输出。
连接后只读取远端，核对项目、分支和论文主文件。
本次不修改研究仓库的远端，不推送论文。

连接后，先只读取远端状态，确认项目、分支和论文主文件对应正确。研究仓库与论文仓库的组织方式见 项目与上下文管理。

搭建本地 LaTeX 环境

建议优先在本地编译论文。这样可以在推送前发现缺失文件、引用错误和版面问题；确认本地版本后，再通过 Git 将它同步到 Overleaf，作为合作者继续查看和编辑的版本。

这里以 MacTeX 为例。它包含完整的 TeX Live、常用字体和工具，安装体积较大，但处理不同模板时较少遇到缺包问题。磁盘空间有限时可以选择 BasicTeX，之后需要自行补装论文使用的宏包。二者选择一种即可。

安装前先检查本机是否已经有可用环境：

command -v latexmk
latexmk -v
command -v pdflatex xelatex lualatex

通过 MacTeX 官方安装包完成安装后，重新打开终端再运行这些命令。命令路径通常会经过 /Library/TeX/texbin。如果命令仍不可用，先检查当前 shell 的 PATH，不要重复安装另一套 TeX。

请检查当前设备和【论文仓库绝对路径】的本地 LaTeX 编译环境。

先读取项目说明、Makefile、latexmkrc 和主文件，确认项目使用的编译器与现有编译命令。检查 latexmk、pdflatex、xelatex、lualatex、BibTeX 和 Biber 是否可用，并报告实际路径与版本。
如果环境缺失，请根据当前操作系统和项目依赖给出适用的安装方案；开始下载安装前告诉我所需空间和会执行的步骤。
环境可用后，使用项目已有命令做一次本地编译，保存完整日志并确认预期 PDF 是否生成。整理错误和警告，不通过更换编译器、删除源文件或忽略失败来得到表面成功。
本次不修改论文内容、不提交 Git、不推送 Overleaf。

开始编译前，从项目说明、Makefile、latexmkrc 和 Overleaf 项目设置中确认主文件与编译器。项目已有编译命令时优先使用它；没有时可以参考：

将 main.tex 替换为实际主文件。latexmk 会根据文件依赖安排需要的多轮编译。清理常见辅助文件时可以使用 latexmk -c；先检查仓库约定，不要删除项目需要保留的生成文件。

开始修改前读取远端变化

每次修改前，先检查本地是否有未提交内容，再获取远端最新状态。如果合作者在 Overleaf 网页上修改了论文，需要先把这些变化纳入本地版本。

建议使用 pull --ff-only 处理可以直接快进的情况。它拒绝继续时，说明需要检查分支关系，不应直接改用强制覆盖。

在 ChatGPT 中修改并查看差异

说明本次要修改的段落、图表或问题，并限制到对应文件。修改后可以在 ChatGPT 的 Codex 模式中打开差异视图查看，也可以让 Agent 汇总改动与原因。

重点检查是否改变了论文原意、是否删掉合作者新增的内容、图表是否对应实际结果，以及引用键是否仍然正确。涉及整段重写时，同时看修改前后的上下文。

本地提交可以保存一次已经检查的修改。提交到本地 Git 与推送到 Overleaf 是两步操作；当你只要求本地修改时，应在本地结束。

请在【论文仓库绝对路径】修改【具体段落或问题】。

先检查本地状态，并获取 Overleaf 远端变化。
如果本地干净且可以快进，读取差异后更新；有未提交修改、分叉或冲突时，说明情况并保留双方内容。
然后完成本次指定修改，检查差异，按项目现有方法编译。
请报告改动、实际编译结果和仍需我核实的内容。
本次只在本地修改，不推送到 Overleaf。

编译并检查结果

在论文仓库中使用已经确认的主文件、编译器与项目命令。不要只根据目录中第一个 .tex 文件猜测入口，也不要在编译失败后直接改用另一种编译器掩盖问题。

编译完成后，确认命令退出成功并生成了预期 PDF，再查看未定义引用、缺失文献、缺少文件和字体等警告。打开最终 PDF 检查图表、页码、参考文献和版面。编译成功只说明文档能够生成，论文内容和结果仍需单独核实。

本地与 Overleaf 结果不一致时，先比较主文件、编译器和 TeX Live 版本，再检查宏包版本与系统字体。Overleaf 的编译器和 TeX Live 版本按项目设置保存，可以在项目设置中查看和调整。Overleaf 编译环境说明

辅助文件是否加入 .gitignore 以项目约定为准。通常不提交 .aux、.log、.fls、.fdb_latexmk 和 .synctex.gz；遇到已经被跟踪的文件或投稿流程要求保留的产物时，先确认再调整。

将确认后的修改同步到 Overleaf

当本地修改已经确认，明确告诉 Agent 可以推送。推送前再次获取远端状态，避免在修改期间错过合作者的新提交。

我已经确认【论文仓库绝对路径】中的本次修改，请同步到对应的 Overleaf 项目。

先确认仓库、分支、远端和本次要提交的文件，保留其他未提交工作。
推送前重新获取远端状态；可以快进时使用快进更新，有分叉或冲突时先列出差异，保留合作者更新。
检查并按项目约定编译，提交已确认的修改，再执行正常推送；不要强制推送。
推送完成后重新读取远端，报告实际结果、两边提交是否一致，以及剩余未提交文件。
编译或合并没有完成时，说明原因，不报告同步完成。

推送后重新读取远端，并比较当前分支的提交状态。报告应说明实际推送是否成功、本地与远端是否一致，以及是否仍有未提交文件。两边提交一致不代表所有本地文件都已纳入 Git，因此还需要查看工作区状态。最后在 Overleaf 中重新编译共享版本；如果结果与本地不同，回到编译环境差异继续检查。

处理冲突与误改

冲突通常表示相同位置被分别修改。请 Agent 展示各方修改的目的，先保留有效内容，再决定合并后的文本。科学判断存在分歧时，把分歧列出来交由作者讨论。

发现误改后，先找到对应提交，查看需要恢复的内容。已经共享的提交通常适合用新的修正提交恢复；不默认改写共享历史或强制推送。

同步完成不等于投稿。实际提交后，再记录投稿时间、稿件版本和系统返回的状态。

参考来源

• Overleaf：Git integration 与 GitHub synchronization
• Overleaf：Git authentication tokens
• MacTeX：下载与安装
• MacTeX：BasicTeX 与其他安装包
• CTAN：latexmk
• Overleaf：选择 TeX Live 版本与编译器
• Research-Workflow-Skills：独立论文仓库