How to create Git Diff and Git Apply to Patch Your Drupal Website

When working with a Drupal website—especially in a collaborative or enterprise environment—custom code changes, contributed module tweaks, or core modifications often need to be tracked and shared efficiently. One powerful way to handle this without creating full branches or pull requests is by using Git patches.

Patches are essentially text files that record the difference between two sets of files. They allow developers to capture a change and share it, apply it elsewhere, or store it for documentation and later use.

In this guide, we’ll walk you through:

• What a Git patch is and why you’d use one in Drupal development
  
• How to create a patch using git diff
  
• How to apply a patch using git apply
  
• Best practices for working with patches in a Drupal workflow
  
• Troubleshooting patch issues

What is a Git Patch and Why Use One in Drupal?

A Git patch is a file that contains a list of differences between two versions of a file (or files) in a Git repository. These differences are created using the git diff command and saved in a .patch or .diff file.

Why are patches useful in Drupal?

• Contributed module changes: You may need to tweak a module’s behavior before a pull request is merged upstream.
  
• Sharing changes: When working with clients, teammates, or upstream maintainers, a patch is a portable, inspectable way to share a set of changes.
  
• Maintaining clean forks: Patches help you modify vendor code without diverging from the source, especially useful with tools like Composer.
  
• Avoiding fork overhead: Instead of forking a repository and creating branches, small changes can be passed around as patch files.
  

Configuration standardization: Patches help maintain consistent tweaks across environments or projects.

Prerequisites

Before we dive in, make sure:

• You have Git installed (git –version)
  
• You are in a Git-tracked project (e.g., your Drupal site’s root or a contributed module directory)
  
• You’ve made some code changes that you haven’t yet committed
  

You can create patches for core, custom modules, themes, or contributed modules, as long as Git is tracking those changes.

Creating a Patch with git diff

Let’s say you edited a contributed module, like pathauto, to fix a bug or change some functionality.

Step-by-step process

1. Navigate to your Drupal root directory (or the submodule you’re patching):
   cd /path/to/drupal/web/modules/contrib/pathauto
2. Make your code changes
   Edit the files using your IDE or editor of choice. Once done, verify the changes:
   git status
3. Generate the patch file
   Use the git diff command to generate a patch file with your changes.
   git diff > pathauto-bugfix.patch
   This will generate a file in your current directory containing the differences.
4. Move the patch to a patches directory (optional)
   It’s common practice to store patches under /patches or in a specific module directory for organization:
   mkdir -p /path/to/drupal/patches/pathauto
   mv pathauto-bugfix.patch /path/to/drupal/patches/pathauto/
5. Tip: Create a patch from specific commits
   If you’ve already committed your changes, you can still create a patch by referencing a commit hash:
   git format-patch -1 <commit-hash>
   Or for uncommitted changes in your working tree:
   git diff HEAD > my-changes.patch

Applying a Patch with git apply

Once you have a patch, applying it is just as easy.

Step-by-step process

1. Navigate to the base of the Git repo
   You need to be in the same context where the patch was originally created. This is usually the module directory or Drupal root.
2. Apply the patch
   git apply /path/to/patches/pathauto/pathauto-bugfix.patch
   Git will silently apply the patch. If it fails, it’ll let you know with errors or .rej files.
   
3. Verify the changes
   After applying the patch, confirm it worked:
   git status
   You should see the affected files as modified.

Managing Patches with Composer in Drupal

Drupal sites that use Composer (which should be all modern installations) can apply patches automatically using the cweagans/composer-patches plugin.

Step-by-step setup

1. Require the Composer patches plugin
   If not already installed:
   composer require cweagans/composer-patches
2. Add your patch to composer.json
   Inside the extra section of composer.json, specify patches like this:
   “extra”: {
     “patches”: {
       “drupal/pathauto”: {
        “Fix custom URL alias conflict issue”:       “patches/pathauto/pathauto-bugfix.patch”
      }
     }
   }
3. Apply patches
   Then, run:
   composer install
   Or to reapply patches:
   composer update nothing
   This ensures the patch is automatically applied when someone installs the site or updates dependencies.

Best Practices for Using Git Patches in Drupal

• Always document your patch: Include a comment with the source, purpose, and applicable Drupal issue URL (if relevant).
• Keep patches in version control: Store patches in your Git repo so they can be applied consistently.
• Name patches descriptively: Use clear, meaningful names like fix-title-field-length.patch.
• Track upstream issues: If you’re patching a contributed module, check if an official patch exists on Drupal.org and link to it in your documentation.
• Test thoroughly: Patches can break on updates. Re-test after applying patches to new versions of modules.

Troubleshooting Patch Errors

Sometimes, patches don’t apply cleanly. Here’s how to handle common issues:

1. Hunk failed

This happens if the line numbers or surrounding code in the patch don’t match your current files. Try:

• Checking if the module or file version changed
• Manually editing the patch file to match the updated context
• Using git apply –reject to apply what it can and create .rej files for manual resolution
  

2. Whitespace or EOF issues

Try applying with:
git apply –whitespace=fix path/to/patch.patch

3. Patch won’t apply with Composer

Double-check:

• File paths inside the patch file match your vendor/module directory
  
• The module name in composer.json is correct
  
• Run composer clear-cache if things still aren’t working

Conclusion

Using git diff and git apply to create and manage patches is a powerful way to manage code changes in your Drupal website—especially when dealing with contributed modules or custom workflows. Whether you’re building reusable features, collaborating with teams, or contributing to Drupal.org, patches keep your changes portable, trackable, and well-documented.

By integrating patch management into your Composer workflow and Git version control, you gain the benefits of customization without sacrificing maintainability or upgradability.

Bonus: Common Patch Commands Cheat Sheet