Making a Drupal patch with Git

Last updated April 11, 2012.

This page documents a high-level overview of the current best practice recommendations for contributing change requests, in the form of a patch file, to projects (e.g., modules, themes, Drupal core, etc) hosted on Drupal.org using Git. For a more advanced workflow with Git, please refer to the Advanced patch contributor guide.

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

Note 2: If you choose to create patches with a tool other than Git, be sure to produce a -p1 patch; the old -p0 format was phased out in 2011

General patch guidelines

Keeping things organized

To help reviewers understand the scope of changes, separate each change type into its own patch. For example, bug fixes, performance enhancements, code style fixes, and whitespace fixes all should be in different patches. Each separate change type (and patch) should be associated with a different issue in the queue on Drupal.org.

Line endings and directory separators

Note for Windows users: Use Unix line endings (LF) and directory separators (/). Many text editors can convert line endings, or you can pipe diff output through dos2unix.

Quick and simple patch

This section is written to be a step-by-step guide to help someone contribute their first patch.

1. Go to the module/theme's page. ex: http://drupal.org/project/colorbox/
2. Click "Version Control" under the title. ex: http://drupal.org/project/colorbox/git-instructions
3. Select the dev version that you wish to patch/update. This is typically the current Drupal release with the module's version and '-dev' appended. ex: 7.x-1.x-dev. Make patches against the -dev version because it is the latest code. Any changes since the last release, 7.x-1.2, will already be in the -dev branch.
4. Click the show button to make sure the "git clone" command line is correct/updated
5. Copy the "git clone --branch .. " command
6. Now run the git command to download a revisioned copy of the module/theme. Run the command in the appropriate folder (ex: sites/all/modules or sites/all/themes) and it will be the equivalent of downloading and unpacking the module/theme, but with git revisioning.
git clone --branch 7.x-1.x http://git.drupal.org/project/colorbox.git
cd colorbox
7. In the module/theme directory, tell git to create a 'branch' of the local version you just downloaded so that you can update/change a separate branch, commit those changes, and still easily generate a patch against a local branch.
git branch [IssueNumber]-[IssueDescription]
ex: git branch 1234-fix_for_header
To see if it worked:

git branch
* 7.x-1.x-dev
  1234-fix_for_header
8. Notice the '*', it tells which branch git is using. To use the new branch, tell git to checkout the files from branch 1234-fix_for_header. Note: 'git checkout branch_name' replaces all of the revisioned files in the directory with the files from that branch, essentially swapping out one version for another. In our case, the files are the same so there isn't any noticeable change.
git checkout 1234-fix_for_header
git branch
  7.x-1.x-dev
* 1234-fix_for_header
9. Now make the changes you want to the module/theme. You can use git to see about general changes you've made, specific changes you made, add files you created, and commit your work.
git status
git diff
git add new_file.php
git commit -a
10. When you're ready to make a patch. Go to the folder of the module/theme. Commit any changes you've made, then use 'git diff 7.x-1.x-dev' to review the changes that will go into the patch.

git diff 7.x-1.x-dev

11. When you're ready, create the patch with this command:
git diff 7.x-1.x-dev > [project_name]-[short-description]-[issue-number]-[comment-number].patch
12. Now go upload the patch! congratulations on helping to make Drupal better!

Notes

• The command 'git clone' will only work if the folder does NOT exist. If it does exist it will give you an error. This saves from overwriting any work you might have already done. Either move folder if it already exists , or delete if you have not made any changes.
• If you rename/move the folder, be sure to move it out of of the Drupal directory so Drupal will not detect it as a module/theme and try to load it twice.
• Or, you can run this command in a non Drupal directory, and then copy files you've already edited into the new folder. This has the drawback of not being to able see live changes.
• If your branch doesn't yet work, and you'd like to revert the module to a working/official copy. Commit your changes, checkout the main branch, and then clear Drupal's caches. Note: If you haven't committed your changes yet, git will NOT allow you to change branches.
  
  git commit -a
git branch
  7.x-1.x-dev
* 1234-fix_for_header
git checkout 7.x-1.x-dev
git branch
* 7.x-1.x-dev
  1234-fix_for_header

More git commands

Be sure you have checked out the branch you wish to patch with the following command.

Ensure it is up-to-date with the following:

Make your changes. Then if, for example, the issue appears on Drupal.org at http://drupal.org/node/707484, using issue-number 707484:

[project_name] refer's to the project's name as it appears in the URL, i.e. http://drupal.org/project/[project_name], or from the git remote repository location, i.e. http://git.drupal.org/project/[project_name].git

If you added new files with your patch, then:

To perform both at the same time:

Applying a patch

Download the patch to the root of your working directory. Apply the patch with the following command. The -v flag makes the output verbose so you can see the patch apply successfully.

To avoid accidentally including the patch file in future commits, remove it:

When you're done: Reverting uncommitted changes

Revert changes to a specific file:

Revert changes to the whole working tree: