<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-patch">
	<title>Creating and Applying Patches and Pull Requests</title>
	<indexterm>
		<primary>patch</primary>
	</indexterm>
	<indexterm>
		<primary>diff</primary>
	</indexterm>
	<indexterm>
		<primary>unified diff</primary>
	</indexterm>
	<indexterm>
		<primary>pull request</primary>
	</indexterm>
	<indexterm>
		<primary>request pull</primary>
	</indexterm>
	<?dbhh topicname="HIDD_FORMAT_PATCH"?>
	<?dbhh topicname="HIDD_APPLY_PATCH_LIST"?>
	<?dbhh topicname="HIDD_REQUESTPULL"?>
	<?dbhh topicname="HIDD_SENDMAIL"?>
	<para>
		For open source projects (like this one) everyone has read
		access to the (main/public) repository, and anyone can make a contribution
		to the project. So how are those contributions controlled?
		If just anyone could commit changes to this central repository, the project would be permanently
		unstable and probably permanently broken. In this situation the
		change is managed by submitting a <firstterm>patch</firstterm> file or a <firstterm>pull request</firstterm>
		to the development team, who do have write access.
		They can review the changes first, and then either submit it to the
		main repository or reject it back to the author.
	</para>
	<para>
		Patch files are simply Unified-Diff files showing the differences
		between your working tree and the base revision.
	</para>
	<para>
		A pull request is an request to another repository owner to <link linkend="tgit-dug-pull">pull</link>
		changes from your repository. I.e. you must have access to a public repository where you can
		<link linkend="tgit-dug-push">push</link> your changes (normally a special branch).
	</para>
	<sect2 id="tgit-dug-patch-createpatchserial">
		<title>Creating a Patch Serial</title>
		<para>
			First you need to make <emphasis>and test</emphasis> your changes.
			Then you commit your changes via
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Commit...</guimenuitem>
			</menuchoice>
			on the parent folder, enter a good commit message. After that select
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Create Patch Serial...</guimenuitem>
			</menuchoice>
			and choose the correct options to include your changes/commits.
		</para>
		<figure id="tgit-dug-patch-dia-1">
			<title>The Create Patch dialog</title>
			<graphic fileref="../images/CreatePatch.png"/>
		</figure>
		<para>
			<guilabel>Directory</guilabel> is output directory of patch.
			Patch file name will be created by commit subject.
		</para>
		<para>
			<guilabel>Since</guilabel> create patch from point. You can click
			<guibutton>...</guibutton> to launch reference browser dialog to choose branch or tag (cf. <xref linkend="tgit-dug-browse-ref"/>).
		</para>
		<para>
			<guilabel>Number Commits</guilabel> is limited how much patch will created.
		</para>
		<para>
			<guilabel>Range</guilabel> is choose range of <guilabel>from</guilabel> commit
			to <guilabel>to</guilabel>. You can click <guibutton>...</guibutton> to launch
			log dialog to choose commit.
		</para>
		<para>
			<guilabel>Send Mail after create</guilabel> launch send mail dialog after patches created (see <xref linkend="tgit-dug-patch-sendpatches"/>).
		</para>
		<para>
			You can find more information at <gitdoclink cmd="git-format-patch" section="1"/>.
		</para>
		<important>
			<para>
				Here Git is different to TortoiseSVN: In TortoiseSVN you directly create a patch instead of committing
				your changes and create a patch of the commits afterwards (in git you have a full local copy/fork of the project you cloned - commits are just local).
				To generate a patch containing the uncommitted,
				but staged, changes click on <guibutton>Save unified diff since HEAD</guibutton>.
			<para>
			</para>
				For hints where to find more information about doing version control with Git see <xref linkend="tgit-preface-readingguide"/>.
			</para>
		</important>
	</sect2>
	<sect2 id="tgit-dug-patch-sendpatches">
		<title>Sending patches by mail</title>
		<para>
			In order to send patches to the upstream authors, select the patch files and then right click on them and select
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Send Mail...</guimenuitem>
			</menuchoice>
		</para>
		<para>
			<figure id="tgit-dug-patch-dia-sendpatches">
				<title>The Send Patches Dialog</title>
				<graphic fileref="../images/SendPatch.png"/>
			</figure>
		</para>
		<para>
			First you need to enter the recipient(s) (<guilabel>To</guilabel> and/or <guilabel>CC</guilabel>).
		</para>
		<para>
			Depending on the mail type (<guilabel>Patch as attachment</guilabel> or <guilabel>Combine One Mail</guilabel>)
			you have to enter a <guilabel>Subject</guilabel> for the mail.
		</para>
		<para>
			<guilabel>Patch as attachment</guilabel> adds the patch(es) as attachment(s) to the mail(s) instead of inlining them.
		</para>
		<para>
			<guilabel>Combine One Mail</guilabel> adds all patches to one mail. You have to enter a <guilabel>Subject</guilabel>
			for the mail in this case.
		</para>
	</sect2>
	<sect2 id="tgit-dug-patch-applysinglepatch">
		<title>Applying a single Patch File</title>
		<para>
			Patch files are applied to your working tree. This should be done
			from the same folder level as was used to create the patch.
			If you are not sure what this is, just look at the first line of
			the patch file. For example, if the first file being worked on was
			<filename>doc/source/english/chapter1.xml</filename>
			and the first line in the patch file is
			<filename>Index: english/chapter1.xml</filename>
			then you need to apply the patch to the
			<filename>doc/source/</filename> folder.
			However, provided you are in the correct working tree, if you
			pick the wrong folder level, TortoiseGit will notice and suggest the
			correct level.
		</para>
		<para>
			From the context menu for a patch file (<filename>.patch</filename>
			or <filename>.diff</filename> extension), click on
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Review/apply single patch...</guimenuitem>
			</menuchoice>
			You might be prompted to enter a working tree location:
			<figure id="tgit-dug-choose-repository">
				<title>The Choose Repository Dialog</title>
				<graphic fileref="../images/ChooseRepository.png"/>
			</figure>
			If the working tree is found, TortoiseGitMerge is launched to show and apply differences.
		</para>
	</sect2>
	<sect2 id="tgit-dug-patch-applaypatchserial">
		<title>Applying a Patch Serial</title>
		<para>
			Patch files are applied to your working tree. For this copy the patch (or mbox)
			files to the root of your working tree.
		</para>
		<para>
			From the context menu for that folder (or all marked patch files), click on
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Apply Patch Serial...</guimenuitem>
			</menuchoice>
			<figure id="tgit-dug-apply-patch">
				<title>The Apply Patch Dialog</title>
				<graphic fileref="../images/ApplyPatch.png"/>
			</figure>
		</para>

		<para>
			<guibutton>Add</guibutton> Insert patch
		</para>
		<para>
			<guibutton>Up</guibutton> Move chosen patch up.
		</para>
		<para>
			<guibutton>Down</guibutton> Move chosen patch down.
		</para>
		<para>
			<guibutton>Remove</guibutton> Remove the chosen patch.
		</para>
		<para>
			<guibutton>Apply</guibutton> Start applying the patches one by one.
		</para>
		<para>
			You can find more information at <gitdoclink cmd="git-am" section="1"/>.
		</para>
	</sect2>
	<sect2 id="tgit-dug-patch-pullrequest">
		<title>Creating a pull request</title>
		<para>
			Apart from sending patches (or patch serials) to other developers,
			there are two ways to ask other people to integrate your changes
			into their repositories.
		</para>
		<para>
			<emphasis>First:</emphasis> After pushing your changes to a (public)
			repository, you just provide other people the URL of your repository
			and the name of the branch or the revision id.
			E.g.: <literal>git://example.com/repo.git BRANCHNAME</literal>
		</para>
		<para>
			<emphasis>Second:</emphasis> After pushing your changes to a (public)
			repository, you can create a standardized (quite formal) request for other
			people to pull your changes and integrate them into their repository.
			The format pull request consists of a list of all commits and provides
			some statistics about changed files, so that other people can get a quick overview.
		</para>
		<para>
			Select <guibutton>Request pull</guibutton> on the progress dialog after pushing your changes.
			<figure id="tgit-dug-request-pull">
				<title>The Request Pull Dialog</title>
				<graphic fileref="../images/RequestPull.png"/>
			</figure>
		</para>
		<variablelist>
			<varlistentry>
				<term><guilabel>Start</guilabel></term>
				<listitem>
					<para>
						This should be the revision on which your changes are based on.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><guilabel>URL</guilabel></term>
				<listitem>
					<para>
						The public URL to your repository, which can be access
						by the people who shall pull your changes.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><guilabel>End</guilabel></term>
				<listitem>
					<para>
						This should be the branch name or revision id of the end of your commits.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
		<para>
			After clicking on <guibutton>OK</guibutton> the pull request is created. Just copy it
			and pass it to other people who you want to pull your changes.
		</para>
		<para>
			You can find more information at <gitdoclink cmd="git-request-pull" section="1"/>.
		</para>
	</sect2>
</sect1>
