Drupaltools Patch

Drupal Patch

Apply a patch to a Drupal contrib project from any source.

Step 1 — Identify the target module

Derive the module machine name from context in this order:

1. Selected code or file — walk up to the nearest *.info.yml using the drupal-module-info skill. The filename stem is the machine name.
2. Selected folder — same as above.
3. Selected composer.json line — extract from "drupal/<machine_name>" pattern.
4. Natural language — if the user named the module explicitly, use that.
5. Not found — ask the user: "Which module should the patch be applied to?"

Once identified, locate the module directory:

find web/modules/contrib -maxdepth 1 -type d -name "<machine_name>" | head -1
# Also try docroot/ or html/ if web/ not found

Store as $MODULE_DIR.

Step 2 — Get the patch

Identify the patch source from the user prompt and follow the matching path below.

Source A — Direct URL

User provides a URL ending in .patch or .diff.

curl -L -o /tmp/<machine_name>.patch "<URL>"

Source B — Git commit hash

User provides a commit hash for the module.

Check if $MODULE_DIR has a .git folder:

[ -d "$MODULE_DIR/.git" ] && echo "git repo"

If yes:

cd "$MODULE_DIR" && git format-patch -1 <HASH> --stdout > /tmp/<machine_name>.patch

If no, generate a diff patch from drupalcode.org:

https://git.drupalcode.org/project/<machine_name>/-/commit/<HASH>.diff

Source C — Drupal.org issue ID

User provides an issue number or URL like https://www.drupal.org/node/<issue_number>.

Fetch the issue page and find patch attachments:

curl -sS "https://www.drupal.org/node/<issue_number>" | \
  grep -oE 'https://[^"]+\.patch' | tail -1

If no .patch found, look for a GitLab MR link on the page (see Source E).

Store the latest patch URL and download it:

curl -L -o /tmp/<machine_name>.patch "<PATCH_URL>"

Source D — Drupal.org issue comment

User provides a comment URL like https://www.drupal.org/project/.../issues/<issue>#comment-<id>.

Fetch the specific comment and extract its patch attachment:

curl -sS "<COMMENT_URL>" | grep -oE 'https://[^"]+\.patch' | head -1

Download the patch as in Source C.

Source E — GitLab merge request number

User provides an MR number (e.g. 15137) or full URL.

Construct the diff URL:

https://git.drupalcode.org/project/<machine_name>/-/merge_requests/<MR_NUMBER>/diffs.patch

curl -L -o /tmp/<machine_name>.patch \
  "https://git.drupalcode.org/project/<machine_name>/-/merge_requests/<MR_NUMBER>/diffs.patch"

Source F — Local file changes (IDE or git)

Try in order:

PHPStorm MCP — if available, request a diff of uncommitted changes in $MODULE_DIR from the MCP and save to /tmp/<machine_name>.patch.

Git CLI fallback:

cd "$MODULE_DIR" && git diff > /tmp/<machine_name>.patch
# Or for staged changes:
cd "$MODULE_DIR" && git diff --cached > /tmp/<machine_name>.patch

Source G — Natural language

Parse the user's description to extract one of the above source types:

Once identified, proceed with the matching source above.

Store the final patch file path as $PATCH_PATH. If the patch could not be obtained, tell the user and stop.

Step 3 — Offer dry-run

Before applying, always offer:

"Patch ready at $PATCH_PATH. Run a dry-run first to check for conflicts?"

If yes, or no response implies yes, run:

# For git repos
git apply --summary "$PATCH_PATH"

# For non-git
patch --dry-run -p1 < "$PATCH_PATH"

Show the dry-run output. If it is clean, confirm with the user before applying for real. If it has conflicts, skip straight to Step 5.

Step 4 — Apply the patch

Choose the method by priority:

Priority 1 — Module is a git repo ($MODULE_DIR/.git exists)

First check if the drupalorg CLI is available:

which drupalorg 2>/dev/null && echo "available"

If available and the patch source is a Drupal.org issue or MR, prefer drupalorg over git apply:

# From an issue number
drupalorg patch:apply <issue_number> --directory="$MODULE_DIR"

# From a specific MR
drupalorg patch:apply --mr=<MR_NUMBER> --directory="$MODULE_DIR"

If drupalorg is not available, or the patch source is a local file or direct URL, fall back to:

cd "$MODULE_DIR" && git apply "$PATCH_PATH"

Priority 2 — Project uses cweagans/composer-patches

Check:

grep -q "cweagans/composer-patches" composer.json && echo "yes"

If yes, add to composer.json under extra.patches:

{
  "extra": {
    "patches": {
      "drupal/<machine_name>": {
        "https://dgo.to/<issue_number> | <description>": "<PATCH_URL>"
      }
    }
  }
}

Use the pattern https://dgo.to/<issue_number> | <description> as the key. If there is no issue number, use the patch URL or a short description as the key.

Then apply:

ddev composer install

Priority 3 — Raw patch command

cd "$MODULE_DIR" && patch -p1 < "$PATCH_PATH"

Step 5 — Report

Show the stdout/stderr from the apply command and state clearly:

• OK — patch applied cleanly. State which method was used and which files were modified.
• ERROR — show the exact error lines from stderr.

Step 6 — Error diagnosis

If the apply failed, identify the cause:

Step 7 — Retry with alternative patches

If the error is a version or line mismatch, and the source was a Drupal.org issue (Source C or D):

1. Fetch all patch URLs from the issue page:

curl -sS "https://www.drupal.org/node/<issue_number>" | \
  grep -oE 'https://[^"]+\.patch'

2. Try each patch from newest to oldest, repeating Steps 3–5 for each.
3. Stop at the first one that applies cleanly.
4. If none apply, proceed to Step 8.

Step 8 — Offer to fix the patch

If all patches fail, offer:

"No patch applied cleanly. I can attempt minor adjustments to the patch (line number offsets, context line fixes) so it applies to your local version. Proceed?"

If yes:

• Show a diff between what the patch expects and what the local file contains.
• Propose specific line changes.
• Ask for confirmation before modifying the patch file.
• Re-run Step 3 (dry-run) with the modified patch before applying.

Related skills

The following skills may be available alongside this one. Use them when relevant:

Notes

• Patch key format in composer.json: always "https://dgo.to/<issue_number> | Description" when an issue number is known.
• For MR-sourced patches with no issue number, use the MR URL as the key.
• Never silently modify composer.json — show the diff and confirm first.
• If ddev is not running when needed, warn the user: "DDEV must be running. Start with ddev start first."