Documentation: Multiple Patches on the Same Code Block Fail in Composer Patches v2 #660
Description
Verification
- I have searched existing issues and discussions for my problem.
Which file do you have feedback about? (leave blank if not applicable)
No response
Feedback
Applying multiple patches to the same file using Composer Patches v2 fails when the patches modify different lines but are located within the same block of code. This appears like overlapping patch conflicts, even though the edits are not on the same line. The behaviour is confusing for end users and looks like a plugin defect, but it is actually a consequence of how git apply processes unified diff context.
This is expected Git behaviour, but it is not documented, leading to repeated confusion.
What Happens
• Composer Patches v2 applies patches sequentially using git apply.
• Two patches generated from the same original file typically share the same unified diff context lines.
• After patch 1 modifies the file, the context expected by patch 2 no longer matches.
• git apply therefore rejects patch 2 with a “patch does not apply” error.
• Composer Patches reports the failure, even if the two patches modify different lines.
Why This Is Expected
This is normal behaviour of unified diffs:
• Patches do not only modify specific lines; they also require surrounding context to match exactly.
• When an earlier patch changes any part of that context, subsequent patches generated from the original version cannot apply.
• Composer Patches v2 intentionally delegates patching to Git, so Git’s standard behaviour applies.
Impact
• Users often try to apply multiple upstream patches to the same method/function.
• Patching fails unless patches are re-rolled or merged.
• The cause is non-obvious unless the user understands unified diff mechanics.
This commonly leads users to believe Composer Patches is broken, when it is in fact working correctly.
Recommended Documentation Additions
The documentation should clarify:
1. Multiple patches affecting the same code block (even different lines) may fail due to unified diff context mismatches.
2. Each subsequent patch must be created against the codebase after applying the earlier patches, or all patches should be merged.
3. Reducing diff context (git diff -U1 / -U0) can sometimes help but has drawbacks.
4. Patch ordering matters, and the lock file preserves that order.
5. This is expected behaviour of git apply, not a Composer Patches limitation or bug.
Suggested Workflows to Document
• Merge multiple patches into a single combined patch
or
• Re-roll patches sequentially against already-patched code
Both approaches avoid context conflicts.
Conclusion
No code changes are required, but the behaviour should be clearly documented to prevent confusion. Explicitly noting the unified-diff context limitation will help users understand why multiple patches on the same block may fail and how to work around it.