gradle-plugins/gradle-plugin-shadow/src/docs/asciidoc/13-controlling-merging.adoc

=== Controlling JAR Content Merging

Shadow allows for customizing the process by which the output JAR is generated through the
link:{api}/transformers/Transformer.html[`Transformer`] interface.
This is a concept that has been carried over from the original Maven Shade implementation.
A link:{api}/transformers/Transformer.html[`Transformer`] is invoked for each entry in the JAR before being written to
the final output JAR.
This allows a link:{api}/transformers/Transformer.html[`Transformer`] to determine if it should process a particular
entry and apply any modifications beforewriting the stream to the output.

.Adding a Transformer
[source,groovy,indent=0]
----
shadowJar {
  transform(MyTransformer.class)
}
----

Additionally, a `Transformer` can accept a `Closure` to configure the provided `Transformer`.

.Configuring a Transformer
[source,groovy,indent=0]
----
shadowJar {
  transform(MyTransformer.class) {
    enable = true
  }
}
----

An instantiated instance of a `Transformer` can also be provided.

.Adding a Transformer Instance
[source,groovy,indent=0]
----
shadowJar {
  transform(new MyTransformer(enabled: true))
}
----

==== Merging Service Descriptor Files

Java libraries often contain service descriptors files in the `META-INF/services` directory of the JAR.
A service descriptor typically contains a line delimited list of classes that are supported for a particular __service__.
At runtime, this file is read and used to configure library or application behavior.

Multiple dependencies may use the same service descriptor file name.
In this case, it is generally desired to merge the content of each instance of the file into a single output file.
The link:{api}/transformers/ServiceFileTransformer.html[`ServiceFileTransformer`] class is used to perform this merging.
By default, it will merge each copy of a file under `META-INF/services` into a single file in the output JAR.

.Merging Service Files
[source,groovy,indent=0]
----
shadowJar {
  mergeServiceFiles()
}
----

The above code snippet is a convenience syntax for calling
link:{api}/tasks/ShadowJar.html#transform(Class++<? extends Transformer>++)[`transform(ServiceFileTransformer.class)`].

[NOTE]
====
Groovy Extension Module descriptor files (located at `META-INF/services/org.codehaus.groovy.runtime.ExtensionModule`)
are ignored by the link:{api}/transformers/ServiceFileTransformer.html[`ServiceFileTransformer`].
This is due to these files having a different syntax than standard service descriptor files.
Use the link:{api}/tasks/ShadowJar.html#mergeGroovyExtensionModules()[`mergeGroovyExtensionModules()`] method to merge
these files if your dependencies contain them.
====

===== Configuring the Location of Service Descriptor Files

By default the link:{api}/transformers/ServiceFileTransformer.html[`ServiceFileTransformer`] is configured to merge
files in `META-INF/services`.
This directory can be overridden to merge descriptor files in a different location.

.Merging Service Files in a Specific Directory
[source,groovy,indent=0]
----
shadowJar {
  mergeServiceFiles {
    path = 'META-INF/custom'
  }
}
----

===== Excluding/Including Specific Service Descriptor Files From Merging

The link:{api}/transformers/ServiceFileTransformer.html[`ServiceFileTransformer`] class supports specifying specific
files to include or exclude from merging.

.Excluding a Service Descriptor From Merging
[source,groovy,indent=0]
----
shadowJar {
  mergeServiceFiles {
    exclude 'META-INF/services/com.acme.*'
  }
}
----

==== Merging Groovy Extension Modules

Shadow provides a specific transformer for dealing with Groovy extension module files.
This is due to their special syntax and how they need to be merged together.
The link:{api}/transformers/GroovyExtensionModuleTransformer.html[`GroovyExtensionModuleTransformer`] will handle these
files.
The link:{api}/tasks/ShadowJar.html[`ShadowJar`] task also provides a short syntax method to add this transformer.

.Merging Groovy Extension Modules
[source,groovy,indent=0]
----
shadowJar {
  mergeGroovyExtensionModules()
}
----

==== Appending Text Files

Generic text files can be appended together using the
link:{api}/transformers/AppendingTransformer.html[`AppendingTransformer`].
Each file is appended using new lines to separate content.
The link:{api}/tasks/ShadowJar.html[`ShadowJar`] task provides a short syntax method of
link:{api}/tasks/ShadowJar.html#append(java.lang.String)[`append(String)`] to configure this transformer.

.Appending a Property File
[source,groovy,indent=0]
----
shadowJar {
  append 'test.properties'
}
----

==== Appending XML Files

XML files require a special transformer for merging.
The link:{api}/transformers/XmlAppendingTransformer.html[`XmlAppendingTransformer`] reads each XML document and merges
each root element into a single document.
There is no short syntax method for the link:{api}/transformers/XmlAppendingTransformer.html[`XmlAppendingTransformer`].
It must be added using the link:{api}/tasks/ShadowJar.html#transform(++Class<? extends Transformer>++)[`transform`] methods.

.Appending a XML File
[source,groovy,indent=0]
----
shadowJar {
  tranform(XmlAppendingTransformer.class) {
    resource = 'properties.xml'
  }
}
----