<para>\r
You can integrate a bug tracking tool of your choice in\r
TortoiseGit. To do this, you have to define\r
- some properties, which start with <literal>bugtraq:</literal>.\r
- They must be set on Folders: (<xref linkend="tsvn-dug-propertypage"/>)\r
+ some configuration, which start with <literal>bugtraq.</literal>.\r
+ <xref linkend="tsvn-setting-bugtraq"/>)\r
</para>\r
<para>\r
There are two ways to integrate TortoiseGit with issue trackers. One is\r
based on simple strings, the other is based on\r
<emphasis>regular expressions</emphasis>.\r
- The properties used by both approaches are:\r
+ The configuration used by both approaches are:\r
<variablelist>\r
<varlistentry>\r
- <term condition="pot">bugtraq:url</term>\r
+ <term condition="pot">bugtraq.url</term>\r
<listitem>\r
<para>\r
- Set this property to the URL of your bug tracking tool.\r
+ Set this configuration to the URL of your bug tracking tool.\r
It must be properly URI encoded and it has to contain\r
<literal>%BUGID%</literal>.\r
<literal>%BUGID%</literal> is replaced with the Issue number\r
to display a link in the log dialog, so when you are looking\r
at the revision log you can jump directly to your\r
bug tracking tool.\r
- You do not have to provide this property, but then\r
+ You do not have to provide this configuration, but then\r
TortoiseGit shows only the\r
issue number and not the link to it.\r
e.g the TortoiseGit project is using\r
- <systemitem class="url">http://issues.TortoiseGit.net/?do=details&id=%BUGID%</systemitem>\r
+ <systemitem class="url">http://code.google.com/p/tortoisegit/issues/detail?id=%BUGID%</systemitem>\r
</para>\r
<para>\r
You can also use relative URLs instead of absolute ones. This is\r
useful when your issue tracker is on the same domain/server\r
as your source repository. In case the domain name ever changes,\r
- you don't have to adjust the <literal>bugtraq:url</literal> property.\r
+ you don't have to adjust the <literal>bugtraq.url</literal> configuration.\r
There are two ways to specify a relative URL:\r
</para>\r
+ <!--\r
<para>\r
If it begins with the string <literal>^/</literal> it is assumed\r
to be relative to the repository root.\r
if your repository is located on\r
<systemitem class="url">http://TortoiseGit.net/svn/trunk/</systemitem>.\r
</para>\r
+ -->\r
<para>\r
A URL beginning with the string <literal>/</literal> is assumed\r
to be relative to the server's hostname.\r
</listitem>\r
</varlistentry>\r
<varlistentry>\r
- <term condition="pot">bugtraq:warnifnoissue</term>\r
+ <term condition="pot">bugtraq.warnifnoissue</term>\r
<listitem>\r
<para>\r
Set this to <literal>true</literal>, if you want\r
is appended/prepended to the log message the user entered.\r
<variablelist>\r
<varlistentry>\r
- <term condition="pot">bugtraq:message</term>\r
+ <term condition="pot">bugtraq.message</term>\r
<listitem>\r
<para>\r
- This property activates the bug tracking system\r
+ This configuration activates the bug tracking system\r
in <emphasis>Input field</emphasis> mode.\r
- If this property is set, then TortoiseGit\r
+ If this configuration is set, then TortoiseGit\r
will prompt you to enter an issue number when you commit\r
your changes. It's used to add a line at the end of the\r
log message. It must contain\r
</listitem>\r
</varlistentry>\r
<varlistentry>\r
- <term condition="pot">bugtraq:append</term>\r
+ <term condition="pot">bugtraq.append</term>\r
<listitem>\r
<para>\r
- This property defines if the bug-ID is appended (true)\r
+ This configuration defines if the bug-ID is appended (true)\r
to the end of the log message or inserted (false) at the\r
start of the log message. Valid values are\r
<literal>true/false</literal>.\r
</listitem>\r
</varlistentry>\r
<varlistentry>\r
- <term condition="pot">bugtraq:label</term>\r
+ <term condition="pot">bugtraq.label</term>\r
<listitem>\r
<para>\r
This text is shown by TortoiseGit\r
</listitem>\r
</varlistentry>\r
<varlistentry>\r
- <term condition="pot">bugtraq:number</term>\r
+ <term condition="pot">bugtraq.number</term>\r
<listitem>\r
<para>\r
If set to <literal>true</literal> only numbers are allowed\r
the one used by the TortoiseGit project itself.\r
<variablelist>\r
<varlistentry>\r
- <term condition="pot">bugtraq:logregex</term>\r
+ <term condition="pot">bugtraq.logregex</term>\r
<listitem>\r
<para>\r
- This property activates the bug tracking system\r
+ This configuration activates the bug tracking system\r
in <emphasis>Regex</emphasis> mode.\r
It contains either a single regular expressions,\r
or two regular expressions separated by a newline.\r
you set the properties on <filename>trunk/</filename>.\r
If you can't be sure, you should set the properties recursively\r
on each sub-folder.\r
- A property setting deeper in the project hierarchy overrides settings on\r
+ A configuration setting deeper in the project hierarchy overrides settings on\r
higher levels (closer to <filename>trunk/</filename>).\r
</para>\r
<para>\r
For <literal>tsvn:</literal> properties <emphasis>only</emphasis>\r
you can use the <guilabel>Recursive</guilabel> checkbox to set\r
- the property to all sub-folders in the hierarchy, without also\r
+ the configuration to all sub-folders in the hierarchy, without also\r
setting it on all files.\r
</para>\r
</important>\r
<para>\r
This issue tracker integration is not restricted to TortoiseGit; it can be used\r
with any Git client. For more information, read the full\r
- <ulink url="http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/doc/issuetrackers.txt">\r
+ <ulink url="http://TortoiseSVN.tigris.org/svn/TortoiseSVn/trunk/doc/issuetrackers.txt">\r
<citetitle>Issue Tracker Integration Specification</citetitle>\r
</ulink>\r
in the TortoiseGit source repository.\r
program is beyond the scope of this manual. The interface definition\r
and sample programs can be obtained from the <literal>contrib</literal>\r
folder in the\r
- <ulink url="http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/contrib/issue-tracker-plugins">\r
+ <ulink url="http://TortoiseSVN.tigris.org/svn/TortoiseSVN/trunk/contrib/issue-tracker-plugins">\r
<citetitle>TortoiseGit repository</citetitle>\r
</ulink>.\r
(<xref linkend="tsvn-preface-source"/> explains how to access the repository).\r
<?xml version="1.0" encoding="UTF-8"?>\r
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
-<sect1 id="tsvn-dug-merge">\r
+<sect1 id="tsvn-dug-merge" xmlns:xi="http://www.w3.org/2001/XInclude">\r
<title>Merging</title>\r
<?dbhh topicname="HIDD_MERGEWIZARD_START"?>\r
<indexterm>\r
<para>\r
Where branches are used to maintain separate lines of development,\r
at some stage you will want to merge the changes made on one branch\r
- back into the trunk, or vice versa.\r
+ back into the other branch, or vice versa.\r
</para>\r
<para>\r
It is important to understand how branching and merging works in\r
Git before you start using it, as it can become quite complex.\r
It is highly recommended that you read the chapter\r
- <ulink url="http://svnbook.red-bean.com/en/1.5/svn.branchmerge.html">\r
- <citetitle>Branching and Merging</citetitle>\r
- </ulink>\r
+ <xref linkend="Basic_Branching_and_Mergin"/>\r
in the Git book, which gives a full description and many \r
examples of how it is used.\r
</para>\r
<guimenu>TortoiseGit</guimenu>\r
<guimenuitem>Merge...</guimenuitem>\r
</menuchoice>.\r
+ <figure id="tsvn-dug-checkout-dia-1">\r
+ <title>Merge dialog</title>\r
+ <graphic fileref="../images/Merge.png"/>\r
+ </figure>\r
</para>\r
<para>\r
In general it is a good idea to perform a merge into an unmodified\r
<emphasis>all</emphasis> changes including any you made before the merge.\r
</para>\r
<para>\r
- There are three common use cases for merging which are handled in\r
- slightly different ways, as described below.\r
- The first page of the merge wizard asks you to select the method\r
- you need.\r
+ You can choose one commit that you want to merge from. \r
+ <xi:include href="./dug_chooseversion.xml"/> \r
+ </para>\r
+ <para>\r
+ <guilabel>Squash</guilabel> Just merge change from the other branch. Can't\r
+ recorder Merge information. The new commit will not record merge branch as\r
+ one parent commit. Log view will not show merge line between two branch. \r
+ </para>\r
+ <para>\r
+ <guilabel>No Fast Forward</guilabel> Generate a merge commit even if the\r
+ merge resolved as a fast-forward.\r
+ </para>\r
+ <para>\r
+ You can see more information at <xref linkend="git-merge(1)"/>\r
+ </para>\r
+ <para>\r
+ Although major merge working is done by git automatically, conflict maybe happen during merge, \r
+ please see <xref linked="tsvn-dug-conflicts"/> to how to resolve conflict.\r
</para>\r
- <variablelist>\r
- <varlistentry>\r
- <term>Merge a range of revisions</term>\r
- <listitem>\r
- <para>\r
- This method covers the case when you have made one or more\r
- revisions to a branch (or to the trunk) and you want to port\r
- those changes across to a different branch.\r
- </para>\r
- <para>\r
- What you are asking Git to do is this:\r
- <quote>Calculate the changes necessary to get [FROM] revision 1\r
- of branch A [TO] revision 7 of branch A, and apply those changes\r
- to my working copy (of trunk or branch B).</quote>\r
- </para>\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry>\r
- <term>Reintegrate a branch</term>\r
- <listitem>\r
- <para>\r
- This method covers the case when you have made a feature branch\r
- as discussed in the Git book. All trunk changes have been\r
- ported to the feature branch, week by week, and now the feature\r
- is complete you want to merge it back into the trunk. Because\r
- you have kept the feature branch synchronized with the trunk,\r
- the latest versions of branch and trunk will be absolutely\r
- identical except for your branch changes.\r
- </para>\r
- <para>\r
- This is a special case of the tree merge described below,\r
- and it requires only the URL to merge from (normally) your\r
- development branch. It uses the merge-tracking features of\r
- Git to calculate the correct revision ranges to use,\r
- and perform additional checks which ensure that the branch has\r
- been fully updated with trunk changes. This ensures that you don't\r
- accidentally undo work that others have committed to trunk since\r
- you last synchronized changes.\r
- </para>\r
- <para>\r
- After the merge, all branch development has been completely\r
- merged back into the main development line. The branch is now\r
- redundant and can be deleted.\r
- </para>\r
- <para>\r
- Once you have performed a reintegrate merge you should not\r
- continue to use it for development. The reason for this is that\r
- if you try to resynchronize your existing branch from trunk later on,\r
- merge tracking will see your reintegration as a trunk change\r
- that has not yet been merged into the branch, and will try to\r
- merge the branch-to-trunk merge back into the branch!\r
- The solution to this is simply to create a new branch from trunk\r
- to continue the next phase of your development.\r
- </para>\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry>\r
- <term>Merge two different trees</term>\r
- <listitem>\r
- <para>\r
- This is a more general case of the reintegrate method.\r
- What you are asking Git to do is:\r
- <quote>Calculate the changes necessary to get [FROM] the head\r
- revision of the trunk [TO] the head revision of the branch, and\r
- apply those changes to my working copy (of the trunk).</quote>\r
- The net result is that trunk now looks exactly like the branch.\r
- </para>\r
- <para>\r
- If your server/repository does not support merge-tracking\r
- then this is the only way to merge a branch back to trunk.\r
- Another use case occurs when you are using vendor branches\r
- and you need to merge the changes following a new vendor drop\r
- into your trunk code. For more information read the chapter on\r
- <ulink url="http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html">\r
- <citetitle>vendor branches</citetitle>\r
- </ulink>\r
- in the Git Book.\r
- </para>\r
- </listitem>\r
- </varlistentry>\r
- </variablelist>\r
- <sect2 id="tsvn-dug-merge-range">\r
- <title>Merging a Range of Revisions</title>\r
- <?dbhh topicname="HIDD_MERGEWIZARD_REVRANGE"?>\r
- <indexterm>\r
- <primary>merge</primary>\r
- <secondary>revision range</secondary>\r
- </indexterm>\r
- <para>\r
- <figure id="tsvn-dug-merge-wizard-range">\r
- <title>The Merge Wizard - Select Revision Range</title>\r
- <graphic fileref="../images/MergeWizardRange.png"/>\r
- </figure>\r
- In the <guilabel>From:</guilabel> field enter the full\r
- folder URL of the branch or tag containing the changes\r
- you want to port into your working copy.\r
- You may also click\r
- <guibutton>...</guibutton>\r
- to browse the repository and find the desired branch.\r
- If you have merged from this branch before, then just\r
- use the drop down list which shows a history of\r
- previously used URLs.\r
- </para>\r
- <para>\r
- In the <guilabel>Revision range to merge</guilabel> field\r
- enter the list of revisions you want to merge. This can\r
- be a single revision, a list of specific revisions\r
- separated by commas, or a range of revisions separated by a\r
- dash, or any combination of these.\r
- </para>\r
- <important>\r
- <para>\r
- There is an important difference in the way a revision\r
- range is specified with TortoiseGit compared to the\r
- command line client. The easiest way to visualise it is\r
- to think of a fence with posts and fence panels.\r
- </para>\r
- <para>\r
- With the command line client you specify the changes\r
- to merge using two <quote>fence post</quote> revisions\r
- which specify the <emphasis>before</emphasis> and\r
- <emphasis>after</emphasis> points.\r
- </para>\r
- <para>\r
- With TortoiseGit you specify the changeset to merge\r
- using <quote>fence panels</quote>. The reason for this\r
- becomes clear when you use the log dialog to specify\r
- revisions to merge, where each revision appears as\r
- a changeset.\r
- </para>\r
- <para>\r
- If you are merging revisions in chunks, the method\r
- shown in the Git book will have you merge\r
- 100-200 this time and 200-300 next time. With\r
- TortoiseGit you would merge 100-200 this time and\r
- 201-300 next time.\r
- </para>\r
- <para>\r
- This difference has generated a lot of heat on the\r
- mailing lists. We acknowledge that there is a difference\r
- from the command line client, but we believe that for the\r
- majority of GUI users it is easier to understand the\r
- method we have implemented.\r
- </para>\r
- </important>\r
- <para>\r
- The easiest way to select the range of revisions you need\r
- is to click on <guibutton>Show Log</guibutton>, as this\r
- will list recent changes with their log comments.\r
- If you want to merge the changes from a single revision, just\r
- select that revision. If you want to merge changes from several\r
- revisions, then select that range\r
- (using the usual <keycap>Shift</keycap>-modifier).\r
- Click on <guibutton>OK</guibutton> and the list of revision\r
- numbers to merge will be filled in for you.\r
- </para>\r
- <para>\r
- If you want to merge changes back <emphasis>out</emphasis>\r
- of your working copy, to revert a change which has already\r
- been committed, select the revisions to revert and make sure\r
- the <guilabel>Reverse merge</guilabel> box is checked.\r
- </para>\r
- <para>\r
- If you have already merged some changes from this branch,\r
- hopefully you will have made a note of the last revision\r
- merged in the log message when you committed the change.\r
- In that case, you can use <guibutton>Show Log</guibutton>\r
- for the Working Copy to trace that log message.\r
- Remembering that we are thinking of revisions as\r
- changesets, you should Use the revision after the\r
- end point of the last merge as the start point for this\r
- merge. For example, if you have merged revisions 37 to 39\r
- last time, then the start point for this merge should be\r
- revision 40.\r
- </para>\r
- <para>\r
- If you are using the merge tracking features of Git,\r
- you do not need to remember which revisions have already been\r
- merged - Git will record that for you. If you leave\r
- the revision range blank, all revisions which have not yet\r
- been merged will be included. Read\r
- <xref linkend="tsvn-dug-merge-tracking"/> to find out more.\r
- </para>\r
- <para>\r
- If other people may be committing changes then be careful\r
- about using the HEAD revision. It may not refer to the\r
- revision you think it does if someone else made a commit\r
- after your last update.\r
- </para>\r
- <para>\r
- Click <guibutton>Next</guibutton> and go to\r
- <xref linkend="tsvn-dug-merge-options"/>\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-reintegrate">\r
- <title>Reintegrate a branch</title>\r
- <?dbhh topicname="HIDD_MERGEWIZARD_REINTEGRATE"?>\r
- <indexterm>\r
- <primary>merge</primary>\r
- <secondary>reintegrate</secondary>\r
- </indexterm>\r
- <para>\r
- <figure id="tsvn-dug-merge-wizard-reintegrate">\r
- <title>The Merge Wizard - Reintegrate Merge</title>\r
- <graphic fileref="../images/MergeWizardReintegrate.png"/>\r
- </figure>\r
- To merge a feature branch back into the trunk you must start the\r
- merge wizard from within a working copy of the trunk.\r
- </para>\r
- <para>\r
- In the <guilabel>From URL:</guilabel> field enter the full\r
- folder URL of the branch that you want to merge back.\r
- You may also click\r
- <guibutton>...</guibutton>\r
- to browse the repository.\r
- </para>\r
- <para>\r
- There are some conditions which apply to a reintegrate merge.\r
- Firstly, the server must support merge tracking.\r
- The working copy must be of depth infinite (no sparse checkouts),\r
- and it must not have any local modifications, switched items or\r
- items that have been updated to revisions other than HEAD.\r
- All changes to trunk made during branch development must have\r
- been merged across to the branch (or marked as having been merged).\r
- The range of revisions to merge will be calculated automatically.\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-tree">\r
- <title>Merging Two Different Trees</title>\r
- <?dbhh topicname="HIDD_MERGEWIZARD_TREE"?>\r
- <indexterm>\r
- <primary>merge</primary>\r
- <secondary>two trees</secondary>\r
- </indexterm>\r
- <para>\r
- <figure id="tsvn-dug-merge-wizard-trees">\r
- <title>The Merge Wizard - Tree Merge</title>\r
- <graphic fileref="../images/MergeWizardTree.png"/>\r
- </figure>\r
- If you are using this method to merge a feature branch back to trunk,\r
- you need to start the merge wizard from within a working copy of trunk.\r
- </para>\r
- <para>\r
- In the <guilabel>From:</guilabel> field enter the full\r
- folder URL of the <emphasis>trunk</emphasis>. This\r
- may sound wrong, but remember that the trunk is the\r
- start point to which you want to add the branch changes.\r
- You may also click\r
- <guibutton>...</guibutton>\r
- to browse the repository.\r
- </para>\r
- <para>\r
- In the <guilabel>To:</guilabel> field enter the full\r
- folder URL of the feature branch.\r
- </para>\r
- <para>\r
- In both the <guilabel>From Revision</guilabel> field and\r
- the <guilabel>To Revision</guilabel> field, enter the\r
- last revision number at which the two trees were\r
- synchronized. If you are sure no-one else is making\r
- commits you can use the HEAD revision in both cases.\r
- If there is a chance that someone else may have made\r
- a commit since that synchronization, use the specific\r
- revision number to avoid losing more recent commits.\r
- </para>\r
- <para>\r
- You can also use <guibutton>Show Log</guibutton> to\r
- select the revision.\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-options">\r
- <title>Merge Options</title>\r
- <?dbhh topicname="HIDD_MERGEWIZARD_OPTIONS"?>\r
- <para>\r
- This page of the wizard lets you specify advanced options,\r
- before starting the merge process.\r
- Most of the time you can just use the default settings.\r
- </para>\r
- <para>\r
- You can specify the depth to use for the merge, i.e. how far down\r
- into your working copy the merge should go. The depth terms used\r
- are described in <xref linkend="tsvn-dug-checkout-depth"/>. The\r
- default depth is <guilabel>Working copy</guilabel>, which uses\r
- the existing depth setting, and is almost always what you want.\r
- </para>\r
- <para>\r
- Most of the time you want merge to take account of the file's history,\r
- so that changes relative to a common ancestor are merged. Sometimes\r
- you may need to merge files which are perhaps related, but not in\r
- your repository. For example you may have imported versions 1 and 2 of\r
- a third party library into two separate directories. Although they\r
- are logically related, Git has no knowledge of this because\r
- it only sees the tarballs you imported. If you attempt to merge the\r
- difference between these two trees you would see a complete removal\r
- followed by a complete add. To make Git use only path-based\r
- differences rather than history-based differences, check the\r
- <guilabel>Ignore ancestry</guilabel> box. Read more about this \r
- topic in the Git book,\r
- <ulink url="http://svnbook.red-bean.com/en/1.5/svn.branchmerge.advanced.html#svn.branchmerge.advanced.ancestry">\r
- <citetitle>Noticing or Ignoring Ancestry</citetitle>\r
- </ulink>\r
- </para>\r
- <para>\r
- You can specify the way that line ending and whitespace changes are handled.\r
- These options are described in <xref linkend="tsvn-dug-diff-eol-whitespace"/>.\r
- The default behaviour is to treat all whitespace and line-end differences\r
- as real changes to be merged.\r
- </para>\r
- <para>\r
- If you are using merge tracking and you want to mark a revision as\r
- having been merged, without actually doing the merge here, check the\r
- <guilabel>Only record the merge</guilabel> checkbox. There are two\r
- possible reasons you might want to do this. It may be that the merge\r
- is too complicated for the merge algorithms, so you code the changes\r
- by hand, then mark the change as merged so that the merge tracking\r
- algorithm is aware of it. Or you might want to prevent a particular\r
- revision from being merged. Marking it as already merged will prevent\r
- the merge occurring with merge-tracking-aware clients.\r
- </para>\r
- <para>\r
- Now everything is set up, all you have to do is click on the\r
- <guibutton>Merge</guibutton> button. If you want to preview the results\r
- <guibutton>Test Merge</guibutton> performs the merge operation, but does\r
- <emphasis>not</emphasis> modify the working copy at all.\r
- It shows you a list of the files that will be changed\r
- by a real merge, and notes those areas where conflicts will occur.\r
- </para>\r
- <para>\r
- The merge progress dialog shows each stage of the merge, with the\r
- revision ranges involved. This may indicate one more revision than\r
- you were expecting. For example if you asked to merge revision 123\r
- the progress dialog will report <quote>Merging revisions 122 through\r
- 123</quote>. To understand this you need to remember that Merge is\r
- closely related to Diff. The merge process works by generating a list\r
- of differences between two points in the repository, and applying\r
- those differences to your working copy. The progress dialog is simply\r
- showing the start and end points for the diff.\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-review">\r
- <title>Reviewing the Merge Results</title>\r
- <para>\r
- The merge is now complete. It's a good idea to have a look at the\r
- merge and see if it's as expected. Merging is usually quite complicated.\r
- Conflicts often arise if the branch has drifted far from the trunk.\r
- </para>\r
- <para>\r
- For Git clients and servers prior to 1.5, no merge information\r
- is stored and merged revisions have to be tracked manually. \r
- When you have tested the changes and come to commit this revision,\r
- your commit log message should <emphasis>always</emphasis>\r
- include the revision numbers which have been ported in the merge.\r
- If you want to apply another merge at a later time you will need to\r
- know what you have already merged, as you do not want to port a\r
- change more than once. For more information about this, refer to\r
- <!-- NOTE this reference to the 1.4 book is deliberate. This is the\r
- pre-mergetracking stuff which is not covered in version 1.5\r
- -->\r
- <ulink url="http://svnbook.red-bean.com/en/1.4/svn.branchmerge.copychanges.html#svn.branchmerge.copychanges.bestprac">\r
- <citetitle>Best Practices for Merging</citetitle>\r
- </ulink>\r
- in the Git book.\r
- </para>\r
- <para>\r
- If your server and all clients are running Git 1.5 or higher,\r
- the merge tracking facility will record the revisions merged and avoid\r
- a revision being merged more than once. This makes your life much simpler\r
- as you can simply merge the entire revision range each time and know\r
- that only new revisions will actually be merged.\r
- </para>\r
- <para>\r
- Branch management is important. If you want to keep this branch up to\r
- date with the trunk, you should be sure to merge often so that the\r
- branch and trunk do not drift too far apart. Of course, you\r
- should still avoid repeated merging of changes, as explained above.\r
- </para>\r
- <tip>\r
- <para>\r
- If you have just merged a feature branch back into the trunk,\r
- the trunk now contains all the new feature code, and the\r
- branch is obsolete. You can now delete it from the repository\r
- if required.\r
- </para>\r
- </tip>\r
- <important>\r
- <para>\r
- Git can't merge a file with a folder and vice versa - only\r
- folders to folders and files to files. If you click on a file and\r
- open up the merge dialog, then you have to give a path to a file\r
- in that dialog. If you select a folder and bring up the dialog,\r
- then you must specify a folder URL for the merge.\r
- </para>\r
- </important>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-tracking">\r
- <title>Merge Tracking</title>\r
- <indexterm>\r
- <primary>merge tracking</primary>\r
- </indexterm>\r
- <para>\r
- Git 1.5 introduced facilities for merge tracking. When you\r
- merge changes from one tree into another, the revision numbers merged are\r
- stored and this information can be used for several different purposes.\r
- <itemizedlist>\r
- <listitem>\r
- <para>\r
- You can avoid the danger of merging the same revision twice\r
- (repeated merge problem). Once a revision is marked as having\r
- been merged, future merges which include that revision in the\r
- range will skip over it.\r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>\r
- When you merge a branch back into trunk, the log dialog\r
- can show you the branch commits as part of the trunk\r
- log, giving better traceability of changes.\r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>\r
- When you show the log dialog from within the merge dialog,\r
- revisions already merged are shown in grey.\r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>\r
- When showing blame information for a file, you can choose\r
- to show the original author of merged revisions, rather than\r
- the person who did the merge.\r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>\r
- You can mark revisions as <emphasis>do not merge</emphasis>\r
- by including them in the list of merged revisions without\r
- actually doing the merge.\r
- </para>\r
- </listitem>\r
- </itemizedlist>\r
- </para>\r
- <para>\r
- Merge tracking information is stored in the <literal>svn:mergeinfo</literal>\r
- property by the client when it performs a merge. When the merge is committed\r
- the server stores that information in a database, and when you request merge,\r
- log or blame information, the server can respond appropriately. For the system\r
- to work properly you must ensure that the server, the repository and all clients\r
- are upgraded.\r
- Earlier clients will not store the <literal>svn:mergeinfo</literal> property\r
- and earlier servers will not provide the information requested by new clients.\r
- </para>\r
- <para>\r
- Find out more about merge tracking from Git's\r
- <ulink url="http://Git.tigris.org/merge-tracking/index.html">\r
- <citetitle>Merge tracking documentation</citetitle>\r
- </ulink>.\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-conflict-callback">\r
- <title>Handling Conflicts during Merge</title>\r
- <?dbhh topicname="HIDD_CONFLICTRESOLVE"?>\r
- <indexterm>\r
- <primary>merge conflicts</primary>\r
- </indexterm>\r
- <para>\r
- Merging does not always go smoothly. Sometimes there is a\r
- conflict, and if you are merging multiple ranges, you generally\r
- want to resolve the conflict before merging of the next range\r
- starts. TortoiseGit helps you through this process by showing\r
- the <emphasis>merge conflict callback</emphasis> dialog.\r
- <figure id="tsvn-dug-merge-callback-dia">\r
- <title>The Merge Conflict Callback Dialog</title>\r
- <graphic fileref="../images/MergeConflictCallback.png"/>\r
- </figure>\r
- </para>\r
- <para>\r
- When a conflict occurs during the merge, you have three ways to\r
- handle it.\r
- <orderedlist>\r
- <listitem>\r
- <para>\r
- You may decide that your local changes are much more\r
- important, so you want to discard the version from the\r
- repository and keep your local version. Or you might\r
- discard your local changes in favour of the repository\r
- version. Either way, no attempt is made to merge the\r
- changes - you choose one or the other.\r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>\r
- Normally you will want to look at the conflicts and resolve\r
- them. In that case, choose the <guibutton>Edit Conflict</guibutton>\r
- which will start up your merge tool. When you are satisfied with\r
- the result, click <guibutton>Resolved</guibutton>.\r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>\r
- The last option is to postpone resolution and continue\r
- with merging. You can choose to do that for the current\r
- conflicted file, or for all files in the rest of the merge.\r
- However, if there are further changes in that file, it\r
- will not be possible to complete the merge.\r
- </para>\r
- </listitem>\r
- </orderedlist>\r
- </para>\r
- <para>\r
- If you do not want to use this interactive callback, there is a\r
- checkbox in the merge progress dialog <guilabel>Merge non-interactive</guilabel>.\r
- If this is set for a merge and the merge would result in a conflict,\r
- the file is marked as in conflict and the merge goes on. You will have\r
- to resolve the conflicts after the whole merge is finished.\r
- If it is not set, then before a file is marked as conflicted you get the\r
- chance to resolve the conflict <emphasis>during</emphasis> the merge.\r
- This has the advantage that if a file gets multiple merges (multiple\r
- revisions apply a change to that file), subsequent merges might succeed\r
- depending on which lines are affected. But of course you can't walk away\r
- to get a coffee while the merge is running ;)\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-all">\r
- <title>Merge a Completed Branch</title>\r
- <?dbhh topicname="HIDD_MERGEALL"?>\r
- <indexterm>\r
- <primary>merge reintegrate</primary>\r
- </indexterm>\r
- <para>\r
- If you want to merge all changes from a feature branch\r
- back to trunk, then you can use the\r
- <menuchoice>\r
- <guimenu>TortoiseGit</guimenu>\r
- <guimenuitem>Merge reintegrate...</guimenuitem>\r
- </menuchoice>\r
- from the extended context menu (hold down the <keycap>Shift</keycap>\r
- key while you right click on the file).\r
- <figure id="tsvn-dug-mergeall-dia-1">\r
- <title>The Merge reintegrate Dialog</title>\r
- <graphic fileref="../images/MergeAll.png"/>\r
- </figure>\r
- This dialog is very easy. All you have to do is set the options for\r
- the merge, as described in <xref linkend="tsvn-dug-merge-options"/>.\r
- The rest is done by TortoiseGit automatically using merge tracking.\r
- </para>\r
- </sect2>\r
- <sect2 id="tsvn-dug-merge-maintenance">\r
- <title>Feature Branch Maintenance</title>\r
- <para>\r
- When you develop a new feature on a separate branch it is a good\r
- idea to work out a policy for re-integration when the feature is\r
- complete. If other work is going on in <literal>trunk</literal>\r
- at the same time you may find that the differences become significant\r
- over time, and merging back becomes a nightmare.\r
- </para>\r
- <para>\r
- If the feature is relatively simple and development will not take\r
- long then you can adopt a simple approach, which is to keep\r
- the branch entirely separate until the feature is complete,\r
- then merge the branch changes back into trunk. In the merge wizard\r
- this would be a simple <guilabel>Merge a range of revisions</guilabel>,\r
- with the revision range being the revision span of the branch.\r
- </para>\r
- <para>\r
- If the feature is going to take longer and you need to account\r
- for changes in <literal>trunk</literal>, then you need to keep\r
- the branch synchronised. This simply means that periodically\r
- you merge trunk changes into the branch, so that the branch\r
- contains all the trunk changes <emphasis>plus</emphasis> the\r
- new feature. The synchronisation process uses\r
- <guilabel>Merge a range of revisions</guilabel>. When the feature\r
- is complete then you can merge it back to <literal>trunk</literal>\r
- using either <guilabel>Reintegrate a branch</guilabel> or\r
- <guilabel>Merge two different trees</guilabel>.\r
- </para>\r
- </sect2>\r
</sect1>\r