GitHub 代码提交完整指南

GitHub 代码提交完整指南

一份详细的 GitHub 代码提交指南，包含初始设置、日常流程、分支管理、常见问题解决方案和最佳实践。适合作为博客笔记收藏使用。

📑 目录

1. 初始设置
2. 日常提交流程
3. 分支管理
4. 常见问题及解决方案
5. 最佳实践
6. 常用命令速查

🚀 初始设置

1. 安装 Git

Windows:

• 下载地址：https://git-scm.com/download/win
• 安装时选择 “Git Bash Here”

验证安装:

git--version

2. 配置 Git 用户信息

# 设置全局用户名和邮箱gitconfig --global user.name"您的姓名"gitconfig --global user.email"your.email@example.com"# 查看配置gitconfig --global --list

3. 配置 SSH 密钥（推荐）

生成 SSH 密钥:

# 生成密钥对ssh-keygen -t ed25519 -C"your.email@example.com"# 按提示操作，默认保存在 ~/.ssh/id_ed25519

添加 SSH 密钥到 GitHub:

1. 复制公钥内容：

cat~/.ssh/id_ed25519.pub

2. 登录 GitHub → Settings → SSH and GPG keys → New SSH key
3. 粘贴公钥并保存

测试 SSH 连接:

ssh-T git@github.com

4. 创建 GitHub 仓库

1. 登录 GitHub
2. 点击右上角 “+” → New repository
3. 填写仓库名称、描述
4. 选择 Public/Private
5. 不要勾选“Initialize this repository with a README”（如果本地已有代码）
6. 点击 Create repository

📝 日常提交流程

标准提交流程（三步走）

# 1. 添加文件到暂存区gitadd.# 2. 提交更改gitcommit -m"提交信息描述"# 3. 推送到远程仓库gitpush origin main

详细步骤说明

步骤 1：检查改动状态

# 查看工作区状态gitstatus# 查看具体改动内容gitdiff# 查看已暂存的文件gitdiff--staged

步骤 2：添加文件到暂存区

# 添加所有改动（推荐）gitadd.# 添加特定文件gitaddREADME.mdgitaddsrc/main.py# 添加整个目录gitaddsrc/# 交互式添加（可以选择性添加）gitadd-p# 添加所有已跟踪文件的修改（不包括新文件）gitadd-u

步骤 3：提交更改

# 简单提交gitcommit -m"修复bug"# 多行提交信息gitcommit -m"添加新功能 - 实现用户登录功能 - 添加数据验证 - 优化界面响应速度"# 打开编辑器编写详细提交信息gitcommit

步骤 4：推送到远程仓库

# 推送到主分支gitpush origin main# 推送到指定分支gitpush origin feature-branch# 首次推送并设置上游分支gitpush -u origin main

🌿 分支管理

创建和切换分支

# 创建新分支gitbranch feature-branch# 创建并切换到新分支gitcheckout -b feature-branch# 或使用新语法gitswitch -c feature-branch# 切换到已有分支gitcheckout maingitswitch main# 查看所有分支gitbranch -a# 删除本地分支gitbranch -d feature-branch# 强制删除分支gitbranch -D feature-branch

推送分支到远程

# 推送新分支到远程gitpush -u origin feature-branch# 推送所有分支gitpush --all origin# 删除远程分支gitpush origin --delete feature-branch

合并分支

# 切换到主分支gitcheckout main# 合并功能分支gitmerge feature-branch# 使用 rebase（保持线性历史）gitrebase feature-branch

❗ 常见问题及解决方案

问题 1：推送被拒绝（non-fast-forward）

错误信息:

! [rejected] main -> main (non-fast-forward) error: failed to push some refs

原因:远程仓库有本地没有的新提交

解决方案:

方案 A：先拉取再推送（推荐）

# 拉取远程最新代码gitpull origin main# 解决可能的冲突后，再次推送gitpush origin main

方案 B：强制推送（谨慎使用）

# 强制推送（会覆盖远程分支）gitpush origin main --force# 更安全的强制推送gitpush origin main --force-with-lease

问题 2：合并冲突

错误信息:

Auto-merging README.md CONFLICT (content): Merge conflict in README.md

解决方案:

# 1. 查看冲突文件gitstatus# 2. 打开冲突文件，找到冲突标记# <<<<<<< HEAD# 本地代码# =======# 远程代码# >>>>>>> branch-name# 3. 手动解决冲突，删除冲突标记，保留需要的代码# 4. 标记冲突已解决gitaddREADME.md# 5. 完成合并gitcommit -m"解决合并冲突"

问题 3：提交了错误的文件

解决方案:

撤销最后一次提交（保留文件修改）:

gitreset --soft HEAD~1

撤销最后一次提交（不保留文件修改）:

gitreset --hard HEAD~1

从暂存区移除文件（保留工作区修改）:

gitreset HEAD<文件名>

丢弃工作区的修改:

gitcheckout --<文件名>

问题 4：修改最后一次提交信息

# 修改提交信息gitcommit --amend -m"新的提交信息"# 如果已经推送，需要强制推送gitpush origin main --force

问题 5：忘记添加文件到提交

# 添加遗漏的文件gitaddforgotten-file.py# 追加到上一次提交gitcommit --amend --no-edit

问题 6：SSH 连接失败

错误信息:

Permission denied (publickey)

解决方案:

# 1. 检查 SSH 密钥是否存在ls-al ~/.ssh# 2. 启动 SSH agenteval"$(ssh-agent -s)"# 3. 添加 SSH 密钥ssh-add ~/.ssh/id_ed25519# 4. 测试连接ssh-T git@github.com# 5. 如果还是失败，检查 GitHub 上是否添加了公钥cat~/.ssh/id_ed25519.pub

问题 7：认证失败（HTTPS）

错误信息:

remote: Support for password authentication was removed

解决方案:

使用 Personal Access Token:

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token
3. 选择权限（至少勾选repo）
4. 复制 token
5. 推送时使用 token 作为密码

或切换到 SSH:

# 查看当前远程地址gitremote -v# 切换到 SSHgitremote set-url origin git@github.com:username/repo.git

问题 8：大文件推送失败

错误信息:

remote: error: File is 120.00 MB; this exceeds GitHub's file size limit

解决方案:

使用 Git LFS（大文件存储）:

# 1. 安装 Git LFS# Windows: 下载 https://git-lfs.github.com/# 2. 初始化 Git LFSgitlfsinstall# 3. 跟踪大文件类型gitlfs track"*.zip"gitlfs track"*.pt"# PyTorch 模型文件gitlfs track"*.h5"# Keras 模型文件# 4. 提交 .gitattributesgitadd.gitattributesgitcommit -m"添加 Git LFS 配置"# 5. 正常添加和提交大文件gitaddlarge-file.zipgitcommit -m"添加大文件"gitpush origin main

问题 9：撤销已推送的提交

方案 A：创建新提交撤销（推荐）

# 撤销指定提交（创建新提交）gitrevert<commit-hash># 推送撤销提交gitpush origin main

方案 B：重置并强制推送（危险）

# 回退到指定提交gitreset --hard<commit-hash># 强制推送（会覆盖远程历史）gitpush origin main --force

问题 10：本地分支与远程分支不同步

# 查看本地和远程分支差异gitlog main..origin/main --oneline# 拉取远程最新代码gitfetch origingitpull origin main# 或使用 rebase 保持线性历史gitpull --rebase origin main

✨ 最佳实践

1. 提交信息规范

使用约定式提交格式：

# 格式：<type>(<scope>): <subject># 类型（type）：# feat: 新功能# fix: 修复bug# docs: 文档更新# style: 代码格式调整（不影响代码运行）# refactor: 代码重构# perf: 性能优化# test: 测试相关# chore: 构建/工具相关# ci: CI/CD 相关# 示例：gitcommit -m"feat(auth): 添加用户登录功能"gitcommit -m"fix(detection): 修复姿态检测算法bug"gitcommit -m"docs(readme): 更新安装说明"

2. 提交前检查清单

• 代码已测试，可以正常运行
• 没有包含临时文件、日志文件
• 提交信息清晰明确
• 已添加.gitignore排除不需要的文件
• 没有包含敏感信息（密码、API密钥等）

3. 工作流程建议

# 1. 开始工作前，先拉取最新代码gitpull origin main# 2. 创建功能分支gitcheckout -b feature/new-feature# 3. 开发并提交gitadd.gitcommit -m"feat: 实现新功能"# 4. 推送到远程gitpush -u origin feature/new-feature# 5. 在 GitHub 创建 Pull Request# 6. 合并后删除功能分支gitcheckout maingitpull origin maingitbranch -d feature/new-feature

4. .gitignore 配置示例

# Python __pycache__/ *.py[cod] *$py.class *.so .Python *.egg-info/ dist/ build/ venv/ env/ ENV/ # IDE .vscode/ .idea/ *.swp *.swo # 系统文件 .DS_Store Thumbs.db # 日志和临时文件 *.log *.tmp *.temp # 环境变量 .env .env.local # 模型文件（如果很大，使用 Git LFS） # *.pt # *.h5 # *.pkl

📚 常用命令速查

基础命令

# 查看状态gitstatus# 查看改动gitdiffgitdiff--staged# 添加文件gitadd.gitadd<文件># 提交gitcommit -m"提交信息"# 推送gitpush origin main# 拉取gitpull origin main

分支操作

# 查看分支gitbranch -a# 创建分支gitcheckout -b<分支名># 切换分支gitcheckout<分支名># 合并分支gitmerge<分支名># 删除分支gitbranch -d<分支名>

历史查看

# 查看提交历史gitloggitlog --onelinegitlog --graph --oneline --all# 查看特定文件的提交历史gitlog<文件路径># 查看提交详情gitshow<commit-hash>

撤销操作

# 撤销工作区修改gitcheckout --<文件># 撤销暂存区gitreset HEAD<文件># 撤销最后一次提交（保留修改）gitreset --soft HEAD~1# 撤销最后一次提交（不保留修改）gitreset --hard HEAD~1

远程操作

# 查看远程仓库gitremote -v# 添加远程仓库gitremoteaddorigin<url># 修改远程地址gitremote set-url origin<new-url># 获取远程更新（不合并）gitfetch origin# 拉取并合并gitpull origin main

📋 快速参考表

💡 总结

掌握以下核心流程即可：

1. 检查改动→git status
2. 添加文件→git add .
3. 提交更改→git commit -m "提交信息"
4. 推送到远程→git push origin main

遇到问题时：

• 先查看错误信息
• 使用git status检查当前状态
• 参考本文的常见问题解决方案
• 谨慎使用--force强制推送

提示:建议将本文收藏，遇到问题时快速查阅。Git 操作需要多练习，熟能生巧！