iT邦幫忙

第 11 屆 iThome 鐵人賽

DAY 3
3
Software Development

用樂高玩轉 GIT 版本控制系列 第 3

Day 03 - 如何做出一本樂高組裝手冊?GIT 操作區域

昨天提到了關於「樂高與 GIT 版本控制」的關聯,從今天起,我們要開始以樂高組裝的角度,看 GIT 的一些入門必學的指令;這一篇將會介紹使用 GIT 一定要很清楚的三個區域。

前言

假設你手上已經有一個自己發揮創意組裝完成的樂高作品,市面上也都還沒有類似造型的作品,而你想跟大家分享這個作品該怎麼完成,那你會怎麼做?製作出跟樂高官方提供的類似型式的手冊,讓人依照你寫的手冊跟著一層一層的堆疊,完成一樣的作品,應該是必經的過程。

那要怎麼完成組裝手冊,別人才能一目了然的跟著步驟,就能作出同樣的作品呢?

如何製作出自己的樂高組裝手冊?

我個人認為應該有以下的步驟:

1. 拆解組裝程序作為預備

拆解組裝程序的過程,我想最重要的是,要讓未來看你的手冊的人,可以清楚的知道眼前的這個程序,在做什麼?因此拆解程序的過程中,絕對不能夠讓每個程序一次就出現太多物件,甚至是讓人有跨步驟,無法承接上下步驟的感覺。

2. 定義好第一個開始的基礎

樂高的組裝過程,一個物件需要裝配在什麼位置,通常都是根據目前已有的成品,做相對位置的表示,而在什麼都還沒有的時候,則必須定義好第一塊物件,好讓下一個組裝程序可以有一個相對值作標示。

3. 將組裝程序需要的樂高物件取出

依據分解好的組裝程序,將這個程序需要的物件取出,放在預備暫存區,預備為這些物件標示或寫上說明。

4. 為目前的組裝程序寫上一些說明到手冊上

為整理好的物件們正式寫下說明到準備分享出去的手冊上,並且正式把這些物件堆疊回目前的半成品上。

5. 回到第 3 點,繼續下一個組裝程序

在更細部的思考,同樣以上一篇文章提到的樂高直升機組裝手冊中的第三步驟作例子,如果這個步驟最終要變成第畫面中 4 的樣子,那在思考組裝程序的時候,如果只有標示小步驟 1 和 4 的圖示,那看手冊的人可能就無法理解,但如果再加上小步驟 2 和 3 那手冊就明了多了:

img

再思考的過程中,就如同底下的動畫,工作區有心中已經分解好了的組裝程序,透過暫存區,一步一步的把這些組裝程序正式寫入手冊之中

img

一份好的樂高組裝說明手冊,最好是讓看的人在每個組裝程序上,一看就知道該怎麼把物件裝置在目前的半成品上,因此拆解組裝程序的思維上,必須站在完全不知道相關程序的人的角度上去思考,每個程序步驟是不是太大步,標示的是不是夠精確?看說明手冊的人是不是能夠真的了解。

樂高與 GIT 的關聯

還記得在上一篇提到的圖片原始碼變化嗎?

img

把「原始碼編寫過程作版本控制」之於「製作樂高組裝說明手冊」,相似的地方在於:

  1. 都有一段取出目前的物件暫放的過程
  2. 根據目前的半成品相對位置,將目前的物件組裝起來
  3. 都是先組裝過,確認好組裝程序後,才正式編寫入手冊

在版本控制工具 GIT 的使用中,最終紀錄組裝步驟及物件的區域叫做「儲存區 (Repository)」,而準備放到儲存區前,還在整備中的區域叫做「舞台區 (Stage Area)」,正在編輯中的原始碼,或已經設定好組裝程序,等待進入整備中區域的原始碼們則是「工作預備區 (Workspace)」。

關於 GIT 的三個區域

  • 工作預備區 (Workspace)
    • 還在準備中還沒要記錄到儲存庫的區域
    • 尚未紀錄的步驟在這個區域
  • 舞台區 (Stage)
    • 準備要進入儲存庫前的等待區,要從工具預備區進到舞台區,需要的指令是 git add
    • 就 GIT 的設計上,這邊可以是好幾個新檔案、好幾個有變化的檔案,也可以只是一個只變更了一行的程式碼,甚至是一個檔案在工作區如果有三處修改、新增,也可以只是任意的一處或兩處。
    • 在這個區域籌備好準備進到儲存庫區,需要的指令是 git commit
  • 儲存庫區 (Repository)
    • 從舞台區正式透過 commit 指令記錄下來之後,就進入到儲存庫區,對 GIT 來說,這邊存放的是 GIT 物件 (object),每一次的commit 就紀錄下來自舞台區相對於上一個階段(上一個 commit )的變化,變化可能是新增檔案、在某個檔案中新增一行原始碼、刪除一些原始碼等等的。

總結:

GIT 的三個區域我認為,是初期在操作 GIT 的時候,最需要深刻的認識的概念,當對於每個區域的作用有充分的理解時,在操作指令上,會很自然的覺得理所當然。

我個人,剛開始接觸 GIT 的時候,會覺得為什麼需要舞台區 (Stage) 這樣的區域,直接放到儲存庫 (Repository) 區不好嗎?不過後來隨著與之接觸越來越深就會覺得,還好 GIT 提供了 Stage 區域,這是非常值得讚嘆的設計,透過這個區域,可以不疾不徐的預備這個階段想要放進儲存庫的原始碼「變化」,待準備確認後,再透過commit指令,紀錄這些「變化」的目的、原因等資訊,而後正式放進儲存庫。

接下來我們會再更細部的了解 GIT 在三個區域的一些變化與指令操作,我們下次見。


上一篇
Day 02 - 為什麼是樂高與 GIT
下一篇
Day 04 - 建立自己的組裝手冊,從工作區往舞台區搬 git add
系列文
用樂高玩轉 GIT 版本控制30

1 則留言

0
PeterLiao
iT邦新手 4 級 ‧ 2019-09-19 23:14:44

想請問: 習慣上是要先盡量預想好這次要放入 repo 的 commit 有哪些嗎?
還是後面有文章會提到,我太猴急了/images/emoticon/emoticon25.gif

墨嗓 iT邦新手 3 級 ‧ 2019-09-20 01:12:02 檢舉

這問題我可能也會順便列入下一篇的題材討論。感謝。

實務上,我不會在工作區就想好要放到 repo 的 commit 順序。

但我會在要開始 add, commit 的時候,開始想,要怎麼放 commit 看 code 的人(至少是 code reviewer)才能比較順利得懂每個步驟在幹嘛,然後依序 add, commit。

例如假設我在 HTML 頁面上,用了一個自己獨立新完成的 js 工具。如果這邊每個變更獨立 commit 是很重要的,那我會先針對這個 js 工具作 commit,而後才是 HTML 頁面上的 commit。

因為:

  1. 如果先 commit HTML 使用 js 的部分,再看 js 本體的 commit,對於閱讀的人來說,可能會有天外飛來一筆的哪來的 js 的感受。
  2. 如果有一天我需要逐步的找出哪個 commit 有錯,如果先 commit HTML 的部分再 commit js,那除錯找到 HTML 的 commit 時,可能會因為在這個 commit 還沒有 js 檔,而發生非預期錯誤的錯誤,造成確認錯誤不便。
PeterLiao iT邦新手 4 級 ‧ 2019-09-20 09:49:54 檢舉

理解,要為將來看 code 的人(包含將來的自己)著想;
謝謝詳細解說

另外如果是單人作業、沒有開其他分支,
是不是就無法體會到 repo 前有 stage 的美好了?
我現在也是停在「為什麼不直接放 repo 就好」、 「如果有個 add fileName1 fileName2 fileName3 -m ' some txt '」 不就好了的階段

感覺墨嗓回覆都很詳盡,可以改天剛好沒靈感用發文回,感謝

墨嗓 iT邦新手 3 級 ‧ 2019-09-20 11:18:12 檢舉

真的要往前一百步再到退回來看這個流程,假設自己一年後有需要再回來看 code,如果有好的切分 commit,可以幫助理解自己當時寫的 code。

commit 當下多花一點點時間思考,第一個幫到的通常是自己。

我要留言

立即登入留言