Глава 3. Рабочая копия

Документация FreeBSD — это не только книги и статьи. Справочник (man) для всех команд и конфигурационных файлов также являются частью документации и входят в сферу ответственности FDP. Используются два репозитория: doc для книг и статей и src для операционной системы и справочника. Для редактирования справочника необходимо отдельно получить репозиторий src.

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

Документация FreeBSD традиционно хранится в /usr/doc/, а исходный код системы с руководствами — в /usr/src/. Эти деревья каталогов могут быть перемещены, и пользователи могут разместить рабочие копии в других местах, чтобы избежать конфликтов с существующей информацией в основных каталогах. В следующих примерах используются ~/doc и ~/src — подкаталоги домашнего каталога пользователя.

Загрузка рабочей копии из репозитория называется клоном и выполняется командой git clone. В этом примере клонируется последняя версия (main) основного дерева документации:

Получение исходного кода для работы со справочником (man) выполняется аналогично:

Документы и файлы в репозитории FreeBSD изменяются ежедневно. Пользователи вносят изменения в файлы и фиксируют их довольно часто. Даже спустя короткое время после первоначального получения копии репозитория, между локальной рабочей копией и основным репозиторием FreeBSD уже могут появиться различия. Чтобы обновить локальную версию с учетом изменений, внесённых в основной репозиторий, используйте команду git pull в каталоге с локальной рабочей копией:

Приучите себя к полезной привычке использовать git pull перед редактированием файлов документации. Кто-то другой мог недавно изменить этот файл, и ваша локальная рабочая копия не будет содержать последних изменений, пока вы не обновите её. Редактировать самую свежую версию файла гораздо проще, чем пытаться объединить более старую, отредактированную локальную версию с новой версией из репозитория.

Иногда оказывается, что изменения были не нужны, или автор просто хочет начать заново. Файлы можно «сбросить» к их исходному состоянию с помощью git restore. Например, чтобы отменить правки, сделанные в _index.adoc, и вернуть его в исходное состояние:

После завершения редактирования файла или группы файлов, различия между локальной рабочей копией и версией в репозитории FreeBSD должны быть собраны в один файл для отправки. Эти diff-файлы создаются путём перенаправления вывода команды git diff в файл:

Присвойте файлу осмысленное имя, отражающее его содержимое. В приведенном примере указаны исправления орфографии для всего дерева документации.

Если файл с различиями должен быть отправлен через веб-интерфейс "Сообщить о проблеме в FreeBSD", добавьте расширение .txt, чтобы дать простой и прямолинейной веб-форме понять, что содержимое представляет собой обычный текст.

Будьте осторожны: git diff включает все изменения в текущем каталоге и его подкаталогах. Если в рабочей копии есть файлы с правками, которые ещё не готовы к отправке, укажите список только тех файлов, которые нужно включить:

Эти примеры демонстрируют базовое использование Git. Более подробная информация доступна в Книге по Git и документации Git.