Review of Chapter 2: Basic Usage

C. Michael Pilato cmpilato at red-bean.com
Fri Feb 23 00:38:34 CST 2007


Here's my quicky review of chapter 2.  Good job, Fitz.  It's nasty work
talking about the various client subcommands and their varied uses.

Running with the previously made agreement that, to the degree possible,
we won't try to mention concepts earlier in the book than their proper
introduction, there are some issues that arise fairly early in the chapter.

   * The section on getting data into the repository is introducing 'svn
     import' and 'svn add'.  No problem with 'svn import', but the part
     about 'svn add' requires a working copy (though we've not
     mentioned how to get one yet) and casually mentions 'svn commit'
     (without further explanation -- though, at least in this case
     'commit' was mentioned in Chapter 1).

     Perhaps we should simply explain 'svn import' here, and note that
     later in the chapter we'll talk about other ways to add files to
     version control (since we do cover 'add' again later as part of
     the "making changes" section).

   * Shortly after introducing checkouts, we smack users with "Disabling
     Password Caching", which is a pretty hefty topic.  Seems that
     Chapter 1 (where fundamentals are discussed) should mention the
     fundamental fact that Subversion can operate over a network and
     supports authentication.  In fact, Chapter 1 does talk about
     a client/server model, but is using the terms "Repository" and
     "Client".  It's really kinda wierd that way.

I don't like that we explain each and every status code in this chapter.
 That's reference material.  Choosing some common examples to
demonstrate is fine, but the exhaustive list need live only in the
reference.  The current state is a hugely imbalanced attention to the
finer details of 'svn status' compared to the level of exposition
provided for the other subcommands.  And it also means we have several
links to later chapters because some of the status codes have more
advanced meanings.

I've similar complaints about the exhaustive list of 'svn update' output
codes.

The variable list section containing "File changes" and "Tree changes"
is unnecessary.  I'd just merge the info there into the two paragraphs
which follow it.

I think we should promote 'svn mkdir' as a commonly used operation.  It
certainly is for me, but more importantly, there are multiple references
to it in the "Basic Work Cycle" section that might make more sense if it
was quickly explained alongside add, delete, copy and move.

"Earlier in this chapter, we said that you have to commit any changes
that you make in order for the repository to reflect these changes.
That's not entirely true—there are some use cases that immediately
commit tree changes to the repository."  This seems contradictory --
"earlier we said you have to commit, but we lied, because sometimes you
can commit another way".  I know what is meant here; I don't think our
readers will.

"Look Ma!  No Network!" begins, "All three of these commands (svn
status, svn diff, and svn revert) can be used without any network
access..."  Sidebars should be self-sufficient, able to be read
independent of the surrounding chapter context.  But "these commands"
has a dependency on that context.  Remember that in print, sidebars may
get moved around so that they fit nicely on the printed page -- the
context in our HTML and PDF renderings isn't guaranteed to be the same
context in the printed book.

The footnote that begins "Subversion uses its internal diff engine,
which produces unified diff format, by default." is a little out of
date.  In Subversion 1.4.0, you can get whitespace-ignoring diffs
without using an external diff tool.  Maybe pick a different peculiarity
of GNU diff to highlight?

"Undoing Working Changes" begins, "Now suppose you see the above diff
output..."  First, we can't say "above" -- that implies page
positioning.  But more importantly, it binds the section to the previous
one, and this is something we try to avoid.  This section doesn't need
to refer to a diff in a previous section, because "setting up" the
example is a really trivial task.  "Suppose while viewing the output of
'svn diff' you determine that all the changes you made to a particular
file are mistakes.  Maybe you shouldn't have changed the file at all, or
perhaps it would be easier to make different changes starting from scratch."

"You're probably wondering why we don't just use svn update --revision
to update the file to the older revision.... it's sometimes just easier
to look at an older version of a file in its entirety than to look only
at the differences between it and another revision."  These two
sentences don't really make sense.  'svn update' isn't about viewing
diffs, and *would* provide a way to see the old version of the file in
its entirety.

OFF-TOPIC:

$ svn list --verbose http://svn.collab.net/repos/svn
  20620 harry            1084 Jul 13  2006 README
  23339 harry                 Feb 04 01:40 branches/
  21282 sally                 Aug 27 09:41 developer-resources/
  23198 harry                 Jan 23 17:17 tags/
  23351 sally                 Feb 05 13:26 trunk/

Do we know why sometimes a year is printed, and sometimes a timestamp is
printed?  I would have guessed "any time the date is not in the current
year, a year is printed" but that doesn't appear to be true.

I'm not completely thrilled with the relationship of this chapter to the
other ones.  That's not anybody's fault, really -- it's extremely
difficult to present so many interrelated concepts in building-blocks
order.  But I'll start a different thread around that subject.

-- 
C. Michael Pilato <cmpilato at red-bean.com>

"The Christian ideal has not been tried and found wanting.  It has
 been found difficult; and left untried."  -- G. K. Chesterton




More information about the svnbook-dev mailing list