Question

When I try to git pull in my branch, I get:

error: Your local changes to the following files would be overwritten by merge:
    Vendor/JSONKit

Indeed, when I do a git status, it says Vendor/JSONKit is “modified”.

Vendor/JSONKit contains a third-party project called JSONKit (https://github.com/johnezang/JSONKit). I’ve never touched this code. I didn’t set up the folder, either — but I gather that it’s what’s called a “submodule”.

What is causing this error and how do I get past it? If I try to git stash, it claims I have “No local changes to save.” If I go into Vendor/JSONKit and try to do anything, git says I’m not on a branch anymore.

Answer 1

In a single repository:

You should be able to explore the diff with git diff -- Vendor/JSONKit, but if you want to just reset the file (and abandon the changes), issue this command:

git checkout HEAD -- Vendor/JSONKit

That’ll checkout the most recent version of Vendor/JSONKit in your working directory and abandon the modifications.

---

In a repository with submodules:

Git submodules allow you to embed git repositories inside one another. Suppose “JSONKit” were a submodule inside “MyApp”. The top-level git repository, MyApp, only tracks the HEAD commits of JSONKit, so you can perfectly reconstruct both MyApp‘s and JSONKit‘s states at any point in history.

Suppose you committed changes inside the JSONKit repository. Inside JSONKit, this would look like a normal diff and have a normal history. Inside the parent repository, MyApp, it would register as a change to the HEAD commit. It might look something like this diff, taken from the git scm docs. The submodule in this example is a directory called “rack”.

$ git diff --cached rack
diff --git a/rack b/rack
new file mode 160000
index 0000000..08d709f
--- /dev/null
+++ b/rack
@@ -0,0 +1 @@
+Subproject commit 08d709f78b8c5b0fbeb7821e37fa53e69afcf433

How does MyApp know which directories are submodules? It’s tracked inside the .gitmodules file. cat it, and you’ll see every submodule registered in MyApp:

$ cat .gitmodules 
[submodule "rack"]
    path = rack
    url = git://github.com/chneukirchen/rack.git

When you issued git submodule update, you told git to checkout the most recent HEAD commit for JSONKit in your parent repo’s index, thus abandoning the change in the submodule repository:

update
   Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. This will
   make the submodules HEAD be detached unless --rebase or --merge is specified or the key submodule.$name.update is set to rebase, merge or none.  none
   can be overridden by specifying --checkout.