hercules
v10.7.2
Быстрый, глубокий и легко настраиваемый анализ истории Git.
Обзор • Как использовать • Установка • Вклад • Лицензия
Hercules — это удивительно быстрый и легко настраиваемый механизм анализа репозитория Git, написанный на Go. Батарейки включены. Работает на Go-git.
Уведомление (ноябрь 2020 г.): основной автор вернулся из подвешенного состояния и постепенно возобновляет разработку. Посмотрите дорожную карту.
Существует два инструмента командной строки: hercules и labours . Первая — это программа, написанная на Go, которая использует репозиторий Git и выполняет направленный ациклический граф (DAG) задач анализа на протяжении всей истории коммитов. Второй — это скрипт Python, который показывает некоторые заранее определенные графики на основе собранных данных. Эти два инструмента обычно используются вместе через трубу. Можно писать собственные анализы с помощью системы плагинов. Также возможно объединить несколько результатов анализа вместе, что актуально для организаций. Анализируемая история коммитов включает в себя ветки, слияния и т. д.
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 за 1ч 40мин.
Загрузите двоичный файл hercules со страницы «Релизы». labours можно установить из PyPi:
pip3 install labours
pip3 — менеджер пакетов Python.
Numpy и Scipy можно установить в Windows, используя http://www.lfd.uci.edu/~gohlke/pythonlibs/.
Вам понадобятся Go (>= v1.11) и protoc .
git clone https://github.com/src-d/hercules && cd hercules
make
pip3 install -e ./python
Hercules можно запустить как действие GitHub: Hercules на 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 . Поскольку упаковать несколько файлов в один артефакт на данный момент невозможно, все диаграммы и файлы 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 , он должен указывать на текстовый файл с пользовательскими идентификаторами. Формат: каждая строка соответствует одному разработчику, содержит все совпадающие адреса электронной почты и имена, разделенные | . Случай игнорируется.
20 лучших разработчиков Wireshark — перезаписывает матрицу
hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m overwrites-matrix
Помимо информации о выгорании, --burndown-people собирает статистику добавленных и удаленных строк по каждому разработчику. Таким образом, можно визуализировать, сколько строк, написанных разработчиком А, удалено разработчиком Б. Это указывает на сотрудничество между людьми и определяет экспертные группы.
Формат — матрица с N строками и (N+2) столбцами, где N — количество разработчиков.
--people-dict не указан, всегда 0). Последовательность разработчиков хранится в узле people_sequence YAML.
20 лучших разработчиков Ember.js – владение кодом
hercules --burndown --burndown-people [--people-dict=/path/to/identities]
labours -m ownership
--burndown-people также позволяет отображать долю кода через график областей с накоплением времени. То есть, сколько строк активно в выбранные моменты времени для каждого идентифицированного разработчика.
Связь файлов Torvalds/Linux в проекторе Tensorflow
hercules --couples [--people-dict=/path/to/identities]
labours -m couples -o <name> [--couples-tmp-dir=/tmp]
Важно : для этого требуется установка Tensorflow, следуйте официальным инструкциям.
Файлы связаны, если они были изменены в одном коммите. Разработчики связаны, если они меняют один и тот же файл. hercules записывает количество пар за всю историю коммитов и выводит две соответствующие матрицы совпадения. Затем labours тренируют вложения Swivel — плотные векторы, которые отражают вероятность совместного появления через евклидово расстояние. Для обучения требуется работающая установка Tensorflow. Промежуточные файлы хранятся во временном системном каталоге или --couples-tmp-dir если он указан. Обученные внедрения записываются в текущий рабочий каталог с именем, зависящим от -o . Выходной формат — TSV и соответствует проектору Tensorflow, поэтому файлы и людей можно визуализировать с помощью t-SNE, реализованного в TF Projector.
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>
Мы фиксируем количество сделанных коммитов, а также добавленных, удаленных и измененных строк в день для каждого разработчика. Мы строим итоговый временной ряд коммитов, используя несколько приемов, чтобы показать временную группировку. Другими словами, две соседние серии коммитов после нормализации должны выглядеть одинаково.
Этот сюжет позволяет узнать, как команда разработчиков развивалась с течением времени. Здесь также показаны «флешмобы-совершения», такие как 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 стороне может создавать исключения. Отфильтруйте вывод hercules через fix_yaml_unicode.py чтобы отбросить такие оскорбительные символы.
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 активирует растянутый макет Burndown.
Всю информацию, необходимую для построения графиков, можно вывести в формате JSON. Просто добавьте .json к выходным данным ( -o ), и все готово. Формат данных не определен полностью и зависит от кода Python, который его генерирует. Каждый файл JSON должен содержать "type" , отражающий тип графика.
--first-parent в качестве обходного пути.hercules для ядра Linux в режиме «пары» составляет 1,5 ГБ и требует более часа / 180 ГБ ОЗУ для анализа. Однако большинство репозиториев анализируются в течение минуты. Вместо этого попробуйте использовать протокольные буферы ( 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. 
