<?xml version="1.0" encoding="utf-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Basic Merging</title> <link rel="stylesheet" type="text/css" href="styles.css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /> <style type="text/css"> body { background-image: url('images/draft.png'); background-repeat: no-repeat; background-position: top left; /* The following properties make the watermark "fixed" on the page. */ /* I think that's just a bit too distracting for the reader... */ /* background-attachment: fixed; */ /* background-position: center center; */ }</style> <link rel="home" href="index.html" title="Version Control with Subversion [DRAFT]" /> <link rel="up" href="svn.branchmerge.html" title="Chapter 4. Branching and Merging" /> <link rel="prev" href="svn.branchmerge.using.html" title="Using Branches" /> <link rel="next" href="svn.branchmerge.advanced.html" title="Advanced Merging" /> </head> <body> <div xmlns="" id="vcws-version-notice"> <p>This text is a work in progress—highly subject to change—and may not accurately describe any released version of the Apache™ Subversion® software. Bookmarking or otherwise referring others to this page is probably not such a smart idea. Please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a> for stable versions of this book.</p> </div> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Basic Merging</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="svn.branchmerge.using.html">Prev</a> </td> <th width="60%" align="center">Chapter 4. Branching and Merging</th> <td width="20%" align="right"> <a accesskey="n" href="svn.branchmerge.advanced.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="svn.branchmerge.basicmerging"></a>Basic Merging</h2> </div> </div> </div> <p>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 trunk, or main line of development.</p> <p>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.</p> <p>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 <span class="emphasis"><em>too</em></span> far apart. Remember that one of the problems with the <span class="quote">“<span class="quote">crawl in a hole</span>”</span> 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.</p> <p> <a id="idm4551" class="indexterm"></a>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 <span class="quote">“<span class="quote">copy</span>”</span> 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 <em class="firstterm">merging</em>, and it is performed using various invocations of the <span class="command"><strong>svn merge</strong></span> subcommand.</p> <p>In the examples that follow, we're assuming that both your Subversion client and server are running Subversion 1.8 (or later). If either client or server is older than version 1.5, things are more complicated: the system won't track changes automatically, forcing you 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 <a class="xref" href="svn.branchmerge.advanced.html#svn.branchmerge.advanced.advancedsyntax" title="Merge Syntax: Full Disclosure">the section called “Merge Syntax: Full Disclosure”</a> 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 <span class="emphasis"><em>strongly</em></span> recommend that you make sure your client and server are at least at version 1.5.</p> <div class="sidebar"> <a id="svn.branchmerge.basicmerging.mergetracking"></a> <div class="titlepage"> <div> <div> <p class="title"> <strong>Merge Tracking</strong> </p> </div> </div> </div> <p> <a id="idm4562" class="indexterm"></a>Subversion 1.5 introduced the <em class="firstterm">merge tracking</em> feature to Subversion. Prior to this feature keeping track of merges required cumbersome manual procedures or the use of external tools. Subsequent releases of Subversion introduced many enhancements and bug fixes to merge tracking, which is why we recommend using the most recent versions for both your server and client. Keep in mind that even if your server is running 1.5-1.7, you can still use a 1.8 client. This is particularly important with regard to merge tracking, because the overwhelming majority of fixes and enhancements to it are on the client side.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.changesets"></a>Changesets</h3> </div> </div> </div> <p> <a id="idm4568" class="indexterm"></a>Before we proceed further, we should warn you that there's a lot of discussion of <span class="quote">“<span class="quote">changes</span>”</span> in the pages ahead. A lot of people experienced with version control systems use the terms <span class="quote">“<span class="quote">change</span>”</span> and <span class="quote">“<span class="quote">changeset</span>”</span> interchangeably, and we should clarify what Subversion understands as a <em class="firstterm">changeset</em>.</p> <p>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.</p> <p>In Subversion, a global revision number <em class="replaceable"><code>N</code></em> names a tree in the repository: it's the way the repository looked after the <em class="replaceable"><code>N</code></em>th commit. It's also the name of an implicit changeset: if you compare tree <em class="replaceable"><code>N</code></em> with tree <em class="replaceable"><code>N</code></em>-1, you can derive the exact patch that was committed. For this reason, it's easy to think of revision <em class="replaceable"><code>N</code></em> 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—for example, <span class="quote">“<span class="quote">this issue was fixed by r9238.</span>”</span> Somebody can then run <strong class="userinput"><code>svn log -r 9238</code></strong> to read about the exact changeset that fixed the bug, and run <strong class="userinput"><code>svn diff -c 9238</code></strong> to see the patch itself. And (as you'll see shortly) Subversion's <span class="command"><strong>svn merge</strong></span> 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 <strong class="userinput"><code>-c 9238</code></strong> to <span class="command"><strong>svn merge</strong></span> would merge changeset r9238 into your working copy.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.basicmerging.stayinsync"></a>Keeping a Branch in Sync</h3> </div> </div> </div> <p> <a id="idm4590" class="indexterm"></a> <a id="idm4593" class="indexterm"></a>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 continue to make important changes in the project's <code class="filename">/trunk</code>. It's in your best interest to replicate those changes to your own branch, just to make sure they mesh well with your changes. This is done by performing an <em class="firstterm">automatic sync merge</em>—a merge operation designed to bring your branch up to date with any changes made to its ancestral parent branch since your branch was created. <a id="idm4599" class="indexterm"></a> An <span class="quote">“<span class="quote">automatic</span>”</span> merge is simply one in which you provide the bare minimum of information required for a merge (i.e. a single merge source and a working copy target) and let Subversion determine which changes need merging—no changesets are passed to <span class="command"><strong>svn merge</strong></span> via the <code class="option">-r</code> or <code class="option">-c</code> options in an automatic merge.</p> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p>Frequently keeping your branch in sync with the main development line helps prevent <span class="quote">“<span class="quote">surprise</span>”</span> conflicts when the time comes for you to fold your changes back into the trunk.</p> </td> </tr> </table> </div> <p>Subversion is aware of the history of your branch and knows when it split away from the trunk. To perform a sync merge, first make sure your working copy of the branch is <span class="quote">“<span class="quote">clean</span>”</span>—that it has no local modifications reported by <span class="command"><strong>svn status</strong></span>. Then simply run:</p> <div class="informalexample"> <pre class="screen"> $ pwd /home/user/my-calc-branch $ svn merge ^/calc/trunk --- Merging r341 through r351 into '.': U doc/INSTALL U src/real.c U src/button.c U Makefile --- Recording mergeinfo for merge of r341 through r351 into '.': U . $ </pre> </div> <p> <a id="idm4615" class="indexterm"></a>This basic syntax—<strong class="userinput"><code>svn merge <em class="replaceable"><code>URL</code></em></code></strong>—tells Subversion to merge all changes which have not been previously merged from the URL to the current working directory (which is typically the root of your working copy). Notice that we're using the caret (<code class="literal">^</code>) syntax<a href="#ftn.idm4621" class="footnote" id="idm4621"><sup class="footnote">[33]</sup></a> to avoid having to type out the entire <code class="filename">/trunk</code> URL. Also note the <span class="quote">“<span class="quote">Recording mergeinfo for merge…</span>”</span> notification. This tells you that the merge is updating the <code class="literal">svn:mergeinfo</code> property. We'll discuss both this property and these notifications later in this chapter, in <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.mergeinfo" title="Mergeinfo and Previews">the section called “Mergeinfo and Previews”</a>.</p> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p> <a id="idm4629" class="indexterm"></a>In this book and elsewhere (Subversion mailing lists, articles on merge tracking, etc.) you will frequently come across the term <em class="firstterm">mergeinfo</em>. This is simply shorthand for the <code class="literal">svn:mergeinfo</code> property.</p> </td> </tr> </table> </div> <div class="sidebar"> <div class="titlepage"> <div> <div> <p class="title"> <strong>Keeping a Branch in Sync Without Merge Tracking</strong> </p> </div> </div> </div> <p>You may not always be able to use Subversion's merge tracking feature, perhaps because your server is running Subversion 1.4 or earlier or you must use an older client. In such a scenario, you can of course still perform merges, but Subversion will need you to manually do many of the historical calculations that it automatically does on your behalf when the merge tracking feature is available.</p> <p>To replicate the most recent trunk changes you need to perform sync merges the <span class="quote">“<span class="quote">old-fashioned</span>”</span> way—by specifying ranges of revisions you wish to merge.</p> <p>Using the ongoing example, you know that you branched <code class="filename">/calc/trunk</code> to <code class="filename">/calc/branches/my-calc-branch</code> in revision 341:</p> <div class="informalexample"> <pre class="screen"> $ svn log -v -r341 ------------------------------------------------------------------------ r341 | user | 2013-02-15 07:41:25 -0500 (Fri, 15 Feb 2013) | 1 line Changed paths: A /calc/branches/my-calc-branch (from /calc/trunk:340) Creating a private branch of /calc/trunk. ------------------------------------------------------------------------ </pre> </div> <p>When you are ready to synchronize your branch with the ongoing changes from trunk, you specify the starting revision as the revision of <code class="filename">/calc/trunk</code> which the branch was copied from and the ending revision as the youngest change on <code class="filename">/calc/trunk</code>. You can find the latter with the <span class="command"><strong>svn log</strong></span> command with the <code class="option">-r</code> set to <code class="literal">HEAD</code>:</p> <div class="informalexample"> <pre class="screen"> $ svn log -q -rHEAD http://svn.example.com/repos/calc/trunk ------------------------------------------------------------------------ r351 | sally | 2013-02-16 08:04:22 -0500 (Sat, 16 Feb 2013) ------------------------------------------------------------------------ $ svn merge http://svn.example.com/repos/calc/trunk -r340:351 U doc/INSTALL U src/real.c U src/button.c U Makefile </pre> </div> <p>After any conflicts have been resolved, you can commit the merged changes to your branch. Now, to avoid accidentally trying to merge these same changes into your branch again in the future, you'll need to record the fact that you've already merged them. But where should that record be kept? One of the simplest places to record this information is in the log message for the commit of the merge:</p> <div class="informalexample"> <pre class="screen"> $ svn ci -m "Sync the my-calc-branch with ^/calc/trunk through r351." … </pre> </div> <p>The next time you sync <code class="filename">/calc/branches/my-calc-branch</code> with <code class="filename">/calc/trunk</code> you repeat this process, except that the starting revision is the <span class="emphasis"><em>youngest</em></span> revision that's already been merged in from the trunk. If you've been keeping good records of your merges in the commit log messages, you should be able to determine what that youngest revision was by reading the revision logs associated with your branch. Once you know your starting revision, you can perform another sync merge:</p> <div class="informalexample"> <pre class="screen"> $ svn log -q -rHEAD http://svn.example.com/repos/calc/trunk ------------------------------------------------------------------------ r959 | sally | 2013-03-5 7:30:21 -0500 (Tue, 05 Mar 2013) ------------------------------------------------------------------------ $ svn merge http://svn.example.com/repos/calc/trunk -r351:959 … </pre> </div> </div> <p>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:</p> <div class="informalexample"> <pre class="screen"> $ svn status M . M Makefile M doc/INSTALL M src/button.c M src/real.c </pre> </div> <p>At this point, the wise thing to do is look at the changes carefully with <span class="command"><strong>svn diff</strong></span>, and then build and test your branch. Notice that the current working directory (<span class="quote">“<span class="quote"><code class="filename">.</code></span>”</span>) has also been modified; <span class="command"><strong>svn diff</strong></span> shows that its <code class="literal">svn:mergeinfo</code> property has been created. </p> <div class="informalexample"> <pre class="screen"> $ svn diff --depth empty . Index: . =================================================================== --- . (revision 351) +++ . (working copy) Property changes on: . ___________________________________________________________________ Added: svn:mergeinfo Merged /calc/trunk:r341-351 </pre> </div> <p> This new property is important merge-related metadata that you should <span class="emphasis"><em>not</em></span> touch, since it is needed by future <span class="command"><strong>svn merge</strong></span> commands. (We'll learn more about this metadata later in the chapter.)</p> <p>After performing the merge, you might also need to resolve some conflicts—just as you do with <span class="command"><strong>svn update</strong></span>—or possibly make some small edits to get things working properly. (Remember, just because there are no <span class="emphasis"><em>syntactic</em></span> conflicts doesn't mean there aren't any <span class="emphasis"><em>semantic</em></span> conflicts!) If you encounter serious problems, you can always abort the local changes by running <strong class="userinput"><code>svn revert . -R</code></strong> (which will undo all local modifications) and starting a long <span class="quote">“<span class="quote">what's going on?</span>”</span> discussion with your collaborators. If things look good, however, you can submit these changes into the repository:</p> <div class="informalexample"> <pre class="screen"> $ svn commit -m "Sync latest trunk changes to my-calc-branch." Sending . Sending Makefile Sending doc/INSTALL Sending src/button.c Sending src/real.c Transmitting file data .... Committed revision 352. </pre> </div> <p>At this point, your private branch is now <span class="quote">“<span class="quote">in sync</span>”</span> 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.</p> <div class="sidebar"> <div class="titlepage"> <div> <div> <p class="title"> <strong>Why Not Use Patches Instead?</strong> </p> </div> </div> </div> <p>A question may be on your mind, especially if you're a Unix user: why bother to use <span class="command"><strong>svn merge</strong></span> at all? Why not simply use <span class="command"><strong>svn patch</strong></span> or the operating system's <span class="command"><strong>patch</strong></span> command to accomplish the same job? For example:</p> <div class="informalexample"> <pre class="screen"> $ cd my-calc-branch $ svn diff -r 341:351 ^/calc/trunk > my-patch-file $ svn patch my-patch-file U doc/INSTALL U src/real.c U src/button.c U Makefile </pre> </div> <p>In this particular example, there really isn't much difference. But <span class="command"><strong>svn merge</strong></span> has special abilities that surpass the <span class="command"><strong>patch</strong></span> program. The file format used by <span class="command"><strong>patch</strong></span> is quite limited; it's able to tweak file contents only. There's no way to represent changes to <span class="emphasis"><em>trees</em></span>, such as the addition, removal, or renaming of files and directories. Nor can the <span class="command"><strong>patch</strong></span> program notice changes to properties. If Sally's change had, say, added a new directory, the output of <span class="command"><strong>svn diff</strong></span> wouldn't have mentioned it at all. <span class="command"><strong>svn diff</strong></span> outputs only the limited patch format, so there are some ideas it simply can't express. Even Subversion's own <span class="command"><strong>svn patch</strong></span> subcommand, while more flexible than the patch program, still has similar limitations.</p> <p>The <span class="command"><strong>svn merge</strong></span> 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 <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.mergeinfo" title="Mergeinfo and Previews">the section called “Mergeinfo and Previews”</a>). 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.</p> </div> <p>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 want to replicate the latest trunk changes to your branch and bring yourself in sync. Just run the same merge command again!</p> <div class="informalexample"> <pre class="screen"> $ svn merge ^/calc/trunk svn: E195020: Cannot merge into mixed-revision working copy [352:357]; try up\ dating first $ </pre> </div> <p>Well that was unexpected! After making changes to your branch over the past week you now find yourself with a working copy that contains a mixture of revisions (see <a class="xref" href="svn.basic.in-action.html#svn.basic.in-action.mixedrevs" title="Mixed-revision working copies">the section called “Mixed-revision working copies”</a>). With Subversion 1.7 and later, the <span class="command"><strong>svn merge</strong></span> subcommand disables merges into mixed-revision working copies by default. Without going into too much detail, this is because of limitations in the way merges are tracked by the <code class="literal">svn:mergeinfo</code> property (see <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.mergeinfo" title="Mergeinfo and Previews">the section called “Mergeinfo and Previews”</a> for details). These limitations mean that merges into mixed-revision working copies can result in unexpected text and tree conflicts.<a href="#ftn.idm4712" class="footnote" id="idm4712"><sup class="footnote">[34]</sup></a> We don't want any needless conflicts, so we update the working copy and then reattempt the merge.</p> <div class="informalexample"> <pre class="screen"> $ svn up Updating '.': At revision 361. $ svn merge ^/calc/trunk --- Merging r352 through r361 into '.': U src/real.c U src/main.c --- Recording mergeinfo for merge of r352 through r361 into '.': U . </pre> </div> <p>Subversion knows which trunk changes you previously replicated to your branch, so it carefully replicates only those changes you don't yet have. And once again, you build, test, and <span class="command"><strong>svn commit</strong></span> the local modifications to your branch.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.basicmerging.stayinsync.subtree"></a>Subtree Merges and Subtree Mergeinfo</h3> </div> </div> </div> <p> <a id="idm4723" class="indexterm"></a> <a id="idm4726" class="indexterm"></a>In most of the examples in this chapter the merge target is the root directory of a branch (see <a class="xref" href="svn.branchmerge.whatis.html" title="What's a Branch?">the section called “What's a Branch?”</a>). While this is a best practice, you may occasionally need to merge directly to some child of the branch root. This type of merge is called a <em class="firstterm">subtree merge</em> and the mergeinfo recorded to describe it is called <em class="firstterm">subtree mergeinfo</em>. There is nothing special about subtree merges or subtree mergeinfo. In fact there is really only one important point to keep in mind about these concepts: the complete record of merges to a branch may not be contained solely in the mergeinfo on the branch root. You may have to consider subtree mergeinfo to get a full accounting. Fortunately Subversion does this for you and rarely will you need to concern yourself with it. A brief example will help explain:</p> <div class="informalexample"> <pre class="screen"> # We need to merge r958 from trunk to branches/proj-X/doc/INSTALL, # but that revision also affects main.c, which we don't want to merge: $ svn log --verbose --quiet -r 958 ^/ ------------------------------------------------------------------------ r958 | bruce | 2011-10-20 13:28:11 -0400 (Thu, 20 Oct 2011) Changed paths: M /trunk/doc/INSTALL M /trunk/src/main.c ------------------------------------------------------------------------ # No problem, we'll do a subtree merge targeting the INSTALL file # directly, but first take a note of what mergeinfo exists on the # root of the branch: $ cd branches/proj-X $ svn propget svn:mergeinfo --recursive Properties on '.': svn:mergeinfo /trunk:651-652 # Now we perform the subtree merge, note that merge source # and target both point to INSTALL: $ svn merge ^/trunk/doc/INSTALL doc/INSTALL -c 958 --- Merging r958 into 'doc/INSTALL': U doc/INSTALL --- Recording mergeinfo for merge of r958 into 'doc/INSTALL': G doc/INSTALL # Once the merge is complete there is now subtree mergeinfo on INSTALL: $ svn propget svn:mergeinfo --recursive Properties on '.': svn:mergeinfo /trunk:651-652 Properties on 'doc/INSTALL': svn:mergeinfo /trunk/doc/INSTALL:651-652,958 # What if we then decide we do want all of r958? Easy, all we need do is # repeat the merge of that revision, but this time to the root of the # branch, Subversion notices the subtree mergeinfo on INSTALL and doesn't # try to merge any changes to it, only the changes to main.c are merged: $ svn merge ^/subversion/trunk . -c 958 --- Merging r958 into '.': U src/main.c --- Recording mergeinfo for merge of r958 into '.': U . --- Eliding mergeinfo from 'doc/INSTALL': U doc/INSTALL </pre> </div> <p> <a id="idm4735" class="indexterm"></a>You might be wondering why <code class="filename">INSTALL</code> in the above example has mergeinfo for r651-652, when we only merged r958. This is due to mergeinfo inheritance, which we'll cover in the sidebar <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.mergeinfo.inheritance" title="Mergeinfo Inheritance">Mergeinfo Inheritance</a>. Also note that the subtree mergeinfo on <code class="filename">doc/INSTALL</code> was removed, or <span class="quote">“<span class="quote">elided</span>”</span>. This is called <em class="firstterm">mergeinfo elision</em> and it occurs whenever Subversion detects redundant subtree mergeinfo.</p> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p>Prior to Subversion 1.7, merges unconditionally updated <span class="emphasis"><em>all</em></span> of the subtree mergeinfo under the target to describe the merge. For users with a lot of subtree mergeinfo this meant that relatively <span class="quote">“<span class="quote">simple</span>”</span> merges (e.g. one which applied a diff to only a single file) resulted in changes to every subtree with mergeinfo, even those that were not parents of the affected path(s). This caused some level of confusion and frustration. Subversion 1.7 and later addresses this problem by only updating the mergeinfo on subtrees which are parents of the paths modified by the merge (i.e. paths changed, added, or deleted by application of the difference, see <a class="xref" href="svn.branchmerge.advanced.html#svn.branchmerge.advanced.advancedsyntax" title="Merge Syntax: Full Disclosure">the section called “Merge Syntax: Full Disclosure”</a>). The one exception to this behavior regards the actual merge target; the merge target's mergeinfo is always updated to describe the merge, even if the applied difference made no changes.</p> </td> </tr> </table> </div> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.basicmerging.reintegrate"></a>Reintegrating a Branch</h3> </div> </div> </div> <p>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 into sync with the trunk again, just as you've been doing all along<a href="#ftn.idm4751" class="footnote" id="idm4751"><sup class="footnote">[35]</sup></a>:</p> <div class="informalexample"> <pre class="screen"> $ svn up # (make sure the working copy is up to date) Updating '.': At revision 378. $ svn merge ^/calc/trunk --- Merging r362 through r378 into '.': U src/main.c --- Recording mergeinfo for merge of r362 through r378 into '.': U . $ # build, test, ... $ svn commit -m "Final merge of trunk changes to my-calc-branch." Sending . Sending src/main.c Transmitting file data . Committed revision 379. </pre> </div> <p>Now, use <span class="command"><strong>svn merge</strong></span> subcommand to automatically replicate your branch changes back into the trunk. This type of merge is called an <a id="idm4758" class="indexterm"></a> <span class="quote">“<span class="quote">automatic reintegrate</span>”</span> merge. You'll need a working copy of <code class="filename">/calc/trunk</code>. You can get one by doing an <span class="command"><strong>svn checkout</strong></span>, dredging up an old trunk working copy from somewhere on your disk, or using <span class="command"><strong>svn switch</strong></span> (see <a class="xref" href="svn.branchmerge.switchwc.html" title="Traversing Branches">the section called “Traversing Branches”</a>).</p> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p>The term <span class="quote">“<span class="quote">reintegrating</span>”</span> comes from the <span class="command"><strong>merge</strong></span> option <code class="option">--reintegrate</code>. This option is deprecated in Subversion 1.8 (which automatically detects when a reintegrate merge is needed), but is required for Subversion 1.5 through 1.7 clients when performing reintegrate merges.</p> </td> </tr> </table> </div> <p>Your trunk working copy cannot have any local edits, switched paths, or contain a mixture of revisions (see <a class="xref" href="svn.basic.in-action.html#svn.basic.in-action.mixedrevs" title="Mixed-revision working copies">the section called “Mixed-revision working copies”</a>). While these are typically best practices for merging anyway, they are <span class="emphasis"><em>required</em></span> for automatic reintegrate merges.</p> <p>Once you have a clean working copy of the trunk, you're ready to merge your branch back into it:</p> <div class="informalexample"> <pre class="screen"> $ pwd /home/user/calc-trunk $ svn update Updating '.': At revision 379. $ svn merge ^/calc/branches/my-calc-branch --- Merging differences between repository URLs into '.': U src/real.c U src/main.c U Makefile --- Recording mergeinfo for merge between repository URLs into '.': U . $ # build, test, verify, ... $ svn commit -m "Merge my-calc-branch back into trunk!" Sending . Sending Makefile Sending src/main.c Sending src/real.c Transmitting file data ... Committed revision 380. </pre> </div> <p>Congratulations, your branch-specific changes have now been merged back into the main line of development. Notice that the automatic reintegrate merge did a different sort of work than what you've done up until now. Previously, we were asking <span class="command"><strong>svn merge</strong></span> to grab the <span class="quote">“<span class="quote">next set</span>”</span> 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 341:351 from <code class="filename">/calc/trunk</code> to <code class="filename">/calc/branches/my-calc-branch</code>; later on, it continues by merging the next contiguously available range, 351:361. When doing the final sync, it merges the range 361:378.</p> <p>When merging <code class="filename">/calc/branches/my-calc-branch</code> back to the <code class="filename">/calc/trunk</code>, however, the underlying mathematics are quite different. Your feature branch is now a mishmash of both duplicated trunk changes and private branch changes, so there's no simple contiguous range of revisions to copy over. By using an automatic merge, you're asking Subversion to carefully replicate <span class="emphasis"><em>only</em></span> 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!)</p> <p>Keep in mind that the automatic reintegrate merges only support the use case described above. Because of this narrow focus, in addition to the requirements previously mentioned (up-to-date working copy <a href="#ftn.idm4787" class="footnote" id="idm4787"><sup class="footnote">[36]</sup></a> with no mixed-revisions, switched paths or local changes) it will not function in combination with most of the other <span class="command"><strong>svn merge</strong></span> options. You'll get an error if you use any non-global options but these: <code class="option">--accept</code>, <code class="option">--dry-run</code>, <code class="option">--diff3-cmd</code>, <code class="option">--extensions</code>, or <code class="option">--quiet</code>.</p> <p>Now that your private branch is merged to trunk, you may wish to remove it from the repository:</p> <div class="informalexample"> <pre class="screen"> $ svn delete ^/calc/branches/my-calc-branch \ -m "Remove my-calc-branch, reintegrated with trunk in r381." … </pre> </div> <p>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 <code class="filename">/calc/branches</code> directory, its existence is still an immutable part of the repository's history. A simple <span class="command"><strong>svn log</strong></span> command on the <code class="filename">/calc/branches</code> URL will show the entire history of your branch. Your branch can even be resurrected at some point, should you desire (see <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.resurrect" title="Resurrecting Deleted Items">the section called “Resurrecting Deleted Items”</a>).</p> <p>If you choose not to delete your branch after reintegrating it to the trunk you may continue to perform sync merges from the trunk and then reintegrate the branch again<a href="#ftn.idm4807" class="footnote" id="idm4807"><sup class="footnote">[37]</sup></a>. If you do this, only the changes made on your branch after the first reintegrate are merged to the trunk.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.basicmerging.mergeinfo"></a>Mergeinfo and Previews</h3> </div> </div> </div> <p> <a id="idm4813" class="indexterm"></a>The basic mechanism Subversion uses to track changesets—that is, which changes have been merged to which branches—is by recording data in versioned properties. Specifically, merge data is tracked in the <code class="literal">svn:mergeinfo</code> property attached to files and directories. (If you're not familiar with Subversion properties, see <a class="xref" href="svn.advanced.props.html" title="Properties">the section called “Properties”</a>.)</p> <p>You can examine the mergeinfo property, just like any other versioned property:</p> <div class="informalexample"> <pre class="screen"> $ cd my-calc-branch $ svn pg svn:mergeinfo -v Properties on '.': svn:mergeinfo /calc/trunk:341-378 </pre> </div> <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Warning"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Warning]" src="images/warning.png" /> </td> <th align="left">Warning</th> </tr> <tr> <td align="left" valign="top"> <p>While it is possible to modify <code class="literal">svn:mergeinfo</code> just as you might any other versioned property, we strongly discourage doing so unless you <span class="emphasis"><em>really</em></span> know what you're doing.</p> </td> </tr> </table> </div> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p>The amount of <code class="literal">svn:mergeinfo</code> on a single path can get quite large, as can the output of a <span class="command"><strong>svn propget --recursive</strong></span> or <span class="command"><strong>svn proplist --recursive</strong></span> when dealing with large amounts of subtree mergeinfo. See <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.stayinsync.subtree" title="Subtree Merges and Subtree Mergeinfo">the section called “Subtree Merges and Subtree Mergeinfo”</a> . The formatted output produced by the <code class="option">--verbose</code> option with either of these subcommands is often very helpful in these cases.</p> </td> </tr> </table> </div> <p>The <code class="literal">svn:mergeinfo</code> property is automatically maintained by Subversion whenever you run <span class="command"><strong>svn merge</strong></span>. Its value indicates which changes made to a given path have been replicated into the directory in question. In our previous example, the path which is the source of the merged changes is <code class="filename">/calc/trunk</code> and the directory which has received the changes is <code class="filename">/calc/branches/my-calc-branch</code>. Earlier versions of Subversion maintained the <code class="literal">svn:mergeinfo</code> property silently. You could still detect the changes, after a merge completed, with the <span class="command"><strong>svn diff</strong></span> or <span class="command"><strong>svn status</strong></span> subcommands, but the merge itself gave no indication when it changed the <code class="literal">svn:mergeinfo</code> property. In Subversion 1.7 and later this is no longer true as there are several notifications to alert you when a merge updates the <code class="literal">svn:mergeinfo</code> property. These notifications all begin with <span class="quote">“<span class="quote">--- Recording mergeinfo for</span>”</span> and appear at the end of the merge. Unlike other merge notifications, these don't describe the application of a difference to a working copy (see <a class="xref" href="svn.branchmerge.advanced.html#svn.branchmerge.advanced.advancedsyntax" title="Merge Syntax: Full Disclosure">the section called “Merge Syntax: Full Disclosure”</a>), but instead describe "housekeeping" changes made to keep track of what was merged.</p> <p>Subversion also provides a subcommand, <span class="command"><strong>svn mergeinfo</strong></span>, which is helpful in seeing the merge relationships between two branches; specifically which changesets a directory has absorbed or which changesets it's still eligible to receive. The latter gives a sort of preview of which changes a subsequent <span class="command"><strong>svn merge</strong></span> operation would replicate to your branch. By default, <span class="command"><strong>svn mergeinfo</strong></span> gives an graphical overview of the relationship between to branches. Returning to our earlier example, we use the subcommand to analyze the relationship between <code class="filename">/calc/trunk</code> and <code class="filename">/calc/branches/my-calc-branch</code>:</p> <div class="informalexample"> <pre class="screen"> $ cd my-calc-branch $ svn mergeinfo ^/calc/trunk youngest common ancestor | last full merge | | tip of branch | | | repository path 340 382 | | -------| |------------ calc/trunk \ / \ / --| |------------ calc/branches/my-calc-branch | | 379 382 </pre> </div> <p>The diagram shows that <code class="filename">/calc/branches/my-calc-branch </code> was copied from <code class="filename">/calc/trunk@340</code> and that most recent automatic merge was the reintegrate merge we made from the branch to the trunk in r380. Notice that the diagram does <span class="emphasis"><em>not</em></span> show the four automatic sync merges we made in revisions 352, 362, 372, and 379. Only the most recent automatic merge, in either direction<a href="#ftn.idm4856" class="footnote" id="idm4856"><sup class="footnote">[38]</sup></a>, is shown. This default output is useful for obtaining an overview of the merges between two branches, but to see the specific revisions which were merged we use the <code class="option">--show-revs=merged</code> option:</p> <div class="informalexample"> <pre class="screen"> $ svn mergeinfo ^/calc/trunk --show-revs merged r344 r345 r346 … r366 r367 r368 </pre> </div> <p>Likewise, to see which changes are eligible to merge from the trunk to the branch we can use the <code class="option">--show-revs=eligible </code> option:</p> <div class="informalexample"> <pre class="screen"> $ svn mergeinfo ^/calc/trunk --show-revs eligible r380 r381 r382 </pre> </div> <div class="sidebar"> <a id="svn.branchmerge.basicmerging.mergeinfo.operativerevs"></a> <div class="titlepage"> <div> <div> <p class="title"> <strong>Operative and Inoperative Merge Revisions</strong> </p> </div> </div> </div> <p>The revision lists produced by the <code class="option">--show-revs </code> option include only revisions which made (or would make) changes when merged. So while we have merged a contiguous range of revisions (i.e. r341-378) from <code class="filename">/calc/trunk</code> to <code class="filename">/calc/branches/my-calc-branch</code>, only the revisions listed with the <code class="option">--show-revs=merged</code> option actually represent changes made on <code class="filename">/calc/trunk</code>. These revisions are described as <span class="quote">“<span class="quote">operative</span>”</span> revisions as regards merging, not to be confused with the operative revision used with the <code class="option">-r</code> option, see <a class="xref" href="svn.advanced.pegrevs.html" title="Peg and Operative Revisions">the section called “Peg and Operative Revisions”</a>. Not suprisingly, the revisions in the range r341-378 that are <span class="emphasis"><em>not</em></span> listed as merged are termed <span class="quote">“<span class="quote">inoperative</span>”</span> revisions. </p> </div> <p>The <span class="command"><strong>svn mergeinfo</strong></span> command requires a <span class="quote">“<span class="quote">source</span>”</span> URL (where the changes come from), and takes an optional <span class="quote">“<span class="quote">target</span>”</span> URL (where the changes merge 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 <code class="filename">/calc/branches/my-calc-branch </code> from the specified trunk URL.</p> <p>Since Subversion 1.7, the <span class="command"><strong>svn mergeinfo</strong></span> subcommand can also account for subtree mergeinfo and non-inheritable mergeinfo. It accounts for subtree mergeinfo by use of the <code class="option">--recursive</code> or <code class="option">--depth</code> options, while non-inheritable mergeinfo is considered by default.</p> <div class="sidebar"> <a id="svn.branchmerge.basicmerging.mergeinfo.inheritance"></a> <div class="titlepage"> <div> <div> <p class="title"> <strong>Mergeinfo Inheritance</strong> </p> </div> </div> </div> <p> <a id="idm4891" class="indexterm"></a> <a id="idm4894" class="indexterm"></a>When a path has the <code class="literal">svn:mergeinfo</code> property set on it we say it has <em class="firstterm">explicit mergeinfo</em>. This explicit mergeinfo describes not only what changes were merged into that particular directory, but also all the children of that directory (because those children inherit the mergeinfo of their parent path). For example:</p> <div class="informalexample"> <pre class="screen"> # What explicit mergeinfo exists on a branch? $ svn propget svn:mergeinfo ^/branches/proj-X --recursive /trunk:651-652 # What children does proj-X have? $ svn list --recursive ^/branches/proj-X doc/ doc/INSTALL README src/main.c # Ask what revs were merged to a file with no explicit mergeinfo $ svn mergeinfo ^/trunk/src/main.c ^/branches/proj-X/src/main.c \ --show-revs merged 651 652 </pre> </div> <p>Notice from our first subcommand that only the root of <code class="filename">/branches/proj-X</code> has any explicit mergeinfo. However, when we use <span class="command"><strong>svn mergeinfo</strong></span> to ask what was merged to <code class="filename">/branches/proj-X/src/main.c</code> it reports that the two revisions described in the explicit mergeinfo on <code class="filename">/branches/proj-X</code> were merged. This is because <code class="filename">/branches/proj-X/src/main.c</code>, having no explicit mergeinfo of its own, inherits the mergeinfo from its nearest parent with explicit mergeinfo, <code class="filename">/branches/proj-X</code>.</p> <p>There are two cases in which mergeinfo is not inherited. First, if a path has explicit mergeinfo, then it never inherits mergeinfo. Another way to think of this is that explicit mergeinfo is always a complete record of the merges to a given path. Once it exists it overrides any mergeinfo that path might otherwise inherit. The second way is when dealing with non-inheritable mergeinfo, a special type of explicit mergeinfo that applies <span class="emphasis"><em>only</em></span> to the directory on which the <code class="literal">svn:mergeinfo</code> property is set (and it's only directories, non-inheritable mergeinfo is never set on files). For example:</p> <div class="informalexample"> <pre class="screen"> # The '*' decorator indicates non-inheritable mergeinfo $ svn propget svn:mergeinfo ^/branches/proj-X /trunk:651-652,758* # Revision 758 is non-inheritable, but still applies to the path it is # set on. Here the '*' decorator signals that r758 is only partially # merged from trunk. $ svn mergeinfo ^/trunk ^/branches/proj-X --show-revs merged 651 652 758* # Revision 758 is not reported as merged because it is non-inheritable # and applies only to ^/trunk $ svn mergeinfo ^/trunk/src/main.c ^/branches/proj-X/src/main.c \ --show-revs merged 651 652 </pre> </div> <p>You might never have to think about mergeinfo inheritance or encounter non-inheritable mergeinfo in your own repository. A discussion of the full ramifications of mergeinfo inheritance are beyond the scope of this book. If you have more questions check out some of the references mentioned in <a class="xref" href="svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword" title="The Final Word on Merge Tracking">the section called “The Final Word on Merge Tracking”</a></p> </div> <p>Let's say we have a branch with both subtree and non-inheritable mergeinfo:</p> <div class="informalexample"> <pre class="screen"> $ svn pg svn:mergeinfo -vR # Non-inheritable mergeinfo Properties on '.': svn:mergeinfo /calc/trunk:354,385-388* # Subtree mergeinfo Properties on 'Makefile': svn:mergeinfo /calc/trunk/Makefile:354,380 </pre> </div> <p>From the above mergeinfo we see that r385-388 has only been merged into the root of the branch, but not any of the root's children. We also see that r380 has only been merged to <code class="filename">Makefile</code>. When we use <span class="command"><strong>svn mergeinfo</strong></span> with the <code class="option">--recursive</code> option to see what has been merged from <code class="filename">/calc/trunk</code> to this branch, we see three revisions are flagged with the <code class="literal">*</code> marker:</p> <div class="informalexample"> <pre class="screen"> $ svn mergeinfo -R --show-revs=merged ^/calc/trunk . r354 r380* r385 r386 r387* r388* </pre> </div> <p>The <code class="literal">*</code> indicates revisions that are only <span class="emphasis"><em>partially</em></span> merged to the target in question (the meaning is the same if we are checking for eligible revisions). What this means in this example is that if we tried to merge r380, r387, or r388 from <code class="filename">^/trunk</code> then more changes would result. Likewise, because r354, r385 and r386 are <span class="emphasis"><em>not</em></span> flagged with a <code class="literal">*</code>, we know that re-merging those revisions would have no result. <a href="#ftn.idm4932" class="footnote" id="idm4932"><sup class="footnote">[39]</sup></a></p> <p>Another way to get a more precise preview of a merge operation is to use the <code class="option">--dry-run</code> option:</p> <div class="informalexample"> <pre class="screen"> $ svn merge ^/paint/trunk paint-feature-branch --dry-run --- Merging r290 through r383 into 'paint-feature-branch': U paint-feature-branch/src/palettes.c U paint-feature-branch/src/brushes.c U paint-feature-branch/Makefile $ svn status # nothing printed, working copy is still unchanged. </pre> </div> <p>The <code class="option">--dry-run</code> option doesn't actually apply any local changes to the working copy. It shows only status codes that <span class="emphasis"><em>would</em></span> be printed in a real merge. It's useful for getting a <span class="quote">“<span class="quote">high-level</span>”</span> preview of the potential merge, for those times when running <span class="command"><strong>svn diff</strong></span> gives too much detail.</p> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p>After performing a merge operation, but before committing the results of the merge, you can use <strong class="userinput"><code>svn diff --depth=empty <em class="replaceable"><code> /path/to/merge/target</code></em></code></strong> to see only the changes to the immediate target of your merge. If your merge target was a directory, only property differences are displayed. This is a handy way to see the changes to the <code class="literal">svn:mergeinfo</code> property recorded by the merge operation, which will remind you about what you've just merged.</p> </td> </tr> </table> </div> <p>Of course, the best way to preview a merge operation is to just do it! Remember, running <span class="command"><strong>svn merge</strong></span> isn't an inherently risky thing (unless you've made local modifications to your working copy—but we already stressed that you shouldn't merge into such an environment). If you don't like the results of the merge, simply run <strong class="userinput"><code>svn revert . -R</code></strong> to revert the changes from your working copy and retry the command with different options. The merge isn't final until you actually <span class="command"><strong>svn commit</strong></span> the results.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.basicmerging.undo"></a>Undoing Changes</h3> </div> </div> </div> <p>An extremely common use for <span class="command"><strong>svn merge</strong></span> is to roll back a change that has already been committed. Suppose you're working away happily on a working copy of <code class="filename">/calc/trunk</code>, and you discover that the change made back in revision 392, which changed several code files, is completely wrong. It never should have been committed. You can use <span class="command"><strong>svn merge</strong></span> to <span class="quote">“<span class="quote">undo</span>”</span> the change in your working copy, and then commit the local modification to the repository. All you need to do is to specify a <span class="emphasis"><em>reverse</em></span> difference. (You can do this by specifying <code class="option">--revision 392:391</code>, or by an equivalent <code class="option">--change -392</code>.)</p> <div class="informalexample"> <pre class="screen"> $ svn merge ^/calc/trunk . -c-392 --- Reverse-merging r392 into '.': U src/real.c U src/main.c U src/button.c U src/integer.c --- Recording mergeinfo for reverse merge of r392 into '.': U . $ svn st M src/button.c M src/integer.c M src/main.c M src/real.c $ svn diff … # verify that the change is removed … $ svn commit -m "Undoing erroneous change committed in r392." Sending src/button.c Sending src/integer.c Sending src/main.c Sending src/real.c Transmitting file data .... Committed revision 399. </pre> </div> <p>As we mentioned earlier, one way to think about a repository revision is as a specific changeset. By using the <code class="option">-r</code> option, you can ask <span class="command"><strong>svn merge</strong></span> to apply a changeset, or a whole range of changesets, to your working copy. In our case of undoing a change, we're asking <span class="command"><strong>svn merge</strong></span> to apply changeset r392 to our working copy <span class="emphasis"><em>backward</em></span>.</p> <p>Keep in mind that rolling back a change like this is just like any other <span class="command"><strong>svn merge</strong></span> operation, so you should use <span class="command"><strong>svn status</strong></span> and <span class="command"><strong>svn diff</strong></span> to confirm that your work is in the state you want it to be in, and then use <span class="command"><strong>svn commit</strong></span> to send the final version to the repository. After committing, this particular changeset is no longer reflected in the <code class="literal">HEAD</code> revision.</p> <p>Again, you may be thinking: well, that really didn't undo the commit, did it? The change still exists in revision 392. If somebody checks out a version of the <code class="filename">calc</code> project between revisions 392 and 398, she'll still see the bad change, right?</p> <p>Yes, that's true. When we talk about <span class="quote">“<span class="quote">removing</span>”</span> a change, we're really talking about removing it from the <code class="literal">HEAD</code> 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 <code class="literal">HEAD</code> 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.<a href="#ftn.idm4981" class="footnote" id="idm4981"><sup class="footnote">[40]</sup></a></p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.branchmerge.basicmerging.resurrect"></a>Resurrecting Deleted Items</h3> </div> </div> </div> <p>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 <code class="literal">HEAD</code> revision, but the object still exists in earlier revisions. One of the most common questions new users ask is, <span class="quote">“<span class="quote">How do I get my old file or directory back?</span>”</span></p> <p>The first step is to define exactly <span class="emphasis"><em>which</em></span> 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 is defined by a specific coordinate pair. (Remember the <span class="quote">“<span class="quote">peg revision</span>”</span> syntax—foo.c@224—mentioned back in <a class="xref" href="svn.advanced.pegrevs.html" title="Peg and Operative Revisions">the section called “Peg and Operative Revisions”</a>.)</p> <p>First, you might need to use <span class="command"><strong>svn log</strong></span> to discover the exact coordinate pair you wish to resurrect. A good strategy is to run <strong class="userinput"><code>svn log --verbose</code></strong> in a directory that used to contain your deleted item. The <code class="option">--verbose</code> (<code class="option">-v</code>) 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 <span class="command"><strong>grep</strong></span>, or perhaps via an incremental search in an editor). If you know that the item in question was recently deleted you might also use the <code class="option">--limit</code> option to keep the log output brief enough to examine manually.</p> <div class="informalexample"> <pre class="screen"> $ cd calc/trunk $ svn log -v --limit 3 ------------------------------------------------------------------------ r401 | sally | 2013-02-19 23:15:44 -0500 (Tue, 19 Feb 2013) | 1 line Changed paths: M /calc/trunk/src/main.c Follow-up to r400: Fix typos in help text. ------------------------------------------------------------------------ r400 | bill | 2013-02-19 20:55:08 -0500 (Tue, 19 Feb 2013) | 4 lines Changed paths: M /calc/trunk/src/main.c D /calc/trunk/src/real.c * calc/trunk/src/main.c: Update help text. * calc/trunk/src/real.c: Remove this file, none of the APIs implemented here are used anymore. ------------------------------------------------------------------------ r399 | sally | 2013-02-19 20:05:14 -0500 (Tue, 19 Feb 2013) | 1 line Changed paths: M /calc/trunk/src/button.c M /calc/trunk/src/integer.c M /calc/trunk/src/main.c M /calc/trunk/src/real.c Undoing erroneous change committed in r392. ------------------------------------------------------------------------ </pre> </div> <p>In the example, we're assuming that you're looking for a deleted file <code class="filename">real.c</code>. By looking through the logs of a parent directory, you've spotted that this file was deleted in revision 400. Therefore, the last version of the file to exist was in the revision right before that. Conclusion: you want to resurrect the path <code class="filename">/calc/trunk/real.c</code> from revision 399.</p> <p>That was the hard part—the research. Now that you know what you want to restore, you have two different choices.</p> <p>One option is to use <span class="command"><strong>svn merge</strong></span> to apply revision 400 <span class="quote">“<span class="quote">in reverse.</span>”</span> (We already discussed how to undo changes in <a class="xref" href="svn.branchmerge.basicmerging.html#svn.branchmerge.basicmerging.undo" title="Undoing Changes">the section called “Undoing Changes”</a>.) This would have the effect of re-adding <code class="filename">real.c</code> as a local modification. The file would be scheduled for addition, and after a commit, the file would again exist in <code class="literal">HEAD</code>.</p> <p>In this particular example, however, this is probably not the best strategy. Reverse-applying revision 400 would not only schedule <code class="filename">real.c</code> for addition, but the log message indicates that it would also undo certain changes to <code class="filename">main.c</code>, which you don't want. Certainly, you could reverse-merge revision 400 and then <span class="command"><strong>svn revert</strong></span> the local modifications to <code class="filename">main.c</code>, but this technique doesn't scale well. What if 90 files were changed in revision 400?</p> <p>A second, more targeted strategy is not to use <span class="command"><strong>svn merge</strong></span> at all, but rather to use the <span class="command"><strong>svn copy</strong></span> command. Simply copy the exact revision and path <span class="quote">“<span class="quote">coordinate pair</span>”</span> from the repository to your working copy:</p> <div class="informalexample"> <pre class="screen"> $ svn copy ^/calc/trunk/src/real.c@399 ./real.c A real.c $ svn st A + real.c # Commit the resurrection. … </pre> </div> <p>The plus sign in the status output indicates that the item isn't merely scheduled for addition, but scheduled for addition <span class="quote">“<span class="quote">with history.</span>”</span> Subversion remembers where it was copied from. In the future, running <span class="command"><strong>svn log</strong></span> on this file will traverse back through the file's resurrection and through all the history it had prior to revision 399. In other words, this new <code class="filename">real.c</code> 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 <span class="emphasis"><em>without</em></span> maintaining a historical link to the old file, this technique works just as well:</p> <div class="informalexample"> <pre class="screen"> $ svn cat ^/calc/trunk/src/real.c@399 > ./real.c $ svn add real.c A real.c # Commit the resurrection. … </pre> </div> <p>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—it can happen entirely in the repository:</p> <div class="informalexample"> <pre class="screen"> $ svn copy ^/calc/trunk/src/real.c@399 ^/calc/trunk/src/real.c \ -m "Resurrect real.c from revision 399." Committed revision 402. $ svn up Updating '.': A real.c Updated to revision 402. </pre> </div> </div> <div class="footnotes"> <br /> <hr style="width:100; text-align:left;margin-left: 0" /> <div id="ftn.idm4621" class="footnote"> <p><a href="#idm4621" class="para"><sup class="para">[33] </sup></a>This was introduced in svn 1.6.</p> </div> <div id="ftn.idm4712" class="footnote"> <p><a href="#idm4712" class="para"><sup class="para">[34] </sup></a>The <span class="command"><strong>svn merge</strong></span> subcommand option <code class="option">--allow-mixed-revisions</code> allows you to override this prohibition, but you should only do so if you understand the ramifications and have a good reason for it.</p> </div> <div id="ftn.idm4751" class="footnote"> <p><a href="#idm4751" class="para"><sup class="para">[35] </sup></a>Since Subversion 1.7 you don't absolutely have to do all your sync merges to the root of your branch as we do in this example. <span class="emphasis"><em>If</em></span> your branch is effectively synced via a series of subtree merges then the reintegrate will work, but ask yourself, if the branch is effectively synced, then why are you doing subtree merges? Doing so is almost always needlessly complex.</p> </div> <div id="ftn.idm4787" class="footnote"> <p><a href="#idm4787" class="para"><sup class="para">[36] </sup></a>Automatic reintegrate merges are allowed if the target is a shallow checkout (see <a class="xref" href="svn.advanced.sparsedirs.html" title="Sparse Directories">the section called “Sparse Directories”</a>) but any paths affected by the diff which are <span class="quote">“<span class="quote">missing</span>”</span> due to the sparse working copy will be skipped—this is probably <span class="emphasis"><em>not</em></span> what you intended!</p> </div> <div id="ftn.idm4807" class="footnote"> <p><a href="#idm4807" class="para"><sup class="para">[37] </sup></a>Only Subversion 1.8 supports this reuse of a feature branch. Earlier versions require some special handling before a feature branch can be reintegrated more than once. See the earlier version of this chapter for more information: <a class="ulink" href="http://svnbook.red-bean.com/en/1.7/svn.branchmerge.basicmerging.html#svn.branchemerge.basicmerging.reintegrate" target="_top">http://svnbook.red-bean.com/en/1.7/svn.branchmerge.basicmerging.html#svn.branchemerge.basicmerging.reintegrate</a></p> </div> <div id="ftn.idm4856" class="footnote"> <p><a href="#idm4856" class="para"><sup class="para">[38] </sup></a>By <span class="quote">“<span class="quote">direction</span>”</span> we mean either trunk-to-branch (automatic sync) or branch-to-trunk (automatic reintegrate) merges.</p> </div> <div id="ftn.idm4932" class="footnote"> <p><a href="#idm4932" class="para"><sup class="para">[39] </sup></a>This is a good example of inoperative merge revisions.</p> </div> <div id="ftn.idm4981" class="footnote"> <p><a href="#idm4981" class="para"><sup class="para">[40] </sup></a>The Subversion project has plans, however, to someday implement a command that would accomplish the task of permanently deleting information. In the meantime, see <a class="xref" href="svn.reposadmin.maint.html#svn.reposadmin.maint.tk.svndumpfilter" title="svndumpfilter">the section called “svndumpfilter”</a> for a possible workaround.</p> </div> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="svn.branchmerge.using.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="svn.branchmerge.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="svn.branchmerge.advanced.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Using Branches </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Advanced Merging</td> </tr> </table> </div> <div xmlns="" id="vcws-footer"> <hr /> <img src="images/cc-by.png" style="float: right;" /> <p>You are reading <em>Version Control with Subversion</em> (for Subversion 1.8), by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato.</p> <p>This work is licensed under the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.</p> <p>To submit comments, corrections, or other contributions to the text, please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a>.</p> </div> </body> </html>