Troubleshooting guide

[benjy]

Could be worth having a troubleshooting guide somewhere, I had an issue today where all patches would apply perfectly fine locally but failed on CI inside of the docker container. For me, the version of patch was outdated and I fixed it with

apk --update add patch

Hopefully this helps others.

[cweagans]

Thanks for that! A troubleshooting guide is definitely on my radar. There are some other common problems that would be a good fit for that too.

[TynanFox]

I'm sure this is probably a "duh" thing to all the rest of you, lol, but for us newbs out there, perhaps add a note in the troubleshooting guide to ensure that Windows users are running in a bash shell.

I couldn't get any patches to apply at all via the terminal running Xampp on a Windows 10 PC, until I started the bash shell. Then it worked fine. Not difficult at all, but also something so obvious to experienced developers that little things like these get missed in documentation. :)

[velletti]

Some Remarks from my side :

the Thrown exception should / could also contain the used value for install_path and a link to the planed "Trouble Shooting" page .

f.e.:

if (!$patched) { throw new \Exception("Cannot apply patch: Install_path: $install_path \n File: $filename \n patch-levels :" . implode(", " ,$patch_levels ) . "\n see Troubleshooting page : https://github.com/cweagans/composer-patches/wiki "); }

(or link to this issue :-)

for me this would have helped (found it by reading the code .. ) :

This plug in is doing this:

1. Checks if the folder is under Git Control ( check if .git folder exists)
   if yes, it tries to call this command with all patch_levels
   git -C $install_path apply $patch_level $filenames'

2. if this is not successfull, it tries to call the patch command like this:
   patch $patch_level --no-backup-if-mismatch -d $install_path < $filenames

Try these commands manually to get more details, why your patch could not be applied.

Check wrong path settings, (see $install_path) , missing slashes, different line breaks,

The path of the patch files must normaly start from the Root directory of the composer project.

Some Examples could be helpful:

if you using this to patch a TYPO3 core file and have this in your composer.json,

"typo3/cms": { "cms-package-dir": "{$vendor-dir}/typo3/cms", "web-dir": "http" },

the files must be referenced like this:
typo3/sysext/core/Classes/Cache/ .. / ...php

and not starting with:
vendor/typo3/cms/

see this :

Index: typo3/sysext/core/Classes/Cache/Backend/Typo3DatabaseBackend.php IDEA additional info: Some commit comment Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP <+>UTF-8 '=================================================================== --- typo3/sysext/core/Classes/Cache/Backend/Typo3DatabaseBackend.php (date 1542704751280) +++ typo3/sysext/core/Classes/Cache/Backend/Typo3DatabaseBackend.php (date 1542704751280)
.....

[cweagans]

I've made a note to include a troubleshooting guide in the 2.x documentation.

[cweagans]

(this is for 2.x)

Basic troubleshooting guide here: https://docs.cweagans.net/composer-patches/troubleshooting/guide/

I also added a composer command (composer patches-doctor) that spits out a report like this:

System information
================================================================================
Composer version:                                                          2.5.1
PHP version:                                                               8.2.1

Available patchers
================================================================================
cweagans\Composer\Patcher\GitPatcher usable:                                 yes
cweagans\Composer\Patcher\GnuPatchPatcher usable:                            yes
cweagans\Composer\Patcher\GnuGPatchPatcher usable:                            no
cweagans\Composer\Patcher\BsdPatchPatcher usable:                             no
Has usable patchers:                                                         yes

Common configuration issues
================================================================================
preferred-install is set:                                                    yes
preferred-install set to 'source' for all/some packages:                      no
has plain http patch URLs:                                                    no

Suggestions
================================================================================
 - Setting 'preferred-install' to 'source' either globally or for each patched dependency is highly recommended for consistent results
   More information: https://docs.cweagans.net/composer-patches/troubleshooting/guide#set-preferred-install-to-source

Hope this helps!