Applying patches with git

This page outlines a workflow for testing patches and code improvements, including how to download, apply, test, and improve upon patches on your local development environment that have been uploaded by others to Drupal.org's issue queues, using a Git workflow and local "topic branches".

Note: If you're unfamiliar with patching Drupal, please read the Getting Involved section on Patches.

There are also less-technical instructions in the Beginner's guides on How to Apply Patches, as well as non-Git focused instructions for applying patches on Windows and Mac OS.

Setup: preparing the local project environment

1. There are two ways you might go about setting things up, depending on if you've already obtained the project or not.
   • Clone the project to get a copy you can work with locally (you only need to do this once per project).
     git clone --branch [version] http://git.drupal.org/project/[project_name].git
   • Alternatively, if you're working on a project that you've already obtained, pull the latest changes down to ensure you're working on the latest code.
     git pull

     Optionally, switch to the version (aka, branch) to which you'll be applying the patch. This is not necessary if you checked out the code with git clone specifying the --branch option, as in the example above, but is needed if you typically work between multiple branches.

     # List all the versions
     git branch -a

     # Switch to the branch (version)
     git checkout [version]  #  e.g. version might be 7.x-2.x

2. Create a local "topic branch" for the issue you're working on.
   git checkout -b [issue-number]-[short-description] # e.g. 123456-some-bug

Configuration: Obtaining and applying a patch file

1. Download the patch and apply the code changes in the patch to your working directory. The following commands assume you're already in the project's root directory. If not, you need to cd ~/path/to/[project-name] first.
   • Use `curl` to download the file, then use git to apply the patch:
     curl -O http://drupal.org/files/issues/[patch-name].patch
git apply [patch-name].patch

     Or in a single line:

     curl http://drupal.org/files/issues/[patch-name].patch | git apply -
   • Alternatively, use `wget` to download the file, then use git to apply the patch:
     wget http://drupal.org/files/issues/[patch-name].patch
git apply [patch-name].patch

     Or in a single line:

     wget -q -O - http://drupal.org/files/issues/[patch-name].patch | git apply -

Test & Report the results

• If the patch does not apply, you may either copy the patch error message into a comment in the issue queue, or attempt to "re-roll" the patch by hand, which may require applying the patch manually.

  If the patch command executes without any complaints, examine the code changes in your working directory, to confirm the changes.

  git diff
• Now test the changes, to see if you can break them. Leave a detailed review of what you tried in the issue. If you can confirm the patch does it's job as advertised, leave a comment to that effect and change the status to "reviewed and tested by the community". On the other hand, if the patch breaks something or does not fix the original issue adequately, change the issue status to "needs work", and explain what still needs fixing.
• Alternatively, (ideally?) fix what is broken about the patch, or make your own improvements, by editing the code and files, then create a single-commit patch of your own and upload it in a comment on the issue, changing the issue status to "needs review". Note: Your patch should be made against the [version] of code that is to be patched, not against the patch you downloaded.

When you're done: Code cleanup

• This workflow provides a methodology to organize each issue into its own "topic branch". If you're working on various issues within a given project, Git will let you see a list of your local topic branches at any time.
  git branch
• Once you no longer need or plan to work on a feature, delete your topic branches.
  git branch -D [branch-name]

Footnotes

• You can also apply patches with patch -p1 and git am. git am is also useful if the patches were created by git format-patch.
• Some older patches may require patch -p0 or git apply -p0 to apply correctly, but patches made with git should all be -p1 compatible.
• Since the patch files themselves should not ever be added to the project, you may wish to tell Git to ignore them by adding the line *.patch to the .git/info/exclude file in the project, or to a global ~/.gitignore file.