How to Fix Git Submodule Add, "a git directory is found locally" issue

Info

Not interested in the Understanding the issue? Feel free to skip to the solution.

I use Git Submodules in my blog (chaseadams.io) to separately version control my content and public assets from my blog architecture.

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!

The Problem

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.

The Solution

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 git@github.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 rm -rf.

git rm --cached src/content 
rm -rf src/content

Step 2: Delete the relevant lines from the .gitmodules file

Open your .gitmodules file and delete the section related to your submodule. This usually looks something like this:

[submodule "src/content"] 
	path = src/content 
	url = git@github.com:curiouslychase/content.git

Step 3: Delete the relevant section from .git/config

Next, open your .git/config file and delete the section related to your submodule. It will resemble this:

[submodule "src/content"] 
	url = git@github.com:curiouslychase/content.git

Step 4: Remove the relevant directory from .git/modules

Finally, remove the directory related to your submodule from the .git/modules directory.

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  git@github.com:curiouslychase/content.git

Wrapping Up

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!