2013-10-31

工作中用到的 git 指令

來分享一下最近工作上常用的 git 指令,以及相關工作流程。

首先介紹一下工作的場景,在怎樣的情境下,怎樣的需求,讓我產生了這樣的 git 工作方法。我們主要的 VCS 其實是 mercurial (hg),但是有一個 git 的 mirror,所以可以在 git 的環境下改 code,但是最後必須到 hg 那邊把 patch push 上去,因此比較特別的是,我不會用到 git push,除非要 push 到自己維護的 repository,然後我必須要生成 hg 可讀的 patch 格式。

對應工具


editor: vim
difftool, mergetool: p4merge

alias


可以參考我的 .gitconfig,因為 programmer 的懶人特性,alias 會隨著時間越加越多
[alias]
  lo = log --oneline
  br = branch
  cbr = rev-parse --abbrev-ref HEAD
  df = diff
  dt = difftool
  mt = mergetool
  st = status
  co = checkout
  ci = commit
  cp = cherry-pick
  showt = "!f() { git dt $1^ $1; }; f"
  files = "!f() { git diff --name-status $1^ $1; }; f"
說明一下,絕大多數的 command 都縮寫為兩個字母,其中:
  • git lo -- 因為 git log 顯示的資訊太多,比較習慣一行一個 commit,所以設計了 lo,少個 'g' 表示比較短 XD。
  • git cbr -- current br 單純顯示目前 branch 名稱,主要是拿來給其他 script call 的。
  • git showt -- git show 可以顯示一個 commit 的 change 內容,加上 't' 表示要用 diff tool 顯示。
  • git files -- 列出某個 commit 修改了哪些檔案。

自訂 git 指令


可以在系統中放入 git-xxx 等以 'git-' 為 prefix 的指令 (放在 PATH 指得到的地方),然後之後就可以用 git xxx 使用那些自訂指令,打的時候會有 tab complete,所以當一個功能用 alias 做很複雜的時候,就可以把他獨立成一個檔案,結果就是一包各式各樣的 git-xxx,這包是從前人那裡 fork 來的,有很多功能,不過我沒有全部用到,fork 之後也立馬加了自己的東西,之後會提到。

開始修改


因為 git 的 light weight branching  特性,一般都是一個功能 (bug) 拉一個 branch 出來弄,所以在開始之前,我會先 sync 最新的 code 然後拉一個 branch 出來。另外為了避免弄髒,我會保持 master 跟 origin 同步,不會直接在上面操作自己的東西。
git co master
git pull
git co -b <branch>
開一條有最新 code 的 <branch> 出來。

改 code


就用喜歡的 editor 改 code,測試,這邊沒什麼。

檢查修改


當修改差不多到一個段落後,改動越小越好,但看起來必須有相關起且完整的。這時候我會開始 commit,但是真正 commit 前會先看一下改了哪些檔案
git st
輸出大概像這樣
# On branch demo
# Changes not staged for commit:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#
#       modified:   dom/icc/tests/marionette/test_icc_card_state.js
#       modified:   dom/icc/tests/marionette/test_icc_info.js
#       modified:   dom/system/gonk/RadioInterfaceLayer.js
#       modified:   dom/telephony/test/marionette/test_outgoing_emergency_in_airplane_mode.js
#       modified:   dom/telephony/test/marionette/test_outgoing_radio_off.js
#
# Untracked files:
#   (use "git add ..." to include in what will be committed)
留意哪些檔案是有修改的,以及下面 untracked 的地方有沒有新增的檔案,有的話記得 commit 時要特別加進去。

當發現某個檔案出乎預期被動到了,會進去仔細看看改了什麼
git df <filename>
覺得太複雜就用 diff tool 開
git dt <filename>
如果發現是不小心動到,或是一些 debug/TODO 資訊,覺得可以拿掉了,就用
git co -- <filename>
那個檔案就會被 reset

commit


一般來說整個改動可能很大,會想把他拆成若干個 commits。我們先看最簡單的情形,打算把全部的改動放到一個 commit。
git ci -am "<commit message>"
複雜一點的,照 file 分割。
git add <file1> <file2> ... <fileN>
git ci -m "<commit message>"
注意 -a 是拿掉的,有時後不小心打了,就會全部連沒有 add 的也一起進去,解決辦法是參考後面會提到的「如何把一個 commit 拆成多個」。

最麻煩的,想將一個 file 內的改動,分散在多個 commits,這時候就要用 patch mode。
git add -p [<filename>]
有 file 的話就會只看那個檔案,不然的話就會全部一起看。執行結果如下
diff --git a/dom/icc/tests/marionette/test_icc_card_state.js b/dom/icc/tests/marionette/test_icc_card_state.js
index 535ff77..6f213b9 100644
--- a/dom/icc/tests/marionette/test_icc_card_state.js
+++ b/dom/icc/tests/marionette/test_icc_card_state.js
@@ -4,13 +4,15 @@
 MARIONETTE_TIMEOUT = 30000;

 SpecialPowers.addPermission("mobileconnection", true, document);
-SpecialPowers.addPermission("settings-write", true, document);

 // Permission changes can't change existing Navigator.prototype
 // objects, so grab our objects from a new Navigator
 let ifr = document.createElement("iframe");
+let connection;
 let icc;
 ifr.onload = function() {
+  connection = ifr.contentWindow.navigator.mozMobileConnection;
+  ok(connection);
   icc = ifr.contentWindow.navigator.mozIccManager;

   ok(icc instanceof ifr.contentWindow.MozIccManager,
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]?
他會一個一個 hunk (小改動) 問,互動式的選擇要不要 include 這個 hunk,打 '?' 可以看各個選項的意義,我常用的有:
  • y: 要
  • n: 不要
  • q: 之後都不要了,離開
  • a: 之後的都要
  • s: 如果覺得這個 hunk 太大,可以選這個,讓 git 把他分割的更小,再來問
  • e: 要,但是用 editor 開起來,可以作細部的 diff 格式修改
做完之後,就等於做完 add,可以 commit 了。
git ci -m "<commit message>"
接著 repeat,用 git st 看一下還有哪些 change,一直作到所有都 commit 進去。

commit 的合併與整理


在這之後可能還會繼續改 code、commit,會需要整理 commit,可以用 interactive rebase。
git rebase -i <commit hash>
使用後會用 editor 開起來,上面每行代表一個 commit,下面的是說明。
pick d0c994e Add setRadioEnabled API (idl)
s daac55b Add setRadioEnabled API (dom)
pick a10139d Add radiostatechange in listener (bluetooth)
r d6b0ee2 Add setRadioEnabled API (ril)
pick f18042f Add setRadioEnabled marionette test

# Rebase f17c1b3..15b27cb onto f17c1b3
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#  x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out        
一開始前面的都是 pick,我常用的有:
  • 調換 commit 的順序 (之後可能會 merge fail),
  • s: 合併到前一個 commit
  • r: 改 commit message
  • e: 在打完這個 commit 後停下來,可以做些事
  • 刪掉那行,這個 commit 就會不見 (有可能讓後面的 merge fail)
存檔關閉,rebase 就開始跑了,如果都沒事,就結束了,有 conflict 的話他會說,遇到了直接輸入
git mt
會一個一個檔案用 merge tool 開起來,three-way merge,修改完存檔就表示那個檔案 resolved 了,全部做完後
git rebase --continue
繼續 rebase,有時候 (很少) 修完 conflict 後會發現這個 change 變成空的,這時候會打不進去,可以用
git rebase --skip
跳過這個 commit,通常這在 sync 新 code 要 rebase 才會出現,例如你要改的地方已經被別人先進了。

有時候 conflict 改一改,發現弄爛了,可以砍掉重來,取消這個 rebase,就會回到 rebase 之前的狀況。
git rebase --abort

commit 的分割


有時後會需要把一個 commit 拆成多個,假設要修改的 commit 是最後一個
git reset HEAD^
可以保持檔案內容不動,但是讓 commit history 回到上一步,這時候再用之前的 git add、git add -p 之類的弄出想要的 commits。

如果要拆開的不是最後一個呢?
git rebase -i <commit_hash>
用 rebase 回到前面一點的位置,在 interactive 時把你要拆開的 commit 標成 e (edit),這時候 rebase 到那邊就會停下來,現在你要修改的 commit 就是最後一個了,套用上面教的方法,最後做完後,記得要讓 rebase 繼續跑下去 git rebase --continue。

[自訂] git qapplied


通常我會打 git qa<tab>

這是 git log 的變形,一般來說我們只關心自己加的那幾個 commit,過去的那些 history 不太需要看,這個指令會從你的 branch 與 upstream (master) 的 LCA (Lowest Common Ancestor) 開始列出 log,
Branch demo (downstream from origin/master)
f17c1b3 .. enable ril_debug
d0c994e Add setRadioEnabled API (idl)
daac55b Add setRadioEnabled API (dom)
a10139d Add radiostatechange in listener (bluetooth)
d6b0ee2 Add setRadioEnabled API (ril)
f18042f Add setRadioEnabled marionette test
有了這個之後,我就很少用 git log 了

[自訂] git qrebase


通常我會打 git qre<tab>

類似 qapplied 的概念,在 interactive rebase 時,git rebase -i <commit hash> 都要打一個 commit hash,其實這個值也可以用 LCA 帶入,因為反正會修改的都是自己的那些 commits。

Sync 到最新的 code


隨著在自己 branch 上的開發,master 也會一直往前進,在 deliver patch 前要確保自己有 sync 到最新的 code,這樣產生的 patch 才是基於目前最新的 code,別人打你的 patch 時才不會遇到 conflict。
git co master
git pull
git co <branch>
git rebase master
如果在 rebase 中遇到 conflict,就用前面提到的方法解決。

Patch 的產生


上述的那些方法,可以做出乾淨整齊的 commit,再來就是把這些 commit 輸出成 hg 格式的 patch 檔,可以給別人 review 或是到 hg 那邊 push。

我有改一個類似 git format-patch 的 git format-hg-patch,他會先用 git format-patch 產生想要區間的 patch 檔 (通常我是下 -N, 表示倒數 N 個 commit),接著自動用另一個 tool 把 git format patch 改成 hg format patch,如下:
aknow@aknow-pc:~/workspace/mcg/patch$ git qapplied
Branch demo (downstream from origin/master)
f17c1b3 .. enable ril_debug
d0c994e Add setRadioEnabled API (idl)
daac55b Add setRadioEnabled API (dom)
a10139d Add radiostatechange in listener (bluetooth)
d6b0ee2 Add setRadioEnabled API (ril)
f18042f Add setRadioEnabled marionette test
7497290 Modify related tests
a7bf0a9 .. remove enable radio when power on (ril)

aknow@aknow-pc:~/workspace/mcg/patch$ git format-hg-patch f17c1b3..7497290
0001-Add-setRadioEnabled-API-idl.patch
0002-Add-setRadioEnabled-API-dom.patch
0003-Add-radiostatechange-in-listener-bluetooth.patch
0004-Add-setRadioEnabled-API-ril.patch
0005-Add-setRadioEnabled-marionette-test.patch
0006-Modify-related-tests.patch

aknow@aknow-pc:~/workspace/mcg/patch$ showpatch
HG Part 1: Add setRadioEnabled API (idl)
HG Part 2: Add setRadioEnabled API (dom)
HG Part 3: Add radiostatechange in listener (bluetooth)
HG Part 4: Add setRadioEnabled API (ril)
HG Part 5: Add setRadioEnabled marionette test
HG Part 6: Modify related tests
showpatch 是我另一個小工具,會看目錄下的 .patch,然後列出他們的 title。

再來因為我們的 commit mesasge 中要加上 bug id,我覺得如果每次 commit 都要在 commit message 中打實在很麻煩,尤其是那個 id 一般來說都不會記得,要另外去查, 造成頭腦的 context switch,所以我選擇弄另一個 tool 出來,markbug,負責幫 patch 檔加上想要的 bug id。

至於要怎麼查 bug id 呢,我加了一個指令 git bugs,使用的話要先裝兩個 python packages:
  • bztools: 查 bugzilla 用的 api
  • colorama: 因為我很假掰的想要讓 console 的輸出有顏色,但是不想打色碼
所以一整套用下來大概是這樣:

  • git bugs: 查 bug,複製對應的 bug id
  • git qapplied: 看要生成幾個 patch 檔
  • git format-hg-patch -N | markbug <bug id>:  經過一個 markbug 的 pipe,貼上 bug id
  • showpatch: 檢查最後結果
showpatch 現在前面的綠色 HG 感覺有點雞肋,那是以前還沒弄 git format-hg-patch 時,hg patch 的生成是拆成兩步驟的,有時後會忘記 convert,所以特地在這邊檢查 patch 的格式是 git 還是 hg。

結束,其實用久了,都是那幾個而已。