[svnbook] r4314 committed - For issue 5 ("Document svnmucc"), add a section to Chapter 3 about...

svnbook at googlecode.com svnbook at googlecode.com
Tue Jan 15 18:26:42 CST 2013

Revision: 4314
Author:   cmpilato at gmail.com
Date:     Tue Jan 15 16:26:34 2013
Log:      For issue 5 ("Document svnmucc"), add a section to Chapter 3 about
working-copy-less operations, and use it to introduce svnmucc.  Then,
stub out a section in the Chapter 9 Reference to cover this tool in

* en/book/ch03-advanced-topics.xml
   (svn.advanced.working-without-a-wc): New section.

* en/book/ch09-reference.xml
   (svn.ref.svnmucc): New section (or at least, placeholder there-for).



--- /trunk/en/book/ch03-advanced-topics.xml	Mon Jan 14 10:25:22 2013
+++ /trunk/en/book/ch03-advanced-topics.xml	Tue Jan 15 16:26:34 2013
@@ -4806,6 +4806,240 @@

+  <!-- =================================================================  
+  <!-- =================================================================  
+  <!-- =================================================================  
+  <sect1 id="svn.advanced.working-without-a-wc">
+    <title>Working Without a Working Copy</title>
+    <para>As we described in <xref linkend="svn.basic.in-action.wc"
+      />, the Subversion working copy is a sort of staging area where
+      a user can privately make changes to his or her versioned data
+      and then—when those changes are complete and ready for
+      sharing with others—commit them to the repository.  It
+      should come as no surprise, then, that most of the interaction
+      you will have with Subversion will be in the form of asking your
+      Subversion client to do <emphasis>something</emphasis> to one or
+      more items in a local working copy.  Even for those operations
+      which don't manipulate the working copy data itself (such
+      as <command>svn log</command>), it's often just easier to use a
+      working copy file or directory as a convenient target for that
+      operation.</para>
+    <para>Clearly, the typical approach to making changes to
+      your versioned data is via commits from a Subversion working
+      copy.  Fortunately, it's not the only way.  Users of Subversion
+      who need to make relatively simple changes to their versioned
+      data can do so without the overhead of checking out a working
+      copy.  We'll cover some of those supported operations in this
+      section.</para>
+    <!-- ===============================================================  
+    <sect2 id="svn.advanced.working-without-a-wc.svn">
+      <title>Remote command-line client operations</title>
+      <para>The Subversion command-line client supports a number of
+        operations which can be performed directly against repository
+        URLs in order to make simple changes without a working copy.
+        Some of these are described elsewhere in this book, but we
+        provide an exhaustive list of them here for your
+        convenience.</para>
+      <para>Perhaps the most obvious remote commit-like operation is
+        the <command>svn import</command> command.  We describe that
+        command in <xref linkend="svn.tour.importing.import" /> as
+        part of explaining how you can easily get a whole tree of
+        unversioned information into your Subversion repository so you
+        can start doing version-controlled operations on it.</para>
+      <para>The <command>svn mkdir</command> and <command>svn
+        delete</command> commands, when used with URL targets, are
+        also remote commit-type operations.  These allow the user to
+        create one or more new versioned directories or remove
+        (recursively) one or more versioned files or directories,
+        respectively, without the use of a working copy.  Each time
+        you issue one of these commands, the client communicates with
+        the server in a way that's similar to how it would describe
+        the commit of a directory added or of an item removed from the
+        working copy.  If there's no problem or conflict detected with
+        the requested operation, the server commits the additions or
+        removals in a single new revision.</para>
+      <para>You can use <command>svn copy</command> or <command>svn
+        move</command> with two URLs—a copy/move source and a
+        destination—to commit a copies and moves of files and
+        directories directly in the repository.  These operations tend
+        to be some of the most expensive ones when performed within a
+        working copy, but they complete in constant time when
+        performed remotely using repository URLs.  In fact,
+        the <command>svn copy</command> remote operation is commonly
+        used to create branches in Subversion, as we discuss later in
+        <xref linkend="svn.branchmerge.using.create" />.</para>
+      <para>As with the regular <command>svn commit</command> command,
+        you can supply a log message with any of these commands we've
+        discussed so far to describe the changes you're making.  Use
+        the <option>--file (-F)</option> or <option>--message
+        (-m)</option> option, or otherwise allow the client to prompt
+        you for the log message.</para>
+      <para>Finally, there are a number of operations related to
+        unversioned revision properties which can be performed
+        directly against the repository.  In fact, revision properties
+        are somewhat unique in this context, as they aren't stored in
+        the working copy and therefore <emphasis>must</emphasis> be
+        modified without working copy interaction.  See
+        <xref linkend="svn.advanced.props" /> for a more detailed
+        description of how to manage properties in Subversion.</para>
+    </sect2>
+    <!-- ===============================================================  
+    <sect2 id="svn.advanced.working-without-a-wc.svnmucc">
+      <title>Using svnmucc</title>
+      <para>One shortcoming of the remote commit operation support
+        offered in the command-line client is that you are essentially
+        limited to one operation—or, really, one type of
+        operation—per commit.  For example, it's perfectly
+        natural and supported to, say, use <command>svn
+        delete</command> followed by <command>svn mkdir</command>
+        within a working copy to replace an existing versioned
+        directory with a brand new one.  When you commit the results
+        of those operations, a single new revision is created in the
+        repository, and that revision carries the full replacement of
+        your directory.  You can't really do the same thing as remote
+        operations using the command-line client while still
+        preserving the it-happened-in-a-single-revision-ness of the
+        change—<command>svn
+        delete <replaceable>URL</replaceable></command> would create a
+        new revision that removed the directory; <command>svn
+        mkdir <replaceable>URL</replaceable></command> would generate
+        a second revision for the directory's re-creation.</para>
+      <para>Fortunately, Subversion provides a separate tool which
+        exists solely to allow users to string together a set of
+        remote operations and commit them as one atomic change.  That
+        tool is the <command>svnmucc</command> tool—the
+        Subversion Multiple URL Command Client:</para>
+      <informalexample>
+        <screen>
+$ svnmucc --help
+Subversion multiple URL command client
+usage: svnmucc ACTION...
+  Perform one or more Subversion repository URL-based ACTIONs, committing
+  the result as a (single) new revision.
+  cp REV URL1 URL2       : copy URL1 at REV to URL2
+  mkdir URL              : create new directory URL
+  mv URL1 URL2           : move URL1 to URL2
+  rm URL                 : delete URL
+  put SRC-FILE URL       : add or modify file URL with contents copied from
+                           SRC-FILE (use "-" to read from standard input)
+  propset NAME VAL URL   : set property NAME on URL to value VAL
+  propsetf NAME VAL URL  : set property NAME on URL to value from file VAL
+  propdel NAME URL       : delete property NAME from URL
+      </informalexample>
+      <para><command>svnmucc</command> has been a part of the Subversion
+        project's source code tree for many years
+        (as <command>mucc</command> for most of that time), but it was
+        only in Subversion 1.8 that it become a fully supported member
+        of the Subversion command-line tool suite.</para>
+      <para>Unlike <command>svn</command>, the functionality
+        that <command>svnmucc</command> offers isn't broken up into
+        subcommands.  Rather, you provide a list of actions and
+        operands in a single command line (or from a file stream, via
+        the <option>--extra-args (-X)</option> option).  Some of the
+        actions supported by <command>svnmucc</command> mimic those of
+        the command-line client.  You'll notice in the previous
+        command output actions such as <literal>cp</literal>,
+        <literal>mkdir</literal>, <literal>mv</literal>,
+        and <literal>rm</literal>, all of which are very similar to
+        the commands we mentioned in
+        <xref linkend="svn.advanced.working-without-a-wc.svn" />.  But
+        remember, the key difference here is that you can use any
+        number of these actions together in a single command
+        invocation, resulting in a single committed revision in the
+        repository.</para>
+      <para>Let's take our previous example of trying to simply
+        replace a remote directory.  Using <command>svnmucc</command>,
+        you would accomplish this as follows:</para>
+      <informalexample>
+        <screen>
+$ svnmucc rm http://svn.example.com/projects/sandbox \
+          mkdir http://svn.example.com/projects/sandbox \
+          -m "Replace my old sandbox with a fresh new one."
+r22 committed by harry at 2013-01-15T21:45:26.442865Z
+      </informalexample>
+      <para>Another action commonly performed
+        with <command>svnmucc</command> is the implementation of
+        a <quote>moving tag</quote><footnote><para>"Easy there,
+        cowboy!  Tags?!"  Yes, it's true that we don't really talk
+        about tags until <xref linkend="svn.branchmerge" />, but
+        trying to maintain linear introduction of terms and behaviors
+        in this book is <emphasis>really</emphasis>
+        hard!</para></footnote>, where a single tag name is recycled
+        to point to new snapshots of a codebase.  Some teams use such
+        a tag to identfy, for example, the latest stable snapshot of a
+        quickly evolving codebase.  Again, <command>svnmucc</command>
+        allows you to remove and re-create a moving tag in a single
+        commit:</para>
+      <informalexample>
+        <screen>
+$ svnmucc -U http://svn.example.com/projects/doohickey \
+          rm tags/latest-stable \
+          cp trunk tags/latest-stable \
+          -m "Slide the 'latest-stable' tag forward."
+r134 committed by harry at 2013-01-12T11:02:16.142536Z
+      </informalexample>
+      <para>The astute reader will have noticed that in this second
+        example, we slyly introduced the use of the <option>--root-url
+        (-U)</option> option.  Since <command>svnmucc</command>
+        concerns itself primarily with URLs, and since URLs can get
+        rather lengthy, you can use this option to specify a root URL
+        to which all other operand URLs are treated as
+        relative.</para>
+      <para>The <command>svnmucc</command> tool is not limited to
+        merely remixing actions that <command>svn</command> itself can
+        perform.  It introduces some additional functionality not
+        found in the command-line client.  For example, you can use
+        the <command>put</command> action to add or modify a file in
+        the repository, copying the file's contents from either a file
+        on your local machine or from data piped in via standard
+        input.  The tool also offers <command>propset</command>,
+        <command>propsetf</command>, and <command>propdel</command>
+        actions, useful for setting properties on versioned files and
+        directories (explicitly, or by copying the property's value
+        from a local file) and for deleting properties on the same.
+        Those actions are unsupported in the command-line client at
+        this time.</para>
+      <para>As you can see, <command>svnmucc</command> is a handy
+        addition to the Subversion user's tool chest.  For a complete
+        reference of this tool's offerings, see
+        <xref linkend="svn.ref.svnmucc" />.</para>
+    </sect2>
+  </sect1>
    <!-- =================================================================  
    <!-- =================================================================  
    <!-- =================================================================  
--- /trunk/en/book/ch09-reference.xml	Mon Jan 14 10:25:16 2013
+++ /trunk/en/book/ch09-reference.xml	Tue Jan 15 16:26:34 2013
@@ -10925,6 +10925,38 @@


+    </refentry>
+  </sect1>
+  <!-- =================================================================  
+  <!-- =================================================================  
+  <!-- =================================================================  
+  <sect1 id="svn.ref.svnmucc">
+    <title>svnmucc—Subversion Multiple URL Command Client</title>
+    <!-- ===============================================================  
+    <refentry id="svn.ref.svnmucc.re">
+      <indexterm>
+        <primary>svnmucc</primary>
+      </indexterm>
+      <refnamediv>
+        <refname>svnmucc</refname>
+        <refpurpose>Perform one or more Subversion repository
+          URL-based ACTIONs, committing the result as a (single) new
+          revision.</refpurpose>
+      </refnamediv>
+      <refsect1 id="svn.ref.svnmucc.re.syn">
+        <title>Synopsis</title>
+        <para><literal>svnmucc ACTION...</literal></para>
+      </refsect1>
+      <!-- ### TODO: Write this section! See                        -->
+      <!-- ### https://code.google.com/p/svnbook/issues/detail?id=5 -->

More information about the svnbook-dev mailing list