Last updated June 1, 2016.

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. Drush issue queue commands makes it an easier and faster to create and work with patches.

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

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

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 or 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: 8.x-1.x-dev. Make patches against the -dev version because it is the latest code. Note that when you're working on the -dev branch with git, you won't actually append '-dev' to the branch name or see '-dev' in the branch name. Just the fact that the branch name ends in '.x' (e.g. 8.x-1.x) means it is a development branch. Any changes since the last release, 8.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 or 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 or theme, but with git revisioning.
  7. git clone --branch 8.x-1.x http://git.drupal.org/project/colorbox.git 
    cd colorbox
  8. In the module or 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. (If the issue appears at http://drupal.org/node/123456 then the issue number is 123456.)
  9. git branch [issue-number]-[issue-description]
    ex: git branch 1234-fix-for-header
    

    To see if it worked:

    git branch
    * 8.x-1.x
      1234-fix-for-header
    
  10. 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 branchname' 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. (To quickly fill in the branchname, start typing and hit 'tab'.)
  11. git checkout 1234-fix-for-header
    git branch
      8.x-1.x
    * 1234-fix-for-header
    
  12. Now make the changes you want to the module or 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.
  13. git status
    git diff 
    git add new_file.php
    git commit -a 
    
  14. When you're ready to make a patch. Go to the folder of the module or theme. Commit any changes you've made, then use 'git diff 8.x-1.x' to review the changes that will go into the patch.
  15. git diff 8.x-1.x
    (To exit git diff, simply press q.)

  16. On the issue page, go to the files section at the bottom of the page and click the "Patchname suggestion" button and copy the filename from the pop-up.
  17. When you're ready, create the patch with this command using the filename from the previous step in place of [patch_name.patch]:
  18. git diff 8.x-1.x > [patch_name.patch]
    
  19. Now go upload the patch! congratulations on helping to make Drupal better!

Notes

  • More indepth information can be found in the Advanced patch contributor guide.
  • 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 or 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
      8.x-1.x-dev
    * 1234-fix-for-header
    git checkout 8.x-1.x-dev
    git branch
    * 8.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.

git branch

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

git pull origin [branchname]

Make your changes. Get the patch name by using the "Patchname suggestion" button on the issue's page. Create the patch file using the retrieved filename:

git diff > [patch-name.patch]

If you added new files with your patch, then:

git add [path.to.new.file]
git diff --staged > [patch-name.patch]

To perform both at the same time:

git add [path.to.new.file]
git diff HEAD > [patch-name.patch]

To create a patch of the commits on the current branch that are not on master:

git format-patch master --stdout > [patch-name.patch]

Create a New patch

Here is the instruction with the help of we can create a new patch
Firstly write the code in the specific file
and then use this command

git diff > [patch-name.patch]

e.g

git diff > migrate_d6_i18n_nodes-2225775-136.patch

see the e.g
_ (Underscore sign is used to separate the word)
migrate_d6_i18n_nodes is short-description for the issue.
2225775 is issue number. The issue number is the last part of the issue page URL; ie https://www.drupal.org/node/2225775.
136 is comment number.

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.

git apply -v [patch-name.patch]

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

rm [patch-name.patch]

When you're done: Reverting uncommitted changes

Revert changes to a specific file:

git checkout [filename]

Revert changes to the whole working tree:

git reset --hard

Remove files added outside the working tree:

Note: Use with care! Add -n to do a dry run

git clean -fd

Comments

kalebheitzman’s picture

Initially had trouble with git clear. I finally found the .gitconfig file referencing this as well as a note in the revision log saying this should be made more clear. That was 6 months ago. I would add a note myself except I can't edit the page.

kndr’s picture

Also, for Unix/Mac users:
Execute:
git config --global core.autocrlf input
git config --global core.safecrlf true

And for Windows users:
Execute:
git config --global core.autocrlf true
git config --global core.safecrlf true

Look at http://drupal.org/node/1046962

alex.designworks’s picture

It is not clear whether headings above are steps to follow or just descriptions how to perform totally separate tasks?

If steps - please specify step number in the heading and description that below are steps that one needs to follow to create a patch.
If separate tasks - please bring under different headings and place a note before that below are just description of separate tasks and not steps.

mjross’s picture

The command "git branch" worked fine.

The command "git pull origin" resulted in the error "fatal: 'origin' does not appear to be a git repository".

I then made the changes to one of the source files, and tried the command "git diff", but there was no output.

There seem to be critical steps missing from the instructions in this article.

attheshow’s picture

Here's a simple example of how to create a patch for a contrib module in case anyone wants to see a video version:

https://vimeo.com/41366717

Mark W. Jarrell
mark@fleetthought.com
http://about.me/markjarrell
http://fleetthought.com
Beautiful websites managed by you.

decibel.places’s picture

In Step 9 I also had to add a commit message with the -m switch

git commit -a -m "my message"

rondp’s picture

If you only want to submit a single file and don't want to clone the whole repository with 180,000 objects to do so, the method below seems to produce almost identical results.

Notes:
* original file is "taxonomy.install.orig",
* modified file "taxonomy.install",
* all commands run from the parent directory of the repository, i.e. one level above "drupal"

$ mkdir -p a/modules/taxonomy
$ ln -s drupal b
$ mv b/modules/taxonomy/taxonomy.install.orig a/modules/taxonomy/taxonomy.install
$ diff -up a/modules/taxonomy/taxonomy.install b/modules/taxonomy/taxonomy.install 
Elijah Lynn’s picture

If you already have a module and you made some changes and want to generate a diff from the current directory and not have to checkout a repo you can use --relative.

http://www.lullabot.com/articles/git-best-practices-upgrading-patch-process

-----------------------------------------------
The Future is Open!

JamesLefrère’s picture

YMMV, but I found this the most straightforward method to keep patches clean:

  • Create branch
  • Add your commits
  • Switch to master and squash the branch: git merge --squash your-branch-name-here
  • Create the patch from the working tree

That way you can always return to your history of commits in the issue branch.

joachim’s picture

The suggested patch filename format of [project_name]-[short-description]-[issue-number]-[comment].patch is problematic because it makes autocomplete difficult.

I propose [issue-number]-[comment]-[project_name]-[short-description].patch instead.

bwoods’s picture

I've applied many patches but haven't created one until today. It seemed weird that the description wasn't at the end, and it seems the issue number is the most important of the items within the string.

jrockowitz’s picture

A stupid trick to avoid accidentally committing patches, is to create a .gitignore file that ignores itself and all patches.

The below code only works when the contrib project does NOT include a .gitignore file.

cd contrib_project;
cat >> .gitignore <<'EOF'
.gitignore
*.patch
EOF
ultrabob’s picture

On the issue page, go to the files section at the bottom of the page and click the "Patchname suggestion" button and copy the filename from the pop-up.

I don't actually see this button anywhere on the issue page.

nerdcore’s picture

There is no such link on drupal.org today...

What is the suggested patch name scheme?