hercules
v10.7.2
高速かつ洞察力に富み、高度にカスタマイズ可能な Git 履歴分析。
概要 • 使用方法 • インストール • 貢献 • ライセンス
Hercules は、Go で書かれた驚くほど高速で高度にカスタマイズ可能な Git リポジトリ分析エンジンです。電池は付属しています。ゴーギットを搭載。
お知らせ (2020 年 11 月): メイン作者が宙ぶらりんの状態から復帰し、徐々に開発を再開しています。ロードマップを参照してください。
コマンドライン ツールには、 herculesとlaboursの 2 つがあります。 1 つ目は Go で書かれたプログラムで、Git リポジトリを取得し、完全なコミット履歴にわたって分析タスクの有向非巡回グラフ (DAG) を実行します。 2 つ目は、収集されたデータに対する事前定義されたプロットを表示する Python スクリプトです。通常、これら 2 つのツールはパイプを通して一緒に使用されます。プラグイン システムを使用してカスタム分析を作成することができます。組織に関連する複数の分析結果を結合することも可能です。分析されたコミット履歴には、ブランチ、マージなどが含まれます。
Hercules は、source{d} のいくつかの内部プロジェクトで正常に使用されています。ブログ投稿 1、2、およびプレゼンテーションがあります。テスト、バグの修正、新しい分析の追加、またはスワガーのコーディングなどによって貢献してください。
バーンダウンの DAG と UAST 差分精製による解析を組み合わせます。 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で生成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 アクションとして実行することが可能です: Hercules on GitHub Marketplace。セットアップ方法を示すサンプル ワークフローを参照してください。
...大歓迎です！ 「貢献」と「行動規範」を参照してください。
アパッチ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という名前のアーティファクトが生成されます。現在、複数のファイルを 1 つのアーティファクトにパックすることは不可能であるため、すべてのチャートと Tensorflow Projector ファイルは内部の tar アーカイブにパックされます。埋め込みを表示するには、projector.tensorflow.org に移動し、「Load」をクリックして 2 つの 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-oftheseus が行うこととまったく同じですが、はるかに高速です。ブレイミングは、カスタム 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が指定されていない場合、ID は次のアルゴリズムによって検出されます。
--people-dictが指定されている場合は、カスタム ID を含むテキスト ファイルを指す必要があります。形式は次のとおりです。各行は単一の開発者であり、一致するすべての電子メールと名前が|で区切られて含まれます。 。大文字と小文字は無視されます。
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使用すると、タイムスタックエリアプロットを通じてコードシェアを描画することもできます。つまり、識別された各開発者について、サンプリングされた時点で生きている回線が何行あるかということです。
Tensorflow プロジェクターにおける torvalds/linux ファイルの結合
hercules --couples [--people-dict=/path/to/identities]
labours -m couples -o <name> [--couples-tmp-dir=/tmp]
重要: Tensorflow をインストールする必要があります。公式の手順に従ってください。
同じコミット内で変更された場合、ファイルは結合されます。開発者が同じファイルを変更する場合、開発者は結合されます。 herculesコミット履歴全体を通じてカップルの数を記録し、2 つの対応する共起行列を出力します。次に、 laboursユークリッド距離による共起確率を反映する密なベクトルである Swivel embeddings をトレーニングします。トレーニングには、動作する 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 は各構造単位が何回変更されたかを測定することができます。デフォルトでは、関数を調べます。他のものに切り替えるには、Semantic UAST XPath マニュアルを参照してください。
hercules --shotness [--shotness-xpath-*]
labours -m 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>
私たちは、各開発者ごとに行われたコミットの数と、1 日あたりの行の追加、削除、変更を記録します。時間的なグループ化を示すために、いくつかのトリックを使用して結果のコミット時系列をプロットします。言い換えれば、2 つの隣接する一連のコミットは、正規化後は類似しているように見えるはずです。
このプロットにより、開発チームが時間の経過とともにどのように進化したかを知ることができます。ハクトーバーフェストなどの「コミットフラッシュモブ」も表示されます。たとえば、上記のtensorflow/tensorflowプロットから明らかになった洞察は次のとおりです。
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プロトコル バッファ形式の複数の解析結果を結合するコマンドです。
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 Figure のサイズをインチ単位で設定します。デフォルトは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 で、解析には 1 時間以上 / 180 GB RAM が必要です。ただし、ほとんどのリポジトリは 1 分以内に解析されます。代わりにプロトコル バッファー ( 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 。これら 2 つの数値を操作して、OOM の直前に休止状態を開始します。--burndown-hibernation-disk --burndown-hibernation-dir /path 。--first-parent 、あなたの勝ちです。 src-d/go-gitからgo-git/go-gitに切り替えます。最新の Go バージョンと互換性があるようにコードベースをアップグレードします。 
