The Working CopyThe working copy is a copy of the &os;
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.Subversion
is used to manage the &os; documentation files. It is obtained by
installing the Subversion
package:&prompt.root; pkg install subversionDocumentation and Manual Pages&os; 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
base for the operating system and manual
pages. To edit manual pages, the base
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 head.Choosing a Directory&os; documentation is traditionally stored in
/usr/doc/, and system
source code with manual pages in
/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 ~/doc
and ~/src, both
subdirectories of the user's home directory.Checking Out a CopyA download of a working copy from the repository is called
a checkout, and done with
svn checkout. This example checks out a
copy of the latest version (head) of
the main documentation tree:&prompt.user; svn checkout https://svn.FreeBSD.org/doc/head ~/docA checkout of the source code to work on manual pages is
very similar:&prompt.user; svn checkout https://svn.FreeBSD.org/base/head ~/srcUpdating a Working CopyThe documents and files in the &os; 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 &os;
repository. To update the local version with the changes that
have been made to the main repository, use
svn update on the directory containing the
local working copy:&prompt.user; svn update ~/docGet in the protective habit of using
svn update 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.Reverting ChangesSometimes 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
svn revert. For example, to erase the edits
made to chapter.xml and reset it to
unmodified form:&prompt.user; svn revert chapter.xmlMaking a DiffAfter edits to a file or group of files are completed, the
differences between the local working copy and the version on
the &os; repository must be collected into a single file for
submission. These diff files are produced
by redirecting the output of svn diff into a
file:&prompt.user; cd ~/doc
&prompt.user; svn diff > doc-fix-spelling.diffGive 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
Submit
a &os; problem report interface, add a
.txt extension to give the earnest and
simple-minded web form a clue that the contents are plain
text.Be careful: svn 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:&prompt.user; cd ~/doc
&prompt.user; svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diffSubversion ReferencesThese examples show very basic usage of
Subversion. More detail is available
in the Subversion
Book and the Subversion
documentation.