GitPython提交前必须检查工作区是否干净，用repo.is_dirty(untracked_files=True)判断，不干净需手动add；合并前应abort残留状态，push后须校验PushInfo.flags确认是否成功。
GitPython 提交前必须确保工作区干净
直接调用 repo.index.commit() 会失败，如果工作区有未暂存或未跟踪文件。GitPython 不会自动帮你 git add，也不会跳过冲突检查。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 先用
repo.is_dirty(untracked_files=True)检查是否干净；不干净时，手动repo.index.add([file_path])或批量添加（注意路径是相对于 Git 根目录的） - 避免用
glob或os.listdir构造文件列表——GitPython 看的是 Git 的暂存区状态，不是文件系统快照 - 如果想“提交所有已跟踪变更”，可用
repo.index.add(repo.untracked_files)是错的，untracked_files返回的是未跟踪文件，不能直接 add；正确做法是先repo.git.add('--all')（调用底层命令）或逐个判断repo.git.status('--porcelain')解析输出
merge() 方法不会自动解决冲突，且默认不执行 fast-forward
调用 repo.git.merge('feature-branch') 或 repo.head.reference.commit 相关操作，若存在冲突，会抛出 GitCommandError，错误信息里含 CONFLICT (content): 字样，但 GitPython 不提供内置冲突解析器。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 合并前务必
repo.git.merge('--abort')清理可能残留的合并状态（尤其在 CI 中重复运行脚本时） - 显式指定策略：如需强制 fast-forward，加参数
repo.git.merge('--ff-only', 'origin/main')；想禁用 ff 只走三路合并，用--no-ff - 不要依赖
repo.merge()（这是旧版 API，已弃用且行为不一致），统一走repo.git.merge()底层封装 - 合并后记得
repo.index.write()和repo.head.reference.set_commit(...)—— 否则 Python 层 HEAD 可能没同步，后续push()会推错提交
push() 失败常见于凭证、权限或拒绝非快进更新
origin.push('main') 表面成功但实际没推送，往往因为远程拒绝（如 protected branch、force push 被禁、缺少 write 权限），而 GitPython 默认不抛异常，只返回 PushInfo 对象，需主动检查其 summary 和 flags。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 检查
push_info.flags & PushInfo.REMOTE_REJECTED或push_info.flags & PushInfo.FORCED_UPDATE，而非只看push_info.remote_ref是否为 None - CI 场景下避免用 HTTPS + 用户名密码（已基本失效），改用
https://<token>@github.com/... </token>或配置repo.git.update_environment(GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no")配合 deploy key - 如果远程分支被其他人更新过，本地又没
pull，直接push会被拒；此时应先repo.git.pull('--rebase')再 push，但注意 rebase 可能触发 pre-commit 钩子失败
自动化场景中别忽略 .git/config 的动态修改风险
比如用 repo.config_writer().set_value('user', 'name', 'CI Bot') 设置提交作者，看似生效，但若多个线程/进程共用同一 repo 实例，或 config_writer 没 .release()，会导致写入丢失或文件锁冲突。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 每次修改 config 后必须调用
writer.release()，否则内容只在内存，不落盘 - 不要在并发任务中复用同一个
Repo实例；每个任务应通过Repo(path)重新打开，避免内部缓存（如head.commit）过期 - 设置 author/email 最稳妥的方式是临时注入环境变量：
repo.git.env = {'GIT_AUTHOR_NAME': 'CI Bot', 'GIT_AUTHOR_EMAIL': 'bot@example.com'}，比改 config 更轻量、无副作用
