Git项目提交忽略文件怎么做？以Python项目为例，详解.gitignore

文章背景

我们在用 Git 维护 Python 项目时，本地运行代码会源源不断产生各类临时文件：

Python 编译后的 __pycache__ 缓存目录
虚拟环境文件夹
程序运行输出的日志
IDE 自动生成的配置文件
本地密钥配置、数据集文件等等
很多新手直接执行 git add . 全量提交，会把上述无关文件一并提交到远程仓库。这不仅会造成仓库体积膨胀、提交记录杂乱冗余，还存在极大安全隐患------很容易把本地密钥、数据库账号等敏感信息泄露到公网仓库。
Git 本身并不会自动过滤 Python 项目的临时产物，这时候就需要借助 .gitignore 配置文件，告诉 Git 哪些文件、目录不需要纳入版本追踪。本文以 Python 实际项目为例，完整讲解 .gitignore 的编写规则、实操步骤以及开发中高频踩坑问题。

💡小提示：很多同学手敲的时候容易写错文件名，不是.gitnone！正确文件名是 .gitignore，开头带英文点号，属于隐藏文件。

一、什么是 .gitignore

.gitignore是Git的忽略规则配置文件，一般放置在项目根目录 。

文件内部定义匹配规则，Git读取该文件后，会自动忽略命中规则的文件与文件夹，git add、git commit、git push都不会对这些内容做版本追踪。

⚠️核心重点：.gitignore仅对还没有被Git追踪的文件生效 。

如果文件已经提交推送到远程仓库，后续再写忽略规则是不会自动生效的，需要手动解除Git追踪。

二、Python项目通用 .gitignore模板

在项目根目录新建名为.gitignore的文件，下面是Python项目开箱即用的模板，#代表注释，方便阅读理解，可以按需增删规则。

gitignore 复制代码

# Python字节码、编译缓存
__pycache__/
*.py[cod]
*$py.class

# Python虚拟环境（常用venv / .venv / env）
venv/
.venv/
env/
ENV/

# 项目打包构建产物
dist/
build/
*.egg-info/
*.egg

# 程序日志文件
*.log
logs/

# IDE编辑器配置文件
# VSCode
.vscode/
*.code-workspace
# PyCharm
.idea/
*.iml

# 本地环境变量、密钥配置，防止密钥泄露
.env
.env.local

# 数据集、大资源文件
data/
dataset/

# 操作系统自动生成的垃圾文件
.DS_Store
Thumbs.db

基础语法简单解读

规则末尾带/：代表匹配文件夹，例如venv/会忽略整个虚拟环境目录；
*为通配符，*.log代表匹配所有.log后缀的日志文件；
#开头为注释语句，Git会直接跳过该行，不会作为匹配规则；
一行书写一条忽略规则。

三、完整实操步骤

在Git项目根目录 创建.gitignore文件

Windows系统新建文件时，直接输入完整文件名.gitignore，系统会自动识别为隐藏文件；千万不要命名为.gitignore.txt，txt后缀会直接导致配置失效。

将上面的模板复制粘贴，保存文件。
.gitignore本身需要提交到版本仓库，团队成员可以共用同一套忽略规则

bash 复制代码

git add .gitignore
git commit -m "feat: 添加.gitignore，配置Python项目文件忽略规则"

完成之后，后续执行git add .，缓存文件、虚拟环境、IDE配置就不会被纳入提交。

四、高频踩坑：已经提交过的文件，.gitignore不生效

问题场景

前期没有配置忽略规则，已经把venv、__pycache__等目录推送到远程仓库，之后才新增.gitignore。

此时即便写好了忽略规则，Git依旧会继续追踪这些已经入库的文件，配置不会自动生效。

解决方案

使用git rm --cached，只删除Git的追踪记录，本地磁盘文件会完整保留，不会被删除。

bash 复制代码

# 取消追踪整个文件夹，示例：venv虚拟环境目录
git rm -r --cached venv/

# 取消追踪单个文件，示例：本地日志文件
git rm --cached test.log

执行完毕后，再次提交更新到仓库：

bash 复制代码

git add .
git commit -m "fix: 取消对已忽略文件的git追踪"
git push

执行完成后，远程仓库会移除对应文件，本地文件不受影响，后续不会再提交这类文件。

五、取反语法：! 强制不忽略

有时候需要忽略整个文件夹，但保留文件夹内个别文件，可以使用!做取反匹配。

场景举例：Git不会提交空文件夹，如果想要保留空的logs目录，忽略全部日志，但是保留占位文件.gitkeep

gitignore 复制代码

logs/
!logs/.gitkeep

上面规则含义：忽略logs目录全部内容，唯独保留logs/.gitkeep文件。

六、直接使用官方现成模板

不用从零手写全部规则，GitHub维护了各编程语言的标准gitignore模板。

Python官方模板地址：https://github.com/github/gitignore/blob/main/Python.gitignore

可以直接复制官方模板，结合自己项目实际情况删减修改，快速完成配置。

七、总结

文件名称务必是.gitignore，放置在项目根目录，不要放到.git文件夹内部，放到里面配置完全无效；
.gitignore只对未追踪文件生效，已经提交过的文件，需要用git rm --cached解除追踪；
Python项目核心忽略内容：__pycache__缓存、虚拟环境、IDE配置、日志、.env密钥文件；
.gitignore本身需要提交仓库，实现团队统一忽略规范，避免每个人提交一堆无关文件。

❌常见错误：文件名写错、多出txt后缀、存放位置错误、期望对已经提交的文件直接生效。