git describe

用最近的 tag 及其間隔的送交數目來描述一個送交，格式是 <tag>-<間隔的送交數目>-g<短 HASH 碼>，後面可以選擇加是否 dirty。<短 HASH 碼> 前面的 g 代表 git，用來區別 SCM。
指令格式
git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]

尋找最近的 tag，首先先看送交本身有沒有 tag，沒有則往上游找。annotated tag 比 lightweight tag 優先，新的比舊的優先。往上游找 tag 的過程中，可能會因合併的送交而有好幾個候選的 tag，最後以間隔的送交數目少的出線。

預設只找 annotated tag
--tags：也找 lightweight tag
--all：也找 refs/ 下的任何 ref，可能是已知的分支、遠端追蹤的分支、或 lightweight tag。
--contains：也找 lightweight tag，但找下游的 tag
--first-parent：只往第一上游找

--match <pattern>：只找符合 <pattern> 的 tag。(似乎 wildcard <pattern> 有些清況比對會有問題)
--exact-match：只看送交本身的 tag

--candidates=<n>：設定候選 tag 的數目，預設只考慮 10 個，設大於 10 執行會慢一些，但較精準，用 --debug 可看每個候選 tag 的結果。設為 0 相當於 --exact-match。

--debug：在 stderr 顯示對每個 tag 尋找的結果

--abbrev=<n>：設定短 HASH 碼的碼數，預設是 9。設為 0 則不加 HASH 碼。

--dirty[=<mark>]：只能用在 HEAD，增加描述 dirty 的清況，預設加 -dirty，可提供 dirty 時要加的描述，例如 M。較舊版本的 git 無此選項，可用 git status | grep 'Change.*:' 判斷。

--long：送交本身有 tag 時預設不顯示間隔的送交數目及短 HASH 碼，加 --long 參數總是顯示這些部份。

--always：當找不到任何 tag 時，顯示短 HASH 碼

參考來源：git help describe

git tag

git 的標籤 (tag) 有 annotated tag 及 lightweight tag 兩種，以有沒有註釋區別。後者沒有註釋、只是代表某個送交不好記憶的 HASH 碼，比較偏向私人或暫時使用。前者有註釋，比較偏向釋出版本用，除了註釋外，還包含日期、貼標籤者的資訊 (名子及 e-mail)，可以選擇加上 GnuPG 簽名。

新增 tag

指令格式：git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>]

沒加特別的參數則是新增名為 <tagname> 的 lightweight tag 到目前送交，可用 <commit> 或 <object> 指定 tag 是要加到哪個送交。

加參數 -a、-s、或 -u <keyid> 的話都是用來新增 annotated tag，這三者不同在於 -a 沒有簽名，-s 是用目前使用者的簽名，-u <keyid> 是用 <keyid> 的簽名。annotated tag 需要加訊息，會跳出編輯器輸入，或用 -m <msg> 透過指令行加訊息，或用 -F <file> 自檔案取得訊息。由於 annotated tag 才能加訊息，沒有 -a、-s、或 -u <keyid>，但有 -m <msg> 或 -F <file> 也是新增 annotated tag，隱含 -a 新增沒簽名的 annotated tag。

-f 或 --force 是強制取代已存在相同名子的 tag
--cleanup

列表

指令格式：git tag 或 git tag [-n[<num>]] -l [--contains <commit>] [--points-at <object>] [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] [--format=<format>] [--[no-]merged [<commit>]] [<pattern>...]

(沒有 <tagname> 或含有參數 -l 或 --list)

-n[<num>]：加顯示 tag 的訊息，預設只顯示一行，可指定顯示幾行。
--contains <commit>：只顯示包含特定送交的 tag
--points-at <object>：只顯示特定送交的 tag
--column[=<options>]：column 顯示
--no-column
--create-reflog
--sort=<key>：排序
--format=<format>：顯示格式
--[no-]merged [<commit>]：只列特定送交可到達與否 (待深入了解)
<pattern>：只顯示樣式比對符合的

刪除

(含有參數-d 或 --delete)

簽名校驗

(含有參數 -v 或 --verify)

tag 修改

以修改 annotated tag 為例：

git tag <tagname> <tagname> -a -f

自動跳出編輯器修改之前的註釋

git show <tagname>

可看到除了原本的註釋，另外有多一筆註釋。如果要覆蓋原本的註釋則用

git tag <tagname> <tagname>^{} -a -f

送交修改的 tag

git push <tagname> -f

在別的 git clone 執行 git pull 並不會更新註釋內容，除非知道哪個 tag 有修改，移除它，再 pull

git tag -d <tagname>
git pull

參考及延伸閱讀

• git help tag
• http://stackoverflow.com/questions/7813194/how-do-i-edit-an-existing-tag-message-in-git
• git describe：描述一個送交跟最近可達的 tag 的關係
• git