必须忽略venv/和__pycache__/等自动生成文件，因其为本地运行时产物、含绝对路径或版本不兼容字节码；已跟踪文件需用git rm -r --cached手动清理索引，否则.gitignore无效。
不配 .gitignore，你的 Git 仓库很快会变成“垃圾场”——venv/ 被提交、__pycache__/ 每次都 diff 出一堆变更、同事 clone 下来还要手动删缓存，协作直接卡死。
为什么 venv/ 和 __pycache__/ 必须忽略
它们不是代码，是本地运行时产物：虚拟环境目录（venv/、.venv/、env/）由 Python 工具生成，含绝对路径、平台相关二进制文件，无法跨机器复现；__pycache__/ 是解释器自动生成的字节码，每次修改 .py 就变，且不同 Python 版本生成的 .pyc 不兼容。
常见错误现象：
- 提交了
venv/后，Git diff 显示成百上千个二进制文件变更 -
git status总显示modified: venv/bin/pip这类无关变动 - CI 流水线因拉取几百 MB 的
venv/而超时失败
正确做法：
立即学习“Python免费学习笔记（深入）”；
- 在
.gitignore中写venv/、.venv/、env/三行，覆盖主流工具（python -m venv、poetry、virtualenv）生成的路径 - 用
__pycache__/+*.py[co]组合，兼顾子目录和旧版.pyo - 注意末尾加
/：写成venv是忽略同名文件，venv/才是忽略目录
.gitignore 对已跟踪文件完全无效
这是最常踩的坑：你刚发现 __pycache__/ 被提交了，于是往 .gitignore 加一行，git status 依然显示它 —— 因为 Git 只对“从未跟踪过的文件”生效。
必须手动清理索引：
使用 `gh` CLI 与 GitHub 交互。通过`gh issue`、`gh pr`、`gh run` 和 `gh api` 管理 issue、PR、CI 运行以及高级查询。
- 运行
git rm -r --cached __pycache__/删除缓存但保留本地文件 - 再
git add .gitignore && git commit -m "ignore __pycache__" - 如果已经提交过
venv/，用git rm -r --cached venv/，否则每次git pull都会把别人删掉的venv/又拉回来
性能影响：不清理已跟踪的缓存目录，每次 git status 都要遍历数千个 .pyc 文件，命令响应明显变慢。
哪些 .env 类文件该忽略、哪些该保留
.env 本身应忽略——它通常含数据库密码、API 密钥等敏感信息；但 .env.example 可以提交，作为模板供新人复制后填写。
容易混淆的点：
-
.env：忽略（通用约定，被python-decouple、dotenv自动加载） -
.env.local或.env.development：也忽略，属于本地配置 -
.python-version：视团队而定——若统一用 pyenv 管理版本，可提交；否则忽略 -
.vscode/settings.json：建议提交，用于统一代码格式化规则；但.vscode/extensions.json忽略
IDE 配置如 .idea/、.vscode/ 忽略是安全的，它们只存用户偏好，不影响项目构建。
推荐直接用 GitHub 官方模板起步
手写容易漏项，比如忘记 .pytest_cache/ 或 .mypy_cache/。GitHub 的 python.gitignore 已覆盖主流场景，执行这条命令就能拉下来：
curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
之后再追加你项目的特例，比如：
- PyTorch 项目加
**/*.pt、runs/ - Django 项目加
db.sqlite3、local_settings.py - Jupyter 项目加
.ipynb_checkpoints/
真正麻烦的从来不是写规则，而是清理历史中已经混进去的缓存和环境目录——一旦提交过，就得靠 git rm --cached 补救，而且所有协作者都得同步执行一遍。
