Fixing Git Checkout Invalid Path Error on Windows

How to fix the clone succeeded, but checkout failed git issue on Windows

   , ,   3 min read

Once upon a time, I got a small freelance gig where I needed to edit a web app project on my Windows PC. The client shared their git repository with me.

As usual, I cloned the remote git repository into my local Windows folder. Here’s the git clone command I did:

git clone git@github.com:username/my-project.git

Normally, I’ll just need to wait for the cloning process to be finished, and the project will be ready to use.

But not this time.

You see, I got a fatal error with this concerning message: “Clone succeeded, but checkout failed.”

Cloning into 'my-project'...
remote: Counting objects: 5824, done.
remote: Total 5824 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (5824/5824), 33.81 MiB | 2.44 MiB/s, done.
Resolving deltas: 100% (1582/1582), done.
error: invalid path 'my-project/js/19-10-5:27pm-clockevents.js'
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'

I thought there was something wrong with the git remote repository. But when I tried to clone it on my Linux server, there was no issue. The git clone process worked normally.

That means the issue was coming from my Windows PC or the git binary itself.

After a quick search online, I found out that the core issue was most likely coming from Windows.

The obvious clue was coming from “error: invalid path” error message above.

You see, there was a filename with : in it, which turned out to be one of Windows’ reserved characters. You can say it’s forbidden to have a : character in a filename on Windows.

Obviously, you can just rename the file from the remote git repository into something safe, but what if it’s not allowed?

Luckily, git allows you to turn off this NTFS protection.

Disable Git NTFS Protection Locally

To solve this git checkout failed issue only for this exact project, you can go to the project folder first.

cd my-project

Then disable NTFS protection of git by executing this command.

git config core.protectNTFS false

Once it’s set, clean up the local git repository and pull all changes from the remote repository.

git clean -fdx
git reset --hard HEAD
git pull

Disable Git NTFS Protection Globally

If you don’t want to deal with it next time, you can also disable the git NTFS protection globally by executing this command.

git config --global core.protectNTFS false

Next time you clone a fresh git repository, it won’t cause “Clone succeeded, but checkout failed.” anymore.

Final Thoughts

Thanks for reading this article. It’s been in my draft for years, but I finally got time to publish it.

Hopefully it’s useful and solved your issue.

Thanks for reading and see you around!

References