Jan 1, 2009

Quick Tip: Remove a Git Submodule

The other day I was deploying a fix to one of my sites via Capistrano and it failed. I traced it back to the attachment_fu plugin.. somehow the submodule just wasn't playing well with others and nothing I could do would gracefully fix it. I ended up having to remove the submodule and reinstall it. Not a big deal in the grand scheme of things so I thought I'd share a little info on how to do it in case you run into the same problem.

The error I was seeing was:

error: pathspec '1a74c25a424bc26989722e730d56c305d87e430c' did not match any file(s) known to git.
Unable to checkout '1a74c25a424bc26989722e730d56c305d87e430c' in submodule path 'vendor/plugins/attachment_fu'

I saw a post about it being related to the git 1.6 branch but in my case I am still using git 1.5.6. The only solution I saw was to remove the submodule and then re-add it later. To remove a git submodule, you have to edit 2 files and remove the directory with the submodule.

Step 1: Edit the .gitmodules file and remove the reference to your submodule. In my case, I removed the submodule for attachment_fu.

Step 2: Edit the .git/config file and remove the reference to your submodule. Again it should only be one place.. maybe a couple of lines.

Step 3: Remove the actual submodule. The command to do that is git rm --cached plus the directory in question. Note that the trailing slash is not there.. be sure to honor that syntax when you remove your submodule.

git rm --cached vendor/plugins/attachment_fu

Step 4: Since we're talking git, you may want to commit and push your changes. Do that the way you normally go about things. Probably something like:

git commit -a -m "removed attachment fu temporarily"
git push

You should now be free of your submodule! If you want to add that submodule back then you'll need roughly these commands. Replace the path for attachment fu in this example to the path of your submodule:

git submodule add git://github.com/technoweenie/attachment_fu.git
git submodule init
git submodule update
git commit -a -m "added attachment fu back to the repo"
git push


  1. Re step 4: When you add the files back into git make sure you don't;

    git add path_to_submodule

    but instead

    git add path_to_submodule/*

    As git will retain a reference to the submodule and you'll get this error if you do a git submodule status;

    No submodule mapping found in .gitmodules for path: 'path_to_submodule'

  2. @james2m: Thanks! I couldn't figure out the problem.

  3. Thanks a boatload - one more step towards getting Git squared away! :)

  4. In newer versions of git, you will also have to remove the corresponding directory and files under .git/modules