创建在线文档网站之一—学习使用GitHub（附错误解决src refspec master does not match any）

平常我们个人学习或工作的过程中会有些产出，比如技术总结等，为了能更好地管理这些产出，最好的办法是发表在技术博客里。

那对于一个公司来说，如何对外呈现公司的整体产出呢，那就要用到公司网站了。这里我们不做多展开，本次我们的目的是搭建一个公司的技术文档中心。这个技术文档中心，对外可以在线查看官方技术文档，对内可以实现文档源代码的保存和迭代版本管理等。

通过了解，我决定使用GitHub+Hugo这两个开源工具来实现目的。

1. 了解GitHub和Hugo

1）GitHub是一个版本控制系统+代码托管系统+静态网页托管系统

所以，GitHub很好地满足了我们的所有需要。初识GitHub，我们可以把它认作为一个与SVN类似的东西，或者说高级版的SVN，

因为一开始使用它时，并不觉得它与SVN有何不同。

在廖雪峰的教程里，解释得很清楚，即GitHub是分布式版本控制系统，而SVN是集中式版本控制系统，SVN需要有一个中央服务器来存储版本库，使用时必须联网从此中央服务器下载原来的内容和上传修改后的内容，当修改的文件很大时，对于网速就会有很高的要求；而GitHub由于每个使用人本地都有一个完整的版本库，使用时不需要联网，将修改完的内容推送给对方即可。

详细的对比在这里：https://www.liaoxuefeng.com/wiki/896043488029600/896202780297248

图1 集中式版本控制系统（此图摘自廖雪峰个人网站）

图2 分布式版本控制系统（此图摘自廖雪峰个人网站）

2）Hugo是一个依赖于Markdown文件的静态网站生成器

Hugo是Go编写的静态网站生成器，速度快，易用，可配置。Hugo 有一个内容和模板目录，把他们渲染到完全的 HTML 网站。Hugo的好处之一是不用搭建网站服务器环境，它自带一个Web服务器，给我们技术小白们省去了很多力气。

遗留问题：为什么选择GitHub+Hugo呢？这应该是看过很多文章以后权衡的结果。其实以前也了解过Sphinx、Nginx、Wordpress，具体原因也许要我把这些工具都试过以后才有明确的答案。所以，先做为一个遗留吧。

2. 实操——Windows环境下安装和使用GitHub

使用流程图总结如下：

接下来请看具体步骤。

1. 注册GitHub账号

https://github.com/

需要注意的是，GitHub账号注册时既有邮箱，又有用户名。后续使用过程中，会有需要输入用户名的时候。

注册过程中，需要进入邮箱验证。注册成功后，点击Sign in登录。

2. 下载Git

https://www.git-scm.com/download/

验证安装：鼠标右键菜单出现以下两项表示安装成功。

3. 设置GitHub

在本地电脑任意目录右键选择Git Bash Here，进入GitHub命令行工具

$ git config --global user.name "abc987987"
$ git config --global user.email "abc987@sina.com"

  

查看用户名和邮箱，如果设置不对，重新执行以上命令进行修改。

​​$ git config user.name
$ git config user.email

  

4. 使用GitHub

我们需要创建两个版本库（GitHub称之为Repository），一个是远程仓库，一个是本地仓库

1）在GitHub网页上创建远程仓库

使用用户名/邮箱名和密码登录https://github.com/，单击“+”选择New repository，创建远程仓库。

这里以创建abc远程仓库为例。

待会需要将远程仓库上的文件克隆(clone)到本地仓库。所以这里我们可以先在远程仓库上创建一个文件，后续验证克隆到本地的内容是否正确。

单击Code，将以下IP地址复制待用。

说明：远程仓库和本地仓库是使用HTTPS或SSH连接的，使用SSH安全性更高，但需要设置密钥，而HTTPS连接也是符合要求的，为了配置简便，我们这里暂时使用HTTPS连接，就不对SSH配置作介绍了。

2）克隆远程仓库到本地，形成本地仓库

$ git clone https://github.com/abc987987/abc.git

  

  可以看到形成本地仓库如下。

  

3）本地仓库中添加一些文件，如添加一个README.md文件。此时该文件状态显示？，表示还未提交到本地仓库暂存区。

4）初始化本地仓库并提交更改至本地仓库

Git Bash Here进入本地仓库文件夹（注意，需要进入clone下来的本地仓库文件夹，而不是在当前文件夹下，因为后续的操作都是针对我们之前clone下的本地仓库的）

$ cd abc //进入本地仓库目录
$ git init //初始化本地仓库
$ git add . //添加当前目录下的所有文件到暂存区
$ git status //查看文件状态
$ git commit -m "first commit"  //将暂存区内容添加到本地仓库，并注释“first commit”

此时文件状态显示为绿色已提交状态，当然这里表示的是本地已提交状态。

6）关键一步——将本地仓库文件推送到远程仓库网上很多教程都是执行了git push -u origin master，正常这里是要弹窗输入用户名和密码的（因为我未配置SSH连接，使用了默认的HTTPS连接；如果前期配置了SSH连接不需要每次输入用户名和密码）但执行以后发现报错如下图。

提交文件至远程的报错

查了很多文章都未解决，最后参考https://my.oschina.net/lvyi/blog/317255这篇文章终于出现了弹窗。

弹窗出现终于见到曙光

在远程仓库的Settings->Branches也可以看到默认分支名称为main。

回顾这里我们必须要了解此条命令的含义，才能保证正确的使用，而不是亦步亦趋地跟着前人的步骤来，之所前人步骤不可参考是因为当前形势发生了重大变化：（ 

 a. 学习git push -u origin master此条命令含义

 查询得知git push -u origin master是将本地的master分支推送到origin主机即远程仓库，同时指定origin为默认主机，后面就可以不加任何参数使用git push了。使用-u选项指定一个默认主机的意思。

同时参考https://www.runoob.com/git/git-push.html如下：

      git push 命用于从将本地的分支版本上传到远程并合并。

      命令格式为：

$ git push <远程主机名> <本地分支名>:<远程分支名>

      如果本地分支名与远程分支名相同，刚可以省略冒号后面的内容

$ git push <远程主机名> <本地分支名>

经过近一天的折磨，我是参考https://my.oschina.net/lvyi/blog/317255将问题得到了初步解决（然后又遭遇了用户名和邮箱的混淆错误：））。

解决：执行git push origin HEAD
origin : 是远程仓库的名字
HEAD: 是一个特别的指针，它是一个指向当前正在工作的本地分支的指针，可以把它当做本地分支的别名，这样就可以知道你工作在哪个分支。

$ git push HEAD //将正在工作的本地分支推送到远程仓库

也就是说，如果在不确定远程仓库名称的时候，直接使用git push origin HEAD是可行的。

那么，为什么广大前辈执行的“git push -u origin master”在我这就不香了呢？

原因在这——因为我本地的分支压根不叫master，而是叫main。当我将master改成main，马上出现了弹窗，呜呜，多么美好的弹窗。

至于我做了什么操作，导致我的本地分支改成main，而不是master呢？这就涉及到形势变化了。

 b. 了解当前形势发生了什么重大变化

根据https://blog.csdn.net/h176nhx7/article/details/111350550

早在今年 6 月份，受美国大规模的 “Black Lives Matter”运动影响，为了安抚愈演愈烈的民众情绪，GitHub 就宣布将替换掉 master 等术语，以避免联想奴隶制。现如今，在外界一些声音的催促下，这一举措则终于要正式落地了。

除 GitHub 外，为了避免带有所谓的“种族歧视色彩”，许多科技巨头或知名软件也都调整了自己的业务和产品，以平息社会舆论。包括有：MySQL 宣布删除 master、黑名单白名单等术语；Linus Torvalds 通过了 Linux 中避免 master/slave 等术语的提案；还有 Twitter 、GitHub、微软、LinkedIn、Ansible、Splunk、OpenZFS、OpenSSL、JP Morgan、 Android 移动操作系统、Go 编程语言、PHPUnit 和 Curl 等宣布要对此类术语进行删除或更改。同时，IBM、亚马逊、微软也都接连调整面部识别平台业务，以防加深歧视或遭受指责。关注公众号 逆锋起笔，回复 pdf，下载你需要的各种学习资料。

且最初在 Git 中写下“master”一词的开发者 Petr Baudis 也于 6 月份在社交网站上表明立场称，自己当年不该使用“master”这个可能给别人造成伤害的词语。并表示，他曾多次希望可以将“master”改成“main”(和“upstream”）。不过直到现在，才由 GitHub 开始主导替换工作。

而对于为何选择“main”而不是其他替换词汇，Github 方面给出的解释为，main 是他们在平台上看到的最受欢迎的 master 替代品。并且 main 这个词汇很短，可以帮助用户形成良好的肌肉记忆；在很多种语言中翻译起来也都很容易。

目前，该平台已将 main 用于新创建的仓库和正在迁移的仓库，例如 dependabot-core。不过，Github 也指出，对于现有的仓库来说，重命名默认分支的举措无可避免地会造成一些麻烦，譬如必须编辑拉请求的设置和修改安全策略等。

此外，Github 还透露，截至今年年底，他们将使现有存储库无缝重命名其默认分支。当用户重命名分支机构时，他们将重新定位打开的 PR 和草稿版本、移动分支机构保护策略等，且所有的这些都将自动完成。

---

也就是说，为了避免种族歧视，在2020年10月1日以后，我们在Github上创建的仓库，现在默认分支名称都是main了，而以前创建的仓库不受影响，仍然是master。

 c. 执行git push origin main 走回正确路线

输入用户名后，将弹出密码窗。

通过上面的截图，我们知道其实直接执行git push origin main也是可以的，直接指向main仓库，而HEAD是指向当前默认仓库。

由于我将邮箱名当做了用户名，所以推送失败。重新执行命令，并输入注册时创建的用户名，推送成功了！显示如下：

这时在GitHub网页上刷新远程仓库，也会发现本地仓库的内容已经推送上去了。

到这我们就完成了GitHub克隆和推送的基本使用，当然这里是做为我们的代码控制系统来使用的，GitHub还可以有很多用途，比如打造个人博客，或者克隆其他作者的开源项目并申请提交自己的修改等。

7）测试——将本地仓库文件文件删除，并推送到远程仓库

为了给后续hugo建站部署文件，暂时先把我们本地仓库里的文件手动删除（注意不能删除.git这个隐藏文件夹），然后执行命令：

$ git add * //提交本地仓库的所有变化到暂存区
$ git commit -m "del"  //将暂存区内容添加到本地仓库，并注释“del”
$ git push origin main //将本地仓库提交到远程仓库

经过上面的实操，我们已经实现了本地仓库和远程仓库的文件修改相互推送。

后续再做深入学习（比如将本地仓库与远程仓库的连接改为SSH连接，这样提交变化时就不需要每次都输入用户名和密码了），我们当前的目标是要结合GitHub和Hugo打造我们的一个在线文档网站。

——————————————————————————————————————————

后续：2021-8-17更新

重新提交本地代码时，一直认证失败。拿报错信息上网一搜才知道原来github对此做了变动，请参考下帖https://blog.csdn.net/mu_mu_mu_mu_mu/article/details/119712430

使用git提交代码到github时报错：Support for password authentication was removed on August 13, 2021.

https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token

重新生成token，即解决