Как проверить правки в Markdown через Git diff
Сравните две редакции инструкции, отделите изменения смысла от перевёрстки и оставьте проверяемый комментарий.
Два автора редактировали инструкцию по выдаче материалов перед занятием. В новой версии изменились отступы, ссылки и формулировка срока. При обычном чтении трудно заметить, что документ теперь предлагает выдать комплект после встречи вместо выдачи до неё. Сравнение версий показывает места, где изменился исходный текст. Предпросмотр помогает проверить, что получится у читателя. У этих проверок разные задачи, поэтому полезно делать обе.
Сравните две копии без репозитория
Возьмите два файла, например handout-before.md и handout-after.md. Положите их в отдельную рабочую папку и откройте в ней терминал. Если Git установлен, он умеет сравнить обычные файлы даже вне репозитория. Команда ниже читает указанные файлы и выводит различия. Перед запуском убедитесь, что старая редакция указана первой.
git diff --no-index -- handout-before.md handout-after.mdВ результате строки с минусом относятся к старой редакции, строки с плюсом к новой. Строки без такого знака показывают контекст. Заголовки с номерами помогают найти соответствующий фрагмент в файле. При сравнении через --no-index обнаруженные различия дают ненулевой код завершения, поэтому автоматизация должна различать найденные правки и ошибку запуска. Для ручной проверки достаточно посмотреть, что инструмент действительно прочитал обе редакции.
Сделайте простую пробу. В старом файле оставьте «Подготовить листы до начала занятия», а в новом замените «до» на «после». Откройте вывод и убедитесь, что изменение обнаружено. Затем отмените пробную замену вручную в копии. Если оба файла совпадают, различий содержимого быть не должно. Проба подтверждает, что вы сравниваете правильные пути и различаете направление правки.
Разберите смысл отдельно от переноса строк
Обычный вывод показывает изменённые строки. Если редактор переформатировал целый абзац, визуально может казаться, что он полностью переписан. Для прозы полезно дополнительно посмотреть изменения по словам. Обычный вывод тоже пригодится. Изменения отступов и пустых строк могут менять вложенность списка или границы блока.
git diff --no-index --word-diff=plain -- handout-before.md handout-after.mdРежим сравнения по словам выделит удалённые и добавленные части внутри строки. На плотном тексте удобно начать с него, затем вернуться к построчному режиму возле каждого заголовка, списка и примера кода. Знаки режима тоже могут встретиться в исходном документе, поэтому при неоднозначности откройте обе редакции непосредственно. Проверка основана на тексте, а не на цвете терминала. Она полезна и при передаче вывода в обычном сообщении.
Отдельно отнеситесь к невидимым изменениям. Пустая строка может отделять абзацы. Пробелы в начале строки могут влиять на структуру вложенного списка. Настройка сравнения, игнорирующая пробелы, уменьшает шум, но её нельзя использовать как единственный способ проверки Markdown. Сначала найдите смысловые правки, затем посмотрите формат в целевом предпросмотре.
Сверьте ссылки, заголовки и результат действия
Сначала проверьте, кто и когда выполняет изменённый шаг. Затем откройте обновлённые ссылки и вложения. Наконец, попробуйте выполнить новые команды в описанных условиях. Для примера с листами проверьте не только слово «после», но и следующий абзац. Если ученики должны делать пометки прямо во время встречи, новый срок меняет выполнимость инструкции.
Комментарии лучше оставлять рядом с конкретной правкой. Объясните, что новый срок выдачи листов расходится с третьим шагом, который требует заполнить их во время встречи. Попросите согласовать оба шага. Читателю комментария будет понятно, какой факт проверить. Если автор действительно изменил сценарий, он сможет ответить ссылкой на новое решение.
При работе в репозитории выясните, с чем сравнивается файл. Команда git diff -- path/to/guide.md показывает незаписанные в индекс изменения относительно индекса. Для уже добавленных в индекс правок используют git diff --staged -- path/to/guide.md. Если требуется сравнить опубликованную редакцию с текущей, заранее определите нужную точку истории. Слово «текущая» может означать рабочую копию, индекс или последний коммит.
Завершите проверку глазами читателя
Откройте новую редакцию в том редакторе или на том сайте, где её будут читать. Пройдите изменённые переходы и проверьте, что заголовки сохранили уровни, список остался списком, а ограждение кода закрыто. Если были обновлены команды, повторите безопасный пример на учебных данных. Проверка закончена, когда все правки смысла получили объяснение, изменённые ссылки открываются, а итоговая страница поддерживает прежний или явно обновлённый сценарий. Перевёрстку и смысловые правки в дальнейшем удобнее отправлять отдельными изменениями, если команда часто пересматривает длинные инструкции.
Добавьте проверку случайного переименования
В тестовой копии замените ссылку на схему ссылкой с другим именем файла. Найдите правку в сравнении и откройте новое назначение из готовой страницы. Если оба адреса существуют, сравните назначение по содержимому, потому что статус успешной загрузки не гарантирует правильную схему. Это особенно заметно при работе с файлами, которые различаются лишь датой. Зафиксируйте в комментарии, какой вариант требуется для действующего занятия. Так проверка включает смысл ссылки, а не только появление нового пути в выводе Git.