mirror of https://git.FreeBSD.org/doc.git
137 lines
5.1 KiB
Plaintext
137 lines
5.1 KiB
Plaintext
---
|
|
title: Chapter 3. The Working Copy
|
|
prev: books/fdp-primer/tools
|
|
next: books/fdp-primer/structure
|
|
description: How to get a working copy of the FreeBSD Documentation Project
|
|
---
|
|
|
|
[[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 550 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,shell]
|
|
....
|
|
# 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,shell]
|
|
....
|
|
% git clone https://git.FreeBSD.org/doc.git ~/doc
|
|
....
|
|
|
|
A checkout of the source code to work on manual pages is very similar:
|
|
|
|
[source,shell]
|
|
....
|
|
% 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,shell]
|
|
....
|
|
% cd ~/doc
|
|
% git pull --ff-only
|
|
....
|
|
|
|
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,shell]
|
|
....
|
|
% 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,shell]
|
|
....
|
|
% 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,shell]
|
|
....
|
|
% 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].
|