Manage Git Submodules in GitKraken Desktop

Last updated: February 2026

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

Quick Start

Add, update, and manage Git submodules in GitKraken Desktop from the Left Panel.

To show the Submodules pane: Right-click any Left Panel header and check Submodules.

To add a submodule:

Hover over Submodules in the Left Panel and click the + icon.
Paste the HTTPS or SSH repository URL and enter the desired path.
GitKraken Desktop updates .gitmodules and references the submodule commit.

To update a submodule: Open the Submodules pane, right-click the submodule, and select Update to fetch its latest commit.

To change the tracked commit: Open the submodule in GitKraken Desktop, check out a new commit or branch, then exit the submodule. GitKraken Desktop will prompt you to save the updated pointer.

To enable automatic updates: Go to Preferences > General to update all repos globally, or Preferences > Submodules for per-repository settings.

When cloning a parent repository that includes submodules, GitKraken Desktop will prompt you to initialize them.

Enable the Submodules Pane

To toggle the Submodules pane:

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

GitKraken Desktop Left Panel showing the toggle pane menu with options to show or hide sections like Remote, Pull Requests, Tags, and Submodules — Toggle the Submodules pane from the Left Panel

Add a Submodule

To add a submodule:

Hover over Submodules in the Left Panel.
Click the icon.
Paste the HTTPS or SSH repository URL.
Enter the desired path.

GitKraken Desktop interface showing the Add Submodule modal with fields for Remote URL and Name/Path, and a green Add Submodule button — Add a submodule using HTTPS or SSH URL

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:

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

Context menu in GitKraken Desktop showing options to update, edit, open, or delete the submodule vendor/libgit2 — Update a submodule from the Left Panel

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

Change the Pointer Commit

To update the tracked commit:

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

GitKraken Desktop will prompt you to save the updated pointer commit.

GitKraken Desktop interface showing submodule vendor/libgit2 out-of-sync, with options to commit or discard changes, and view or delete the submodule — Update the pointer commit for a submodule

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.

Have feedback about this article? Did we miss something? Let us know!