Working with Submodule Branches
Learn how to manage and switch branches within a submodule and push changes back to the submodule's origin.
Working with Submodule Branches is a free Git Advanced: Monorepo, Submodules & Workflows lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Git Advanced: Monorepo, Submodules & Workflows learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Branching in Submodules
Git submodules usually point to a specific commit. But what if you need to actively develop inside a submodule?
- This allows independent feature development.
- You can contribute changes back to the submodule's own project.
- It's key for complex projects needing tight integration.
Submodules: Detached HEAD
By default, when you clone a project with submodules, each submodule is checked out to a specific commit. This is called a "detached HEAD" state.
- It means you're not currently on any named branch.
- You can view files, but new commits won't automatically belong to a branch.
- It provides a stable way for the parent repo to reference specific submodule versions.
Navigating into a Submodule
To work with a submodule's branches, you first need to navigate into its directory. Think of it as entering a completely separate Git repository.
Use the cd command to change directories:
# Assume 'my-submodule' is a submodule
cd my-submodule
git statusChecking Submodule Status
Once inside the submodule's directory, you can use regular Git commands to see its status, branches, and current HEAD. This helps you understand its current state.
# Inside the submodule directory
git status
git branch
git log --oneline -1Switching Submodule Branches
To develop within a submodule, you need to switch from a detached HEAD to a specific branch. Use git checkout just like in any other Git repository.
# Inside the submodule directory
git checkout main
# Or to create and switch to a new branch
git checkout -b new-featureCommitting in a Submodule
Now that you're on a branch, you can make changes, add them, and commit them. These commits are specific to the submodule's repository, not the parent repository.
# Inside the submodule directory
echo "New content" > newfile.txt
git add newfile.txt
git commit -m "Added newfile in submodule"Pushing Submodule Changes
After committing changes within the submodule, you need to push them to the submodule's own remote repository. This makes your changes available to others.
# Inside the submodule directory
git push origin main
# Or to push a new branch
git push origin new-featureUpdating the Parent Repository
After pushing changes in the submodule, the parent repository still points to the old commit. You need to tell the parent repo to track the new commit.
- Navigate back to the parent repository.
- Stage and commit the submodule's change.
# Back in the parent repository
cd .. # Go up one level
git status
git add my-submodule
git commit -m "Updated my-submodule to latest commit"
git push origin mainSubmodule Branching Tips
Working with submodule branches requires care and coordination:
- Communicate: Inform your team if you're actively developing on a submodule branch.
- Keep parent updated: Always commit the submodule reference change in the parent repo after pushing submodule changes.
- Avoid direct pushes: Don't push to a submodule's
mainbranch from the parent repo unless absolutely necessary; work inside the submodule itself.
Submodule Branch Quiz
Test your knowledge on managing submodule branches!
Recap: Submodule Branches
In this lesson, we explored how to actively develop within a Git submodule:
- Navigating into the submodule's directory.
- Switching from a detached HEAD to a specific branch.
- Making, committing, and pushing changes in the submodule.
- Updating the parent repository's reference to the new submodule commit.
This workflow enables independent development and contribution to submodule projects, making your overall project more flexible.
Frequently asked questions
Is the “Working with Submodule Branches” lesson free?
Yes — the full text of “Working with Submodule Branches” is free to read here on the web, and the Git Advanced: Monorepo, Submodules & Workflows course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Git Advanced: Monorepo, Submodules & Workflows course, upgrade to CoddyKit PRO.
What will I learn in “Working with Submodule Branches”?
Learn how to manage and switch branches within a submodule and push changes back to the submodule's origin. You practise Git Advanced: Monorepo, Submodules & Workflows with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Git Advanced: Monorepo, Submodules & Workflows?
No prior experience is required. Git Advanced: Monorepo, Submodules & Workflows on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Working with Submodule Branches” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Git Advanced: Monorepo, Submodules & Workflows lesson?
Yes. Every Git Advanced: Monorepo, Submodules & Workflows lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Working with Submodule Branches
- Nested Submodules and Complex Setups
- Common Submodule Issues & Fixes
- Pinning Submodules to Specific Tags and Commits