Last updated 1 December 2015.

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.

There is a short video on Applying and Creating Patches with Git that covers much of this material as well.

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 fetch [remote_name]
      

      After running a quick diff of the two branches and you're happy with the changes that will be brought into your project, merge it into your working branch using:

      git merge [remote_name]
      
  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 https://www.drupal.org/files/[patch-name].patch
      git apply [patch-name].patch
      

      Or in a single line:

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

      Or in a single line:

      wget -q -O - https://www.drupal.org/files/[patch-name].patch | git apply -
      
    • As a further alternative, setup a git alias to download and apply the patch in one command. In ~/.gitconfig:
      [alias]
      # Download and apply a patch.
              a = apply --index
              ac = "!f() { curl $@ | git a; }; f"
      

      Then run git ac https://www.drupal.org/patch-url

    • You can reverse a patch if you have finished testing. To reverse the patch, use the patch command with the -R option:
      git apply -R path/file.patch
      

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.
    • An example of using patch is patch -p1 < patch-file-name.patch - In most cases this will be from the directory of the module you are patching or the root drupal core directory for core patches.
  • 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.

Comments

chowdah’s picture

Hey, I just wanted to drop a note here that I was able to install and use Git on my Windows 7 machine this way:

Now I can just patch modules on my machine and upload the changed file(s) as opposed to having to login to shell and apply the patch in the directory!

This also comes with a Git GUI for Windows, but I haven't found the time to explore it too much yet.

scottm316’s picture

I got git working and committing to drupal.org on my Windows 7 machine too. I used git from http://git-scm.com/downloads and found a decent video here: https://www.youtube.com/watch?v=XK5zp5jXTQg Although the video isn't about the same software, a lot of the options are similar. It comes with gitk and git gui graphical tools.

Scott
http://morrisonmultimedia.ca/
Edmonton, AB

DrCord’s picture

Use the --verbose or -v flag when applying a patch to output more useful information, especially if the patch fails to apply cleanly.