[svnbook commit] r2930 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Sat Dec 15 23:57:25 CST 2007
Author: cmpilato
Date: Sat Dec 15 23:57:23 2007
New Revision: 2930
Log:
Add initial documentation for the changelists feature. This is a
reworking of a blog post I wrote for CollabNet's Subversion blog,
http://blogs.open.collab.net/svn/2007/07/one-quality-of-.html
reproduced here as part of the book with the permission of Guido
Haarmans, the CollabNet Marketing dude for whom the original blog post
was composed.
Modified:
trunk/src/en/book/ch03-advanced-topics.xml
Modified: trunk/src/en/book/ch03-advanced-topics.xml
==============================================================================
--- trunk/src/en/book/ch03-advanced-topics.xml (original)
+++ trunk/src/en/book/ch03-advanced-topics.xml Sat Dec 15 23:57:23 2007
@@ -2912,8 +2912,348 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
- <sect1 id="svn.serverconfig.netmodel">
+ <sect1 id="svn.advanced.changelists">
+ <title>Changelists</title>
+
+ <para>It is commonplace for a developer to find himself working at
+ any given time on multiple different, distinct changes to a
+ particular bit of source code. This isn't necessarily due to
+ poor planning or some form of digital masochism. A software
+ engineer often spots bugs in his peripheral vision while working
+ on some nearby chunk of source code. Or perhaps he's halfway
+ through some large change when he realizes the solution he's
+ working on is best committed as several smaller logical units.
+ Often, these logical units aren't nicely contained in some
+ module, safely separated from other changes. The units might
+ overlap, modifying different files in the same module, or even
+ modifying different lines in the same file.</para>
+
+ <para>There are various work methodologies that developers can
+ employ to keep these logical changes organized. Some use
+ separate working copies of the same repository to hold each
+ individual change-in-progress. Others might choose to create
+ short-lived feature branches in the repository, and use a single
+ working copy that is constantly switched to point to one such
+ branch or another. Still others use <command>diff</command> and
+ <command>patch</command> tools to backup and restore uncommitted
+ changes to and from patchfiles associated with each change.
+ Each of these methods has its pros and cons, and to a large
+ degree, the details of the changes being made heavily influence
+ the methodology used to distinguish them.</para>
+
+ <para>Subversion 1.5 brings a new
+ <firstterm>changelists</firstterm> feature which adds yet
+ another method to the mix. Changelists are basically arbitrary
+ labels applied to working copy files for the express purpose of
+ associating multiple files together. Users of many of Google's
+ software offerings are familiar with this concept already. For
+ example, Gmail doesn't provide the traditional folders-based
+ email organization mechanism. In <ulink
+ url="http://mail.google.com/">Gmail</ulink>, you apply arbitrary
+ labels to emails, and multiple emails can be said to be part of
+ the same group if they happen to share a particular label.
+ Viewing only a group of similarly labeled emails then becomes a
+ simple user interface trick. Many other Web 2.0 sites have
+ similar mechanisms—consider the <quote>tags</quote> used
+ by sites like <ulink
+ url="http://www.youtube.com/">YouTube</ulink> and <ulink
+ url="http://www.flickr.com/">Flickr</ulink>,
+ <quote>categories</quote> applied to blog posts, and so on.
+ Folks understand today that organization of data is critical,
+ but that how that data is organized needs to be a flexible
+ concept. The old files-and-folders paradigm is too rigid for
+ some applications.</para>
+
+ <para>Subversion's changelist support allows you to create
+ changelists by applying labels to files you want to be
+ associated with that changelist, remove those labels, and limit
+ the scope of the files on which its subcommands operate to only
+ those bearing a particular label. In this section, we'll look
+ in detail at how to do these things.</para>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.changelists.creating">
+ <title>Creating and Modifying Changelists</title>
+
+ <para>You can create, modify, and delete changelists using the
+ <command>svn changelist</command> command. More accurately,
+ you use this command to set or unset the changelist
+ association of a particular working copy file. A changelist
+ is effectively created the first time you label a file with
+ that changelist; it is deleted when you remove that label from
+ the last file which had it. Let's examine a usage scenario
+ which demonstrates these concepts.</para>
+
+ <para>Harry is fixing some bugs in the calculator application's
+ mathematics logic. His work leads him to change a couple of
+ files.</para>
+
+ <screen>
+$ svn status
+M integer.c
+M mathops.c
+$
+</screen>
+
+ <para>While testing his bug fix, Harry notices that his changes
+ bring to light a tangentially related bug in the user
+ interface logic found in <filename>button.c</filename>. Harry
+ decides that he'll go ahead and fix that bug, too, as a
+ separate commit from his math fixes. Now, in a small working
+ copy with only a handful of files and few logical changes,
+ Harry can probably keep his two logical change groupings
+ mentally organized without any problem. But today he's going
+ to use Subversion's changelists feature as a special favor to
+ the authors of this book.</para>
+
+ <para>Harry first creates a changelist and associates with it
+ the two files he's already changed. He does this by using the
+ <command>svn changelist</command> command to assign the same
+ arbitrary changelist name to those files.</para>
+
+ <screen>
+$ svn changelist math-fixes integer.c mathops.c
+Path 'integer.c' is now a member of changelist 'math-fixes'.
+Path 'mathops.c' is now a member of changelist 'math-fixes'.
+$ svn status
+
+--- Changelist 'math-fixes':
+M integer.c
+M mathops.c
+$
+</screen>
+
+ <para>As you can see, the output of <command>svn
+ status</command> reflects this new grouping.</para>
+
+ <para>Harry now sets off to fix the secondary UI problem. Since
+ he knows which file he'll be changing, he assigns that path to
+ a changelist, too. Unfortunately, Harry careless assigns this
+ third file to the same changelist as the previous two files.</para>
+
+ <screen>
+$ svn changelist math-fix button.c
+Path 'button.c' is now a member of changelist 'math-fixes'.
+$ svn status
+
+--- Changelist 'math-fixes':
+ button.c
+M integer.c
+M mathops.c
+$
+</screen>
+
+ <para>Fortunately, Harry catches his mistake. At this point,
+ he has two options. He can remove the changelist association
+ from button.c, and then assign a different changelist
+ name:</para>
+
+ <screen>
+$ svn changelist --remove button.c
+Path 'button.c' is no longer a member of a changelist.
+$ svn changelist ui-fix button.c
+Path 'button.c' is now a member of changelist 'ui-fix'.
+$
+</screen>
+
+ <para>Or, he can skip the removal and just assign a new
+ changelist name. In this case, Subversion will first warn
+ Harry that <filename>button.c</filename> is being removed from
+ the first changelist:</para>
+
+ <screen>
+$ svn changelist ui-fix button.c
+svn: warning: Removing 'button.c' from changelist 'math-fixes'.
+Path 'button.c' is now a member of changelist 'ui-fix'.
+$ svn status
+
+--- Changelist 'ui-fix':
+ button.c
+
+--- Changelist 'math-fixes':
+M integer.c
+M mathops.c
+$
+</screen>
+
+ <para>Harry now has two distinct changelists present in his
+ working copy, and <command>svn status</command> will group its
+ output according to these changelist determinations. Notice
+ that even though Harry hasn't yet modified
+ <filename>button.c</filename>, it still shows up in the output
+ of <command>svn status</command> as interesting because it has
+ a changelist assignment. Changelists can be added to and
+ removed from files at any time, regardless of whether or not
+ they contain local modifications.</para>
+
+ <para>Harry now fixes the user interface problem in
+ <filename>button.c</filename>.</para>
+
+ <screen>
+$ svn status
+
+--- Changelist 'ui-fix':
+M button.c
+
+--- Changelist 'math-fixes':
+M integer.c
+M mathops.c
+$
+</screen>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.changelists.asfilters">
+ <title>Changelists as Operation Filters</title>
+
+ <para>The visual grouping that Harry sees in the output of
+ <command>svn status</command> as shown in our previous section
+ is nice, but not entirely useful. The
+ <command>status</command> command is but one of many
+ operations that he might wish to perform on his working copy.
+ Fortunately, many of Subversion's other operations understand
+ how to operate on changelists via the use of the
+ <option>--changelist</option> option.</para>
+
+ <para>When provided with a <option>--changelist</option> option,
+ Subversion commands will limit the scope of their operation to
+ only those files to which a particular changelist name is
+ assigned. If Harry now wants to see the actual changes he's
+ made to the files in his <literal>math-fixes</literal>
+ changelist, he <emphasis>could</emphasis> explicitly list only
+ the files that make up that changelist on the <command>svn
+ diff</command> command line.</para>
+ <screen>
+$ svn diff integer.c mathops.c
+Index: integer.c
+===================================================================
+--- integer.c (revision 1157)
++++ integer.c (working copy)
+…
+Index: mathops.c
+===================================================================
+--- mathops.c (revision 1157)
++++ mathops.c (working copy)
+…
+$
+</screen>
+
+ <para>That works okay for a few files, but what if Harry's
+ change touched twenty or thirty files? That would be an
+ annoyingly long list of explicitly named files. Now that he's
+ using changelists, though, Harry can avoid explicitly listing
+ the set of files in his changelist from now on, and provide
+ instead just the changelist name.</para>
+
+ <screen>
+$ svn diff --changelist math-fixes
+Index: integer.c
+===================================================================
+--- integer.c (revision 1157)
++++ integer.c (working copy)
+…
+Index: mathops.c
+===================================================================
+--- mathops.c (revision 1157)
++++ mathops.c (working copy)
+…
+$
+</screen>
+
+ <para>And when it's time to commit, Harry can again use the
+ <option>--changelist</option> option to limit the scope of the
+ commit to files in a certain changelist. He might commit his
+ user interface fix by doing the following:</para>
+
+ <screen>
+$ svn ci -m "Fix a user interface bug found while working on math logic." \
+ --changelist ui-fix
+Sending button.c
+Transmitting file data .
+Committed revision 1158.
+$
+</screen>
+
+ <para>In fact, the <command>svn commit</command> command
+ provides a second changelists-related option:
+ <option>--keep-changelist</option>. Normally, changelist
+ assignments are removed from files after they are committed.
+ But if <option>--keep-changelist</option> is provided,
+ Subversion will leave the changelist assignment on the
+ committed (and now unmodified) files. In any case, committing
+ files assigned to one changelist leaves other changelists
+ undisturbed.</para>
+
+ <screen>
+$ svn status
+
+--- Changelist 'math-fixes':
+M integer.c
+M mathops.c
+$
+</screen>
+
+ <note>
+ <para>The <option>--changelist</option> option acts only as a
+ filter for Subversion command targets, and will not add
+ targets to an operation. For example, on a commit operation
+ specified as <command>svn commit /path/to/dir</command>, the
+ target is the directory <filename>/path/to/dir</filename>
+ and its children (to infinite depth). If you then add a
+ changelist specifier to that command, only those files in
+ and under <filename>/path/to/dir</filename> which are
+ assigned that changelist name will be considered as targets
+ of the commit—the commit will not include files
+ located elsewhere (such is in
+ <filename>/path/to/another-dir</filename>, regardless of
+ their changelist assignment, even if they are part of the
+ same working copy as the operation's target(s).</para>
+ </note>
+
+ <para>Even the <command>svn changelist</command> command accepts
+ the <option>--changelist</option> option. This allows you to
+ quickly and easily rename or remove a changelist.</para>
+
+ <screen>
+$ svn changelist math-bugs --changelist math-fixes
+svn: warning: Removing 'integer.c' from changelist 'math-fixes'.
+Path 'integer.c' is now a member of changelist 'math-bugs'.
+svn: warning: Removing 'mathops.c' from changelist 'math-fixes'.
+Path 'mathops.c' is now a member of changelist 'math-bugs'.
+$ svn changelist --remove --changelist math-bugs
+Path 'integer.c' is no longer a member of a changelist.
+Path 'mathops.c' is no longer a member of a changelist.
+$
+</screen>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.changelists.limitations">
+ <title>Changelist Limitations</title>
+
+ <para>Subversion's changelist feature is a handy tool for
+ grouping working copy files, but does have a few limitations.
+ Changelist are artifacts of a particular working copy, which
+ means that changelist assignments cannot be propogated to the
+ repository or otherwise shared with other users. Changelists
+ can only be assigned to files—Subversion doesn't
+ currently support the use of changelists with directories.
+ Finally, you can have at most one changelist assignment on a
+ given working copy file. Here is where the blog post category
+ and photo service tag analogies break down—if you find
+ yourself needing to assign a file to multiple changelists,
+ you're out of luck.</para>
+
+ </sect2>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.netmodel">
<title>Network Model</title>
<para>At some point, you're going to need to understand how your
More information about the svnbook-dev
mailing list