Manage Git Submodules in GitKraken Desktop

Last updated: June 2025

Submodules allow you to include another Git repository inside a parent repository. Use submodules to incorporate independent projects while maintaining separate commit histories.

Enable the Submodules Pane

To toggle the Submodules pane:

1. Right-click any pane header in the Left Panel.
2. Check or uncheck “Submodules” to show or hide the pane.

Add a Submodule

To add a submodule:

1. Hover over Submodules in the Left Panel.
2. Click the + icon.
3. Paste the HTTPS or SSH repository URL.
4. Enter the desired path.

Adding a submodule updates the .gitmodules file and references the submodule commit.

When cloning the parent repository, you’ll be prompted to initialize the submodule to fetch and checkout its commit.

Update a Submodule

To update a submodule:

1. Open the Submodules pane.
2. Right-click the submodule.
3. Select Update to fetch the latest commit.

When cloning a repository that includes submodules, GitKraken prompts you to initialize them.

Change the Pointer Commit

To update the tracked commit:

1. Open the submodule in GitKraken Desktop.
2. Check out a new commit or branch.
3. Exit the submodule to return to the parent repo.

GitKraken will prompt you to save the updated pointer commit.

Submodule Statuses

Possible submodule states and how to resolve them:

• Out of sync: The pointer commit changed. Stash, commit, or discard changes.
• Added but not initialized: Right-click and select Initialize.
• Added and initialized but not committed: Commit the submodule folder and update .gitmodules.

Keep Submodules Up to Date

Enable automatic submodule updates:

• Globally: Preferences > General
• Per repository: Preferences > Submodules

Subtree Support

GitKraken Desktop does not support subtree workflows in-app.