# Outline
一、前言
  1-1. 目標讀者
  1-2. 內容簡介
二、建議閱讀順序
三、文章結構
  3-1. 綱要與簡述
  3-2. 作者碎語
  3-3. 正文結構
  3-4. 附錄
四、範例專案與程式碼

# TL;DR
此篇文章是本系列文的導讀，主要是讓讀者暸解本系列文該怎麼閱讀，文章通常會以怎樣的結構呈現，並怎麼去使用與之搭配的範例程式碼。

# Updated Logs
- 2019-10-17：
  - 新增目錄網址與建議閱讀順序。
- 2019-10-12：
  - 將「建議閱讀順序」的目錄移除，將會獨立成一篇文章，這邊只概略性提及。
  - 更新文章結構為目前實際使用的狀況。

總算遇到一個有空的週末，儘管是前一天是補班，放假的只有一天，在這 30 天的挑戰中，仍是彌足珍貴。今天主要的進度是重整這 19 天來的產出，並且為各文章建立範例程式碼與專案。既然本篇稱之為 README，就讓我們用這篇聊聊這系列文的架構以及如何搭配範例專案與文章內的程式碼服用吧！
—— Day 20

一、前言

1-1. 目標讀者

本系列的主要讀者是已經在使用 Git 這套工具，但是對其了解不多的開發者。更進一步，是大概知道 Git 怎麼用，但對它仍有很多疑惑、想要瞭解更多的人。

所以本文不會像是多數技術工具的書籍、文件一樣，一章章解釋指令該如何使用，而是比較偏向一個觀念或原理為一個章節，和讀者一起探討 Git 背後運作的某些原理，並且附上一個個練習範例，讓讀者在瞭解概念後也能透過指令操作去驗證這個概念，希望能藉此帶給讀者另一個深入暸解 Git 的方向。

1-2. 內容簡介

本系列文主要分為兩大部分，前半部是在聊 How Git Works，也就是 Git 的運作原理；後半部則是 How to Work with Git，也就是在探討如何搭配 Git 進行工作，並延伸到 DevOps 的相關概念。

1-2-1：How Git Works

• 起始：如何使用 Git 工具，並該用什麼角度去切入，以暸解 Git 是怎麼運作的。
• 結構：暸解 Git 是怎麼儲存資料的，透過這部分，我們會暸解 Git 的真實樣貌。
• 空間：延續結構的概念，進一步探討這些資料是如何被儲存與同步的。
• 分合：既然有了空間上的交流，也該來研究分支的分合是怎樣的概念。

1-2-2：How to Work with Git

• 整合：探討如何讓 Git 專心做好自己的角色，並搭配其他工具進行軟體的整合。
• 工作流：暸解 Git 的定位後，或許我們就可以更正確的心態去探討目前團隊適合怎樣的 Git Workflow。
• CI/CD：有了明確的工作流，就可以善用 CI 工具幫我們進行各項自動化，達到持續整合、交付與部署了。

二、建議閱讀順序

在創作本系列文時，秉持著前兩年的參加經驗，決定先不列綱要，以照當天的狀況與當前的總產出去編寫文章，並在事後做審校、編輯。所以天數的順序不一定代表最佳閱讀順序，在編寫系列文時，也會每天更新存在筆者裝置上的綱要，思考還有什麼題目可以編寫的，進修安插與重新調整。因此在完賽後才會有一個最好的閱讀順序。

為了方便讀者閱讀，已在完賽時將閱讀順序寫成一篇文章——《How Git Works：目錄》。本系列文也會在每篇文章放置該篇文章建議的前後閱讀順序。而所謂的順序不一定是一個一對一的直線鏈關係，對我來說各個文章本來就可以互相參照，所以我也會前後的閱讀可能不會只有一個選項，我也在文章中盡量去參照其他文章，讓讀者得以在就自己感興趣的文章做為閱讀的開始。

三、文章架構

3-1 綱要與簡述

本系列文的每篇文章最前面都會有一個程式碼區塊，裡面會放置本篇文章綱要（Outline）以及簡述（TL;DR），讓讀者一進到這篇文章就可以暸解本篇文章是否對其有用。

而在綱要中，以漢字有序列表的項目就是該篇文章的正文，若是羅馬字母有序列表的項目，就代表是附錄。附錄中多是和該篇文章的補述、參考資料、期望能在日後補上的方向（TODO）。

大致會像這樣：

# Outline
一、前言
二、標題甲
  2-1. 標題甲一
  2-2. 標題甲二
三、標題乙
四、小結
Ａ、參考資料
Ｂ、待敘項目（TODO）

# TL;DR
把一篇很長的文章，縮短成簡單的三兩句話，讓人快速抓住文章的精華。

3-2. 作者碎語

在「綱要與簡述」後，正文之前，會有一個區塊用引文的方式去陳述的，通常是和內容直接無關的敘述。這部分就是作者在編寫這篇文章當下的一些喃喃自語或是當時情境的一些介紹。

3-3. 正文結構

如「綱要與簡述」所述，只要是以漢字有序列表的項目就是該篇文章的正文，這邊就會講述與該篇文章標題相關的資訊。而在之中可能還會附上一些特別的 Block。

3-3-1. 指令簡介

在介紹到某個 Git 指令時，會在文章中放置下面的這樣一個程式碼區塊讓讀者可以輔助參照。通常開頭會有兩行註解，分別是表示在介紹哪個指令的 Command Synopsis，以及該指令參考文件網址的 Reference。

# Command Synopsis: git-init 
# Reference: https://git-scm.com/docs/git-init
git init [--options] [directory]

3-3-2. 程式碼

在每段範例程式碼中，都會用 # 作為註解，標示一些資訊，如下：

# Snapshot: 61d0acc @ dot-git
# Location: ~/how-git-works/lab
$ tree .git
.git/
├── HEAD
├── objects/
└── refs/

• 以 # Snapshot: 作為開頭的，是指這段範例程式碼是位於哪個範例專案 (e.g. dot-git) 的哪個 commit (e.g. 61d0acc) 中。
• 以 # Location: 作為開頭的，是指當前命令列所在的位置。~ 是 UNIX 作業系統的表示法，代表的是當前使用者的 home 目錄，以本系列文為例就是 /Users/ironman/。

關於範例專案的說明，請參考本文的「四、範例專案與程式碼」。

3-3-3. 圖片與示意圖

在講解 Git 時，最好是能搭配示意圖。本系列文目前打算用 Graphviz 的 dot 去繪製分支圖，也為了方便筆者紀錄以及讀者能夠複用，通常也會將示意圖的原始碼放置在附錄中。讀者若有興趣，可以先透過 Graphviz Online 編輯與試驗。

3-3-4. 註腳

只要在文章任何地方出現了 [1]的標示，就代表是註腳，通常可以在附錄中找到對應號碼的解說。

3-4. 附錄

這部分通常是用來放置待述項目、參考資料、延伸閱讀、註腳、示意圖的原始碼等。

四、範例專案與程式碼

本系列文專案會有兩個搭配的範例專案，分別是 how-git-works-lab 以及 how-git-works-dotgit，前者是本系列文各個實驗、示範的紀錄，後者是前者各個 commit 時的 .git 資料夾的紀錄，方便對照。

會建議將兩個專案都 clone 在同一個目錄下，然後各取名為 lab 和 dotgit，本系列文在目錄的表示也都會以這樣為主。可以參照下面範例程式碼操作：

# Location: ~
$ mkdir how-git-works
$ cd how-git-works

# Location: ~/how-git-works
$ git clone git@github.com:fntsrlike/how-git-works-lab.git lab
$ git clone https://github.com/fntsrlike/how-git-works-dotgit.git dotgit

下一篇：

• How Git Works：目錄