Add a way to specify the --include and --exclude flags for git apply

[cweagans]

Verification

• I have updated Composer to the most recent stable release (composer self-update)
• I have updated Composer Patches to the most recent stable release (composer update cweagans/composer-patches)
• I am using one of the supported PHP versions (8.0+)
• I have searched existing issues and discussions for my idea.

Is your feature request related to a problem?

Sometimes, patches are created for a given dependency and those patches include changes to test files or other files that aren't in the final distribution package. Normally, we'd recommend installing from source instead of from dist, but it's valid to not want to do that. Example of this friction: #528

Describe your proposed solution(s)

There should be a way to specify the --include and --exclude flags for git apply. Note that those flags are sensitive to the order that they're specified:

• --include path/* --exclude path/foo.txt will apply changes to files in path/ except for foo.txt
• --exclude path/foo.txt --include path/ is essentially a no-op
• --include path/foo --exclude path/foo/bar --include path/foo/bar/baz.txt

If we want to generalize this, we could potentially have an allowlist of flags to pass to git (with the default being --include and --exclude) so that users can completely control how patches are applied.

Maybe something like this?

{
    [...],
    "extra": {
        "patches": {
            "the/project": [
                {
                    "description": "[...]",
                    "url": "[...]",
                    "extra": {
                        "git-flags": [
                            "--include foo/",
                            "--exclude foo/bar.txt"
                        ]
                    },
                }
            ]
        }
    }
}

Or if we don't want arbitrary flags to be passed, maybe something more like this:

{
    [...],
    "extra": {
        "patches": {
            "the/project": [
                {
                    "description": "[...]",
                    "url": "[...]",
                    "extra": {
                        "git-flags": [
                            { include: "foo/" },
                            { exclude: "foo/bar.txt"}
                        ]
                    },
                }
            ]
        }
    }
}

Wrapping in an object in the latter example is needed so that we don't have duplicate keys in the event that the user wants to specify include then exclude then include again.

A simpler option here is to simply assume that the user will only ever need to specify --include or --exclude and only have one place to put each of those things. That'll make it easier to test, too.

Describe alternatives

No response

Additional context

No response

[github-actions]

👋 Thanks for the idea! Please remember that this is an open source project - feature requests may or may not be implemented, and if they are, the timeline is unknown. If you need a guaranteed implementation or timeline, sponsorships are welcome!