Skip to main content

Git error: 'main/' does not have a commit checked out`

· 4 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

The error error: 'main/' does not have a commit checked out occurs when Git tries to add files to a submodule that is in a detached HEAD state or has no checked-out commit. This happens because the main repository expects the submodule to point to a specific commit, but it's in an invalid state.

To fix this, you need to navigate into the submodule's directory and check out a commit, usually by switching to the main branch or a specific branch.

Step-by-Step Fix​

If you're working on the brand new project and get this erorr right after the start and while git status - maybe you just need to re-initialize the folder you're in and associate it again with github repo.

  1. Navigate into the Submodule Directory First, change your current directory to the submodule that is causing the error. In this case, it's the main folder.

    cd main

  2. Verify the State of the Submodule Run git status to see the current state. You'll likely see a message indicating a detached HEAD or that you are not on any branch.

    git status
    # You are in a detached 'HEAD' state...

  3. Check Out a Valid Branch To fix the detached HEAD, you need to check out a valid branch, such as main or master. This will make the submodule point to a specific commit, which the parent repository can then track.

    git checkout main

    If the main branch doesn't exist, use master or the correct branch name. You may also need to fetch from the submodule's remote before checking out.

    git fetch origin
    git checkout main

  4. Return to the Parent Repository and Add Changes Now that the submodule is in a valid state, navigate back to the root directory of your main repository.

    cd ..

    You can now safely add the submodule's changes and commit them.

    git add .
    git commit -m "Updated submodule 'main' to latest commit"

Why This Happens​

This error is a classic symptom of an improperly synchronized submodule. Submodules are essentially nested Git repositories (1). When you clone a repository with submodules, Git doesn't automatically check out a branch for each submodule. Instead, it checks out a specific commit for that submodule, which can leave it in a detached HEAD state. The parent repository cannot track a folder that isn't pointing to a specific, trackable commit.

By manually checking out a branch within the submodule, you're telling the parent repository which commit to point to and track.

Sources​

  1. Git Tools - Submodules