[SvnBook] #62: [PATCH] Hanchrow review [ch3:ch4]
SvnBook
noreply at red-bean.com
Fri Aug 10 21:06:48 CDT 2007
#62: [PATCH] Hanchrow review [ch3:ch4]
-------------------------+--------------------------------------------------
Reporter: cmpilato | Owner: nobody
Type: enhancement | Status: new
Priority: normal | Milestone: 1.5
Component: content | Version:
Keywords: |
-------------------------+--------------------------------------------------
From: Eric Hanchrow <offby1 at blarg.net>
{{{
--- ch03-advanced-topics.xml (revision 2735)
+++ ch03-advanced-topics.xml (working copy)
@@ -5,7 +5,7 @@
start to finish, you should by now have acquired enough
knowledge to use the Subversion client to perform the most
common version control operations. You understand how to
- checkout a working copy from a Subversion repository. You are
+ check out a working copy from a Subversion repository. You are
comfortable with submitting and receiving changes using the
<command>svn commit</command> and <command>svn update</command>
functions. You've probably even developed a reflex which causes
@@ -15,7 +15,7 @@
<para>But the Subversion feature set doesn't stop at <quote>common
version control operations</quote>. It has other bits of
- functionality that extend beyond just communicating file and
+ functionality besides just communicating file and
directory changes to and from a central repository.</para>
<para>This chapter highlights some of Subversion's features that,
@@ -44,14 +44,14 @@
<emphasis>do</emphasis> require a revision specifier, you
generally supply a revision number that you saw in a commit
email, in the output of some other Subversion operation, or in
- some other context that would yield meaning to that particular
+ some other context that would give meaning to that particular
number.</para>
<para>But occasionally, you need to pinpoint a moment in time for
which you don't already have a revision number memorized or
handy. So besides the integer revision numbers,
<command>svn</command> allows as input some additional forms of
- revision specifiers—revision keywords, and revision
+ revision specifiers—revision <firstterm>keywords</firstterm>,
and revision
dates.</para>
<note>
@@ -90,7 +90,7 @@
</indexterm>
<para>The Subversion client understands a number of
- <firstterm>revision keywords</firstterm>. These keywords can
+ revision keywords. These keywords can
be used instead of integer arguments to the
<option>--revision (-r)</option> switch, and are resolved into
specific revision numbers by Subversion:</para>
@@ -116,6 +116,10 @@
</varlistentry>
<varlistentry>
+ <!-- I recall a discussion on IRC wherein someone was asking
+ how COMMITTED might be different than BASE. I've forgotten
+ the answer, and am wondering myself. I therefore suspect it
+ would be good to explain that here. -->
<term>COMMITTED</term>
<listitem>
<para>The most recent revision prior to, or equal to,
@@ -253,6 +257,11 @@
…
</screen>
+ <!-- I don't quite understand what I'm being warned about here:
+ is it "Don't trust the results when you specify dates", or is it
+ "Don't mess with the svn:date property because you'll confuse
+ your co-workers", or what? What kind of havoc will be wrought:
+ will my repository become corrupt? -->
<warning>
<para>Since the timestamp of a revision is stored as an
unversioned, modifiable property of the revision (see <xref
@@ -294,7 +303,9 @@
attached to each item in your working copy. Generally speaking,
the names and values of the properties can be whatever you want
them to be, with the constraint that the names must be
- human-readable text. And the best part about these properties
+ human-readable text. <!-- and that a few, beginning with "svn:",
+ are reserved. -->
+ And the best part about these properties
is that they, too, are versioned, just like the textual contents
of your files. You can modify, commit, and revert property
changes as easily as you can file content changes. And the
@@ -333,6 +344,9 @@
support. You'll learn about the property-related
<command>svn</command> subcommands, and how property
modifications affect your normal Subversion workflow.
+
+ <!-- ick. Why include this sentence at all? It sounds like
+ marketing. -->
Hopefully, you'll be convinced that Subversion properties can
enhance your version control experience.</para>
@@ -343,9 +357,7 @@
<para>Just as Subversion uses properties to store extra
information about the files, directories, and revisions that
it contains, you might also find properties to be of similar
- use. Some part of the processes around Subversion's usage
- to which you adhere, or maybe some additional tooling around
- Subversion that you use, might find utility in having a place
+ use. You might find it useful to have a place
close to your versioned data to hang custom metadata about
that data.</para>
@@ -379,6 +391,7 @@
casual browser like there are nothing but image files in it.
But your automation scripts know better. They know that they
can use <command>svn</command> (or better yet, they can use
+ <!-- why not just svn.developer.usingapi ? -->
the Subversion language bindings—see <xref
linkend="svn.developer.usingapi.otherlangs" />) to dig out the
extra information that your site needs to display without
@@ -387,14 +400,16 @@
<para>Custom revision properties are also frequently used. One
common such use is a property whose value contains an issue
- tracker ID with which the revision is associated, perhaps
- because the change made in that revision fixes a bug filed in
- the tracker issue with that ID. Other uses include hanging
- more friendly names on the revision—it might be hard to
- remember that revision 1935 was a fully tested revision. But
- if there's, say, a <literal>test-results</literal> property on
- that revision with a value <literal>all passing</literal>,
- that's meaningful information to have.</para>
+ <!-- there seems to be a standard forming around this:
+ http://tortoisesvn.net/issuetracker_integration --> tracker ID
+ with which the revision is associated, perhaps because the
+ change made in that revision fixes a bug filed in the tracker
+ issue with that ID. Other uses include hanging more friendly
+ names on the revision—it might be hard to remember that
+ revision 1935 was a fully tested revision. But if there's,
+ say, a <literal>test-results</literal> property on that
+ revision with a value <literal>all passing</literal>, that's
+ meaningful information to have.</para>
<sidebar>
<title>Searchability (or, Why <emphasis>Not</emphasis>
@@ -402,8 +417,8 @@
<para>For all their utility, Subversion properties—or,
more accurately, the available interfaces to them—have
- a major shortcoming which diminishes their practicality.
- While it is a simple matter to set a custom property,
+ a major shortcoming:
+ while it is a simple matter to <emphasis>set</emphasis> a
custom property,
<emphasis>finding</emphasis> that property later is whole
different ball of wax.</para>
@@ -420,6 +435,9 @@
search would require a working copy from the root of your
repository.</para>
+ <!-- actually it's not clear to me why putting the info in
+ svn:log is any better, performance-wise, than putting it in
+ some custom revprop. Can you explain? -->
<para>For this reason, you might choose—especially in
the revision property use-case—to simply add your
metadata to the revision's log message, using some
@@ -453,7 +471,7 @@
add or modify file and directory properties. For properties
with short, human-readable values, perhaps the simplest way to
add a new property is to specify the property name and value
- on the command-line of the <command>propset</command>
+ on the command line of the <command>propset</command>
subcommand.</para>
<screen>
@@ -465,7 +483,7 @@
<para>But we've been touting the flexibility that Subversion
offers for your property values. And if you are planning to
have a multi-line textual, or even binary, property value, you
- probably do not want to supply that value on the command-line.
+ probably do not want to supply that value on the command line.
So the <command>propset</command> subcommand takes a
<option>--file (-F)</option> option for specifying the name of
a file which contains the new property value.</para>
@@ -503,7 +521,7 @@
Subversion detects that you've actually changed the existing
value of the property, it will accept that as the new property
value. If you exit your editor without making any changes, no
- property modification will occur.</para>
+ property modification will occur:</para>
<screen>
$ svn propedit copyright calc/button.c ### exit the editor without
changes
@@ -534,8 +552,8 @@
command will list the names of properties that exist on a
path. Once you know the names of the properties on the node,
you can request their values individually using <command>svn
- propget</command>. This command will, given a path (or set of
- paths) and a property name, print the value of the property to
+ propget</command>. This command will, given a property name and
a path (or set of
+ paths), print the value of the property to
the standard output stream.</para>
<screen>
@@ -568,6 +586,7 @@
red-beans-and-rice.
…
</screen>
+ <!-- hey! where can I get that recipe? -->
<para>The last property-related subcommand is
<command>propdel</command>. Since Subversion allows you to
@@ -629,7 +648,7 @@
</screen>
<para>But even if you haven't checked out a working copy from
- that repository, you can still affect the property change by
+ that repository, you can still effect the property change by
providing the repository's root URL:</para>
<screen>
@@ -642,9 +661,9 @@
<para>Note that the ability to modify these unversioned
properties must be explicitly added by the repository
administrator (see <xref linkend="svn.reposadmin.create.hooks"
/>).
- Since the properties aren't versioned, you run the risk of
+ That's because the properties aren't versioned, so you run the
risk of
losing information if you aren't careful with your edits.
- The repository administrator can setup methods to protect
+ The repository administrator can set up methods to protect
against this loss, and by default, modification of
unversioned properties is disabled.</para>
@@ -673,7 +692,7 @@
workflow. As we mentioned earlier, file and directory
properties are versioned, just like your file contents. As a
result, Subversion provides the same opportunities for
- merging—in cleanly or conflicting fashions—someone
+ merging—cleanly or with conflicts—someone
else's modifications into your own.</para>
<para>And as with file contents, your property changes are local
@@ -681,7 +700,7 @@
repository with <command>svn commit</command>. Your property
changes can be easily unmade, too—the <command>svn
revert</command> command will restore your files and
- directories to their un-edited states, contents, properties,
+ directories to their un-edited states—contents, properties,
and all. Also, you can receive interesting information about
the state of your file and directory properties by using the
<command>svn status</command> and <command>svn diff</command>
@@ -702,7 +721,7 @@
<para>Notice how the <command>status</command> subcommand
displays <literal>M</literal> in the second column instead of
the first. That is because we have modified the properties on
- <filename>calc/button.c</filename>, but not modified its
+ <filename>calc/button.c</filename>, but not its
textual contents. Had we changed both, we would have seen
<literal>M</literal> in the first column, too (see <xref
linkend="svn.tour.cycle.examine.status" />).</para>
@@ -757,8 +776,8 @@
still run <command>svn diff</command> and redirect the output
to create a usable patch file. The <command>patch</command>
program will ignore property patches—as a rule, it
- ignores any noise it can't understand. This does
- unfortunately mean that to fully apply a patch generated by
+ ignores any noise it can't understand. This does,
+ unfortunately, mean that to fully apply a patch generated by
<command>svn diff</command>, any property modifications will
need to be applied by hand.</para>
@@ -773,10 +792,10 @@
in this and other chapters—textual diff and merge
support, keyword substitution, newline translation, etc. But
to get the full benefit of properties, they must be set on the
- right files and directories. Unfortunately, that can be a
- step easily forgotten in the routine of things, especially
+ right files and directories. Unfortunately, that
+ step can be easily forgotten in the routine of things, especially
since failing to set a property doesn't usually result in an
- obvious error condition (at least compared to, say, failing to
+ obvious error (at least compared to, say, failing to
add a file to version control). To help your properties get
applied to the places that need them, Subversion provides a
couple of simple but useful features.</para>
@@ -809,11 +828,11 @@
flexible automatic property setting feature which allows you
to create mappings of filename patterns to property names and
values. Once again, these mappings affect adds and imports,
- and not only can override the default MIME type decision made
+ and can not only override the default MIME type decision made
by Subversion during those operations, but can also set
additional Subversion or custom properties, too. For example,
you might create a mapping that says that any time you add
- JPEG files—ones that match the pattern
+ JPEG files—ones whose names match the pattern
<literal>*.jpg</literal>—Subversion should automatically
set the <literal>svn:mime-type</literal> property on those
files to <literal>image/jpeg</literal>. Or perhaps any files
@@ -821,7 +840,7 @@
<literal>svn:eol-style</literal> set to
<literal>native</literal>, and <literal>svn:keywords</literal>
set to <literal>Id</literal>. Automatic property support is
- perhaps the handiest property related tool in the Subversion
+ perhaps the handiest property-related tool in the Subversion
toolbox. See <xref
linkend="svn.advanced.confarea.opts.config"/> for more about
configuring that support.</para>
@@ -875,6 +894,8 @@
<sidebar>
<title>Identifying File Types</title>
+ <!-- "Software programs" sounds funny to me - just "Software"
+ sounds better -->
<para>Software programs on most modern operating systems make
assumptions about the type and format of the contents of a
file by the file's name, specifically its file extension.
@@ -885,18 +906,18 @@
whose names end in <filename>.png</filename>, on the other
hand, are assumed to be of the Portable Network Graphics
type—not human-readable at all, and sensible only when
- interpreted by software which understands the PNG format and
+ interpreted by software which understands the PNG format, and
can render the information in that format as a raster
image.</para>
<para>Unfortunately, some of those extensions have changed
- meanings over time. When personal computers first appeared,
+ their meanings over time. When personal computers first
appeared,
a file named <filename>README.DOC</filename> would have
almost certainly been a plaintext file, just like today's
<filename>.txt</filename> files. But by the mid-1990's, you
could almost bet that a file of that name would not be a
plaintext file at all, but instead a Microsoft Word document
- with a proprietary, non-human-readable format. But this
+ in a proprietary, non-human-readable format. But this
change didn't occur overnight—there was certainly a
period of confusion for computer users over what exactly
they had in hand when they saw a <filename>.DOC</filename>
@@ -912,7 +933,7 @@
doubt on the mapping between a file's name and its content.
With information being served across networks and generated
dynamically by server-side scripts, there was often no real
- file per se to speak of, and therefore no file name. Web
+ file per se, and therefore no file name. Web
servers, for example, needed some other way to tell browsers
what they were downloading so the browser could do something
intelligent with that information, whether that was to
@@ -922,11 +943,11 @@
<para>Eventually, a standard emerged for, among other things,
describing the contents of a data stream. In 1996, RFC2045
- was published, the first of five RFCs describing MIME. In
- it, this RFC describes the concept of media types and
+ was published, the first of five RFCs describing MIME.
+ It 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
+ those types. Today, MIME media types—or <quote>MIME
+ types</quote>—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>
@@ -940,6 +961,7 @@
concept of a <quote>line</quote>. So, for versioned files
whose <literal>svn:mime-type</literal> property is set to a
non-textual MIME type (generally, something that doesn't begin
+ <!-- are the precise rules documented somewhere? -->
with <literal>text/</literal>, though there are exceptions),
Subversion does not attempt to perform contextual merges
during updates. Instead, any time you have locally modified a
@@ -956,7 +978,7 @@
set, then the Subversion Apache module will use its value to
populate the <literal>Content-type:</literal> HTTP header when
responding to GET requests. This gives your web browser a
- crucial clue about how to display a file when using it to
+ crucial clue about how to display a file when you use it to
peruse your Subversion repository's contents.</para>
</sect2>
@@ -1018,19 +1040,19 @@
character to denote the end of a line.</para>
<para>Not all of the various tools on these operating systems
- are prepared to understand files that contain line endings
+ understand files that contain line endings
in a format that differs from the <firstterm>native line
ending style</firstterm> of the operating system on which
- they are running. Common results are that Unix programs
+ they are running. So, typically, Unix programs
treat the <literal>CR</literal> character present in Windows
files as a regular character (usually rendered as
- <literal>^M</literal>), and that Windows programs combine
+ <literal>^M</literal>), and Windows programs combine
all of the lines of a Unix file into one giant line because
no carriage return-linefeed (or <literal>CRLF</literal>)
- character combination was found to denote the end of
- line.</para>
+ character combination was found to denote the ends of
+ the lines.</para>
- <para>This sensitivity to foreign EOL markers can become
+ <para>This sensitivity to foreign EOL markers can be
frustrating for folks who share a file across different
operating systems. For example, consider a source code
file, and developers that edit this file on both Windows and
@@ -1135,6 +1157,7 @@
alongside all those versioned files and directories are other
files and directories which are neither versioned nor intended
to be. Text editors litter directories with backup files. Code
+ <!-- Why not just say "Compilers", instead of "Code compilation
processes"? -->
compilation processes generate intermediate—or even
final—files which you typically wouldn't bother to
version. And users themselves drop various other files and
@@ -1171,14 +1194,15 @@
<para>The Subversion runtime configuration system provides an
option, <literal>global-ignores</literal>, whose value is a
- whitespace-delimited collection of file patterns (or globs).
- These patterns are applied to files which are candidates for
+ whitespace-delimited collection of file patterns (also known as
<firstterm>globs</firstterm>).
+ The subversion client checks these patterns against the names of
+ the files which are candidates for
addition to version control, as well as to unversioned files
- which the <command>svn status</command> command notices. If the
- filenames match one of the patterns, Subversion will basically
+ which the <command>svn status</command> command notices. If any
+ file's name matches one of the patterns, Subversion will basically
act as if the file didn't exist at all. This is really useful
- for file patterns which are nearly universally of the variety
- that you don't want to version, such as editor backup files like
+ for the kinds of files
+ that you almost never want to version, such as editor backup files
like
Emacs' <literal>*~</literal> and <literal>.*~</literal>
files.</para>
@@ -1190,7 +1214,7 @@
<literal>global-ignores</literal> runtime configuration option,
but are instead appended to that list. And it's worth noting
again that, unlike the <literal>global-ignores</literal> option,
- the patterns found in the <literal>svn:eol-ignore</literal>
+ the patterns found in the <literal>svn:ignore</literal>
property apply only to the directory on which that property is
set, and not to any of its subdirectories. The
<literal>svn:ignore</literal> property is a good way to tell
@@ -1201,7 +1225,11 @@
result of a conversion of some source DocBook XML files to a
more legible output format.</para>
- <warning>
+ <!-- it might be good to put an anchor right here, so that I can
+ give out a URL to this exact note on IRC. This mistake - assuming
+ that svn:ignore applied to files that are already checked in - is
+ probably the single most common mistake I note on IRC. -->
+ <note>
<para>Subversion's support for ignorable file patterns extends
only to the one-time process of adding unversioned
files and directories to version control. Once an object is
@@ -1211,7 +1239,7 @@
simply because that file's name matches an ignore
pattern—Subversion <emphasis>always</emphasis> notices
all of its versioned objects.</para>
- </warning>
+ </note>
<sidebar>
<title>Ignore Patterns for CVS Users</title>
@@ -1288,6 +1316,10 @@
debug_log*
</programlisting>
+ <!-- you might want to mention that svn:ignore takes effect
+ immediately - that is, you don't have to commit in order for it to
+ suppress ignored files in the output of "svn st". This surprised
+ me. -->
<para>After you've added this property, you will now have a local
property modification on the <filename>calc</filename>
directory. But notice what else is different about your
@@ -1351,9 +1383,9 @@
<para>Subversion has the ability to substitute
<firstterm>keywords</firstterm>—pieces of useful,
dynamic information about a versioned file—into the
- contents of the file itself. Keywords generally describe
- information about the last time the file was known to be
- modified. Because this information changes each time the
+ contents of the file itself. Keywords generally provide
+ information about the last modification made to the file.
+ Because this information changes each time the
file changes, and more importantly, just
<emphasis>after</emphasis> the file changes, it is a hassle
for any process except the version control system to keep
@@ -1365,7 +1397,7 @@
could burden every author of that document to, just before
committing their changes, also tweak the part of the
document that describes when it was last changed. But
- sooner or later, someone would forget to do that. Instead
+ sooner or later, someone would forget to do that. Instead,
simply ask Subversion to perform keyword substitution on the
<literal>LastChangedDate</literal> keyword. You control
where the keyword is inserted into your document by placing
@@ -1390,7 +1422,15 @@
<term><literal>Date</literal></term>
<listitem>
<para>This keyword describes the last time the file was
+ <!-- why "known to have been changed", instead of simply
+ "changed"? Are there cases where a file will change in
+ the repo, but the keyword doesn't "know" about it? If so,
+ what are they? -->
known to have been changed in the repository, and
+ <!-- why "looks something like", instead of "is of the
+ form"? Is this format something that programs can count
+ on, rather the way that the C library function 'asctime'
+ always yields a 26-character string, formatted just so? -->
looks something like <literal>$Date:
2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006)
$</literal>. It may also be specified as
@@ -1547,7 +1587,7 @@
was designed for just this purpose.
<command>svnversion</command> crawls your working copy and
generates as output the revision(s) it finds. You can use
- this program, plus some additionally tooling, to embed that
+ this program, plus some additional tooling, to embed that
revision information into your files. For more information on
<command>svnversion</command>, see <xref
linkend="svn.ref.svnversion"/>.</para>
@@ -1571,6 +1611,17 @@
special hash (<literal>#</literal>) character just before
the final dollar sign terminator.</para>
+ <!-- perhaps mention more prominently, and earlier, that this
+ feature is just the thing for Microsoft Word documents. I suspect
+ (with, I admit, no evidence other than my own usage)
+ that this feature is more likely to be used with Word than in the
+ keeping-the-columns-neat scenario described below. -->
+
+ <!-- In fact, if possible, can you write something that answers
+ the question "When should I use this double-colon feature"? I
+ fear the answer is "try not using it and see if your document gets
+ corrupted", but maybe there's a better way :-| -->
+
<para>For example, say you have a document in which you have
some section of tabular data reflecting the document's
Subversion keywords. Using the original Subversion keyword
@@ -1648,6 +1699,8 @@
file corrupt, refusing to operate on the file
altogether.</para>
</warning>
+ <!-- fair enough. Can you recommend any way of avoiding this
+ problem? "leave lots of spaces", maybe? -->
</sect1>
@@ -1719,22 +1772,27 @@
cracked windshield!</para>
<para>Clearly, things would have gone more smoothly if Harry and
- Sally had serialized their modifications to the image. If, say,
+ Sally had serialized their modifications to the image—if,
say,
Harry had waited to draw his windshield cracks on Sally's
now-red car, or if Sally had tweaked the color of a car whose
windshield was already cracked. As is discussed in <xref
- linkend="svn.basic.vsn-models.copy-merge" />, much of these
- types problems go away entirely where perfect communication
+ linkend="svn.basic.vsn-models.copy-merge" />, most of these
+ types of problems go away entirely where perfect communication
between Harry and Sally exists.
+
<footnote>
<para>Communication wouldn't have been such bad medicine for
Harry and Sally's Hollywood namesakes, either, for that
matter.</para>
</footnote>
+
+ <!-- this is confusing; I'm not sure what it's trying to say. -->
But as one's version control system is, in fact, one form of
communication, it follows that having that software facilitate
the serialization of non-parallelizable energies is no bad
- thing. And this where Subversion's implementation of the
+ thing.
+
+ And this where Subversion's implementation of the
lock-modify-unlock model steps into the spotlight. This is
where we talk about Subversion's <firstterm>locking</firstterm>
feature, which is similar to the <quote>reserved
@@ -1753,9 +1811,12 @@
confident that energy invested on unmergeable changes won't
be wasted—his commit of those changes will
succeed.</para>
</listitem>
+
+ <!-- seems to me these two items are just different ways of
+ saying the same thing. -->
<listitem>
<para><emphasis>Aiding communication</emphasis>. By alerting
- other users that serialization is in effect for particular
+ other users that serialization is in effect for a particular
versioned object, those other users can reasonably expect
that the object is about to be changed by someone else,
and they, too, can avoid wasting their time and energy on
@@ -1802,6 +1863,7 @@
is the sort of lock whose unwanted persistence after an error
can cause a repository to be <quote>wedged</quote>, as
described in <xref
linkend="svn.reposadmin.maint.recovery"/>.</para>
+ <!-- perhaps point out that this command won't work when
disconnected -->
<para>You can generally forget about these other kinds of locks
until something goes wrong that requires you to care about
@@ -1931,7 +1993,7 @@
token prevents one piece of Subversion-related software from
undermining the work of another. (In our example, if you
really need to change the file from an alternate working
- copy, you would need to break the lock and re-lock the
+ copy, you would need to <firstterm>break</firstterm> the lock
and re-lock the
file.)</para>
</sidebar>
@@ -1982,7 +2044,7 @@
long. If Harry haphazardly locks thirty files in a directory
named <filename>images</filename> because he's unsure of which
files he needs to change, yet only only changes four of those
- file, when he runs <command>svn commit images</command>, the
+ files, when he runs <command>svn commit images</command>, the
process will still release all thirty locks.</para>
<para>This behavior of automatically releasing locks can be
@@ -2150,7 +2212,7 @@
authorization requirements are ignored, and the remote lock is
broken.</para>
- <para>Of course, simply breaking a lock may not be enough. In
+ <para>Simply breaking a lock may not be enough. In
the running example, Sally may not only want to break Harry's
long-forgotten lock, but re-lock the file for her own use.
She can accomplish this by running <command>svn unlock
@@ -2174,7 +2236,7 @@
may be in for a surprise. Harry's working copy still contains
the original lock token, but that lock no longer exists. The
lock token is said to be <firstterm>defunct</firstterm>. The
- lock represented by the lock-token has either been broken (no
+ lock represented by the lock token has either been broken (no
longer in the repository), or stolen (replaced with a
different lock). Either way, Harry can see this by asking
<command>svn status</command> to contact the
@@ -2259,19 +2321,19 @@
is a special property, <literal>svn:needs-lock</literal>. If
that property is attached to a file (regardless of its value,
which is irrelevant), then Subversion will try to use
- filesystem-level permissions to make the file read-only,
- unless, of course, the user has explicitly locked the file.
- When a lock-token is present (as a result of running
+ filesystem-level permissions to make the file read-
only—unless,
+ of course, the user has explicitly locked the file.
+ When a lock token is present (as a result of running
<command>svn lock</command>), the file becomes read-write.
When the lock is released, the file becomes read-only
again.</para>
<para>The theory, then, is that if the image file has this
property attached, then Sally would immediately notice
- something is strange when she opens the file for editing.
- Many applications alert users immediately when a read-only
- file is opened for editing. And nearly all applications would
- at least prevent her from saving changes to the file. This
+ something is strange when she opens the file for editing:
+ many applications alert users immediately when a read-only
+ file is opened for editing, and nearly all would
+ prevent her from saving changes to the file. This
reminds her to lock the file before editing, whereby she
discovers the pre-existing lock:</para>
@@ -2333,7 +2395,7 @@
made out of a number of different checkouts. For example, you
may want different subdirectories to come from different
locations in a repository, or perhaps from different
- repositories altogether. You could certainly setup such a
+ repositories altogether. You could certainly set up such a
scenario by hand—using <command>svn checkout</command> to
create the sort of nested working copy structure you are trying
to achieve. But if this layout is important for everyone who
@@ -2344,6 +2406,10 @@
<firstterm>externals definitions</firstterm>. An externals
definition is a mapping of a local directory to the
URL—and possibly a particular revision—of a
+ <!-- this section contains no examples of specifying a revision
+ in an externals definition; it needs some. And given the second
+ <tip> below, perhaps that "possibly" should be changed to
+ something stronger, like "ideally". -->
versioned directory. In Subversion, you declare externals
definitions in groups using the <literal>svn:externals</literal>
property. You can create or modify this property using
@@ -2352,7 +2418,7 @@
/>). It can be set on any versioned directory, and its value is
a multi-line table of subdirectories (relative to the versioned
directory on which the property is set), optional revision
- flags, and a fully qualified, absolute Subversion repository
+ flags, and fully qualified, absolute Subversion repository
URLs.</para>
<screen>
@@ -2369,22 +2435,22 @@
once one person has made the effort to define those nested
working copy checkouts, no one else has to
bother—Subversion will, upon checkout of the original
- working copy, also checkout the external working copies.</para>
+ working copy, also check out the external working copies.</para>
- <note>
+ <warning>
<para>The relative target subdirectories of externals
- definitions needn't already exist on your or other users'
+ definitions <emphasis>must not</emphasis> already exist on your
or other users'
systems—Subversion will create them when it checks out
- the external working copy. In fact, you should
- <emphasis>not</emphasis> try to use externals definitions to
- populate directories that are already under version
- control.</para>
- </note>
+ the external working copy.</para>
+ <!-- true. Perhaps it'd be nice to show what happens if the
+ subdirectory already exists, and how to recover. I've seen
+ this problem on IRC. -->
+ </warning>
<para>Note the previous externals definition example. When
someone checks out a working copy of the
<filename>calc</filename> directory, Subversion also continues
- to checkout the items found in its externals definition.</para>
+ to check out the items found in its externals definition.</para>
<screen>
$ svn checkout http://svn.example.com/repos/calc
@@ -2424,7 +2490,7 @@
</tip>
<tip>
- <para>You should strongly consider using explicit revision
+ <para>You should seriously consider using explicit revision
numbers in all of your externals definitions. Doing so means
that you get to decide when to pull down a different snapshot
of external information, and exactly which snapshot to pull.
@@ -2449,7 +2515,7 @@
themselves.</para>
<para>The support that exists for externals definitions in
- Subversion today can be a little misleading, though. First, an
+ Subversion today (i.e., through version 1.4.x) is less than ideal,
though. First, an
externals definition can only point to directories, not files.
Second, the externals definition cannot point to relative paths
(paths like <filename>../../skins/myskin</filename>). Third, the
@@ -2513,10 +2579,10 @@
$
</screen>
- <para>Also, the fact that externals definitions use absolute URLs
+ <para>Also, the absolute URLs that externals definitions use
can cause problems with repositories that are available via
multiple URL schemes. For example, if your Subversion server is
- configured to allow everyone to checkout the repository over
+ configured to allow everyone to check out the repository over
<literal>http://</literal> or <literal>https://</literal>, but
only allow commits to come in via <literal>https://</literal>,
you have an interesting problem on your hands. If your
@@ -2533,9 +2599,8 @@
re-parented.</para>
<para>Finally, there might be times when you would prefer that
- <command>svn</command> subcommands would not recognize or
- otherwise operate on the external working copies created as the
- result of externals definition handling. In those instances,
+ <command>svn</command> subcommands would not recognize, or
+ otherwise operate upon, the external working copies. In those
instances,
you can pass the <option>--ignore-externals</option> option to
the subcommand.</para>
</sect1>
@@ -2546,7 +2611,7 @@
<sect1 id="svn.advanced.pegrevs">
<title>Peg and Operative Revisions</title>
- <para>We make use of the ability to copy, move, rename, and
+ <para>We copy, move, rename, and
completely replace files and directories on our computers all
the time. And your version control system shouldn't get in the
way of your doing these things with your version-controlled
@@ -2593,7 +2658,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
@@ -2617,7 +2682,7 @@
later rename the thing back to <filename>concept</filename> for
some reason.</para>
- <para>When scenarios like these occur, attempting to instruct
+ <para>In scenarios like these, attempting to instruct
Subversion to work with these re-used paths can be a little like
instructing a motorist in Chicago's West Suburbs to drive east
down Roosevelt Road and turn left onto Main Street. In a mere
@@ -2669,8 +2734,7 @@
<para>The Subversion command-line performs the peg revision
algorithm any time it needs to resolve possible ambiguities in
the paths and revisions provided to it. Here's an example of
- such an invocation for the purposes of illustrating that
- algorithm.</para>
+ such an invocation:</para>
<screen>
$ svn <replaceable>command</replaceable> -r <replaceable>OPERATIVE-
REV</replaceable> item@<replaceable>PEG-REV</replaceable>
@@ -2687,6 +2751,9 @@
</listitem>
<listitem>
+ <!-- might not the algorithm also trace the object's history
+ -forwards-? That is, if the operative revision is greater
+ than the peg revision? -->
<para>Trace the object's history backwards (through any
possible renames) to its ancestor in the
revision <replaceable>OPERATIVE-REV</replaceable>.</para>
@@ -2725,8 +2792,8 @@
<filename>IDEA</filename> file looked like back in revision 1.
But Subversion needs to know if we are asking about how the
<emphasis>current</emphasis> file looked back in revision 1, or
- are we asking for the contents of whatever file lived at
- <filename>concepts/IDEA</filename> in revision 1? Certainly
+ if we are asking for the contents of whatever file lived at
+ <filename>concepts/IDEA</filename> in revision 1. Certainly
those questions have different answers, and because of peg
revisions, you can ask either of them. To find out how the
current <filename>IDEA</filename> file looked in that old
@@ -2753,6 +2820,9 @@
revision currently present in the working copy) when applied to
working copy paths, and of <literal>HEAD</literal> when applied
to URLs.</para>
+ <!-- "generally"? Don't they always? If they don't always, then
+ please tell me _exactly_ when they don't, and why not. And
+ anyway, didn't we say just this above, at line 2783? -->
<para>The perceptive reader is probably wondering at this point if
the peg revision syntax causes problems for working copy paths
@@ -2770,6 +2840,9 @@
even applies to paths that end in an at sign—you would
use <literal>filename@@</literal> to talk about a file named
<filename>filename@</filename>.</para>
+ <!-- nifty. Does this also work around the bug described in
+ http://subversion.tigris.org/issues/show_bug.cgi?id=2349? If so,
+ it might be good to mention that. -->
<para>Let's ask the other question, then—in revision 1, what
were the contents of whatever file occupied the address
@@ -2879,8 +2952,8 @@
attempts to access a URL, and depending on the URL schema, a
particular protocol is used to contact the server (see <xref
linkend="svn.basic.in-action.wc.sb-1"/>).</para>
-
- <tip><para>Users can run <command>svn --version</command> to see
+ <!-- is it "schema" or "scheme"? 'svn - -version' says "scheme"
-->
+ <tip><para>Run <command>svn --version</command> to see
which URL schemas and protocols the client knows how to
use.</para>
</tip>
@@ -2914,6 +2987,8 @@
never issued an authentication challenge), then the revision's
<literal>svn:author</literal> property is empty.
<footnote>
+ <!-- but it's not on http://subversion.tigris.org/faq.html.
+ Should it be?-->
<para>This problem is actually a FAQ, resulting from
a misconfigured server setup.</para>
</footnote>
@@ -2926,8 +3001,8 @@
<title>Client Credentials Caching</title>
<para>Many servers are configured to require authentication on
- every request. This can become a big annoyance to users, who
- are forced to type their passwords over and over again.
+ every request. This would be a big annoyance to users, if
+ they were forced to type their passwords over and over again.
Fortunately, the Subversion client has a remedy for
this—a built-in system for caching authentication
credentials on disk. By default, whenever the command-line
@@ -2957,7 +3032,7 @@
concerns, and so Subversion works with available mechanisms
provided by the operating system and environment to try to
minimize the risk of leaking this information. Here's a
- breakdown of what this means on for users on the most common
+ breakdown of what this means for users on the most common
platforms:</para>
<itemizedlist>
@@ -3031,8 +3106,12 @@
<literal>no</literal>. This will prevent the storing of
credentials used in any Subversion interactions you perform on
the affected computer. This can be extended to cover all
- users on the computer, too, by modifying the system-wide
- runtime configuration area.</para>
+ <!-- have we mentioned this system-wide runtime configuration
+ area before? I don't think so. It would be good to link to
+ the section of the book that discusses it in detail
+ (svn.advanced.confarea.layout) --> users on the computer, too,
+ by modifying the system-wide runtime configuration
+ area.</para>
<screen>
[auth]
Index: ch09-reference.xml
===================================================================
--- overall (revision 0)
+++ overall (revision 0)
@@ -0,0 +1,19 @@
+* I changed many <warning>s to <note>s, and vice-versa. I couldn't
+ find any document that explains when we should use which, so I made
+ up my own rule: warnings are for suggestions which, if they're not
+ followed, might lead to data loss (e.g. doing "svn revert" when
+ you've got un-checked-in changes). notes and tips are just about
+ saving time or typing. (Frankly I don't know what the difference is
+ between notes and tips).
+
+* I can't believe I'm saying this, but: the jokes in footnotes are
+ distracting. I always follow footnotes to see if I'm missing some
+ interesting bit of information, and it's disappointing -- and a
+ slight waste of my time -- when it turns out that they're just
+ jokes. If _all_ the footnotes in this book were jokes, that'd be
+ OK, since I'd come to realize that. But many of the footnotes in
+ this book contain useful straight information. It's hard for me to
+ make this criticism, because I _like_ this book's light tone, and
+ the jokes. I just wish they weren't in the footnotes. Put them in
+ parentheses, maybe? For some reason they don't bother me when
+ they're part of the main text.
--- ch04-branching-and-merging.xml (revision 2735)
+++ ch04-branching-and-merging.xml (working copy)
@@ -98,6 +98,12 @@
place.</para>
<para>Let's say that you've been given the task of performing a
+ <!-- this is probably silly, but I would hesitate to suggest
+ that someone use branches to "reorganize" a product, as long as
+ issue 2685 is open. I'd instead simply say "rewrite" or "make
+ real big changes to". (I now notice that you address precisely
+ this bug below, in the section
+ svn.branchmerge.copychanges.bestprac.moves; excellent) -->
radical reorganization of the project. It will take a long time
to write, and will affect all the files in the project. The
problem here is that you don't want to interfere with Sally, who
@@ -218,7 +224,10 @@
Committed revision 341.
</screen>
- <para>There's really no difference between these two methods.
+ <!-- but from the user's point of view, there's a HUGE
+ difference: the first method requires that they download a
+ potentially large amount of data from the repository. -->
+ <para>From the repository's point of view, there's really no
difference between these two methods.
Both procedures create a new directory in revision 341, and
the new directory is a copy of
<filename>/calc/trunk</filename>. This is shown in
@@ -250,9 +259,9 @@
duplicate any data. Instead, it creates a new directory
entry that points to an <emphasis>existing</emphasis> tree.
If you're a Unix user, this is the same concept as a
- hard-link. As further changes are made to files and
+ <quote>hard link</quote>. As further changes are made to files
and
directories beneath the copied directory, Subversion
- continues to employ this hard-link concept where it can. It
+ continues to employ this <quote>hard link</quote> concept where
it can. It
only duplicates data when it is necessary to disambiguate
different versions of objects.</para>
@@ -266,6 +275,7 @@
more about this, visit Subversion's website and read about
the <quote>bubble up</quote> method in Subversion's design
documents.)</para>
+ <!-- why not include a link to doc/design/server.xml? -->
<para>Of course, these internal mechanics of copying and
sharing data are hidden from the user, who simply sees
@@ -295,8 +305,8 @@
<para>There's nothing special about this working copy; it simply
mirrors a different directory in the repository. When you
- commit changes, however, Sally won't ever see them when she
- updates. Her working copy is of
+ commit changes, however, Sally won't see them when she
+ updates, because her working copy is of
<filename>/calc/trunk</filename>. (Be sure to read <xref
linkend="svn.branchmerge.switchwc"/> later in this chapter: the
<command>svn switch</command> command is an alternate way of
@@ -630,7 +640,7 @@
way to represent changes to <emphasis>trees</emphasis>, such
as the addition, removal, or renaming of files and
directories. Nor can the <command>patch</command> program
- notice changes to property changes. If Sally's change had,
+ notice changes to properties. If Sally's change had,
say, added a new directory, the output of <command>svn
diff</command> wouldn't have mentioned it at
all. <command>svn diff</command> only outputs the limited
@@ -847,7 +857,9 @@
<para>The <option>--dry-run</option> option doesn't actually
apply any local changes to the working copy. It only shows
status codes that <emphasis>would</emphasis> be printed in a
- real merge. It's useful for getting a <quote>high
+ real merge. <!-- I have a sneaking suspicion that - -dry-run
+ doesn't always announce every status code, but I can't prove
+ it :-( --> It's useful for getting a <quote>high
level</quote> preview of the potential merge, for those
times when running <command>svn diff</command> gives too
much detail.</para>
@@ -884,7 +896,7 @@
compare the wrong two trees, creating a delta that doesn't
apply cleanly. <command>svn merge</command> will do its
best to apply as much of the delta as possible, but some
- parts may be impossible. Just like the Unix
+ parts may be impossible. Just as the Unix
<command>patch</command> command sometimes complains about
<quote>failed hunks</quote>, <command>svn merge</command>
will complain about <quote>skipped targets</quote>:</para>
@@ -909,9 +921,15 @@
likely comparing the wrong two trees; they're the classic
sign of user error. When this happens, it's easy to
recursively revert all the changes created by the merge
- (<command>svn revert --recursive</command>), delete any
- unversioned files or directories left behind after the
- revert, and re-run <command>svn merge</command> with
+ (<command>svn revert --recursive</command>),
+
+ <!-- Why must we delete unversioned stuff? And can you
+ suggest a convenient method of doing that, when there are a
+ lot of unversioned objects?-->
+ delete any unversioned files or directories left behind
+ after the revert,
+
+ and re-run <command>svn merge</command> with
different arguments.</para>
<para>Also notice that the previous example shows a conflict
@@ -954,6 +972,7 @@
describe the relationship between two objects in a
repository: if they're related to each other, then one
object is said to be an ancestor of the other.</para>
+ <!-- might they not instead merely have a _common_ ancestor? -->
<para>For example, suppose you commit revision 100, which
includes a change to a file <filename>foo.c</filename>.
@@ -970,8 +989,8 @@
<para>The reason for bringing this up is to point out an
important difference between <command>svn diff</command> and
- <command>svn merge</command>. The former command ignores
- ancestry, while the latter command is quite sensitive to it.
+ <command>svn merge</command>: <command>svn diff</command>
ignores
+ ancestry, while <command>svn merge</command> is quite sensitive
to it.
For example, if you asked <command>svn diff</command> to
compare revisions 99 and 102 of <filename>foo.c</filename>,
you would see line-based diffs; the <literal>diff</literal>
@@ -996,9 +1015,8 @@
linkend="svn.advanced.vendorbr"/>).
If you asked <command>svn merge</command> to compare the two
trees, you'd see the entire first tree being deleted,
- followed by an add of the entire second tree!</para>
-
- <para>In these situations, you'll want <command>svn
+ followed by an add of the entire second tree!
+ In these situations, you'll want <command>svn
merge</command> to do a path-based comparison only, ignoring
any relations between files and directories. Add the
<option>--ignore-ancestry</option> option to your merge
@@ -1038,7 +1056,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 +1082,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 +1419,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
@@ -1721,8 +1739,8 @@
<para>The <command>svn switch</command> command transforms an
existing working copy to reflect a different branch. While this
- command isn't strictly necessary for working with branches, it
- provides a nice shortcut to users. In our earlier example,
+ command isn't strictly necessary for working with branches, it's
+ a nice shortcut. In our earlier example,
after creating your private branch, you checked out a fresh
working copy of the new repository directory. Instead, you can
simply ask Subversion to change your working copy of
@@ -1747,7 +1765,11 @@
<para>After <quote>switching</quote> to the branch, your working
copy is no different than what you would get from doing a fresh
- checkout of the directory. And it's usually more efficient to
+ checkout of the directory.
+ <!-- not true -- if the original wc has un-checked-in changes,
+ "switching" will preserve them, whereas a fresh checkout of
+ course won't have them. -->
+ And it's usually more efficient to
use this command, because often branches only differ by a small
degree. The server sends only the minimal set of changes
necessary to make your working copy reflect the branch
@@ -1755,7 +1777,7 @@
<para>The <command>svn switch</command> command also takes a
<option>--revision</option> (<option>-r</option>) option, so you
- need not always move your working copy to the <quote>tip</quote>
+ need not always move your working copy to the
<literal>HEAD</literal>
of the branch.</para>
<para>Of course, most projects are more complicated than our
@@ -1982,6 +2004,11 @@
snapshot of your working copy—mixed revisions, URLs,
and all.</para>
+ <!-- I can't remember the details, but I'm _certain_ that Ben
+ has advised against making a branch this way. Perhaps a warning
+ would be in order here: "this technique works fine for tags, but
+ beware if you make a branch this way, you can run into trouble
+ when you later try to merge ..." -->
<para>Other users have found interesting uses for this feature.
Sometimes there are situations where you have a bunch of local
changes made to your working copy, and you'd like a
@@ -1990,7 +2017,7 @@
tree changes, symlink changes or changes in properties), you can
instead use <command>svn copy</command> to <quote>upload</quote>
your working copy to a private area of the repository. Your
- collaborator can then either checkout a verbatim copy of your
+ collaborator can then either check out a verbatim copy of your
working copy, or use <command>svn merge</command> to receive
your exact changes.</para>
@@ -2047,6 +2074,7 @@
<para>Of course, you're free to ignore these common layouts.
You can create any sort of variation, whatever works best for
you or your team. Remember that whatever you choose, it's not
+ <!-- the caveat about 2685 applies here -->
a permanent commitment. You can reorganize your repository at
any time. Because branches and tags are ordinary directories,
the <command>svn move</command> command can move or rename
@@ -2216,7 +2244,7 @@
the vendor's data that you decide to absorb into your project is
called a <firstterm>vendor drop</firstterm>.</para>
- <para>Vendor branches provide two key benefits. First, by storing
+ <para>Vendor branches provide two benefits. First, by storing
the currently supported vendor drop in your own version control
system, the members of your project never need to question
whether they have the right version of the vendor's data. They
@@ -2308,7 +2336,7 @@
changes made to libcomplex between versions 1.0 and 1.1 to our
modified copy of it.</para>
- <para>To perform this upgrade, we checkout a copy of our vendor
+ <para>To perform this upgrade, we check out a copy of our vendor
branch, and replace the code in the
<filename>current</filename> directory with the new libcomplex
1.1 source code. We quite literally copy new files on top of
@@ -2441,8 +2469,11 @@
<para>You can indicate that you'd like
<command>svn_load_dirs.pl</command> to tag the new vendor drop
by passing the <option>-t</option> command-line option and
- specifying a tag name. This tag is another URL relative to
- the first program argument.</para>
+ specifying a tag name. <!-- a tad unclear; I had to read it
+ twice to understand it. Maybe instead say something like "The
+ tag directory will be created under the directory specified by
+ the first program argument."--> This tag is another URL
+ relative to the first program argument.</para>
<screen>
$ svn_load_dirs.pl -t libcomplex-1.1 \
@@ -2459,8 +2490,8 @@
one version and not the other, and the script will perform the
new import without incident. If, however, there are
discrepancies in the file layouts between versions,
- <command>svn_load_dirs.pl</command> will prompt you for how
- you would like to resolve those differences. For example, you
+ <command>svn_load_dirs.pl</command> will ask you how
+ to resolve those differences. For example, you
will have the opportunity to tell the script that you know
that the file <filename>math.c</filename> in version 1.0 of
libcomplex was renamed to <filename>arithmetic.c</filename> in
}}}
--
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/62>
SvnBook <http://svnbook.red-bean.com/>
More information about the svnbook-dev
mailing list