Git 命令找不到速查：git 不在 PATH、git-lfs 未装与 GUI 自带旧版本
更新时间：2026-10-24。FAQ 速查页，面向新机器上敲
git回一句 command not found、或克隆下来的大文件变成几行文本的同学。「命令找不到」分两个层面：一是 git 本体没装或不在 PATH 里，终端找不到可执行文件；二是 git 装了但扩展组件（最典型是 git-lfs）没装，命令存在、行为却不对——LFS 管理的文件被拉成指针文本。再叠加一层环境差异：终端里 git 好好的，IDE 或 GUI 工具里却用着一个内置的旧版本，功能对不上。病因收敛在六根轴上：git 本体未安装或未进 PATH、登录 shell 与非交互 shell 的 PATH 不同、git-lfs 未装导致指针文件当文本、GUI 自带 git 版本过旧、包管理器装错同名包、以及权限不足装不上也跑不了。顺一遍基本必中。如果是 git 能跑但连不上远端，转 Git connection refused 速查。
本文要回答的问题
- 终端报
git: command not found，是没装还是装了找不到？ - 终端里 git 正常，IDE 里却报找不到 git，差异在哪？
- 克隆下来的大文件（模型、图片）只有一百多字节的文本，是怎么回事？
git lfs报 unknown command，装了 git 为什么还没有 lfs？- GUI 工具的 git 版本比终端旧很多，该让它用哪个？
一、报错原文与典型现象
「找不到」类报错分散在三个层面：shell 层、git 扩展层、文件内容层（远端地址以 git.example.com 占位，路径以 /proj/demo 占位）：
# shell 层：git 本体找不到
$ git status
zsh: command not found: git
# Windows 上
'git' 不是内部或外部命令，也不是可运行的程序# git 扩展层：lfs 子命令不存在
$ git lfs install
git: 'lfs' is not a git command. See 'git --help'.
# 文件内容层：大文件被拉成 LFS 指针
$ cat model.bin
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a2149...(略)
size 83886080读现象先分三层：shell 直接说 command not found 是 PATH 层问题，git 根本没被执行；git: 'lfs' is not a git command 是 git 本体在、扩展不在；文件内容是 version https://git-lfs... 开头的短文本，说明克隆时 LFS 没工作，真实内容还在远端 LFS 存储里没拉下来。三层修法互不相干，先定性。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| command not found: git | 未安装或不在 PATH | which git / where git 查位置 | 装 git 或把 bin 目录加进 PATH |
| 终端能用 IDE 不能用 | IDE 用了非登录 shell 的 PATH | IDE 设置里看 git 路径配置 | IDE 里显式填 git 绝对路径 |
| 'lfs' is not a git command | git-lfs 未安装 | git lfs version 验证 | 装 git-lfs 并执行 git lfs install |
| 大文件是短文本指针 | 克隆时 LFS 未装或未拉取 | 文件开头是 version https://git-lfs | 装 lfs 后 git lfs pull 补拉 |
| GUI 报不支持的新特性 | GUI 内置 git 版本过旧 | 对比 GUI 设置页与终端 git --version | GUI 切换到系统 git |
| 装完仍是旧版 | 包装错或 PATH 顺序被旧版抢先 | which -a git 列全部位置 | 调整 PATH 顺序或卸载旧版 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓分水岭：shell 直接报 command not found 走左支查 PATH——git 在哪、当前环境找不找得到；git 本体活着但 lfs 子命令缺失或大文件变指针走右支——装 git-lfs 并补拉真实内容。GUI 与终端版本不一致本质是左支的变种：两个环境各用各的 git。
四、逐条排查展开
command not found：先确认是没装还是装了找不到。 用 which git（Linux/macOS）或 where git（Windows）查——没输出就是没装或不在 PATH。没装就装：macOS 用系统提示的开发者工具或 Homebrew，Linux 走发行版包管理器，Windows 用官方安装包。装了但找不到，是 PATH 没包含 git 的 bin 目录：找到实际安装位置，把所在目录写进 shell 配置文件（登录 shell 的配置文件，如 zshrc 或 profile），重开终端验证。Windows 安装时勾选「把 git 加入 PATH」那一项就是干这个的，跳过了就要手工补。改完配置不生效是高频疑问——当前终端读的是启动时的旧环境，要么重开窗口，要么手动 source 一次配置文件，别在旧窗口里反复怀疑自己改错了。
终端能用、IDE 报找不到：两类 shell 的 PATH 不一样。 macOS/Linux 上 IDE 从图形会话拉起时读的是登录 shell 环境，而你把 PATH 写在了交互 shell 的配置里；Windows 上 IDE 可能要求显式配置 git 路径。症状固定：终端敲 git 一切正常，IDE 里版本控制面板报「找不到 git 可执行文件」。处置：在 IDE 设置里显式填 git 的绝对路径（先 which git 拿到），这是最稳的一招，不依赖环境继承。
git lfs 报 unknown command：git 和 git-lfs 是两个包。 git-lfs（Large File Storage）是独立组件，不随 git 本体安装。装了 git 不代表有 lfs，git lfs version 验证。装完还要执行一次 git lfs install 把过滤器挂进 git 配置——只装包不 install，克隆时 LFS 文件照样被拉成指针。团队仓库根目录有 .gitattributes 且里面标了 filter=lfs 的，就是用了 LFS 的信号，新成员装机清单里必须有 lfs 这一项。
大文件变指针文本：克隆时 LFS 没工作，补拉就行。 指针文件很好认：version https://git-lfs.github.com/spec/v1 开头，下面一行 oid 哈希和 size，总共一百多字节。这意味着 git 把 LFS 管理的文件按「占位符」拉下来了，真实内容还在远端 LFS 存储。处置：装好 git-lfs 并 git lfs install 后，在仓库里跑 git lfs pull 把所有指针替换成真实文件；下次克隆前就装好 lfs，克隆时自动拉全。注意 git lfs pull 只补当前检出引用的文件，切分支后如有缺失再补。
GUI 自带 git 版本过旧：两个 git 各跑各的。 不少 GUI 工具内置了一份 git，图的是开箱即用，但内置版本往往落后于系统版——新特性（如较新的 sparse-checkout 行为、新协议支持）在 GUI 里用不了，甚至行为与终端不一致，排查问题时分不清是仓库问题还是工具问题。处置：GUI 设置里把 git 路径切到系统安装的那份，终端和 GUI 用同一个 git，行为才可比。切换后顺便看一眼 GUI 里显示的版本号确认生效。
装完仍是旧版：PATH 顺序在作怪。 机器上有多份 git（系统自带一份、包管理器装一份、某 IDE 又塞一份）时，which -a git 能列出 PATH 里所有命中，排第一的生效。新装的版本没生效，多半是老版本所在目录在 PATH 里排更前。处置：调整 PATH 顺序把新版本的目录提前，或者干脆卸载多余旧版，机器上只留一份 git 是最省心的状态。
权限不足让「装了等于没装」。 公司管控机器上，包装上了但可执行文件被安全策略拦、或装进了需要管理员权限才能读的目录，终端里照样 command not found。验证方法：which git 拿到路径后直接执行该绝对路径，能跑说明是 PATH 问题，跑不了且报权限错误就是策略拦截——后者不要硬绕，走 IT 流程把 git 加白名单或换装到用户目录下的可写位置。Windows 上还有一类近似问题：防病毒软件把 git 的某些辅助进程隔离了，表现为 git 能跑但 clone 中途莫名失败，日志里查杀记录是线索。
五、规范做法与预防
- 装机清单固化：git、git-lfs、编辑器/Git 配置列入新机器 checklist，装完跑
git --version && git lfs version验收。 - IDE 显式配路径：不依赖环境继承，IDE 与 GUI 一律显式指向系统 git 绝对路径。
- LFS 仓库写明前置依赖：用了 LFS 的仓库在 README 顶部标注「克隆前先装 git-lfs」。
- 机器上只留一份 git：多余版本卸载，PATH 顺序清晰，避免「装新的用旧的」。
- 环境自检脚本：团队配一个检查脚本，跑一遍输出 git/lfs 版本与路径，入职第一天先跑。
- 指针文件进评审雷达：代码评审里看到
version https://git-lfs开头的短文件变更，立刻意识到有人 LFS 没装好。
这一篇在知识体系里的位置
本篇是 Git 排错速查簇的「环境与安装」入口篇：git 装好了但连不上远端看 Git connection refused 速查；认证失败是另一层问题，看 Git auth failed 速查；依赖缺失类报错的通用排查法交叉参考 Git missing dependency 速查；版本差异引发的行为不一致看 Git version mismatch 速查。「先定层（shell 层/扩展层/内容层）→ 再验证（which/version）→ 装机清单防复发」这条主线对一切环境类报错通用。
一句话总结
Git 命令找不到先定层：shell 报 command not found 是没装或不在 PATH，which git 验证后装包或修 PATH，IDE 找不到就在设置里填绝对路径；git: 'lfs' is not a git command 是 git-lfs 这个独立包没装，装完必须 git lfs install；大文件变短文本是克隆时 LFS 没工作留下的指针，git lfs pull 补拉真实内容；GUI 内置 git 版本旧就切到系统 git，机器上只留一份。根治靠装机清单与环境自检脚本，把 git/lfs 版本验收变成入职第一步。