Gradle filters resources as it copies them. For a Java project, configure the processResources task for the main source set, then choose expand() for Groovy-template placeholders or filter() for explicit tokens and line-based transformations. Limit filtering to known text files and set an explicit character encoding so binary assets remain unchanged and text output is consistent.
Where Gradle resource filtering happens
Resource filtering is part of Gradle’s file-copy and processing phase, not a runtime substitution feature. The Java plugin copies resources from src/main/resources into processed output; that output is used for packaging and is available on the relevant test runtime classpath. The Gradle Java Plugin documentation describes the resource tasks created for Java projects.
Configure processResources for the main source set. Other source sets have corresponding tasks named processSourceSetResources, such as processTestResources. The ProcessResources DSL reference describes the task that copies resources to their target directory and may process them.
Choose between expand() and filter()
| Approach | Placeholder style | Behavior | Best fit |
|---|---|---|---|
expand() |
$name or ${name} |
Evaluates a Groovy template using values supplied by the build script. | Files intentionally written as Groovy templates. |
filter() with Ant ReplaceTokens |
@name@ |
Replaces named tokens using an Ant filter. | Explicit token markers or a project already using an Ant filter. |
filter() with a transformer |
Line-based, as defined by the transformer | A transformer or closure receives each line and returns replacement text or null to remove it. Filters can be chained. |
Custom line-by-line text processing. |
Gradle’s Working With Files guide covers content filtering and the available copy-spec mechanisms.
#1 Best Overall
Use expand() for Groovy-template placeholders
Pass a map of values to expand(). The template file can then refer to those values with Groovy-style expressions. For example, a template might contain version=${version}.
tasks {
processResources {
expand("version" to version, "buildNumber" to currentBuildNumber)
}
}The equivalent Groovy DSL form is:
processResources {
expand(version: version, buildNumber: currentBuildNumber)
}Template expressions can contain Groovy code, so treat templates as executable expressions: provide deliberate inputs and review who can edit the files. By default, expand() also interprets escape sequences. If backslash escaping must be preserved, configure the expand details rather than assuming backslashes will pass through unchanged; see the Gradle Maven migration guide for the documented expansion example and related configuration.
Rank #2
Use filter() for explicit tokens or line transformations
For Ant-style replacement markers, use Ant’s ReplaceTokens filter. In this example, the resource contains @version@, which is replaced with the project version:
import org.apache.tools.ant.filters.ReplaceTokens
processResources {
filter(ReplaceTokens, tokens: [version: project.version])
}For custom processing, filter() can also accept a transformer or closure that handles lines. Returning null removes a line; returning text supplies its replacement. Multiple filters form a chain, so the order of transformations matters.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRestrict filtering to text files
Content filters assume text-based input. Applying them indiscriminately risks changing images, archives, certificates, or other binary resources. Use path patterns to opt in only the text files that contain placeholders:
tasks.processResources {
filesMatching("**/*.properties", "**/*.json") {
expand(mapOf("version" to project.version))
}
}You can also use filesNotMatching(), eachFile(), or a child CopySpec to control which paths receive processing. Prefer an allowlist of known text extensions when practical; a broad filter on every resource is harder to audit and can corrupt binary files. The ProcessResources DSL reference documents these copy-spec options.
Set the filtering character encoding
When filtered text may contain non-ASCII characters, set filteringCharset explicitly. Otherwise Gradle uses the JVM’s default charset, which can vary between environments and lead to inconsistent output.
processResources {
filteringCharset = 'UTF-8'
}Choose the encoding that matches the resource files and downstream expectations; UTF-8 is a common choice, not a substitute for checking those requirements. The task API documentation describes the filtering charset setting.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Check the processed output
After configuring the task, inspect the processed resource output or the resulting JAR to verify that the intended placeholders were replaced, unrelated text stayed intact, and binary resources were not filtered. In a Java project, the processed resources are the copies Gradle uses for packaging and the relevant test runtime classpath, rather than the original files under src/main/resources.
If migrating from Maven, Maven’s process-resources variable substitution corresponds to configuring Gradle’s processResources task. Gradle’s migration guide demonstrates supplying values through expand().
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
