Git submodule addition error: ‘already exists in the index’

To unstage all the files, try the following steps. Then, add the submodule using Solution 2. In Solution 2, remove the git repository for the submodule (projectfolder) before proceeding. Assuming the sample git module is named “c3-pro-ios-framework” and you are in the project root directory, remove the associated files, references to the submodule in config, .gitmodules, and remove it from the cache without “git”. Lastly, add the submodule. If you encounter the same issue, Solution 4 suggests that the answer can be found after hours of searching.


As a newcomer to Git, I am seeking assistance in incorporating submodules. There are two projects that have a common
common code
. Instead of duplicating the shared code, I have extracted it to a distinct Git repository and eliminated it from the projects. My intention is to add it as a



To specify the folder, I utilized the path option provided by
git submodule

git submodule add url_to_repo projectfolder

but then got the error:

'projectfolder' already exists in the index"

This is the structure that I aim to have in my repository.

|-- projectfolder
    |-- folder with common code



submodule can be added to the repository either directly or in a new folder, but not in the project folder. However, it is necessary for it to be in the project folder. What are my options and what am I missing about the path option in git
submodule add

Solution 1:

As you haven’t responded to my follow-up question, it’s difficult to determine what’s occurring. Nonetheless, this information may still be useful.

The specified error indicates that the


has already been staged, as it “already exists in the index.” To investigate further, attempt to retrieve a list of all items in the index located within that directory.

git ls-files --stage projectfolder

The output’s initial column provides information about the type of object present at the


index. These characters resemble Unix file modes, but they have distinct interpretations in git.

It is my belief that what you will observe is something along the lines of:

160000 d00cf29f23627fc54eb992dde6a79112677cd86c 0   projectfolder

If the output of

git submodule

does not include a line starting with


, it means that the repository in


has already been added as a “gitlink”. However, if you still want to add it as a submodule, you can do the following.

git rm --cached projectfolder

… to unstage it, and then:

git submodule add url_to_repo projectfolder

…to include the repository as a submodule.

In case you come across a long list of blobs with file modes




after copying the new repository without unstaging the files in


properly, it could mean that you missed unstaging some files. To resolve this, you can unstage all the files by following these steps:

git rm -r --cached projectfolder

Next, proceed to incorporate the submodule using the following command:

git submodule add url_to_repo projectfolder

Solution 2:

For the git path, your
submodule git repository
(which is the project folder) should be removed beforehand.

rm -rf projectfolder
git rm -r projectfolder

and then
add submodule

git submodule add  projectfolder

Solution 3:

I was able to successfully complete the process by following several steps manually.

If the name of the sample
git module
is “c3-pro-ios-framework” and you are currently in the project root directory.

Eliminate the linked documents of the submodule.

rm -rf .git/modules/c3-pro-ios-framework/

Eliminate all mentions of the submodule from the configuration.

vim .git/config

Eliminate the .gitmodules file.

rm -rf .gitmodules

Clear it from the cache excluding the “git”.

git rm --cached c3-pro-ios-framework

Add submodule

git submodule add

Solution 4:

After spending numerous hours searching, I was able to find the solution to the identical issue I was facing.

The error I encountered had a slightly distinct code, namely

<path> already exists and is not a valid git repo

. This is also mentioned here for search engine optimization purposes.

To avoid creating a directory for the submodule, it is recommended not to create it beforehand. Instead, the directory will be automatically created when executing the

git submodule add


Be cautious that the argument should pertain to the parent-repo root rather than your current working directory.

Solution for the example above:

  1. It is acceptable if your parent repository has already been cloned.
  2. Ensure that the directory designated as


    is non-existent.

  3. cd Repo
  4. Please ensure to include a trailing slash as it is mandatory for

    git submodule add git://url_to_repo projectfolder/common_code/

  5. Sanity restored.

Hopefully, this information proves useful to someone since there is a scarcity of it available elsewhere.

Frequently Asked Questions

Posted in Git