Cloning succeded but checkout failed due to invalid path. What is the path problem?

Question

I need to clone a repository that has been working with no issue on multiple linux machines, across several distributions.

Now it turns out that in Windows I get this problem

error: invalid path 'soft/android-app/app/src/main/java/com/inti/bleapp/Aux.java'
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.

And one of the biggest issues is that the cloning process takes about 15 to 20 minutes (the git has a lot of history).

And this error is thrown at the very end. I can't, for the life of me figure out why windows does nto like this path.

Can anyone give me any clues?

Answer 1

How to fix it

If you can get someone else—on Linux for instance—to rename the problematic file and commit, that will do the job. Or just spin up a VM with Linux on it, clone, fix the name (and all users of it), commit, and send the update back.

The problem is Windows

Windows cannot handle any file named AUX. You can't name a file PRN or CON or COM1 either.

error: invalid path 'soft/android-app/app/src/main/java/com/inti/bleapp/Aux.java'

You might object: that's not a file named AUX. At worst, that's a file named Aux.java.

But to Windows, that's a file named AUX:

• Windows is case-insensitive, so aux, Aux, auX, and so on are all just way to spell AUX.
• Windows still thinks about files with eight-dot-three names: FILENAME.EXT. Sure, everything seems to use long names and you can actually have files named foo.data.jpg if you like. But deep in its crazy past, Windows used to use 8.3 names, and it insists on supporting programs that still use 8.3 names, so all files get an 8.3 name somewhere—and Aux.java gets an 8.3 name that starts with AUX, and having an extension doesn't get you around the forbidden file name.

The problem isn't just Windows

Those with macOS might gleefully point and laugh, but macOS has issues as well.

Linux folks can, and have in the past, saved files under names such as both ip.h and IP.h in the same directory. The idea here was to define the little-endian variant of the IP headers for TCP/IP in the lowercase ip.h, and define the big-endian variant in the uppercase IP.h. Case-folding, which both Windows and macOS do by default, gets us in trouble here.

Besides this, accented character file names—files named schön or agréable–can be built in multiple ways using UTF-8. Linux file systems can store any of the ways, and Git will just take whatever the storage method is, and put it in the committed file's name. But macOS demands one normalized form of the file name, and this causes the same kinds of problems.

What Git needs (but doesn't have)

Git needs a way to deal with this.

Git does have "sparse checkout". Sparse checkout allows you to define a set of files that will be checked out of some commit, and other files that won't—that will go into Git's index as usual but not appear in the work-tree at all.

You can use sparse checkout to check out this commit without extracting the file soft/android-app/app/src/main/java/com/inti/bleapp/Aux.java at all. Well, that's perhaps OK, but you won't have the file.

In fact, you already don't, as the final message said:

warning: Clone succeeded, but checkout failed.

When the checkout fails, all the other files should be available in your work-tree. It's just this one soft/android-app/app/src/main/java/com/inti/bleapp/Aux.java that won't. If you can get work done without it, you can simulate the sparse checkout by running:

git update-index --skip-worktree soft/android-app/app/src/main/java/com/inti/bleapp/Aux.java

What Git should have are some tools to deal with these files more productively. In particular, it should be possible (and is, if you get down into the depths of Git) to extract the file under some other name, then add the renamed file under the original name if necessary. It should be possible (and is, but not with any sensible user-facing command) to rename the file and commit, after which you can check out the new commit and work with the file with a name that your OS doesn't hate.

All of this is possible because Git actually makes new commits from what is in its index, not what is in your work-tree. There's no hard requirement that the names in the index match the names in your work-tree. But all of Git's user-facing commands—git checkout, git restore, and git add being the primary ones—do make this requirement today.