Adding Git Submodules

Refer to the Git Documentation and Guide if you need help adding a git submodule. Below we discuss some common issues that occur when adding a submodule to a cloned git project that has already been created.

Cloning a project that contains submodules

When cloning an existing project that already comes with a submodule, the submodule folder will not be cloned, to clone these files as well, run the following commands:

cd path/to/your/cloned/repo

git submodule init

git submodule update

Error: "[projectfolder] already exists in the index."

Suppose you want to add the submodule to a directory named projectfolder with the desired directory structure:

    repo
    |-- projectfolder
        |-- folder with common_code

And you run the command:

git submodule add https://github.com/zmhassan/reactjs-redux-patternfly-library projectfolder

And you get the error:

'projectfolder' already exists in the index"

Solution (courtesy of Mark Longair):

That error means that projectfolder is already staged ("already exists in the index"). To find out what's going on here, try to list everything in the index under that folder with:

git ls-files --stage projectfolder

The first column of that output will tell you what type of object is in the index at projectfolder. (These look like Unix filemodes, but have special meanings in git.)

You should see something like:

160000 d00cf29f23627fc54eb992dde6a79112677cd86c 0 projectfolder

(i.e. a line beginning with 160000), in which case the repository in projectfolder has already been added as a "gitlink". If it doesn't appear in the output of git submodule, and you want to re-add it as a submodule, you can do:

git rm --cached projectfolder

... to unstage it, and then:

git submodule add url_to_repo projectfolder

... to add the repository as a submodule.

However, it's also possible that you will see many blobs listed (with file modes 100644 and 100755), which could mean it's possible that you didn't properly unstage the files in projectfolder before copying the new repository into place. If that's the case, you can do the following to unstage all of those files:

git rm -r --cached projectfolder

... and then add the submodule with:

git submodule add url_to_repo projectfolder

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

If you encounter this error (potentially after trying the previous) here are some following steps that might help you out:

1. Ensure the common_code directory does not exist (it will be created by git)
2. cd Repo
3. git submodule add https://github.com/zmhassan/reactjs-redux-patternfly-library projectfolder/common_code/ (the trailing slash is important here).