第三十九章. IDEA 插件

要完全覆盖现有IDEA文件，请执行clean任务及其相应的生成任务，例如gradle cleanIdea idea（按此顺序）。如果要让它成为默认行为，请添加 tasks.idea.dependsOn(cleanIdea) 到构建脚本中。这样我们就不用显式执行清理任务了。
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 tasks.idea.dependsOn(cleanIdea) to your build script. This makes it unnecessary to execute the clean task explicitly.

完全覆盖同样可以用于个人文件，例如通过执行gradle cleanIdeaModule ideaModule。
Complete overwrite works equally well for individual files, for example by executing gradle cleanIdeaModule ideaModule.

完全覆盖会导致现有的所有内容被丢弃，从而丢失直接在 IDE 中进行的任何更改。beforeMerged 钩子使得可以只覆盖现有内容的某些部分。以下示例为从 Module 域对象中删除现有的所有依赖：
A complete overwrite causes all existing content to be discarded, thereby losing any changes made directly in the IDE. The beforeMerged 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:

idea.module.iml {
    beforeMerged { module ->
        module.dependencies.clear()
    }
}

生成的模块文件将仅包含Gradle生成的依赖项，但不包含原始文件中可能存在的任何其他依赖项。（对于依赖项，这也是默认行为。）模块文件的其他部分将保持原样或合并。对项目文件中的模块路径也可以这样做：

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:

idea.project.ipr {
    beforeMerged { project ->
        project.modulePaths.clear()
    }
}

whenMerged 钩子允许操作完全填充的域对象。通常，这是自定义IDEA文件的首选方法。下面的例子展示了如何导出一个IDEA模块的所有依赖：
The whenMerged 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:

idea.module.iml {
    whenMerged { module ->
        module.dependencies*.exported = true
    }
}

withXml钩子允许在文件写入磁盘之前操作内存中的 XML 表示形式。尽管 Groovy 的 XML 支持对其帮助很大，但这种方法比起操作域对象依然很不方便。作为回报，你可以对生成的文件进行完全的控制，包括未由域对象建模的部分。
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.

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