简介面向需要将本地代码托管到 GitHub 的开发者这份资料以详尽的操作文档形式系统讲解使用 Git 上传代码的全流程。内容涵盖 GitHub 账号注册与仓库创建、msysgit 客户端安装、SSH Key 生成与远端配置以及 add、commit、push 等核心命令的实际用法同时针对 .gitignore 规则编写和 tag 标签管理给出具体示例可帮助初学者避开常见配置陷阱快速建立规范的代码提交习惯。资源包内仅 1 个 docx 文档大小 52KB内容组织紧凑、便于检索查阅适合在实操时对照步骤执行。目前已有 1061 人学习浏览过该资料实用性得到一定验证。通过这份文档读者可以完整掌握从本地仓库初始化到远程推送的关键操作并理解如何利用标签标记版本节点、用忽略文件保持仓库整洁。1. 把代码推到 GitHub从“本地改了”到“远程可看”到底经历了什么很多人第一次接触 git 上传代码到 github是把它当成一个“上传工具”来理解的选中文件、点个按钮、完事。等你真正敲完一遍git add、git commit、git push才会发现这套流程其实是一个三层结构本地仓库负责记录每一次改动远程仓库负责存放和共享SSH key 负责让 GitHub 认你不是来偷代码的。这篇就按这条线拆开讲从注册账号、创建仓库、安装客户端到配置 SSH key、第一次 push再到.gitignore和 tag每一步我都给出原理、具体命令、参数为什么要这么写以及我实际踩过的坑。适合第一次接触 Git 的开发者如果你已经在用但一直是靠图形界面点按钮、没搞懂命令行里到底发生了什么也值得花十分钟过一遍。2. 创建仓库与安装 msysgit第一台机器上的三个选择2.1 注册账号与仓库可见性现在免费用户也能建私有仓库了注册 GitHub 账号是第一步这没什么好说的邮箱验证完就能登录。登录之后点右上角的加号选择 New repository就进入了创建仓库的页面。需要填的东西不多仓库名、描述、可见性以及要不要顺手初始化一个 README。这里有个和早期教程不一样的地方。原文里写的是“免费用户只能建公共仓库”那是 GitHub 很早以前的规定。现在免费账号也可以创建 Private 仓库只是私有仓库在免费版上有协作人数限制。对第一次练手的人来说选 Public 还是 Private 都不影响后续流程区别只是别人能不能在 GitHub 上搜到你的代码。我自己的习惯是练手项目一律 Private等真觉得能见人了再改 Public反正仓库的可见性随时可以切换。创建页面底部还有几个初始化选项README、.gitignore 模板、开源协议。我的建议是第一次先全都不要勾让仓库保持完全空白。原因很简单等你学会git add、git commit、git push之后自己手动创建 README 再推上去比让 GitHub 帮你初始化更能理解“本地仓库”和“远程仓库”是怎么连起来的。勾了初始化选项GitHub 会自动生成第一次提交本地仓库第一次 push 反而会碰见远程领先本地的问题对新手不友好。选项建议说明Repository name必填会出现在远程 URL 里尽量用项目名不要带空格Description选填仓库描述不影响技术流程Public / Private按需免费账号两者都能选练手建议 PrivateInitialize with README先不勾留空仓库等你自己 push 第一个文件上去Add .gitignore先不选后面手动写能理解它到底在干什么2.2 安装 msysgit 与 TortoiseGit命令行和图形界面各管什么原文提到的客户端叫 msysgit它就是后来 Git for Windows 的早期形态。现在去 git-scm.com 下载安装包里带的就是同一套东西只是名字变成了 Git for Windows。安装过程一路默认就行组件不用改唯一的建议是安装页让你选“默认编辑器”的时候如果你不熟悉 vim可以顺手换成 VS Code后面 commit 信息写错要改时就知道省多少事。装完之后在文件夹里右键会多出几个菜单项一个叫 Git Init Here在新版本里显示为 Open in Terminal 或者 Git Bash Here 的变体一个叫 Git Bash Here。Git Init Here 是在当前目录初始化仓库右键点一下目录里会出现一个.git文件夹这就代表本地仓库创建成功了Git Bash Here 是打开 git 的命令行环境。TortoiseGit 是很多人装完 msysgit 之后会跟着装的东西它提供图形界面装好之后右键菜单里会多出 Git Commit、Git Pull、Git Push 之类的一堆选项。但我要说一句不那么讨喜的话我一般建议先别急着装 TortoiseGit至少等你能不查资料敲出git add、git commit、git push这三个命令之后再说。原因很实际——你以后遇到报错去搜解决方案网上 99% 的回答都是命令行语境的粘贴回来的也是命令行。图形界面能帮你点按钮但帮不了你读报错。2.3 第一次 git init.git 文件夹里到底装了什么用命令行的方式执行初始化其实就是这么一句# 创建一个空目录并进入 mkdir my-project cd my-project # 初始化本地仓库 git init第一行命令创建一个叫 my-project 的目录第二行进入它第三行在当前目录初始化 git 仓库。执行完之后用ls -a查看能看到一个.git文件夹。这个.git文件夹就是本地仓库的核心git 的所有本地版本记录都存在里面objects目录存的是每次提交的内容快照refs目录存的是分支和 tag 指向的位置config文件记录的是这个仓库的配置包括后面要加的远程地址HEAD文件指示当前处在哪个分支。这个目录平时不用管它但也请你记住不要手动去改里面的文件更不要为了“清理空间”把它删掉——删掉.git这个目录就变回一个普通文件夹所有提交历史全部归零没有后悔药可吃。顺带一提如果你在执行git init之前就已经在目录里放了一堆代码文件初始化之后这些文件依然在只是还没有被 git 跟踪。git 只管理被add进暂存区、被commit进历史记录的文件“放在这个目录里”和“被 git 管理”是两回事这一点后面第四节会细说。3. 配置 SSH key 与本地身份为什么 push 不需要输密码3.1 SSH key 是干什么的公钥私钥的免密原理先把一个关键问题讲清楚为什么不用账号密码直接上传非要折腾 SSH key如果你用过 HTTPS 方式推送代码就知道体验有多差——每次git push都要输入 GitHub 账号密码而 GitHub 出于安全考虑2019 年之后不再接受账号密码直接认证得先去网页生成一个 Personal Access Token再把这个一大串的 token 当密码粘进去。Token 有有效期过期了又得重新生成。对频繁推送代码的人来说这条路很烦。SSH key 走的是另一套逻辑本地生成一对密钥一个公钥、一个私钥。私钥留在你电脑的~/.ssh目录里永远不要给任何人公钥是可以公开的把它粘贴到 GitHub 后台。推送代码时git 用本地私钥做签名GitHub 收到请求后用你留在后台的公钥去验证签名验证通过就放行。整个过程不输入任何密码这就是大家常说的“git 免密”。这套机制在日常使用中基本感觉不到存在但你要明白它的边界私钥泄露等于把仓库钥匙交出去所以不要把自己的id_rsa文件发给别人也不要把id_rsa.pub的内容粘贴到不明来历的网站。3.2 生成密钥ssh-keygen 的参数与文件位置打开 Git Bash执行下面这条命令生成密钥# 生成 rsa 密钥-C 后跟你的邮箱用于在 GitHub 后台识别这把 key ssh-keygen -t rsa -C your_emailyouremail.com命令执行后会出现三次询问。第一次问私钥保存路径括号里是默认路径~/.ssh/id_rsa直接回车用默认即可第二次和第三次是设置 passphrase访问私钥时的口令如果希望更安全可以输入不想每次推送都输一遍的话就直接回车留空。参数说明-t指定密钥算法。原文写的是rsa这也是最经典、兼容性最好的选择GitHub 完全支持。如果你是新电脑新账号也可以用更新的ed25519算法ssh-keygen -t ed25519 -C your_emailyouremail.com生成的私钥文件是~/.ssh/id_ed25519密钥更短、安全性更高。-C是注释字段一般填自己的邮箱将来在多台电脑上管理多把 key 时这个注释能帮你快速分清哪台机器对应哪把。生成完之后~/.ssh目录下会出现两个文件id_rsa私钥权限默认只有你自己可读写和id_rsa.pub公钥。我们接下来要复制的是带.pub后缀的那一个。3.3 把公钥交给 GitHub后台粘贴与命令行验证在 Git Bash 里执行# 查看公钥内容整段复制 cat ~/.ssh/id_rsa.pub # 验证 SSH 连接是否成功 ssh -T gitgithub.com第一条命令把公钥内容打印到终端从ssh-rsa开头一直到最后面的邮箱注释全部选中复制。然后回到 GitHub 网页进入 Settings头像下拉菜单里左侧找到 SSH and GPG keys点 New SSH key。Title 随便填比如 “my laptop”Key 框里粘贴刚才复制的公钥内容保存。第二条命令是验证连通性。ssh -T gitgithub.com的意思是用 SSH 协议连接 GitHub 服务器-T表示不分配终端因为我们只是验证身份不是真的要登录进去操作。第一次连接时会提示确认服务器指纹输入yes回车即可。如果一切正常会看到一行英文提示Youve successfully authenticated, but GitHub does not provide shell access.看到这句话就说明 GitHub 已经认识你这台电脑了。“does not provide shell access” 是说 GitHub 不给 SSH 用户开终端不是报错很多第一次看到这句话的人会误以为失败了实际上这是成功的标志。3.4 设置提交身份git config 与全局、局部作用域SSH 认证解决的是“GitHub 认不认你这台电脑”的问题还有一个问题要解决GitHub 认不认识“你是谁”。每次 commit 都会记录作者信息这个信息不是从 GitHub 账号自动读取的而是来自你本地的 git 配置。如果没配置就执行 commitgit 会直接报错提示你设置 user.name 和 user.email。在 Git Bash 里执行# 设置全局用户名commit 记录里会显示这个名字 git config --global user.name your name # 设置全局邮箱用于关联 GitHub 账号 git config --global user.email your_emailyouremail.com # 查看当前所有配置 git config --list命令里的your name和your_emailyouremail.com换成你自己的信息。建议邮箱填 GitHub 注册时用的邮箱这样提交记录能在 GitHub 上正确关联到你的账号。--global表示配置对当前用户的所有仓库生效写在用户主目录的.gitconfig文件里。还有--local和--system两个作用域--local只对当前仓库生效配置写在仓库的.git/config里优先级最高--system对整台机器所有用户生效一般用不到。我自己的习惯是全局配置用个人邮箱在公司项目里如果要求用公司邮箱提交就在仓库目录单独执行一遍git config --local user.email这样能避免私人邮箱出现在公司公共仓库的提交记录里。4. 提交、上传、撤回git add / commit / push 的完整闭环4.1 添加远程地址git remote add 与 .git/config 的关系仓库建好了本地代码也有了接下来要把两者连起来。在本地仓库目录里打开 Git Bash执行# 添加远程仓库地址origin 是这个远程地址的别名 git remote add origin gitgithub.com:yourName/yourRepo.git # 查看已配置的远程地址 git remote -v这条命令的格式要解释清楚git remote add是“添加远程仓库”的意思origin是给这个远程地址起的名字约定俗成都用 origin后面 push 时写git push origin master就是在往这个地址推送。冒号后面的yourName是你的 GitHub 用户名yourRepo是你刚才创建的仓库名两者都要替换成你自己的原样粘贴肯定报错。执行完之后用git remote -v验证能看到两行记录一行是 fetch 地址一行是 push 地址。如果你懒得敲命令也可以直接打开仓库里的.git/config文件里面会多出这样一段配置[remote origin] url gitgithub.com:yourName/yourRepo.git fetch refs/heads/*:refs/remotes/origin/*这说明远程地址本质上就是写在这个配置文件里的手动编辑 config 文件改 URL 完全可行。我偶尔会遇到远程地址配错的情况比如仓库改名了直接进 config 把 url 改掉比删了 remote 重新 add 更快。但新手阶段建议还是用命令不容易改错格式。4.2 第一次提交add 与 commit 的分工协作本地仓库里先创建一个 README 文件然后执行# 把 README 文件加入暂存区 git add README # 把暂存区的内容提交成一次快照 git commit -m first commit这里要搞清楚add和commit的分工很多人栽在这里。git add是把文件从工作区放进“暂存区”你可以理解为把要打包的文件挑出来放到篮子里git commit则是把暂存区里的内容拍成一张快照永久写进 git 历史。只add不commit文件只是被标记了并没有真正形成一条提交记录反过来没add就commitgit 会提示没有可提交的内容。-m后面是本次提交的说明文字我的习惯是写清楚这次改了什么比如 “fix: 修复登录接口超时” 比 “update” 有用得多。git add可以一次指定多个文件也可以用git add -A或git add .把当前目录所有变动全部加进去包括文件新增、修改和删除。原文里提到的git add -i是交互式添加会进入菜单让你选择怎么添加适合文件多、需要精细控制的场景新手可以暂时不用管它。4.3 推送与拉取git push 和 git pull 的完整语义第一次提交打完了现在把它推到 GitHub 上# 把当前分支推送到远程 origin 仓库 git push origin master # 从远程拉取最新代码并合并 git pull origin master # 查看工作区状态 git status # 查看提交历史每条记录显示一行 git log --onelinegit push origin master这条命令做了三件事把本地 master 分支上的提交记录发给远程仓库检查远程有没有本地没有的提交有的话会拒绝推送后面避坑章节细说最后更新远程分支的指针。git pull则相反把远程的新提交拉下来合并到本地当前分支。这里要特别注意分支名。原文写的是master这是 git 的老默认分支名。2020 年之后 GitHub 新建仓库的默认分支改成了main所以 push 之前最好先执行git status看一眼提示 “On branch main” 就写git push origin main“On branch master” 就写 master。分支名写错的最典型表现是GitHub 上出现两个分支一个里是你推上去的代码另一个是创建仓库时初始化的 README。git status是我用得最多的命令没有之一。每次要提交之前先跑一遍它能告诉你哪些文件被修改了、哪些文件还没被 git 跟踪、当前在哪个分支。git log --oneline用一行显示一条提交记录配合后面的 tag 操作会用到。4.4 撤销与补救git commit --amend 的边界在哪提交之后发现 commit 信息写错了或者漏掉了一个文件这时候不需要慌乱git 给了后悔药# 修改最近一次提交的说明文字 git commit --amend -m 修正后的提交信息--amend的意思是“修正上一次提交”它不会生成一条新提交而是把最近一次提交替换掉新的提交会包含你补充的文件或修改后的说明。配合使用的方式是先git add漏掉的文件再执行git commit --amend就能把漏掉的文件并入上一次提交。但这里有一个非常重要的边界--amend会改写提交历史。提交的哈希值会变如果这条提交已经被git push到远程了再执行 amend本地和远程的历史就对不上了下一次 push 会被拒绝处理起来很麻烦。我自己的习惯是commit 只存在于本地时随便 amend已经 push 到远程的提交绝不 amend老老实实再提交一条新的 commit 推上去。对新手来说记住“没推上去能改推上去就别动”这条就够了。5. 上传代码避坑指南五个常见报错与对应处理5.1 “fatal: not a git repository” 是没站在仓库里现象在某个目录里执行git add或git commit终端直接报错fatal: not a git repository (or any of the parent directories): .git原因当前目录不是一个 git 仓库或者不在仓库的上级目录链上。git 在找.git文件夹往上翻了所有父目录都没找到就直接拒绝了。解决用cd回到仓库目录或者执行git status看一下当前站在哪个仓库里。如果这个目录本来就不是仓库先git init初始化。《硅谷》里有个段子某程序员把git init当成了人生格言到处执行——现实中如果整个系统盘都被你 init 过那另说但对单个项目来说初始化一次就够了不要反复 init。我从那以后每到一个新目录要敲 git 命令前都会先git status确认自己没站错地方。5.2 SSH 认证失败Permission denied (publickey) 的三种可能现象执行ssh -T gitgithub.com返回Permission denied (publickey)连不上 GitHub。原因GitHub 后台没有匹配到你的公钥。常见有三种可能第一公钥压根没粘贴到 GitHub 后台第二粘贴的时候只复制了一部分或者复制错了文件比如复制了id_rsa私钥内容第三多台电脑共用了同一把私钥但公钥被覆盖了。解决先cat ~/.ssh/id_rsa.pub重新复制一遍公钥去 GitHub 的 Settings → SSH and GPG keys 确认粘贴完整再执行ssh -T gitgithub.com验证。如果还不通干脆重新生成一对密钥再贴一遍。另外注意~/.ssh目录的权限私钥文件不能对其他用户开放读写否则 ssh 会拒绝使用它这在 Windows 上很少见但在一些集成环境里会碰到。我后来在每台新电脑上都是单独生成密钥各贴各的不复制私钥文件再没出过这类问题。5.3 push 被拒绝non-fast-forward 与远程领先本地现象git push origin main被拒绝报错里有Updates were rejected because the remote contains work that you do not have locally.或non-fast-forward。原因远程仓库有本地没有的提交。常见场景是你在网页端直接改过文件或者上一台电脑推过代码现在这台电脑的本地历史落后于远程。git 为了保证不覆盖别人的提交默认拒绝这种推送。解决先执行git pull origin main把远程的提交拉下来。如果两个人改了同一个文件会提示冲突解决冲突后 commit再 push。进阶一点的写法是git pull --rebase origin main它会把本地提交“挪”到远程最新提交的后面历史更干净但冲突处理方式不一样新手先用普通 pull 更稳。千万不要在有同事协作的仓库里用git push -f强推那会把远程的历史直接覆盖掉属于真正的翻车现场。5.4 .gitignore 写了却不生效被跟踪的文件不受它管现象在.gitignore里写了bin/和*.suo执行git status时这些文件照样出现在未跟踪列表里。原因.gitignore的规则只对“尚未被 git 跟踪”的文件生效。如果某个文件之前已经被git add甚至git commit过了git 会一直跟踪它之后再怎么写 ignore 规则都不管用。比如项目开始没写.gitignore你把bin目录整个 add 进去了后来补上 ignore 规则它照样出现在git status里。解决先把文件从 git 的索引里移除但保留在磁盘上# 把 bin 目录从 git 跟踪中移除但保留本地文件 git rm -r --cached bin git commit -m remove bin from version control--cached是关键词意思是只删 git 索引里的记录不动磁盘上的实际文件。执行完再 commit这些文件就彻底不被 git 管了。以后再创建新文件.gitignore的规则才会正常生效。这个坑几乎每个写代码的人都踩过我一般建仓库第一件事就是写好.gitignore免得编译产物全堆进 git 历史里。5.5 tag 传不上去git push 默认不携带 tag现象本地执行git tag v1.0然后git push origin main上 GitHub 网页一看tag 列表是空的。原因git push默认推送的是分支和对应的提交tag 是单独管理的引用不会随分支一起上传。你推了代码但 tag 还留在本地。解决执行git push origin --tags把本地所有 tag 一次性推上去。如果只推送某一个git push origin v1.0。这个问题我在第一次发版本时也遇到过当时我在网页上翻来翻去找不到 tag一度以为是创建失败后来才意识到 tag 和分支是两套引用需要单独推。养成习惯就好打了 tag记得后面跟上--tags。6. tag 不只是版本号给仓库打标签的完整姿势6.1 三种 tag 和几个常用操作tag 在 git 里是一个指向某个 commit 的固定引用适合用来标记开发中的关键节点。原文把 tag 的操作分成了查看、创建、验证、共享几块这里合并成一个常用的命令组合# 查看所有 tag按字母排序 git tag # 过滤查看 v1.x 系列 git tag -l v1.* # 创建轻量级 tag只指向当前 commit git tag v1.0 # 创建带注释的 tag记录版本信息 git tag -a v1.0 -m first version # 查看提交历史找到要为哪个 commit 打 tag git log --oneline # 给历史 commit 打 tag git tag -a v1.1 8a5cbc2 # 删除本地 tag git tag -d v1.0 # 推送所有 tag 到远程关键一步 git push origin --tags # 只推送单个 tag git push origin v1.0轻量级 tag 就像一个便签只包含 commit 的哈希值适合临时标记带-a的 tag 会额外记录打标签的日期、作者和注释信息适合正式发布版本时使用。git log --oneline的输出里左侧那串字符就是 commit 的简短哈希比如8a5cbc2 updated readme后面可以接着那个哈希给历史提交补 tag。git tag -s是带签名的 tag需要本机配置 GPG 私钥没有 GPG 的全套配置就别折腾了个人项目用-a足够了。6.2 让 tag 成为发版的固定动作tag 的好处不只是给版本号贴个标签它让“某个版本的具体代码”变得可以被随时精确找回。发 v2.0 时打个 tag半年后线上出问题一句git checkout v2.0就能回到当时那个提交比靠记忆翻提交历史靠谱得多。我后来养成了一个习惯每次发布版本先git tag -a v1.0 -m release v1.0再git push origin --tags两步固定执行网页上能看到的 tag 列表就是完整的发布列表。如果哪天发现版本号和 tag 对不上优先检查是不是打完 tag 忘了推。希望这个习惯能帮到你至少我从此再没在版本回溯上栽过跟头。本文还有配套的精品资源点击获取