Maven Flatten Plugin – flatten:flatten

flatten:flatten

Full name:

org.codehaus.mojo:flatten-maven-plugin:1.6.0:flatten

Description:

This MOJO realizes the goal flatten that generates the flattened POM and #isUpdatePomFile() potentially updates the POM file so that the current org.apache.maven.project.MavenProject's file points to the flattened POM instead of the original pom.xml file. The flattened POM is a reduced version of the original POM with the focus to contain only the important information for consuming it. Therefore information that is only required for maintenance by developers and to build the project artifact(s) are stripped. Starting from here we specify how the flattened POM is created from the original POM and its project:


Element	Transformation	Note
`modelVersion`	Fixed to "4.0.0"	New maven versions will once be able to evolve the model version without incompatibility to older versions if flattened POMs get deployed.
`groupId` `artifactId` `version` `packaging`	resolved	copied to the flattened POM but with inheritance from `parent` as well as with all variables and defaults resolved. These elements are technically required for consumption.
`licenses`	resolved	copied to the flattened POM but with inheritance from `parent` as well as with all variables and defaults resolved. The licenses would not be required in flattened POM. However, they make sense for publication and deployment and are important for consumers of your artifact.
`Model#getDependencies() dependencies`	resolved specially	flattened POM contains the actual dependencies of the project. Test dependencies are removed. Variables and `Model#getDependencyManagement() dependencyManagement` is resolved to get fixed dependency attributes (especially `version`). If `#isEmbedBuildProfileDependencies() embedBuildProfileDependencies` is set to `true`, then also build-time driven `org.apache.maven.model.Profile`s will be evaluated and may add `dependencies`. For further details see `org.apache.maven.model.Profile`s below.
`profiles`	resolved specially	only the `org.apache.maven.model.Activation` and the `dependencies` of a `org.apache.maven.model.Profile` are copied to the flattened POM. If you set the parameter `embedBuildProfileDependencies` to `true` then only profiles `activated` by `JDK` or `OS` will be added to the flattened POM while the other profiles are triggered by the current build setup and if activated their impact on dependencies is embedded into the resulting flattened POM.
`name` `description` `url` `inceptionYear` `organization` `scm` `developers` `contributors` `mailingLists` `Model#getPluginRepositories() pluginRepositories` `issueManagement` `ciManagement` `Model#getDistributionManagement() distributionManagement`	configurable	Will be stripped from the flattened POM by default. You can configure all of the listed elements inside `pomElements` that should be kept in the flattened POM (e.g. <pomElements><name/><description/><developers/><contributors/></pomElements>). For common use-cases there are predefined modes available via the parameter `flattenMode` that should be used in preference.
`prerequisites`	configurable	Like above but by default NOT removed if packaging is "maven-plugin".
`Model#getRepositories() repositories`	configurable	Like two above but by default NOT removed. If you want have it removed, you need to use the parameter `pomElements` and configure the child element `repositories` with value `flatten`.
`parent` `build` `Model#getDependencyManagement() dependencyManagement` `Model#getProperties() properties` `Model#getModules() modules` `Model#getReporting() reporting`	configurable	These elements should typically be completely stripped from the flattened POM. However for ultimate flexibility (e.g. if you only want to resolve variables in a POM with packaging pom) you can also configure to keep these elements. We strictly recommend to use this feature with extreme care and only if packaging is pom (for "Bill of Materials"). In the latter case you configure the parameter `flattenMode` to the value `bom`. If the `build` element contains plugins in the `build/plugins` section which are configured to load extensions, a reduced `build` element containing these plugins will be kept in the flattened pom.

Attributes:

Requires a Maven project to be executed.
The goal is thread-safe and supports parallel builds.

Optional Parameters

Name Type Since Description

<defaultOperation> ElementHandling 1.6.0 The default operation to use when no element handling is given. Defaults to flatten.
Default: flatten
User Property: flatten.dependency.defaultOperation

<embedBuildProfileDependencies> Boolean - Profiles activated by OS or JDK are valid ways to have different dependencies per environment. However, profiles activated by property of file are less clear. When setting this parameter to true, the latter dependencies will be written as direct dependencies of the project. This is not how Maven2 and Maven3 handles dependencies. When keeping this property false, all profiles will stay in the flattened-pom.
Default: false

<flattenDependencyMode>

FlattenDependencyMode

-

The different possible values for flattenDependencyMode:

Mode

Description

direct

Flatten only the direct dependency versions. This is the default mode and compatible with Flatten Plugin prior to 1.2.0.

all

Flatten both direct and transitive dependencies. This will examine the full dependency tree, and pull up all transitive dependencies as a direct dependency, and setting their versions appropriately.

This is recommended if you are releasing a library that uses dependency management to manage dependency versions.

User Property: flatten.dependency.mode

<flattenedPomFilename> String - The filename of the generated flattened POM file.
Default: .flattened-pom.xml
User Property: flattenedPomFilename

<flattenMode>

FlattenMode

-

The different possible values for flattenMode:

Mode	Description
oss	For Open-Source-Software projects that want to keep all `optional POM elements` except for `Model#getRepositories() repositories` and `Model#getPluginRepositories() pluginRepositories`.
ossrh	Keeps all `optional POM elements` that are required for OSS Repository-Hosting.
bom	Like `ossrh` but additionally keeps `Model#getDependencyManagement() dependencyManagement` and `Model#getProperties() properties`. Especially it will keep the `Model#getDependencyManagement() dependencyManagement` as-is without resolving parent influences and import-scoped dependencies. This is useful if your POM represents a BOM (Bill Of Material) and you do not want to deploy it as is (to remove parent and resolve version variables, etc.).
defaults	The default mode that removes all `optional POM elements` except `Model#getRepositories() repositories`.
clean	Removes all `optional POM elements`.
fatjar	Removes all `optional POM elements` and all `Model#getDependencies() dependencies`.
resolveCiFriendliesOnly	Only resolves variables revision, sha1 and changelist. Keeps everything else. See Maven CI Friendly for further details.

User Property: flatten.mode

<keepCommentsInPom> boolean 1.3.0 The core maven model readers/writers are discarding the comments of the pom.xml. By setting keepCommentsInPom to true the current comments are moved to the flattened pom.xml. Default value is false (= not re-adding comments).
Default: false
User Property: flatten.dependency.keepComments

<omitExclusions> boolean 1.3.0 Dictates whether dependency exclusions stanzas should be included in the flattened POM. By default exclusions will be included in the flattened POM but if you wish to omit exclusions stanzas from being present then set this configuration property to true.
Default: false

<outputDirectory> File - The directory where the generated flattened POM file will be written to.
Default: ${project.basedir}

<pomElements> FlattenDescriptor - The org.apache.maven.model.Model that defines how to handle additional POM elements. Please use flattenMode in preference if possible. This parameter is only for ultimate flexibility.

<skip> boolean 1.6.0 If true the plugin will be skipped.
Default: false
User Property: flatten.skip

<skipFlatten> boolean 1.6.0 If true the flatten goal will be skipped.
Default: false
User Property: flatten.flatten.skip

<updatePomFile> Boolean - The flag to indicate if the generated flattened POM shall be set as POM file to the current project. By default this is only done for projects with packaging other than pom. You may want to also do this for pom packages projects by setting this parameter to true or you can use false in order to only generate the flattened POM but never set it as POM file. If flattenMode is set to bom the default value will be true.
User Property: updatePomFile

Parameter Details

<defaultOperation>

The default operation to use when no element handling is given. Defaults to flatten.

Type: org.codehaus.mojo.flatten.ElementHandling
Since: 1.6.0
Required: report.plugin.goal.no
User Property: flatten.dependency.defaultOperation
Default: flatten

<embedBuildProfileDependencies>

Profiles activated by OS or JDK are valid ways to have different dependencies per environment. However, profiles activated by property of file are less clear. When setting this parameter to true, the latter dependencies will be written as direct dependencies of the project. This is not how Maven2 and Maven3 handles dependencies. When keeping this property false, all profiles will stay in the flattened-pom.

Type: java.lang.Boolean
Required: report.plugin.goal.no
Default: false

<flattenDependencyMode>

The different possible values for flattenDependencyMode:

Mode	Description
direct	Flatten only the direct dependency versions. This is the default mode and compatible with Flatten Plugin prior to 1.2.0.
all	Flatten both direct and transitive dependencies. This will examine the full dependency tree, and pull up all transitive dependencies as a direct dependency, and setting their versions appropriately. This is recommended if you are releasing a library that uses dependency management to manage dependency versions.

Mode

Description

direct

Flatten only the direct dependency versions. This is the default mode and compatible with Flatten Plugin prior to 1.2.0.

all

Flatten both direct and transitive dependencies. This will examine the full dependency tree, and pull up all transitive dependencies as a direct dependency, and setting their versions appropriately.

This is recommended if you are releasing a library that uses dependency management to manage dependency versions.

Type: org.codehaus.mojo.flatten.FlattenDependencyMode
Required: report.plugin.goal.no
User Property: flatten.dependency.mode

<flattenedPomFilename>

The filename of the generated flattened POM file.

Type: java.lang.String
Required: report.plugin.goal.no
User Property: flattenedPomFilename
Default: .flattened-pom.xml

<flattenMode>

The different possible values for flattenMode:

Mode	Description
oss	For Open-Source-Software projects that want to keep all `optional POM elements` except for `Model#getRepositories() repositories` and `Model#getPluginRepositories() pluginRepositories`.
ossrh	Keeps all `optional POM elements` that are required for OSS Repository-Hosting.
bom	Like `ossrh` but additionally keeps `Model#getDependencyManagement() dependencyManagement` and `Model#getProperties() properties`. Especially it will keep the `Model#getDependencyManagement() dependencyManagement` as-is without resolving parent influences and import-scoped dependencies. This is useful if your POM represents a BOM (Bill Of Material) and you do not want to deploy it as is (to remove parent and resolve version variables, etc.).
defaults	The default mode that removes all `optional POM elements` except `Model#getRepositories() repositories`.
clean	Removes all `optional POM elements`.
fatjar	Removes all `optional POM elements` and all `Model#getDependencies() dependencies`.
resolveCiFriendliesOnly	Only resolves variables revision, sha1 and changelist. Keeps everything else. See Maven CI Friendly for further details.

Type: org.codehaus.mojo.flatten.FlattenMode
Required: report.plugin.goal.no
User Property: flatten.mode

<keepCommentsInPom>

The core maven model readers/writers are discarding the comments of the pom.xml. By setting keepCommentsInPom to true the current comments are moved to the flattened pom.xml. Default value is false (= not re-adding comments).

Type: boolean
Since: 1.3.0
Required: report.plugin.goal.no
User Property: flatten.dependency.keepComments
Default: false

<omitExclusions>

Dictates whether dependency exclusions stanzas should be included in the flattened POM. By default exclusions will be included in the flattened POM but if you wish to omit exclusions stanzas from being present then set this configuration property to true.

Type: boolean
Since: 1.3.0
Required: report.plugin.goal.no
Default: false

<outputDirectory>

The directory where the generated flattened POM file will be written to.

Type: java.io.File
Required: report.plugin.goal.no
Default: ${project.basedir}

<pomElements>

The org.apache.maven.model.Model that defines how to handle additional POM elements. Please use flattenMode in preference if possible. This parameter is only for ultimate flexibility.

Type: org.codehaus.mojo.flatten.FlattenDescriptor
Required: report.plugin.goal.no

<skip>

If true the plugin will be skipped.

Type: boolean
Since: 1.6.0
Required: report.plugin.goal.no
User Property: flatten.skip
Default: false

<skipFlatten>

If true the flatten goal will be skipped.

Type: boolean
Since: 1.6.0
Required: report.plugin.goal.no
User Property: flatten.flatten.skip
Default: false

<updatePomFile>

The flag to indicate if the generated flattened POM shall be set as POM file to the current project. By default this is only done for projects with packaging other than pom. You may want to also do this for pom packages projects by setting this parameter to true or you can use false in order to only generate the flattened POM but never set it as POM file. If flattenMode is set to bom the default value will be true.

Type: java.lang.Boolean
Required: report.plugin.goal.no
User Property: updatePomFile