Applying a patch in a feature branch

This page outlines a workflow for downloading and applying patches to a local workspace, based on local "topic branches".

Prepare the local repository

1. Follow the steps on Cloning a Drupal git repository to make a local copy of the repository or update your existing local copy to the latest version.
2. Create a local "feature branch" for the issue you're working on.
   

   git checkout -b [issue-number]-[short-description] # e.g. 123456-some-bug
   

Obtain and apply a patch file

Download the patch file from the issue (see Downloading a patch file), and apply the code changes in the patch to your working directory.

There are several command variations you can use (the following commands assume you're in a terminal window in the project's root directory):

• Download the patch file manually from the issue (click the link and save to your local computer). Then:
  git apply --index -v [patch-name].patch
• 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 --index [patch-name].patch
  

  Or in a single line:

  curl https://www.drupal.org/files/[patch-name].patch | git apply --index -
  

• Use wget to download the file, then use git to apply the patch:
  

  wget https://www.drupal.org/files/[patch-name].patch
  git apply --index [patch-name].patch
  

  Or in a single line:

  wget -q -O - https://www.drupal.org/files/[patch-name].patch | git apply --index -
  

• Set up 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

Also, there are many command-line arguments to the git apply command. One useful one is -v, which gives a more verbose output:
git apply -v patchname.patch
See the git apply documentation for more information.

If the patch does not apply, and you perhaps are getting a "Skipped patch ..." message, try adding the option --directory=<path_from_the_git_project_root> or use the patch command (see "Footnotes" below for more) or reroll the patch:

patch -p1 < [patch-name].patch

Reverse the patch, by adding the -R parameter:

patch -R -p1 < [patch-name].patch

Commit the patch

If you are planning to work on improving the patch, the next step is to commit the original patch to your local repository branch:

git add FILESAFFECTED
git commit -m “Patch COMMENTNUMBER by OTHERPERSON”

When you're done: Code cleanup

After you have finished testing the patch, you'll want to get your repository back to a "clean" state:

• Use this command to revert the patch: git apply -R path/file.patch
• Use this command to delete the feature branch you created: git branch -D [branch-name]

Footnotes

• You can also apply patches with git am. git am is also useful if the patches were created by git format-patch.
• The patch command is useful for patches that don't apply, as it will apply most of the patch and then you may be able to look at the .rej file it creates for the rejected "hunks" of the patch, and fix them manually. If it is too complicated, try rerolling the patch.
• 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. Alternatively, you can download them to a different location.
• If you have errors when you try to apply a patch, check for the following:
  • The patch may have the wrong end-of-line encoding. Our standard is to use Unix-style end-of-line encoding (see Patch Guidelines).
  • The patch may not match the latest development version. See Rerolling patches for how to merge in later changes.
  • If the automatic testing also flagged the patch as not applying at the time it was created, the developer who created the patch may have made an error (such as not using Git or not using the latest development version).