Editing Troubleshooting of GIT (section)

=== Git Submodule Pull Failed: unable to create file — File exists ===

'''Error Message'''

After pulling in GitHub Desktop, met the error message

<pre>
Fetching submodule lib
error: unable to create file feeds/example.php: File exists
Updating xxxxxxxx..xxxxxxxx
</pre>

'''Cause'''

When Git tries to update the submodule to a newer commit, it finds a local untracked file with the same name, blocking the checkout. A mid-pull failure leaves the submodule in an inconsistent state and causes a large number of unexpected unstaged changes to appear in GitHub Desktop.

'''Solution'''

Run the following command in the project root directory to force re-sync the submodule:

<pre>
git submodule update --init --recursive --force
</pre>

If it still fails, manually remove the conflicting file and retry:

<pre>
rm lib/feeds/example.php
git submodule update --init --recursive
</pre>

Enter the submodule directory and verify the status is clean:

<pre>
cd lib
git status
</pre>

The expected output should be:

<pre>
HEAD detached from xxxxxxxx
nothing to commit, working tree clean
</pre>

`nothing to commit, working tree clean` confirms the submodule has been successfully synced — return to GitHub Desktop and continue as normal. `HEAD detached` is the expected state for a submodule and does not require any action.

{{exclaim}} Notice: The large number of unstaged changes appearing in GitHub Desktop after a failed Pull will typically return to normal once the submodule is fixed. If unexpected changes still remain, run <code>git submodule foreach git checkout .</code> to revert all modifications inside every submodule.