Git之常用命令与避坑指南分享

一、Git 基础配置

在用Git之前，有两件事最好先搞定，否则后续操作会处处碰壁。

# 设置全局用户信息（必填，否则无法提交）
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱@example.com"

# 设置默认分支名（可选）
git config --global init.defaultBranch main

# 查看配置
git config --list

这段配置看起来简单，但却是版本控制的基石。没有它，每次提交都会报错提示缺少用户信息，到时候还得回头补上，不如一开始就配好。

二、Git 常用命令速查表

日常开发中，Git命令最常用的场景无非那么几个。下面这张表基本覆盖了从初始化到协作的完整流程，关键时刻翻一翻就能解决问题。

三、GitHub / Gitee 上传避坑指南

上传代码到远程仓库，看起来简单，但新手（甚至老手）经常踩坑。下面这7个场景，几乎是每个开发者都会遇到的，提前了解能省很多时间。

坑 1：远程仓库已有内容，本地推不上去

问题：git push 被拒绝，提示 failed to push some refs

原因：远程仓库初始化时创建了 README/LICENSE 等文件，本地没有这些文件

解决：

# 方法一：先拉取合并（推荐）
git pull origin main --allow-unrelated-histories
git push origin main

# 方法二：强制推送（⚠️ 会覆盖远程）
git push -u origin main -f

方法一更安全，能保留远程已有的文件。方法二虽然简单粗暴，但会覆盖远程内容，慎用。

坑 2：push 时提示输入用户名密码

问题：每次 push 都要输入账号密码

解决：配置凭据缓存

# 缓存 15 分钟
git config --global credential.helper cache

# 永久存储（Windows）
git config --global credential.helper store

频繁输入密码确实烦人，配置了缓存后，体验会好很多。不过永久存储要谨慎，尤其是公用电脑。

坑 3：SSH 推送报错 Permission denied

问题：使用 SSH 方式推送报权限错误

解决：

# 1. 生成 SSH 密钥
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 2. 查看公钥
cat ~/.ssh/id_ed25519.pub

# 3. 将公钥添加到 GitHub/Gitee 的 SSH Keys 设置中

# 4. 测试连接
# GitHub
ssh -T git@github.com
# Gitee
ssh -T git@gitee.com

SSH 方式比 HTTPS 更安全，配置一次后就不用再输密码了。如果测试连接时提示“Permission denied”，多半是公钥没添对，或者密钥文件路径不对。

坑 4：文件过大无法推送

问题：

remote: error: File xxx is 100.00 MB; this exceeds the file size limit

解决：

# 安装 Git LFS
git lfs install

# 追踪大文件
git lfs track "*.psd"
git lfs track "*.zip"

# 然后正常 add/commit/push

Git 默认不支持大文件，超过 100MB 就会报错。Git LFS 是官方解决方案，专门用来管理大文件，推荐在项目初期就配置好。

坑 5：误提交了敏感信息

问题：密码、密钥等被提交到仓库

紧急处理：

# 1. 立即修改泄露的密码/密钥！

# 2. 从 Git 历史中移除文件
git filter-branch --force --index-filter 
  "git rm --cached --ignore-unmatch 敏感文件路径" 
  --prune-empty --tag-name-filter cat -- --all

# 3. 推送清理后的历史
git push origin main --force --all

# 4. 添加 .gitignore 防止再次提交
echo "敏感文件名" >> .gitignore

这种事一旦发生，第一件事是立即修改密码或密钥，而不是清理 Git 历史。因为历史记录一旦被公开，即使删除了，攻击者也可能已经下载了。清理历史只是事后补救，防止后续被更多人看到。

坑 6：push 时提示 detached HEAD

问题：不在任何分支上，无法 push

解决：

# 切换回主分支
git checkout main
# 或创建新分支保存当前修改
git checkout -b new-branch

这个状态通常是因为 checkout 到了某个特定的提交哈希，而不是分支名。解决方法很简单，要么切回分支，要么创建一个新分支来保存当前工作。

坑 7：GitHub 访问慢 / 连不上

解决：

# 使用 GitHub 镜像加速（临时）
git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/"

# 或修改 hosts 文件绑定 IP

# Gitee 一般无需加速

GitHub 的访问稳定性在国内确实是个问题，尤其是大文件下载或大量请求时。镜像加速是个临时方案，长远来看，可以考虑使用 Gitee 或自建 Git 服务器。

四、推荐工作流

一个标准的工作流应该是什么样的？下面这个流程适合大多数团队和个人项目，能最大程度减少冲突和混乱。

# 1. 克隆远程仓库
git clone git@github.com:用户名/仓库名.git

# 2. 创建功能分支
git checkout -b feature/my-new-feature

# 3. 开发并提交
git add .
git commit -m "feat: 添加新功能描述"

# 4. 推送分支到远程
git push -u origin feature/my-new-feature

# 5. 在 GitHub/Gitee 上创建 Pull Request / Merge Request

这个流程的核心是：永远不要在 main 分支上直接开发，始终通过功能分支来管理代码。这样既能保持主分支的整洁，也便于代码审查和回滚。

五、Git 提交规范（推荐）

提交信息写得清楚，团队协作才能顺畅。下面这个规范是社区常用的，推荐直接采用。

feat:     新功能
fix:      修复 bug
docs:     文档更新
style:    代码格式（不影响逻辑）
refactor: 重构
test:     测试相关
chore:    构建/工具变动

示例：

git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复首页加载超时问题"

格式简单，但效果显著。规范的提交信息能让你在查看历史记录时一目了然，尤其是当项目规模变大后，这种价值会愈发明显。