使用Github一年又余了,感觉GitHub还是非常好用的,在这个平台上不仅能学到很多东西,还能认识一些有意思的人。最近同学对GitHub很感兴趣,不知道该如何入门,顺手记录一下。这是一篇5000字+的多图长文(持续更新ING)。

GitHub是做什么的?

  • GitHub是全球最大的同性社交平台,业界人称GayHub, 今年微软喜提全球最大的社交平台GitHub. 好吧,上面是来搞笑的😄, GitHub是一个代码托管的平台,类似于这样的平台还有GitLabCodingBitbucket等等;之所以叫GitHub是因为它只支持Git这一种版本控制工具。GitHub这个单词拆分开来就是GitHub,用过Usb Hub的人都知道hub是一个类似集线器的东西。

Thank you for 10 years

开始使用GitHub

  • 注册GitHub账号
  • 建立Repo, 添加ssh key
  • git的简单使用以及一些GUI的GitHub客户端
  • Commit History 以及 issue
  • 如何编写README文件
  • 如何贡献代码– Pull request
  • 如何为项目添加开源协议
  • 如何在GitHub上面写日记
  • 为项目添加web文档
  • 编译、部署以及添加贴纸

先准备写这些吧。
多图警告⚠️, 本博客文章配有大量图片, 请注意流量。


下面以全球最大的开源社区GitHub为例(今年是GitHub十周年)。

注册GitHub账号

首先,在浏览器中打开GitHub, 映入眼帘的是一只黑色章鱼🐙猫🐱,是不是和我的衣服上的标志差不多😝。

GitHub

GitHub

  • Sign in就是登陆啦,如果你注册了一个账号就直接登陆就是喽
  • Sign up注册一个新的账号
Sign up

Sign up

  • Username填一个简单一点的英文名,因为以后你的博客可以通过Username.github.io来访问的,所以起一个好点的、不太长的名字就很有必要了,比如我的这个Usernameourfor,很短也很好记。

  • Email address填个QQ邮箱📮也是OK的啦

  • Password这个你懂得😳😳

  • step2和step3这个由于我注册过了,我就没打开看了,你看着填吧。

这个B的英语我也是服了。

注册完登陆我们就来到了这样的一个界面:

Home Page

Home Page


我们打开页面右上角的Setting, 打开Your Profile, 就会跳转到我们的个人主页:
不要盗我的图,再盗就全绿了😆

不要盗我的图,再盗就全绿了😆

下载git

这里我们的主角登场了,就是Git, 对于Unix-Like的操作系统, 就不用下载了, 直接从源安装就好了。对于Windows操作系统, 下载最新的Git

以Windows上面为例:
安装完我们的Git之后, 我们需要生成一对SSH Key, 打开安装的Git bash

Windows10 的搜索框中查找Git bash,或者点击Windows徽键,在最近添加中打开,在Git bash键入如下命令:

1
pwd                #print working directory显示当前路径。

创建Repo

新建一个Repository(以下简称Repo/repo),点击页面上面的New repository

New repository

New repository

  • 这个Repository name,你随意,不过并不建议用中文名.
  • Public在你没有付费或者使用学生包的时候,我们只能创建public类型的repo,其实已经够用了。然后点击Create repository就可以完成创建。
  • Description可选。建议勾选☑️Initialize this repository with a README

这时候就会打开仓库主页,依次点击页面右侧的Clone or downloadUse SSH复制框中的Repo地址,待会要用。

添加部署密钥.

打开Git bash,输入ssh-keygen -t rsa -C "2320813747@qq.com",这个邮箱地址换成你的。连续四次回车就生成了一对密钥。

1
2
Your identification has been saved in /c/Users/zip/.ssh/id_rsa.
Your public key has been saved in /c/Users/zip/.ssh/id_rsa.pub.

它会告诉你密钥生成在哪个文件夹,上面是我的密钥生成路径,下面要相应替换成你的,使用cat来查看公钥内容:

1
cat /c/Users/zip/.ssh/id_rsa.pub

复制输出的内容,打开GitHub,点击页面右侧头像旁边的倒三角,打开Settings,在页面左侧的Personal settings下面定位到SSH and GPG keys这一栏,点击右侧的New SSH key来添加一个密钥,其中Title随意,Key填写上一步Git bash里面生成的那个。最后Add SSH key就行了。

Add SSH keys

Add SSH keys

git的简单使用

git命令

下面命令均在Git bashTerminal中执行。
打开我们的项目仓库页面, 复制仓库地址。将远程仓库克隆到本地计算机:

Repo Address

Repo Address

1
2
3
git clone git@github.com:ourfor/Java_note.git # 使用ssh方式clone, 那么你必须在该仓库中添加你的ssh key, 所以对于别人项目你只能使用https的方式clone。

git clone https://github.com/ourfor/Java_note.git

接下来我们为Repo添加文件, 这里我使用数据流重定向来创建一个文件。

1
echo -e "hello world" > firstfile.c # 你没必要这么骚吧, 直接在文件管理器里面移个文件进去不就好了

是不是这样我们放在项目目录下的文件就变成我们的项目文件了呢?肯定不是啊, 那我不是随便放个文件都能改变你的项目文件了, 再者, 版本控制肯定是会有版本记录的啊!这时候我们就需要手动添加文件到我们的项目文件了。

1
git add firstfile.c # 添加firstfile.c到项目

如果每次这样添加不麻烦吗?有时候我都不知道生成了什么文件, 更简易的方法是每次添加项目目录里面的所有文件:

1
git add . # 或者git add -A A就是all的缩写

接下来为我们的更改添加注释信息:

1
git commit -m "first commit"  #其中引号里面的内容就是我们添加的提交记录

添加完提交记录后我们还可以将更改推送到远程仓库:

1
git push origin master   #将本地更改push到分支master

有时版本冲突,可以使用强制推送:

1
git push -f origin master  #参数f就是force的意思

对应的如果远程仓库的版本比较新, 我们可以将远程仓库的内容同步到本地计算机:

1
git pull origin master    #将分支master的内容pull到本地计算机

有时我们开发软件,不同的开发阶段我们的软件有不同的开发版本,比如alphabetagamma. 我们希望一个仓库同时存在多个不同的版本,我们可以充分利用branch的功能。

  • 创建一个新分支
1
git checkout -b alpha
  • 切换分支
1
git checkout alpha

当我们在git中切换分支以后,在文件浏览器里面就看不到其他分支的文件,是不是很方便?

举个栗子🌰
骑士飞行棋坦克大战并存, Game_java

一般该怎么用git?

在添加好ssh公钥后,我们先在本地创建一个目录,以RepoLocal做目录名为例:

  • 初始化RepoLocal目录,使之能够被git管理(设置一次就好了)
1
git init RepoLocal  # 在RepoLocal上级目录执行,如果在目录RepoLocal中则执行git init
  • 关联远程git仓库(一次)
1
git remote add origin RepoRemoteAddress # RepoRemoteAddress 就是你的远程仓库地址
  • 设置提交人信息(每次提交都会显示某某某提交,信息就是在这里设置,一次性设置)
1
2
git config --global user.name "ourfor"    #不太记得是不是这条命令了,反正到时候会有英文提示的,看看提示就好了
git config --global user.email "ourfor@foxmail.com" #用户名和邮箱用于标识和查找头像,如果不介意,随意喽

  • 添加更改文件到repo
1
git add .  # 添加当前目录所有文件及目录  git add -A
  • 为更改添加注释说明信息
1
git commit -m "some information to tell others why you change the file or code"
  • 推送到远程仓库
1
git push origin master   #这里推送到主分支,可以推送到其他分支,第一次推送要加参数u,git push -u origin master
  • 如果远程仓库版本比本地仓库版本新,本地就需要pull
1
git pull

GUI的GitHub客户端

对于GitHub的GUI客户端我是比较推荐GitKraken尽管它在我的电脑里面已经打入冷宫很长一段时间了, 不过它确实比Web端的美观一点, 对各个平台的支持都比较好。还是比较习惯用git的命令来管理.

GitKraken

GitKraken

我们下载安装的git也是有gui的界面的,使用指令gitk来打开gui界面

如何编写README文件

READMD文件作为我们项目的一个说明文件, 我们如何编辑README文件,才能让它美观简洁呢?README文件以后缀.md结尾,它支持markdown语法,同时支持部分html语法,在每个repo中,它会自动解析README.md这个文件.

由于经常使用markdown写笔记和文章,都已经形成自己的风格了,所以下面的语法介绍是我经常使用的, 有很多等价的语法,不再此处一一列举
Markdown语法:
一级标题: #
二级标题: ##
等等…

1
2
# 算法概述
## 递归与分治策略

加粗: 第一个认识的人就是你

1
**第一个认识的人就是你**

倾斜: 很高兴

1
*很高兴*

加粗并倾斜: nice

1
***nice***

插入代码:

  • 插入c语言代码:
    1
    2
    3
    4
    5
    6
    #include <iostream>
    #include <stdio.h>
    int main(){
    printf("Hello world\n");
    return 0;
    }
1
2
3
4
5
6
7
8
```c
#include <iostream>
#include <stdio.h>
int main(){
printf("Hello world\n");
return 0;
}
```
  • 插入shell命令
    1
    2
    sudo dnf install git -y
    sudo dnf update -y
1
2
3
4
```bash
sudo dnf install git -y
sudo dnf update -y
```

规则就是三个反引号+需要语法高亮语言类型

引用书中的话或名人名言:

书籍是人类进步的阶梯 —- 高尔基
1
> 书籍是人类进步的阶梯 ---- 高尔基

小黑点:

  • 你还是这么好看
1
- 你还是这么好看

任务列表(有x显示为勾选,留空表示不勾选):

  • 高等数学
  • 线性代数
1
2
- [x] 高等数学
- [ ] 线性代数

反白:

1
` root ` 在Unix/Linux操作系统中是指具有最高权限的用户

root 在Unix/Linux操作系统中是指具有最高权限的用户

删除线:

1
~~浮生若梦, 为欢几何.~~

浮生若梦, 为欢几何.

文章分割线:

1
---

插入图片:

1
![life](https://i.loli.net/2018/10/06/5bb815d8e14fd.jpg)

life

life

  • 方括号内部是对图片的描述,在github是不会显示出来的,也就是html中的alt
  • 圆括号里面的网址可以是图片的绝对路径地址也可以是相对路径

添加超链接:
GitHub

1
[GitHub](https://github.com)

表格:

1
2
3
|这是表头|A|B|
|:-|-:|:-:|
|h|a|b|

实际效果:

这是表头 A B
h a b
  • :- 这是左对齐
  • -: 这是右对齐
  • :-: 这是居中对齐

显然这种表格是很简单的, 对于更加复杂的表格, markdown就有点心有余而力不足了, 还好兼容html, 我们就可以用html的方式插入表格:

星期一 星期二 星期三 星期四 星期五
第一节 高等数学A(理化214) 线性代数(理化327) 软件综合(一)(机房) 程序设计基础(理化327) 软件综合(一)(机房)
第二节
第三节 程序设计基础(理化327) 大学英语(至105) 大学体育(体育馆)
第四节
午安 我的课表居然这么满🍎🍏🍐🍑🍒🍓🥝🍅
第五节 程序设计基础(机房) 面向对象软件方法学(至308) 算法分析与设计(至308) 操作系统(至116)
第六节
第七节
第八节
傍晚 认识你真好🍇🍈🍉🍊🍋🍌🍍
第一节 Java校选课(至502) 概率论与数理统计(至117)
第二节
第三节
HTML代码
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
<table>
<th>
<td align=center>星期一</td>
<td align=center>星期二</td>
<td align=center>星期三</td>
<td align=center>星期四</td>
<td align=center>星期五</td>
</th>
<tr>
<td>第一节</td>
<td align=center rowspan=2>高等数学A(理化214)</td>
<td align=center rowspan=2>线性代数(理化327)</td>
<td align=center rowspan=4>软件综合(一)(机房)</td>
<td align=center rowspan=2>程序设计基础(理化327)</td>
<td align=center rowspan=4>软件综合(一)(机房)</td>
</tr>
<tr>
<td>第二节</td>
</tr>
<tr>
<td>第三节</td>
<td align=center rowspan=2>程序设计基础(理化327)</td>
<td align=center rowspan=2>大学英语(至105)</td>
<td align=center rowspan=2>大学体育(体育馆)</td>
</tr>
<tr>
<td>第四节</td>
</tr>
<tr>
<td align=center>午安</td>
<td align=center colspan=5>我的课表居然这么满🍎🍏🍐🍑🍒🍓🥝🍅</td>
</tr>
<tr>
<td>第五节</td>
<td align=center rowspan=4>程序设计基础(机房)</td>
<td align=center rowspan=3>面向对象软件方法学(至308)</td>
<td align=center rowspan=3>算法分析与设计(至308)</td>
<td></td>
<td align=center rowspan=3>操作系统(至116)</td>
</tr>
<tr>
<td>第六节</td>
<td></td>

</tr>
<tr>
<td>第七节</td>
<td></td>
</tr>
<tr>
<td>第八节</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td align=center>傍晚</td>
<td align=center colspan=5>认识你真好🍇🍈🍉🍊🍋🍌🍍</td>
</tr>
<tr>
<td>第一节</td>
<td align=center rowspan=3>Java校选课(至502)</td>
<td></td>
<td></td>
<td></td>
<td align=center rowspan=3>概率论与数理统计(至117)</td>
</tr>
<tr>
<td>第二节</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>第三节</td>
<td></td>
<td></td>
<td></td>
</tr>
</table>


数学公式:

数学是科学的语言, 学习笔记里面怎么可以没有数学公式呢?
  • \\(a + b\\)
    \(a + b\)
  • $$a + b$$
    $$a + b$$
  • $$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$$
    $$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$$
  • $$\mathscr{ABCDEFGHIJKLMNOPQRSTUVWXYZ}$$
    $$\mathscr{ABCDEFGHIJKLMNOPQRSTUVWXYZ}$$

markdown编辑的时候最好用$符号括起来。否则就需要转义字符
比如一个$就是是这样:$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$:

$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$

$$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$$
$$\sum_{i=0}^n i = \frac{n+1}{2}$$

原本语法中两个\\, 你还需要加一个\来转义:

$$
\begin{pmatrix}
1 & a_1 & a_1^2 & \cdots & a_1^n \\
1 & a_2 & a_2^2 & \cdots & a_2^n \\
\vdots & \vdots& \vdots & \ddots & \vdots \\
1 & a_m & a_m^2 & \cdots & a_m^n
\end{pmatrix}
$$

我不是学数学的所以我很少用数学公式,如果你对数学公式的用法感兴趣你可以看看Mathjax官网的说明。一般的markdown编辑器和解析器都支持Mathjax

$$
\begin{pmatrix}
🍇 & 🍈 & 🍉 & 🍊 \\
🍋 & 🍌 & 🍍 & 🍎 \\
🍏 & 🍐 & 🍑 & 🍒 \\
🍓 & 🥝 & 🍅 & 😳
\end{pmatrix}
$$

Commit History 以及 issue

Commit History使用场景

情景一

旺仔是一名大二计算机专业的学生,这个学期学校开了一门操作系统的课程,

你渴望力量吗?你想更深入了解计算机吗?

你渴望力量吗?你想更深入了解计算机吗?

操作系统向来都是他的最爱,上操作系统的副教授使用的教材是国外经典操作系统教材,这个教材各方面都不错,唯一得缺点就是实体书太贵,完整的pdf电子书📚又得收费。每章都是免费的,在线网站OSTEP

Three Easy Pieces

Three Easy Pieces


在他Google一圈以后,他累了,在他快要放弃的时候,他想到了GitHub—-这个全球最大的开源社区,打开GitHub主页,键入ostep, 得到了以下结果:

检索结果

检索结果

忽略前面两项搜索🔍结果,之前他找书的时候在Commits里面并没有这两项提交,他发现了这一项提交Delete Operating Systems - Three Easy Pieces.pdf, 他点进去了,

ostep,点击右侧的view就可以下载了

ostep,点击右侧的view就可以下载了

由此我们推测在这一项记录📝提交前,这个仓库里面肯定是有Operating Systems - Three Easy Pieces.pdf这个文件的, 并且这个文件位于目录Computer_Science于是我们进入仓库的主界面,点击上方的Commits, 定位到 Delete Operating Systems - Three Easy Pieces.pdf, 我们选择比这一项提交更早的一次提交,点击右侧的 <>,即Browse the repository at this point in the history(回到那时的仓库), 这里我选择de是这一项提交Added bitcoin books. 找到这个文件并下载。

ostep

ostep

当然,要下载这本教程的完整的电子书📚,我们可以直接在GitHub的检索结果中下载更好的。这仅仅是其中一个应用场景,从这里我们可以知道,GitHub会将你每个版本的代码都保存下来,充分利用Commits,才能更好更舒服的开发。

情景二

曾哥是一名大一软件专业的学生,他觉得前端的东西很炫酷,并且具备一定的前端基础,于是他用GitHub和coding提供的pages,搭了一个基于hexo的静态博客网站,他看上了一个开源的主题Mellow,在使用Mellow这款主题的时候,他发现使用html<table> 标记插入表格的时候,表格离上一段文字总是莫名其妙的出现大段空白,他在经过排查得出这不是主题的bug,于是他在主题作者的仓库提了一个issue(这个B,真是令人匪夷所思,都不是主题的bug还提,md,你总不能让我去hexo官网提交bug吧,我得等多久,还有我也认识主题作者很久了😒),主题作者Michael.Lu很热心,很快就解决了这个hexo引擎解析的bug,然而我们的曾哥不满足一个网站,于是他又搭了一个diary,这回他并没有使用Mellow这个主题,他又遇到了这个表格的问题,于是他想到了之前修复这个bug的mellow仓库,查看commits,他找到了fixed table display in the index-card

commits

commits

点击这段文字的超链接或者右侧的7位奇妙字串😳,我们可以清楚的看到在哪个位置改动了那些代码,当然这段代码不能直接粘贴复制,但是却给我提供了修复的思路。所以很快我就将另一个主题的<table>修复好了。

fix table

fix table

issue

你在使用的时候遇到任何问题,都可以通过点击仓库主页上方的Issues,和作者以及其他人讨论。支持MarkDown语法哦😯。

issues

issues

添加开源协议(License)

当我们的项目达到了一定的规模,贡献者的人数达到了一定的数量,我们就需要为项目添加开源协议.

  • 为什么要添加开源协议?
    简言之,随着你的代码越写越多,你难免会用到一些其他人的优秀代码,或者是一小段,即使是开源的,也并意味着可以为所欲为,你浏览博客和开源项目的时候也应该能看到一些声明,诸如遵守国际禁止演绎3.0许可请遵循BSD开源协议许可等等,算了不扯了,我语言文字功底太差,重点是如何添加,协议的具体内容,在添加时都是可以查看的。

为项目添加开源协议

  • 创建repo时选择
  • 创建repo后添加
创建reop时选择

这个你在创建的时候选择一个开源协议就好了,没什么大的问题。

创建repo后添加
step 1

打开我们的仓库主页(注意最好在项目的根目录添加),在目录浏览的上方有个Create new file

Create new file

Create new file

点进来,我们只需要输入License,输入完后,右侧就会出现Choose a license template, 选择一个合适的模板

Choose a license template

Choose a license template

step 2

Review and submit->Commit new file->Create pull request.我们就创建了一个pull的请求(什么意思自己领会😁)。

Review and submit

Review and submit


Commit new file

Commit new file


Create pull request

Create pull request

依次点击Merge pull request->Confirm merge, 它会提示你Pull request successfully merged and closed, 至此我们的开源协议就添加好了

如何贡献代码– Pull request

正如物理学泰斗牛顿所言:如果说我看得比别人更远些,那是因为我站在巨人的肩膀上(暂且不讨论这句话的其他含义),同样我们打算创建一个新的project的时候并不一定得从头开始,我们可以找找目前已有的项目,fork过来,有时发现了bug,修复之后还可以issue一个 Pull require,作者认为你的修改很好,就会合并你的请求,这样你就成为了这个项目的Contributor,当以后项目的Starfork多了,这还能成为求职的一个加分项,下图就是我在Mellow这个主题贡献的代码.

添加fancybox

添加fancybox

问题来了,具体要怎么做呢?

首先,你得fork一个repo,你自己原创的repo就不存在这种情况。你的repo名下面就会有fork from xxx,同时你做了一些更改以后,就可以通过页面上方的New pull request

为项目添加web文档

在我们的项目,完成到一定的程度以后,README的局限性就很大了,我们可以考虑添加Web文档,其实也不难,README文件就可以作为文档页面.在我们repo上方的setting选项卡里面能找到GitHub Pages这一个选项卡。

GitHub Pages

GitHub Pages

  • source 也就是我们文档的位置,位于哪个分支,哪个文件,这个你自己规划好,你可以放在任意一个分支的根目录或者子目录doc,其实也是可以创建一个专门用来放web文档的分支: docweb之类的名字都是比较见文知义的。
  • theme 一些现成的主题可供选择,如果你对主题中的一些样式不太满意,充分利用Chrome的开发者模式修改元素,就能得到你预期的结果。
  • custom domain 绑定自己的域名,可选。

可以直接将README里面的内容拷贝一份,添加到主页的index.md(文档首页),或者你熟悉html,也可以自己写index.htm

本博客网站就是部署在GitHubCoding上面的一个静态网站。搭建方法见hexo个人博客

写日记

GitHub上面的每次更改都会有一个时间记录📝,如果你懂MarkDown语法,那自然写起来得心应手,除了GitHub以外,Gist也是一个不错的选择,只不过需要科学上网或者ipv6才能访问。Gist是GitHub专门提供的一个写gist的网站,你想写什么就写什么

编译、部署以及添加贴纸

自动编译是使用我们的travis-ci,我们只要在项目更目录下面创建一个.travis.yml,里面填写一些编译的指令以及依赖。具体写哪些,不同的语言写法不同,根据官方提供的文档写就是了。但是一般都需要声明编程语言、操作系统这些。

1
2
3
4
5
language: sh

os:
- linux
- osx

可以参考别人写的.travis.yml

添加贴纸

GitHub官方提供的贴纸图标:Shields.io

search/project URL中填入你repo的address(https形式不带git后缀),它就会自动生成一些icon,因为是svg的矢量图,是可以动态更新的。

动态更新

动态更新


你html排好版之后写进README就好了。Your BadgeStyles是一些可以自定义的icon,其实就和printf的格式化输出字串差不多。它都有英文说明的。


不过像这样盲目的贴是不可取的.

file.ourfor.top

file.ourfor.top

又要开始我的折腾了。
Raspberry pi 3B