Changelist analogy confusing

James Kistruck James.Kistruck at
Thu Aug 14 10:22:54 CDT 2008


Thanks for the response.  I take your point about it being a good
forward-looking analogy if multiple changelists per file will be coming
at some point.  I can't immediately see how to make a pleasant UI for
splitting out multiple changes in the same file when you come to diff or
commit a change, but that's a different problem!

If I can trespass on your time some more, I noticed another instance
where the book has a simple analogy, followed up some paragraphs later
with a comment saying that the analogy isn't right.  In chapter 4, it
explains how after a switch, "your working copy is no different from
what you would get from doing a fresh checkout of the directory".  That
is wrong, of course, because the switch preserves the local changes from
the old branch, and a fresh checkout to a new location wouldn't have
them - something which is pointed out later on in the same section.

In both these cases adding a small rider right up front, such as "plus
your local changes - see later" or "though at the moment you are
restricted to one tag per file" would have helped me.  As it was, I
immediately went back to other parts of the book to check my
understanding before I read on to the bit that explained the limitation
/ clarified the simple statement.

But hey, I haven't written a book, nor am I an editor, so maybe that's
bad style :-)


-----Original Message-----
From: svnbook-dev-bounces at
[mailto:svnbook-dev-bounces at] On Behalf Of C. Michael Pilato
Sent: 14 August 2008 15:48
To: James Kistruck
Cc: svnbook-dev at
Subject: Re: Changelist analogy confusing

James Kistruck wrote:
> Hi,
> Sorry, I don't have a patch for this - I'm just getting started with
> I find Gmail tags a confusing analogy for changelists (Ch.3).  The 
> whole point of tags (over folders) is that you can have a 1:M mapping 
> between content and groupings.  One piece of content can be a member 
> of many groups, through its set of tags.
> Changelists don't allow that.. They enforce a 1:1 mapping between 
> content and groupings, so that a given piece of content (file) exists 
> in at most one group (changelist).  This is exactly like a directory 
> hierarchy, or the "files and folders paradigm" that Ch.3 suggests has 
> been surpassed by changelists.
> A more helpful analogy might be that of separating music tracks into 
> genres.  Any given track can be a member of only one genre (in most 
> virtual jukeboxes, if not in real life!), but there is no implicit 
> ordering of genres.  You can view your tracks by genre, but that 
> doesn't prevent you viewing them in another way (say by artist).
> James.

James, thanks for the feedback.  Sorry the analogy doesn't work for you.

Part of the reason I choose the tags/labels analogy was to be a little
forward-looking.  Nobody believes that the limitation of a single
changelist per file in Subversion is altogether ideal.  So by describing
the state of the feature as most of the Subversion developers think of
it, plus the current limitation it carries, the text more accurately
describes the intended design of the feature.

The decision to use this analogy has also been affirmed by the various
in-person encounters I've had with folks just hearing about the feature
(I've given multiple public talks about Subversion 1.5's features).
They "get" the analogy, even with the current limitation.

That's not to say anything negative about you, of course -- most
analogies are imperfect because the recipient has mental baggage around
the analogous concept that the producer of the analogy didn't
anticipate.  For example, your jukebox genre analogy doesn't hit me
perfectly because the available genres are often pre-defined, not able
to be arbitrarily named like changelists or labels or tags can.

C. Michael Pilato <cmpilato at> |

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

svnbook-dev mailing list
svnbook-dev at

More information about the svnbook-dev mailing list