--- description: 'Как получить рабочую копию проекта документации FreeBSD' next: books/fdp-primer/structure params: path: /books/fdp-primer/working-copy/ prev: books/fdp-primer/tools showBookMenu: 'true' tags: ["working copy", "documentation", "manual pages", "git"] title: 'Глава 3. Рабочая копия' weight: 4 --- [[working-copy]] = Рабочая копия :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 3 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] _Рабочая копия_ — это копия дерева документации репозитория FreeBSD, загруженная на локальный компьютер. Изменения вносятся в локальную рабочую копию, тестируются, а затем отправляются в виде патчей для включения в основной репозиторий. Полная копия дерева документации может занимать 550 мегабайт дискового пространства. Рекомендуется выделить не менее гигабайта, чтобы было место для временных файлов и тестовых версий в различных выходных форматах. link:https://git-scm.com/[Git] используется для управления файлами документации FreeBSD. Он устанавливается через package:devel/git[], который также имеет облегчённую версию под названием git-lite: [source, shell] .... # pkg install git-lite .... [[working-copy-doc-and-src]] == Документация и Справочник Документация FreeBSD — это не только книги и статьи. Справочник (man) для всех команд и конфигурационных файлов также являются частью документации и входят в сферу ответственности FDP. Используются два репозитория: `doc` для книг и статей и `src` для операционной системы и справочника. Для редактирования справочника необходимо отдельно получить репозиторий `src`. Репозитории могут содержать несколько версий документации и исходного кода. Новые изменения почти всегда вносятся только в последнюю версию, называемую `main`. [[working-copy-choosing-directory]] == Выбор каталога Документация FreeBSD традиционно хранится в [.filename]#/usr/doc/#, а исходный код системы с руководствами — в [.filename]#/usr/src/#. Эти деревья каталогов могут быть перемещены, и пользователи могут разместить рабочие копии в других местах, чтобы избежать конфликтов с существующей информацией в основных каталогах. В следующих примерах используются [.filename]#~/doc# и [.filename]#~/src# — подкаталоги домашнего каталога пользователя. [[working-copy-checking-out]] == Извлечение копии Загрузка рабочей копии из репозитория называется _клоном_ и выполняется командой `git clone`. В этом примере клонируется последняя версия (`main`) основного дерева документации: [source, shell] .... % git clone https://git.FreeBSD.org/doc.git ~/doc .... Получение исходного кода для работы со справочником (man) выполняется аналогично: [source, shell] .... % git clone https://git.FreeBSD.org/src.git ~/src .... [[working-copy-updating]] == Обновление рабочей копии Документы и файлы в репозитории FreeBSD изменяются ежедневно. Пользователи вносят изменения в файлы и фиксируют их довольно часто. Даже спустя короткое время после первоначального получения копии репозитория, между локальной рабочей копией и основным репозиторием FreeBSD уже могут появиться различия. Чтобы обновить локальную версию с учётом изменений, внесённых в основной репозиторий, используйте команду `git pull` в каталоге с локальной рабочей копией: [source, shell] .... % cd ~/doc % git pull --ff-only .... Приучите себя к полезной привычке использовать `git pull` перед редактированием файлов документации. Кто-то другой мог недавно изменить этот файл, и ваша локальная рабочая копия не будет содержать последних изменений, пока вы не обновите её. Редактировать самую свежую версию файла гораздо проще, чем пытаться объединить более старую, отредактированную локальную версию с новой версией из репозитория. [[working-copy-revert]] == Отмена изменений Иногда оказывается, что изменения были не нужны, или автор просто хочет начать заново. Файлы можно «сбросить» к их исходному состоянию с помощью `git restore`. Например, чтобы отменить правки, сделанные в [.filename]#_index.adoc#, и вернуть его в исходное состояние: [source, shell] .... % git restore _index.adoc .... [[working-copy-making-diff]] == Создание Diff После завершения редактирования файла или группы файлов, различия между локальной рабочей копией и версией в репозитории FreeBSD должны быть собраны в один файл для отправки. Эти _diff_-файлы создаются путём перенаправления вывода команды `git diff` в файл: [source, shell] .... % cd ~/doc % git diff > doc-fix-spelling.diff .... Присвойте файлу осмысленное имя, отражающее его содержимое. В приведённом примере указаны исправления орфографии для всего дерева документации. Если файл с различиями должен быть отправлен через веб-интерфейс "link:https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi[Сообщить о проблеме в FreeBSD]", добавьте расширение [.filename]#.txt#, чтобы дать простой и прямолинейной веб-форме понять, что содержимое представляет собой обычный текст. Будьте осторожны: `git diff` включает все изменения в текущем каталоге и его подкаталогах. Если в рабочей копии есть файлы с правками, которые ещё не готовы к отправке, укажите список только тех файлов, которые нужно включить: [source, shell] .... % cd ~/doc % git diff disks/_index.adoc printers/_index.adoc > disks-printers.diff .... [[working-copy-git-references]] == Ссылки Git Эти примеры демонстрируют базовое использование Git. Более подробная информация доступна в https://git-scm.com/book/en/v2[Книге по Git] и https://git-scm.com/doc[документации Git].