Github和GitBook使用

1. GitHub

1.1. 創建賬戶

https://github.com/ 在上面注冊賬戶: gitexample

1.2. 生成本地公鑰/私鑰對

在本地Ubuntu上，ssh-keygen命令創建公鑰/私鑰對：

$ ssh-keygen 

然后根據提示在用戶主目錄下的.ssh目錄中創建默認的公鑰/私鑰對文件，其中_{/.ssh/id_rsa是私鑰文件，}/.ssh/id_rsa.pub是公鑰文件。注意私鑰文件要嚴加保護，不能泄露給任何人。如果在執行ssh-keygen命令時選擇了使用口令保護私鑰，私鑰文件是經過加密的。至於公鑰文件~/.ssh/id_rsa.pub則可以放心地公開給他人。
也可以用ssh-keygen命令以不同的名稱創建多個公鑰，當擁有多個GitHub賬號時，非常重要。這是因為雖然一個GitHub賬號允許使用多個不同的SSH公鑰，但反過來，一個SSH公鑰只能對應於一個GitHub賬號。下面的命令在~/.ssh目錄下創建名為gitexample的私鑰和名為gitexample.pub的公鑰文件。

$ ssh-keygen -C "[e-mail]" -f ~/.ssh/gitexample $ ls ~/.ssh/ gitexample gitexample.pub 

當生成的公鑰/私鑰對不在缺省位置（~/.ssh/id_rsa等）時，使用ssh命令連接遠程主機時需要使用參數-i <filename>指定公鑰/私鑰對。或者在配置文件_{/.ssh/config中針對相應主機進行設定。例如對於上例創建了非缺省公鑰/私鑰對}/.ssh/gitexample，可以在~/.ssh/config配置文件中寫入如下配置。

Host github.com User git Hostname github.com PreferredAuthentications publickey IdentityFile ~/.ssh/gitexample 

好了，有了上面的准備，就將~/.ssh/gitexample.pub文件內容拷貝到剪切板。然后將公鑰文件中的內容粘貼到GitHub的SSH公鑰管理的對話框中。
設置成功后，再用ssh命令訪問GitHub，會顯示一條認證成功信息並退出。在認證成功的信息中還會顯示該公鑰對應的用戶名。

$ ssh -T [e-mail] Hi gitexample! You have successfully authenticated, but GitHub does not provide shell access. 

1.3. 項目托管

本章介紹如何在GitHub上創建一個新項目，包括創建版本庫及為項目設計主頁等。

1.3.1. 創建新項目

Your repositories --> Create a new repository --> set Repository name --> Create Reopsitory Button

1.3.2. 版本庫初始化

如果是從頭創建版本庫，可以采用先克隆，建立提交數據，最后再通過推送完成GitHub版本庫的初始化。步驟如下：

$ git clone [e-mail]:gitexample/helloworld.git helloworld
Cloning into 'helloworld'...
Warning: Permanently added the RSA host key for IP address '13.250.177.223' to the list of known hosts.
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
Checking connectivity... done.

1.3.3. 創建並修改文件README.md

My first GitHub project This is a example repository. Support markdown syntax format. 

1.3.4. 添加README.md文件並提交。

$ git add README.md $ git commit -m "README for this project." 

1.3.5. 向GitHub推送，完成版本庫初始化。

$ git push origin master

1.3.6. 從已有版本庫創建

如果在GitHub項目初始化之前，數據已經存在於本地版本庫中，顯然像上面那樣先克隆、再提交、后推送的方法就不適宜了。應該采用下面的方法。
為試驗新的版本庫初始化方法，先把剛剛新建的測試項目“helloworld”刪除，同時也將本地工作區中克隆的“helloworld”刪除。警告：刪除項目的操作非常危險，不可恢復，慎用。
點擊項目首頁中"Settings"選項卡，在"Danger Zone"區域有"Delete this repository"
然后再重建版本庫“helloworld”，見3.1節。
本地建立一個Git版本庫。

$ mkdir helloworld
$ cd helloworld
$ git init

然后在版本庫中添加示例文件，如README.md文件，內容同前。

$ git add README.md $ git commit -m "README for this project." 

為版本庫添加名為origin的遠程版本庫。

$ git remote add origin [e-mail]:gitexample/helloworld.git 

執行推送命令，完成GitHub版本庫的初始化。注意命令行中的-u參數，在推送成功后自動建立本地分支與遠程版本庫分支的追蹤。

$ git push -u origin master 

1.4. 操作版本庫

1.4.1. 強制推送

上文提交時，提交用戶設置的郵件地址並非gitexample用戶設置的郵件地址。補救辦法就是對此提交進行修改，然后強制推送到GitHub。
重新設置core.editor，user.name和user.email配置變量。

$ git config --global core.editor vim $ git config user.name "gitexample" $ git config user.email "[e-mail]" 

執行Git修補提交命令。
注意使用參數--reset-author會將提交信息中的屬性Author連同AuthorDate一並修改，否則只修改Commit和CommitDate。參數-C HEAD維持提交說明不變。

$ git commit --amend --reset-author -C HEAD 

查看提交日志，發現提交者信息和作者信息都已經更改。

$ git log --pretty=fuller commit 959af4fe61bbdc984dcc26acd139ea3e164096f4 Author: gitexample <[e-mail]> AuthorDate: Tue Sep 4 15:58:25 2018 +0800 Commit: gitexample <[e-mail]> CommitDate: Tue Sep 4 15:58:25 2018 +0800 README for this project. 

使用強制推送。

$ git push -f origin master 

1.4.2. 新建分支

Git的分支就是保存在.git/refs/heads/命名空間下的引用。引用文件的內容是該分支對應的提交ID。當前版本庫中的默認分支master就對應於文件.git/refs/heads/master。
若在GitHub版本庫中創建分支，首先要在本地版本庫中創建新的分支（即引用），然后用推送命令將本地創建的新的引用連同所指向的提交推送到GitHub版本庫中完成GitHub上分支的創建。操作如下：
本地版本庫中建立新分支mybranch1。
創建分支有多種方法，如使用git branch命令，但最為便捷的就是git checkout -b命令，同時完成新分支的創建和分支切換。

$ git checkout -b mybranch1 Switched to a new branch 'mybranch1' 

為了易於識別，添加一個新文件hello1，並提交。

$ touch hello1
$ echo "How are you!" > hello1 $ git add hello1 $ git commit -m "add hello1." [mybranch1 f65bdb4] add hello1. 1 file changed, 1 insertion(+) create mode 100644 hello1 

通過推送命令，將本地分支mybranch1推送到GitHub遠程版本庫，完成在GitHub上的新分支創建。

$ git push -u origin mybranch1 

在GitHub上查看版本庫，會看到新增了一個分支mybranch1，不過默認分支仍為master。

1.4.3. 設置默認分支

在"Settings"選項卡可以設置Default branch。
修改了GitHub默認分支后，如果再從GitHub克隆版本庫，本地克隆后版本庫的默認分支也將改變。

$ git clone [e-mail]:gitexample/helloworld.git helloworld-branch1
Cloning into 'helloworld-branch1'...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 6 (delta 0), reused 6 (delta 0), pack-reused 0
Receiving objects: 100% (6/6), done.
Checking connectivity... done.
$ cd helloworld-branch1/
$ git branch

實際上修改GitHub上版本庫的默認分支，就是將GitHub版本庫的頭指針HEAD指向了其他分支，如mybranch1分支。這可以從下面命令看出。

$ cd helloworld-branch1/ $ git branch -r origin/HEAD -> origin/mybranch1 origin/master origin/mybranch1 $ cd helloworld-master/ $ git branch -r origin/HEAD -> origin/master origin/master origin/mybranch1 

1.4.4. 刪除分支

不能刪除當前工作分支。因此先切換到其他分支，例如從GitHub版本庫中取出master分支並切換。

$ cd helloworld-branch1/ $ git branch master * mybranch1 $ git checkout master Switched to branch 'master' Your branch is up-to-date with 'origin/master'. $ git branch * master mybranch1 

現在可以刪除mybanch1分支。下面的命令之所以使用-D參數，而非-d參數，是因為Git在刪除分支時為避免數據丟失，默認禁止刪除尚未合並的分支。參數-D則可強制刪除尚未合並的分支。

$ git branch -D mybranch1 Deleted branch mybranch1 (was f46a284). 

現在只是本地分支被刪除了，遠程GitHub服務器上的mybranch1分支尚在。刪除遠程GitHub版本庫中的分支就不能使用git branch命令，而是要使用git push命令，而且要先在GitHub上把默認分支切換到mater。在使用推送分支命令時要使用一個特殊的引用表達式（冒號前為空）。

$ git push origin :mybranch1 

1.4.5. 里程碑管理

里程碑即tag，其管理和分支管理非常類似。里程碑和分支一樣也是以引用的形式存在的，保存在.git/refs/tags/路徑下。引用可能指向一個提交，但也可能是其他類型（Tag對象）。

1. 輕量級里程碑：用git tag <tagname> [<commit>] 命令創建，引用直接指向一個提交對象<commit>。
2. 帶說明的里程碑：用git tag -a <tagname> [<commit>] 命令創建，並且在創建時需要提供創建里程碑的說明。Git會創建一個tag對象保存里程碑說明、里程碑的指向、創建里程碑的用戶等信息，里程碑引用指向該Tag對象。
3. 帶簽名的里程碑：用git tag -s <tagname> [<commit>] 命令創建。是在帶說明的里程碑的基礎上引入了PGP簽名，保證了所創建的里程碑的完整性和不可拒絕性。

下面演示一下里程碑的創建和管理。

1. 先在本地創建一個新提交。

$ touch hello1
$ git add hello1
$ git commit -m "add hello1 for mark." 

2. 本地創建里程碑mytag1、mytag2和mytag3。

$ git tag -m "Tag on initial commit" mytag1 HEAD^ $ git tag -m "Tag on new commit" mytag2 $ git tag mytag3 

3. 查看新建立的里程碑。

$ git tag -l -n1 mytag1 Tag on initial commit mytag2 Tag on new commit mytag3 add hello1 for mark. 

4. 將本地里程碑推送到GitHub遠程版本庫。

$ git push origin refs/tags/*
Counting objects: 6, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 548 bytes, done.
Total 5 (delta 0), reused 0 (delta 0)
To [e-mail]:gotgithub/helloworld.git
 * [new tag]         mytag1 -> mytag1
 * [new tag]         mytag2 -> mytag2
 * [new tag]         mytag3 -> mytag3

5. 刪除本地里程碑。

$ git tag -d mytag3 Deleted tag 'mytag3' (was c71231c) 

6. 刪除GitHub遠程版本庫中的里程碑。

$ git push origin :mytag3 To [e-mail]:gotgithub/helloworld.git [deleted] mytag3 

另外，版本庫還可以與一些擴展應用建立聯系，比如跟Email 和Redmine整合，Email可以實現新提交推送至版本庫時，發送通知郵件。Redmine可以和多種版本庫（包括Git）整合，可以直接通過Web界面瀏覽Git提交，還實現了提交和問題的關聯。

1.5. 建立主頁

1.5.1. 創建個人主頁

GitHub 為每一個用戶分配了一個二級域名<user-id>.github.io，用戶為自己的二級域名創建主頁很容易，只要在托管空間下創建一個名為<user-id>.github.io的版本庫，向其master分支提交網站靜態頁面即可，其中網站首頁為index.html。下面以gitexample用戶為例介紹如何創建個人主頁。

1. 用戶gitexample創建一個名為gitexample.github.io的Git版本庫。
2. 在本地克隆新建立的版本庫。

$ git clone [e-mail]:gitexample/gitexample.github.io.git gitexample.github.io
Cloning into 'gitexample.github.io'...
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
Checking connectivity... done.
$ cd gitexample.github.io/

3. 在版本庫根目錄中創建文件index.html作為首頁。

$ printf "<h1>gitexample's HomePage</h1>It works.\n" > index.html

4. 提交

$ git add index.html $ git commit -m "Homepage test version." 

5. 推送到GitHub，完成遠程版本庫創建。

$ git push origin master

6. 訪問網址： http://gitexample.github.io/ 。

1.5.2. 創建項目主頁

如前所述，GitHub會為每個賬號分配一個二級域名<user-id>.github.io作為用戶的首頁地址。實際上還可以為每個項目設置主頁，項目主頁也通過此二級域名進行訪問。

例如gitexample用戶創建的helloworld項目如果啟用了項目主頁，則可通過網址http://gitexample.github.io/helloworld/訪問。

為項目啟用項目主頁很簡單，只需要在項目版本庫中創建一個名為gh-pages的分支，並向其中添加靜態網頁即可。也就是說如果項目的Git版本庫中包含了名為gh-pages分支的話，則表明該項目提供靜態網頁構成的主頁，可以通過網址http://<user-id>.github.io/<project-name>訪問到。

下面以用戶gitexample的項目helloworld為例，介紹如何維護項目主頁。

如果本地尚未從GitHub克隆helloworld版本庫，執行如下命令。

$ git clone [e-mail]:gitexample/helloworld.git $ cd helloworld 

當前版本庫只有一個名為master的分支，如果直接從master分支創建gh-pages分支操作非常簡單，但是作為保存網頁的gh-pages分支中的內容和master分支中的可能完全不同。如果不希望gh-pages分支繼承master分支的歷史和文件，即想要創建一個干凈的gh-pages分支，需要一點小技巧。

若使用命令行創建干凈的gh-pages分支，可以從下面三個方法任選一種。

第一種方法用到兩個Git底層命令：git write-tree和git commit-tree。步驟如下：

1. 基於master分支建立分支gh-pages。

$ git checkout -b gh-pages 

2. 刪除暫存區文件，即相當於清空暫存區。

$ rm .git/index 

3. 創建項目首頁index.html。

$ printf "hello world.\n" > index.html

4. 添加文件index.html到暫存區。

$ git add index.html 

5. 用Git底層命令創建新的根提交，並將分支gh-pages重置。

$ git reset --hard $(echo "branch gh-pages init." | git commit-tree $(git write-tree)) 

6. 執行推送命令，在GitHub遠程版本庫創建分支gh-pages。

$ git push -u origin gh-pages 

稍后，用瀏覽器訪問下面的地址即可看到剛剛提交的項目首頁： http://gitexample.github.io/helloworld/ 。
當然，還有其他創建方法，詳見：GotGitHub

2. GitBook

本文以Ubuntu 14.04.5 LTS為例安裝。

2.1. 安裝nodejs

首先需要安裝 nodejs，以便能夠使用 npm 來安裝 gitbook。
從URL: https://nodejs.org/en/下載Linux版本的nodejs，我下載的是node-v8.11.4-linux-x64.tar.xz。

$ xz -d node-v8.11.4-linux-x64.tar.zx $ tar xvf node-v8.11.4-linux-x64.tar $ sudo cp node-v8.11.4-linux-x64 /opt/ $ sudo chmod 640 /etc/sudoers $ sudo vi /etc/sudoers Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/node-v8.11.4-linux-x64/bin/" $ sudo chmod 440 /etc/sudoers 

重啟系統。

2.2. 安裝gitbook

$ sudo npm install -g gitbook-cli 

2.3. 基本使用

gitbook 的基本用法非常簡單，基本上就只有兩步：

使用 gitbook init 初始化書籍目錄
使用 gitbook serve 編譯書籍
下面將結合一個非常簡單的實例，來介紹 gitbook 的基本用法。

2.3.1. gitbook init

首先，創建如下目錄結構：

$ tree book/ book/ ├── README.md └── SUMMARY.md 0 directories, 2 files 

README.md 和 SUMMARY.md 是兩個必須文件，README.md 是對書籍的簡單介紹：

$ cat book/README.md This is a book powered by [GitBook](https://github.com/GitbookIO/gitbook). 

SUMMARY.md 是書籍的目錄結構。內容如下：

$ cat book/SUMMARY.md * [Chapter1](chapter1/README.md) * [Section1.1](chapter1/section1.1.md) * [Section1.2](chapter1/section1.2.md) * [Chapter2](chapter2/README.md) 

創建了這兩個文件后，使用 gitbook init，它會為我們創建 SUMMARY.md 中的目錄結構。

$ cd book
$ gitbook init
$ tree
. ├── chapter1 │ ├── README.md │ ├── section1.1.md │ └── section1.2.md ├── chapter2 │ └── README.md ├── README.md └── SUMMARY.md 2 directories, 6 files 

注意：在我的實驗中，gitbook init 只支持兩級目錄！

2.3.2. gitbook serve

書籍目錄結構創建完成以后，就可以使用 gitbook serve 來編譯和預覽書籍了：

$ gitbook serve
Live reload server started on port: 35729 Press CTRL+C to quit ... info: 7 plugins are installed info: loading plugin "livereload"... OK info: loading plugin "highlight"... OK info: loading plugin "search"... OK info: loading plugin "lunr"... OK info: loading plugin "sharing"... OK info: loading plugin "fontsettings"... OK info: loading plugin "theme-default"... OK info: found 5 pages info: found 0 asset files info: >> generation finished with success in 1.1s ! Starting server ... Serving book on http://localhost:4000 

gitbook serve 命令實際上會首先調用 gitbook build 編譯書籍，完成以后會打開一個 web 服務器，監聽在本地的 4000 端口。
現在，可以用瀏覽器打開 http://127.0.0.1:4000 查看書籍的效果。
現在，gitbook 為我們創建了書籍目錄結構后，就可以向其中添加真正的內容了，文件的編寫使用 markdown 語法，在文件修改過程中，每一次保存文件，gitbook serve 都會自動重新編譯，所以可以持續通過瀏覽器來查看最新的書籍效果！
另外，用戶還可以下載 gitbook 編輯器，做到所見即所得的編輯

3. GitHub + GitBook管理圖書

3.1. 書籍內容存儲

使用github提供的git倉庫管理書籍內容，增加、修改書籍內容，提交至git倉庫即可。

1. github上創建倉庫arm-cm4-guide
2. checkout arm-cm4-guide到本地

$ git clone [e-mail]:gitexample/arm-cm4-guide.git arm-cm4-guide 

3. 編寫書籍內容

$ cd arm-cm4-guide/ $ cat README.md ARM Cortex-M3與Cortex-M4權威指南（第三版） $ cat SUMMARY.md * [ARM Cortex-M 處理器簡介](chapter1/README.md) * [什么是ARM Cortex-M處理器](chapter1/section1.md) * [Cortex-M處理器家族](chapter1/section1.1.md) * [處理器和微控制器的區別](chapter1/section1.2.md) * [ARM Cortex-M處理器的優勢](chapter1/section2.md) * [低功耗](chapter2/section2.1.md) * [代碼密度](chapter2/section2.2.md) $ tree . ├── README.md └── SUMMARY.md 0 directories, 2 files $ gitbook init info: create chapter1/README.md info: create chapter1/section1.md info: create chapter1/section1.1.md info: create chapter1/section1.2.md info: create chapter1/section2.md info: create chapter2/section2.1.md info: create chapter2/section2.2.md info: create SUMMARY.md info: initialization is finished $ tree . ├── chapter1 │ ├── README.md │ ├── section1.1.md │ ├── section1.2.md │ ├── section1.md │ └── section2.md ├── chapter2 │ ├── section2.1.md │ └── section2.2.md ├── README.md └── SUMMARY.md 2 directories, 9 files 

4. 提交到arm-cm4-guide倉庫

$ git add README.md SUMMARY.md chapter1/ chapter2/ $ git commit -m "add book content." $ git push origin master 

3.2. 構建書籍

首先，使用 gitbook build 將書籍內容輸出到默認目錄，也就是當前目錄下的 _book 目錄。

$ gitbook build
info: 7 plugins are installed info: 6 explicitly listed info: loading plugin "highlight"... OK info: loading plugin "search"... OK info: loading plugin "lunr"... OK info: loading plugin "sharing"... OK info: loading plugin "fontsettings"... OK info: loading plugin "theme-default"... OK info: found 8 pages info: found 0 asset files info: >> generation finished with success in 1.5s ! $ ls _book/ chapter1 chapter2 gitbook index.html search_index.json 

3.3. 創建 gh-pages 分支

將gitbook生成的html page發布github pages上(實際是提交內容到gh-pages 分支)。所以先創建arm-cm4-guide的 gh-pages 分支。

$ git checkout -b gh-pages $ rm .git/index $ git reset --hard $(echo "branch gh-pages init." | git commit-tree $(git write-tree)) $ git push -u origin gh-pages 

現在，目錄下應該只剩下 _book 目錄了，首先，忽略一些文件：

$ echo "*~" > .gitignore $ echo "_book" >> .gitignore $ git add .gitignore $ git commit -m "Ignore some files" 

然后，加入 _book 下的內容到分支中：

$ cp -r _book/* . $ git add . $ git commit -m "Publish book" 

3.4. 上傳書籍內容到 GitHub

現在，可以將編譯好的書籍內容上傳到 GitHub 中 arm-cm4-guide項目的 gh-pages 分支了.

$ git push -u origin gh-pages 

訪問 https://gitexample.github.io/arm-cm4-guide/ 就可以閱讀 arm-cm4-guide這本書了！

4. 利用 GitHub Pages 快速搭建個人博客

fork別人的模板（qiubaiying.github.io），rename為自己的倉庫名(<user-id>.github.io)。
把里面的頁面內容修改為自己的即可。

作者：蝴蝶泉nq
鏈接：https://www.jianshu.com/p/925745669c6c
來源：簡書
著作權歸作者所有。商業轉載請聯系作者獲得授權，非商業轉載請注明出處。