Troubleshooting Git Issues: Removing and Re-adding a Submodule

How I Fixed Frontend Folder Tracking in a Git Repository

Git submodules are powerful but can introduce complications when improperly managed. In this article, I’ll walk through a real-world scenario where I had to:

1. Remove a frontend submodule that was incorrectly set up.

2. Re-add the frontend folder as part of the main repository.

3. Clean up lingering .gitmodules issues to ensure a stable Git state.

If you’ve ever struggled with Git submodules or untracked folders, this guide will help you resolve similar issues.

---

Problem 1: Removing the Submodule

The Issue

I had a frontend directory that was mistakenly initialized as a Git submodule. When I tried removing it using standard commands:

git submodule deinit -f frontend  
git rm -f frontend  
git commit -m "Remove frontend submodule"

I encountered an error:

fatal: could not lookup name for submodule 'frontend'

This happened because Git’s submodule tracking was out of sync with the .gitmodules file.

Solution

To properly remove the submodule:

1. Delete submodule metadata (if .git exists inside the folder):

    rm -rf frontend/.git
   

2. Remove the submodule from Git’s index:

    git rm -r --cached frontend
   

3. Re-add the folder as part of the main repo:

    git add frontend/  
    git commit -m "Re-add frontend as a regular folder"
   

4. Push changes:

    git push origin main
   

✅ Result: The frontend folder was no longer a submodule but a regular tracked directory.

---

Problem 2: Git Not Tracking the Frontend Folder

The Issue

After removing the submodule, Git still wasn’t tracking changes inside frontend/. Running git status showed:

Untracked files:  
  frontend/

Solution

I forced Git to recognize the folder:

1. Re-add forcefully:

    git add -f frontend/
   

2. Commit changes:

    git commit -m "Track frontend files in main repo"
   

3. Push to remote:

    git push origin main
   

✅ Result: All frontend files were now properly tracked.

---

Problem 3: Leftover .gitmodules File

The Issue

Even after removing the submodule, the .gitmodules file remained, causing confusion.

Solution

I removed it completely:

1. Delete the file:

    rm .gitmodules
   

2. Commit the change:

    git add .gitmodules  
    git commit -m "Remove obsolete .gitmodules file"
   

✅ Result: No more submodule-related artifacts.

---

Final Verification

To ensure everything was clean:

git status  
git log --oneline  # Verify commits  
git push origin main

The repository was now free of submodules, and the frontend folder was fully tracked as part of the main project.

---

Key Takeaways

1. Submodules can be tricky – Always verify .gitmodules and .git/config when removing them.

2. Force-add untracked folders if Git ignores them after submodule removal.

3. Clean up leftover files like .gitmodules to avoid future issues.

If you’ve faced similar Git struggles, let me know in the comments!

Happy coding! 🎉