Commit tool window: Submodule directory shown as a change after submodule add or update – Support | JetBrains

Problem

After adding or modifying a Git submodule in a JetBrains IDE (such as IntelliJ IDEA, WebStorm, PyCharm), the Commit tool window shows the submodule directory as a change that needs to be committed in the parent repository. This appears alongside the expected .gitmodules file change, and recurs whenever the submodule is updated.

Example sequence:

git submodule add https://example.com/my-project-frontend.git frontend-v3
git commit -am "Add frontend v3 as git submodule"
git push

After the next change to the submodule, the frontend-v3 folder reappears in the Commit tool window of the parent repository.

Cause

This is expected Git behavior, not an IDE issue.

A submodule directory entry in the parent repository is not a regular folder. Git stores it as a reference (a "gitlink") to a specific commit in the submodule's own repository. When the submodule is updated to a different commit, the parent repository sees this as a change to the gitlink, because the recorded commit pointer no longer matches the current state.

The IDE displays the gitlink as a folder in the Commit tool window with color coding:

Green — the submodule directory was just added (git submodule add).
Blue — the submodule has modifications, or its HEAD points to a different commit than the one recorded in the parent repository.

Resolution

When adding a new submodule

After running git submodule add, commit and push both items from the parent repository:

The .gitmodules file
The submodule directory entry (the gitlink)

This records the submodule mapping and the initial commit pointer in the parent repository.

When the submodule has been updated

A change to the gitlink in the parent repository means the parent now points to a different commit in the submodule. If the new commit is intended — for example, after switching the submodule to another branch or pulling new commits inside it — commit and push the gitlink change from the parent repository to record the new pointer.

If the change is unintended, revert the submodule directory entry in the Commit tool window before committing.

Working with submodule contents in the same project

By default, content changes inside the submodule are made by opening the submodule as a separate project. To edit and commit submodule contents from within the parent project:

Open Settings (Ctrl+Alt+S on Windows/Linux, ⌘ , on macOS).
Go to Version Control | Directory Mappings.
Add the submodule directory as a separate VCS root mapped to Git.

The submodule then appears as its own repository in the Commit tool window, and changes inside it can be committed and pushed independently of the parent repository.

Additional information