This tortured and broken sentence in the docs cost me hours of troubleshooting.

[hungarian-notation]

Describe your use-case which is not covered by existing documentation.

I've just spent a few hours pouring over whatever documentation I could find and permuting my build.gradle trying to get shadow to merge several META-INF/hk2-locator/default files in a way that doesn't break their syntax.

Getting ServiceFileTransformer to combine them was easy enough, but the empty lines between groups of entries in hk2-locator files are semantically significant, and ServiceFileTransformer does not preserve them.

The ResourceTransformers like ServiceFileTransformer will not work as expected as the duplicate resource files fed for them are excluded beforehand. However, this behavior might be what you expected for duplicate foo/bar files, preventing them from being included.

from configuration/merging

On my several passes through the documentation, I read this to mean that DuplicatesStrategy should not be used with ResourceTransformers that merge files, as they somehow interfere with eachother.

None of the usages I could find of the transformers appeared to combine append with duplicatesStrategy = DuplicatesStrategy.INCLUDE, and thanks to this section of the documentation counter-indicating combining duplicatesStrategy with "transformers like ServiceFileTransformer" I didn't think to try it.

I was finally working on just writing a bespoke transformer implementation when I got a strange feeling and decided to just try doing the opposite of what the docs seem to say here, and low and behold:

tasks.named('shadowJar', com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar) {   
    filesMatching ('META-INF/hk2-locator/default') {
        duplicatesStrategy = DuplicatesStrategy.INCLUDE 
    }
    append 'META-INF/hk2-locator/default'
}

was exactly what I needed.

The grammar of that paragraph from the docs is broken to the point where it doesn't clearly say anything, but at the very least, if it was meant to imply that we should use DuplicatesStrategy to merge files it's more than just a little ambiguous.

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

No response

Are you interested in contributing to the documentation?

I'd write a pull request fixing the docs, but this whole experience has left me so confused that I'm still not sure I 100% understand the behavior here, beyond the fact that this specific incantation I came up with works. Am I missing something?

[Goooler]

I think it's noted at https://gradleup.com/shadow/configuration/merging/#handling-duplicates-strategy.

This issue appears to be a duplicate of #1884.

[hungarian-notation]

No, that's the section I quoted from.

Do you mean this?

INCLUDE: Duplicate foo/bar entries will be included in the final JAR.

The plain meaning of that sentence is that if I use INCLUDE then I should have duplicate META-INF/hk2-locator/default entries in my final JAR. I did validate that in the course of my troubleshooting, and of course I did have duplicate entries.

What is not clear from the documentation is that if I then add an append or some other reducing transform it will collapse those duplicates, and then I will no longer have duplicates in my final JAR. My solution config uses INCLUDE and does not have duplicate entries, which contradicts that part of the documentation explicitly.

That line should probably read:

INCLUDE: Duplicate foo/bar entries will **contribute** to the final JAR.

This issue appears to be a duplicate of #1884.

It is not a duplicate of that. I mentioned that I tried mergeServiceFiles, but it did not fit my use case. That's not a defect with mergeServiceFiles. It's not designed to handle HK2 locators, and HK2 locators are not part of the Service Provider Interface paradigm. That first paragraph is just background narrative.

[hungarian-notation]

I suppose that its tangentially related to the fact that mergeServiceFiles has special interactions with DuplicatesStrategy, but only in that the documentation implies that those special interactions extend to "ResourceTransformers like ServiceFileTransformer" without clarifying that that means.

I never even tried mergeServiceFiles with a DuplicatesStrategy, for the record. The documentation is clear enough on that point.

Are there other transformers with special cases? That's one of the questions I still have that lead me to an issue rather than a pull request with clearer language.

[Goooler]

If the transformers aim to merge files with the same path, both transformers need to override the duplicatesStrategy. We could probably mention this in the documentation.