How to fix fatal: Not a git repository: 'path/to/submodule/../.git/modules/submodule' in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 280 views

This error occurs when Git cannot locate or access the git directory for a submodule. The submodule's internal .git reference points to a path that doesn't exist or has become corrupted after moving, cloning, or branch switching.

Quick fix

Fixes fatal: Not a git repository: 'path/to/submodule/../.git/modules/submodule'

# Check if .git exists in current or parent directories
git rev-parse --git-dir
  1. Verify you're inside a git repository
  2. Initialize and update submodules
  3. Deinitialize and reinitialize the problematic submodule
  4. Fix path references after moving the repository
git — error
# Check if .git exists in current or parent directories
git rev-parse --git-dir
fatal: Not a git repository: 'path/to/submodule/../.git/modules/submodule'

What this error means

The "fatal: Not a git repository" error in a submodule context indicates that Git cannot find or access the git metadata directory for one of your submodules. Unlike a regular "not a git repository" error (where you simply aren't in a git repo), this error specifically involves broken references between a submodule's working directory and its actual git data. In modern Git (1.7.8+), submodules don't contain a full `.git` directory. Instead, each submodule has a `.git` **file** that contains a `gitdir:` pointer to the parent repository's `.git/modules/<submodule-name>` directory. This design keeps all git data centralized in the parent repo while allowing submodules to function independently. When this pointer becomes invalid—due to moving the repository, incorrect cloning, switching branches with different submodule configurations, or filesystem corruption—Git cannot resolve the submodule's git directory and throws this error. The error message typically includes a path like `.git/modules/submodule_name` that Git is trying to access but cannot find.

Typical symptoms

  • Git commands fail with 'fatal: Not a git repository' mentioning a path containing '.git/modules/'
  • git submodule update --init fails with 'not a git repository' errors
  • git status shows submodule as modified but git diff shows nothing
  • Switching branches causes submodule-related 'not a git repository' errors
  • After moving or renaming a repository directory, submodule commands fail

Common causes

  1. Repository was moved or renamed, breaking absolute paths in submodule configuration
  2. Submodule was not properly initialized after cloning (missing git submodule update --init)
  3. The .git/modules/<submodule> directory was deleted or corrupted
  4. Branch switch to a branch with different submodule structure when submodule.recurse=true is set
  5. Using git config submodule.recurse=true with branches that have incompatible submodule states
  6. Downloaded repository as ZIP instead of cloning (no .git directory exists)

How to fix "fatal: Not a git repository: 'path/to/submodule/../.git/modules/submodule'"

1Verify you're inside a git repository

First, confirm you're actually inside a git repository and not in a ZIP download or unrelated directory:

bash
# Check if .git exists in current or parent directories
git rev-parse --git-dir

If this command fails, you're not in a git repository. If you downloaded a ZIP archive of the project:

bash
# You need to clone the repository properly instead
rm -rf project-folder
git clone --recursive https://github.com/user/repo.git project-folder

The --recursive flag ensures submodules are also cloned.

2Initialize and update submodules

If submodules haven't been initialized yet (common after a fresh clone without --recursive):

bash
# Initialize and update all submodules recursively
git submodule update --init --recursive

If a specific submodule is causing issues:

bash
# Check the status of all submodules
git submodule status

# Initialize a specific submodule
git submodule init path/to/submodule
git submodule update path/to/submodule

This fetches the submodule content and sets up the proper git directory structure.

3Deinitialize and reinitialize the problematic submodule

If the submodule exists but is in a broken state, deinitializing and reinitializing often fixes the issue:

bash
# Deinitialize the submodule (removes working tree but keeps .git/modules entry)
git submodule deinit -f path/to/submodule

# Reinitialize the submodule
git submodule init path/to/submodule

# Update to fetch content
git submodule update path/to/submodule

If the error persists, you may need to also remove the cached modules directory:

bash
# Remove the submodule's git directory from parent repo
rm -rf .git/modules/path/to/submodule

# Then reinitialize
git submodule init path/to/submodule
git submodule update path/to/submodule
4Fix path references after moving the repository

If you moved or renamed your repository directory, the absolute paths in submodule configuration may be broken. Find and fix these paths:

bash
# Find all files with old path references
find .git -type f -name "config" -exec grep -l "old/path" {} \;
find . -name ".git" -type f -exec grep -l "old/path" {} \;

The submodule's .git file contains a gitdir path. Check its contents:

bash
# View the .git file in the submodule directory
cat path/to/submodule/.git
# Output: gitdir: ../../.git/modules/submodule

If the path is incorrect (e.g., has the old directory name), fix it:

bash
# Update the gitdir path (adjust the relative path as needed)
echo "gitdir: ../../.git/modules/submodule" > path/to/submodule/.git

Also check the corresponding config in the parent's modules directory:

bash
# Check the worktree path
cat .git/modules/submodule/config | grep worktree

Update it if necessary to point to the correct working directory.

5Completely remove and re-add the submodule

If other solutions fail, completely removing and re-adding the submodule ensures a clean state:

bash
# Step 1: Remove submodule entry from .gitmodules
git config -f .gitmodules --remove-section "submodule.path/to/submodule"

# Step 2: Remove submodule entry from .git/config
git config --remove-section "submodule.path/to/submodule"

# Step 3: Remove the submodule's git modules directory
rm -rf .git/modules/path/to/submodule

# Step 4: Remove the submodule working directory
rm -rf path/to/submodule

# Step 5: Remove from Git's cache
git rm --cached path/to/submodule

# Step 6: Commit the removal
git commit -m "Remove broken submodule"

# Step 7: Re-add the submodule
git submodule add https://github.com/user/submodule-repo.git path/to/submodule

# Step 8: Commit the re-added submodule
git commit -m "Re-add submodule"
6Disable submodule.recurse if causing branch switch issues

If you're getting this error when switching branches, the submodule.recurse config option may be causing Git to update submodules before they're properly initialized:

bash
# Check if submodule.recurse is enabled
git config --get submodule.recurse

# Disable it globally
git config --global submodule.recurse false

# Or disable it for just this repository
git config submodule.recurse false

After disabling, switch branches first, then manually update submodules:

bash
git checkout target-branch
git submodule update --init --recursive

You can re-enable submodule.recurse once all submodules are in a consistent state.

7Use git submodule absorbgitdirs for cleanup

If a submodule has a full .git directory instead of a .git file with a gitdir pointer, it can cause issues. The absorbgitdirs command fixes this:

bash
# Move submodule git directories to parent's .git/modules
git submodule absorbgitdirs

This command:
1. Moves each submodule's .git directory to .git/modules/<submodule>
2. Replaces the submodule's .git directory with a .git file containing the gitdir pointer

This is especially useful if you've manually run git init inside a submodule or converted an existing directory to a submodule.

8Clone fresh as a last resort

If the repository is severely corrupted and other fixes don't work, cloning fresh is the most reliable solution:

bash
# Backup any local changes
cd /path/to/parent-repo
git stash

# Clone fresh with all submodules
cd ..
git clone --recursive https://github.com/user/repo.git repo-fresh

# Copy over any untracked files you need
# Then remove the old repository
rm -rf parent-repo
mv repo-fresh parent-repo

If you have local commits that haven't been pushed:

bash
# In the old repo, export patches
cd old-repo
git format-patch origin/main --stdout > ../my-patches.patch

# In the fresh clone, apply them
cd ../repo-fresh
git am < ../my-patches.patch

Advanced notes

How Git submodule directories work:

Modern Git (1.7.8+) stores submodule git data in the parent repository at .git/modules/<submodule-path>/. The submodule's working directory contains a .git file (not directory) with content like:

bash
gitdir: ../../.git/modules/my-submodule

This bidirectional linking requires two paths to match:
1. The gitdir: in the submodule's .git file → points to parent's .git/modules/
2. The core.worktree in .git/modules/<submodule>/config → points back to submodule's working directory

Both paths are typically relative, which is why moving the parent repository usually doesn't break things. However, older Git versions used absolute paths, which break when moving repositories.

Upgrading from older Git versions:

If you're migrating a repository from Git < 1.7.10 that used absolute paths:

bash
# Check Git version
git --version

# If submodules have absolute paths, upgrade Git and re-clone
# Or manually fix the paths in .git files and config

Submodules in CI/CD pipelines:

Many CI/CD runners use shallow clones or don't initialize submodules by default:

yaml
# GitHub Actions
- uses: actions/checkout@v4
  with:
    submodules: recursive  # Clone submodules too

# GitLab CI
variables:
  GIT_SUBMODULE_STRATEGY: recursive

Debugging submodule state:

bash
# Show detailed submodule status
git submodule status --recursive

# Show submodule summary (commits)
git submodule summary

# List all registered submodules
git config --file .gitmodules --get-regexp path

# Check what's in the submodule's .git file
cat path/to/submodule/.git

# Check parent's submodule config
cat .git/modules/submodule/config

Common gotcha: nested submodules:

If your submodules contain their own submodules (nested submodules), you need --recursive for most operations:

bash
git clone --recursive <url>
git submodule update --init --recursive
git submodule foreach --recursive git pull origin main

Frequently asked questions

What does "fatal: Not a git repository: 'path/to/submodule/../.git/modules/submod" mean?
The "fatal: Not a git repository" error in a submodule context indicates that Git cannot find or access the git metadata directory for one of your submodules. Unlike a regular "not a git repository" error (where you simply aren't in a git repo), this error specifically involves broken references between a submodule's working directory and its actual git data. git directory.
How do I fix "fatal: Not a git repository: 'path/to/submodule/../.git/modules/submod"?
This error occurs when Git cannot locate or access the git directory for a submodule. The submodule's internal .git reference points to a path that doesn't exist or has become corrupted after moving, cloning, or branch switching.
What causes "fatal: Not a git repository: 'path/to/submodule/../.git/modules/submod"?
Repository was moved or renamed, breaking absolute paths in submodule configuration Submodule was not properly initialized after cloning (missing git submodule update --init) The .git/modules/<submodule> directory was deleted or corrupted
Is the "fatal: Not a git repository: 'path/to/submodule/../.git/modules/submod" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading