The ProblemYou just cloned a fresh Git repository and everything looks fine until you head into a specific subfolder. Instead of the library or shared component you expected, the directory is a ghost town—completely empty. When you try to compile your code or run a build script, Git kills the process with a frustrating error:
Submodule path 'folder_name' not initialized. Use 'git submodule update --init' to fix it.
This happens because a standard git clone only grabs the main project's files. Git treats submodules as separate entities. It leaves those folders as empty shells until you specifically ask for the content.
Why Git Leaves Submodules EmptyThink of a submodule as a bookmark. The main repository (the 'superproject') doesn't actually store the submodule's files. Instead, it stores a tiny pointer—a specific 40-character commit hash—that tells Git which version of the external repo to use. When you clone the main repo, Git sees the pointer but waits for your command before downloading 100MB of external library data.
Solution 1: Fixing a Repository You Already ClonedIf you have already cloned the project and are staring at empty folders, you can fix it in seconds. Run these commands from the root of your project.
Step 1: Register the SubmodulesFirst, you need to tell Git to look at your .gitmodules file and set up your local configuration.
git submodule init
Step 2: Fetch the DataNow, tell Git to actually reach out to the remote server and download the files. This command checks out the specific commit hash recorded in your main project.
git submodule update
The Pro ShortcutMost developers just combine these into one command. It is faster and handles nested submodules (submodules inside submodules) that would otherwise stay empty.
git submodule update --init --recursive
Use the --recursive flag every time. It saves you from manual troubleshooting if the project structure is complex.
Solution 2: Prevent the Error During Your Initial CloneYou can avoid this entire headache by pulling everything down at once. When cloning a new project, add a single flag to your command:
git clone --recurse-submodules https://github.com/username/repository.git
If you are using a version of Git older than 2.13, you might need to use --recursive instead. Modern versions (2.13 and up) prefer --recurse-submodules, but both generally achieve the same result.
How to Verify the FixOnce the commands finish, you should see files in your folders. However, it is better to let Git confirm the status for you.
1. List the FilesCheck the folder size or list the hidden files to make sure the .git file exists inside the submodule:
ls -la folder_name/
2. Check Git's Internal StatusRun the submodule status command to see exactly what Git thinks of your local files:
git submodule status
Look at the character prefix. A - means the submodule is still not initialized. A + means the files are there, but the version you have checked out doesn't match what the main repo expects. A simple space (no prefix) means everything is perfect.
Troubleshooting Common Pitfalls### Missing .gitmodules FileIf git submodule init does nothing, check your project root for a .gitmodules file. This text file acts as a map. If it is missing, Git has no idea where the submodule lives. A healthy file looks like this:
[submodule "folder_name"]
path = folder_name
url = https://github.com/example/library.git
Authentication FailuresSubmodule updates often fail if the submodule is a private repository. If the main repo uses HTTPS but the submodule uses SSH, Git might prompt for keys you haven't set up. Make sure you have access to the submodule's URL independently before running the update.
The Detached HEAD StateAfter running git submodule update, your submodule will be in a 'Detached HEAD' state. Don't panic; this is normal. Git is pointing to a specific commit, not a branch name. If you need to write code inside that submodule, move to a branch first by running git checkout main inside that specific folder.
Forcing a Clean SlateSometimes a submodule update fails because you accidentally changed a file inside that folder. If you just want to wipe those changes and get the correct files, add the force flag:
git submodule update --init --recursive --force