hercules
v10.7.2
快速、富有洞察力且高度可自訂的 Git 歷史分析。
概述 • 如何使用 • 安裝 • 貢獻 • 許可證
Hercules 是一個用 Go 編寫的速度極快且高度可自訂的 Git 儲存庫分析引擎。內含電池。由 go-git 提供支援。
通知（2020年11月）：主要作者已從冷漠回歸，並逐漸恢復開發。請參閱路線圖。
有兩個命令列工具： hercules和labours 。第一個是用 Go 編寫的程序，它採用 Git 儲存庫並在完整提交歷史記錄上執行分析任務的有向無環圖 (DAG)。第二個是一個 Python 腳本，它顯示了收集到的資料的一些預定義圖。這兩個工具通常透過管道一起使用。可以使用插件系統編寫自訂分析。也可以將多個分析結果合併在一起 - 與組織相關。分析的提交歷史包括分支、合併等。
Hercules 已成功用於來源{d} 的多個內部專案。有部落格文章：1、2 和簡報。請透過測試、修復錯誤、新增分析或編碼來做出貢獻！
燃盡圖的 DAG 以及與 UAST diff 細化的耦合分析。使用hercules --burndown --burndown-people --couples --feature=uast --dry-run --dump-dag doc/dag.dot https://github.com/src-d/hercules
torvalds/linux 線路燃盡圖（粒徑 30，採樣 30，依年份重新取樣）。使用hercules --burndown --first-parent --pb https://github.com/torvalds/linux | labours -f pb -m burndown-project生成1 小時 40 分鐘內hercules --burndown --first-parent --pb https://github.com/torvalds/linux | labours -f pb -m burndown-project 。
從發布頁面取得hercules進位。 labours可以從 PyPi 安裝：
pip3 install labours
pip3是 Python 套件管理器。
Numpy 和 Scipy 可以使用 http://www.lfd.uci.edu/~gohlke/pythonlibs/ 安裝在 Windows 上
您將需要 Go (>= v1.11) 和protoc 。
git clone https://github.com/src-d/hercules && cd hercules
make
pip3 install -e ./python
可以將 Hercules 作為 GitHub Action 運行：GitHub Marketplace 上的 Hercules。請參閱示範如何設定的範例工作流程。
....歡迎光臨！請參閱貢獻和行為準則。
阿帕契2.0
最有用且可靠的最新命令列參考：
hercules --help
一些例子：
# Use "memory" go-git backend and display the burndown plot. "memory" is the fastest but the repository's git data must fit into RAM.
hercules --burndown https://github.com/go-git/go-git | labours -m burndown-project --resample month
# Use "file system" go-git backend and print some basic information about the repository.
hercules /path/to/cloned/go-git
# Use "file system" go-git backend, cache the cloned repository to /tmp/repo-cache, use Protocol Buffers and display the burndown plot without resampling.
hercules --burndown --pb https://github.com/git/git /tmp/repo-cache | labours -m burndown-project -f pb --resample raw
# Now something fun
# Get the linear history from git rev-list, reverse it
# Pipe to hercules, produce burndown snapshots for every 30 days grouped by 30 days
# Save the raw data to cache.yaml, so that later is possible to labours -i cache.yaml
# Pipe the raw data to labours, set text font size to 16pt, use Agg matplotlib backend and save the plot to output.png
git rev-list HEAD | tac | hercules --commits - --burndown https://github.com/git/git | tee cache.yaml | labours -m burndown-project --font-size 16 --backend Agg --output git.png
labours -i /path/to/yaml允許讀取保存在磁碟上的hercules的輸出。
可以將複製的儲存庫儲存在磁碟上。後續的分析可以在對應的目錄上運行，而不用從頭克隆：
# First time - cache
hercules https://github.com/git/git /tmp/repo-cache
# Second time - use the cache
hercules --some-analysis /tmp/repo-cache
此操作會產生名為hercules_charts的工件。由於目前不可能將多個檔案打包到一個工件中，因此所有圖表和 Tensorflow Projector 檔案都打包在內部 tar 檔案中。若要查看嵌入，請造訪projector.tensorflow.org，按一下「載入」並選擇兩個 TSV。然後使用 UMAP 或 T-SNE。
docker run --rm srcd/hercules hercules --burndown --pb https://github.com/git/git | docker run --rm -i -v $(pwd):/io srcd/hercules labours -f pb -m burndown-project -o /io/git_git.png
hercules --burndown
labours -m burndown-project
整個儲存庫的線路燃盡統計。與 git-of-theseus 的做法完全相同，但速度更快。使用自訂 RB 樹追蹤演算法高效且增量地執行責備，並且在執行分析時僅記錄最後的修改日期。
所有燃盡分析都取決於粒度和採樣的值。粒度是堆疊中每個帶組成的天數。取樣是對倦怠狀態進行快照的頻率。數值越小，繪圖越平滑，但完成的工作量也越多。
有一個選項可以對labours內的波段進行重新取樣，以便您可以定義非常精確的分佈並以不同的方式將其視覺化。此外，重採樣可以跨週期邊界（例如月或年）對齊頻帶。未重新取樣的頻段顯然沒有對齊，並且從專案的誕生日期開始。
hercules --burndown --burndown-files
labours -m burndown-file
儲存庫中最新版本中有效的每個檔案的燃盡統計資料。
注意：它將為每個文件產生單獨的圖表。您不想在包含許多文件的存儲庫上運行它。
hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m burndown-person
儲存庫貢獻者的燃盡統計。如果未指定--people-dict ，則透過下列演算法發現身分：
如果指定了--people-dict ，它應該指向具有自訂身分的文字檔案。格式為：每一行都是一個開發人員，包含所有符合的電子郵件和姓名，以|分隔。 。該案被忽略。
Wireshark 前 20 名開發者 - 覆蓋矩陣
hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m overwrites-matrix
除了燃盡資訊之外， --burndown-people還收集每個開發人員添加和刪除的行統計資料。因此可以直觀地看到開發人員 A 編寫的程式碼被開發人員 B 刪除了多少行。
格式是 N 行 (N+2) 列的矩陣，其中 N 是開發人員的數量。
--people-dict ，則始終為 0）。開發人員的序列儲存在people_sequence YAML 節點中。
Ember.js 前 20 名開發者 - 程式碼所有權
hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m ownership
--burndown-people也允許透過時間堆積面積圖繪製程式碼共享。也就是說，對於每個已識別的開發人員，在採樣時刻有多少行處於活動狀態。
Torvalds/linux 檔案在 Tensorflow Projector 中的耦合
hercules --couples [--people-dict=/path/to/identities]
labours -m couples -o <name> [--couples-tmp-dir=/tmp]
重要提示：需要安裝 Tensorflow，請遵循官方說明。
如果文件在同一提交中發生更改，則這些文件是耦合的。如果開發人員更改同一個文件，那麼他們就是耦合的。 hercules記錄整個提交歷史中的對數，並輸出兩個對應的共現矩陣。然後labours旋轉嵌入－透過歐幾里德距離反映共現機率的密集向量。培訓需要安裝有效的 Tensorflow。中間檔案儲存在系統暫存目錄或--couples-tmp-dir （如果指定）中。訓練後的嵌入將寫入目前工作目錄，名稱取決於-o 。輸出格式為 TSV，並與 Tensorflow Projector 匹配，以便可以使用 TF Projector 中實現的 t-SNE 來視覺化檔案和人員。
46 jinja2/compiler.py:visit_Template [FunctionDef]
42 jinja2/compiler.py:visit_For [FunctionDef]
34 jinja2/compiler.py:visit_Output [FunctionDef]
29 jinja2/environment.py:compile [FunctionDef]
27 jinja2/compiler.py:visit_Include [FunctionDef]
22 jinja2/compiler.py:visit_Macro [FunctionDef]
22 jinja2/compiler.py:visit_FromImport [FunctionDef]
21 jinja2/compiler.py:visit_Filter [FunctionDef]
21 jinja2/runtime.py:__call__ [FunctionDef]
20 jinja2/compiler.py:visit_Block [FunctionDef]
透過 Babelfish，Hercules 能夠測量每個結構單元被修改的次數。預設情況下，它會查看函數；請參閱語意 UAST XPath 手冊以切換到其他內容。
hercules --shotness [--shotness-xpath-*]
labours -m shotness
耦合分析會自動載入“shotness”資料（如果可用）。
hercules --shotness --pb https://github.com/pallets/jinja | labours -m couples -f pb
tensorflow/tensorflow 按提交編號排列了前 50 位開發人員的提交系列。
hercules --devs [--people-dict=/path/to/identities]
labours -m devs -o <name>
我們記錄每個開發人員每天進行的提交數量以及新增、刪除和更改的行數。我們使用一些技巧來繪製產生的提交時間序列來顯示時間分組。換句話說，兩個相鄰的提交系列在標準化後應該看起來相似。
這個情節可以讓我們發現開發團隊是如何隨著時間的推移而演變的。它還展示了“commit flashmobs”，例如 Hacktoberfest。例如，以下是從上面的tensorflow/tensorflow圖中揭示的見解：
張量流/張量流隨著時間的推移添加和更改了行。
hercules --devs [--people-dict=/path/to/identities]
labours -m old-vs-new -o <name>
上一節中的--devs允許繪製隨著時間的推移添加了多少行以及有多少現有更改（刪除或替換）。該圖已平滑。
kubernetes/kubernetes 隨著時間的推移所做的努力。
hercules --devs [--people-dict=/path/to/identities]
labours -m devs-efforts -o <name>
此外， --devs允許繪製每個開發人員更改（新增或刪除）的行數。此圖的上半部是累積（整合）的下半部。兩個部分不可能具有相同的比例，因此對較低的值進行縮放，因此不存在較低的 Y 軸刻度。儘管變化線與擁有線相關，但努力圖和所有權圖之間存在差異。
可以清楚地看到，Django 的評論一開始是積極/樂觀的，但後來變得消極/悲觀。
hercules --sentiment --pb https://github.com/django/django | labours -m sentiment -f pb
我們在每次提交時從原始程式碼中提取新的和更改的註釋，應用 BiDiSentiment 通用情緒循環神經網路並繪製結果。需要 libtensorflow。例如sadly, we need to hide the rect from the documentation finder for now為負數，而Theano has a built-in optimization for logsumexp (...) so we can just write the expression directly為正數。不過，不要期望太多 - 正如所寫的，情感模型是通用目的，代碼註釋具有不同的性質，因此（目前）沒有魔法。
Hercules 必須使用“tensorflow”標籤建立 - 預設不是：
make TAGS=tensorflow
這樣的建置需要libtensorflow 。
hercules --burndown --burndown-files --burndown-people --couples --shotness --devs [--people-dict=/path/to/identities]
labours -m all
Hercules 有一個插件系統，允許運行自訂分析。請參閱 PLUGINS.md。
hercules combine是將多個Protocol Buffers格式的分析結果連結在一起的指令。
hercules --burndown --pb https://github.com/go-git/go-git > go-git.pb
hercules --burndown --pb https://github.com/src-d/hercules > hercules.pb
hercules combine go-git.pb hercules.pb | labours -f pb -m burndown-project --resample M
YAML 不支援整個 Unicode 字元範圍，且labours端的解析器可能會引發異常。透過fix_yaml_unicode.py過濾hercules的輸出以丟棄此類違規字元。
hercules --burndown --burndown-people https://github.com/... | python3 fix_yaml_unicode.py | labours -m people
這些選項會影響所有繪圖：
labours [--style=white|black] [--backend=] [--size=Y,X]
--style設定情節的整體風格（請參閱labours --help ）。 --background將繪圖背景改為白色或黑色。 --backend選擇 Matplotlib 後端。 --size設定圖形的大小（以英吋為單位）。預設值為12,9 。
（macOS 中必要）您可以使用下列命令固定預設的 Matplotlib 後端
echo "backend: TkAgg" > ~/.matplotlib/matplotlibrc
這些選項僅在燃盡圖中有效：
labours [--text-size] [--relative]
--text-size更改字體大小， --relative啟動拉伸的燃盡佈局。
可以以 JSON 格式輸出繪製繪圖所需的所有資訊。只需將.json附加到輸出 ( -o ) 即可完成。資料格式未完全指定，取決於生成它的 Python 程式碼。每個 JSON 檔案應包含反映繪圖類型的"type" 。
--first-parent作為解決方法。hercules在「夫妻」模式下的 Linux 核心輸出為 1.5 GB，需要一個多小時/180GB RAM 才能解析。然而，大多數儲存庫都會在一分鐘內解析完畢。試試使用 Protocol Buffers（ hercules --pb和labours -f pb ）。 # Debian, Ubuntu
apt install libyaml-dev
# macOS
brew install yaml-cpp libyaml
# you might need to re-install pyyaml for changes to make effect
pip uninstall pyyaml
pip --no-cache-dir install pyyaml
如果分析的儲存庫很大且廣泛使用分支，則燃盡統計資訊收集可能會失敗並出現 OOM。您應該嘗試以下操作：
--skip-blacklist避免分析不需要的檔案。也可以限制--language 。--hibernation-distance 10 --burndown-hibernation-threshold=1000 。使用這兩個數字在 OOM 之前開始休眠。--burndown-hibernation-disk --burndown-hibernation-dir /path 。--first-parent ，你贏了。 src-d/go-git切換到go-git/go-git 。升級程式碼庫以相容於最新的 Go 版本。 
