Git 畫圖工具介紹－－gitdags

2021-09-03 2021-09-03 約 311 字預計閱讀 2 分鐘

想像用口頭或文字描述 Git Flow 流程：首先在 develop 開 feature 分支，然後完成後合併回 develop。接著上線要在 develop 開 release 分支，定版後即可合併進 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 git@github.com: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 的方法。