Multi-module Projects

Have multiple Git repositories in one IDE project for better cross-references. This is beneficial especially for Antora projects.

Situation

The user is working with AsciiDoc or Antora content in several Git repositories.

If the projects can contain standard AsciiDoc content, the user might want to benefit from auto-completion on attribute names.

When the Git repositories contain Antora components, the user wants to use cross-references and auto-completion when referencing content in another component.

Supported as of 0.34.2 of the plugin: In another situation, a playbook might be in one repository, while the components reside in a different repository, and the user wants auto-completion for attributes defined in the playbook when editing components.

Solution

Create a project with multiple modules in the IDE. Each module will be backed by its own Git repository. Despite multiple Git repositories, the IDE will show it as one project with multiple modules.

The alternative: the user can check out all repositories in separate folders below the main folder, and then open the main folder as the project folder in the IDE.

Tradeoffs of a multi-module project

Once the setup is complete, the IDE’s view for Git will show a combined history for all Git repositories added in the following steps. Depending on the user’s needs, this might be helpful in the long term and confusing at the beginning.

To help with multiple Git repositories,

  • the Git tool window allows filtering the view via the Paths dropdown, and

  • color coding for the Git history indicates which repository a commit belongs to.

Setup

Users find an extensive description of how to do this in the IDE’s docs. The following paragraph gives a quick start.

Pre-requisites

This assumes that the different Git repositories are already checked-out on the user’s local file system.

Creating a multi-module project

  1. Start with the main Git repository and open it in the IDE. This project will be the project the user will open to work with all Git repositories added in the following steps.

  2. Select the existing top-level module in the project in the project view.

  3. Choose File  Project Structure…​  Modules. Click on and Import Module.

  4. Select the folder with the other Git repository and press OK.

  5. Choose option Import module from external model if the repository contains sources from a build tool you recognize, or Create module from existing sources if not.

  6. Depending on the external model, complete the following dialogs.

  7. Repeat from step two for all Git repositories that should be added.