_index.adoc

---
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].