How to Fix Git Submodule Add, "a git directory is found locally" issue
Not interested in the Understanding the issue? Feel free to skip to the solution.
I find one of the most common issues I run into is when I add a Git submodule and get back a response of the "a git directory is found locally" issue.
If you've ever found yourself puzzled by the "a git directory is found locally" issue while trying to add a Git submodule, you're not alone. In this blog post, we're going to demystify this error message and provide a step-by-step solution to get you back on track.
This blog post aims to help you learn about why this problem occurs and how to fix it effectively. So, let's dive right into it!
You may encounter this issue while trying to add a submodule to your repository using the command:
git submodule add <repository_url>
Instead of adding the repository as a submodule, Git responds with a error message:
"a git directory is found locally, rm the '.git' file in <local_directory> to clone."
Understanding the Issue
So, what's going on?
This error typically happens when there's already a '.git' directory present in the directory where you're trying to add the submodule. Git gets confused because it expects the directory to be empty when adding a new submodule.
In order to fix this, there are 5 steps you have to do to get your submodules working again.
For this example, I'm going to use
src/content as the path to the submodule and
email@example.com:curiouslychase/content.git as the git repository URL.
Step 1: Remove the submodule from the cache and the disk
If you haven't already, remove the submodule from the cache using the
git rm --cached command.
Also, remove the submodule directory using
git rm --cached src/content rm -rf src/content
Step 2: Delete the relevant lines from the .gitmodules file
.gitmodules file and delete the section related to your submodule. This usually looks something like this:
[submodule "src/content"] path = src/content url = firstname.lastname@example.org:curiouslychase/content.git
Step 3: Delete the relevant section from
Next, open your
.git/config file and delete the section related to your submodule. It will resemble this:
[submodule "src/content"] url = email@example.com:curiouslychase/content.git
Step 4: Remove the relevant directory from .git/modules
Finally, remove the directory related to your submodule from the
rm -rf .git/modules/src/content
Step 5: Add the submodule back
With your project tidied up, you can now add your submodule without encountering the error:
git submodule add firstname.lastname@example.org:curiouslychase/content.git
If you're regularly adding submodules, always ensure that your target directories are clean and devoid of any '.git' directory before adding a new submodule.
This way, you and Git can continue your version-controlled journey in harmony!Share on Twitter