<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Basic Work Cycle</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Version Control with Subversion" /><link rel="up" href="svn.tour.html" title="Chapter 2. Basic Usage" /><link rel="prev" href="svn.tour.initial.html" title="Initial Checkout" /><link rel="next" href="svn.tour.history.html" title="Examining History" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Basic Work Cycle</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="svn.tour.initial.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Basic Usage</th><td width="20%" align="right"> <a accesskey="n" href="svn.tour.history.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="svn.tour.cycle"></a>Basic Work Cycle</h2></div></div></div><p>Subversion has numerous features, options, bells and
whistles, but on a day-to-day basis, odds are that you will only
use a few of them. In this section we'll run through the most
common things that you might find yourself doing with Subversion
in the course of a day's work.</p><p>The typical work cycle looks like this:</p><div class="itemizedlist"><ul type="disc"><li><p>Update your working copy</p><div class="itemizedlist"><ul type="circle"><li><p><span class="command"><strong>svn update</strong></span></p></li></ul></div></li><li><p>Make changes</p><div class="itemizedlist"><ul type="circle"><li><p><span class="command"><strong>svn add</strong></span></p></li><li><p><span class="command"><strong>svn delete</strong></span></p></li><li><p><span class="command"><strong>svn copy</strong></span></p></li><li><p><span class="command"><strong>svn move</strong></span></p></li></ul></div></li><li><p>Examine your changes</p><div class="itemizedlist"><ul type="circle"><li><p><span class="command"><strong>svn status</strong></span></p></li><li><p><span class="command"><strong>svn diff</strong></span></p></li></ul></div></li><li><p>Possibly undo some changes</p><div class="itemizedlist"><ul type="circle"><li><p><span class="command"><strong>svn revert</strong></span></p></li></ul></div></li><li><p>Resolve Conflicts (Merge Others' Changes)</p><div class="itemizedlist"><ul type="circle"><li><p><span class="command"><strong>svn update</strong></span></p></li><li><p><span class="command"><strong>svn resolved</strong></span></p></li></ul></div></li><li><p>Commit your changes</p><div class="itemizedlist"><ul type="circle"><li><p><span class="command"><strong>svn commit</strong></span></p></li></ul></div></li></ul></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.cycle.update"></a>Update Your Working Copy</h3></div></div></div><p>When working on a project with a team, you'll want to
update your working copy to receive any changes made since
your last update by other developers on the project. Use
<span class="command"><strong>svn update</strong></span> to bring your working copy into
sync with the latest revision in the repository.</p><pre class="screen">
$ svn update
U foo.c
U bar.c
Updated to revision 2.
</pre><p>In this case, someone else checked in modifications to
both <code class="filename">foo.c</code> and <code class="filename">bar.c</code>
since the last time you updated, and Subversion has updated
your working copy to include those changes.</p><p>When the server sends changes to your working copy via
<span class="command"><strong>svn update</strong></span>, a letter code is displayed next
to each item to let you know what actions Subversion performed
to bring your working copy up-to-date. To find out what these
letters mean, see <a class="xref" href="svn.ref.svn.c.update.html" title="svn update">svn update</a>.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.cycle.edit"></a>Make Changes to Your Working Copy</h3></div></div></div><p>Now you can get to work and make changes in your working
copy. It's usually most convenient to decide on a discrete
change (or set of changes) to make, such as writing a new
feature, fixing a bug, etc. The Subversion commands that you
will use here are <span class="command"><strong>svn add</strong></span>, <span class="command"><strong>svn
delete</strong></span>, <span class="command"><strong>svn copy</strong></span>, <span class="command"><strong>svn
move</strong></span>, and <span class="command"><strong>svn mkdir</strong></span>. However, if
you are merely editing files that are already in Subversion,
you may not need to use any of these commands until you
commit.</p><p>There are two kinds of changes you can make to your
working copy: file changes and tree changes. You don't need
to tell Subversion that you intend to change a file; just make
your changes using your text editor, word processor, graphics
program, or whatever tool you would normally use. Subversion
automatically detects which files have been changed, and in
addition handles binary files just as easily as it handles
text files—and just as efficiently too. For tree
changes, you can ask Subversion to “<span class="quote">mark</span>” files
and directories for scheduled removal, addition, copying, or
moving. These changes may take place immediately in your
working copy, but no additions or removals will happen in the
repository until you commit them.</p><p>Here is an overview of the five Subversion subcommands
that you'll use most often to make tree changes.</p><div class="sidebar"><p class="title"><b>Versioning symbolic links</b></p><p>On non-Windows platforms, Subversion is able to version
files of the special type <em class="firstterm">symbolic
link</em> (or, “<span class="quote">symlink</span>”). A symlink is
a file which acts as a sort of transparent reference to some
other object in the filesystem, allowing programs to read
and write to those objects indirectly by way of performing
operations on the symlink itself.</p><p>When a symlink is committed into a Subversion
repository, Subversion remembers that the file was in fact a
symlink, as well as the object to which the symlink
“<span class="quote">points</span>”. When that symlink is checked out to
another working copy on a non-Windows system, Subversion
reconstructs a real filesystem-level symbolic link from the
versioned symlink. But that doesn't in any way limit the
usability of working copies on systems such as Windows which
do not support symlinks. On such systems, Subversion simply
creates a regular text file whose contents are the path to
which to the original symlink pointed. While that file
can't be used as a symlink on a Windows system, it also
won't prevent Windows users from performing their other
Subversion-related activities.</p></div><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>svn add foo</strong></span></span></dt><dd><p>Schedule file, directory, or symbolic link
<code class="filename">foo</code> to be added to the repository.
When you next commit, <code class="filename">foo</code> will
become a child of its parent directory. Note that if
<code class="filename">foo</code> is a directory, everything
underneath <code class="filename">foo</code> will be scheduled
for addition. If you only want to add
<code class="filename">foo</code> itself, pass the
<code class="option">--non-recursive (-N)</code> option.</p></dd><dt><span class="term"><span class="command"><strong>svn delete foo</strong></span></span></dt><dd><p>Schedule file, directory, or symbolic link
<code class="filename">foo</code> to be deleted from the
repository. If <code class="filename">foo</code> is a file or
link, it is immediately deleted from your working copy.
If <code class="filename">foo</code> is a directory, it is not
deleted, but Subversion schedules it for deletion. When
you commit your changes, <code class="filename">foo</code> will
be entirely removed from your working copy and the
repository.
<sup>[<a id="id350238" href="#ftn.id350238" class="footnote">5</a>]</sup></p></dd><dt><span class="term"><span class="command"><strong>svn copy foo bar</strong></span></span></dt><dd><p>Create a new item <code class="filename">bar</code> as a
duplicate of <code class="filename">foo</code> and automatically
schedule <code class="filename">bar</code> for addition. When
<code class="filename">bar</code> is added to the repository on
the next commit, its copy history is recorded (as having
originally come from <code class="filename">foo</code>).
<span class="command"><strong>svn copy</strong></span> does not create intermediate
directories unless you pass the
<code class="option">--parents</code>.</p></dd><dt><span class="term"><span class="command"><strong>svn move foo bar</strong></span></span></dt><dd><p>This command is exactly the same as running
<span class="command"><strong>svn copy foo bar; svn delete foo</strong></span>.
That is, <code class="filename">bar</code> is scheduled for
addition as a copy of <code class="filename">foo</code>, and
<code class="filename">foo</code> is scheduled for removal.
<span class="command"><strong>svn move</strong></span> does not create intermediate
directories unless you pass the
<code class="option">--parents</code>.</p></dd><dt><span class="term"><span class="command"><strong>svn mkdir blort</strong></span></span></dt><dd><p>This command is exactly the same as running
<span class="command"><strong>mkdir blort; svn add blort</strong></span>. That is,
a new directory named <code class="filename">blort</code> is
created and scheduled for addition.</p></dd></dl></div><div class="sidebar"><p class="title"><b>Changing the Repository Without a Working Copy</b></p><p>There <span class="emphasis"><em>are</em></span> some use cases that
immediately commit tree changes to the repository. This
only happens when a subcommand is operating directly on a
URL, rather than on a working-copy path. In particular,
specific uses of <span class="command"><strong>svn mkdir</strong></span>, <span class="command"><strong>svn
copy</strong></span>, <span class="command"><strong>svn move</strong></span>, and
<span class="command"><strong>svn delete</strong></span> can work with URLs (And don't
forget that <span class="command"><strong>svn import</strong></span> always makes
changes to a URL).</p><p>URL operations behave in this manner because commands
that operate on a working copy can use the working copy as a
sort of “<span class="quote">staging area</span>” to set up your changes
before committing them to the repository. Commands that
operate on URLs don't have this luxury, so when you operate
directly on a URL, any of the above actions represent an
immediate commit.</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.cycle.examine"></a>Examine Your Changes</h3></div></div></div><p>Once you've finished making changes, you need to commit
them to the repository, but before you do so, it's usually a
good idea to take a look at exactly what you've changed. By
examining your changes before you commit, you can make a more
accurate log message. You may also discover that you've
inadvertently changed a file, and this gives you a chance to
revert those changes before committing. Additionally, this is
a good opportunity to review and scrutinize changes before
publishing them. You can see an overview of the changes
you've made by using <span class="command"><strong>svn status</strong></span>, and dig
into the details of those changes by using <span class="command"><strong>svn
diff</strong></span>.</p><div class="sidebar"><p class="title"><b>Look Ma! No Network!</b></p><p>The commands <span class="command"><strong>svn status</strong></span>,
<span class="command"><strong>svn diff</strong></span>, and <span class="command"><strong>svn
revert</strong></span> can be used without any network access even
if your repository <span class="emphasis"><em>is</em></span> across the
network. This makes it easy to manage your
changes-in-progress when you are somewhere without a network
connection, such as travelling on an airplane, riding a
commuter train or hacking on the beach.<sup>[<a id="id350528" href="#ftn.id350528" class="footnote">6</a>]</sup></p><p>Subversion does this by keeping private caches of
pristine versions of each versioned file inside of the
<code class="filename">.svn</code> administrative areas. This allows
Subversion to report—and revert—local
modifications to those files <span class="emphasis"><em>without network
access</em></span>. This cache (called the
“<span class="quote">text-base</span>”) also allows Subversion to send the
user's local modifications during a commit to the server as
a compressed <em class="firstterm">delta</em> (or
“<span class="quote">difference</span>”) against the pristine version.
Having this cache is a tremendous benefit—even if you
have a fast net connection, it's much faster to send only a
file's changes rather than the whole file to the
server.</p></div><p>Subversion has been optimized to help you with this task,
and is able to do many things without communicating with the
repository. In particular, your working copy contains a
hidden cached “<span class="quote">pristine</span>” copy of each version
controlled file within the <code class="filename">.svn</code> area.
Because of this, Subversion can quickly show you how your
working files have changed, or even allow you to undo your
changes without contacting the repository.</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.examine.status"></a>See an overview of your changes</h4></div></div></div><p>To get an overview of your changes, you'll use the
<span class="command"><strong>svn status</strong></span> command. You'll probably use
<span class="command"><strong>svn status</strong></span> more than any other Subversion
command.</p><div class="sidebar"><p class="title"><b>CVS Users: Hold That Update!</b></p><p>You're probably used to using <span class="command"><strong>cvs
update</strong></span> to see what changes you've made to your
working copy. <span class="command"><strong>svn status</strong></span> will give you
all the information you need regarding what has changed in
your working copy—without accessing the repository
or potentially incorporating new changes published by
other users.</p><p>In Subversion, <span class="command"><strong>update</strong></span> does just
that—it updates your working copy with any changes
committed to the repository since the last time you've
updated your working copy. You may have to break the
habit of using the <span class="command"><strong>update</strong></span> command to
see what local modifications you've made.</p></div><p>If you run <span class="command"><strong>svn status</strong></span> at the top of
your working copy with no arguments, it will detect all file
and tree changes you've made. Below are a few examples of
the most common status codes that <span class="command"><strong>svn
status</strong></span> can return. (Note that the text following
<code class="literal">#</code> is not
actually printed by <span class="command"><strong>svn status</strong></span>.)</p><pre class="screen">
A stuff/loot/bloo.h # file is scheduled for addition
C stuff/loot/lump.c # file has textual conflicts from an update
D stuff/fish.c # file is scheduled for deletion
M bar.c # the content in bar.c has local modifications
</pre><p>In this output format <span class="command"><strong>svn status</strong></span>
prints six columns of characters, followed by several
whitespace characters, followed by a file or directory name.
The first column tells the status of a file or directory
and/or its contents. The codes we listed are:</p><div class="variablelist"><dl><dt><span class="term"><code class="computeroutput">A item</code></span></dt><dd><p>The file, directory, or symbolic link
<code class="filename">item</code> has been scheduled for
addition into the repository.</p></dd><dt><span class="term"><code class="computeroutput">C item</code></span></dt><dd><p>The file <code class="filename">item</code> is in a state
of conflict. That is, changes received from the
server during an update overlap with local changes
that you have in your working copy (and weren't
resolved during the update). You must resolve this
conflict before committing your changes to the
repository.</p></dd><dt><span class="term"><code class="computeroutput">D item</code></span></dt><dd><p>The file, directory, or symbolic link
<code class="filename">item</code> has been scheduled for
deletion from the repository.</p></dd><dt><span class="term"><code class="computeroutput">M item</code></span></dt><dd><p>The contents of the file <code class="filename">item</code>
have been modified.</p></dd></dl></div><p>If you pass a specific path to <span class="command"><strong>svn
status</strong></span>, you get information about that item
alone:</p><pre class="screen">
$ svn status stuff/fish.c
D stuff/fish.c
</pre><p><span class="command"><strong>svn status</strong></span> also has a
<code class="option">--verbose (-v)</code> option, which will show you
the status of <span class="emphasis"><em>every</em></span> item in your
working copy, even if it has not been changed:</p><pre class="screen">
$ svn status -v
M 44 23 sally README
44 30 sally INSTALL
M 44 20 harry bar.c
44 18 ira stuff
44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
44 21 sally stuff/things
A 0 ? ? stuff/things/bloo.h
44 36 harry stuff/things/gloo.c
</pre><p>This is the “<span class="quote">long form</span>” output of
<span class="command"><strong>svn status</strong></span>. The letters in the first
column mean the same as before, but the second column shows
the working-revision of the item. The third and fourth
columns show the revision in which the item last changed,
and who changed it.</p><p>None of the prior invocations to <span class="command"><strong>svn
status</strong></span> contact the repository—instead, they
compare the metadata in the
<code class="filename">.svn</code> directory with the working copy.
Finally, there is the <code class="option">--show-updates (-u)</code>
option, which contacts the repository and adds information
about things that are out-of-date:</p><pre class="screen">
$ svn status -u -v
M * 44 23 sally README
M 44 20 harry bar.c
* 44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
A 0 ? ? stuff/things/bloo.h
Status against revision: 46
</pre><p>Notice the two asterisks: if you were to run
<span class="command"><strong>svn update</strong></span> at this point, you would
receive changes to <code class="filename">README</code>
and <code class="filename">trout.c</code>. This tells you some very
useful information—you'll need to update and get the
server changes on <code class="filename">README</code> before you
commit, or the repository will reject your commit for being
out-of-date. (More on this subject later.)</p><p><span class="command"><strong>svn status</strong></span> can display much more
information about the files and directories in your
working copy than we've shown here—for an exhaustive
description of svn status and its output, see <a class="xref" href="svn.ref.svn.c.status.html" title="svn status">svn status</a>.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.examine.diff"></a>Examine the details of your local modifications</h4></div></div></div><p>Another way to examine your changes is with the
<span class="command"><strong>svn diff</strong></span> command. You can find out
<span class="emphasis"><em>exactly</em></span> how you've modified things by
running <span class="command"><strong>svn diff</strong></span> with no arguments, which
prints out file changes in <em class="firstterm">unified diff
format</em>:</p><pre class="screen">
$ svn diff
Index: bar.c
===================================================================
--- bar.c (revision 3)
+++ bar.c (working copy)
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>
int main(void) {
- printf("Sixty-four slices of American Cheese...\n");
+ printf("Sixty-five slices of American Cheese...\n");
return 0;
}
Index: README
===================================================================
--- README (revision 3)
+++ README (working copy)
@@ -193,3 +193,4 @@
+Note to self: pick up laundry.
Index: stuff/fish.c
===================================================================
--- stuff/fish.c (revision 1)
+++ stuff/fish.c (working copy)
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.
Index: stuff/things/bloo.h
===================================================================
--- stuff/things/bloo.h (revision 8)
+++ stuff/things/bloo.h (working copy)
+Here is a new file to describe
+things about bloo.
</pre><p>The <span class="command"><strong>svn diff</strong></span> command produces this
output by comparing your working files against the cached
“<span class="quote">pristine</span>” copies within the
<code class="filename">.svn</code> area. Files scheduled for
addition are displayed as all added-text, and files
scheduled for deletion are displayed as all deleted
text.</p><p>Output is displayed in unified diff format. That is,
removed lines are prefaced with <code class="literal">-</code> and
added lines are prefaced with
<code class="literal">+</code>. <span class="command"><strong>svn diff</strong></span> also
prints filename and offset information useful to the
<span class="command"><strong>patch</strong></span> program, so you can generate
“<span class="quote">patches</span>” by redirecting the diff output to a
file:</p><pre class="screen">
$ svn diff > patchfile
</pre><p>You could, for example, email the patch file to another
developer for review or testing prior to commit.</p><p>Subversion uses its internal diff engine, which produces
unified diff format, by default. If you want diff output in
a different format, specify an external diff program using
<code class="option">--diff-cmd</code> and pass any flags you'd like to
it using the <code class="option">--extensions (-x)</code> option. For
example, to see local differences in file
<code class="filename">foo.c</code> in context output format while
ignoring case differences, you might run <span class="command"><strong>svn diff
--diff-cmd /usr/bin/diff --extensions '-i'
foo.c</strong></span>.</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.cycle.revert"></a>Undoing Working Changes</h3></div></div></div><p>Suppose while viewing the output of <span class="command"><strong>svn
diff</strong></span> 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.</p><p>This is a perfect opportunity to use <span class="command"><strong>svn
revert</strong></span>:</p><pre class="screen">
$ svn revert README
Reverted 'README'
</pre><p>Subversion reverts the file to its pre-modified state by
overwriting it with the cached “<span class="quote">pristine</span>” copy
from the <code class="filename">.svn</code> area. But also note that
<span class="command"><strong>svn revert</strong></span> can undo
<span class="emphasis"><em>any</em></span> scheduled operations—for
example, you might decide that you don't want to add a new
file after all:</p><pre class="screen">
$ svn status foo
? foo
$ svn add foo
A foo
$ svn revert foo
Reverted 'foo'
$ svn status foo
? foo
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><span class="command"><strong>svn revert</strong></span>
<em class="replaceable"><code>ITEM</code></em> has exactly the same
effect as deleting <em class="replaceable"><code>ITEM</code></em> from
your working copy and then running <span class="command"><strong>svn update -r
BASE</strong></span> <em class="replaceable"><code>ITEM</code></em>. However,
if you're reverting a file, <span class="command"><strong>svn revert</strong></span>
has one very noticeable difference—it doesn't have
to communicate with the repository to restore your
file.</p></div><p>Or perhaps you mistakenly removed a file from version
control:</p><pre class="screen">
$ svn status README
README
$ svn delete README
D README
$ svn revert README
Reverted 'README'
$ svn status README
README
</pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.cycle.resolve"></a>Resolve Conflicts (Merging Others' Changes)</h3></div></div></div><p>We've already seen how <span class="command"><strong>svn status -u</strong></span>
can predict conflicts. Suppose you run <span class="command"><strong>svn
update</strong></span> and some interesting things occur:</p><pre class="screen">
$ svn update
U INSTALL
G README
Conflict discovered in 'bar.c.
Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options :
</pre><p>The <code class="computeroutput">U</code> and
<code class="computeroutput">G</code> codes are no cause for
concern; those files cleanly absorbed changes from the
repository. The files marked with
<code class="computeroutput">U</code> contained no local changes
but were <code class="computeroutput">U</code>pdated with changes
from the repository. The <code class="computeroutput">G</code>
stands for mer<code class="computeroutput">G</code>ed, which
means that the file had local changes to begin with, but the
changes coming from the repository didn't overlap with the local
changes.</p><p>But the next line is part of a feature new in Subversion
1.5 called interactive conflict resolution. This means that
the changes from the server overlapped with your own, and you
have the opportunity to resolve this conflict. The most
commonly used options are displayed, but you can see all of
the options by typing <em class="replaceable"><code>h</code></em>: </p><pre class="screen">
...
(p)ostpone - mark the conflict to be resolved later
(d)iff - show all changes made to merged file
(e)dit - change merged file in an editor
(r)esolved - accept merged version of file
(m)ine - accept my version of file
(t)heirs - accept their version of file
(l)aunch - use third-party tool to resolve conflict
(h)elp - show this list
</pre><p>Let's briefly review each of these options before we go
into detail on what each option means.</p><div class="variablelist"><dl><dt><span class="term"><code class="computeroutput">(p)ostpone</code></span></dt><dd><p>Leaves the file in a conflicted state for you to
resolve after your update is complete.</p></dd><dt><span class="term"><code class="computeroutput">(d)iff</code></span></dt><dd><p>Display the differences between the base revision
and the conflicted file itself in unified diff format.</p></dd><dt><span class="term"><code class="computeroutput">(e)dit</code></span></dt><dd><p>Open the file in conflict with your favorite editor,
as set in the environment variable
<code class="literal">EDITOR</code>.</p></dd><dt><span class="term"><code class="computeroutput">(r)esolved</code></span></dt><dd><p>After editing a file, choosing this command tells
<span class="command"><strong>svn</strong></span> that you've resolved the
conflicts in the file and that it should accept the
current contents—basically that you've
“<span class="quote">resolved</span>” the conflict.</p></dd><dt><span class="term"><code class="computeroutput">(m)ine</code></span></dt><dd><p>Discard the newly received changes from the server
and use only your local changes for the file under review.</p></dd><dt><span class="term"><code class="computeroutput">(t)heirs</code></span></dt><dd><p>Discard your local changes to the file under review
and use only the newly received changes from the
server.</p></dd><dt><span class="term"><code class="computeroutput">(l)aunch</code></span></dt><dd><p>Launch an external program to perform the conflict
resolution. This requires a bit of preparation
beforehand.</p></dd><dt><span class="term"><code class="computeroutput">(h)elp</code></span></dt><dd><p>Shows the list of all possible commands you can use
in interactive conflict resolution.</p></dd></dl></div><p>We'll cover these commands in more detail now, grouping
them together by related functionality.</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.resolve.diff"></a>Viewing Conflict Differences Interactively</h4></div></div></div><p>Before deciding how to attack a conflict interactively,
odds are that you'd like to see what exactly is in conflict,
and the diff command (<span class="command"><strong>d</strong></span>) is what you'll
use for this:</p><pre class="screen">
...
Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options : d
--- .svn/text-base/sandwich.txt.svn-base Tue Dec 11 21:33:57 2007
+++ .svn/tmp/tempfile.32.tmp Tue Dec 11 21:34:33 2007
@@ -1 +1,5 @@
-Just buy a sandwich.
+<<<<<<< .mine
+Go pickup a cheesesteak.
+=======
+Bring me a taco!
+>>>>>>> .r32
...
</pre><p>The first line of the diff content shows the previous
contents of the working copy (the <code class="literal">BASE</code>
revision), the next content line is your change, and the
last content line is the change that was just received from
the server (<span class="emphasis"><em>usually</em></span> the
<code class="literal">HEAD</code> revision). With this information in
hand, you're ready to move on to the next action.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.resolve.resolve"></a>Resolving Conflict Differences Interactively</h4></div></div></div><p>There are four different ways to resolve conflicts
interactively—two of which allow you to selectively
merge and edit changes, and two of which allow you to simply
pick a version of the file and move along.</p><p>If you wish to choose some combination of your local
changes, you can use the “<span class="quote">edit</span>” command
(<span class="command"><strong>e</strong></span>) to manually edit the file with
conflict markers in a text editor (determined by the
<code class="literal">EDITOR</code> environment variable). Editing
the file by hand in your favorite text editor is a somewhat
low-tech way of remedying conflicts (see <a class="xref" href="svn.tour.cycle.html#svn.tour.cycle.resolve.byhand" title="Merging Conflicts by Hand">the section called “Merging Conflicts by Hand”</a> for a
walkthrough), so some people like to use fancy graphical
merge tools instead.</p><p>In order to use a merge tool, you need to either set the
<code class="literal">SVN_MERGE</code> environment variable, or define
the <code class="literal">merge-tool-cmd</code> option in your
Subversion configuration file (see <a class="xref" href="svn.advanced.confarea.html#svn.advanced.confarea.opts" title="Configuration Options">the section called “Configuration Options”</a> for more details).
Subversion will pass four arguments to the merge tool: The
<code class="literal">BASE</code> revision of the file, the revision
of the file received from the server as part of the update,
the copy of the file containing your local edits, and
lastly, the merged copy of the file (which contains conflict
markers). If your merge tool is expecting arguments in a
different order or format, you'll need to write a wrapper
script for Subversion to invoke. After you've edited the
file, if you're satisfied with the changes you've made, you
can tell Subversion that the edited file is no longer in
conflict by using the “<span class="quote">resolved</span>” command
(<code class="literal">r</code>).</p><p>If you decide that you don't need to merge any changes,
but just want to accept one version of the file or the
other, you can either choose your changes (aka
“<span class="quote">mine</span>”) by using the “<span class="quote">mine</span>”
command (<span class="command"><strong>m</strong></span>) or choose theirs by using the
“<span class="quote">theirs</span>” command (<span class="command"><strong>t</strong></span>).</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.resolve.pending"></a>Postponing Conflict Resolution</h4></div></div></div><p>This may sound like an appropriate section for avoiding
marital disagreements, but it's actually still about
Subversion, so read on. If you're doing an update and
encounter a conflict that you're not prepared to review or
resolve, you can type <span class="command"><strong>p</strong></span> to postpone
resolving a conflict on a file-by-file basis when you run
<span class="command"><strong>svn update</strong></span>. If you're running an update
and don't want to resolve any conflicts, you can pass the
<code class="option">--non-interactive</code> option to <span class="command"><strong>svn
update</strong></span> and any file in conflict will be marked
with a <code class="computeroutput">C</code>
automatically.</p><p>The <code class="computeroutput">C</code> stands for
<code class="computeroutput">c</code>onflict. This means that
the changes from the server overlapped with your own, and
now you have to manually choose between them after the
update has completed. When you postpone a conflict
resolution, <span class="command"><strong>svn</strong></span> typically does three
things to assist you in noticing and resolving that
conflict:</p><div class="itemizedlist"><ul type="disc"><li><p>Subversion prints a <code class="computeroutput">C</code>
during the update, and remembers that the file is in a
state of conflict.</p></li><li><p>If Subversion considers the file to be mergeable, it
places <em class="firstterm">conflict
markers</em>—special strings of text which
delimit the “<span class="quote">sides</span>” of the
conflict—into the file to visibly demonstrate the
overlapping areas. (Subversion uses the
<code class="literal">svn:mime-type</code> property to decide if a
file is capable of contextual, line-based merging. See
<a class="xref" href="svn.advanced.props.file-portability.html#svn.advanced.props.special.mime-type" title="File Content Type">the section called “File Content Type”</a>
to learn more.)</p></li><li><p>For every conflicted file, Subversion places three
extra unversioned files in your working copy:</p><div class="variablelist"><dl><dt><span class="term"><code class="filename">filename.mine</code></span></dt><dd><p>This is your file as it existed in your working
copy before you updated your working copy—that
is, without conflict markers. This file has only
your latest changes in it. (If Subversion considers
the file to be unmergeable, then the
<code class="filename">.mine</code> file isn't created, since
it would be identical to the working file.)</p></dd><dt><span class="term"><code class="filename">filename.rOLDREV</code></span></dt><dd><p>This is the file that was the
<code class="literal">BASE</code> revision before you updated
your working copy. That is, the file that you
checked out before you made your latest
edits.</p></dd><dt><span class="term"><code class="filename">filename.rNEWREV</code></span></dt><dd><p>This is the file that your Subversion client
just received from the server when you updated your
working copy. This file corresponds to the
<code class="literal">HEAD</code> revision of the
repository.</p></dd></dl></div><p>Here <code class="literal">OLDREV</code> is the revision number
of the file in your <code class="filename">.svn</code> directory
and <code class="literal">NEWREV</code> is the revision number of
the repository <code class="literal">HEAD</code>.</p></li></ul></div><p>For example, Sally makes changes to the file
<code class="filename">sandwich.txt</code> in the repository. Harry has
just changed the file in his working copy and checked it in.
Sally updates her working copy before checking in and she gets
a conflict, which she postpones:</p><pre class="screen">
$ svn update
Conflict discovered in 'sandwich.txt'.
Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options : p
C sandwich.txt
Updated to revision 2.
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2
</pre><p>At this point, Subversion will <span class="emphasis"><em>not</em></span>
allow Sally to commit the file
<code class="filename">sandwich.txt</code> until the three temporary
files are removed.</p><pre class="screen">
$ svn commit -m "Add a few more things"
svn: Commit failed (details follow):
svn: Aborting commit: '/home/sally/svn-work/sandwich.txt' remains in conflict
</pre><p>If you've postponed a conflict, you need to do one of three
things:</p><div class="itemizedlist"><ul type="disc"><li><p>Merge the conflicted text “<span class="quote">by hand</span>” (by
examining and editing the conflict markers within the
file).</p></li><li><p>Copy one of the temporary files on top of your
working file.</p></li><li><p>Run <span class="command"><strong>svn revert <filename></strong></span>
to throw away all of your local changes.</p></li></ul></div><p>Once you've resolved the conflict, you need to let
Subversion know by running <span class="command"><strong>svn resolved</strong></span>.
This removes the three temporary files and Subversion no
longer considers the file to be in a state of
conflict.<sup>[<a id="id351965" href="#ftn.id351965" class="footnote">7</a>]</sup></p><pre class="screen">
$ svn resolved sandwich.txt
Resolved conflicted state of 'sandwich.txt'
</pre></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.resolve.byhand"></a>Merging Conflicts by Hand</h4></div></div></div><p>Merging conflicts by hand can be quite intimidating the
first time you attempt it, but with a little practice, it
can become as easy as falling off a bike.</p><p>Here's an example. Due to a miscommunication, you and
Sally, your collaborator, both edit the file
<code class="filename">sandwich.txt</code> at the same time. Sally
commits her changes, and when you go to update your working
copy, you get a conflict and you're going to have to edit
<code class="filename">sandwich.txt</code> to resolve the conflicts.
First, let's take a look at the file:</p><pre class="screen">
$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
Creole Mustard
Bottom piece of bread
</pre><p>The strings of less-than signs, equal signs, and
greater-than signs are conflict markers, and are not part of
the actual data in conflict. You generally want to ensure
that those are removed from the file before your next
commit. The text between the first two sets of markers is
composed of the changes you made in the conflicting
area:</p><pre class="screen">
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
</pre><p>The text between the second and third sets of conflict
markers is the text from Sally's commit:</p><pre class="screen">
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
</pre><p>Usually you won't want to just delete the conflict
markers and Sally's changes—she's going to be awfully
surprised when the sandwich arrives and it's not what she
wanted. So this is where you pick up the phone or walk
across the office and explain to Sally that you can't get
sauerkraut from an Italian deli.<sup>[<a id="id351784" href="#ftn.id351784" class="footnote">8</a>]</sup> Once you've agreed on the changes
you will check in, edit your file and remove the conflict
markers.</p><pre class="screen">
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
Salami
Mortadella
Prosciutto
Creole Mustard
Bottom piece of bread
</pre><p>Now run <span class="command"><strong>svn resolved</strong></span>, and you're
ready to commit your changes:</p><pre class="screen">
$ svn resolved sandwich.txt
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."
</pre><p>Note that <span class="command"><strong>svn resolved</strong></span>, unlike most
of the other commands we deal with in this chapter, requires
an argument. In any case, you want to be careful and only
run <span class="command"><strong>svn resolved</strong></span> when you're certain that
you've fixed the conflict in your file—once the
temporary files are removed, Subversion will let you commit
the file even if it still contains conflict markers.</p><p>If you ever get confused while editing the conflicted
file, you can always consult the three files that Subversion
creates for you in your working copy—including your
file as it was before you updated. You can even use a
third-party interactive merging tool to examine those three
files.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.resolve.copyover"></a>Copying a File Onto Your Working File</h4></div></div></div><p>If you get a conflict and decide that you want to throw
out your changes, you can merely copy one of the temporary
files created by Subversion over the file in your working
copy:</p><pre class="screen">
$ svn update
C sandwich.txt
Updated to revision 2.
$ ls sandwich.*
sandwich.txt sandwich.txt.mine sandwich.txt.r2 sandwich.txt.r1
$ cp sandwich.txt.r2 sandwich.txt
$ svn resolved sandwich.txt
</pre></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="svn.tour.cycle.resolve.revert"></a>Punting: Using <span class="command"><strong>svn revert</strong></span></h4></div></div></div><p>If you get a conflict, and upon examination decide that
you want to throw out your changes and start your edits
again, just revert your changes:</p><pre class="screen">
$ svn revert sandwich.txt
Reverted 'sandwich.txt'
$ ls sandwich.*
sandwich.txt
</pre><p>Note that when you revert a conflicted file, you don't
have to run <span class="command"><strong>svn resolved</strong></span>.</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.cycle.commit"></a>Commit Your Changes</h3></div></div></div><p>Finally! Your edits are finished, you've merged all
changes from the server, and you're ready to commit your
changes to the repository.</p><p>The <span class="command"><strong>svn commit</strong></span> command sends all of
your changes to the repository. When you commit a change, you
need to supply a <em class="firstterm">log message</em>,
describing your change. Your log message will be attached to
the new revision you create. If your log message is brief,
you may wish to supply it on the command line using the
<code class="option">--message</code> (or <code class="option">-m</code>)
option:</p><pre class="screen">
$ svn commit -m "Corrected number of cheese slices."
Sending sandwich.txt
Transmitting file data .
Committed revision 3.
</pre><p>However, if you've been composing your log message as you
work, you may want to tell Subversion to get the message from
a file by passing the filename with the
<code class="option">--file (-F)</code> option:</p><pre class="screen">
$ svn commit -F logmsg
Sending sandwich.txt
Transmitting file data .
Committed revision 4.
</pre><p>If you fail to specify either the
<code class="option">--message</code> or <code class="option">--file</code> option,
then Subversion will automatically launch your favorite editor
(see the <code class="literal">editor-cmd</code> section in
<a class="xref" href="svn.advanced.confarea.html#svn.advanced.confarea.opts.config" title="Config">the section called “Config”</a>) for composing a log
message.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>If you're in your editor writing a commit message and
decide that you want to cancel your commit, you can just
quit your editor without saving changes. If you've already
saved your commit message, simply delete the text, save
again, then abort.</p><pre class="screen">
$ svn commit
Waiting for Emacs...Done
Log message unchanged or not specified
a)bort, c)ontinue, e)dit
a
$
</pre></div><p>The repository doesn't know or care if your changes make
any sense as a whole; it only checks to make sure that nobody
else has changed any of the same files that you did when you
weren't looking. If somebody <span class="emphasis"><em>has</em></span> done
that, the entire commit will fail with a message informing you
that one or more of your files is out-of-date:</p><pre class="screen">
$ svn commit -m "Add another rule"
Sending rules.txt
svn: Commit failed (details follow):
svn: Your file or directory 'sandwich.txt' is probably out-of-date
…
</pre><p>(The exact wording of this error message depends on the
network protocol and server you're using, but the idea is the
same in all cases.)</p><p>At this point, you need to run <span class="command"><strong>svn
update</strong></span>, deal with any merges or conflicts that
result, and attempt your commit again.</p><p>That covers the basic work cycle for using Subversion.
There are many other features in Subversion that you can use
to manage your repository and working copy, but most of your
day-to-day use of Subversion will involve only the commands
that we've discussed so far in this chapter. We will,
however, cover a few more commands that you'll use fairly
often.</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id350238" href="#id350238" class="para">5</a>] </sup>Of course, nothing is ever totally
deleted from the repository—just from the
<code class="literal">HEAD</code> of the repository. You can get
back anything you delete by checking out (or updating
your working copy to) a revision earlier than the one in
which you deleted it. Also see
<a class="xref" href="svn.branchmerge.advanced.html#svn.branchmerge.advanced.resurrect" title="Resurrecting Deleted Items">the section called “Resurrecting Deleted Items”</a>.
</p></div><div class="footnote"><p><sup>[<a id="ftn.id350528" href="#id350528" class="para">6</a>] </sup>And
also that you don't have a WAN card. Thought you got us,
huh?</p></div><div class="footnote"><p><sup>[<a id="ftn.id351965" href="#id351965" class="para">7</a>] </sup>You can always remove the temporary
files yourself, but would you really want to do that when
Subversion can do it for you? We didn't think so.</p></div><div class="footnote"><p><sup>[<a id="ftn.id351784" href="#id351784" class="para">8</a>] </sup>And if you
ask them for it, they may very well ride you out of town on
a rail.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="svn.tour.initial.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="svn.tour.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="svn.tour.history.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Initial Checkout </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Examining History</td></tr></table></div></body></html>
