Code
Usage Guide
Parameters used in any execution
ParameterRequiredDescription phaseno (default: compile)The desired phase can easily be redefined here. Typically used phases are: compile, test and prepare-package. goalyesAlways "replace". outputDirnoDestination directory relative to the baseDir for all replaced files to be written to. outputBasedirnoDestination directory relative to the execution directory for all replaced files to be written to. Use with outputDir to have files written to a specific base location. basedirnoPath to base relative files for replacements from. This feature is useful for multi-module projects. preserveDirno (default: true)Preserve the directory structure of files found with the includes parameter when writing to the outputDir. quietno (default: false)Stops printing a summary of files that have had replacements performed upon them when true. ignoreErrorsno (default: false)Ignore any errors with missing files or any other exceptions caused by this plugin. The Maven build will continue and log an error if ignoreErrors is set to true and an error occurs. maxReplacementsnoMaximum number of files allowed for replacements.Selecting which files to perform replacements upon
ParameterRequiredDescription includes:include(see note below)List of files to include for multiple (or single) replacement. In Ant format (*/directory/**.properties) and works in conjunction with basedir. Note: There is no longer a default for basedir and this must be an absolute path if not using a basedir.
excludes:excludenoList of files to exclude (must have some includes) for multiple (or single) replacement. In Ant format (**/directory/do-not-replace.properties). The files replaced will be derived from the list of includes and excludes. Files not found are ignored by default.
filesToInclude(see note below)List of comma separated files to include for multiple (or single) replacement. In Ant format (*/directory/**.properties). Files not found are ignored by default.
filesToExcludenoList of comma separated files to exclude (must have some includes) for multiple (or single) replacement. In Ant format (**/directory/do-not-replace.properties). The files replaced will be derived from the list of includes and excludes.
file(see note below)Path to single file to replace tokens in. The file must be text (ascii). Based on current execution path.
encodingno (default: uses maven property ${project.build.sourceEncoding})File encoding used for reading and writing files different from the ${project.build.sourceEncoding}.
ignoreMissingFileno (default: false)Set to true to not fail build if the file is not found. First checks if file exists and exits without attempting to replace anything. Only usable with file parameter.
outputFileno (default: file)The input file is read and the final output (after replacing tokens) is written to this file. The path and file are created if it does not exist. If it does exist, the contents are overwritten. You should not use outputFile when using a list of includes.
inputFilePatternnoRegular expression to match upon the name of the file being replaced. Use groups to match the fragments to make use of within outputFilePattern. This parameter will have no effect without outputFilePattern also being used.
outputFilePatternnoExpression for making use of the matched groups from inputFilePattern for creating your output file's name. This parameter will have no effect without inputFilePattern also being used. Ensure you are using the Java standard's group identifies (i.e. $1, $2, etc).
Note: You must either supply a file, or list of includes (excludes are optional).
Parameters for replacing text
ParameterRequiredDescription token(see note below)The text to replace within the given file. This may or may not be a regular expression (see regex notes above). tokenValueMap(see note below)A file containing tokens and respective values to replace with. This file may contain multiple entries to support a single file containing different tokens to have replaced. Each token/value pair should be in the format: "token=value" (without quotations). If your token contains ='s you must escape the = character to \=. e.g. tok\=en=value variableTokenValueMap(see note below)Similar to tokenValueMap but incline configuration inside the pom. Token/Value pairs are separated by a comma (",") instead of new lines. This parameter may contain multiple entries to support a single file containing different tokens to have replaced. Each token/value pair should be in the format: "token1=value1,token2=value2" (without quotations). commentsEnabledno (default: true)Enables comments within the tokenValueMap (denoted by '#'). If your token starts with an '#', then you must supply the commentsEnabled parameter and with a value of false. tokenFile(see note below)A file containing the token to be replaced. May be multiple words or lines. This is useful if you do not wish to expose the token within your pom or the token is long. valueno (default: empty)The text to be written over any found tokens. If no value is given, the tokens found are replaced with an empty string (effectively removing any tokens found). You can also reference grouped regexp matches made in the token here by $1, $2, etc. valueFilenoA file containing a value to replace the given token with. May be multiple words or lines. This is useful if you do not wish to expose the value within your pom or the value is long. regexno (default: true)Indicates if the token should be located with regular expressions. This should be set to false if the token contains regex characters which may miss the desired tokens or even replace the wrong tokens. regexFlags:regexFlagno (list cannot be empty if used)List of standard Java regular expression Pattern flags (see Java Doc). May contain multiple flags. May only be of the following: CANON_EQ, CASE_INSENSITIVE, COMMENTS, DOTALL, LITERAL, MULTILINE, UNICODE_CASE, UNIX_LINES. replacements:replacementno (list of token/value pairs to replace within the given file)Each replacement element to contain sub-elements as token/value pairs. Each token within the given file will be replaced by it's respective value. unescapeno (does not unescape by default)Unescapes tokens and values which contain escaped special characters. e.g. token\n123 would match tokens: token(new line)123. delimiters:delimiternoAdd a list of delimiters which are added on either side of tokens to match against. e.g. @ would match @token@. You may also use the '' character to place the token in the desired location for matching. e.g. ${} would match ${token}. xpathnoUse X-Path to locate a document node to perform replacements upon. This parameter takes an X-Path expression. Since 1.4.0 - Issue 58.Note: Either a token, tokenFile or tokenValueMap is required. An execution should not contain more than one of these.
Examples
Complete examples can be found in the plugin's test utility. http://code.google.com/p/maven-replacer-plugin/source/browse/test-plugin-use/pom.xml
Single regex file replacement with output file:
<build>
<plugins>
...
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>(version)</version>
<executions>
<execution>
<phase>prepare-package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<ignoreMissingFile>true</ignoreMissingFile>
<file>target/someapp/jsp/helloWorld.jsp</file>
<outputFile>
target/someapp/jsp/helloWorld-updated.jsp
</outputFile>
<regex>false</regex>
<token>$BUILD_NUMBER$</token>
<value>${buildNumber}</value>
</configuration>
</plugin>
...
</plugins>
</build>
Using regular expression flags:
<build>
<plugins>
...
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>(version)</version>
<executions>
<execution>
<phase>prepare-package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<file>target/someapp/jsp/helloWorld.jsp</file>
<token>ToKeN</token>
<value>value</value>
<regexFlags>
<regexFlag>CASE_INSENSITIVE</regexFlag>
<regexFlag>MULTILINE</regexFlag>
</regexFlags>
</configuration>
</plugin>
...
</plugins>
</build>
Multiple file replacement:
<build>
<plugins>
...
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>(version)</version>
<executions>
<execution>
<phase>prepare-package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<includes>
<include>target/**/replace-me.*</include>
</includes>
<excludes>
<exclude>target/**/do-not-replace-me.*</exclude>
</excludes>
<token>TOKEN</token>
<value>VALUE</value>
</configuration>
</plugin>
...
</plugins>
</build>
Single file replacement using a tokenValueMap:
<build>
<plugins>
...
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>(version)</version>
<executions>
<execution>
<phase>prepare-package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<file>target/classes/database.properties</file>
<tokenValueMap>etc/${environment}/database.conf</tokenValueMap>
</configuration>
</plugin>
...
</plugins>
</build>
Multiple token/value replacements per file:
<build>
<plugins>
...
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>(version)</version>
<executions>
<execution>
<phase>prepare-package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<file>target/classes/database.properties</file>
<replacements>
<replacement>
<token>token1</token>
<value>value1</value>
</replacement>
<replacement>
<token>token2</token>
<value>value2</value>
</replacement>
</replacements>
</configuration>
</plugin>
...
</plugins>
</build>
Notes on some difficulties integrating maven-replacer-plugin into your build:
The phase and time of execution depends largely on the desired use and the type of packaging. There can be issues with WAR packaging and replacing content at the right time to be included up by the WAR (See Usage with other plugins).