Получение хорошей информации о Git из Hugo

Читая сообщения в блогах других пользователей генератора статических сайтов (SSG), я иногда вижу, что в сообщении есть ссылка на конкретный Git-коммит для последнего обновления этого сообщения. В этом посте я покажу вам, как сделать это на сайте Hugo, на случай, если вы захотите сделать то же самое. В качестве дополнительного преимущества, это позволит автоматизировать то, что вы, возможно, до сих пор делали вручную.

Идея возникла у меня вчера, когда я увидел сообщение Александра Оганесяна. В нем он дал прекрасное руководство по отображению этих данных на страницах, построенных с помощью Eleventy SSG. Метод Оганесяна использовал JavaScript для получения необходимых данных Git для использования шаблонами Eleventy.

С другой стороны: с сайтом на Hugo все гораздо проще, благодаря встроенным информационным переменным Git. Как только вы настроите Hugo на получение этих переменных, они станут доступны из объекта .GitInfo.

В конфигурационном файле проекта установите enableGitInfo в true (здесь я показываю значение TOML по умолчанию в Hugo, хотя мой собственный конфигурационный файл на самом деле YAML):

enableGitInfo = true

Как следует из названия настройки, это активирует присутствие информационных переменных Git.

Я скоро перейду к тому, что касается отображения информации о коммите, но сначала давайте отметим, что создание этой настройки, возможно, только что освободило вас от обязанности придираться к тому, как вы отображаете даты своих сообщений. Если вы использовали ручные записи во фронтменте ваших постов, чтобы указать, когда они были в последний раз изменены, вам больше не нужно этого делать. Git info по умолчанию предоставляет эти данные в виде .Lastmod.¹

Однако есть одна загвоздка, если вы используете GitHub Action для развертывания сайта на выбранном хосте, как это делаю я в последнее время. Проблема в том, что, хотя эти автоматические указания .Lastmod будут правильными при локальной разработке на hugo server, все они будут принимать текущую дату при развертывании. К счастью, есть объяснение и решение, из потока² на форуме Hugo Discourse:

По умолчанию действие GitHub «checkout» извлекает только один коммит (для ref/SHA, который вызвал рабочий процесс). Это приводит к описанному вами поведению — т.е.[,] для .Lastmod используется текущая дата/время.

Если вы измените действие checkout, чтобы получить всю историю (указав fetch-depth: 0), то .GitInfo и .Lastmod [работают] как и ожидалось[.]

[стилистические правки и одна ссылка применены.]

Найдя этот ответ, я просто добавил раздел with в шаг Checkout default branch моего GitHub Action:

      - name: Checkout default branch
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

. … и, действительно, это устранило проблему.

Кстати: Я проверяю, совпадают ли день первоначальной публикации сообщения и день его «последнего изменения» — например, когда я исправляю опечатку или иным образом редактирую что-то в тот же день, когда я впервые опубликовал сообщение — и, если это так, я показываю только листинг «original-pub», чтобы избежать дублирования. Однако это требует сравнения форматированных дат, поскольку полные временные метки никогда не могут быть одинаковыми с точностью до наносекунды; поэтому это делается в каждом соответствующем шаблоне:

<p>
  <strong>{{ .PublishDate.Format "January 2, 2006" }}</strong><br />
  {{- if ne (.PublishDate.Format "January 2, 2006") (.Lastmod.Format "January 2, 2006") }}
    Last modified {{ .Lastmod.Format "January 2, 2006" }}
  {{- else -}}
    &nbsp;
  {{- end -}}
</p>

Внутри абзаца, если они не равны (ne), я показываю сообщение «Last modified»; в противном случае я просто ставлю пробел без разрыва, чтобы высота строки была одинаковой.

Это позаботится о Git-информации для дат; но что насчет первоначальной темы этого сообщения, а именно, как можно сделать ссылку на самый последний Git-коммит страницы?

Ну, объект .GitInfo также предоставляет две переменные для хэша каждого коммита: полный хэш (.Hash) и более знакомый сокращенный хэш (.AbbreviatedHash). Добавить их в соответствующие шаблоны довольно просто. В моем случае я отображаю .AbbreviatedHash, а ссылка — это моя ссылка на репозиторий плюс /commit/ плюс .Hash:

<p>
  {{- if $.GitInfo -}}
    <strong>Latest commit</strong>: <a href="https://github.com/brycewray/hugo_site/commit/{{ .GitInfo.Hash }}" target="_blank" rel="noopener">{{ .GitInfo.AbbreviatedHash }}</a>
  {{- else -}}
    &nbsp;
  {{- end -}}
</p>

(Условие if $.GitInfo предотвращает ошибки hugo server во время локальной разработки, пока вы работаете над содержимым, которое еще не зафиксировали.³ За этот ответ вы можете поблагодарить другой ответ на форуме Hugo Discourse).

Итак, теперь вы автоматизировали как (а) отображение этого Lastmod материала, так и (б) ссылку на коммит, из которого взята последняя версия каждой страницы. При этом вам не потребовалось никаких дополнительных инструментов и совсем немного дополнительного кода. Неплохо для нескольких минут работы в Hugo, не так ли?

Обновление, 2022-10-07: Если вы заинтересованы в отображении как постраничной Git-информации, так и Git-информации всего сайта на вашем сайте Hugo, ознакомьтесь с решением, предложенным экспертом/соавтором Hugo Джо Мурингом. Спасибо Rodrigo Alcaraz de la Osa за сессию Q&A, которая навела меня на эту дополнительную информацию!

1. По умолчанию Hugo будет отдавать приоритет информационной переменной Git .Lastmod по сравнению с другими возможностями — включая любые ручные записи Lastmod, которые вы, возможно, уже предоставили в первой части вашего контента. 

2. Оригинальный вопрос датирован 25 декабря 2019 года, но прошло еще 21 месяц, прежде чем появился ответ, тем более ответ. Jeeeez. 

3. Причина, по которой вам не нужно делать это с ранее упомянутым отображением дат, заключается в том, что в этом случае мы просто используем Lastmod (переменная, которую Hugo уже знает), а не, в частности, .GitInfo.Lastmod, отсутствие которой на данной странице доставляет Hugo неудобства.