gitconfig 与 gitignore 写法错误速查：语法解析失败的六个根因

更新时间：2026-10-24。FAQ 速查页，面向 git config 报 fatal: bad config line 12 in file /home/user/.gitconfig 或 .gitignore 里写了规则文件却照样被跟踪的同学。gitconfig 语法错误的含义一句话：.gitconfig 是 INI 格式（节名 + 键值对），一行走错整个文件解析失败；.gitignore 没有解析报错却有一套「最后匹配生效、目录斜杠、否定规则」的暗坑语义，规则写了不生效九成是语义没写对而不是 Git 出问题。收敛在六根轴上：INI 节名缺方括号或拼错、键值行缺等号、值里引号转义写错、gitignore 否定规则顺序颠倒、目录末尾斜杠语义误解、通配符用错层级。本篇主线工具是 git config --list --show-origin 与 git check-ignore -v——前者照出每条配置来自哪一行，后者照出某文件被哪条 ignore 规则命中。

本文要回答的问题

• bad config line 12 的错误怎么定位到具体写错了什么？
• 为什么 .gitignore 里写了 *.log，某个 log 文件还是没被忽略？
• !important.log 否定规则为什么有时不生效？
• build 和 build/ 在 gitignore 里有什么区别？
• * 与 ** 在 gitignore 里各匹配什么？

一、报错原文与典型现象

gitconfig 解析失败与 gitignore 不生效的真实措辞如下（路径以 /proj/demo 占位）：

$ git -C /proj/demo status
fatal: bad config line 12 in file /home/user/.gitconfig

$ git config --global user.name "zhang san"
fatal: bad config line 5 in file /home/user/.gitconfig

$ git -C /proj/demo check-ignore -v logs/debug.log
.proj/demo/.gitignore:3:!*.log    logs/debug.log

$ git -C /proj/demo status
On branch master
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        build/output.bin

读症状抓两类信号：bad config line N 是 INI 解析器在 .gitconfig 第 N 行撞墙，错误一定在那一行或上一行未闭合的引号里；gitignore 类的「不生效」从不报错，唯一的照妖镜是 git check-ignore -v <文件>——它会告诉你命中的是哪个文件的哪一行规则，没命中就是根本没规则罩住它。两类病两种查法，不要用猜的。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
bad config line N	第 N 行键值缺等号或节名拼错	sed -n 'Np' .gitconfig 看该行	补 key = value 的等号
bad config line，行号偏大	上面某行引号未闭合吞掉后续行	从报错行往上查成对引号	补齐引号或改用单引号
config 值含路径空格被截	值带空格没加引号	git config --get 取值不全	值整体用双引号包住
gitignore 否定规则不生效	! 规则写在被排除的目录之后	git check-ignore -v 看命中行	否定规则后置，且父目录不能被排除
build 把 src/build.c 也忽略了	没写目录斜杠，通配所有层级	git check-ignore -v src/build.c	根目录限定写 /build/
doc/*.txt 没忽略 doc/a/b.txt	单星不跨目录层级	git check-ignore -v doc/a/b.txt	跨层用 doc/**/*.txt
已跟踪文件加 gitignore 无效	gitignore 只管未跟踪文件	git ls-files 里有该文件	git rm --cached 移出索引
Windows 下行尾规则失效	CRLF 行尾让规则名带不可见字符	cat -A .gitignore 看行尾	存为 LF 行尾

三、排查决策图

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

读这张图抓分流点：入口先分清是「config 文件解析炸了」还是「ignore 规则静默不命中」——前者有行号可追，--show-origin 直接给出文件与行的对应；后者永远不报错，只能靠 check-ignore -v 反查命中情况。两条线最后都汇到同一个纪律：config 改动走 git config 命令而不是手改文件，ignore 新规则写完先验证再提交。

四、逐条排查展开

第一条：键值缺等号与节名拼错——bad config line 的最大头。 .gitconfig 是 INI：节名 [user] 方括号成对、节内每行 key = value。手改文件最常见的错是把等号写成冒号、或节名少了个右括号：

[core]
	editor = vim
[userr]              # 拼错：git 不认这个节，不算语法错但配置不生效
	name = zhang
autocrlf = true      # 语法错：游离在节外的键值行，bad config line

定位命令：git config --list --show-origin，它逐条打印「文件:行号 键=值」，报错行之前的配置都会列出来，第一个缺失的位置就是病灶。纪律：config 一律用 git config --global core.editor vim 这类命令改，让 Git 自己写文件，手改是这类事故的唯一源头。

第二条：引号未闭合——行号指偏的隐形坑。 报错说第 12 行有问题，实际错在第 8 行一个没闭合的引号：解析器从第 8 行起把后面所有内容当字符串吞掉，到第 12 行才撞上非法字符。处置：从报错行往上查成对引号，值里必须含双引号时用 \" 转义，或整值换单引号。

第三条：否定规则顺序——gitignore 最经典的翻车。 gitignore 语义是「按行从上到下，最后匹配的那条生效」：

*.log            # 先全部排除
!important.log   # 再把这一个捞回来

顺序颠倒（!important.log 写在 *.log 之前）就等于没写——后到的 *.log 会再次把它排除。还有一条更隐蔽的规则：父目录被排除后，里面的文件无法被否定规则捞回——logs/ 被排除后写 !logs/important.log 是无效的，因为 Git 根本不会进入被排除的目录遍历。验证一律用：

git check-ignore -v logs/important.log   # 命中哪行、生没生效，一眼见底

第四条：目录斜杠语义——build 与 build/ 与 /build/ 是三种东西。 末尾带 / 只匹配目录（build/ 不会忽略名叫 build 的文件）；开头带 / 锚定 gitignore 所在目录（/build/ 只忽略根下的 build 目录，不动 src/build/）；两头都不带的 build 匹配任意层级任意同名文件或目录——想忽略根构建目录结果把 src/build.c 也误伤的事故，就是少了开头那根斜杠。

第五条：通配符层级——* 不跨目录，** 才跨。 doc/*.txt 只罩 doc/ 直属一层的 txt，doc/a/b.txt 罩不住；要罩任意层级写 doc/**/*.txt。这条在多层源码树里高发，规则看着对、文件照样漏进 git status，check-ignore -v 一验便知。

第六条：已跟踪文件与行尾——两条收尾杂病。 其一：gitignore 只对未跟踪文件生效，文件一旦进过索引（git ls-files 能列出），后加的 ignore 规则对它无效——先 git rm --cached <文件> 移出索引，规则才接管。其二：Windows 上编辑器存成 CRLF 行尾，规则名尾部带不可见的 \r，匹配全部失败——cat -A .gitignore 看到行尾 ^M 就是它，统一存 LF。

五、规范做法与预防

• config 只经命令改：任何配置走 git config [--global] key value，Git 自己保证语法正确，手改文件只在读源码级文档时参考。
• ignore 新规则先验证：写完一条规则立刻 git check-ignore -v 拿真实文件验，命中预期再提交；顺手跑 git status --ignored 看全貌。
• 否定规则后置：! 规则永远写在对应排除规则之后，且确认父目录没有被整目录排除。
• 目录规则写全斜杠：锚根目录就 /build/，任意层级目录就 build/，不写裸 build。
• 已跟踪文件先出索引：给已在版本库里的文件加 ignore，第一步永远是 git rm --cached。
• 文件统一 LF：.gitignore 与 .gitattributes 存 LF 行尾，编辑器配好，跨平台协作不出 invisible 坑。

这一篇在知识体系里的位置

本篇是 Git 排错速查簇的配置语法篇，定位「INI 解析失败与 ignore 规则语义不命中」：大仓库内存问题看 git 大仓库内存耗尽速查；引用与路径找不到看 bad revision 速查 与 pathspec did not match 速查；中文文件名乱码看 git 中文乱码速查；合并无共同祖先历史看 refusing to merge unrelated histories 速查；config 的分级与 clone 基础见 config、init、clone；add/commit 工作流见 status、add、commit。

一句话总结

gitconfig 与 gitignore 写法问题的本质是「INI 语法硬报错」与「ignore 语义静默不命中」两条线：前者靠 git config --list --show-origin 定位行号，缺等号、节名错、引号未闭合是三大根因，纪律是 config 只经命令改；后者靠 git check-ignore -v 反查命中行，否定规则必须后置且父目录未被排除、/build/ 与 build 语义不同、* 不跨层级、已跟踪文件先 git rm --cached。每条新规则写完即验，这类坑基本绝迹。