Задача

При написании технической документации является хорошим тоном включать секцию с историей изменений (т.н. Revision History). Как правило, сама документация также хранится в гите и имеет свою историю изменений, поэтому грех этим не воспользоваться, чтобы автоматизировать процесс.

Решение

Рассмотрим решение задачи на базе стандарта AsciiDoc, который в последнее время набирает всё большую популярность среди прогрессивно настроенных инженеров и причастных к их результатам деятельности тех.писателей.

Примем, что для истории ревизий нам необходима следующая информация:

• дата изменения
• имя автора изменения
• суть изменения

Для формирования таблицы с историей ревизий используем замечательную команду git log:

$ 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” в новом гите можно осуществить следующей командой:

git log -n 10 --date=format:'%d.%m.%Y' --pretty=format:"| %cd | %cn | %s" 

Также в зависимости от того хранится ли документация отдельно либо является частью репозитария СФ-блока будет различаться git log, возмодно потребуется указывать конкретный исходник документа или группу исходников, например:

git log -n 10 --pretty=format:"| %ad | %an | %s"  doc/src/IP-core.adoc

или: 

git log -n 10 --pretty=format:"| %ad | %an | %s"  doc/src/*.adoc

Итоговый скрипт

Получившийся скрипт выглядит следующим образом:

#!/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

Вызов скрипта: 

./generate-revision-history.sh revhist.adoc

В сборочном .adoc-файле включаем сгенерированный файл в соответствующую секцию: 

[abstract]
== История изменений документа / Revision Changes

include::revhist.adoc[leveloffset=+1]
<<<<

Также будет полезно добавить revhist.adoc в .gitignore (как файл, генерируемый автоматически); и в мейкфайл - как зависимость при сборке конечного PDF.