[svnbook] r4351 committed - Finish issue 5 ("Document svnmucc")....
svnbook at googlecode.com
svnbook at googlecode.com
Mon Jan 21 23:43:01 CST 2013
Revision: 4351
Author: cmpilato at gmail.com
Date: Mon Jan 21 21:42:37 2013
Log: Finish issue 5 ("Document svnmucc").
* en/book/ch09-reference.xml
(svn.ref.svnmucc.re.examples): Flesh out this section.
http://code.google.com/p/svnbook/source/detail?r=4351
Modified:
/trunk/en/book/ch09-reference.xml
=======================================
--- /trunk/en/book/ch09-reference.xml Mon Jan 21 11:30:40 2013
+++ /trunk/en/book/ch09-reference.xml Mon Jan 21 21:42:37 2013
@@ -11285,8 +11285,9 @@
baseline revision for all changes made via
the <command>svnmucc</command> actions. This is an
important option which users should habituate to using
- correctly in order to avoid inadvertently undoing
- contemporary changes made by fellow team members.</para>
+ whenever modifying existing versioned items to avoid
+ inadvertently undoing contemporary changes made by
+ fellow team members.</para>
</listitem>
</varlistentry>
@@ -11352,7 +11353,117 @@
<refsect1 id="svn.ref.svnmucc.re.examples">
<title>Examples</title>
- <para>### TODO ###</para>
+ <para>To (safely) modify a file's contents without using a
+ working copy, use <command>svn cat</command> to fetch the
+ current contents of the file, and <command>svnmucc
+ put</command> to commit the edited contents thereof.</para>
+
+ <informalexample>
+ <screen>
+$ # Calculate some convenience variables.
+$ export FILEURL=http://svn.example.com/projects/sandbox/README
+$ export BASEREV=`svn info ${FILEURL} | \
+ grep '^Last Changed Rev' | cut -d ' ' -f 2`
+$ # Get a copy of the file's current contents.
+$ svn cat ${FILEURL}@${BASEREV} > /tmp/README.tmpfile
+$ # Edit the (copied) file.
+$ vi /tmp/README.tmpfile
+$ # Commit the new content for our file.
+$ svnmucc -r ${BASEREV} put README.tmpfile ${FILEURL} \
+ -m "Tweak the README file."
+r24 committed by harry at 2013-01-21T16:21:23.100133Z
+# Cleanup after ourselves.
+$ rm /tmp/README.tmpfile
+</screen>
+ </informalexample>
+
+ <para>Apply a similar approach to change a file or directory
+ property. Simply use <command>svnmucc propget</command>
+ and <command>svnmucc propsetf</command> instead
+ of <command>svn cat</command> and <command>svnmucc
+ put</command>, respectively.</para>
+
+ <informalexample>
+ <screen>
+$ # Calculate some convenience variables.
+$ export PROJURL=http://svn.example.com/projects/sandbox
+$ export BASEREV=`svn info ${PROJURL} | \
+ grep '^Last Changed Rev' | cut -d ' ' -f 2`
+$ # Get a copy of the directory's "license" property value.
+$ svnmucc -r ${BASEREV} propget license ${PROJURL} > /tmp/prop.tmpfile
+$ # Tweak the property.
+$ vi /tmp/prop.tmpfile
+$ # Commit the new property value.
+$ svnmucc -r ${BASEREV} propsetf prop.tmpfile ${PROJURL} \
+ -m "Tweak the project directory 'license' property."
+r25 committed by harry at 2013-01-21T16:24:11.375936Z
+# Cleanup after ourselves.
+$ rm /tmp/prop.tmpfile
+</screen>
+ </informalexample>
+
+ <para>Let's look now at some multi-operation examples.</para>
+
+ <para>To implement a <quote>moving tag</quote>, where a single
+ tag name is recycled to point to different snapshots (for
+ example, the current latest stable version) of a codebase,
+ use <command>svnmucc rm</command> and <command>svnmucc
+ cp</command>:</para>
+
+ <informalexample>
+ <screen>
+$ svnmucc -U http://svn.example.com/projects/doohickey \
+ rm tags/latest-stable \
+ cp HEAD trunk tags/latest-stable \
+ -m "Slide the 'latest-stable' tag forward."
+r134 committed by harry at 2013-01-12T11:02:16.142536Z
+$
+</screen>
+ </informalexample>
+
+ <para>In the previous example, we slyly introduced the use of
+ the <option>--root-url (-U)</option> option. Use this
+ option to specify a base URL to which all other operand URLs
+ are treated as relative (and save yourself some
+ typing).</para>
+
+ <para>The following shows an example of using
+ <command>svnmucc</command> to, in a single revision, create
+ a new tag of your project which includes a newly created
+ descriptive file and which lacks a directory which shouldn't
+ be included in, say, a release tarball.</para>
+
+ <informalexample>
+ <screen>
+$ echo "This is the 1.2.0 release." | \
+ svnmucc -U http://svn.example.com/projects/doohickey \
+ -m "Tag the 1.2.0 release." \
+ -- \
+ cp HEAD trunk tags/1.2.0 \
+ rm tags/1.2.0/developer-notes \
+ put - tags/1.2.0/README.tag
+r164 committed by cmpilato at 2013-01-22T05:26:15.563327Z
+$ svn log -c 164 http://svn.example.com/projects/doohickey
+------------------------------------------------------------------------
+r164 | cmpilato | 2013-01-22 00:26:15 -0500 (Tue, 22 Jan 2013) | 1 line
+Changed paths:
+ A /tags/1.2.0 (from /trunk:163)
+ A /tags/1.2.0/README.tag
+ D /tags/1.2.0/developer-notes
+
+Tag the 1.2.0 release.
+$
+</screen>
+ </informalexample>
+
+ <para>The previous example demonstrates not only how to do
+ several different things in a single <command>svnmucc</command>
+ invocation, but also the use of standard input as the source
+ of new file contents. Note the presence of <literal>--</literal>
+ to indicate that no more options follow on the command line.
+ This is required so that the bare <literal>-</literal> used
+ in the <command>svnmucc put</command> action won't be
+ flagged as a malformed option indicator.</para>
</refsect1>
More information about the svnbook-dev
mailing list