Intro to Git, Github and VSCode

Hi，这里是Louis Liu，在本教程中，我将带领大家去熟悉 Git, Github和VSCode 的一些基础操作。

或许你当前还没有完成 CruxAbyss游戏开发小组关于 Echo-Land 游戏项目的 LICENSE签署，那么，请先让我们来完成签署这一步。在签署之前，你需要掌握一些 Github 的基础操作，比如：

Git 和 Github 是什么
Github 中的 Repository (Repo) 是什么
Github Repo 中的 Issue 是什么
Github Repo 中的 Pull Request (PR) 是什么
如何修改/添加/删除 Github Repo 中的文件

当你了解了以上操作之后，你就可以独自去完成签署了。

现在，让我们开始吧。

1. Git 和 Github 是什么

Git是一种分布式的代码版本控制系统。

先让我们来理解一下 “代码版本控制系统”。

这是什么意思呢，也就是Git相当于一个关于代码的历史记录器。为什么我们需要呢，因为在实际开发项目（写代码）的过程中，一次性将代码全部写完，并且能让项目整体运行起来几乎是不可能的事情。因此在正常情况下，我们会将代码模块化，也就是把一个大任务(大代码) 分解成不同的小任务(小代码) 进行分别处理，然后再逐步将这些小代码整合起来成为大代码。

这时，Git这个关于代码的历史记录器就十分重要了，因为它可以帮助你记录你完成的阶段性任务：例如，经理要求你帮公司构建一个可以自动收发邮件的机器人，那么，你首先应该将这个 “可以自动收发邮件的机器人” 这个大任务分解成 “可以自动收邮件的机器人” + “可以自动发邮件的机器人” 这两个小任务进行处理。假设我们先设法去实现 “可以自动收邮件的机器人” 这一部分，若我们完成了，是不是要保存一下？那么此时你就可以用Git来记录一下你当前的代码，然后开始着手下一个任务 “可以自动发邮件的机器人”。

此时大家可能有个疑惑，为什么我一定要记录，我可以不记录吗，这两个任务我分别完成不就好了，似乎根本不需要Git啊？

的确，你当然可以不用Git，但是，你能够确保你在设法实现第二个任务的过程中不会修改第一个任务的代码吗？比如，你在写 “可以自动发邮件的机器人” 的代码的时候，突然发现你可以优化一下自己之前写的 “可以自动收邮件的机器人” 的代码，然后你就改了一下：结果，你改完突然发现你的优化结构完全错了，或者是你突然发现你不小心删除了自己之前写一些代码，导致程序现在运行不起来了。因此你想要回到当时刚写完 “可以自动收邮件的机器人“ 的代码状态，来对比一下，自己当前的代码是哪里写的有问题。然后你开始使用Undo（ctrl + z 或者 command + z），发现也回不到当时刚写完 “可以自动收邮件的机器人“ 的代码状态。于是，你只能眼巴巴地望着当前残破的代码，然后开始硬改。。。。

假设当时你用了Git呢，那是不是超级方便，你只需要用Git帮你回到上次记录过的历史代码状态就可以啦，而且你还可以对比上次的历史代码和自己当前的代码有何不同，等等。因此Git在各类大型项目开发中，几乎都是必备的。

那为什么说 Git 是 “分布式” 的呢？

因为 Git 是允许多个开发者一起协作开发同一个项目的。例如，你可以将你的项目连同这个项目的Git 一起发送给别人，然后大家各自开发，优化代码，提出新的功能等等，然后我们可以用git进行代码对比，项目分支的创建，还有项目代码的合并，等等等等。

Github是一个集成了Git的代码托管平台。

这个平台为全球各地的开发者提供了一种方式去共同协作各种项目，而且还新加了很多功能等等。

因此我们将游戏项目的文件都放在Github平台上就是因为：首先，它有Git可以帮我们记录游戏项目内所有文件的历史状态。同时，Github内置的一些功能例如webhook，还有代码审核功能等等，都可以提升我们游戏项目开发的效率。

2. Github 中的 Repository (Repo) 是什么

这个Github中的Repo其实就是“代码库”的意思，我们上传在Github中的游戏项目目前就是 Github内的一个Repo，如图：

3. Github Repo 中的 Issue 是什么

想象一下：

你正在逛Github，看看有什么好玩的代码，想要试一试。然后你突然发现一个Github上有个Repo是关于自动做作业的Canvas机器人，你一下子就心动了！于是乎，你下载了这个Repo到本地，然后根据这个Repo中的readme文件，学习如何使用这个repo来帮你做canvas的作业哈哈。

（这里提一句，什么是readme文件呢？这其实是各种repo都会有的“使用说明手册”，因为readme文件之所以叫做”read”+”me”是因为，代码作者担心其他人并不清楚他的Repo是干什么的，于是他就写了一个readme文件，里面包含着了关于个repo的简介，还有如何使用等等细节。）

结果，你在跑这个repo中的代码的时候发现，这个代码竟然报错了？你十分确定你的每一步都按照着这个repo中的readme文件运行的。那么唯一的可能就是 —- 作者的代码写的有问题，或者，作者的readme文件写的有问题，不过这些都是repo内的文件，所以，无论如何，都是repo内的文件出了问题/bug。那么你既然发现了这个问题，并且希望作者能够解决（毕竟是可以帮你做作业的机器人诶！），于是，你可以到Github的issue里面去提出这个问题，向作者反馈bug。如果你的能力相对高一点，你可以通过debug的方式找到代码报错和bug的具体位置，然后通过issue向作者反馈。如图：

例子：Github Repo是在这里提交/反馈 Issue 的

一个issue的例子

不过，值得一提的是，在Github Repo的issue中，你不但可以反馈bug，你还可以提出一些代码的建议，或者是一些新功能的添加请求。例如，你对于那个canvas自动做作业机器人十分满意，不过你还希望这个机器人可以帮你完成canvas的线上考试，但是这个功能目前repo中还没有，而且你自己的代码水平也不是很高，没有办法独自添加这个功能，那么，你就可以在repo中的issue中提交一份功能请求，来告诉代码作者，希望他可以在不久的将来加入这一功能等等。

4. Github Repo 中的 Pull Request (PR) 是什么

想象一下：

你对于那个canvas自动做作业机器人十分满意，不过你还希望这个机器人可以帮你完成canvas的线上考试，但是这个功能目前repo中还没有。但是！你的代码水平很高，你有百分百的把握自己可以添加这个新功能到repo里。于是你花了几天时间，改进了一下你当时下载到本地的那个机器人的repo，并实现了这个自动做canvas的线上考的功能！此时，十分仗义的你，觉得这种东西不能自己一个人独享，而是要造福全体留学生！

因此你决定把你本地改进后的repo发到github上去，但是，你不能在github上直接修改原作者的repo，因为别人没有给你权限啊。同时，你不能创建一个新的repo然后发上去，因为，你当前的代码可是在一个作者完成了canvas做作业机器人的代码基础上改进的啊！所以，按照国际惯例以及基本道德礼仪，你应该在Github上提交一个Pull Request到原作者的Repo中。这样一旦你的代码被原作者同意收录，那么Repo中就会多出你的代码部分，而且你的名字也会被加入这个Repo的贡献者名单当中。

那么问题来了，什么是Pull Request（PR）呢？

PR的直译就是 “拉取请求” ，意思是，“希望作者可以把你的代码收录进当前的Repo中”。一个容易理解的例子就是，你写了一首新的“唐诗”，然后你向“唐诗300首”这个repo提交了一个PR，如果唐诗300首的作者同意了你的PR，那么“唐诗300首”就会变成“唐诗301首”了😂，然后你也会成为作者之一。

好，那么改如何提交PR呢，是直接在Github上点击那个Repo的Pull Request按钮吗？

其实并没有那么简单哦，请看下一小节。

5. 如何修改/添加/删除 Github Repo 中的文件

好，现在，让我们来模拟一次：你修改了 Github Repo 中的文件，然后向对这个 Repo 提交了一个 PR。

首先，让我们先明确一点，如果你将这个Repo下载到了本地，然后你对这个本地repo进行了修改，那么这是没有办法提交PR的。为什么呢？因为Github要求，你修改的repo必须需要有同一个git，才可以提交PR。

哦哦，那是不是说，我对我本地改好的repo创建一个git就好了？

当然不是哦，因为你对你本地改好的repo创建的git，是一个新的git哦，和原作者的repo的git不是同一个git哦？两个代码的历史记录是不一样的，因为你的历史记录器（git）只记录了你修改的历史记录，而原作者的修改没有被记录诶，所以你的git在被初始化的时候就只记录了你直接用原作者的代码的状态（如同100分的卷子你直接从60分开始做，60分之前的做题记录根本没有）！而原作者那边的git只记录了他自己修改的历史记录，你的修改记录并没有被录入（如同100分的卷子，原作者的git只记录了 0分 —- 60分的做题过程）。

而同一个git，应该是记录着从 0分 —- 100分的所有做题过程，一点都不可以漏！

那么我该如何把我做的 60分 —- 100分的做题记录和原作者做的 0分 —- 60分的做题过程进行合并呢？

答案：你需要在一开始就把原作者repo连同那个repo的git一起copy到你的本地上，然后再正常做你的修改，而不是新创建一个git！

原来如此，不过为什么一定要用同一个git在改进repo？我就是不想用同一个git，怎么办！

答案：你的确可以不用同一个git，但是：

首先，如果你打算公开你改进后的repo，但是你不用同一个repo，这也就意味着抹除了原作者的0到60分的贡献，通常这是极其不道德的行为。
其次，从代码合作层面讲，这会导致repo缺乏统一性，使得其他代码人员不知道应该统一改进哪一个repo，例如我改进了代码的可读性，你增加了代码的一个新功能，但是由于我们没有用同一个git，导致了repo分裂成两个repo，这样不同的功能没有被整合到一起，使得开发效率低下。

还记得我们之前说git是“分布式”的吗？Git 是允许多个开发者一起协作开发同一个项目的，但是，其核心在于，你们共同协作开发的repo需要使用同一个“代码版本控制系统”，或者说，同一个“代码的历史记录器”，因此这意味着你们共同协作开发的repo必须使用同一个git。

举个例子，假设A和B都借了C的作业来抄，但是因为C在班级里是公认的学渣，一般他的作业只有60分，因此学霸A和学霸B在抄C的作业的时候必须十分小心，防止犯下同样的低级错误被老师抓包。于是，A和B各自边抄边改，最后都完成了作业。不过，由于A和B也是十分仗义的，觉得独乐乐不如众乐乐，因此他们打算在班级里公开自己改好的作业，来给全班其他同学抄。但是问题来了，到底公开谁的呢，A的，还是B的？如果公开之后，学王D想要改进一下其中一人的作业，那么另一个人的作业就没有用了吗？于是为了防止这种事情方法，AB两人决定对比一下双方的作业，并打算一起做出一份作业来公开（两份repo通过PR请求，最终被原作者同一个，而合成为一份repo的概念叫做merge，这个在后文中会提到）。

这里面其实蕴含着“共同协作开发的repo必须使用同一个git”的思想，因为如果A和B都公开，这就相当于，一个repo经过修改之后分裂成了两个repo，因为A和B的repo并没有用同一个git，那么此时班级的同学选择谁的呢？因此他们决定对比，这一举动其实意味着要统一git，例如A的作业中修改了C做的第一问，因为他觉得C做的步骤太繁琐了，而B的作业却没有修改C做的第一问，但是B修改了C做的最后一问，A却没有修改那到问题。为了献出一份完美的作业，他们最后将双方学霸做出的修改都合并了起来，也就是统一了git。这样其他学生可以统一抄一份完美的作业，十分方便！要是后续有个学王，觉得可以再改进一下这个作业，那他也可以直接改，而不是要同时对比A和B两份作业，然后再做出选择。

好了，既然我们明确了“共同协作开发的repo必须使用同一个git”，现在让我们开始实操吧。

首先，由于我们需要在一开始就把原作者repo连同那个repo的git一起copy到本地上，那么这应该怎么做呢，repo正常的下载是无法将git一起下载的，因此，我们需要点击repo旁边的 “Fork” ，这样就可以把原作者repo连同那个repo的git一起copy到本地上了！

现在让我们来一起操作一下，请你也用你的github开始跟随我的教程一起复现。

请先点击here，这是专门给你熟悉github用的repo，不会有任何负面影响的。

首先，点击 “Fork”，如下图。

在点击完后，你会看到这个页面，什么都不用改，直接点击右下角绿色的 “Create fork”。

点击之后，稍稍等待几秒钟，你应该会看到如下的页面。

上图中的红框所圈起来的信息，都在表示这个repo是你fork的，你可以对比一下原作者的repo和你fork后的有什么区别。

现在，请点击 docs/ 这个folder，如下图。

再点击 ok.md 这个file。

然后你可以选择（下图）：

选项1: 点击红框内左边的 ✏️ 直接进行编辑（若你对coding相关的东西不是很熟悉，请选这个）

或者

选项2: 点击右边的小三角形，再选择”open with github.dev” 来使用网页版的vscode进行编辑（若你对coding相关的东西很熟悉，请选这个）

选项1的步骤：

然后你应该看到下图，请在里面随便写点什么。

等你写完之后，请点击 “Commit changes…”。

点击完之后，你应该会看到下图，然后请修改一下 Commit message 下的内容，这里应当填写你对这个file做了什么大致的修改，然后再 Extended description 处，若你觉得需要补充什么其他内容，或是想要详细展开说明自己添加或者修改的内容等等。以后请养成这样良好的填写习惯，因为在git中，这些都是你的代码记录的信息，如果你填写的模凌两可，不够清楚，那将导致到后期开发的时候，不便于快速查看这些代码历史状态，也不方便总结项目进度的信息等等，这些都会给未来的你造成麻烦。

等你认真填写完这些信息之后，请点击右下角的 “Commit changes” ，如下图。

此时你的forked repo就记录了这些changes然后更新啦！

提一句，这个”Commit changes” 其实就是 “记录changes” ，并非 PR 或者 “收录” 。PR是正式的收录请求。

而且， “Commit changes” 一般就是普通的记录，你可以使用它来记录各种小changes（commit changes如同给你写的作业拍照记录一下，防止丢失什么的，不过不必如此频繁的使用），因为它并非是一个里程碑/目标的change，一旦达到了里程碑/目标的change，我们将会使用PR（PR如同把你所拍的所有作业照片合并成为一个最终作业pdf进行提交）。

(不过， 选项1 这种方法也有缺点，因为每次只能修改一个file，如果使用 选项2 的话，将可以十分轻松的同时修改多个file，你要是敢兴趣的话，可以查看一下选项2的步骤。)

然后现在，让我们提交一下PR来试试手，不过，在实体做项目开发的时候，请一定不要频繁提交PR，因为PR相当于提交最终作业，是非常正式的，只有当你所记录的所有changes都满足了特定目标的时候，那才可以提交PR。

所以，commit changes如同给你写的作业拍照记录一下，防止丢失什么的，不过不必如此频繁的使用。PR如同把你所拍的所有作业照片合并成为一个最终作业pdf进行提交。

现在让我们来提交一下PR吧。

请先回到你的fork了的repo的页面，然后点击 “Contribute” ，如下图。

之后请点击 “Open pull request” ，如下图。

然后，你应看到下图，请点击 “Create pull request” 。

之后，你应看到下图，然后请填写 “Title” ，其应当包含你记录的所有changes的大致信息，关于细节，请在下方的 “Description” 中填写。同时务必点击右侧红框框选的 “Labels” ，并选择对应的Area Label，而且请只选择一个Area。然后请点击下方的 “Create pull request” 。

（但如果你忘了选择Area并Create了PR，也没有关系，DevGuardian Bot将会提醒你去选择Area。）

下图就是PR提交好了的页面。

然后PR就提交好了，若你在提交PR前，正确地选择了相应的Area，那repo的审核人员将会立刻收到审核提醒。之后repo的审核人员将会根据PR的贡献程度来添加一个Importance Label，这将会记录在你的贡献统计当中。

之后若所有的commits记录没有任何问题，并且符合游戏开发的目标等等，审核人员将会把这个PR merge到原repo内。

这是什么意思呢？

还记得PR是什么吗？它是“拉取请求”，是将“forked repo”拉取到“原repo”的请求，当然这两个repo是拥有同一个git记录的。如果这个拉取请求被repo的原作者接受了，那么“forked repo”和“原repo”就会被merge（融合）。

然后“原repo”就会更新啦。不过，当然你的“forked repo”也不会消失的，只要fork过一次，这个就会永远在你的账号里存在的。以后如果你还想要更新“原repo”，同样可以通过在“forked repo”中commit changes，然后提交PR，并不需要重新fork一次。

然后，你就已经入门github啦，现在请去 CruxAbyss/Echo-Land 这个repo内的 LICENSE.txt file里提交你的签名（在这个file的末尾处署名）吧，步骤和上面也是一样的，先fork，再commit changes，再提交PR，等收录了你就正式成为CruxAbyss的一员了🤝。

选项2的步骤：

对于上图，若你点击了右边的小三角形，然后选择了”open with github.dev”，你应看到以下页面，然后请你在ok.md这个file里随便写点什么，之后请点击红框选中的图标。

之后请点击 “Changes” 旁红框圈住的 “+” ，这代表着你想把所有的changes都打算记录在repo中，因此如果你只想要记录其中部分文件，那你可以点击被更改的文件旁的 “+” ，这个十分有用，因为当你对项目内的不同文件都做了修改，而你想要把相对应且修改好了的文件进行记录，而有些修改了的文件但是还没有改好，你就可以不点他们旁边的”+”，以此来暂时不记录他们。

然后当你点好这些”+”之后，请在Message方框中的填写一下你对这些选中的file做了什么大致的修改，请注意，这是一定要填写的，如果不填写，你将无法commit成功，因为这是git的要求。

同时，以后请养成这样良好的填写习惯，因为在git中，这些都是你的代码记录的信息，如果你填写的模凌两可，不够清楚，那将导致到后期开发的时候，不便于快速查看这些代码历史状态，也不方便总结项目进度的信息等等，这些都会给未来的你造成麻烦。

当你填写好之后，请点击绿色的 “Commit & Push”，这样就记录好了你对这些file做的changes。

此时你的repo就记录了这些changes然后更新啦！