What is the purpose of dependency-reduced-pom.xml generated by the shade plugin?

I read over the docs and didn't find anything that talks about what it's used for.

The shade:shade Mojo is quite well documented, here especially about the createDependencyReducedPom parameter, which will create that dependency-reduced-pom.xml file: maven-shade-plugin/shade-mojo.html#createDependencyReducedPom

In short, this is quite useful if you intend to use that shaded JAR (instead of the normal JAR) as a dependency for another module. That dependency-reduced-pom.xml will not contain the JARs already present in the shaded one, avoiding useless duplication.

I read the docs about a hundred times or so and still couldn't understand what this is for, what really is the use case for it.

Finally this is what I think: lets say you have a project with dependencies A, B, C, D, E. In the pom.xml you configure the shade plugin in such a way that when it creates the uber-jar (call it foo.jar), it includes A, B, C in the shaded jar but for some reason you decide not to include D, E in the shaded jar even though your project depends on them - a case in point are dependencies that are needed only for testing (e.g. any dependency that has a scope of test and is not included in the shaded jar). The dependency-reduced-pom.xml will define D, E in it. The idea is that if someone wants to use foo.jar the dependency-reduced-pom.xml provides a hint of some sort that beware foo.jar is missing dependencies D, E in it - use at your own risk. You might then decide to explicitly add D, E in the project that will use foo.jar.

So the dependency-reduced-pom.xml is more like missing-dependencies.xml and lists the dependencies which are missing in the uber-jar which is output by the shade plugin.

Short Answer

The dependency-reduced-pom.xml removes transitive dependencies which are already in your shaded jar. This prevents consumers from pulling them in twice.

Long Answer

There are several reasons to shade a jar.

If you are producing an executable jar with all of its dependencies bundled, then you are probably uploading it to a package repository and users are downloading it manually. In this scenario, the dependency-reduced-pom.xml doesn't do anything for you.

Another reason is because you are building a library and are using specific versions of other common libraries. You don't want to force your users to use the same version as you. By shading, you effectively namespace those dependencies and your users can then include the same libraries again, but on different versions.

In this case, if you upload the original pom, then users who depend on your library will end up pulling in all dependencies twice. Once from the shaded copies and once from the copies declared in the pom. Uploading the dependency-reduced-pom.xml instead prevents this from happening because the shaded dependency declarations are removed.

The purpose of dependency-reduced-pom.xml is to show you what is the final dependency set of the artifact that you are preparing.

Let's say artifact X depends on A and B. By embedding B dependency with maven-shade-plugin we create an artifact that depends only on A and this is what dependency-reduced-pom.xml will tell you (B dependency will not be in that file). This is the file that will be installed in Maven repository instead of original pom.xml. It will be used where calculating dependency set of artifact X, so if any other module depends on X it will not depend on B.