Skip to main content

Автовставка истории изменений в техническую документацию на AsciiDoc

Задача

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

Решение

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

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

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

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

— как видим на выходе отличная заготовка для asciidoc-таблицы.

Подробнее об опциях команды:

  • —max-count= — указываем желаемое число последних коммитов
  • —branches= — если интересуют только конкретные ветки (например release/production), указываем тут
  • —tags= — аналогично с тегами, можно задавать паттерн типа rev*.*, v?.?.? и т.п.
  • —no-merges — не выводить в лог слияния веток

У меня установлен гит довольно старый (v1.8), в новых версиях появилась кудо более гибкая кастомизация даты. Тонкую настойку на славянский формат даты «19.2.2015» в новом гите можно осуществить следующей командой:

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

или: 

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

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

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

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

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

 

 

читать...

git: советы и шпаргалки

Начальная настройка окружения

Задать имя пользователя и почтовый адрес для текущего репозитария:

Выполнение этой команды эквивалентно редактированию строк файла .git/config:

Тоже самое глобально для всех будущих репозитариев:

Для удобства работы можно задать короткие псевдонимы команд, например:

По умолчанию git использует стандартный редактор вашей системы, которым обычно является vim. Если вы хотите использовать другой текстовый редактор, например, joe, проделайте следующее:

Проверить используемую конфигурацию командой:

Также можете проверить значение конкретного ключа, выполнив git config <key>, например:

Вывести лог коммитов в формате «Дата Автор»:

Использовать цветной вывод в терминале:

Выводить в логе коммит на одной строке:

Интерактивный способ добавления в индекс:

Помощь по использованию команд git можно получить следующими способами:

или:

 

Мнение о настройке окончания строк исходников

(далее…)

читать...