Dev:Doc/Tools/Patches

Patches and Diffs

What is a patch?

A patch is no more than a text file which contains data about the differences between two versions of code. They contain changes to code, adding functionality, fixing a bug, etc. A patch contains information about which files change on which lines and how. Contributing Code to Blender is done through such patches or diffs.

The words patch and diff are often used interchangeably, although for Git they can mean slight different things. Our Code Review tool currently accepts diffs created with git diff or git show, not git format-patch.

When should I submit a patch?

Writing patches is generally done for two reasons:

• To distribute a bugfix: often you may spot a bug in Blender's source code before a developer has the opportunity to do the same work. Creating a patch is the perfect opportunity to get the work done without putting it on someone else's (likely very long) todo list.

• Contributing new features: many coders take it upon themselves to add functionality to Blender in their own free time. Without these 'homebrew' projects, Blender would not be what it is today. Outside contributions from hobbyists and professionals alike are crucial to the development process. Yes that means you!

Applying Patches

In order to apply the changes stored in a patch file to your checkout of the source code you need to use the following command in your repository root directory. Note: the following require that patch is installed.

# for git diffs
patch -p1 < some-new-feature.diff

# for svn diffs (older patches in the tracker)
patch -p0 < some-new-feature.diff

You will then be given an indication of whether or not the operation was a success. If it was not, there are many possibilities as to why your source code was incompatible with the source code the patch was created against. It is best to contact the author to be sure you both have an updated version of sources or edit the resulting files manually to be sure everything is as it should be. Be warned! This can be a time consuming and frustrating process.

Reverting Patches

You can revert the changes made by a patch by using the -R switch as shown below, again from the root directory:

# for git diffs
patch -p1 -R < some-new-feature.diff

# for svn diffs (older patches in the tracker)
patch -p0 -R < some-new-feature.diff

Creating Patches

The simplest way is simply to make changes in the code, then run this command from the root repository directory. You can then upload this file and share it with others.

git diff > some-new-feature.diff

Creating Patches from Local Git Branches

When working with Git, the usual workflow is to create local branches where you commit your changes. You can then easily switch between the unmodified master branch and your local branch, and create a diff from the local branch when you're ready to submit it.

To create a new branch when you are in the master branch, the basic commands are:

git checkout -b some-new-feature
# ... make changes to code ...
git commit -a

To generate a diff, you can run:

# generate a diff
git diff master..some-new-feature > some-new-feature.diff

If you work on your some-new-feature branch but do not submit its diff soon, it can get out of sync with the master branch, where you typically keep pulling in commits with new features and bugfixes from the main repository. If you are going to do further work on the new feature or send a diff, you want it to be created relative to the very latest version of the main repository. Otherwise your diff may no longer apply cleanly for others, or your feature may no longer work correctly due to changes in the code.

To get all those new commits into your some-new-feature branch as well, you have to 'rebase' it on top of master. That means it will pull in new commits from master and keep your local commits at the top of the commit list.

# switch to feature branch
git checkout some-new-feature
# rebase on top of master
git rebase master
# now you can continue work on the feature or generate a new diff

For more info on how to use Git or how to submit changes for code review, see the Git Usage and Code Review pages.

Git Mailbox Style Patch Sets

With Git you can create more advanced patches that can contain multiple commits and information about the author. Unfortunately our code review tool does not accept these yet, for that you have to use the arc command line tool described on the code review documentation.

For reference, here is how to use such patches. To apply:

# for git mailbox style patch sets
git am group-of-patches.mbx

To create patches in mailbox style format from changes in a branch:

git format-patch --stdout origin > group-of-patches.mbx

To generate a mailbox style patch from commits R1 to R2:

git format-patch --stdout R1..R2 > group-of-patches.mbx