Git 安装、升级与配置基线

Git 安装配置来源与升级验证安装来源、可执行文件、配置作用域和升级验证形成可解释、可回退的证据链。高清原图

很多 Git 故障看起来发生在 push、merge 或 CI，根因却在安装层。一个常见现场是：PowerShell 中 git --version 已经变了，IDE 仍报未知选项；开发者重装 Git 后，提交邮箱忽然换成个人账号；Linux CI 又把本机正常的脚本判成没有执行权限。此时继续重试业务命令只会混淆证据，先要回答三个问题：实际执行的是哪个 Git、它读取了哪些配置、仓库规则与文件系统语义是否一致。

假设你刚接手这台开发机，先不要卸载任何“看起来重复”的版本，也不要用管理员账号运行项目命令。企业设备可能由软件中心统一分发，IDE、GUI、WSL 和自动任务也可能各自绑定不同路径。先在日常账号下保存只读快照：

git --version
git --exec-path
git config --list --show-origin --show-scope

Windows：

where.exe git
Get-Command git -All | Format-Table CommandType, Source, Version

macOS/Linux：

type -a git
command -v git

把输出保存到临时诊断记录中，但删除真实仓库 URL、代理账号和内部路径后再共享。git --exec-path 指向 Git 的子程序目录，--show-origin --show-scope 则把配置值还原到文件与作用域；这两组证据能区分“版本没有切换”和“配置被覆盖”。只有确认安装渠道、设备策略和依赖它的入口后，才进入安装或升级。

从受控渠道安装 Git

Git 官方安装入口按操作系统维护当前发行方式。团队基线应写“批准的发行渠道与最低安全线”，而不是把某个最新版本永久写死；升级实施时，以发行说明、设备软件源和本机包管理器输出共同确定目标版本。

Windows

Git for Windows 提供 Windows 原生 Git、Git Bash 和常用集成：Git for Windows。企业设备优先使用组织批准的软件分发或包管理源；交互安装时需要明确默认编辑器、PATH、SSH 实现、HTTPS 后端和换行策略，不能一路接受默认后再让每台机器行为不同。

允许使用 WinGet 的设备可以从明确的软件包 ID 安装：

winget show --id Git.Git -e --source winget
winget install --id Git.Git -e --source winget

第一条先展示来源和候选版本，第二条才改变机器。企业软件中心已经托管 Git 时，不要再用个人包管理器叠装；交互安装包也应从官方入口获取并保留校验与发布记录。

安装后新开终端验证：

git --version
where.exe git
git --exec-path

WSL 中的 Git 属于 Linux 发行版，不等于 Windows Git。项目主要在 WSL Linux 文件系统中构建时，应在 WSL 内安装和调用 Git，避免 Windows Git 与 Linux 权限、路径和换行语义交叉。

macOS

macOS 可能通过 Xcode Command Line Tools 提供 Git，也可以使用 Homebrew 安装。先检查来源：

xcode-select -p
type -a git
git --version

如果团队选择 Homebrew，就要确认 PATH 顺序和 Apple silicon 路径，不能假设 git 自动指向新安装版本。系统更新后再次检查来源。

brew info git
brew install git
type -a git
git --version

brew info 先展示配方与安装状态。若 type -a git 的首项仍是系统 Git，应修正 shell PATH 并新开终端，不能用 alias 暂时掩盖顺序错误。

Linux

优先使用发行版官方包仓库，并遵守发行版生命周期：

# Debian/Ubuntu 类
sudo apt update
sudo apt install git

# Fedora/RHEL 类
sudo dnf install git

发行版仓库版本可能落后于上游，但通常得到发行版安全维护。只有明确需要新能力且组织能承担构建、依赖和升级责任时，才引入额外仓库或源码构建。不要从未知脚本一键安装。

安装后用 command -v git、包管理器查询命令和 git --version 组成三点证据：路径证明执行入口，包管理器证明 owner，版本输出证明运行结果。仅有最后一项，无法判断二进制来自发行版仓库、额外仓库还是手工覆盖。

源码构建边界

源码构建适合维护发行包、验证补丁或使用发行版尚未提供的能力，不应成为普通开发机默认路径。必须记录编译依赖、prefix、卸载方式、更新 owner 和安全公告来源。Git 未来重大版本的构建依赖可能变化，需持续关注 BreakingChanges。

升级、灰度与回退

升级不是运行一条 update 命令，而是把“旧入口、目标入口、配置兼容、项目行为”依次锁定。先保存版本、路径、安装渠道和配置来源，再用原渠道升级：

winget upgrade --id Git.Git -e --source winget

# Homebrew
brew upgrade git

# Debian/Ubuntu 类
sudo apt update && sudo apt install --only-upgrade git

# Fedora/RHEL 类
sudo dnf upgrade git

升级后新开终端，重新执行路径探测和后文的临时仓库实验。IDE、GUI、WSL、Git LFS、submodule、签名或自定义 hook 只要被团队使用，也必须进入灰度样本。若核心操作失败，先停止推广，再按原安装渠道恢复组织保存的上一受支持包或仓库快照；不要从随机镜像下载旧二进制。回退后同样检查路径与配置来源，避免“包降级了，PATH 仍指向新副本”。

配置改动要与二进制升级分开记录。这样失败时可以判断是新 Git 行为、安装路径切换，还是 global/system 配置变化，而不必一次回滚所有东西。

建立可解释的配置基线

先理解配置优先级

使用官方 git-config 作为事实源。常见作用域从低到高包括 system、global、local、worktree 和命令行配置；同一键后出现的更高优先级值会覆盖前者。

git config --list --show-origin --show-scope
git config --show-origin --get-all user.email
git config --local --list

排障时不能只运行 git config --list，否则看得到结果却看不到谁覆盖了谁。

最小个人配置

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global fetch.prune true
git config --global pull.ff only

pull.ff only 不是唯一正确答案。团队也可以选择 rebase 或 merge，但要把选择写入协作规范并在项目脚本、培训和排障中保持一致。本文采用它作为保守示例，因为它会在历史已经分叉时明确失败，而不是静默产生团队未约定的合并提交。

工作与个人身份隔离

同一开发机访问多个组织时，避免频繁手工改全局邮箱。使用条件配置按目录隔离：

# ~/.gitconfig
[includeIf "gitdir:~/workspace/company/"]
    path = ~/.gitconfig-company

[includeIf "gitdir:~/workspace/personal/"]
    path = ~/.gitconfig-personal

# ~/.gitconfig-company
[user]
    name = Your Name
    email = you@example.com

条件匹配依赖路径和尾部斜线语义。验证时必须进入目标仓库：

git config --show-origin --get user.email
git config --show-origin --get user.name

身份配置只决定提交元数据，不决定远端认证账号。HTTPS 凭据和 SSH key 需要在后续文章单独验证。

换行基线

仓库文本语义优先放在 .gitattributes，不要只依赖个人 core.autocrlf：

* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf
*.png binary

变更规则前先在独立分支检查影响：

git check-attr --all -- path/to/file
git diff --ignore-space-at-eol

不要把一次全仓换行归一化与业务修改混在同一个提交中。

大小写与文件模式

Windows、默认 macOS 文件系统和 Linux 的大小写语义可能不同。不要用全局关闭检查来掩盖仓库冲突。仅修改文件名大小写时，通过临时名称完成受控重命名并在 Linux CI 验证。

core.fileMode 反映文件系统是否可靠记录可执行位。Shell 脚本应由仓库明确维护执行位，而不是要求每个开发者手工 chmod 后不提交模式变化。

safe.directory 不是万能修复

Git 的可疑所有权检查用于防止在不可信目录读取仓库配置。出现 dubious ownership 时，先确认目录 owner、挂载方式和运行账号。只有仓库确实可信且共享模型经过设计时，才添加精确路径；禁止把 * 作为团队默认：

git config --global --add safe.directory /trusted/workspace/project

容器、CI 和共享目录应从 owner、UID/GID 映射和工作区生命周期解决根因。

在可删除目录创建仓库：

mkdir git-baseline-check
cd git-baseline-check
git init
printf "baseline\n" > README.md
git add README.md
git commit -m "test: verify git baseline"
git status --short --branch
git log -1 --show-signature --format=fuller
git config --list --show-origin --show-scope

预期结果：

默认分支符合团队约定。提交姓名和邮箱来自预期配置文件。工作区干净。

git log 显示的提交者时间和身份正确。没有 unexpected safe.directory、换行或 owner 警告。

接着制造一个不会影响其他仓库的作用域反例：

git config --local user.email wrong-account@example.invalid
git config --get user.email
git config --show-origin --show-scope --get-all user.email
git config --local --unset-all user.email
git config --get user.email

第二条会返回仓库级错误邮箱；第三条同时显示 global 与 local 来源，并证明 local 值拥有更高优先级。删除 local 值后，最后一条应恢复条件配置或 global 身份。这个实验解释了为什么“重新设置全局邮箱”无法修复已有仓库覆盖，也验证了回滚命令确实删除了正确作用域。

清理：

cd ..
rm -rf git-baseline-check

Windows PowerShell 使用 Remove-Item -LiteralPath .\git-baseline-check -Recurse 前，应先确认当前位置和目标绝对路径，避免误删其他目录。

仓库至少应维护：

.editorconfig
.gitattributes
.gitignore
CONTRIBUTING.md

CONTRIBUTING.md 记录最低 Git 版本、安装来源、同步策略、换行规则、身份要求和升级支持入口。可加入只读诊断脚本输出版本与配置来源，但脚本不得收集 token、代理密码、私钥路径内容或完整内部远端 URL。

IDE 中显式检查 Git executable 路径。终端验证成功而 IDE 失败时，优先比较二者调用路径、环境变量和配置 home，而不是重复生成凭证。

查配置是谁设置的

git config --show-origin --show-scope --get-all user.email
git config --show-origin --show-scope --get-all http.proxy

只修改当前仓库

git config --local user.email "you@example.com"
git config --local pull.ff only

删除错误配置

先确认作用域，再删除：

git config --global --unset-all user.email

如果键有多个值，先 --get-all，不要假设只存在一项。

升级后检查差异

git --version
git --exec-path
git config --list --show-origin --show-scope
git fsck --no-dangling

在测试仓库执行 clone、commit、fetch 和团队约定的最小操作，再逐步推广。

终端与 IDE 显示不同版本

终端支持某个参数，IDE 报未知选项或行为不同。

比较终端 command -v/where.exe、IDE Git executable 和 git --exec-path。

系统包、GUI 内置 Git、Git for Windows、Homebrew 或 WSL 版本同时存在。

选定团队支持版本，显式配置 IDE 路径，清理 PATH 中过时入口；不要在未确认依赖前直接卸载。

终端、IDE Task 和 GUI 分别输出相同版本及 exec path。

提交用了错误邮箱

平台没有关联贡献，或工作提交使用个人邮箱。

运行 git config --show-origin --get user.email，检查最近提交的 author/committer。

全局配置覆盖预期身份，includeIf 路径未匹配，或仓库已有 local 配置。

修正条件路径或当前仓库配置。未发布提交可按团队流程重写；已发布历史不要自行改写。

创建测试提交并检查 git log -1 --format=fuller。

一次提交出现全仓换行变化

业务只改一行，diff 却覆盖大量文件。

检查 .gitattributes、core.autocrlf 和文件实际 EOL。

个人换行配置与仓库规则冲突，或编辑器自动归一化。

停止提交，恢复工作区，在独立变更中确定 .gitattributes 和归一化计划。

全新 clone 后业务修改只产生预期 diff。

dubious ownership 被随手全局放开

Git 拒绝仓库，添加通配 safe.directory 后告警消失。

检查目录 owner、运行账号、容器挂载和配置来源。

共享目录或提权命令制造所有权不一致。

恢复正确 owner/UID 映射，只对白名单可信路径配置例外，删除通配设置。

日常账号访问可信仓库成功，不可信 owner 仓库仍被阻止。

安装包和更新源必须经过组织批准，并记录 Git 安装渠道经过哪条代理、更新由谁批准、失败日志保存在哪里。代理链和私有 CA 出现异常时，沿网络、代理与证书工具继续定位，不能通过关闭 TLS 校验绕过。

不要使用管理员/root 执行日常 git clone、依赖安装或项目构建，否则工作区会留下高权限文件。Git 配置中不要出现带账号密码的代理 URL、PAT、私钥内容或真实内部仓库地址。

团队基线至少包含：

支持的操作系统、安装渠道和最低安全版本。Git 可执行文件 owner 与 IDE 配置方式。system/global 配置由谁管理，仓库 local 配置允许覆盖什么。

身份、默认分支、同步策略、换行和文件模式规则。升级灰度、兼容验证、回退包和停止推广标准。安全公告、重大版本与弃用项的维护 owner。

新成员自检脚本和问题升级入口。

配置基线应尽量进入仓库文件和可审查文档，不依赖个人 dotfiles 或培训截图。

多版本问题不是“删掉旧 Git”这么简单

GUI、IDE、Shell、WSL 和自动任务可能各自绑定路径。判断标准是所有入口的版本、exec path 和配置 home 可解释；迁移前要列出消费者，升级后逐一验证。

全局配置会跨组织泄露行为

身份、代理、签名和 URL 重写都可能通过 global 配置影响不相关仓库。优先使用条件配置和仓库配置缩小作用域，并定期检查 --show-origin --show-scope。

换行治理必须与业务变更分离

一次全仓归一化会干扰 blame、review、冲突和回滚。团队应单独评审 .gitattributes，冻结其他大改动，完成全新 clone 与 CI 验证后再合并。

安全目录告警反映的是信任边界

把所有路径加入 safe.directory 等于移除保护。共享 runner、容器和网络盘应通过所有权和隔离设计解决，例外必须有精确路径、owner、期限和复查。

重大版本升级要验证行为而非只看启动

Git 默认值、构建依赖和安全策略可能变化。升级门禁至少覆盖 clone、配置解析、提交、fetch/push、签名、LFS/submodule（如使用）和 IDE 集成；失败时能回到已记录的安装包与配置快照。

Git 来自批准的安装渠道，版本与 exec path 可追踪。终端、IDE、GUI 和 WSL 没有意外调用不同版本。system/global/local/条件配置来源可解释。

工作与个人身份不会因为目录或 local 配置串用。默认分支和 pull 策略与团队规范一致。.gitattributes 管理换行和二进制规则。

safe.directory 没有通配放开，不可信 owner 仍会被阻止。日常项目命令不依赖管理员/root。升级有灰度、验证、停止标准和回退路径。

文档、诊断输出和截图不包含真实凭证、私钥或内部地址。