2.32. Creating and Applying Patches and Pull Requests

TortoiseGit

2.32. Creating and Applying Patches and Pull Requests

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 this this central repository, the project would be permanently unstable and probably permanently broken. In this situation the change is managed by submitting a patch file or a pull request 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.

Patch files are simply Unified-Diff files showing the differences between your working tree and the base revision.

A pull request is an request to another repository owner to pull changes from your repository. I.e. you must have access to a public repository where you can push your changes (normally a special branch).

2.32.1. Creating a Patch Serial

First you need to make and test your changes. Then you commit your changes via TortoiseGitCommit... on the parent folder, enter a good commit message. After that select TortoiseGitCreate Patch Serial... and choose the correct options to include your changes/commits.

Figure 2.60. The Create Patch dialog

The Create Patch dialog

Directory is output directory of patch. Patch file name will be created by commit subject.

Since create patch from point. You can click ... to launch refbrowse dialog to choose branch or tag.

Number Commits is limited how much patch will created.

Range is choose range of from commit to to. You can click ... to launch log dialog to choose commit.

Send Mail after create launch send mail dialog after patches created (see Section 2.32.2, “Sending patches by mail”).

You can find more information at Section G.3.50, “git-format-patch(1)”.

[Important] Important

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 Save unified diff since HEAD.

For hints where to find more information about doing version control with Git see Section 2, “Reading Guide”.

2.32.2. Sending patches by mail

In order to send patches to the upstream authors, select the patch files and then right click on them and select TortoiseGitSend Mail...

Figure 2.61. The Send Patches Dialog

The Send Patches Dialog


First you need to enter the recipient(s) (To and/or CC).

Depending on the mail type (Patch as attachment or Combine One Mail) you have to enter a Subject for the mail.

Patch as attachment adds the patch(es) as attachment(s) to the mail(s) instead of inlining them.

Combine One Mail adds all patches to one mail. You have to enter a Subject for the mail in this case.

2.32.3. Applying a single Patch File

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 doc/source/english/chapter1.xml and the first line in the patch file is Index: english/chapter1.xml then you need to apply the patch to the doc/source/ 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.

From the context menu for a patch file (.patch or .diff extension), click on TortoiseGitReview/apply single patch... You might be prompted to enter a working tree location:

Figure 2.62. The Choose Repository Dialog

The Choose Repository Dialog


If the working tree is found, TortoiseGitMerge is launched to show and apply differences.

2.32.4. Applying a Patch Serial

Patch files are applied to your working tree. For this copy the patch (or mbox) files to the root of your working tree.

From the context menu for that folder (or all marked patch files), click on TortoiseGitApply Patch Serial...

Figure 2.63. The Apply Patch Dialog

The Apply Patch Dialog


Add Insert patch

Up Move chosen patch up.

Down Move chosen patch down.

Remove Remove the chosen patch.

Apply Start applying the patches one by one.

You can find more information at Section G.3.3, “git-am(1)”.

2.32.5. Creating a pull request

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.

First: 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.: git://example.com/repo.git BRANCHNAME

Second: 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 can a quick overview.

Select Request pull on the progress dialog after pushing your changes.

Figure 2.64. The Request Pull Dialog

The Request Pull Dialog


Start

This should be the revision on which your changes are based on.

URL

The public URL to your repository, which can be access by the people who shall pull your changes.

End

This should be the branch name or revision id of the end of your commits.

After clicking on OK the pull request is created. Just copy it and pass it to other people who you want to pull your changes.

You can find more information at Section G.3.109, “git-request-pull(1)”.