hercules
v10.7.2
빠르고 통찰력이 높으며 사용자 정의가 가능한 Git 기록 분석.
개요 • 사용방법 • 설치 • 기여 • 라이센스
Hercules는 Go로 작성된 놀랍도록 빠르고 사용자 정의가 가능한 Git 저장소 분석 엔진입니다. 배터리가 포함되어 있습니다. go-git에 의해 구동됩니다.
공지 (2020년 11월): 주요 작성자가 림보에서 돌아와 점진적으로 개발을 재개하고 있습니다. 로드맵을 참조하세요.
명령줄 도구에는 hercules 와 labours 두 가지가 있습니다. 첫 번째는 Git 저장소를 가져와 전체 커밋 기록에 걸쳐 분석 작업의 DAG(방향성 비순환 그래프)를 실행하는 Go로 작성된 프로그램입니다. 두 번째는 수집된 데이터에 대해 사전 정의된 플롯을 보여주는 Python 스크립트입니다. 이 두 도구는 일반적으로 파이프를 통해 함께 사용됩니다. 플러그인 시스템을 사용하여 사용자 정의 분석을 작성할 수 있습니다. 조직에 관련된 여러 분석 결과를 함께 병합하는 것도 가능합니다. 분석된 커밋 내역에는 분기, 병합 등이 포함됩니다.
Hercules는 소스{d}의 여러 내부 프로젝트에 성공적으로 사용되었습니다. 블로그 게시물 1, 2 및 프레젠테이션이 있습니다. 테스트, 버그 수정, 새로운 분석 추가 또는 코딩을 통해 기여해 주세요!
Burndown 및 Couples의 DAG는 UAST diff Refining을 사용하여 분석합니다. 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
GitHub Marketplace에서 Hercules를 GitHub Action: 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 아카이브에 압축됩니다. 임베딩을 보려면 project.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 지정되지 않은 경우 다음 알고리즘을 통해 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 Projector의 torvalds/linux 파일 결합
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는 각 구조 단위가 몇 번이나 수정되었는지 측정할 수 있습니다. 기본적으로 함수를 살펴봅니다. 다른 것으로 전환하려면 Semantic 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>
우리는 각 개발자에 대해 하루에 얼마나 많은 커밋이 이루어졌는지, 라인이 추가, 제거 및 변경되었는지 기록합니다. 시간적 그룹화를 보여주기 위해 몇 가지 트릭을 사용하여 결과 커밋 시계열을 플롯합니다. 즉, 두 개의 인접한 커밋 시리즈는 정규화 후에 유사하게 보일 것입니다.
이 플롯을 통해 시간이 지남에 따라 개발 팀이 어떻게 진화했는지 확인할 수 있습니다. 또한 Hacktoberfest와 같은 "플래시몹 커밋"도 표시됩니다. 예를 들어, 위의 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은 전체 범위의 유니코드 문자를 지원하지 않으며 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 의 출력은 1.5GB이며 구문 분석하는 데 1시간/180GB 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 . OOM 직전에 최대 절전 모드를 시작하려면 이 두 숫자를 사용하세요.--burndown-hibernation-disk --burndown-hibernation-dir /path .--first-parent , 당신이 이겼습니다. src-d/go-git 에서 go-git/go-git 로 전환합니다. 최신 Go 버전과 호환되도록 코드베이스를 업그레이드하세요. 
