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命令的使用场景相对集中。下表涵盖了从仓库初始化到团队协作的完整流程，遇到问题时查阅即可快速解决。

场景	命令
初始化仓库	git init
克隆远程仓库	git clone
查看状态	git status
添加文件到暂存区	git add / git add .
提交代码	git commit -m "提交信息"
推送到远程	git push origin
拉取远程更新	git pull origin
查看提交日志	git log --oneline
创建分支	git branch
切换分支	git checkout / git switch
合并分支	git merge
暂存工作区	git stash
恢复暂存	git stash pop

三、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 操作都需要输入账号密码。

解决方案：配置凭据缓存。

# 缓存 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：推送时提示 detached HEAD

问题描述：当前不在任何分支上，无法执行推送操作。

解决方案：

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

此状态通常是因为检出了某个特定的提交哈希，而非分支名称。解决方法简单，要么切回已有分支，要么创建新分支保存当前工作进度。

常见问题 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: 修复首页加载超时问题"

格式简洁，但效果显著。规范的提交信息在查看历史记录时一目了然，随着项目规模增长，其价值会愈发明显。