How to fix fatal: A git directory for 'path' is found locally in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 220 views

This error occurs when adding a Git submodule that conflicts with a cached submodule directory in .git/modules/. Fix it by removing the stale cache, using --force, or providing an alternate --name.

Quick fix

Fixes fatal: A git directory for 'path' is found locally

# View what's in the cached directory
ls .git/modules/path/to/submodule

# Check the cached remote
cat .git/modules/path/to/submodule/config | grep url
  1. Understand what Git is telling you
  2. Option A: Use --force to reuse the cached directory
  3. Option B: Remove the cached modules directory
  4. Option C: Use --name to avoid the conflict
git — error
# View what's in the cached directory
ls .git/modules/path/to/submodule
# Check the cached remote
cat .git/modules/path/to/submodule/config | grep url
fatal: A git directory for 'path' is found locally

What this error means

When you run `git submodule add`, Git stores the submodule's repository data in the `.git/modules/<path>` directory of your parent repository. This error indicates that Git found an existing git directory at that location, typically left over from a previously removed submodule. The full error message usually looks like: ``` fatal: A git directory for 'path/to/submodule' is found locally with remote(s): origin git@github.com:example/repo.git If you want to reuse this local git directory instead of cloning again from git@github.com:example/new-repo.git use the '--force' option. If the local git directory is not the correct repo or you are unsure what this means choose another name with the '--name' option. ``` This commonly happens when you: - Removed a submodule but didn't clean up `.git/modules/` - Changed a submodule's remote URL - Moved or renamed a submodule path - Cloned a repository where submodule history diverged Git is being cautious: it won't overwrite existing repository data that might contain commits not pushed elsewhere.

Typical symptoms

  • Running 'git submodule add' fails with 'A git directory is found locally' error
  • The error mentions a remote URL that may be different from the one you're trying to add
  • The submodule path doesn't exist in the working directory but Git still complains
  • Previously deleted submodule cannot be re-added with the same path
  • Switching branches with different submodule configurations triggers the error

Common causes

  1. A submodule was removed without cleaning up .git/modules/<path> (most common)
  2. The submodule's remote URL was changed but the cached repository still references the old URL
  3. A submodule path was renamed or moved without proper cleanup
  4. The repository was cloned with --recursive after submodule configuration changed upstream
  5. Git configuration in .git/config still references the old submodule settings
  6. Multiple branches have conflicting submodule configurations at the same path

How to fix "fatal: A git directory for 'path' is found locally"

1Understand what Git is telling you

Read the error message carefully. It shows:

1. The path where the conflict exists
2. The existing remote URL in the cached directory
3. The new remote URL you're trying to add

If the remotes match, you can safely use --force. If they differ, you need to decide which repository you actually want.

bash
# View what's in the cached directory
ls .git/modules/path/to/submodule

# Check the cached remote
cat .git/modules/path/to/submodule/config | grep url
2Option A: Use --force to reuse the cached directory

If the cached directory contains the correct repository (same remote URL), use the --force flag to reuse it:

bash
git submodule add --force <repository-url> <path>

This tells Git to use the existing .git/modules/<path> directory instead of cloning fresh. This is the fastest solution when the cached data is valid.

Example:

bash
git submodule add --force git@github.com:example/lib.git libs/mylib
3Option B: Remove the cached modules directory

If you want a fresh clone or the cached directory has the wrong repository, remove it:

bash
# Remove the cached submodule git directory
rm -rf .git/modules/path/to/submodule

# Also remove the submodule config section
git config --remove-section submodule.path/to/submodule 2>/dev/null || true

Now retry adding the submodule:

bash
git submodule add <repository-url> <path>

Example for a submodule at `libs/mylib`:

bash
rm -rf .git/modules/libs/mylib
git config --remove-section submodule.libs/mylib 2>/dev/null || true
git submodule add git@github.com:example/lib.git libs/mylib
4Option C: Use --name to avoid the conflict

If you want to add a different repository at the same path (e.g., replacing a submodule with a fork), use the --name option:

bash
git submodule add --name <unique-name> <repository-url> <path>

This stores the submodule data under a different name in .git/modules/<unique-name>, avoiding the conflict.

Example:

bash
# Original was stored as .git/modules/libs/mylib
# Use a new name to avoid conflict
git submodule add --name mylib-fork git@github.com:myfork/lib.git libs/mylib
5Properly remove a submodule (for future reference)

To fully remove a submodule and avoid this error in the future, use these steps:

Modern Git (2.17+):

bash
# This handles most cleanup automatically
git rm path/to/submodule
git commit -m "Remove submodule"

# Still need to manually clean up .git/modules
rm -rf .git/modules/path/to/submodule

Complete manual removal:

bash
# 1. Deinitialize the submodule
git submodule deinit -f path/to/submodule

# 2. Remove from .git/modules
rm -rf .git/modules/path/to/submodule

# 3. Remove from working tree and index
git rm -f path/to/submodule

# 4. Commit the removal
git commit -m "Remove submodule path/to/submodule"
6Use git submodule sync after URL changes

If the issue is a URL mismatch (you updated .gitmodules but the cache has the old URL), sync the configuration:

bash
# Update cached URLs from .gitmodules
git submodule sync

# Reinitialize and update the submodule
git submodule update --init --recursive

This is often better than deleting the cache, especially if the submodule has the same content and you just changed the remote URL (e.g., switching from HTTPS to SSH).

7Clean up all orphaned submodule caches

If you have multiple stale submodule directories, you can clean them all:

bash
# List what's in .git/modules
ls -la .git/modules/

# Compare with current .gitmodules entries
git config --file .gitmodules --get-regexp path

# Remove orphaned directories not in .gitmodules
# (Do this manually after reviewing the lists above)
rm -rf .git/modules/orphaned-submodule

Deinit all submodules and start fresh:

bash
git submodule deinit --all -f
rm -rf .git/modules/*
git submodule update --init --recursive

Advanced notes

### How Git Stores Submodules

Git stores submodule data in multiple locations:

| Location | Purpose |
|----------|---------|
| .gitmodules | Tracked file with submodule URLs and paths |
| .git/config | Local config with [submodule "name"] sections |
| .git/modules/<path>/ | The actual git repository data |
| <path>/.git | A gitfile pointing to .git/modules/<path> |

The "git directory found locally" error specifically refers to .git/modules/<path>/ existing when Git tries to clone there.

### git submodule absorbgitdirs

If you have submodules with their own .git directories (older Git style), you can move them into the parent's .git/modules/:

bash
git submodule absorbgitdirs

This is mostly for historical repositories or submodules added before Git 1.7.8.

### Nested Submodules

For nested submodules, the path in .git/modules/ includes the full nested path:

bash
.git/modules/
  libs/
    logging/
    utils/
      nested-submodule/

When cleaning up, make sure you're targeting the correct nested path.

### CI/CD Considerations

In CI pipelines, this error often appears because:
- The runner caches .git/modules/ between builds
- Submodule configuration changed in the meantime

Solutions:
1. Add cache invalidation when .gitmodules changes
2. Run git submodule sync before git submodule update
3. Use fresh clones instead of cached working directories

Frequently asked questions

What does "fatal: A git directory for 'path' is found locally" mean?
git/modules/<path> directory of your parent repository. This error indicates that Git found an existing git directory at that location, typically left over from a previously removed submodule. git/modules/ - Changed a submodule's remote URL - Moved or renamed a submodule path - Cloned a repository where submodule history diverged Git is being cautious: it won't overwrite existing repository data that might contain commits not pushed elsewhere.
How do I fix "fatal: A git directory for 'path' is found locally"?
This error occurs when adding a Git submodule that conflicts with a cached submodule directory in .git/modules/. Fix it by removing the stale cache, using --force, or providing an alternate --name.
What causes "fatal: A git directory for 'path' is found locally"?
A submodule was removed without cleaning up .git/modules/<path> (most common) The submodule's remote URL was changed but the cached repository still references the old URL A submodule path was renamed or moved without proper cleanup
Is the "fatal: A git directory for 'path' is found locally" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading