Git基础与环境搭建全攻略：IntelliGit项目实战指南

做IntelliGit这个项目之前，我给自己出了一道题：能不能在Git日常操作里加入一些"智能"，让提交、分支、回滚这些重复动作变得不那么机械。想法是好的，但真正动手的时候发现，想给Git做工具，首先得自己把Git吃透。于是就有了这个系列博客的第一篇：先把环境搭起来，把Git基础系统过一遍，给后面的功能开发打底。

这篇内容对两类人最有用：一是准备做自己的开发者工具、但Git还不熟的同学，二是已经有Git经验、想系统捋一遍底层逻辑的朋友。我会把Windows、macOS、Linux三套环境的搭建过程、Git的核心概念、以及我在IntelliGit项目里实际用到的完整工作流都写出来，包括那些网上教程很少提的坑。

1. IntelliGit项目背景与环境规划

1.1 这个项目到底要做什么

先说清楚IntelliGit是什么。它的定位是一个面向开发者的智能Git辅助工具，核心思路是在Git命令之上加一层"自动化判断"：比如监听文件变化后生成规范的提交信息，分析分支状态提前预警合并冲突，根据提交历史推荐合适的回滚点。听起来不算复杂，但真正落地的时候会牵扯到文件系统监控、命令解析、仓库状态分析这些东西，一步都不能跳。

之所以选择这个方向，是因为我在日常开发中最大的痛点不是不会用Git，而是重复劳动太多。每次提交要写信息、切换分支要理清状态、合并冲突要一个个排查，这些操作完全可以提取共性规则做成工具。IntelliGit就是想把这些"经验"固化下来，让我和其他开发者少踩一些重复的坑。

当然，理想很丰满，落地得一步步来。第一件事就是让本机环境跑起来，并且真正理解Git的底层工作方式。工具开发最忌讳的就是地基不稳——如果你连暂存区和工作区的关系都说不清，做出来的辅助工具大概率也只是花架子。

1.2 为什么第一件事是打牢Git基础

很多同学上手Git就是照着博客敲命令，git add .、git commit -m "update"、git push三连，能用但不明白背后发生了什么。这种状态做普通开发问题不大，但做IntelliGit这种工具类项目就不够了。

举个例子，IntelliGit要自动生成提交信息，前提是能准确判断"这次改动到底动了什么"。你得知道git diff和git diff --cached的区别，知道git status的各类状态从哪来，知道HEAD指针移动的代价是什么。否则生成的信息要么词不达意，要么遗漏关键变更。

所以这一篇我会花大篇幅讲清楚那些"看起来是基础、实际上很关键"的概念。别嫌啰嗦，后面开发具体功能的时候你会感谢今天的自己。

1.3 开发环境需求清单

动手之前，先列一份环境需求清单。这是我从之前几个项目里总结出来的习惯：不管做什么，先把目标环境明确下来，避免中途切换操作系统或工具链导致的无谓返工。

我本机是Windows 11 + Git 2.40 + Python 3.11的组合，所有命令我都在这个环境里实测过。macOS和Linux的步骤我也写了，照着做不会有问题。

2. Git环境搭建全流程实操

2.1 Windows：从下载到验证的完整步骤

Windows下安装Git最推荐的方式是直接去官网git-scm.com下载安装包。下载的时候注意选对系统位数，现在基本都是64位，直接选最新的64-bit版本就行。

安装过程有几个选项值得认真对待，不要全程一路Next：

第一个是"Select Components"，默认勾选的项基本都保留，但建议额外把"Git Bash Here"和"Git GUI Here"这两个右键菜单项勾上。这俩在后续操作中特别方便，在文件夹里右键就能打开终端，省去一路cd的麻烦。

第二个是"Choosing the default editor"，默认是Vim。Vim新手在这里会被卡到怀疑人生。我建议在安装前装好VS Code，然后在这里直接选"Use Visual Studio Code as Git's default editor"。后面所有需要编辑提交信息的场景，Git都会自动打开VS Code，体验好很多。

第三个是"Adjusting the name of the initial branch in new repositories"，这里我选了"Override"并填了main。现在主流托管平台都把默认分支名改成了main，本地仓库也用main可以避免后面推送时改来改去。

第四个是"Configuring the line ending conversions"，我选的是"Checkout as-is, commit as-is"。这个选项的意思是检出和提交都不做换行符转换，Windows下不会有CRLF/LF互相折腾的问题。具体的坑我在后面第5章会详细讲。

安装完成后验证一下，在开始菜单搜索"Git Bash"，打开后输入：

bash复制git --version

能看到git version 2.40.0之类的输出就说明装好了。如果提示"无法识别"，大概率是PATH没配置对，后面第5章有排查方案。

2.2 macOS与Linux：一行命令搞定

macOS用户最省事的安装方式是用Homebrew：

bash复制brew install git

如果你的Mac还没装Homebrew，建议先去brew.sh把命令复制下来装好，后续开发基本离不开它。装完之后同样验证git --version。

Linux这边，Debian/Ubuntu系用apt：

bash复制sudo apt update
sudo apt install git -y

CentOS/RHEL系用yum或dnf：

bash复制sudo yum install git -y

这里有个细节可以留意：Linux发行版自带的Git版本普遍偏旧。比如Ubuntu 20.04默认的Git可能是2.25，虽然也能用，但和Windows/macOS上的2.40在个别命令行为上会有差异。如果做跨平台工具开发，建议所有环境尽量保持大版本一致。

2.3 为什么Windows上一定要用Git Bash

Windows下装了Git之后，桌面会有三个入口：Git Bash、Git CMD、Git GUI。很多新手只认识GUI，点开之后发现就是个图形界面，提交操作也能做，但总觉得哪里不对劲。

我的建议是：老老实实从Git Bash开始学。它本质是一个模拟Linux终端环境的程序，里面用的是Linux风格的命令，比如ls、pwd、touch这些。这和macOS、Linux上的终端体验是一致的，你在这三个系统之间切换，命令不用改。

更重要的是，很多Git的高级操作只有命令行能做，GUI反而找不着入口。比如git reflog查看操作历史、git rebase -i交互式变基，这些在图形界面里操作非常别扭。IntelliGit以后要做成命令行工具，现在不把命令行练熟，后面连测试都写不了。

在Git Bash里输入pwd看看当前目录，输入ls -a看看隐藏文件。多敲两下，慢慢就有感觉了。

2.4 全局配置：三行命令让Git认识你

Git装好之后不能直接用，得先告诉它"你是谁"。这一步会写入提交记录里，成为你每次提交的身份标识。

打开Git Bash，依次执行：

bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

名字建议用英文或拼音，仓库公开的话会直接显示在提交记录里。邮箱最好用注册代码托管平台时使用的邮箱，这样你的提交能正确关联到自己的账号上。

除了身份信息，还有几个配置我强烈建议顺手改掉：

bash复制git config --global init.defaultBranch main
git config --global core.autocrlf false
git config --global core.quotepath false
git config --global pull.rebase false

这些配置的作用分别是：新仓库默认分支名用main，不做换行符自动转换，让中文文件名正常显示，pull时使用默认的merge策略而不是rebase。前两条我前面安装时已经选过，这里作为命令行配置再确认一遍，后面两个是实战里最容易踩坑的点。

想知道配置是否生效，可以执行：

bash复制git config --global --list

这个命令会列出当前用户的所有全局配置。配置文件存放在用户主目录下的.gitconfig文件里，想看原始内容可以直接编辑这个文件，不过用命令改更不容易出错。

2.5 SSH密钥：免密推送的关键一步

每次git push都输账号密码确实能忍，但绝不推荐。正确做法是配置SSH密钥，一次配置，终身免密。

生成密钥：

bash复制ssh-keygen -t ed25519 -C "你的邮箱"

这里-t ed25519是指定加密算法，相比传统的RSA，ed25519更安全、密钥更短、生成速度更快。现在新版本Git都支持。一路回车到结束，密钥会生成在~/.ssh/id_ed25519和~/.ssh/id_ed25519.pub两个文件里，前者是私钥，打死都不能给别人，后者是公钥，需要放到代码托管平台上。

查看公钥内容：

bash复制cat ~/.ssh/id_ed25519.pub

复制全部输出，然后登录你的代码托管平台（GitHub或Gitee都可以），在设置里的"SSH Keys"或"Deploy Keys"页面粘贴保存。

验证是否成功：

bash复制ssh -T git@github.com

如果是GitHub，成功会输出类似Hi 你的用户名! You've successfully authenticated的提示。这一步通了之后，后续所有远程操作都不需要再输密码。

3. Git基础概念与常用命令速通

3.1 三个区域到底怎么理解

Git最核心的概念就是三个区域：工作区（Working Directory）、暂存区（Staging Area）、本地仓库（Repository）。

我平时给朋友解释喜欢用做饭的类比。工作区就是你摆在案板上的所有食材，随便切、随便改；暂存区是"待下锅的碗"，你把想下锅的食材先挑到这个碗里；本地仓库则是已经做好的菜，放进冰箱保存。

对应到命令上就是：你在工作区里修改文件，git add把修改放进暂存区，git commit把暂存区的内容固化成一次提交存进本地仓库。理解这个流程，你就知道为什么每次提交前都要先git add了——不是所有改动你都一定要提交，先用暂存区筛选一遍，再决定哪些进入版本历史。

git status命令就是用来查看这三个区域当前状态的。它会把工作区、暂存区各自有哪些变动清清楚楚列出来。我几乎每个项目操作前都会跑一次git status，确认自己当前站在哪个位置，避免在错误的状态下执行错误的操作。

3.2 本地提交五连：init、status、add、commit、log

本地操作最常用的命令就五个，先记住它们：

bash复制git init        # 当前目录初始化为Git仓库
git status      # 查看状态
git add .       # 把所有改动加入暂存区
git commit -m "提交信息"  # 提交
git log --oneline        # 查看提交历史

git init执行后，目录里会出现一个隐藏的.git文件夹，这个文件夹就是仓库的"大脑"，所有历史记录、指针、配置都在里面。日常操作千万不要手动改动它，否则仓库你可能就抢救不回来了。

git add .是一次性把全部改动放入暂存区，适合小改动。如果只想提交部分文件，用git add 文件名指定路径。我开发IntelliGit的习惯是分模块提交，这次改了核心逻辑就只add相关文件，文档改动单独提交，这样历史记录干净，后面用git log回溯时思路清晰。

看到这里你可能想问，git add和git commit为什么不合并成一个命令？早期我也这么觉得，直到我负责的项目里出现过一次误提交——把含数据库密码的配置文件顺手提交上去了，那次之后我才理解了暂存区的价值：它是最后一道筛选关卡，防的就是"手滑"。

git log --oneline会以一行一条的方式展示提交历史，每条前面是七位哈希值，后面是提交信息。这个哈希值是Git根据内容计算出来的，内容一变，哈希就变，这就是Git保证历史不可篡改的基础。

3.3 分支管理与合并：Git最值钱的武器

分支是Git相比传统版本控制工具（比如SVN）最具革命性的设计。你可以把它理解为平行宇宙：在main主干上干活的同时，新建一个dev分支去尝试新功能，互不干扰，开发完成后把dev合并回main。

常用命令：

bash复制git branch dev          # 创建分支dev
git checkout dev        # 切换到dev分支
git switch dev          # 切换分支的现代写法
git branch              # 查看所有分支，当前分支前有*
git merge dev           # 把dev合并到当前分支
git branch -d dev       # 删除dev分支

这里建议直接用git switch，语义更清晰，也是Git 2.23之后推荐的方式。git checkout身兼多职——既能切分支又能恢复文件，新手很容易搞混。

合并冲突是绕不开的坎。当两个分支改了同一个文件的同一段代码，Git没法替你决定留哪边，就会提示冲突。表现形式是文件中出现这样的标记：

code复制<<<<<<< HEAD
当前分支的内容
=======
被合并分支的内容
>>>>>>> dev

手工把不要的内容删掉，保留想要的，再git add、git commit，冲突就解决了。头几次遇到冲突确实慌，但操作多了会发现，冲突其实就是Git在帮你确认"你到底想留哪版"，只要耐心读懂这几个标记，处理起来不难。

3.4 远程协作：push、pull、fetch怎么分工

把本地仓库和远程托管平台连接起来，用的命令是：

bash复制git remote add origin 仓库地址
git push -u origin main

origin是远程仓库的默认别名，你可以理解成"给那个远程仓库起了个外号叫origin"。第一次推送用-u参数，会把本地main分支和远程main分支建立关联，之后的推送直接写git push就行。

git pull和git fetch容易混淆。git fetch只把远程的最新状态拉下来，不会动你本地的工作区；git pull则是拉下来之后自动合并。建议初学者先用fetch加merge两步走，能看清楚整个过程发生了什么，用熟了再换pull。

git clone 仓库地址可以把远程仓库完整复制到本地，它会自动帮你设置好origin，不需要手动remote add。从零参与一个开源项目，第一件事通常就是git clone。

3.5 .gitignore：该忽略的别提交

这个文件几乎每个项目都需要，它的作用是告诉Git忽略哪些文件和目录。比如Python项目里的__pycache__、虚拟环境venv、IDE配置.idea之类，这些根本不该进版本库。

一个简单的例子：

code复制__pycache__/
*.pyc
venv/
.idea/
.vscode/
*.log
.env

*.pyc匹配所有.pyc后缀文件，目录名后面加/表示忽略整个目录，.env则是因为里面往往有密钥，绝对不建议上传。

我在IntelliGit项目里踩过一次坑：忘了配.gitignore，把本地测试生成的临时文件全提交上去了，仓库瞬间多了几十个无意义的文件，后面清理花了不少时间。所以强烈建议，git init之后第一件事就是创建.gitignore文件，把该忽略的先列好。

4. 用IntelliGit项目完整走一遍Git流程

4.1 初始化仓库并建立基本结构

理论说了一堆，不如完整跑一遍。我现在模拟IntelliGit项目的起步阶段，把每一步命令和输出都摆出来。

项目会有一个主模块叫git_intelli，先创建项目目录并初始化：

bash复制mkdir intelligit
cd intelligit
git init

然后创建.gitignore和README.md，用VS Code打开项目开始写第一行代码：

code复制intelligit/
├── .gitignore
├── README.md
└── git_intelli/
    └── __init__.py

__init__.py是Python包标识文件，内容可以先留空。然后在git_intelli目录里新建analyzer.py，先写一个非常简单的类，用来分析暂存区的改动规模：

python复制import subprocess


class ChangeAnalyzer:
    """分析Git暂存区的变更情况。"""

    def __init__(self, repo_path="."):
        self.repo_path = repo_path

    def staged_file_count(self) -> int:
        """返回暂存区内改动的文件数量。"""
        result = subprocess.run(
            ["git", "diff", "--cached", "--name-only"],
            cwd=self.repo_path,
            capture_output=True,
            text=True,
        )
        return len(result.stdout.strip().splitlines())

这段代码的功能是调用git diff --cached --name-only拿到暂存区的文件名列表，然后数个数。注意--cached这个参数，它指定的是暂存区和HEAD的差异，也就是"已经add但还没commit的内容"。

4.2 从首次提交到分支开发

现在把这两个文件加入暂存区并提交：

bash复制git add .
git commit -m "feat: init project structure and change analyzer"

feat:前缀是我在IntelliGit项目里定的提交规范，后面会细说。

现在创建一个功能分支dev，开始开发文件变更检测功能：

bash复制git switch -c dev

-c参数表示创建并切换，一个命令顶git branch dev加git switch dev。在dev分支上给analyzer.py加一个方法，统计工作区里未暂存的改动行数：

python复制def unstaged_changes(self) -> int:
    """返回工作区中未暂存的改动数量。"""
    result = subprocess.run(
        ["git", "diff", "--name-only"],
        cwd=self.repo_path,
        capture_output=True,
        text=True,
    )
    return len(result.stdout.strip().splitlines())

改完之后回到main分支合并dev：

bash复制git switch main
git merge dev -m "merge: import dev branch into main"

整个过程如果有冲突，Git会在合并时停下来提示，这时就是前面第3章说的冲突处理环节了。

4.3 IntelliGit项目的Git工作规范

做工具类项目，提交信息的规范程度直接影响后续排查效率。IntelliGit内部定了一套简单实用的规则，分享出来供参考。

分支策略用了最经典的main + dev + feature三层模型。main永远保持可发布状态，dev是日常开发集散地，大块的功能再单独开feature分支，开发完合回dev。这个模型不复杂，对单人项目和两三个人的小团队都够用。

5. 常见问题与排查技巧实录

5.1 "git不是内部或外部命令"怎么办

这个报错几乎每个Windows新手都会遇到，尤其在用PowerShell或CMD执行git命令时。原因很简单：Git安装时没有把可执行文件路径加进系统PATH环境变量。

解决办法有两个。第一个是重装Git，在安装向导的"Adjusting your PATH environment"一步，务必选"Git from the command line and also from 3rd-party software"。第二个是手动添加：右键"此电脑"→属性→高级系统设置→环境变量，在系统变量里找到Path，追加C:\Program Files\Git\bin和C:\Program Files\Git\cmd，然后重新开终端。

如果是用Git Bash却报"找不到git"，基本不可能，因为Git Bash自带了git命令路径。

5.2 中文文件名乱码与换行符的坑

如果git status里中文文件名显示成\346\265\213\350\257\225这种八进制转义序列，不用慌，这是Git为了兼容旧系统默认的处理方式。执行我前面第2章里的那句配置就能解决：

bash复制git config --global core.quotepath false

配置完之后，Git会直接显示原始的中文文件名。

换行符是另一个经典问题。Windows用CRLF（回车+换行），Linux和macOS用LF（换行）。如果你的仓库在Windows下被自动转成了CRLF，推送到远程后别人在mac上打开就会看到一堆奇怪的回车符。我第2章里的建议是全局设置core.autocrlf false，关闭自动转换，然后在项目根目录放一个.gitattributes文件，把文本文件的换行规则固定下来。

5.3 远程仓库连不上：从哪查起

git push报连接超时或认证失败，先别急着怀疑人生。按顺序排查：第一，确认网络能正常访问托管平台网站，比如能打开GitHub首页；第二，确认SSH密钥加对了平台且没有过期；第三，用ssh -T git@github.com测试连接，看返回的具体提示。

如果SSH方式一直有问题，可以临时改用HTTPS方式。重新添加远程地址：

bash复制git remote set-url origin https://github.com/用户名/仓库名.git

HTTPS和SSH是Git支持的两种传输协议，HTTPS不需要配密钥，缺点是每次推送要输账号密码（也可以让系统记住凭据）。我个人的建议是两种都学会，哪个环境用哪个方便，没必要死磕某一种。

5.4 误操作恢复：reflog和reset保命

万一git reset --hard回滚过头，或者觉得某次提交弄丢了，别慌。Git有一个隐藏的"操作日志"，记录了你每一次HEAD变化：

bash复制git reflog

reflog会显示一串操作记录，每条前面有个哈希值。即使你reset掉了某个提交，只要reflog里还有记录，就能用git reset --hard 那串哈希把它找回来。

这个命令是我压箱底的核心技能，在IntelliGit里我计划做成一个内置功能——让用户通过一个命令就能安全回滚到任意历史状态。每次觉得"完了完了，代码丢了"的时候，先跑一下git reflog，大概率能救回来。

5.5 我的排查思路：多读报错原文

最后分享一个习惯：遇到Git报错，先把报错原文完整读一遍。Git的报错信息设计得挺友好，80%的情况它已经告诉你问题出在哪了，比如fatal: not a git repository说明你不在仓库目录里，nothing to commit, working tree clean说明没有未提交的改动。

不要把报错随便复制去搜索引擎，而是先尝试理解。这个习惯后面写IntelliGit的时候帮了大忙，因为我需要精准解析Git错误码并给用户转成人话提示。读多了你会发现，Git的错误体系是有规律的，看懂一条就能举一反三。

这篇拖了挺久才发出来。在整理环境搭建和Git基础的过程中，我最大的体会就是"基础不牢，地动山摇"这句话在工具项目里尤其成立。以前自己搭环境都是能跑就行，这次认认真真把每一个配置项都搞清楚，后面写IntelliGit核心功能时明显感觉踏实很多。

下一篇准备写IntelliGit的第一个核心能力：自动生成提交信息。到时候会带着大家从零实现一个基于规则引擎的中文提交信息生成器，继续在这个项目上往下深挖。