ch04-branching-and-merging.xml - svnbook - Version Control With Subversion

Source path: svn/ tags/ en-1.5-final/ src/ en/ book/ ch04-branching-and-merging.xml

‹r3305

r4266

<chapter id="svn.branchmerge">
  <title>Branching and Merging</title>

  <blockquote>
    <attribution>Confucius</attribution>
    <para><quote>君子务本
      (It is upon the Trunk that a gentleman works.)</quote></para>
  </blockquote>


  <para>Branching, tagging, and merging are concepts common to
    almost all version control systems.  If you're not familiar with
    these ideas, we provide a good introduction in this chapter.  If
    you are familiar, hopefully you'll find it interesting to
    see how Subversion implements them.</para>

  <para>Branching is a fundamental part of version control.  If
    you're going to allow Subversion to manage your data, this
    is a feature you'll eventually come to depend on.  This chapter
    assumes that you're already familiar with Subversion's basic
    concepts (<xref linkend="svn.basic"/>).</para>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.whatis">
    <title>What's a Branch?</title>

    <para>Suppose it's your job to maintain a document for a division
      in your company&mdash;a handbook of some sort.  One day a different
      division asks you for the same handbook, but with a few parts
      <quote>tweaked</quote> for them, since they do things slightly
      differently.</para>

    <para>What do you do in this situation?  You do the obvious: make
      a second copy of your document and begin maintaining the two
      copies separately.  As each department asks you to make small
      changes, you incorporate them into one copy or the other.</para>

    <para>You often want to make the same change to both copies.  For
      example, if you discover a typo in the first copy, it's very
      likely that the same typo exists in the second copy.  The two
      documents are almost the same, after all; they differ only in
      small, specific ways.</para>

    <para>This is the basic concept of a
      <firstterm>branch</firstterm>&mdash;namely, a line of
      development that exists independently of another line, yet still
      shares a common history if you look far enough back in time.  A
      branch always begins life as a copy of something, and moves on
      from there, generating its own history (see <xref
      linkend="svn.branchmerge.whatis.dia-1"/>).</para>

      <figure id="svn.branchmerge.whatis.dia-1">
        <title>Branches of development</title>
        <graphic fileref="images/ch04dia1.png"/>
      </figure>

    <para>Subversion has commands to help you maintain parallel
      branches of your files and directories.  It allows you to create
      branches by copying your data, and remembers that the copies are
      related to one another.  It also helps you duplicate changes
      from one branch to another.  Finally, it can make portions of
      your working copy reflect different branches so that you can
      <quote>mix and match</quote> different lines of development in
      your daily work.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.using">
    <title>Using Branches</title>

    <para>At this point, you should understand how each commit creates
      an entirely new filesystem tree (called a <quote>revision</quote>)
      in the repository.  If you don't, go back and read about revisions in
      <xref linkend="svn.basic.in-action.revs"/>.</para>

    <para>For this chapter, we'll go back to the same example from
      <xref linkend="svn.basic"/>.  Remember that you and your
      collaborator, Sally, are sharing a repository that contains two
      projects, <filename>paint</filename> and
      <filename>calc</filename>.  Notice that in <xref
      linkend="svn.branchmerge.using.dia-1"/>, however, each project
      directory now contains subdirectories named
      <filename>trunk</filename> and <filename>branches</filename>.
      The reason for this will soon become clear.</para>

      <figure id="svn.branchmerge.using.dia-1">
        <title>Starting repository layout</title>
        <graphic fileref="images/ch04dia2.png"/>
      </figure>

    <para>As before, assume that Sally and you both have working
      copies of the <quote>calc</quote> project.  Specifically, you
      each have a working copy of <filename>/calc/trunk</filename>.
      All the files for the project are in this subdirectory rather
      than in <filename>/calc</filename> itself, because your team has
      decided that <filename>/calc/trunk</filename> is where the
      <quote>main line</quote> of development is going to take
      place.</para>

    <para>Let's say that you've been given the task of implementing a
      large software feature.  It will take a long time to write, and
      will affect all the files in the project.  The immediate problem
      is that you don't want to interfere with Sally, who is in the
      process of fixing small bugs here and there.  She's depending on
      the fact that the latest version of the project (in
      <filename>/calc/trunk</filename>) is always usable.  If you
      start committing your changes bit by bit, you'll surely break
      things for Sally (and other team members as well).</para>

    <para>One strategy is to crawl into a hole: you and Sally can stop
      sharing information for a week or two.  That is, start gutting
      and reorganizing all the files in your working copy, but don't
      commit or update until you're completely finished with the task.
      There are a number of problems with this, though.  First, it's
      not very safe.  Most people like to save their work to the
      repository frequently, should something bad accidentally happen
      to their working copy.  Second, it's not very flexible.  If you
      do your work on different computers (perhaps you have a working
      copy of <filename>/calc/trunk</filename> on two different
      machines), you'll need to manually copy your changes back and
      forth or just do all the work on a single computer.  By that
      same token, it's difficult to share your changes in progress
      with anyone else.  A common software development <quote>best
      practice</quote> is to allow your peers to review your work as
      you go.  If nobody sees your intermediate commits, you lose
      potential feedback and may end up going down the wrong path for
      weeks before another person on your team notices.  Finally, when
      you're finished with all your changes, you might find it very
      difficult to remerge your final work with the rest of the
      company's main body of code.  Sally (or others) may have made
      many other changes in the repository that are difficult to
      incorporate into your working copy&mdash;especially if you
      run <command>svn update</command> after weeks of
      isolation.</para>

    <para>The better solution is to create your own branch, or line of
      development, in the repository.  This allows you to save your
      half-broken work frequently without interfering with others, yet
      you can still selectively share information with your
      collaborators.  You'll see exactly how this works as we go.
      </para>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.using.create">
      <title>Creating a Branch</title>

      <para>Creating a branch is very simple&mdash;you make a copy of
        the project in the repository using the <command>svn
        copy</command> command.  Subversion is able to copy not only 
        single files, but whole directories as well.  In this case,
        you want to make a copy of the
        <filename>/calc/trunk</filename> directory.  Where should the
        new copy live?  Wherever you wish&mdash;it's a matter of
        project policy.  Let's say that your team has a policy of
        creating branches in the <filename>/calc/branches</filename>
        area of the repository, and you want to name your branch
        <literal>my-calc-branch</literal>.  You'll want to create a
        new directory,
        <filename>/calc/branches/my-calc-branch</filename>, which
        begins its life as a copy of
        <filename>/calc/trunk</filename>.</para>

      <para>You may already have seen <command>svn copy</command> used
        to copy one file to another within a working copy.  But it can
        also be used to do a <quote>remote</quote> copy entirely
        within the repository.  Just copy one URL to another:</para>

      <screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Creating a private branch of /calc/trunk."

Committed revision 341.
</screen>

      <para>This command causes a near-instantaneous commit in the
        repository, creating a new directory in revision 341.  The new
        directory is a copy of <filename>/calc/trunk</filename>.  This
        is shown in
        <xref linkend="svn.branchmerge.using.create.dia-1"/>.
        <footnote>
        <para>Subversion does not support copying between different
        repositories.  When using URLs with <command>svn
        copy</command> or <command>svn move</command>, you can only
        copy items within the same repository.</para> 
        </footnote>

        While it's also possible to create a branch by
        using <command>svn copy</command> to duplicate a directory
        within the working copy, this technique isn't recommended.  It
        can be quite slow, in fact!  Copying a directory on the
        client side is a linear-time operation, in that it actually
        has to duplicate every file and subdirectory on the local disk.
        Copying a directory on the server, however, is a constant-time
        operation, and it's the way most people create
        branches.</para>

      <figure id="svn.branchmerge.using.create.dia-1">
        <title>Repository with new copy</title>
        <graphic fileref="images/ch04dia3.png"/>
      </figure>

      <sidebar>
        <title>Cheap Copies</title>

        <para>Subversion's repository has a special design.  When you
          copy a directory, you don't need to worry about the
          repository growing huge&mdash;Subversion doesn't actually
          duplicate any data.  Instead, it creates a new directory
          entry that points to an <emphasis>existing</emphasis> tree.
          If you're an experienced Unix user, you'll recognize this as
          the same concept behind a hard link.  As further changes are
          made to files and directories beneath the copied directory,
          Subversion continues to employ this hard link concept where
          it can.  It duplicates data only when it is necessary to
          disambiguate different versions of objects.</para>

        <para>This is why you'll often hear Subversion users talk
          about <quote>cheap copies.</quote>  It doesn't matter how
          large the directory is&mdash;it takes a very tiny, constant
          amount of time and space to make a copy of it.  In fact,
          this feature is the basis of how commits work in Subversion:
          each revision is a <quote>cheap copy</quote> of the previous
          revision, with a few items lazily changed within.  (To read
          more about this, visit Subversion's web site and read about
          the <quote>bubble up</quote> method in Subversion's design
          documents.)</para>

        <para>Of course, these internal mechanics of copying and
          sharing data are hidden from the user, who simply sees
          copies of trees.  The main point here is that copies are
          cheap, both in time and in space.  If you create a branch
          entirely within the repository (by running <userinput>svn copy
          <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput>), it's a quick, constant-time operation.
          Make branches as often as you want.</para>
      </sidebar>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.using.work">
      <title>Working with Your Branch</title> 

      <para>Now that you've created a branch of the project, you can
        check out a new working copy to start using it:</para>

      <screen>
$ svn checkout http://svn.example.com/repos/calc/branches/my-calc-branch
A  my-calc-branch/Makefile
A  my-calc-branch/integer.c
A  my-calc-branch/button.c
Checked out revision 341.
</screen>

      <para>There's nothing special about this working copy; it simply
        mirrors a different directory in the repository.  When you
        commit changes, however, Sally won't see them when she
        updates, because her working copy is of
        <filename>/calc/trunk</filename>.  (Be sure to read <xref
        linkend="svn.branchmerge.switchwc"/> later in this chapter: the
        <command>svn switch</command> command is an alternative way of
        creating a working copy of a branch.)</para>

      <para>Let's pretend that a week goes by, and the following
        commits happen:</para>

      <itemizedlist>
        <listitem><para>
          You make a change to
          <filename>/calc/branches/my-calc-branch/button.c</filename>,
          which creates revision 342.</para>
        </listitem>

        <listitem><para>
          You make a change to
          <filename>/calc/branches/my-calc-branch/integer.c</filename>,
          which creates revision 343.</para>
        </listitem>

        <listitem><para>
          Sally makes a change to
          <filename>/calc/trunk/integer.c</filename>, which creates
          revision 344.</para>
        </listitem>
      </itemizedlist>

      <para>Now two independent lines of development (shown
        in <xref linkend="svn.branchmerge.using.work.dia-1"/>) are happening on
        <filename>integer.c</filename>.</para>

      <figure id="svn.branchmerge.using.work.dia-1">
        <title>The branching of one file's history</title>
        <graphic fileref="images/ch04dia4.png"/>
      </figure>

      <para>Things get interesting when you look at the history of
        changes made to your copy of
        <filename>integer.c</filename>:</para>

      <screen>
$ pwd
/home/user/my-calc-branch

$ svn log -v integer.c
------------------------------------------------------------------------
r343 | user | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/branches/my-calc-branch/integer.c

* integer.c:  frozzled the wazjub.

------------------------------------------------------------------------
r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   A /calc/branches/my-calc-branch (from /calc/trunk:340)

Creating a private branch of /calc/trunk.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   A /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------
</screen>

      <para>Notice that Subversion is tracing the history of your
        branch's <filename>integer.c</filename> all the way back
        through time, even traversing the point where it was copied.
        It shows the creation of the branch as an event in the
        history, because <filename>integer.c</filename> was implicitly
        copied when all of <filename>/calc/trunk/</filename> was
        copied.  Now look at what happens when Sally runs the same
        command on her copy of the file:</para>

      <screen>
$ pwd
/home/sally/calc

$ svn log -v integer.c
------------------------------------------------------------------------
r344 | sally | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  fix a bunch of spelling errors.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   A /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------
</screen>

      <para>Sally sees her own revision 344 change, but not the change
        you made in revision 343.  As far as Subversion is concerned,
        these two commits affected different files in different
        repository locations.  However, Subversion
        <emphasis>does</emphasis> show that the two files share a
        common history.  Before the branch copy was made in revision
        341, the files used to be the same file.  That's why you and
        Sally both see the changes made in revisions 303 and
        98.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.using.concepts">
      <title>The Key Concepts Behind Branching</title> 

      <para>You should remember two important lessons
        from this section.  First, Subversion has no internal concept
        of a branch&mdash;it knows only how to make copies.  When you
        copy a directory, the resultant directory is only
        a <quote>branch</quote> because <emphasis>you</emphasis>
        attach that meaning to it.  You may think of the directory
        differently, or treat it differently, but to Subversion it's
        just an ordinary directory that happens to carry some extra
        historical information.</para>

      <para>Second, because of this copy mechanism, Subversion's
        branches exist as <emphasis>normal filesystem
        directories</emphasis> in the repository.  This is different
        from other version control systems, where branches are
        typically defined by adding
        extra-dimensional <quote>labels</quote> to collections of
        files.  The location of your branch directory doesn't matter
        to Subversion.  Most teams follow a convention of putting all
        branches into a <filename>/branches</filename> directory, but
        you're free to invent any policy you wish.</para>

    </sect2>

  </sect1>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.basicmerging">
    <title>Basic Merging</title>

    <para>Now you and Sally are working on parallel branches of the
      project: you're working on a private branch, and Sally is
      working on the <firstterm>trunk</firstterm>, or main line of
      development.</para>

    <para>For projects that have a large number of contributors, it's
      common for most people to have working copies of the trunk.
      Whenever someone needs to make a long-running change that is
      likely to disrupt the trunk, a standard procedure is to create a
      private branch and commit changes there until all the work is
      complete.</para>

    <para>So, the good news is that you and Sally aren't interfering
      with each other.  The bad news is that it's very easy to drift
      <emphasis>too</emphasis> far apart.  Remember that one of the
      problems with the <quote>crawl in a hole</quote> strategy is
      that by the time you're finished with your branch, it may be
      near-impossible to merge your changes back into the trunk
      without a huge number of conflicts.</para>

    <para>Instead, you and Sally might continue to share changes as
      you work.  It's up to you to decide which changes are worth
      sharing; Subversion gives you the ability to selectively
      <quote>copy</quote> changes between branches.  And when you're
      completely finished with your branch, your entire set of branch
      changes can be copied back into the trunk.  In Subversion
      terminology, the general act of replicating changes from one
      branch to another is called <firstterm>merging</firstterm>, and
      it is performed using various invocations of the <command>svn
      merge</command> command.</para>

    <para>In the examples that follow, we're assuming that both your
      Subversion client and server are running Subversion 1.5 (or
      later).  If either client or server is older than version 1.5,
      things are more complicated: the system won't track changes
      automatically, and you'll have to use painful manual methods to
      achieve similar results.  That is, you'll always need to use the
      detailed merge syntax to specify specific ranges of revisions to
      replicate (see
      <xref linkend="svn.branchmerge.advanced.advancedsyntax"/> later
      in this chapter), and take special care to keep track of what's
      already been merged and what hasn't.  For this reason,
      we <emphasis>strongly</emphasis> recommend that you make sure your
      client and server are at least at version 1.5.</para>

  <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.changesets">
      <title>Changesets</title>

      <para>Before we proceed further, we should warn you that there's
        going to be a lot of discussion of <quote>changes</quote> in
        the pages ahead.  A lot of people experienced with version
        control systems use the terms <quote>change</quote>
        and <quote>changeset</quote> interchangeably, and we should
        clarify what Subversion understands as
        a <firstterm>changeset</firstterm>.</para>

      <para>Everyone seems to have a slightly different definition
        of changeset, or at least a different
        expectation of what it means for a version control system to
        have one.  For our purposes, let's say that a changeset is just
        a collection of changes with a unique name.  The changes might
        include textual edits to file contents, modifications to tree
        structure, or tweaks to metadata.  In more common speak, a
        changeset is just a patch with a name you can refer to.</para>

      <para>In Subversion, a global revision number N names a tree in
        the repository: it's the way the repository looked after the
        Nth commit.  It's also the name of an implicit changeset: if
        you compare tree N with tree N&minus;1, you can derive the exact
        patch that was committed.  For this reason, it's easy to think
        of revision N as not just a tree, but a changeset as well.  If
        you use an issue tracker to manage bugs, you can use the
        revision numbers to refer to particular patches that fix
        bugs&mdash;for example,
        <quote>this issue was fixed by r9238.</quote> Somebody
        can then run <userinput>svn log -r 9238</userinput> to read about
        the exact changeset that fixed the bug, and run
        <userinput>svn diff -c 9238</userinput> to see the patch itself.
        And (as you'll see shortly)
        Subversion's <command>svn merge</command> command is able to use
        revision numbers.  You can merge specific changesets from one
        branch to another by naming them in the merge
        arguments: passing <userinput>-c 9238</userinput> to <command>svn merge</command> would merge
        changeset r9238 into your working copy.</para>

      </sect2>

  <!-- =============================================================== -->
    <sect2 id="svn.branchemerge.basicmerging.stayinsync">
      <title>Keeping a Branch in Sync</title>

      <para>Continuing with our running example, let's suppose that a
        week has passed since you started working on your private
        branch.  Your new feature isn't finished yet, but at the same
        time you know that other people on your team have continued to
        make important changes in the
        project's <filename>/trunk</filename>.  It's in your best
        interest to replicate those changes to your own branch, just
        to make sure they mesh well with your changes.  In fact, this
        is a best practice: frequently keeping your branch in sync
        with the main development line helps
        prevent <quote>surprise</quote> conflicts when it comes time
        for you to fold your changes back into the trunk.</para>

      <para>Subversion is aware of the history of your branch and
        knows when it divided away from the trunk.  To replicate the
        latest, greatest trunk changes to your branch, first make sure
        your working copy of the branch
        is <quote>clean</quote>&mdash;that it has no local
        modifications reported by <command>svn status</command>.  Then
        simply run:</para>

      <screen>
$ pwd
/home/user/my-calc-branch

$ svn merge http://svn.example.com/repos/calc/trunk
--- Merging r345 through r356 into '.':
U    button.c
U    integer.c
</screen>

      <para>This basic syntax&mdash;<userinput>svn merge
        <replaceable>URL</replaceable></userinput>&mdash;tells Subversion to merge all recent
        changes from the URL to the current working directory (which
        is typically the root of your working copy).  After running
        the prior example, your branch working copy now contains new
        local modifications, and these edits are duplications of all
        of the changes that have happened on the trunk since you first
        created your branch:</para>

      <screen>
$ svn status
 M     .
M      button.c
M      integer.c
</screen>

      <para>At this point, the wise thing to do is look at the changes
        carefully with <command>svn diff</command>, and then build and
        test your branch.  Notice that the current working directory
        (<quote><filename>.</filename></quote>) has also been
        modified; the <command>svn diff</command> will show that
        its <literal>svn:mergeinfo</literal> property has been either
        created or modified.  This is important merge-related metadata
        that you should <emphasis>not</emphasis> touch, since it will
        be needed by future <command>svn merge</command> commands.
        (We'll learn more about this metadata later in the
        chapter.)</para>

      <para>After performing the merge, you might also need to resolve
        some conflicts (just as you do with <command>svn
        update</command>) or possibly make some small edits to get
        things working properly.  (Remember, just because there are
        no <emphasis>syntactic</emphasis> conflicts doesn't mean there
        aren't any <emphasis>semantic</emphasis> conflicts!)  If you
        encounter serious problems, you can always abort the local
        changes by running <userinput>svn revert . -R</userinput> (which
        will undo all local modifications) and start a
        long <quote>what's going on?</quote> discussion with your
        collaborators.  If things look good, however, you can
        submit these changes into the repository:</para>

      <screen>
$ svn commit -m "Merged latest trunk changes to my-calc-branch."
Sending        .
Sending        button.c
Sending        integer.c
Transmitting file data ..
Committed revision 357.
</screen>

      <para>At this point, your private branch is now <quote>in
          sync</quote> with the trunk, so you can rest easier knowing
          that as you continue to work in isolation, you're not
          drifting too far away from what everyone else is
          doing.</para>

      <sidebar>
        <title>Why Not Use Patches Instead?</title>

        <para>A question may be on your mind, especially if you're a
          Unix user: why bother to use <command>svn merge</command> at
          all?  Why not simply use the operating system's
          <command>patch</command> command to accomplish the same job?
          For example:</para>

        <screen>
$ cd my-calc-branch
$ svn diff -r 341:HEAD http://svn.example.com/repos/calc/trunk &gt; patchfile
$ patch -p0  &lt; patchfile
Patching file integer.c using Plan A...
Hunk #1 succeeded at 147.
Hunk #2 succeeded at 164.
Hunk #3 succeeded at 241.
Hunk #4 succeeded at 249.
done
</screen>

        <para>In this particular example, there really isn't much
          difference.  But <command>svn merge</command> has special
          abilities that surpass the <command>patch</command> program.
          The file format used by <command>patch</command> is quite
          limited; it's able to tweak file contents only.  There's no
          way to represent changes to <emphasis>trees</emphasis>, such
          as the addition, removal, or renaming of files and
          directories.  Nor can the <command>patch</command> program
          notice changes to properties.  If Sally's change had,
          say, added a new directory, the output of <command>svn
          diff</command> wouldn't have mentioned it at
          all.  <command>svn diff</command> outputs only the limited
          patch format, so there are some ideas it simply can't
          express.</para>

        <para>The <command>svn merge</command> command, however, can
          express changes in tree structure and properties by directly
          applying them to your working copy.  Even more important,
          this command records the changes that have been duplicated
          to your branch so that Subversion is aware of exactly which
          changes exist in each location (see
          <xref linkend="svn.branchmerge.basicmerging.mergeinfo"/>.)
          This is a critical feature that makes branch management
          usable; without it, users would have to manually keep notes
          on which sets of changes have or haven't been merged
          yet.</para>

      </sidebar>

      <para>Suppose that another week has passed.  You've committed
        more changes to your branch, and your comrades have continued
        to improve the trunk as well.  Once again, you'd like to
        replicate the latest trunk changes to your branch and bring
        yourself in sync.  Just run the same merge command
        again!</para>

      <screen>
$ svn merge http://svn.example.com/repos/calc/trunk
--- Merging r357 through r380 into '.':
U    integer.c
U    Makefile
A    README
</screen>

      <para>Subversion knows which trunk changes you've already
        replicated to your branch, so it carefully replicates only
        those changes you don't yet have.  Once again, you'll have to
        build, test, and <command>svn commit</command> the local
        modifications to your branch.</para>

      <para>What happens when you finally finish your work, though?
        Your new feature is done, and you're ready to merge your
        branch changes back to the trunk (so your team can enjoy the
        bounty of your labor).  The process is simple.  First, bring
        your branch in sync with the trunk again, just as you've been
        doing all along:</para>

      <screen>
$ svn merge http://svn.example.com/repos/calc/trunk
--- Merging r381 through r385 into '.':
U    button.c
U    README

$ # build, test, ...

$ svn commit -m "Final merge of trunk changes to my-calc-branch."
Sending        .
Sending        button.c
Sending        README
Transmitting file data ..
Committed revision 390.
</screen>

      <para>Now, you use <command>svn merge</command> to replicate
        your branch changes back into the trunk.  You'll need an
        up-to-date working copy of <filename>/trunk</filename>.  You
        can do this by either doing an <command>svn
        checkout</command>, dredging up an old trunk working copy from
        somewhere on your disk, or using <command>svn 
        switch</command> (see
        <xref linkend="svn.branchmerge.switchwc"/>.) However you get a
        trunk working copy, remember that it's a best practice to do
        your merge into a working copy that
        has <emphasis>no</emphasis> local edits and has been recently
        updated (i.e., is not a mixture of local revisions).  If your
        working copy isn't <quote>clean</quote> in these ways, you can
        run into some unnecessary conflict-related headaches
        and <command>svn merge</command> will likely return an
        error.</para>

      <para>Once you have a clean working copy of the trunk, you're
        ready to merge your branch back into it:</para>

      <screen>
$ pwd
/home/user/calc-trunk

$ svn update  # (make sure the working copy is up to date)
At revision 390.

$ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch
--- Merging differences between repository URLs into '.':
U    button.c
U    integer.c
U    Makefile
 U   .

$ # build, test, verify, ...

$ svn commit -m "Merge my-calc-branch back into trunk!"
Sending        .
Sending        button.c
Sending        integer.c
Sending        Makefile
Transmitting file data ..
Committed revision 391.
</screen>

      <para>Congratulations, your branch has now been remerged back
        into the main line of development.  Notice our use of
        the <option>--reintegrate</option> option this time around.
        The option is critical for reintegrating changes from a branch
        back into its original line of development&mdash;don't forget
        it!  It's needed because this sort of <quote>merge
        back</quote> is a different sort of work than what you've been
        doing up until now.  Previously, we had been
        asking <command>svn merge</command> to grab the <quote>next
        set</quote> of changes from one line of development (the
        trunk) and duplicate them to another (your branch).  This is
        fairly straightforward, and each time Subversion knows how to
        pick up where it left off.  In our prior examples, you can see
        that first it merges the ranges 345:356 from trunk to branch;
        later on, it continues by merging the next contiguously
        available range, 356:380.  When doing the final sync, it
        merges the range 380:385.</para>

      <para>When merging your branch back to the trunk, however, the
        underlying mathematics is quite different.  Your feature
        branch is now a mishmosh of both duplicated trunk changes and
        private branch changes, so there's no simple contiguous range
        of revisions to copy over.  By specifying
        the <option>--reintegrate</option> option, you're asking
        Subversion to carefully replicate <emphasis>only</emphasis>
        those changes unique to your branch.  (And in fact, it does
        this by comparing the latest trunk tree with the latest branch
        tree:  the resulting difference is exactly your branch
        changes!)</para>

      <para>Now that your private branch is merged to trunk, you may
        wish to remove it from the repository:</para>

      <screen>
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Remove my-calc-branch."
Committed revision 392.
</screen>

      <para>But wait!  Isn't the history of that branch valuable?
        What if somebody wants to audit the evolution of your feature
        someday and look at all of your branch changes?  No need to
        worry.  Remember that even though your branch is no longer
        visible in the <filename>/branches</filename> directory, its
        existence is still an immutable part of the repository's
        history.  A simple <command>svn log</command> command on
        the <filename>/branches</filename> URL will show the entire
        history of your branch.  Your branch can even be resurrected
        at some point, should you desire (see
        <xref linkend="svn.branchmerge.basicmerging.resurrect"/>).</para>

      <para>In Subversion 1.5, once
        a <option>--reintegrate</option> merge is done from branch to trunk,
        the branch is no longer usable for further work.  It's not
        able to correctly absorb new trunk changes, nor can it be
        properly reintegrated to trunk again.  For this reason, if you
        want to keep working on your feature branch, we recommend
        destroying it and then re-creating it from the trunk:</para>

      <screen>
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Remove my-calc-branch."
Committed revision 392.

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/new-branch
      -m "Create a new branch from trunk."
Committed revision 393.

$ cd my-calc-branch

$ svn switch http://svn.example.com/repos/calc/branches/new-branch
Updated to revision 393.
</screen>

      <para>The final command in the prior example&mdash;<command>svn
        switch</command>&mdash;is a way of updating an existing working
        copy to reflect a different repository directory.  We'll discuss
        this more in <xref linkend="svn.branchmerge.switchwc"/>.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.basicmerging.mergeinfo">
      <title>Mergeinfo and Previews</title>

      <para>The basic mechanism Subversion uses to track
        changesets&mdash;that is, which changes have been merged to
        which branches&mdash;is by recording data in properties.
        Specifically, merge data is tracked in
        the <literal>svn:mergeinfo</literal> property attached to
        files and directories.  (If you're not familiar with
        Subversion properties, now is the time to skim
        <xref linkend="svn.advanced.props"/>.)</para>

      <para>You can examine the property, just like any
        other:</para>

      <screen>
$ cd my-calc-branch
$ svn propget svn:mergeinfo .
/trunk:341-390
</screen>

      <para>It is <emphasis>not</emphasis> recommended that you change
        the value of this property yourself, unless you really know
        what you're doing.  This property is automatically maintained
        by Subversion whenever you run <command>svn merge</command>.
        Its value indicates which changes (at a given path) have been
        replicated into the directory in question.  In this case, the
        path is <filename>/trunk</filename> and the directory which
        has received the specific changes
        is <filename>/branches/my-calc-branch</filename>.</para>

      <para>There's also a subcommand, <command>svn
        mergeinfo</command>, which can be helpful in seeing not only
        which changesets a directory has absorbed, but also which
        changesets it's still eligible to receive.  This gives a sort
        of preview of the next set of changes that <command>svn
        merge</command> will replicate to your branch.</para>

      <screen>
$ cd my-calc-branch

# Which changes have already been merged from trunk to branch?
$ svn mergeinfo http://svn.example.com/repos/calc/trunk
r341
r342
r343
&hellip;
r388
r389
r390

# Which changes are still eligible to merge from trunk to branch?
$ svn mergeinfo http://svn.example.com/repos/calc/trunk --show-revs eligible
r391
r392
r393
r394
r395
</screen>

      <para>The <command>svn mergeinfo</command> command requires
        a <quote>source</quote> URL (where the changes would be coming
        from), and takes an optional <quote>target</quote> URL (where
        the changes would be merged to).  If no target URL is given,
        it assumes that the current working directory is the
        target.  In the prior example, because we're querying our
        branch working copy, the command assumes we're interested in
        receiving changes to <filename>/branches/mybranch</filename>
        from the specified trunk URL.</para>

      <para>Another way to get a more precise preview of a merge
        operation is to use the <option>--dry-run</option>
        option:</para>

      <screen>
$ svn merge http://svn.example.com/repos/calc/trunk --dry-run
U    integer.c

$ svn status
#  nothing printed, working copy is still unchanged.
</screen>

      <para>The <option>--dry-run</option> option doesn't actually
        apply any local changes to the working copy.  It shows only
        status codes that <emphasis>would</emphasis> be printed in a
        real merge.  It's useful for getting a <quote>high-level</quote>
        preview of the potential merge, for those times
        when running <command>svn diff</command> gives too much
        detail.</para>

      <tip>
        <para>After performing a merge operation, but before committing
          the results of the merge, you can use <userinput>svn diff
          --depth=empty <replaceable>/path/to/merge/target</replaceable></userinput> to see only
          the changes to the immediate target of your merge.  If your
          merge target was a directory, only property differences will
          be displayed.  This is a handy way to see the changes to the
          <literal>svn:mergeinfo</literal> property recorded by the
          merge operation, which will remind you about what you've
          just merged.</para>
      </tip>

      <para>Of course, the best way to preview a merge operation is to
        just do it!  Remember, running <command>svn merge</command>
        isn't an inherently risky thing (unless you've made local
        modifications to your working copy&mdash;but we've already
        stressed that you shouldn't be merging into such an
        environment).  If you don't like the results of the merge,
        simply run <userinput>svn revert . -R</userinput> to revert the changes from
        your working copy and retry the command with different
        options.  The merge isn't final until you
        actually <command>svn commit</command> the results.</para>

      <tip>
        <para>While it's perfectly fine to experiment with merges by
          running <command>svn merge</command> and <command>svn
          revert</command> over and over, you may run into some
          annoying (but easily bypassed) roadblocks.  For example, if
          the merge operation adds a new file (i.e., schedules it for
          addition), <command>svn revert</command> won't actually
          remove the file; it simply unschedules the addition.  You're
          left with an unversioned file.  If you then attempt to run
          the merge again, you may get conflicts due to the
          unversioned file <quote>being in the way.</quote> Solution?
          After performing a revert, be sure to clean up the working
          copy and remove unversioned files and directories.  The
          output of <command>svn status</command> should be as clean
          as possible, ideally showing no output.</para>
      </tip>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.basicmerging.undo">
      <title>Undoing Changes</title>

      <para>An extremely common use for <command>svn merge</command>
        is to roll back a change that has already been committed.
        Suppose you're working away happily on a working copy of
        <filename>/calc/trunk</filename>, and you discover that the
        change made way back in revision 303, which changed
        <filename>integer.c</filename>, is completely wrong.  It never
        should have been committed.  You can use <command>svn
        merge</command> to <quote>undo</quote> the change in your
        working copy, and then commit the local modification to the
        repository.  All you need to do is to specify a
        <emphasis>reverse</emphasis> difference.  (You can do this by
        specifying <option>--revision 303:302</option>, or by an
        equivalent <option>--change -303</option>.)</para>


      <screen>
$ svn merge -c -303 http://svn.example.com/repos/calc/trunk
--- Reverse-merging r303 into 'integer.c':
U    integer.c

$ svn status
 M     .
M      integer.c

$ svn diff
&hellip;
# verify that the change is removed
&hellip;

$ svn commit -m "Undoing change committed in r303."
Sending        integer.c
Transmitting file data .
Committed revision 350.
</screen>

      <para>As we mentioned earlier, one way to think about a
        repository revision is as a specific changeset.  By using the
        <option>-r</option> option, you can ask <command>svn
        merge</command> to apply a changeset, or a whole range of
        changesets, to your working copy.  In our case of undoing a
        change, we're asking <command>svn merge</command> to apply
        changeset #303 to our working copy
        <emphasis>backward</emphasis>.</para>

      <para>Keep in mind that rolling back a change like this is just
        like any other <command>svn merge</command> operation, so you
        should use <command>svn status</command> and <command>svn
        diff</command> to confirm that your work is in the state you
        want it to be in, and then use <command>svn commit</command>
        to send the final version to the repository.  After
        committing, this particular changeset is no longer reflected
        in the <literal>HEAD</literal> revision.</para>

      <para>Again, you may be thinking: well, that really didn't undo
        the commit, did it?  The change still exists in revision 303.
        If somebody checks out a version of the
        <filename>calc</filename> project between revisions 303 and
        349, she'll still see the bad change, right?</para>

      <para>Yes, that's true.  When we talk about
        <quote>removing</quote> a change, we're really talking about
        removing it from the <literal>HEAD</literal> revision.  The
        original change still exists in the repository's history.  For
        most situations, this is good enough.  Most people are only
        interested in tracking the <literal>HEAD</literal> of a
        project anyway.  There are special cases, however, where you
        really might want to destroy all evidence of the commit.
        (Perhaps somebody accidentally committed a confidential
        document.)  This isn't so easy, it turns out, because
        Subversion was deliberately designed to never lose
        information.  Revisions are immutable trees that build upon
        one another.  Removing a revision from history would cause a
        domino effect, creating chaos in all subsequent revisions and
        possibly invalidating all working copies.
        <footnote>
          <para>The Subversion project has plans, however, to someday
            implement a command that would accomplish the task of
            permanently deleting information.  In the meantime, see
            <xref linkend="svn.reposadmin.maint.tk.svndumpfilter"/>
            for a possible workaround.</para>
        </footnote>
      </para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.basicmerging.resurrect">
      <title>Resurrecting Deleted Items</title>

      <para>The great thing about version control systems is that
        information is never lost.  Even when you delete a file or
        directory, it may be gone from the <literal>HEAD</literal>
        revision, but the object still exists in earlier revisions.
        One of the most common questions new users ask is, <quote>How
        do I get my old file or directory back?</quote></para>

      <para>The first step is to define
        exactly <emphasis>which</emphasis> item you're
        trying to resurrect.  Here's a useful metaphor: you can think
        of every object in the repository as existing in a sort of
        two-dimensional coordinate system.  The first coordinate is a
        particular revision tree, and the second coordinate is a path
        within that tree.  So every version of your file or directory
        can be defined by a specific coordinate pair.  (Remember the
        <quote>peg revision</quote>
        syntax&mdash;foo.c@224&mdash;mentioned back in
        <xref linkend="svn.advanced.pegrevs"/>.) </para>

      <para>First, you might need to use <command>svn log</command> to
        discover the exact coordinate pair you wish to resurrect.  A
        good strategy is to run <userinput>svn log --verbose</userinput>
        in a directory that used to contain your deleted item.  The
        <option>--verbose</option> (<option>-v</option>) option shows
        a list of all changed items in each revision; all you need to
        do is find the revision in which you deleted the file or
        directory.  You can do this visually, or by using another tool
        to examine the log output (via <command>grep</command>, or
        perhaps via an incremental search in an editor).</para>

      <screen>
$ cd parent-dir
$ svn log -v
&hellip;
------------------------------------------------------------------------
r808 | joe | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines
Changed paths:
   D /calc/trunk/real.c
   M /calc/trunk/integer.c

Added fast fourier transform functions to integer.c.
Removed real.c because code now in double.c.
&hellip;
</screen>

      <para>In the example, we're assuming that you're looking for a
        deleted file <filename>real.c</filename>.  By looking through
        the logs of a parent directory, you've spotted that this file
        was deleted in revision 808.  Therefore, the last version of
        the file to exist was in the revision right before that.
        Conclusion: you want to resurrect the path
        <filename>/calc/trunk/real.c</filename> from revision
        807.</para>

      <para>That was the hard part&mdash;the research.  Now that you
        know what you want to restore, you have two different
        choices.</para>

      <para>One option is to use <command>svn merge</command> to apply
        revision 808 <quote>in reverse.</quote> (We already
        discussed how to undo changes in
        <xref linkend="svn.branchmerge.basicmerging.undo"/>.)  This
        would have the effect of re-adding <filename>real.c</filename>
        as a local modification.  The file would be scheduled for
        addition, and after a commit, the file would again exist
        in <literal>HEAD</literal>.</para>

      <para>In this particular example, however, this is probably not
        the best strategy.  Reverse-applying revision 808 would not
        only schedule <filename>real.c</filename> for addition, but
        the log message indicates that it would also undo certain
        changes to <filename>integer.c</filename>, which you don't
        want.  Certainly, you could reverse-merge revision 808 and
        then <command>svn revert</command> the local modifications to
        <filename>integer.c</filename>, but this technique doesn't
        scale well.  What if 90 files were changed in revision
        808?</para>

      <para>A second, more targeted strategy is not to use
        <command>svn merge</command> at all, but rather to use the
        <command>svn copy</command> command.  Simply copy the exact
        revision and path <quote>coordinate pair</quote> from the
        repository to your working copy:</para>

      <screen>
$ svn copy http://svn.example.com/repos/calc/trunk/real.c@807 ./real.c

$ svn status
A  +   real.c

$ svn commit -m "Resurrected real.c from revision 807, /calc/trunk/real.c."
Adding         real.c
Transmitting file data .
Committed revision 1390.
</screen>

      <para>The plus sign in the status output indicates that the item
        isn't merely scheduled for addition, but scheduled for
        addition <quote>with history.</quote>  Subversion remembers
        where it was copied from.  In the future, running <command>svn
        log</command> on this file will traverse back through the
        file's resurrection and through all the history it had prior
        to revision 807.  In other words, this new
        <filename>real.c</filename> isn't really new; it's a direct
        descendant of the original, deleted file.  This is usually
        considered a good and useful thing.  If, however, you wanted
        to resurrect the file <emphasis>without</emphasis>
        maintaining a historical link to the old file, this technique
        works just as well:</para>

      <screen>
$ svn cat http://svn.example.com/repos/calc/trunk/real.c@807 &gt; ./real.c

$ svn add real.c
A         real.c

$ svn commit -m "Re-created real.c from revision 807."
Adding         real.c
Transmitting file data .
Committed revision 1390.
</screen>

      <para>Although our example shows us resurrecting a file, note
        that these same techniques work just as well for resurrecting
        deleted directories.  Also note that a resurrection doesn't
        have to happen in your working copy&mdash;it can happen
        entirely in the repository:</para>

      <screen>
$ svn copy http://svn.example.com/repos/calc/trunk/real.c@807 \
           http://svn.example.com/repos/calc/trunk/ \
      -m "Resurrect real.c from revision 807."
Committed revision 1390.

$ svn update
A    real.c
Updated to revision 1390.
</screen>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.advanced">
    <title>Advanced Merging</title>

    <para>Here ends the automated magic.  Sooner or later, once you
      get the hang of branching and merging, you're going to have to
      ask Subversion to merge <emphasis>specific</emphasis> changes
      from one place to another.  To do this, you're going to
      have to start passing more complicated arguments to <command>svn
      merge</command>.  The next section describes the fully expanded
      syntax of the command and discusses a number of common
      scenarios that require it.</para>


    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.cherrypicking">
      <title>Cherrypicking</title>

      <para>Just as the term <quote>changeset</quote> is often used in
        version control systems, so is the term
        <firstterm>cherrypicking</firstterm>.  This word refers to
        the act of choosing <emphasis>one</emphasis> specific
        changeset from a branch and replicating it to another.
        Cherrypicking may also refer to the act of duplicating a
        particular set of (not necessarily contiguous!) changesets
        from one branch to another.  This is in contrast to more
        typical merging scenarios, where the <quote>next</quote>
        contiguous range of revisions is duplicated
        automatically.</para>

      <para>Why would people want to replicate just a single change?
        It comes up more often than you'd think.  For example, let's
        go back in time and imagine that you haven't yet merged your
        private feature branch back to the trunk.  At the
        water cooler, you get word that Sally made an interesting
        change to <filename>integer.c</filename> on the trunk.
        Looking over the history of commits to the trunk, you see that
        in revision 355 she fixed a critical bug that directly
        impacts the feature you're working on.  You might not be ready
        to merge all the trunk changes to your branch just yet, but
        you certainly need that particular bug fix in order to continue
        your work.</para>

      <screen>
$ svn diff -c 355 http://svn.example.com/repos/calc/trunk

Index: integer.c
===================================================================
--- integer.c	(revision 354)
+++ integer.c	(revision 355)
@@ -147,7 +147,7 @@
     case 6:  sprintf(info-&gt;operating_system, "HPFS (OS/2 or NT)"); break;
     case 7:  sprintf(info-&gt;operating_system, "Macintosh"); break;
     case 8:  sprintf(info-&gt;operating_system, "Z-System"); break;
-    case 9:  sprintf(info-&gt;operating_system, "CP/MM");
+    case 9:  sprintf(info-&gt;operating_system, "CP/M"); break;
     case 10:  sprintf(info-&gt;operating_system, "TOPS-20"); break;
     case 11:  sprintf(info-&gt;operating_system, "NTFS (Windows NT)"); break;
     case 12:  sprintf(info-&gt;operating_system, "QDOS"); break;
</screen>

      <para>Just as you used <command>svn diff</command> in the prior
        example to examine revision 355, you can pass the same option
        to <command>svn merge</command>:</para>

      <screen>
$ svn merge -c 355 http://svn.example.com/repos/calc/trunk
U    integer.c

$ svn status
M      integer.c
</screen>

      <para>You can now go through the usual testing procedures before
        committing this change to your branch.  After the commit,
        Subversion marks r355 as having been merged to the branch so
        that future <quote>magic</quote> merges that synchronize your
        branch with the trunk know to skip over r355.  (Merging the
        same change to the same branch almost always results in a
        conflict!)</para>

      <screen>
$ cd my-calc-branch

$ svn propget svn:mergeinfo .
/trunk:341-349,355

# Notice that r355 isn't listed as "eligible" to merge, because
# it's already been merged.
$ svn mergeinfo http://svn.example.com/repos/calc/trunk --show-revs eligible
r350
r351
r352
r353
r354
r356
r357
r358
r359
r360

$ svn merge http://svn.example.com/repos/calc/trunk
--- Merging r350 through r354 into '.':
 U   .
U    integer.c
U    Makefile
--- Merging r356 through r360 into '.':
 U   .
U    integer.c
U    button.c
</screen>

      <para>This use case of replicating
        (or <firstterm>backporting</firstterm>) bug fixes from one
        branch to another is perhaps the most popular reason for
        cherrypicking changes; it comes up all the time, for example,
        when a team is maintaining a <quote>release branch</quote> of
        software.  (We discuss this pattern in
        <xref linkend="svn.branchmerge.commonpatterns.release"/>.)</para>

      <warning>
        <para>Did you notice how, in the last example, the merge
          invocation caused two distinct ranges of merges to be
          applied?  The <command>svn merge</command> command applied
          two independent patches to your working copy to
          skip over changeset 355, which your branch already
          contained.  There's nothing inherently wrong with this,
          except that it has the potential to make conflict resolution
          trickier.  If the first range of changes creates
          conflicts, you <emphasis>must</emphasis> resolve them
          interactively for the merge process to continue and
          apply the second range of changes.  If you postpone a
          conflict from the first wave of changes, the whole merge
          command will bail out with an error message.
          <footnote>
            <para>At least, this is true in Subversion 1.5 at the time
              of this writing.  This behavior may improve in future
              versions of Subversion.</para>
          </footnote> 
        </para>
      </warning>

      <para>A word of warning: while <command>svn diff</command> and
        <command>svn merge</command> are very similar in concept, they
        do have different syntax in many cases.  Be sure to read about
        them in <xref linkend="svn.ref"/> for details, or ask
        <command>svn help</command>.  For example, <command>svn
        merge</command> requires a working copy path as a target, that is,
        a place where it should apply the generated patch.  If the
        target isn't specified, it assumes you are trying to perform
        one of the following common operations:</para>

      <itemizedlist>
        <listitem>
          <para>You want to merge directory changes into your current
            working directory.</para>
        </listitem>
        <listitem>
          <para>You want to merge the changes in a specific file into
            a file by the same name that exists in your current working
            directory.</para>
        </listitem>
      </itemizedlist>

      <para>If you are merging a directory and haven't specified a
        target path, <command>svn merge</command> assumes the first
        case and tries to apply the changes into your current
        directory.  If you are merging a file, and that file (or a
        file by the same name) exists in your current working
        directory,
        <command>svn merge</command> assumes the second case and tries
        to apply the changes to a local file with the same name.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.advanced.advancedsyntax">
      <title>Merge Syntax:  Full Disclosure</title>

      <para>You've now seen some examples of the <command>svn
        merge</command> command, and you're about to see several more.
        If you're feeling confused about exactly how merging works,
        you're not alone.  Many users (especially those new to version
        control) are initially perplexed about the proper syntax of
        the command and about how and when the feature should be
        used.  But fear not, this command is actually much simpler
        than you think!  There's a very easy technique for
        understanding exactly how <command>svn merge</command>
        behaves.</para>

      <para>The main source of confusion is the
        <emphasis>name</emphasis> of the command.  The term
        <quote>merge</quote> somehow denotes that branches are
        combined together, or that some sort of mysterious
        blending of data is going on.  That's not the case.  A better
        name for the command might have been <command>svn
        diff-and-apply</command>, because that's all that happens:
        two repository trees are compared, and the differences are
        applied to a working copy.</para>

      <para>If you're using <command>svn merge</command> to do basic
        copying of changes between branches, it will generally do the
        right thing automatically.  For example, a command such as the
        following:</para>

      <screen>
$ svn merge http://svn.example.com/repos/calc/some-branch
</screen>

      <para>will attempt to duplicate any changes made
        on <filename>some-branch</filename> into your current working
        directory, which is presumably a working copy that shares some
        historical connection to the branch.  The command is smart
        enough to only duplicate changes that your working copy
        doesn't yet have.  If you repeat this command once a week, it
        will only duplicate the <quote>newest</quote> branch changes
        that happened since you last merged.</para>

      <para>If you choose to use the <command>svn merge</command>
        command in all its full glory by giving it specific revision
        ranges to duplicate, the command takes three main
        arguments:</para>

      <orderedlist>

        <listitem><para>An initial repository tree (often called the
        <firstterm>left side</firstterm> of the
        comparison)</para></listitem>

        <listitem><para>A final repository tree (often called the
        <firstterm>right side</firstterm> of the
        comparison)</para></listitem>

        <listitem><para>A working copy to accept the differences as
        local changes (often called the <firstterm>target</firstterm>
        of the merge)</para></listitem>

      </orderedlist>

      <para>Once these three arguments are specified, the two trees
        are compared, and the differences are applied to the
        target working copy as local modifications.  When the command
        is done, the results are no different than if you had
        hand-edited the files or run various <command>svn
        add</command> or <command>svn delete</command> commands
        yourself.  If you like the results, you can commit them.  If
        you don't like the results, you can simply <command>svn
        revert</command> all of the changes.</para>

      <para>The syntax of <command>svn merge</command> allows you to
        specify the three necessary arguments rather flexibly.  Here
        are some examples:</para>

      <screen>
$ svn merge http://svn.example.com/repos/branch1@150 \
            http://svn.example.com/repos/branch2@212 \
            my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk
</screen>

      <para>The first syntax lays out all three arguments explicitly,
        naming each tree in the form <emphasis>URL@REV</emphasis> and
        naming the working copy target.  The second syntax can be used
        as a shorthand for situations when you're comparing two
        different revisions of the same URL.  The last syntax shows
        how the working copy argument is optional; if omitted, it
        defaults to the current directory.</para>

      <para>While the first example shows the <quote>full</quote>
        syntax of <command>svn merge</command>, it needs to be used
        very carefully;  it can result in merges which do not record
        any <literal>svn:mergeinfo</literal> metadata at all.  The
        next section talks a bit more about this.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.nomergedata">
      <title>Merges Without Mergeinfo</title>

      <para>Subversion tries to generate merge metadata whenever it
        can, to make future invocations of <command>svn
        merge</command> smarter.  There are still situations, however,
        where <literal>svn:mergeinfo</literal> data is not created or
        changed.  Remember to be a bit wary of these scenarios:</para>

      <variablelist>
        <varlistentry>
          <term>Merging unrelated sources</term>
          <listitem>
          <para>If you
            ask <command>svn merge</command> to compare two URLs that
            aren't related to each other, a patch will still be
            generated and applied to your working copy, but no merging
            metadata will be created.  There's no common history
            between the two sources, and future <quote>smart</quote>
            merges depend on that common history.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Merging from foreign repositories</term>
          <listitem>
          <para>While it's possible to run a
            command such as <userinput>svn merge -r 100:200
            <replaceable>http://svn.foreignproject.com/repos/trunk</replaceable></userinput>, the
            resultant patch will also lack any historical merge
            metadata.  At time of this writing, Subversion has no way of
            representing different repository URLs within
            the <literal>svn:mergeinfo</literal> property.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Using <option>--ignore-ancestry</option></term>
          <listitem>
          <para>If this option is passed to <command>svn
            merge</command>, it causes the merging logic to mindlessly
            generate differences the same way that <command>svn
            diff</command> does, ignoring any historical
            relationships.  We discuss this later in the chapter in
            <xref linkend="svn.branchmerge.advanced.ancestry"/>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Applying reverse merges to a target's natural history</term>
          <listitem>
            <para>Earlier in this chapter 
                (<xref linkend="svn.branchmerge.basicmerging.undo"/>)
                we discussed how to use <command>svn merge</command>
                to apply a <quote>reverse patch</quote> as a way of
                rolling back changes.  If this technique is used to
                undo a change to an object's personal history (e.g.,
                commit r5 to the trunk, then immediately roll back r5
                using <userinput>svn merge . -c -5</userinput>), this
                sort of merge doesn't affect the recorded mergeinfo.
            <footnote>
              <para>Interestingly, after rolling back a
                revision like this, we wouldn't be able to reapply
                the revision using <userinput>svn merge . -c 5</userinput>,
                since the mergeinfo would already list r5 as being
                applied.  We would have to use
                the <option>--ignore-ancestry</option> option to make
                the merge command ignore the existing
                mergeinfo!</para>
            </footnote>
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.mergeconflicts">
      <title>More on Merge Conflicts</title>

      <para>Just like the <command>svn update</command> command,
        <command>svn merge</command> applies changes to your working
        copy.  And therefore it's also capable of creating
        conflicts.  The conflicts produced by <command>svn
          merge</command>, however, are sometimes different, and this
        section explains those differences.</para>

      <para>To begin with, assume that your working copy has no
        local edits.  When you <command>svn update</command> to a
        particular revision, the changes sent by the server will
        always apply <quote>cleanly</quote> to your working copy.
        The server produces the delta by comparing two trees: a
        virtual snapshot of your working copy, and the revision tree
        you're interested in.  Because the left hand side of the
        comparison is exactly equal to what you already have, the
        delta is guaranteed to correctly convert your working copy
        into the right hand tree.</para>

      <para>But <command>svn merge</command> has no such guarantees
        and can be much more chaotic: the advanced user can ask the
        server to compare <emphasis>any</emphasis> two trees at all,
        even ones that are unrelated to the working copy!  This means
        there's large potential for human error.  Users will sometimes
        compare the wrong two trees, creating a delta that doesn't
        apply cleanly.  <command>svn merge</command> will do its best
        to apply as much of the delta as possible, but some parts may
        be impossible.  Just as the Unix
        <command>patch</command> command sometimes complains about
        <quote>failed hunks,</quote> <command>svn merge</command> will
        similarly complain about <quote>skipped
        targets</quote>:</para>

      <screen>
$ svn merge -r 1288:1351 http://svn.example.com/repos/branch
U    foo.c
U    bar.c
Skipped missing target: 'baz.c'
U    glub.c
U    sputter.h

Conflict discovered in 'glorb.h'.
Select: (p) postpone, (df) diff-full, (e) edit,
        (h) help for more options:
</screen>

      <para>In the previous example, it might be the case that
        <filename>baz.c</filename> exists in both snapshots of the
        branch being compared, and the resultant delta wants to
        change the file's contents, but the file doesn't exist in
        the working copy.  Whatever the case, the
        <quote>skipped</quote> message means that the user is most
        likely comparing the wrong two trees; it's the classic
        sign of user error.  When this happens, it's easy to
        recursively revert all the changes created by the merge
        (<userinput>svn revert . --recursive</userinput>), delete any
        unversioned files or directories left behind after the
        revert, and rerun <command>svn merge</command> with
        different arguments.</para>

      <para>Also notice that the preceeding example shows a conflict
        happening on <filename>glorb.h</filename>.  We already
        stated that the working copy has no local edits: how can a
        conflict possibly happen?  Again, because the user can use
        <command>svn merge</command> to define and apply any old
        delta to the working copy, that delta may contain textual
        changes that don't cleanly apply to a working file, even if
        the file has no local modifications.</para>

      <para>Another small difference between <command>svn
          update</command> and <command>svn merge</command> is the
        names of the full-text files created when a conflict
        happens.  In <xref linkend="svn.tour.cycle.resolve"/>, we saw
        that an update produces files named
        <filename>filename.mine</filename>,
        <filename>filename.rOLDREV</filename>, and
        <filename>filename.rNEWREV</filename>.  When <command>svn
          merge</command> produces a conflict, though, it creates
        three files named <filename>filename.working</filename>,
        <filename>filename.left</filename>, and
        <filename>filename.right</filename>.  In this case, the
        terms <quote>left</quote> and <quote>right</quote> are
        describing which side of the double-tree comparison the file
        came from.  In any case, these differing names will help you
        distinguish between conflicts that happened as a result of an
        update and ones that happened as a result of a
        merge.</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.blockchanges">
      <title>Blocking Changes</title>

      <para>Sometimes there's a particular changeset that you don't
        want to be automatically merged.  For example, perhaps your
        team's policy is to do new development work on
        <filename>/trunk</filename>, but to be more conservative about
        backporting changes to a stable branch you use for releasing
        to the public.  On one extreme, you can manually cherrypick
        single changesets from the trunk to the branch&mdash;just the
        changes that are stable enough to pass muster.  Maybe things
        aren't quite that strict, though; perhaps most of the time
        you'd like to just let <command>svn merge</command>
        automatically merge most changes from trunk to branch.  In
        this case, you'd like a way to mask a few specific changes
        out, that is, prevent them from ever being automatically
        merged.</para>

      <para>In Subversion 1.5, the only way to block a changeset is to
        make the system believe that the change has
        <emphasis>already</emphasis> been merged.  To do this, one can
        invoke a merge command with the <option>--record-only</option>
        option:</para>

      <screen>
$ cd my-calc-branch

$ svn propget svn:mergeinfo .
/trunk:1680-3305

# Let's make the metadata list r3328 as already merged.
$ svn merge -c 3328 --record-only http://svn.example.com/repos/calc/trunk

$ svn status
M     .

$ svn propget svn:mergeinfo .
/trunk:1680-3305,3328

$ svn commit -m "Block r3328 from being merged to the branch."
&hellip;
</screen>

      <para>This technique works, but it's also a little bit
        dangerous.  The main problem is that we're not clearly
        differentiating between the ideas of <quote>I already have this
        change</quote> and <quote>I don't have this change.</quote>
        We're effectively lying to the system, making it think that
        the change was previously merged.  This puts the
        responsibility on you&mdash;the user&mdash;to remember that
        the change wasn't actually merged, it just wasn't wanted.
        There's no way to ask Subversion for a list of <quote>blocked
        changelists.</quote> If you want to track them (so that you
        can unblock them someday). you'll need to record them in a
        text file somewhere, or perhaps in an invented property.  In
        Subversion 1.5, unfortunately, this is the only way to manage
        blocked revisions; the plans are to make a better interface
        for this in future versions.</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.logblame">
      <title>Merge-Sensitive Logs and Annotations</title>

      <para>One of the main features of any version control system is
        to keep track of who changed what, and when they did it.
        The <command>svn log</command> and <command>svn
        blame</command> commands are just the tools for this: when
        invoked on individual files, they show not only the history of
        changesets that affected the file, but also exactly which user
        wrote which line of code, and when she did it.</para>

      <para>When changes start getting replicated between branches,
        however, things start to get complicated.  For example, if you
        were to ask <command>svn log</command> about the history of
        your feature branch, it would show exactly every revision that ever
        affected the branch:</para>

      <screen>
$ cd my-calc-branch
$ svn log -q
------------------------------------------------------------------------
r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line
------------------------------------------------------------------------
r388 | user | 2002-11-21 05:20:00 -0600 (Thu, 21 Nov 2002) | 2 lines
------------------------------------------------------------------------
r381 | user | 2002-11-20 15:07:06 -0600 (Wed, 20 Nov 2002) | 2 lines
------------------------------------------------------------------------
r359 | user | 2002-11-19 19:19:20 -0600 (Tue, 19 Nov 2002) | 2 lines
------------------------------------------------------------------------
r357 | user | 2002-11-15 14:29:52 -0600 (Fri, 15 Nov 2002) | 2 lines
------------------------------------------------------------------------
r343 | user | 2002-11-07 13:50:10 -0600 (Thu, 07 Nov 2002) | 2 lines
------------------------------------------------------------------------
r341 | user | 2002-11-03 07:17:16 -0600 (Sun, 03 Nov 2002) | 2 lines
------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
------------------------------------------------------------------------
</screen>

      <para>But is this really an accurate picture of all the changes
        that happened on the branch?  What's being left out here is
        the fact that revisions 390, 381, and 357 were actually the
        results of merging changes from the trunk.  If you look at one
        of these logs in detail, the multiple trunk changesets that
        comprised the branch change are nowhere to be seen:</para>

      <screen>
$ svn log -v -r 390
------------------------------------------------------------------------
r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line
Changed paths:
   M /branches/my-calc-branch/button.c
   M /branches/my-calc-branch/README

Final merge of trunk changes to my-calc-branch.
</screen>

      <para>We happen to know that this merge to the branch was
        nothing but a merge of trunk changes.  How can we see those
        trunk changes as well?  The answer is to use the
        <option>--use-merge-history</option> (<option>-g</option>)
        option.  This option expands those <quote>child</quote>
        changes that were part of the merge.</para>

      <screen>
$ svn log -v -r 390 -g
------------------------------------------------------------------------
r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line
Changed paths:
   M /branches/my-calc-branch/button.c
   M /branches/my-calc-branch/README

Final merge of trunk changes to my-calc-branch.
------------------------------------------------------------------------
r383 | sally | 2002-11-21 03:19:00 -0600 (Thu, 21 Nov 2002) | 2 lines
Changed paths:
   M /branches/my-calc-branch/button.c
Merged via: r390

Fix inverse graphic error on button.
------------------------------------------------------------------------
r382 | sally | 2002-11-20 16:57:06 -0600 (Wed, 20 Nov 2002) | 2 lines
Changed paths:
   M /branches/my-calc-branch/README
Merged via: r390

Document my last fix in README.
</screen>

      <para>By making the log operation use merge history, we see not
        just the revision we queried (r390), but also the two revisions
        that came along on the ride with it&mdash;a couple of changes
        made by Sally to the trunk.  This is a much more complete
        picture of history!</para>

      <para>The <command>svn blame</command> command also takes the
        <option>--use-merge-history</option> (<option>-g</option>)
        option.  If this option is neglected, somebody looking at
        a line-by-line annotation of <filename>button.c</filename> may
        get the mistaken impression that you were responsible for the
        lines that fixed a certain error:</para>

      <screen>
$ svn blame button.c
&hellip;
   390    user    retval = inverse_func(button, path);
   390    user    return retval;
   390    user    }
&hellip;
</screen>

      <para>And while it's true that you did actually commit those
        three lines in revision 390, two of them were actually written
        by Sally back in revision 383:</para>

      <screen>
$ svn blame button.c -g
&hellip;
G    383    sally   retval = inverse_func(button, path);
G    383    sally   return retval;
     390    user    }
&hellip;
</screen>

      <para>Now we know who to <emphasis>really</emphasis> blame for
        those two lines of code!</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.ancestry">
      <title>Noticing or Ignoring Ancestry</title>

      <para>When conversing with a Subversion developer, you might
        very likely hear reference to the term
        <firstterm>ancestry</firstterm>.  This word is used to
        describe the relationship between two objects in a
        repository: if they're related to each other, one
        object is said to be an ancestor of the other.</para>

      <para>For example, suppose you commit revision 100, which
        includes a change to a file <filename>foo.c</filename>.
        Then <filename>foo.c@99</filename> is an
        <quote>ancestor</quote> of <filename>foo.c@100</filename>.
        On the other hand, suppose you commit the deletion of
        <filename>foo.c</filename> in revision 101, and then add a
        new file by the same name in revision 102.  In this case,
        <filename>foo.c@99</filename> and
        <filename>foo.c@102</filename> may appear to be related
        (they have the same path), but in fact are completely
        different objects in the repository.  They share no history
        or <quote>ancestry.</quote></para>

      <para>The reason for bringing this up is to point out an
        important difference between <command>svn diff</command> and
        <command>svn merge</command>.  The former command ignores
        ancestry, while the latter command is quite sensitive to it.
        For example, if you asked <command>svn diff</command> to
        compare revisions 99 and 102 of <filename>foo.c</filename>,
        you would see line-based diffs; the <command>diff</command>
        command is blindly comparing two paths.  But if you asked
        <command>svn merge</command> to compare the same two objects,
        it would notice that they're unrelated and first attempt to
        delete the old file, then add the new file;  the output would
        indicate a deletion followed by an add:</para>

      <screen>
D    foo.c
A    foo.c
      </screen>

      <para>Most merges involve comparing trees that are ancestrally
        related to one another; therefore, <command>svn
        merge</command> defaults to this behavior.  Occasionally,
        however, you may want the <command>merge</command> command to
        compare two unrelated trees.  For example, you may have
        imported two source-code trees representing different vendor
        releases of a software project (see
        <xref linkend="svn.advanced.vendorbr"/>).  If you ask
        <command>svn merge</command> to compare the two trees, you'd
        see the entire first tree being deleted, followed by an add
        of the entire second tree!  In these situations, you'll want
        <command>svn merge</command> to do a path-based comparison
        only, ignoring any relations between files and directories.
        Add the <option>--ignore-ancestry</option> option to your
        <command>merge</command> command, and it will behave just
          like <command>svn diff</command>.  (And conversely, the
        <option>--notice-ancestry</option> option will cause
        <command>svn diff</command> to behave like the
        <command>svn merge</command> command.)</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.moves">
      <title>Merges and Moves</title>

      <para>A common desire is to refactor source code, especially
        in Java-based software projects.  Files and directories are
        shuffled around and renamed, often causing great disruption
        to everyone working on the project.  Sounds like a perfect
        case to use a branch, doesn't it?  Just create a branch,
        shuffle things around, and then merge the branch back to the
        trunk, right?</para>

      <para>Alas, this scenario doesn't work so well right now and
        is considered one of Subversion's current weak spots.  The
        problem is that Subversion's <command>svn update</command>
        command isn't as robust as it should be, particularly when
        dealing with copy and move operations.</para>

      <para>When you use <command>svn copy</command> to duplicate a
        file, the repository remembers where the new file came from,
        but it fails to transmit that information to the client which
        is running <command>svn update</command> or <command>svn
        merge</command>.  Instead of telling the client, <quote>Copy
        that file you already have to this new location,</quote> it
        sends down an entirely new file.  This can lead to
        problems, especially because the same thing happens with
        renamed files.  A lesser-known fact about Subversion is that
        it lacks <quote>true renames</quote>&mdash;the <command>svn
        move</command> command is nothing more than an aggregation
        of <command>svn copy</command> and <command>svn
        delete</command>.</para>

      <para>For example, suppose that while working on your private
        branch, you rename <filename>integer.c</filename>
        to <filename>whole.c</filename>.  Effectively you've created
        a new file in your branch that is a copy of the original
        file, and deleted the original file.  Meanwhile, back
        on <filename>trunk</filename>, Sally has committed some
        improvements to <filename>integer.c</filename>.  Now you
        decide to merge your branch to the trunk:</para>

      <screen>
$ cd calc/trunk

$ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch
--- Merging differences between repository URLs into '.':
D   integer.c
A   whole.c
U   .
      </screen>

      <para>This doesn't look so bad at first glance, but it's also
        probably not what you or Sally expected.  The merge operation
        has deleted the latest version of
        the <filename>integer.c</filename> file (the one containing
        Sally's latest changes), and blindly added your
        new <filename>whole.c</filename> file&mdash;which is a
        duplicate of the <emphasis>older</emphasis> version
        of <filename>integer.c</filename>.  The net effect is that
        merging your <quote>rename</quote> to the branch has removed
        Sally's recent changes from the latest revision!</para>

      <para>This isn't true data loss.  Sally's changes are still in
        the repository's history, but it may not be immediately
        obvious that this has happened.  The moral of this story is
        that until Subversion improves, be very careful about
        merging copies and renames from one branch to
        another.</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.pre1.5clients">
      <title>Blocking Merge-Unaware Clients</title>

      <para>If you've just upgraded your server to Subversion 1.5 or
        later, there's a significant risk that pre-1.5 Subversion
        clients can mess up your automated merge tracking.  Why is
        this?  When a pre-1.5 Subversion client performs <command>svn
        merge</command>, it doesn't modify the value of
        the <literal>svn:mergeinfo</literal> property at all.  So the
        subsequent commit, despite being the result of a merge,
        doesn't tell the repository about the duplicated
        changes&mdash;that information is lost.  Later on,
        when <quote>merge-aware</quote> clients attempt automatic
        merging, they're likely to run into all sorts of conflicts
        resulting from repeated merges.</para>

      <para>If you and your team are relying on the merge-tracking
        features of Subversion, you may want to configure your
        repository to prevent older clients from committing changes.
        The easy way to do this is by inspecting
        the <quote>capabilities</quote> parameter in
        the <literal>start-commit</literal> hook script.  If the
        client reports itself as having <literal>mergeinfo</literal>
        capabilities, the hook script can allow the commit to start.
        If the client doesn't report that capability, have the hook
        deny the commit.  We'll learn more about hook scripts in the
        next chapter; see
        <xref linkend="svn.reposadmin.create.hooks"/> and
        <xref linkend="svn.ref.reposhooks.start-commit"/> for
        details.</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.advanced.finalword">
      <title>The Final Word on Merge Tracking</title>

      <para>The bottom line is that Subversion's merge-tracking
        feature has an extremely complex internal implementation, and
        the <literal>svn:mergeinfo</literal> property is the only
        window the user has into the machinery.  Because the feature
        is relatively new, a numbers of edge cases and
        possible unexpected behaviors may pop up.</para>

      <para>For example, sometimes mergeinfo will be generated when
        running a simple <command>svn copy</command> or <command>svn
        move</command> command.  Sometimes mergeinfo will appear on
        files that you didn't expect to be touched by an operation.
        Sometimes mergeinfo won't be generated at all, when you expect
        it to.  Furthermore, the management of mergeinfo metadata has
        a whole set of taxonomies and behaviors around it, such
        as <quote>explicit</quote> versus <quote>implicit</quote>
        mergeinfo, <quote>operative</quote>
        versus <quote>inoperative</quote> revisions, specific
        mechanisms of mergeinfo <quote>elision,</quote> and
        even <quote>inheritance</quote> from parent to child
        directories.</para>

      <para>We've chosen not to cover these detailed topics in this
        book for a couple of reasons.  First, the level of detail is
        absolutely overwhelming for a typical user.  Second, as
        Subversion continues to improve, we feel that a typical user
        <emphasis>shouldn't</emphasis> have to understand these
        concepts; they'll eventually fade into the background as pesky
        implementation details.  All that said, if you enjoy this sort
        of thing, you can get a fantastic overview in a paper posted
        at CollabNet's website: <ulink
        url="http://www.collab.net/community/subversion/articles/merge-info.html"
        />.</para>

      <para>For now, if you want to steer clear of bugs and odd
        behaviors in automatic merging, the CollabNet article
        recommends that you stick to these simple best practices:</para>

      <itemizedlist>
        <listitem>
          <para>For short-term feature branches, follow the simple
            procedure described throughout
            <xref linkend="svn.branchmerge.basicmerging"/>.</para>
        </listitem>
        <listitem>
          <para>For long-lived release branches (as described in
            <xref linkend="svn.branchmerge.commonpatterns"/>),
            perform merges only on the root of the branch, not on
            subdirectories.</para>
        </listitem>
        <listitem>
          <para>Never merge into working copies with a mixture of
            working revision numbers, or with
            <quote>switched</quote> subdirectories (as described next
            in <xref linkend="svn.branchmerge.switchwc"/>).  A merge
            target should be a working copy which represents
            a <emphasis>single</emphasis> location in the repository
            at a single point in time.</para>
        </listitem>
        <listitem>
          <para>Don't ever edit the <literal>svn:mergeinfo</literal>
            property directly; use <command>svn
            merge</command> with the <option>--record-only</option> option to effect a desired change
            to the metadata (as demonstrated in
            <xref linkend="svn.branchmerge.advanced.blockchanges"/>).</para>
        </listitem>
        <listitem>
          <para>Always make sure you have complete read access to
            all of your merge sources, and that your target working
            copy has no sparse directories.</para>
        </listitem>
      </itemizedlist>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.switchwc">
    <title>Traversing Branches</title>

    <para>The <command>svn switch</command> command transforms an
      existing working copy to reflect a different branch.  While this
      command isn't strictly necessary for working with branches, it
      provides a nice shortcut.  In our earlier example,
      after creating your private branch, you checked out a fresh
      working copy of the new repository directory.  Instead, you can
      simply ask Subversion to change your working copy of
      <filename>/calc/trunk</filename> to mirror the new branch
      location:</para>

    <screen>
$ cd calc

$ svn info | grep URL
URL: http://svn.example.com/repos/calc/trunk

$ svn switch http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile
Updated to revision 341.

$ svn info | grep URL
URL: http://svn.example.com/repos/calc/branches/my-calc-branch
</screen>

    <para><quote>Switching</quote> a working copy that has no local
      modifications to a different branch results in the working copy
      looking just as it would if you'd done a fresh checkout of the
      directory.  It's usually more efficient to
      use this command, because often branches differ by only a small
      degree.  The server sends only the minimal set of changes
      necessary to make your working copy reflect the branch
      directory.</para>

    <para>The <command>svn switch</command> command also takes a
      <option>--revision</option> (<option>-r</option>) option, so you
      need not always move your working copy to the
      <literal>HEAD</literal> of the branch.</para>

    <para>Of course, most projects are more complicated than our
      <filename>calc</filename> example, and contain multiple
      subdirectories.  Subversion users often follow a specific
      algorithm when using branches:</para>

      <orderedlist>
        <listitem>
          <para>Copy the project's entire <quote>trunk</quote> to a
            new branch directory.</para>
        </listitem>
        <listitem>
          <para>Switch only <emphasis>part</emphasis> of the trunk
            working copy to mirror the branch.</para>
        </listitem>
      </orderedlist>

    <para>In other words, if a user knows that the branch work needs
      to happen on only a specific subdirectory, she uses
      <command>svn switch</command> to move only that subdirectory to
      the branch.  (Or sometimes users will switch just a single
      working file to the branch!)  That way, the user can continue to
      receive normal <quote>trunk</quote> updates to most of her
      working copy, but the switched portions will remain immune
      (unless someone commits a change to her branch).  This feature
      adds a whole new dimension to the concept of a <quote>mixed
      working copy</quote>&mdash;not only can working copies contain a
      mixture of working revisions, but they can also contain a
      mixture of repository locations as well.</para>

    <para>If your working copy contains a number of switched subtrees
      from different repository locations, it continues to function as
      normal.  When you update, you'll receive patches to each subtree
      as appropriate.  When you commit, your local changes will still
      be applied as a single, atomic change to the repository.</para>

    <para>Note that while it's okay for your working copy to reflect a
      mixture of repository locations, these locations must all be
      within the <emphasis>same</emphasis> repository.  Subversion
      repositories aren't yet able to communicate with one another;
      that feature is planned for the future.
      <footnote>
        <para>You <emphasis>can</emphasis>, however, use <command>svn
          switch</command> with the <option>--relocate</option> option
          if the URL of your server changes and you don't want to
          abandon an existing working copy.  See <xref
          linkend="svn.ref.svn.c.switch"/> for more information and an
          example.</para>
      </footnote>
    </para>

    <sidebar>
      <title>Switches and Updates</title>

      <para>Have you noticed that the output of <command>svn
        switch</command> and <command>svn update</command> looks the
        same?  The switch command is actually a superset of the update
        command.</para>

      <para>When you run <command>svn update</command>, you're asking
        the repository to compare two trees.  The repository does so,
        and then sends a description of the differences back to the
        client.  The only difference between <command>svn
        switch</command> and <command>svn update</command> is that the
        latter command always compares two identical repository
        paths.</para>

      <para>That is, if your working copy is a mirror of
        <filename>/calc/trunk</filename>, <command>svn
        update</command> will automatically compare your working copy
        of <filename>/calc/trunk</filename> to
        <filename>/calc/trunk</filename> in the
        <literal>HEAD</literal> revision.  If you're switching your
        working copy to a branch, <command>svn switch</command>
        will compare your working copy of
        <filename>/calc/trunk</filename> to some
        <emphasis>other</emphasis> branch directory in the
        <literal>HEAD</literal> revision.</para>

      <para>In other words, an update moves your working copy through
        time.  A switch moves your working copy through time
        <emphasis>and</emphasis> space.</para>
    </sidebar>

    <para>Because <command>svn switch</command> is essentially a
      variant of <command>svn update</command>, it shares the same
      behaviors; any local modifications in your working copy are
      preserved when new data arrives from the repository.</para>


      <tip>
        <para>Have you ever found yourself making some complex edits
          (in your <filename>/trunk</filename> working copy) and
          suddenly realized, <quote>Hey, these changes ought to be in
          their own branch?</quote>  A great technique to do this can
          be summarized in two steps:</para>

          <screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/newbranch \
      -m "Create branch 'newbranch'."
Committed revision 353.
$ svn switch http://svn.example.com/repos/calc/branches/newbranch
At revision 353.
</screen>

        <para>The <command>svn switch</command> command, like
          <command>svn update</command>, preserves your local edits.
          At this point, your working copy is now a reflection of the
          newly created branch, and your next <command>svn
          commit</command> invocation will send your changes
          there.</para> </tip>

  </sect1>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.tags">
    <title>Tags</title>

    <para>Another common version control concept is a
      <firstterm>tag</firstterm>.  A tag is just a
      <quote>snapshot</quote> of a project in time.  In Subversion,
      this idea already seems to be everywhere.  Each repository
      revision is exactly that&mdash;a snapshot of the filesystem
      after each commit.</para>

    <para>However, people often want to give more human-friendly names
      to tags, such as <literal>release-1.0</literal>.  And they want
      to make snapshots of smaller subdirectories of the filesystem.
      After all, it's not so easy to remember that release 1.0 of a
      piece of software is a particular subdirectory of revision
      4822.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.tags.mksimple">
      <title>Creating a Simple Tag</title>

      <para>Once again, <command>svn copy</command> comes to the
        rescue.  If you want to create a snapshot of
        <filename>/calc/trunk</filename> exactly as it looks in the
        <literal>HEAD</literal> revision, make a copy of it:</para>

      <screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/tags/release-1.0 \
      -m "Tagging the 1.0 release of the 'calc' project."

Committed revision 902.
</screen>

      <para>This example assumes that a
        <filename>/calc/tags</filename> directory already exists.  (If
        it doesn't, you can create it using <command>svn
        mkdir</command>.)  After the copy completes, the new
        <filename>release-1.0</filename> directory is forever a
        snapshot of how the <filename>/trunk</filename> directory
        looked in the <literal>HEAD</literal> revision at the time you
        made the copy.  Of course, you might want to be more precise
        about exactly which revision you copy, in case somebody else
        may have committed changes to the project when you weren't
        looking.  So if you know that revision 901 of
        <filename>/calc/trunk</filename> is exactly the snapshot you
        want, you can specify it by passing <option>-r 901</option> to
        the <command>svn copy</command> command.</para>

      <para>But wait a moment: isn't this tag creation procedure the
        same procedure we used to create a branch?  Yes, in fact, it
        is.  In Subversion, there's no difference between a tag and a
        branch.  Both are just ordinary directories that are created
        by copying.  Just as with branches, the only reason a copied
        directory is a <quote>tag</quote> is because
        <emphasis>humans</emphasis> have decided to treat it that way:
        as long as nobody ever commits to the directory, it forever
        remains a snapshot.  If people start committing to it, it
        becomes a branch.</para>

      <para>If you are administering a repository, there are two
        approaches you can take to managing tags.  The first approach
        is <quote>hands off</quote>: as a matter of project policy,
        decide where your tags will live, and make sure all users know
        how to treat the directories they copy.  (That is, make sure
        they know not to commit to them.)  The second approach is more
        paranoid: you can use one of the access control scripts
        provided with Subversion to prevent anyone from doing anything
        but creating new copies in the tags area (see
        <xref linkend="svn.serverconfig"/>).  The paranoid approach,
        however, isn't usually necessary.  If a user accidentally
        commits a change to a tag directory, you can simply undo the
        change as discussed in the previous section.  This is version
        control, after all!</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.tags.mkcomplex">
      <title>Creating a Complex Tag</title>

      <para>Sometimes you may want your <quote>snapshot</quote> to be
        more complicated than a single directory at a single
        revision.</para>

      <para>For example, pretend your project is much larger than our
        <filename>calc</filename> example: suppose it contains a
        number of subdirectories and many more files.  In the course
        of your work, you may decide that you need to create a working
        copy that is designed to have specific features and bug fixes.
        You can accomplish this by selectively backdating files or
        directories to particular revisions (using <command>svn update</command>
        with the <option>-r</option> option liberally), by switching files and directories to
        particular branches (making use of <command>svn
        switch</command>), or even just by making a bunch of local
        changes.  When you're done, your working copy is a hodgepodge
        of repository locations from different revisions.  But after
        testing, you know it's the precise combination of data you
        need to tag.</para>

      <para>Time to make a snapshot.  Copying one URL to another won't
        work here.  In this case, you want to make a snapshot of your
        exact working copy arrangement and store it in the repository.
        Luckily, <command>svn copy</command> actually has four
        different uses (which you can read about in <xref
        linkend="svn.ref"/>), including the ability to copy a
        working copy tree to the repository:</para>

      <screen>
$ ls
my-working-copy/

$ svn copy my-working-copy \
           http://svn.example.com/repos/calc/tags/mytag \
           -m "Tag my existing working copy state."

Committed revision 940.
</screen>

      <para>Now there is a new directory in the repository,
        <filename>/calc/tags/mytag</filename>, which is an exact
        snapshot of your working copy&mdash;mixed revisions, URLs,
        local changes, and all.</para>

      <para>Other users have found interesting uses for this feature.
        Sometimes there are situations where you have a bunch of local
        changes made to your working copy, and you'd like a
        collaborator to see them.  Instead of running <command>svn
        diff</command> and sending a patch file (which won't capture
        directory, symlink, or property changes), you can
        use <command>svn copy</command> to <quote>upload</quote> your
        working copy to a private area of the repository.  Your
        collaborator can then either check out a verbatim copy of your
        working copy or use <command>svn merge</command> to receive
        your exact changes.</para>

      <para>While this is a nice method for uploading a quick snapshot
        of your working copy, note that this is <emphasis>not</emphasis>
        a good way to initially create a branch.  Branch creation should
        be an event unto itself, and this method conflates the creation
        of a branch with extra changes to files, all within a single revision.
        This makes it very difficult (later on) to identify a single
        revision number as a branch point.</para>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.maint">
    <title>Branch Maintenance</title>

    <para>You may have noticed by now that Subversion is extremely
      flexible.  Because it implements branches and tags with the same
      underlying mechanism (directory copies), and because branches
      and tags appear in normal filesystem space, many people find
      Subversion intimidating.  It's almost <emphasis>too</emphasis>
      flexible.  In this section, we'll offer some suggestions for
      arranging and managing your data over time.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.maint.layout">
      <title>Repository Layout</title>

      <para>There are some standard, recommended ways to organize a
        repository.  Most people create a <filename>trunk</filename>
        directory to hold the <quote>main line</quote> of development,
        a <filename>branches</filename> directory to contain branch
        copies, and a <filename>tags</filename> directory to contain
        tag copies.  If a repository holds only one project,
        often people create these top-level directories:</para>

      <screen>
/trunk
/branches
/tags
</screen>

      <para>If a repository contains multiple projects, admins
        typically index their layout by project (see <xref
        linkend="svn.reposadmin.projects.chooselayout"/> to read more about
        <quote>project roots</quote>):</para>

      <screen>
/paint/trunk
/paint/branches
/paint/tags
/calc/trunk
/calc/branches
/calc/tags
</screen>

      <para>Of course, you're free to ignore these common layouts.
        You can create any sort of variation, whatever works best for
        you or your team.  Remember that whatever you choose, it's not
        a permanent commitment.  You can reorganize your repository at
        any time.  Because branches and tags are ordinary directories,
        the <command>svn move</command> command can move or rename
        them however you wish.  Switching from one layout to another
        is just a matter of issuing a series of server-side moves; if
        you don't like the way things are organized in the repository,
        just juggle the directories around.</para>

      <para>Remember, though, that while moving directories may be
        easy to do, you need to be considerate of your users as well.
        Your juggling can be disorienting to users with existing
        working copies.  If a user has a working copy of a particular
        repository directory, your <command>svn move</command>
        operation might remove the path from the latest revision.
        When the user next runs <command>svn update</command>, she will
        be told that her working copy represents a path that no
        longer exists, and the user will be forced to <command>svn
        switch</command> to the new location.
        </para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.branchmerge.maint.lifetime">
      <title>Data Lifetimes</title>

      <para>Another nice feature of Subversion's model is that
        branches and tags can have finite lifetimes, just like any
        other versioned item.  For example, suppose you eventually
        finish all your work on your personal branch of the
        <filename>calc</filename> project.  After merging all of your
        changes back into <filename>/calc/trunk</filename>, there's
        no need for your private branch directory to stick around
        anymore:</para>

      <screen>
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
             -m "Removing obsolete branch of calc project."

Committed revision 375.
</screen>

      <para>And now your branch is gone.  Of course, it's not really
        gone: the directory is simply missing from the
        <literal>HEAD</literal> revision, no longer distracting
        anyone.  If you use <command>svn checkout</command>,
        <command>svn switch</command>, or <command>svn list</command>
        to examine an earlier revision, you'll still be able to see
        your old branch.</para>

      <para>If browsing your deleted directory isn't enough, you can
        always bring it back.  Resurrecting data is very easy in
        Subversion.  If there's a deleted directory (or file) that
        you'd like to bring back into <literal>HEAD</literal>, simply
        use <command>svn copy</command> to copy it from the old
        revision:</para>

      <screen>
$ svn copy http://svn.example.com/repos/calc/branches/my-calc-branch@374 \
           http://svn.example.com/repos/calc/branches/my-calc-branch \
           -m "Restore my-calc-branch."

Committed revision 376.
</screen>

      <para>In our example, your personal branch had a relatively
        short lifetime: you may have created it to fix a bug or
        implement a new feature.  When your task is done, so is the
        branch.  In software development, though, it's also common to
        have two <quote>main</quote> branches running side by side for
        very long periods.  For example, suppose it's time to release
        a stable version of the <filename>calc</filename> project to the
        public, and you know it's going to take a couple of months to
        shake bugs out of the software.  You don't want people to add
        new features to the project, but you don't want to tell all
        developers to stop programming either.  So instead, you create
        a <quote>stable</quote> branch of the software that won't
        change much:</para>

      <screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/stable-1.0 \
           -m "Creating stable branch of calc project."

Committed revision 377.
</screen>

      <para>And now developers are free to continue adding
        cutting-edge (or experimental) features to
        <filename>/calc/trunk</filename>, and you can declare a
        project policy that only bug fixes are to be committed to
        <filename>/calc/branches/stable-1.0</filename>.  That is, as
        people continue to work on the trunk, a human selectively
        ports bug fixes over to the stable branch.  Even after the
        stable branch has shipped, you'll probably continue to
        maintain the branch for a long time&mdash;that is, as long
        as you continue to support that release for customers.  We'll
        discuss this more in the next section.</para>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.commonpatterns">
    <title>Common Branching Patterns</title>

    <para>There are many different uses for branching and <command>svn
        merge</command>, and this section describes the most
        common.</para>

    <para>Version control is most often used for software
      development, so here's a quick peek at two of the most common
      branching/merging patterns used by teams of programmers.  If
      you're not using Subversion for software development, feel
      free to skip this section.  If you're a software developer
      using version control for the first time, pay close attention,
      as these patterns are often considered best practices by
      experienced folk.  These processes aren't specific to
      Subversion; they're applicable to any version control system.
      Still, it may help to see them described in Subversion
      terms.</para>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.commonpatterns.release">
      <title>Release Branches</title>

      <para>Most software has a typical life cycle: code, test,
        release, repeat.  There are two problems with this process.
        First, developers need to keep writing new features while
        quality assurance teams take time to test supposedly stable
        versions of the software.  New work cannot halt while the
        software is tested.  Second, the team almost always needs to
        support older, released versions of software; if a bug is
        discovered in the latest code, it most likely exists in
        released versions as well, and customers will want to get
        that bug fix without having to wait for a major new
        release.</para>

      <para>Here's where version control can help.  The typical
        procedure looks like this:</para>

      <orderedlist>

        <listitem>
          <para><emphasis>Developers commit all new work to the
              trunk.</emphasis>

            Day-to-day changes are committed to
            <filename>/trunk</filename>: new features, bug fixes, and
            so on.</para>
        </listitem>

        <listitem>
          <para><emphasis>The trunk is copied to a
              <quote>release</quote> branch.</emphasis>

            When the team thinks the software is ready for release
            (say, a 1.0 release), <filename>/trunk</filename>
            might be copied to
            <filename>/branches/1.0</filename>.</para>
        </listitem>

        <listitem>
          <para><emphasis>Teams continue to work in parallel.</emphasis>

            One team begins rigorous testing of the release branch,
            while another team continues new work (say, for version
            2.0) on <filename>/trunk</filename>.  If bugs are
            discovered in either location, fixes are ported back and
            forth as necessary.  At some point, however, even that
            process stops.  The branch is <quote>frozen</quote> for
            final testing right before a release.</para>
        </listitem>

        <listitem>
          <para><emphasis>The branch is tagged and released.</emphasis>

            When testing is complete,
            <filename>/branches/1.0</filename> is copied to
            <filename>/tags/1.0.0</filename> as a reference
            snapshot.  The tag is packaged and released to
            customers.</para>
        </listitem>

        <listitem>
          <para><emphasis>The branch is maintained over time.</emphasis>

            While work continues on <filename>/trunk</filename> for
            version 2.0, bug fixes continue to be ported from
            <filename>/trunk</filename> to
            <filename>/branches/1.0</filename>.  When enough
            bug fixes have accumulated, management may decide to do a
            1.0.1 release: <filename>/branches/1.0</filename> is
            copied to <filename>/tags/1.0.1</filename>, and the tag
            is packaged and released.</para>
        </listitem>

      </orderedlist>

      <para>This entire process repeats as the software matures:
        when the 2.0 work is complete, a new 2.0 release branch is
        created, tested, tagged, and eventually released.  After
        some years, the repository ends up with a number of release
        branches in <quote>maintenance</quote> mode, and a number
        of tags representing final shipped versions.</para>

    </sect2>

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <sect2 id="svn.branchmerge.commonpatterns.feature">
      <title>Feature Branches</title>

      <para>A <firstterm>feature branch</firstterm> is the sort of
        branch that's been the dominant example in this chapter (the
        one you've been working on while Sally continues to work on
        <filename>/trunk</filename>).  It's a temporary branch created
        to work on a complex change without interfering with the
        stability of <filename>/trunk</filename>.  Unlike release
        branches (which may need to be supported forever), feature
        branches are born, used for a while, merged back to the trunk,
        and then ultimately deleted.  They have a finite span of
        usefulness.</para>

      <para>Again, project policies vary widely concerning exactly
        when it's appropriate to create a feature branch.  Some
        projects never use feature branches at all: commits to
        <filename>/trunk</filename> are a free-for-all.  The
        advantage to this system is that it's simple&mdash;nobody
        needs to learn about branching or merging.  The disadvantage
        is that the trunk code is often unstable or unusable.  Other
        projects use branches to an extreme: no change is
        <emphasis>ever</emphasis> committed to the trunk directly.
        Even the most trivial changes are created on a short-lived
        branch, carefully reviewed, and merged to the trunk.  Then
        the branch is deleted.  This system guarantees an
        exceptionally stable and usable trunk at all times, but at
        the cost of tremendous process overhead.</para>

      <para>Most projects take a middle-of-the-road approach.  They
        commonly insist that <filename>/trunk</filename> compile and
        pass regression tests at all times.  A feature branch is
        required only when a change requires a large number of
        destabilizing commits.  A good rule of thumb is to ask this
        question: if the developer worked for days in isolation and
        then committed the large change all at once (so that
        <filename>/trunk</filename> were never destabilized), would it
        be too large a change to review?  If the answer to that
        question is <quote>yes,</quote> the change should be
        developed on a feature branch.  As the developer commits
        incremental changes to the branch, they can be easily reviewed
        by peers.</para>

      <para>Finally, there's the issue of how to best keep a feature
        branch in <quote>sync</quote> with the trunk as work
        progresses.  As we mentioned earlier, there's a great risk to
        working on a branch for weeks or months; trunk changes may
        continue to pour in, to the point where the two lines of
        development differ so greatly that it may become a nightmare
        trying to merge the branch back to the trunk.</para>

      <para>This situation is best avoided by regularly merging trunk
        changes to the branch.  Make up a policy: once a week, merge
        the last week's worth of trunk changes to the branch.</para>

      <para>At some point, you'll be ready to merge the
        <quote>synchronized</quote> feature branch back to the trunk.
        To do this, begin by doing a final merge of the latest trunk
        changes to the branch.  When that's done, the latest versions
        of branch and trunk will be absolutely identical except for
        your branch changes.  You would then merge back with
        the <option>--reintegrate</option> option:</para>

      <screen>
$ cd trunk-working-copy

$ svn update
At revision 1910.

$ svn merge --reintegrate http://svn.example.com/repos/calc/branches/mybranch
--- Merging differences between repository URLs into '.':
U    real.c
U    integer.c
A    newdirectory
A    newdirectory/newfile
 U   .
&hellip;
</screen>

      <para>Another way of thinking about this pattern is that your
        weekly sync of trunk to branch is analogous to running
        <command>svn update</command> in a working copy, while the
        final merge step is analogous to running <command>svn
          commit</command> from a working copy.  After all, what else
        <emphasis>is</emphasis> a working copy but a very shallow
        private branch?  It's a branch that's capable of
        storing only one change at a time.</para>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.vendorbr">
    <title>Vendor Branches</title>

    <para>As is especially the case when developing software, the data
      that you maintain under version control is often closely related
      to, or perhaps dependent upon, someone else's data.  Generally,
      the needs of your project will dictate that you stay as
      up to date as possible with the data provided by that external
      entity without sacrificing the stability of your own project.
      This scenario plays itself out all the time&mdash;anywhere that
      the information generated by one group of people has a direct
      effect on that which is generated by another group.</para>

    <para>For example, software developers might be working on an
      application that makes use of a third-party library.  Subversion
      has just such a relationship with the Apache Portable Runtime (APR)
      library (see <xref linkend="svn.developer.usingapi.apr" />).
      The Subversion source code depends on the APR library for all
      its portability needs.  In earlier stages of Subversion's
      development, the project closely tracked APR's changing API,
      always sticking to the <quote>bleeding edge</quote> of the
      library's code churn.  Now that both APR and Subversion have
      matured, Subversion attempts to synchronize with APR's library
      API only at well-tested, stable release points.</para>

    <para>Now, if your project depends on someone else's information,
      you could attempt to synchronize that information with your own
      in several ways.  Most painfully, you could issue oral or
      written instructions to all the contributors of your project,
      telling them to make sure they have the specific versions
      of that third-party information that your project needs.  If the
      third-party information is maintained in a Subversion
      repository, you could also use Subversion's externals
      definitions to effectively <quote>pin down</quote> specific
      versions of that information to some location in your own
      working copy directory (see
      <xref linkend="svn.advanced.externals" />).</para>

    <para>But sometimes you want to maintain custom modifications to
      third-party code in your own version control system.  Returning
      to the software development example, programmers might need to
      make modifications to that third-party library for their own
      purposes.  These modifications might include new functionality
      or bug fixes, maintained internally only until they become part
      of an official release of the third-party library.  Or the
      changes might never be relayed back to the library maintainers,
      existing solely as custom tweaks to make the library further
      suit the needs of the software developers.</para>

    <para>Now you face an interesting situation.  Your project could
      house its custom modifications to the third-party data in some
      disjointed fashion, such as using patch files or full-fledged
      alternative versions of files and directories.  But these quickly
      become maintenance headaches, requiring some mechanism by which
      to apply your custom changes to the third-party code and
      necessitating regeneration of those changes with each successive
      version of the third-party code that you track.</para>

    <para>The solution to this problem is to use <firstterm>vendor
      branches</firstterm>.  A vendor branch is a directory tree in
      your own version control system that contains information
      provided by a third-party entity, or vendor.  Each version of
      the vendor's data that you decide to absorb into your project is
      called a <firstterm>vendor drop</firstterm>.</para> 

    <para>Vendor branches provide two benefits.  First, by storing
      the currently supported vendor drop in your own version control
      system, you ensure that the members of your project never need to question
      whether they have the right version of the vendor's data.  They
      simply receive that correct version as part of their regular
      working copy updates.  Second, because the data lives in your
      own Subversion repository, you can store your custom changes to
      it in-place&mdash;you have no more need of an automated (or
      worse, manual) method for swapping in your customizations.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.vendorbr.general">
      <title>General Vendor Branch Management Procedure</title>

      <para>Managing vendor branches generally works like this: first,
        you create a top-level directory (such as
        <filename>/vendor</filename>) to hold the vendor branches.
        Then you import the third-party code into a subdirectory of
        that top-level directory.  You then copy that subdirectory
        into your main development branch (e.g.,
        <filename>/trunk</filename>) at the appropriate location.  You
        always make your local changes in the main development branch.
        With each new release of the code you are tracking, you bring
        it into the vendor branch and merge the changes into
        <filename>/trunk</filename>, resolving whatever conflicts
        occur between your local changes and the upstream
        changes.</para>

      <para>An example will help to clarify this algorithm.  We'll use
        a scenario where your development team is creating a
        calculator program that links against a third-party complex
        number arithmetic library, libcomplex.  We'll begin with the
        initial creation of the vendor branch and the import of the
        first vendor drop.  We'll call our vendor branch directory
        <filename>libcomplex</filename>, and our code drops will go
        into a subdirectory of our vendor branch called
        <filename>current</filename>.  And since <command>svn
        import</command> creates all the intermediate parent
        directories it needs, we can actually accomplish both of these
        steps with a single command:</para>

      <screen>
$ svn import /path/to/libcomplex-1.0 \
             http://svn.example.com/repos/vendor/libcomplex/current \
             -m 'importing initial 1.0 vendor drop'
&hellip;
</screen>

      <para>We now have the current version of the libcomplex source
        code in <filename>/vendor/libcomplex/current</filename>.  Now,
        we tag that version (see <xref linkend="svn.branchmerge.tags" />)
        and then copy it into the main development branch.  Our copy
        will create a new directory called
        <filename>libcomplex</filename> in our existing
        <filename>calc</filename> project directory.  It is in this
        copied version of the vendor data that we will make our
        customizations:</para>

      <screen>
$ svn copy http://svn.example.com/repos/vendor/libcomplex/current  \
           http://svn.example.com/repos/vendor/libcomplex/1.0      \
           -m 'tagging libcomplex-1.0'
&hellip;
$ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0  \
           http://svn.example.com/repos/calc/libcomplex        \
           -m 'bringing libcomplex-1.0 into the main branch'
&hellip;
</screen>

      <para>We check out our project's main branch&mdash;which now
        includes a copy of the first vendor drop&mdash;and we get to
        work customizing the libcomplex code.  Before we know it, our
        modified version of libcomplex is now completely integrated
        into our calculator program.
        <footnote>
          <para>And is entirely bug-free, of course!</para>
        </footnote>
      </para>

      <para>A few weeks later, the developers of libcomplex release a
        new version of their library&mdash;version 1.1&mdash;which
        contains some features and functionality that we really want.
        We'd like to upgrade to this new version, but without losing
        the customizations we made to the existing version.  What we
        essentially would like to do is to replace our current
        baseline version of libcomplex 1.0 with a copy of libcomplex
        1.1, and then re-apply the custom modifications we previously
        made to that library to the new version.  But we actually
        approach the problem from the other direction, applying the
        changes made to libcomplex between versions 1.0 and 1.1 to our
        modified copy of it.</para>

      <para>To perform this upgrade, we check out a copy of our vendor
        branch and replace the code in the
        <filename>current</filename> directory with the new libcomplex
        1.1 source code.  We quite literally copy new files on top of
        existing files, perhaps exploding the libcomplex 1.1 release
        tarball atop our existing files and directories.  The goal
        here is to make our <filename>current</filename> directory
        contain only the libcomplex 1.1 code and to ensure that all
        that code is under version control.  Oh, and we want to do
        this with as little version control history disturbance as
        possible.</para>

      <para>After replacing the 1.0 code with 1.1 code, <command>svn
        status</command> will show files with local modifications as
        well as, perhaps, some unversioned files.  If we did what we
        were supposed to do, the unversioned files are only those new
        files introduced in the 1.1 release of libcomplex&mdash;we
        run <command>svn add</command> on those to get them under
        version control.  If the 1.1 code no longer has certain files
        that were in the 1.0 tree, it may be hard to notice them;
        you'd have to compare the two trees with some external tool
        and then <command>svn delete</command> any files present in
        1.0 but not in 1.1.  (Although it might also be just fine to
        let these same files live on in unused obscurity!)  Finally,
        once our <filename>current</filename> working copy contains
        only the libcomplex 1.1 code, we commit the changes we made to
        get it looking that way.</para>

      <para>Our <filename>current</filename> branch now contains the
        new vendor drop.  We tag the new version as 1.1 (in the same
        way we previously tagged the version 1.0 vendor drop), and
        then merge the differences between the tag of the previous
        version and the new current version into our main development
        branch:</para>

      <screen>
$ cd working-copies/calc
$ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0      \
            http://svn.example.com/repos/vendor/libcomplex/current  \
            libcomplex
&hellip; # resolve all the conflicts between their changes and our changes
$ svn commit -m 'merging libcomplex-1.1 into the main branch'
&hellip;
</screen>

      <para>In the trivial use case, the new version of our
        third-party tool would look, from a files-and-directories
        point of view, just like the previous version.  None of the
        libcomplex source files would have been deleted, renamed, or
        moved to different locations&mdash;the new version would
        contain only textual modifications against the previous one.
        In a perfect world, our modifications would apply cleanly to
        the new version of the library, with absolutely no
        complications or conflicts.</para>

      <para>But things aren't always that simple, and in fact it is
        quite common for source files to get moved around between
        releases of software.  This complicates the process of
        ensuring that our modifications are still valid for the new
        version of code, and things can quickly degrade into a
        situation where we have to manually re-create our
        customizations in the new version.  Once Subversion knows
        about the history of a given source file&mdash;including all
        its previous locations&mdash;the process of merging in the new
        version of the library is pretty simple.  But we are
        responsible for telling Subversion how the source file layout
        changed from vendor drop to vendor drop.</para>

    </sect2>

    <!-- TODO: Try to clarify some of the steps for svn_load_dirs.pl
         (Garrett sez they've been "glossed over".  Also, consider
         another section on bypassing svn_load_dirs.pl altogether and
         running with just svn merge, now that it ignores ancestry. -->

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.vendorbr.svn_load_dirs">
      <title>svn_load_dirs.pl</title>

      <para>Vendor drops that contain more than a few deletes,
        additions, and moves complicate the process of upgrading to
        each successive version of the third-party data.  So
        Subversion supplies the <command>svn_load_dirs.pl</command>
        script to assist with this process.  This script automates the
        importing steps we mentioned in the general vendor branch
        management procedure to make sure mistakes are minimized.
        You will still be responsible for using the merge commands to
        merge the new versions of the third-party data into your main
        development branch, but <command>svn_load_dirs.pl</command>
        can help you more quickly and easily arrive at that
        stage.</para>

      <para>In short, <command>svn_load_dirs.pl</command> is an
        enhancement to <command>svn import</command> that has several
        important characteristics:</para>

      <itemizedlist>
        <listitem>
          <para>It can be run at any point in time to bring an existing
            directory in the repository to exactly match an external
            directory, performing all the necessary adds and deletes,
            and optionally performing moves, too.</para>
        </listitem>
        <listitem>
          <para>It takes care of complicated series of operations between
            which Subversion requires an intermediate commit&mdash;such
            as before renaming a file or directory twice.</para>
        </listitem>
        <listitem>
          <para>It will optionally tag the newly imported directory.</para>
        </listitem>
        <listitem>
          <para>It will optionally add arbitrary properties to files and
            directories that match a regular expression.</para>
        </listitem>
      </itemizedlist>

      <para><command>svn_load_dirs.pl</command> takes three mandatory
        arguments.  The first argument is the URL to the base
        Subversion directory to work in.  This argument is followed by
        the URL&mdash;relative to the first argument&mdash;into which the
        current vendor drop will be imported.  Finally, the third
        argument is the local directory to import.  Using our previous
        example, a typical run of <command>svn_load_dirs.pl</command>
        might look like this:</para>

      <screen>
$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
                   current                                        \
                   /path/to/libcomplex-1.1
&hellip;
</screen>

      <para>You can indicate that you'd like
        <command>svn_load_dirs.pl</command> to tag the new vendor drop
        by passing the <option>-t</option> command-line option and
        specifying a tag name.  This tag is another URL relative to
        the first program argument.</para>

      <screen>
$ svn_load_dirs.pl -t libcomplex-1.1                              \
                   http://svn.example.com/repos/vendor/libcomplex \
                   current                                        \
                   /path/to/libcomplex-1.1
&hellip;
</screen>

      <para>When you run <command>svn_load_dirs.pl</command>, it
        examines the contents of your existing <quote>current</quote>
        vendor drop and compares them with the proposed new vendor
        drop.  In the trivial case, no files will be in
        one version and not the other, and the script will perform the
        new import without incident.  If, however, there are
        discrepancies in the file layouts between versions,
        <command>svn_load_dirs.pl</command> will ask you how
        to resolve those differences.  For example, you
        will have the opportunity to tell the script that you know
        that the file <filename>math.c</filename> in version 1.0 of
        libcomplex was renamed to <filename>arithmetic.c</filename> in
        libcomplex 1.1.  Any discrepancies not explained by moves
        are treated as regular additions and deletions.</para>

      <para>The script also accepts a separate configuration file for
        setting properties on files and directories matching a regular
        expression that are <emphasis>added</emphasis> to the
        repository.  This configuration file is specified to
        <command>svn_load_dirs.pl</command> using the
        <option>-p</option> command-line option.  Each line of the
        configuration file is a whitespace-delimited set of two or
        four values: a Perl-style regular expression against which to match the
        added path, a control keyword (either
        <literal>break</literal> or <literal>cont</literal>), and then
        optionally a property name and value.</para>

      <screen>
\.png$              break   svn:mime-type   image/png
\.jpe?g$            break   svn:mime-type   image/jpeg
\.m3u$              cont    svn:mime-type   audio/x-mpegurl
\.m3u$              break   svn:eol-style   LF
.*                  break   svn:eol-style   native
</screen>

      <para>For each added path, the configured property changes whose
        regular expression matches the path are applied in order,
        unless the control specification is <literal>break</literal>
        (which means that no more property changes should be applied
        to that path).  If the control specification is
        <literal>cont</literal>&mdash;an abbreviation for
        <literal>continue</literal>&mdash;matching will continue
        with the next line of the configuration file.</para>

      <para>Any whitespace in the regular expression, property name,
        or property value must be surrounded by either single or
        double quotes.  You can escape quotes that
        are not used for wrapping whitespace by preceding them with a
        backslash (<literal>\</literal>) character.  The backslash
        escapes only quotes when parsing the configuration file, so do
        not protect any other characters beyond what is necessary for
        the regular expression.</para>

    </sect2>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.branchmerge.summary">
    <title>Summary</title>

    <para>We covered a lot of ground in this chapter.  We
      discussed the concepts of tags and branches and demonstrated
      how Subversion implements these concepts by copying directories
      with the <command>svn copy</command> command.  We showed how
      to use <command>svn merge</command> to copy changes from one
      branch to another or roll back bad changes.  We went over
      the use of <command>svn switch</command> to create
      mixed-location working copies.  And we talked about how one
      might manage the organization and lifetimes of branches in a
      repository.</para>

    <para>Remember the Subversion mantra: branches and tags are cheap.
      So don't be afraid to use them when needed!</para>

    <para>As a helpful reminder of all the operations we discussed,
      here is handy reference table you can consult as
      you begin to make use of branches.</para>

    <table id="svn.branchemerge.summary.tbl-1">
      <title>Branching and merging commands</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Action</entry>
            <entry>Command</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>Create a branch or tag</entry>
            <entry><userinput>svn copy <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput></entry>
          </row>

          <row>
            <entry>Switch a working copy to a branch or tag</entry>
            <entry><userinput>svn switch <replaceable>URL</replaceable></userinput></entry>
          </row>

          <row>
            <entry>Synchronize a branch with trunk</entry>
            <entry><userinput>svn merge <replaceable>trunkURL</replaceable>; svn commit</userinput></entry>
          </row>

          <row>
            <entry>See merge history or eligible changesets</entry>
            <entry><userinput>svn mergeinfo target --from-source=<replaceable>URL</replaceable></userinput></entry>
          </row>

          <row>
            <entry>Merge a branch back into trunk</entry>
            <entry><userinput>svn merge --reintegrate <replaceable>branchURL</replaceable>; svn commit</userinput></entry>
          </row>

          <row>
            <entry>Merge one specific change</entry>
            <entry><userinput>svn merge -c <replaceable>REV</replaceable> <replaceable>URL</replaceable>; svn commit</userinput></entry>
          </row>

          <row>
            <entry>Merge a range of changes</entry>
            <entry><userinput>svn merge -r <replaceable>REV1</replaceable>:<replaceable>REV2</replaceable> <replaceable>URL</replaceable>; svn commit</userinput></entry>
          </row>

          <row>
            <entry>Block a change from automatic merging</entry>
            <entry><userinput>svn merge -c <replaceable>REV</replaceable> --record-only <replaceable>URL</replaceable>; svn commit</userinput></entry>
          </row>

          <row>
            <entry>Preview a merge</entry>
            <entry><userinput>svn merge <replaceable>URL</replaceable> --dry-run</userinput></entry>
          </row>

          <row>
            <entry>Abandon merge results</entry>
            <entry><userinput>svn revert -R .</userinput></entry>
          </row>

          <row>
            <entry>Resurrect something from history</entry>
            <entry><userinput>svn copy <replaceable>URL</replaceable>@<replaceable>REV</replaceable> <replaceable>localPATH</replaceable></userinput></entry>
          </row>

          <row>
            <entry>Undo a committed change</entry>
            <entry><userinput>svn merge -c -<replaceable>REV</replaceable> <replaceable>URL</replaceable>; svn commit</userinput></entry>
          </row>

          <row>
            <entry>Examine merge-sensitive history</entry>
            <entry><userinput>svn log -g; svn blame -g</userinput></entry>
          </row>

          <row>
            <entry>Create a tag from a working copy</entry>
            <entry><userinput>svn copy . <replaceable>tagURL</replaceable></userinput></entry>
          </row>

          <row>
            <entry>Rearrange a branch or tag</entry>
            <entry><userinput>svn mv <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput></entry>
          </row>

          <row>
            <entry>Remove a branch or tag</entry>
            <entry><userinput>svn rm <replaceable>URL</replaceable></userinput></entry>
          </row>
        </tbody>
      </tgroup>
      </table>

  </sect1>

</chapter>

<!--
local variables:
sgml-parent-document: ("book.xml" "chapter")
end:
-->

Show details Hide details

Change log

r3306 by cmpilato on Sep 15, 2008 Diff

Tag 1.5 version of the English book (also
known "Version Control With
Subversion, second edition", or "ISBN 10:
0-596-51033-0", or "ISBN 13:
9780596510336", or "Pilato's Bane", or
...)

Go to:

Older revisions

r3301 by cmpilato on Sep 12, 2008 Diff

* src/en/book/ch00-preface.xml,
* src/en/book/ch03-advanced-
topics.xml,
* src/en/book/ch05-repository-
admin.xml,
...

r3294 by cmpilato on Sep 4, 2008 Diff

Minor wording tweak that I suspect
O'Reilly's copyeditors would
have smacked me for writing in the
first place.

r3293 by cmpilato on Sep 4, 2008 Diff

* src/en/book/ch03-advanced-
topics.xml,
* src/en/book/ch04-branching-and-
merging.xml
  Tweak some wording to avoid implying
...

All revisions of this file

File info

Size: 150063 bytes, 3247 lines

View raw file

File properties

svn:mime-type: text/xml
svn:eol-style: native