This post is about looking into the order in which you debug the reason for your inability to checkout Git repo on Windows operating system. It could be because of the following reasons and you should debug in that order:
- Existence and validity of your SSH Keys
- Presence of files in your git repository whose names are reserved words in Windows OS
The next section of the post delves into these two pointers in detail.
Existence and validity of your SSH Keys
- You should have SSH keys (typically id_rsa and id_rsa.pub) in your operating system path $HOME/.ssh/. If not generate it with ssh-keygen.
- You should have the contents of the public key (id_rsa.pub) added to your list of SSH Keys in your Git remote repository. In the case of Github, it will be in your personal settings page.
Windows OS incompatible file names in your git repository
This is a little crazy Windows OS weirdo. After making sure that I indeed have the SSH Keys setup right both in my local windows-os and in the remote Git repository (Github in my case). But how do you do that?
After hours of hair-splitting to think that SSH keys isn't setup right and I was only left frustrated and hopeless. A little insight into why I was misled to thinking so and you too could be trapped by this very step. I tried what others prescribed to validate this, which is to run the below commands:
ssh -T git@github.comssh -T your-github-id@github.com
While the first command turned out successful, the second one failed with an exception stating, "... Permission denied (publickey)" leading me into the rabbit hole to be lost in darkness.
The best thing to do when your lost is to take a break from the problem. You would still be thinking about it at the back of your mind, which is a good sign ;)
So after my break and back at my desk, the next thing that I tried was do exploratory testing to validate my assumption. And so I tried to checkout a couple of other repositories to see if that works. And it did. Damn, my SSH Keys setup was indeed right and that I was wrong to assume that I missed something right there.
Side-note: Best test case for this kind of use-case is to create a simple repository with only a Readme.md file in it and see if you can checkout that repository. If that works good, the problem is likely with your operating system and the repository contents. In my case the remote repository had a file named aux.js.
So now the problem is with my current repository which worked in my other laptop having Ubuntu OS? That leads me to wondering if there is something in my repository that my Windows OS isn't liking? I slap myself and get back to basics of reading that error I get when I checkout this troubling git repository. The error message that I got mid-way through checking out read something like below:
error: invalid path 'src/hoc/aux.js'.fatal: unable to checkout working treewarning: Clone succeeded, but checkout failed.You can inspect what was checked out with 'git status'and retry with 'git restore --source=HEAD :/'
I now have zoomed in into the file aux.js as the possible cause, because windows is unable to create that file. When I tried to manually create a file by that name, I was shocked to learn that windows doesn't allow me to create one by that name, because aux is a reserved name in windows that refers to some device. And boy Windows has quite a few such reserved names and if you got files created by those names in your non-windows operating systems that make it to remote Git repository, your other developers using windows operating systems will be at a loss.
There are other such reserved names in windows os. Do not use the following reserved names for the name of a file: CON, PRN, AUX, NUL, COM1, COM2, COM3,..., LPT1, LPT2, LPT3, ... Also avoid these names followed immediately by an extension; for example, NUL.txt is not recommended.
Below are two possible ways to solve this problem:
- The quick and easy route is to change your git config by running: git config core.protectNTFS false.
- The other is the hard route that I recommend for portability reasons, if it is doable in your project. And that is to rename the file to something that windows developers can consume without any issue.
It is important to know the other windows operating limitations as well for project portability on windows platforms:
- In Windows, filenames are case-insensitive.
- In Windows, certain characters are not permitted as part of file names.
For this reason, it is important to consider the following links to see if you have broken any of windows conventions in your file naming:
- Win32 : Naming Files, Paths, and Namespaces
- (others as I uncover/learn)