[PATCH] Review: patches through chapter 2
Eric Hanchrow
offby1 at blarg.net
Fri Mar 16 13:49:39 CDT 2007
This is a bazillion different changes; I'm reading the book start to
finish and whining^Wmaking constructive suggestions about anything and
everything.
Index: tools/svnbook.el
===================================================================
--- tools/svnbook.el (revision 2735)
+++ tools/svnbook.el (working copy)
@@ -42,7 +42,9 @@
(replace-match ">" nil t))
)))
-
+(when (not (boundp 'sgml-catalog-files))
+ (setq sgml-catalog-files '()))
+(add-to-list 'sgml-catalog-files '("/usr/local/prod/sgml/dblite/catalog") t)
(setq sgml-omittag-transparent t
sgml-trace-entity-lookup nil
sgml-live-element-indicator t
@@ -52,7 +54,6 @@
;; NOTE: I removed the -u from sgml-validate-command to get rid of stupid errors in the DTDs. -Fitz
sgml-set-face t
sgml-mode-hook (quote (auto-fill-mode))
- sgml-catalog-files (append sgml-catalog-files '("/usr/local/prod/sgml/dblite/catalog"))
sgml-auto-activate-dtd t)
Index: en/HACKING
===================================================================
--- en/HACKING (revision 2735)
+++ en/HACKING (working copy)
@@ -1,5 +1,5 @@
This style guide is intended to be *an addition to* the O'Reilly and
-Associates style guide at http://www.ora.com/oreilly/author/stylesheet.html
+Associates style guide at http://www.oreilly.com/oreilly/author/stylesheet.html
===========================================================================
Index: en/book/appc-webdav.xml
===================================================================
--- en/book/appc-webdav.xml (revision 2735)
+++ en/book/appc-webdav.xml (working copy)
@@ -238,7 +238,7 @@
<para>The original WebDAV standard has been widely successful.
Every modern computer operating system has a general WebDAV
client built-in (details to follow), and a number of popular
- standalone applications are also able to speak WebDAV —
+ standalone applications are also able to speak WebDAV—
Microsoft Office, Dreamweaver, and Photoshop to name a few. On
the server end, the Apache webserver has been able to provide
WebDAV services since 1998 and is considered the de-facto
Index: en/book/ch00-preface.xml
===================================================================
--- en/book/ch00-preface.xml (revision 2735)
+++ en/book/ch00-preface.xml (working copy)
@@ -37,6 +37,7 @@
flexible. And for the most part, almost all newly-started
open-source projects now choose Subversion instead of CVS.</para>
+ <!-- Just 1.4? Not 1.5, 1.6, and so on? -->
<para>This book is written to document the 1.4 series of the
Subversion version control system. We have made every attempt to
be thorough in our coverage. However, Subversion has a thriving
@@ -57,11 +58,11 @@
use Subversion to manage their data. While Subversion runs on a
number of different operating systems, its primary user
interface is command-line based. That command-line tool
- (<command>svn</command>) and auxiliary program are the focus of
+ (<command>svn</command>), and some auxiliary programs, are the focus of
this book.</para>
<para>For consistency, the examples in this book assume the reader
- is using a Unix-like operating system and relatively comfortable
+ is using a Unix-like operating system, and is relatively comfortable
with Unix and command-line interfaces. That said, the
<command>svn</command> program also runs on non-Unix platforms
like Microsoft Windows. With a few minor exceptions, such as
@@ -145,7 +146,7 @@
learn how to do more advanced things with Subversion, such
as how to use branches and perform merges (<xref
linkend="svn.branchmerge"/>), how to use Subversion's
- property support ((<xref linkend="svn.advanced"/>), how to
+ property support (<xref linkend="svn.advanced"/>), how to
configure runtime options (<xref
linkend="svn.customization"/>), and other things. These
chapters aren't critical at first, but be sure to read
@@ -303,7 +304,7 @@
<term><xref linkend="svn.serverconfig"/></term>
<listitem>
<para>Explains how to configure your Subversion server and
- the three ways to access your repository:
+ the ways to access your repository, including:
<literal>HTTP</literal>, the <literal>svn</literal>
protocol, and local disk access. It also covers the details
of authentication, authorization and anonymous
@@ -421,6 +422,7 @@
<para>The online home of this book's development and most of the
volunteer-driven translation efforts around it is <ulink
url="http://svnbook.red-bean.com"/>. There, you can find links
+ <!-- what's the difference between a "snapshot" and a "tagged version"? -->
to the latest snapshots and tagged versions of the book in
various formats, as well as instructions for accessing the
book's Subversion repository (where lives its DocBook XML source
@@ -580,7 +582,11 @@
<title>What is Subversion?</title>
- <para>Subversion is a free/open-source version control system.
+ <!-- I'd like to set off the phrase "version control system"
+ somehow, because the next sentence talks _only_ about it, and not
+ about the phrase "free/open-source". But I'm not sure how to do
+ that while conforming to this document's standard style. -->
+ <para>Subversion is a free/open-source <firstterm>version control system</firstterm>.
That is, Subversion manages files and directories, and the
changes made to them, over time. This allows you to recover
older versions of your data, or examine the history of how your
@@ -591,6 +597,7 @@
be used by people on different computers. At some level, the
ability for various people to modify and manage the same set of
data from their respective locations fosters collaboration.
+ <!-- it's not clear to me what "conduit" we're referring to -->
Progress can occur more quickly without a single conduit through
which all modifications must occur. And because the work is
versioned, you need not fear that quality is the trade-off for
Index: en/book/ch03-advanced-topics.xml
===================================================================
--- en/book/ch03-advanced-topics.xml (revision 2735)
+++ en/book/ch03-advanced-topics.xml (working copy)
@@ -926,7 +926,7 @@
it, this RFC describes the concept of media types and
subtypes, and recommends a syntax for the representation of
those types. Today, MIME media types—or, MIME
- types— are used almost universally across e-mail
+ types—are used almost universally across e-mail
applications, Web servers, and other software as the de
facto mechanism for clearing up the file content
confusion.</para>
@@ -2593,7 +2593,7 @@
to give the project a name.
<footnote>
<para><quote>You're not supposed to name it. Once you name it,
- you start getting attached to it.</quote> — Mike
+ you start getting attached to it.</quote>—Mike
Wazowski</para>
</footnote>
Let's say you called your software Frabnaggilywort. At this
Index: en/book/ch05-repository-admin.xml
===================================================================
--- en/book/ch05-repository-admin.xml (revision 2735)
+++ en/book/ch05-repository-admin.xml (working copy)
@@ -419,7 +419,7 @@
however, assumes that the reader is thinking
<quote>eff-ess-eff-ess</quote>.)</para>
</footnote>
- —a versioned filesystem implementation that uses the
+ —a versioned filesystem implementation that uses the
native OS filesystem to store data.</para>
<para><xref linkend="svn.reposadmin.basics.backends.tbl-1" />
Index: en/book/ch01-fundamental-concepts.xml
===================================================================
--- en/book/ch01-fundamental-concepts.xml (revision 2735)
+++ en/book/ch01-fundamental-concepts.xml (working copy)
@@ -1,3 +1,13 @@
+<!-- note that when I say "on IRC", I mean "on the #svn channel on
+irc.freenode.org" -->
+
+<!-- a general note: we're using the word "merge" in two somewhat
+ different ways. One way describes what happens when we "svn up" a
+ file that has uncommitted changes; the other way of course describes
+ what happens when we do "svn merge". I fear this may confuse
+ people. Naturally I can't think of how to alleviate that confusion
+ :-| -->
+
<chapter id="svn.basic">
<title>Fundamental Concepts</title>
@@ -54,6 +64,7 @@
was the last person to change this file, and what changes did
he make?</quote> These are the sorts of questions that are at
the heart of any <firstterm>version control system</firstterm>:
+ <!-- isn't "record and track" redundant? :-) -->
systems that are designed to record and track changes to data
over time.
</para>
@@ -187,6 +198,7 @@
<sect2 id="svn.basic.vsn-models.copy-merge">
<title>The Copy-Modify-Merge Solution</title>
+ <!-- I'd say "most other version control systems" -->
<para>Subversion, CVS, and a number of other version control
systems use a <firstterm>copy-modify-merge</firstterm> model as an
alternative to locking. In this model, each user's client
@@ -207,6 +219,10 @@
later, the repository informs him that his file A is
<firstterm>out-of-date</firstterm>. In other words, that file
A in the repository has somehow changed since he last copied
+ <!-- I fear that using the term "merge" here might lead
+ newbies to think that they should type "svn merge" in this
+ situation, which of course isn't the case: they instead need
+ to type "svn up". -->
it. So Harry asks his client to <firstterm>merge</firstterm>
any new changes from the repository into his working copy of
file A. Chances are that Sally's changes don't overlap with
@@ -252,6 +268,9 @@
communication. When users communicate poorly, both syntactic
and semantic conflicts increase. No system can force users to
communicate perfectly, and no system can detect semantic
+ <!-- one isn't lulled "into a promise"; I'd say "lulled into a
+ false sense of security that ..." or "lulled into thinking
+ that ..." -->
conflicts. So there's no point in being lulled into a false
promise that a locking system will somehow prevent conflicts;
in practice, locking seems to inhibit productivity more than
@@ -277,7 +296,7 @@
<para>While Subversion is still primarily a copy-modify-merge
system, it still recognizes the need to lock an occasional
- file ands provide mechanisms for this. This feature is
+ file, and thus provide mechanisms for this. This feature is
discussed later in this book, in
<xref linkend="svn.advanced.locking"/>.</para>
@@ -332,6 +351,7 @@
Windows platforms will need to use an unofficially
<quote>standard</quote> syntax for accessing repositories
that are on the same machine, but on a different drive than
+ <!-- file://localhost/X:/path/to/repos works too -->
the client's current working drive. Either of the two
following URL path syntaxes will work where
<literal>X</literal> is the drive on which the repository
@@ -362,7 +382,11 @@
filesystem.</para>
</note>
- <para>Finally, it should be noted that the Subversion client will
+ <!-- isn't this behavior dependent upon the various LC_
+ environment variables? If so, might it be useful to include a
+ footnote that says so, and points to the section that explains
+ in detail? -->
+ <para>Finally, the Subversion client will
automatically encode URLs as necessary, just like a web browser
does. For example, if a URL contains a space or upper-ASCII
character:</para>
@@ -457,6 +481,8 @@
Makefile integer.c button.c .svn/
</screen>
+ <!-- maybe instead, say "The letter A's in the left margin", and
+ perhaps emphasize the letter "a" in the word "adding" -->
<para>The list of letter A's indicates that Subversion is adding
a number of items to your working copy. You now have a
personal copy of the repository's <filename>/calc</filename>
@@ -465,6 +491,9 @@
extra information needed by Subversion, as mentioned
earlier.</para>
+ <!-- this sidebar seems a tad out of place. Might not a
+ better place for it be the end of svn.basic.in-action, where we
+ already talked about URLs in some detail? -->
<sidebar id="svn.basic.in-action.wc.sb-1">
<title>Repository URLs</title>
@@ -488,6 +517,8 @@
</thead>
<tbody>
<row>
+ <!-- should this be 'file://' instead - i.e., two
+ slashes instead of three? Nit-picky, I admit. -->
<entry><literal>file:///</literal></entry>
<entry>direct repository access (on local disk)</entry>
</row>
@@ -508,6 +539,13 @@
</row>
<row>
<entry><literal>svn+ssh://</literal></entry>
+ <!-- svn+ssh:// isn't as similar to svn:// as https://
+ is to http://. People on IRC are occasionally
+ suprised to learn that svn+ssh does _not_ contact a
+ daemon, but instead starts up its own "one-shot"
+ svnserve process. This statement might further that
+ confusion. Naturally I can't think of any way to
+ improve it that is short enough :-| -->
<entry>same as <literal>svn://</literal>, but through
an SSH tunnel.</entry>
</row>
@@ -525,7 +563,7 @@
<para>Suppose you make changes to <filename>button.c</filename>.
Since the <filename>.svn</filename> directory remembers the
- file's modification date and original contents, Subversion can
+ file's original modification date and contents, Subversion can
tell that you've changed the file. However, Subversion does
not make your changes public until you explicitly tell it to.
The act of publishing your changes is more commonly known as
@@ -556,6 +594,9 @@
unchanged; Subversion only modifies working copies at the
user's request.</para>
+ <!-- if, above, you still refer to this process as "merging",
+ then it would be good to say something like "this is the
+ 'merging' step we referred to above" -->
<para>To bring her project up to date, Sally can ask
Subversion to <firstterm>update</firstterm> her working copy,
by using the Subversion <command>update</command> command.
@@ -582,7 +623,10 @@
in the <filename>.svn</filename> directory, and further
information in the repository, to decide which files need to
be brought up to date.</para>
-
+ <!-- this probably isn't the place, but you might want to
+ mention that this process doesn't send any more information
+ over the network than needed. People on IRC occasionally ask
+ about this. -->
</sect2>
@@ -593,9 +637,11 @@
<para>An <command>svn commit</command> operation publishes
changes to any number of files and directories as a single
atomic transaction. In your working copy, you can change
- files' contents, create, delete, rename and copy files and
- directories, and then commit a complete set of changes as an
+ files' contents; create, delete, rename and copy files and
+ directories; and then commit a complete set of changes as an
atomic transaction.</para>
+ <!-- might we mention properties here too? They're another type
+ of change that can be made. -->
<para>By <quote>atomic transaction</quote>, we mean simply this:
either all of the changes happen in the repository, or none of
@@ -715,6 +761,10 @@
</listitem>
</itemizedlist>
+ <!-- It's not clear to me if subversion looks at any other
+ information, in particular, the file's size or contents. It
+ might be worthwhile mentioning such other tests, if they
+ exist. -->
<para>Given this information, by talking to the repository,
Subversion can tell which of the following four states a
working file is in:</para>
@@ -774,6 +824,12 @@
changes. If Subversion can't complete the merge in a
plausible way automatically, it leaves it to the user to
resolve the conflict.</para>
+ <!-- at some point it might be worth mentioning that if,
+ by coincidence, the local changes match those on the
+ server, not only will the merge succeed, but the file
+ will suddenly appear to be not modified. This is of
+ course correct behavior, but I suspect it might surprise
+ some people. -->
</listitem>
</varlistentry>
</variablelist>
@@ -892,7 +948,7 @@
contained in a subdirectory, or perhaps you'd like to figure
out when a bug first came into existence in a specific file.
This is the <quote>time machine</quote> aspect of a version
- control system — the feature which allows you to move
+ control system—the feature which allows you to move
any portion of your working copy forward and backward in
history.</para>
Index: en/book/ch06-server-configuration.xml
===================================================================
--- en/book/ch06-server-configuration.xml (revision 2735)
+++ en/book/ch06-server-configuration.xml (working copy)
@@ -409,7 +409,7 @@
<xref linkend="svn.serverconfig.multimethod"/>.) Note
that this is also one of the reasons we warn against
accessing repositories via <literal>svn+ssh://</literal>
- URLs — from a security standpoint, it's effectively
+ URLs—from a security standpoint, it's effectively
the same as local users accessing
via <literal>file://</literal>, and can entail all the
same problems if the administrator isn't careful.</para>
@@ -2088,7 +2088,7 @@
the <quote>default</quote> MIME type,
typically <literal>text/plain</literal>. This can be
frustrating, however, if a user wishes repository files to
- render as something more meaningful — for example,
+ render as something more meaningful—for example,
it might be nice to have a <filename>foo.html</filename> file
in the repository actually render as HTML when
browsing.</para>
@@ -2219,7 +2219,7 @@
even the simplest Subversion client operation generates
multiple network requests. It's very difficult to look at
the <filename>access_log</filename> and deduce what the
- client was doing — most operations look like a series
+ client was doing—most operations look like a series
of cryptic <literal>PROPPATCH</literal>, <literal>GET</literal>,
<literal>PUT</literal>, and <literal>REPORT</literal>
requests. To make things worse, many client operations send
Index: en/book/ch04-branching-and-merging.xml
===================================================================
--- en/book/ch04-branching-and-merging.xml (revision 2735)
+++ en/book/ch04-branching-and-merging.xml (working copy)
@@ -1038,7 +1038,7 @@
file. This can lead to problems, especially because the
same thing happens with renamed files. A lesser-known fact
about Subversion is that it lacks <quote>true
- renames</quote> — the <command>svn move</command>
+ renames</quote>—the <command>svn move</command>
command is nothing more than an aggregation of <command>svn
copy</command> and <command>svn delete</command>.</para>
@@ -1064,7 +1064,7 @@
operation has deleted the latest version
of <filename>integer.c</filename> file (the one containing
Sally's latest changes), and blindly added your
- new <filename>whole.c</filename> file — which is a
+ new <filename>whole.c</filename> file—which is a
duplicate of the <emphasis>older</emphasis> version
of <filename>integer.c</filename>. The net effect is that
merging your <quote>rename</quote> to the branch has removed
@@ -1401,8 +1401,8 @@
particular revision tree, and the second coordinate is a path
within that tree. So every version of your file or directory
can be defined by a specific coordinate pair. (Remember the
- familiar <quote>peg revision</quote> syntax — foo.c at 224
- — mentioned back in
+ familiar <quote>peg revision</quote> syntax—foo.c at 224
+ —mentioned back in
<xref linkend="svn.advanced.pegrevs"/>.) </para>
<para>First, you might need to use <command>svn log</command> to
Index: en/book/ch02-basic-usage.xml
===================================================================
--- en/book/ch02-basic-usage.xml (revision 2735)
+++ en/book/ch02-basic-usage.xml (working copy)
@@ -98,6 +98,10 @@
subdir/
</screen>
+ <!-- it might also be worth emphasizing - even though the example
+ above clearly shows it - that the repo does *not* get a new
+ directory named "mytree". I occasionally find people on IRC are
+ surprised by this. -->
<para>Note that after the import is finished, the original tree
is <emphasis>not</emphasis> converted into a working copy. To
start working, you still need to <command>svn
@@ -125,7 +129,7 @@
</screen>
<para>You'll learn more about tags and branches in <xref
- linkend="svn.branchmerge"/>. For details and how to setup
+ linkend="svn.branchmerge"/>. For details, and how to set up
multiple projects, see <xref
linkend="svn.branchmerge.maint.layout"/> and <xref
linkend="svn.reposadmin.projects.chooselayout"/> to read more
@@ -147,8 +151,8 @@
copy</quote> of it on your local machine. This copy contains
the <literal>HEAD</literal> (latest revision) of the Subversion
repository that you specify on the command line:</para>
+ <!-- well, unless you specify a "-r" option, of course. -->
-
<screen>
$ svn checkout http://svn.collab.net/repos/svn/trunk
A trunk/Makefile.in
@@ -209,6 +213,9 @@
repository by specifying the subdirectory in the checkout
URL:</para>
+ <!-- are you sure you want to introduce the "-r" option here,
+ without describing it? It might make a reader think that it's
+ needed in order to check out a subdirectory. -->
<screen>
$ svn checkout -r 8810 \
http://svn.collab.net/repos/svn/trunk/subversion/tests/cmdline/
@@ -223,27 +230,27 @@
<para>Since Subversion uses a <quote>copy-modify-merge</quote>
model instead of <quote>lock-modify-unlock</quote> (see <xref
- linkend="svn.basic.vsn-models"/>), you're already able to start
+ linkend="svn.basic.vsn-models"/>), you can start right in
making changes to the files and directories in your working
copy. Your working copy is just like any other collection of
files and directories on your system. You can edit and change
them, move them around, you can even delete the entire working
copy and forget about it.</para>
- <note>
+ <warning>
<para>While your working copy is <quote>just like any other
collection of files and directories on your system</quote>,
you can edit files at will, but you must tell Subversion
- about <emphasis>everything else</emphasis>that you do. For
+ about <emphasis>everything else</emphasis> that you do. For
example, if you want to copy or move an item in a working
copy, you should use <command>svn copy</command> or
<command>svn move</command> instead of the copy and move
commands provided by your operating system. We'll talk more
about them later in this chapter.</para>
- </note>
+ </warning>
- <para>Unless you're ready to commit a new file or directory, or
+ <para>Unless you're ready to commit the addition of a new file or directory, or
changes to existing ones, there's no need to further notify the
Subversion server that you've done anything.</para>
@@ -257,9 +264,12 @@
an important directory. Whatever you do, don't delete or
change anything in the administrative area! Subversion
depends on it to manage your working copy.</para>
-
+ <!-- that warning is useful on its own, but how about telling me
+ how to recover if I _have_ deleted that directory? Believe
+ me, it happens. -->
</sidebar>
+ <!-- as above, I think the "-r" option here is a distraction. -->
<para>While you can certainly check out a working copy with the
URL of the repository as the only argument, you can also specify
a directory after your repository URL. This places your working
@@ -288,6 +298,7 @@
<para>When you perform a Subversion operation that requires you
to authenticate, by default Subversion caches your
+ <!-- perhaps say "for convenience - so that you don't have to enter them again" -->
authentication credentials on disk. If you're concerned about
caching your Subversion passwords,<footnote><para>Of course,
you're not terribly worried—first because you know that
@@ -438,7 +449,7 @@
to each item to let you know what actions Subversion performed
to bring your working copy up-to-date. To find out what these
letters mean, see <xref linkend
- ="svn.ref.svn.c.update"/></para>
+ ="svn.ref.svn.c.update"/>.</para>
</sect2>
@@ -467,8 +478,8 @@
text files—and just as efficiently too. For tree
changes, you can ask Subversion to <quote>mark</quote> files
and directories for scheduled removal, addition, copying, or
- moving. While these changes may take place immediately in
- your working copy, no additions or removals will happen in the
+ moving. These changes take place immediately in
+ your working copy, but no additions or removals happen in the
repository until you commit them.</para>
<para>Here is an overview of the five Subversion subcommands
@@ -487,9 +498,9 @@
<para>When a symlink is committed into a Subversion
repository, Subversion remembers that the file was in fact a
- symlink, as well as to what object the symlink
+ symlink, as well as the object to which the symlink
<quote>points</quote>. When that symlink is checked out to
- another working copy on a supporting system, Subversion
+ another working copy on a non-Windows system, Subversion
reconstructs a real filesystem-level symbolic link from the
versioned symlink. But that doesn't in any way limit the
usability of working copies on systems such as Windows which
@@ -526,16 +537,17 @@
repository. If <filename>foo</filename> is a file or
link, it is immediately deleted from your working copy.
If <filename>foo</filename> is a directory, it is not
- deleted, but Subversion schedules it for deletion. When
+ deleted, but versioned files under it are, and
+ Subversion schedules it, and versioned directories under it, for deletion. When
you commit your changes, <filename>foo</filename> will
- be removed from your working copy and the repository.
+ be entirely removed from your working copy and the repository.
<footnote><para>Of course, nothing is ever totally
deleted from the repository—just from the
<literal>HEAD</literal> of the repository. You can get
back anything you delete by checking out (or updating
- your working copy) a revision earlier than the one in
+ your working copy to) a revision earlier than the one in
which you deleted it. Also see <xref
- linkend="svn.branchmerge.commonuses.resurrect"/>></para></footnote></para>
+ linkend="svn.branchmerge.commonuses.resurrect"/>.</para></footnote></para>
</listitem>
</varlistentry>
@@ -623,11 +635,11 @@
<sidebar>
<title>Look Ma! No Network!</title>
- <para>The commands (<command>svn status</command>,
+ <para>The commands <command>svn status</command>,
<command>svn diff</command>, and <command>svn
- revert</command>) can be used without any network access
- (assuming, of course, that your repository is across the
- network and not local). This makes it easy to manage your
+ revert</command> can be used without any network access
+ even if your repository <emphasis>is</emphasis> across the
+ network. This makes it easy to manage your
changes-in-progress when you are somewhere without a network
connection, such as travelling on an airplane, riding a
commuter train or hacking on the beach.<footnote><para>And
@@ -654,6 +666,7 @@
<para>Subversion has been optimized to help you with this task,
and is able to do many things without communicating with the
repository. In particular, your working copy contains a
+ <!-- "secret"? nah. "hidden", maybe. -->
secret cached <quote>pristine</quote> copy of each version
controlled file within the <filename>.svn</filename> area.
Because of this, Subversion can quickly show you how your
@@ -689,14 +702,15 @@
</sidebar>
- <para>If you run <command>svn status</command> at the top of
- your working copy with no arguments, it will detect all file
+ <para>If you run <command>svn status</command>, with no arguments, at the top of
+ your working copy, it will detect all file
and tree changes you've made. Below are a few examples of
the most common status codes that <command>svn
status</command> can return. (Note that the text following
<literal>#</literal> is not
actually printed by <command>svn status</command>.)</para>
+ <!-- conflicts can come from merges, too, of course. -->
<screen>
A stuff/loot/bloo.h # file is scheduled for addition
C stuff/loot/lump.c # file has textual conflicts from an update
@@ -705,9 +719,9 @@
</screen>
<para>In this output format <command>svn status</command>
- prints six columns of characters, followed by several
- whitespace characters, followed by a file or directory name.
- The first column tells the status of a file or directory
+ prints six characters -- letters or whitespace -- followed by several
+ more whitespace characters, followed by a file or directory name.
+ The letter tells the status of a file or directory
and/or its contents. The codes we listed are:</para>
<variablelist>
@@ -726,6 +740,7 @@
<listitem>
<para>The file <filename>item</filename> is in a state
of conflict. That is, changes received from the
+ <!-- again, it could conflict due to a merge, too -->
server during an update overlap with local changes
that you have in your working copy. You must resolve
this conflict before committing your changes to the
@@ -761,6 +776,10 @@
D stuff/fish.c
</screen>
+ <!-- Ooh, this is subtle. -v apparently changes _both_ the
+ files that "status" reports on (at least, if you haven't
+ specified a file name), _and_ the information that appears for
+ each file. Is it worth mentioning this here? -->
<para><command>svn status</command> also has a
<option>--verbose (-v)</option> switch, which will show you
the status of <emphasis>every</emphasis> item in your
@@ -780,16 +799,18 @@
</screen>
<para>This is the <quote>long form</quote> output of
- <command>svn status</command>. The first column remains the
- same, but the second column shows the working-revision of
+ <command>svn status</command>. The letters in the first column mean the
+
+ <!-- what does "working-revision" mean? If you don't want
+ to define it here, then we should probably wrap it in <firstterm/>. -->
+ same as in the above, but the second column shows the working-revision of
+
the item. The third and fourth columns show the revision in
- which the item last changed, and who changed it (these
- columns are not to be confused with the columns of
- characters that we just discussed).</para>
+ which the item last changed, and who changed it.</para>
<para>None of the above invocations to <command>svn
- status</command> contact the repository, they work only
- locally by comparing the metadata in the
+ status</command> contact the repository—instead, they
+ compare the metadata in the
<filename>.svn</filename> directory with the working copy.
Finally, there is the <option>--show-updates (-u)</option>
option, which contacts the repository and adds information
@@ -813,8 +834,10 @@
server changes on <filename>README</filename> before you
commit, or the repository will reject your commit for being
out-of-date. (More on this subject later.)</para>
+ <!-- how about a link to the section where this is discussed,
+ instead of simply saying "later"? -->
- <para><command>svn status</command> displays much more
+ <para><command>svn status</command> can display much more
information about the files and directories in your
working copy than we've shown here—for an exhaustive
description of svn status and its output, see <xref
@@ -830,8 +853,8 @@
<command>svn diff</command> command. You can find out
<emphasis>exactly</emphasis> how you've modified things by
running <command>svn diff</command> with no arguments, which
- prints out file changes in unified diff
- format:</para>
+ prints out file changes in <firstterm>unified diff
+ format</firstterm>:</para>
<screen>
$ svn diff
@@ -881,11 +904,19 @@
addition are displayed as all added-text, and files
scheduled for deletion are displayed as all deleted
text.</para>
+ <!-- shouldn't we then ensure that we have a scheduled-add file,
+ and a scheduled-delete file, in the above example? If we
+ already have one, and I'm overlooking it, then say something
+ like "... files scheduled for deletion, like stuff/fish.c,
+ are displayed ..."-->
- <para>Output is displayed in <firstterm>unified diff
- format</firstterm>. That is, removed lines are prefaced
- with a <literal>-</literal> and added lines are prefaced
- with a <literal>+</literal>. <command>svn diff</command>
+ <para>Output is displayed in unified diff
+ format. That is, removed lines are prefaced
+ <!-- I deleted the word "a" in two places because I fear
+ that it will be confused with the "A" output by "svn st",
+ which we just described. -->
+ with <literal>-</literal> and added lines are prefaced
+ with <literal>+</literal>. <command>svn diff</command>
also prints filename and offset information useful to the
<command>patch</command> program, so you can generate
<quote>patches</quote> by redirecting the diff output to a
@@ -955,7 +986,7 @@
? foo
</screen>
- <note>
+ <warning>
<para><command>svn revert</command>
<replaceable>ITEM</replaceable> has exactly the same
effect as deleting <replaceable>ITEM</replaceable> from
@@ -965,7 +996,7 @@
has one very noticeable difference—it doesn't have
to communicate with the repository to restore your
file.</para>
- </note>
+ </warning>
<para>Or perhaps you mistakenly removed a file from version
control:</para>
@@ -1015,7 +1046,7 @@
changes.</para>
<para>But the <computeroutput>C</computeroutput> stands for
- conflict. This means that the changes from the server overlapped
+ <computeroutput>c</computeroutput>onflict. This means that the changes from the server overlapped
with your own, and now you have to manually choose between
them.</para>
@@ -1359,7 +1390,7 @@
decide that you want to cancel your commit, you can just
quit your editor without saving changes. If you've already
saved your commit message, simply delete the text, save
- again, then quit.</para>
+ again, then abort.</para>
<screen>
$ svn commit
@@ -1379,6 +1410,17 @@
that, the entire commit will fail with a message informing you
that one or more of your files is out-of-date:</para>
+ <!-- frustratingly (and surprisingly), the "out of date" message
+ depends on the access method. The one in the example below is
+ for http:// access, but file:// access yields this instead:
+
+ ../svn-live/subversion/libsvn_client/commit.c:867: (apr_err=160028)
+ svn: Commit failed (details follow):
+ ../svn-live/subversion/libsvn_repos/commit.c:127: (apr_err=160028)
+ svn: Out of date: 'yow' in transaction '2-1'
+
+ So we should probably note that the text of the message might
+ vary somewhat :-| -->
<screen>
$ svn commit -m "Add another rule"
Sending rules.txt
@@ -1396,7 +1438,7 @@
to manage your repository and working copy, but most of your
day-to-day use of Subversion will involve only the commands
that we've discussed so far in this chapter. We will,
- however, cover a few more commands that you'll use just fairly
+ however, cover a few more commands that you'll use fairly
often.</para>
</sect2>
@@ -1443,8 +1485,8 @@
<varlistentry>
<term><command>svn cat</command></term>
<listitem>
- <para>This is used to retrieve any file as it existed in a
- particular revision number and display it on your
+ <para>Retrieves a file as it existed in a
+ particular revision number, and displays it on your
screen.</para>
</listitem>
</varlistentry>
@@ -1591,15 +1633,15 @@
<itemizedlist>
<listitem>
- <para>Examine local changes</para>
+ <para>Examining local changes</para>
</listitem>
<listitem>
- <para>Compare your working copy to the repository</para>
+ <para>Comparing your working copy to the repository</para>
</listitem>
<listitem>
- <para>Compare repository to repository</para>
+ <para>Comparing repository to repository</para>
</listitem>
</itemizedlist>
@@ -1640,6 +1682,12 @@
working copy is compared to the specified revision in the
repository.</para>
+ <!-- might this example be a tad more illuminating if we were
+ to pass some revision _other_ than 3? So that it yields
+ different output than the above example? If not, why not
+ mumble something about "note how the output is the same as
+ above, since the revision we specified is the same as that
+ chosen by default in the above"-->
<screen>
$ svn diff -r 3 rules.txt
Index: rules.txt
@@ -1700,13 +1748,9 @@
$
</screen>
- <para>Not only can you use <command>svn diff</command> to
- compare files in your working copy to the repository, but if
- you supply a URL argument, you can examine the differences
- between items in the repository without even having a
- working copy. This is especially useful if you wish to
- inspect changes in a file when you don't have a working copy
- on your local machine:</para>
+ <para>Lastly, you can compare repository revisions even when
+ you don't have a working copy on your local machine, just by
+ including the appropriate URL on the command line:</para>
<screen>
$ svn diff -c 5 http://svn.example.com/repos/example/trunk/text/rules.txt
@@ -1813,7 +1857,7 @@
…
</screen>
- <warning>
+ <tip>
<para>Many Subversion newcomers attempt to use the above
<command>svn update</command> example to <quote>undo</quote>
committed changes, but this won't work as you can't commit
@@ -1821,12 +1865,12 @@
the changed files have newer revisions. See <xref
linkend="svn.branchmerge.commonuses.resurrect"/> for a
description of how to <quote>undo</quote> a commit.</para>
- </warning>
+ </tip>
<para>Lastly, if you're building a release and wish to bundle up
- your files from Subversion but don't want those pesky .svn
- directories in the way, then you can use svn export to create
- a local copy of all or part of your repository sans .svn
+ your files from Subversion but don't want those pesky <filename>.svn</filename>
+ directories in the way, then you can use <command>svn export</command> to create
+ a local copy of all or part of your repository sans <filename>.svn</filename>
directories. As with <command>svn update</command> and
<command>svn checkout</command>, you can also pass the
<option>--revision</option> switch to <command>svn
@@ -1849,7 +1893,7 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.tour.cleanup">
- <title>Sometimes You Just Need to Cleanup</title>
+ <title>Sometimes You Just Need to Clean Up</title>
<para>When Subversion modifies your working copy (or any
information within <filename>.svn</filename>), it tries to do
@@ -1857,7 +1901,7 @@
Subversion writes its intentions to a log file. Next it
executes the commands in the log file to apply the requested
change, holding a lock on the relevant part of the working
- copy while it works — to prevent other Subversion clients
+ copy while it works—to prevent other Subversion clients
from accessing the working copy in mid-change. Finally,
Subversion removes the log file. Architecturally, this is
similar to a journaled filesystem. If a Subversion operation
--
Most of what ends up in my essays I only thought of when I sat
down to write them. That's why I write them.
-- Paul Graham
More information about the svnbook-dev
mailing list