989d921f5d
I'm very pleased to announce the release of our new website and documentation using the new toolchain with Hugo and AsciiDoctor. To get more information about the new toolchain please read the FreeBSD Documentation Project Primer[1], Hugo docs[2] and AsciiDoctor docs[3]. Acknowledgment: Benedict Reuschling <bcr@> Glen Barber <gjb@> Hiroki Sato <hrs@> Li-Wen Hsu <lwhsu@> Sean Chittenden <seanc@> The FreeBSD Foundation [1] https://docs.FreeBSD.org/en/books/fdp-primer/ [2] https://gohugo.io/documentation/ [3] https://docs.asciidoctor.org/home/ Approved by: doceng, core
113 lines
5 KiB
Text
113 lines
5 KiB
Text
---
|
|
title: Chapter 3. The Working Copy
|
|
prev: books/fdp-primer/tools
|
|
next: books/fdp-primer/structure
|
|
---
|
|
|
|
[[working-copy]]
|
|
= The Working Copy
|
|
:doctype: book
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:icons: font
|
|
:sectnums:
|
|
:sectnumlevels: 6
|
|
:source-highlighter: rouge
|
|
:experimental:
|
|
:skip-front-matter:
|
|
:xrefstyle: basic
|
|
:relfileprefix: ../
|
|
:outfilesuffix:
|
|
:sectnumoffset: 3
|
|
|
|
toc::[]
|
|
|
|
The _working copy_ is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository.
|
|
|
|
A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats.
|
|
|
|
link:https://git-scm.com/[Git] is used to manage the FreeBSD documentation files. It is obtained by installing the Git package:
|
|
|
|
[source,bash]
|
|
....
|
|
# pkg install git-lite
|
|
....
|
|
|
|
[[working-copy-doc-and-src]]
|
|
== Documentation and Manual Pages
|
|
|
|
FreeBSD documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. Two repositories are involved: `doc` for the books and articles, and `src` for the operating system and manual pages. To edit manual pages, the `src` repository must be checked out separately.
|
|
|
|
Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called `main`.
|
|
|
|
[[working-copy-choosing-directory]]
|
|
== Choosing a Directory
|
|
|
|
FreeBSD documentation is traditionally stored in [.filename]#/usr/doc/#, and system source code with manual pages in [.filename]#/usr/src/#. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use [.filename]#~/doc# and [.filename]#~/src#, both subdirectories of the user's home directory.
|
|
|
|
[[working-copy-checking-out]]
|
|
== Checking Out a Copy
|
|
|
|
A download of a working copy from the repository is called a _clone_, and done with `git clone`. This example clones a copy of the latest version (`main`) of the main documentation tree:
|
|
|
|
[source,bash]
|
|
....
|
|
% git clone https://git.FreeBSD.org/doc.git ~/doc
|
|
....
|
|
|
|
A checkout of the source code to work on manual pages is very similar:
|
|
|
|
[source,bash]
|
|
....
|
|
% git clone https://git.FreeBSD.org/src.git ~/src
|
|
....
|
|
|
|
[[working-copy-updating]]
|
|
== Updating a Working Copy
|
|
|
|
The documents and files in the FreeBSD repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main FreeBSD repository. To update the local version with the changes that have been made to the main repository, use `git pull` on the directory containing the local working copy:
|
|
|
|
[source,bash]
|
|
....
|
|
% git pull ~/doc
|
|
....
|
|
|
|
Get in the protective habit of using `git pull` before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository.
|
|
|
|
[[working-copy-revert]]
|
|
== Reverting Changes
|
|
|
|
Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be "reset" to their unchanged form with `git restore`. For example, to erase the edits made to [.filename]#_index.adoc# and reset it to unmodified form:
|
|
|
|
[source,bash]
|
|
....
|
|
% git restore _index.adoc
|
|
....
|
|
|
|
[[working-copy-making-diff]]
|
|
== Making a Diff
|
|
|
|
After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These _diff_ files are produced by redirecting the output of `git diff` into a file:
|
|
|
|
[source,bash]
|
|
....
|
|
% cd ~/doc
|
|
% git diff doc-fix-spelling.diff
|
|
....
|
|
|
|
Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree.
|
|
|
|
If the diff file is to be submitted with the web "link:https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi[Submit a FreeBSD problem report]" interface, add a [.filename]#.txt# extension to give the earnest and simple-minded web form a clue that the contents are plain text.
|
|
|
|
Be careful: `git diff` includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included:
|
|
|
|
[source,bash]
|
|
....
|
|
% cd ~/doc
|
|
% git diff disks/_index.adoc printers/_index.adoc disks-printers.diff
|
|
....
|
|
|
|
[[working-copy-git-references]]
|
|
== Git References
|
|
|
|
These examples show very basic usage of Git. More detail is available in the https://git-scm.com/book/en/v2[Git Book] and the https://git-scm.com/doc[Git documentation].
|