Chapter 29. The IDEA Plugin

To completely overwrite existing IDEA files, execute a clean task together with its corresponding generation task, for example gradle cleanIdea idea (in that order). If you want to make this the default behavior, add idea.dependsOn(cleanIdea) to your build script. This makes it unnecessary to execute the clean task explicitly.

Complete overwrite works equally well for individual files, for example by executinggradle cleanIdeaModule ideaModule.

A complete overwrite causes all existing content to be discarded, thereby losing any changes made directly in the IDE. The beforeConfigured hook makes it possible to overwrite just certain parts of the existing content. The following example removes all existing dependencies from the Module domain object:

ideaModule {
    beforeConfigured { module ->
        module.dependencies.clear()
    }
}

The resulting module file will only contain Gradle-generated dependency entries, but not any other dependency entries that may have been present in the original file. (In the case of dependency entries, this is also the default behavior.) Other sections of the module file will be either left as-is or merged. The same could be done for the module paths in the project file:

ideaProject {
    beforeConfigured { project ->
        project.modulePaths.clear()
    }
}

The whenConfigured hook allows to manipulate the fully populated domain objects. Often this is the preferred way to customize IDEA files. Here is how you would export all the dependencies of an IDEA module:

ideaModule {
    whenConfigured { module ->
        module.dependencies*.exported = true
    }
}

The withXmlhook allows to manipulate the in-memory XML representation just before the file gets written to disk. Although Groovy's XML support makes up for a lot, this approach is less convenient than manipulating the domain objects. In return, you get total control over the generated file, including sections not modeled by the domain objects.

ideaProject {
    withXml { provider ->
        provider.node.component.find { it.@name == 'VcsDirectoryMappings' }.mapping.@vcs = 'Git'
    }
}