Задача
При написании технической документации является хорошим тоном включать секцию с историей изменений (т.н. Revision History). Как правило, сама документация также хранится в гите и имеет свою историю изменений, поэтому грех этим не воспользоваться, чтобы автоматизировать процесс.
Решение
Рассмотрим решение задачи на базе стандарта AsciiDoc, который в последнее время набирает всё большую популярность среди прогрессивно настроенных инженеров и причастных к их результатам деятельности тех.писателей.
Примем, что для истории ревизий нам необходима следующая информация:
- дата изменения
- имя автора изменения
- суть изменения
Для формирования таблицы с историей ревизий используем замечательную команду git log:
1 2 3 4 5 6 7 8 9 10 11 | $ git log --max-count=10 --no-merges --date=short --pretty=format:"| %ad | %an | %s" | 2017-04-05 | Dmitry Murzinov | [ipxact2verilog] minor changes | 2017-04-04 | Dmitry Murzinov | minor changes | 2017-04-04 | Dmitry Murzinov | First scatch for verilog CSR generator | 2017-04-03 | Dmitry Murzinov | Was added Make to build translate files (*.mo) for gettext | 2017-04-03 | Dmitry Murzinov | Was added multilingual support to AsciiDoc Register Overview table | 2017-04-03 | Dmitry Murzinov | First try to multilingual support | 2017-04-03 | Dmitry Murzinov | an AsciiDoc Register Overview table now data width independent | 2017-04-03 | Dmitry Murzinov | Was added dimension of fields for Regs Overview table | 2017-04-03 | Dmitry Murzinov | Ability to generate an AsciiDoc Register Overview table | 2017-04-03 | Dmitry Murzinov | Was added an example config file |
— как видим на выходе отличная заготовка для asciidoc-таблицы.
Подробнее об опциях команды:
- —max-count= — указываем желаемое число последних коммитов
- —branches= — если интересуют только конкретные ветки (например release/production), указываем тут
- —tags= — аналогично с тегами, можно задавать паттерн типа rev*.*, v?.?.? и т.п.
- —no-merges — не выводить в лог слияния веток
У меня установлен гит довольно старый (v1.8), в новых версиях появилась кудо более гибкая кастомизация даты. Тонкую настойку на славянский формат даты «19.2.2015» в новом гите можно осуществить следующей командой:
1 | git log -n 10 --date=format:'%d.%m.%Y' --pretty=format:"| %cd | %cn | %s" |
Также в зависимости от того хранится ли документация отдельно либо является частью репозитария СФ-блока будет различаться git log, возмодно потребуется указывать конкретный исходник документа или группу исходников, например:
1 | git log -n 10 --pretty=format:"| %ad | %an | %s" doc/src/IP-core.adoc |
или:
1 | git log -n 10 --pretty=format:"| %ad | %an | %s" doc/src/*.adoc |
Итоговый скрипт
Получившийся скрипт выглядит следующим образом:
1 2 3 4 5 6 7 | #!/bin/bash echo ".Revision History" > $1 echo "[cols=\"^2s,^8,^26\",options=\"header\"]" >> $1 echo "|===================================================" >> $1 echo "| Date | Author | Comments" >> $1 git log --max-count=10 --date=short --pretty=format:"| %ad | %an | %s" doc/src/*.adoc >> $1 echo "|===================================================" >> $1 |
Вызов скрипта:
1 | ./generate-revision-history.sh revhist.adoc |
В сборочном .adoc-файле включаем сгенерированный файл в соответствующую секцию:
1 2 3 4 5 | [abstract] == История изменений документа / Revision Changes include::revhist.adoc[leveloffset=+1] <<<< |
Также будет полезно добавить revhist.adoc в .gitignore (как файл, генерируемый автоматически); и в мейкфайл — как зависимость при сборке конечного PDF.