Git 畫圖工具介紹--gitdags

想像用口頭或文字描述 Git Flow 流程:首先在 developfeature 分支,然後完成後合併回 develop。接著上線要在 developrelease 分支,定版後即可合併進 master 並 tag 版本…

這樣的描述已經非常難懂了,若是用口頭說明可能就跟講 rap 一樣難懂。俗話說的好--「一圖勝萬言」,今天要介紹的 gitdags 是畫 Git Log 的工具,把圖畫好畫面,可以讓團隊在溝通 Git 流程過程更順利。

環境準備

gitdags 是一個 LaTeX 的套件(packages)。我們可以透過這個套件,用相較簡單的語法畫出 Git Log 圖。

因為是使用 LaTeX 排版語法,所以需要先準備相關環境。Mac 系統可以參考 MacTex 安裝。MacTex 安裝好後會多一個指令 pdflatex,這裡有準備好一個 LaTeX 範例檔:

\documentclass[preview]{standalone}
\begin{document} example for a \LaTeX \ document
\end{document}

把它存成一個 latex.tex 檔,然後下指令能產出 PDF 檔:

pdflatex -output-directory=. latex.tex

如果有需要轉圖片的話,可以改用 pdf2svg 工具,Mac 可以透過 brew install pdf2svg 指令安裝,安裝完後使用工具轉 svg:

pdf2svg latex.pdf latex.svg

範例圖檔:

再來是把 gitdags 下載下來:

git clone [email protected]:jubobs/gitdags.git

主要需要的檔案是 gitdags.sty 檔,在 tex 裡使用 \usepackage{gitdags} 去引用它,下面是個簡單的範例

\documentclass[preview]{standalone}
\usepackage{gitdags}
\tikzgraphsset{%
nudge/.style={/tikz/shift={#1}},
nudge down/.style={nudge=(270:#1)},
nudge down/.default=1
}

\tikzset{global scale/.style={
scale=#1,
every node/.append style={scale=#1}
}
}

\begin{document}
\centering
\begin{tikzpicture}[global scale = 2]
\gitDAG[grow right sep = 2em]{
A -- B -- C
};
\gitbranch
{master}
{above=of C}
{C}
\gitbranch
{new-feature}
{below=of C}
{C}
\gitHEAD
{above=of master}
{master}
\end{tikzpicture}
\end{document}

產生圖檔如下:

Packages 裡面用的方法實在是不大懂,總之工程師嘛,可以從範例再去改內容,就可以有很多變化:

\documentclass[preview]{standalone}
\usepackage{gitdags}
\tikzgraphsset{%
nudge/.style={/tikz/shift={#1}},
nudge down/.style={nudge=(270:#1)},
nudge down/.default=1
}

\tikzset{global scale/.style={
scale=#1,
every node/.append style={scale=#1}
}
}

\begin{document}
\centering
\begin{tikzpicture}[global scale = 2]
\gitDAG[grow right sep = 2em]{
A -- B -- C -- {
{[nudge down] D+E -- F+G } -- M -- {
[nudge down] H' -- I'
},
{[nudge down] {[nodes=unreachable] H -- I}}
} ,
C -- M
};
\gitremotebranch
{origin/master}
{above=of M}
{M}
\gitbranch
{master}
{above=of C}
{C}
\gitbranch
{other-feature}
{below=of I'}
{I'}
\gitHEAD
{below=of other-feature}
{other-feature}
\end{tikzpicture}
\end{document}

產生圖檔如下:

附件一:轉檔腳本

根據上面的指令,我有寫了一個腳本可以拿來做自動轉檔用:

#!/bin/bash
set -e

if [[ ! -f $1 ]]; then
echo File is not exists ...
exit 1;
fi

PDF_FILENAME=${1%.tex}.pdf
SVG_FILENAME=${1%.tex}.svg

# Generate PDF file, see http://www.tug.org/mactex/
pdflatex -output-directory=$(dirname $1) $1

# Generate SVG file, use `brew install pdf2svg` to install
pdf2svg ${PDF_FILENAME} ${SVG_FILENAME}

使用方法:

sh tex2svg.sh some.tex

附件二:Docker 懶人包

環境覺得太難搞了,所以就自己寫了一個 Image,用法是啟動 container 的時候,把 tex 目錄綁定到 /tex 即可:

docker run --rm -it -v /path/to/your-tex-files:/tex ghcr.io/mileschou/gitdags

目前的做法是,它會自動找 .tex 檔做轉換,另外如果有 Makefile 的話,則會執行 make

註:這個 Docker Image 有個缺點是,還沒有轉 svg 的方法。