Usage Guide - beiliubei/maven-replacer-plugin GitHub Wiki

Parameters used in any execution

Parameter Required Default Description
phase no compile The desired phase can easily be redefined here. Typically used phases are: compile, test and prepare-package.
goal yes Always "replace".
outputDir no Destination directory relative to baseDir for all replaced files to be written to.
outputBasedir no Destination 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.
basedir no Path to base relative files for replacements from. This feature is useful for multi-module projects.
preserveDir no true Preserve the directory structure of files found with the includes parameter when writing to the outputDir.
quiet no false Stops printing a summary of files that have had replacements performed upon them when true.
ignoreErrors no 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.
maxReplacements no Maximum number of files allowed for replacements.

Selecting which files to perform replacements upon

Parameter Required Default Description
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:exclude no List 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.
filesToExclude no List 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.
encoding no ${project.build.sourceEncoding} File encoding used for reading and writing files different from the ${project.build.sourceEncoding}.
ignoreMissingFile no 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.
outputFile no 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.
inputFilePattern no Regular 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.
outputFilePattern no Expression 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

Parameter Required Default Description
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).
commentsEnabled no 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.
value no 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.
valueFile no A 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.
regex no 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:regexFlag no If supplied, a non-empty 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:replacement no A 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 its respective value.
unescape no false Unescapes tokens and values which contain escaped special characters. e.g. token\n123 would match tokens: token(new line)123.
delimiters:delimiter no Add 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}.
xpath no Use 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.