<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-conflicts">
	<?dbhh topicname="HIDD_RESOLVE"?>
	<title>Resolving Conflicts</title>
	<indexterm>
		<primary>conflict</primary>
	</indexterm>
	<indexterm>
		<primary>resolve</primary>
	</indexterm>
	<para>
		During a merge, the working tree files are updated to reflect the result of the merge.
		Once in a while, you will get a <emphasis>conflict</emphasis> when
		you merge another branch, cherry-pick commits, rebase or apply a stash:
		Among the changes made to the common ancestor's version, non-overlapping ones (that is, you changed an area of the file while the other side left that area intact, or vice versa) are incorporated in the final result verbatim. When both sides made changes to the same area, however, Git cannot randomly pick one side over the other, and asks you to resolve it by leaving what both sides did to that area.
		Whenever a conflict is reported you need to resolve it!
	</para>
	<para>
		The conflicting area is marked in the file like this (also cf. <gitdoclink cmd="git-merge" section="1" anchor="_how_conflicts_are_presented"/>):
<screen>
&lt;&lt;&lt;&lt;&lt;&lt;&lt; yours
    your changes
=======
    changes from the code merged
&gt;&gt;&gt;&gt;&gt;&gt;&gt; their
</screen>
	</para>
	<para>
		You can use any editor to manually resolve the conflict or
		you can launch an external merge tool/conflict
		editor with
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Edit Conflicts</guimenuitem>
		</menuchoice>.
		Then TortoiseGit will place three additional files in your directory for the selected conflicted file and launch the configured conflict editor:
		<variablelist>
			<varlistentry>
				<term>filename.ext.BASE.ext</term>
				<listitem>
					<para>
						This is the common ancestor's version of the conflicted file (this version does contain neither any of your nor any of the changes of the to be merged branch/revision, especially it does not contain any conflict markers).
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>filename.ext.LOCAL.ext</term>
				<listitem>
					<para>
						This is your file as it existed in your
						working tree before you started the merge (i.e., the file conforms to the latest committed state of the HEAD of your local repository)
						- that is, without conflict markers.
						Therefore, this state/version is often also called "mine".
					</para>
					<para>
						Just for completeness "mine" means for "stash"/"merge"/"pull"/"cherry-pick" the HEAD version in your working tree and for "rebase" the version on the branch you rebase.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>filename.ext.REMOTE.ext</term>
				<listitem>
					<para>
						This is the version of file of the revision you want to merge (on a normal merge this correspondents to MERGE_HEAD).
						As you want to merge other changes, this state/version is often also called "theirs".
					</para>
					<para>
						Just for completeness "theirs" means for "stash"/"merge"/"pull"/"cherry-pick" the version of the to be merged commit/branch and for "rebase" the version of the branch you rebase onto.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</para>
	<para>
		Afterwards execute the command
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Resolved</guimenuitem>
		</menuchoice>
		and commit your modifications to the repository (if the conflict occurred while rebasing or cherry-picking make sure you use the cherry-pick resp. rebase dialog for committing and not the normal commit dialog!).
		Please note that the Resolve command does not really
		resolve the conflict.
		It uses "git add" to mark file status as resolved
		to allow you to commit your changes
		and it removes the
		<filename>filename.ext.BASE.ext</filename>,
		<filename>filename.ext.LOCAL.ext</filename> and
		<filename>filename.ext.REMOTE.ext</filename> files.
	</para>
	<para>
		If you have conflicts with binary files, Git does
		not attempt to merge the files itself. The local file remains
		unchanged (exactly as you last changed it).
		In order to resolve the conflict use
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Resolve...</guimenuitem>
		</menuchoice>
		and then right click on the conflicted file and choose one of <guimenuitem>Resolved</guimenuitem> (the current version of the file which is in the working tree will be used), <guimenuitem>Resolve conflict using 'mine'</guimenuitem> (the version of the file of your HEAD will be used), and <guimenuitem>Resolve conflict using 'theirs'</guimenuitem> (the version of the file of the merged revision/branch will be used). After that commit.
	</para>
	<para>
		You can use the <guimenuitem>Resolved</guimenuitem> command for multiple files
		if you right click on the parent folder and select
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Resolve...</guimenuitem>
		</menuchoice>
		This will bring up a dialog listing all conflicted files
		in that folder, and you can select which ones to mark
		as resolved.
		<figure id="tgit-dug-conflicts-dia-1">
			<title>The resolve conflicts dialog</title>
			<graphic fileref="../images/ResolveConflict.png"/>
		</figure>
	</para>
	<important>
		<para>
			Git (unlike SVN) does not automatically create <filename>filename.ext.BASE.ext</filename>, <filename>filename.ext.LOCAL.ext</filename> and <filename>filename.ext.REMOTE.ext</filename> files for conflicted files. These are only created on-demand by TortoiseGit when you use the command <guimenuitem>Edit Conflicts</guimenuitem>.
		</para>
	</important>
	<important>
		<para>
			In Git (unlike SVN) you have to <link linkend="tgit-dug-commit">commit</link> after resolving conflicts. However, if the conflict occurred while rebasing or cherry-picking make sure you use the cherry-pick resp. rebase dialog for committing and not the normal commit dialog!
		</para>
	</important>
	<sect2 id="tgit-dug-conflicts-special">
		<title>Special conflict cases</title>
		<sect3 id="tgit-dug-conflicts-special-delete-modify">
			<title>Delete-modify conflicts</title>
			<?dbhh topicname="HIDD_RESOLVE_CONFLICT"?>
			<para>
				A special conflict case is a delete-modify conflict. Here, a file is deleted on one branch and the same file is modified on another branch.
				In order to resolve this conflict the user has to decide whether to keep the modified version or delete the file from the working tree.
			</para>
			<para>
				<figure id="tgit-dug-conflicts-special-delete-modify-dialog">
					<title>Resolve delete-modify conflict Dialog</title>
					<graphic fileref="../images/resolve-delete-modify-conflict.png"/>
				</figure>
			</para>
		</sect3>
		<sect3 id="tgit-dug-conflicts-special-submodule">
			<title>Submodule conflicts</title>
			<?dbhh topicname="HIDD_RESOLVESUBMODULECONFLICT"?>
			<para>
				Another special conflict case is a conflict involving a submodule. Here, a submodule is changed in different (conflicting) ways on two branches.
			</para>
			<para>
				The resolve submodule conflict dialog shows the base, the local and the remote commit of the conflicting submodule as well as the commit type (rewind, fast-forward, ...).
				<figure id="tgit-dug-conflicts-special-submodule-dialog">
					<title>Resolve submodule conflict Dialog</title>
					<graphic fileref="../images/resolve-submodule-conflict.png"/>
				</figure>
			</para>
			<important>
				<title>Uninitialized submodules</title>
				<para>
					If the submodule is not yet initialized the resolve submodule conflict dialog only shows the commit IDs (SHA-1). Also, the conflict cannot be resolved automatically:
					First, you have to manually clone the submodule into the right folder. Then, you can resolve the conflict using TortoiseGit or git (by checking out the right commit in the submodule and committing the parent working tree).
				</para>
			</important>
		</sect3>
	</sect2>
</sect1>
