This is related, but not identical, to #2803.

The reason you are seeing this is that < is not allowed in file names on Windows. As such, the error message "Invalid argument" is accurate, if unhelpful.

Unfortunately, I cannot think of any easy way to fix this right now. The error message you are seeing is produced by strerror(), which translates an errno into an error message. And I do not see an errno for the issue where illegal characters are used in a file name.

We do already check for invalid branch names, that could be extended for platform specific invalid names to die on that specific platform and warn about cross-platfom compatibility on others.

Although the cross platform warning should probably only pop up when creating a branch or pushing it to a remote for the first time, not when switching to an existing branch or pushing to a remote that already has this branch.

We do already check for invalid branch names, that could be extended for platform specific invalid names to die on that specific platform and warn about cross-platfom compatibility on others.

Good point.

BTW the code to look for invalid file names (which includes rejecting illegal characters) is only compiled on Windows for now.

Although the cross platform warning should probably only pop up when creating a branch or pushing it to a remote for the first time, not when switching to an existing branch or pushing to a remote that already has this branch.

Thank you for the detailed info! :)

@rimrul Can you provide a bit more info on why this is only an issue with branch creation? I'm probably missing context here 🙈

Really just to avoid annoying users. When you're creating a branch and get a warning that this branch name might cause you issues down the line you might reconsider your name choice. When you've been using this branch name for a long time it seems unlikely that you would rename it. You'd have seen the message when you created the branch and decided to ignore it. Why would you change your mind after seeing it a dozen times?

Small (unsurprising) update:

| and " also cause the same error message:

$ git checkout -b "|"
fatal: cannot lock ref 'refs/heads/|': Unable to create 'C:/Users/whschm/source/repos/TestRepo/.git/refs/heads/|.lock': Invalid argument

$ git checkout -b "\""
fatal: cannot lock ref 'refs/heads/"': Unable to create 'C:/Users/whschm/source/repos/TestRepo/.git/refs/heads/".lock': Invalid argument

@whitneyschmidt maybe you can give it a try to patch Git to provide a better warning?

1. install Git for Windows' SDK,
2. sdk cd git,
3. edit the source code (you will probably want to use the is_valid_path() function in check_or_sanitize_refname(), most likely something like if (!is_valid_path(refname)) return -1; at the beginning
4. build Git via make -j$(nproc)
5. test in-place via ./bin-wrappers/git --exec-path="$PWD" -C <directory> <command>?
6. open a PR?

The Problem is a little bit more complex than only the "Windows create branch side".

On Unix Systems it's ok to create branches with names including < and push it.
Than a Windows user can not fetch the repo anymore.

I think escape the special characters for the Windows path could work. Or git has to disallow create branches with special characters on all systems.

It is especially a problem if you work in a team and your coworkers are on macOS or Linux, where it's apparently okay to use these characters, but whenever you fetch a remote on Windows, you get the error. Characters not allowed in major OSes should be forbidden on every OS. Otherwise, the problem will persist (a warning will not prevent everyone from causing issues for others). It's a breaking change, though, which makes it difficult.

From the look of things, Git uses branch names as file names to create lock files. Why can't illegal characters be substituted transparently (on Windows), e.g. replace them with an underscore? Why use the branch names in the first place? The names could be SHA-1 hashed to ensure that they only contain valid file name characters while still being based on the branch name.

It is especially a problem if you work in a team and your coworkers are on macOS or Linux, where it's apparently okay to use these characters, but whenever you fetch a remote on Windows, you get the error. Characters not allowed in major OSes should be forbidden on every OS. Otherwise, the problem will persist (a warning will not prevent everyone from causing issues for others). It's a breaking change, though, which makes it difficult.

From the look of things, Git uses branch names as file names to create lock files. Why can't illegal characters be substituted transparently (on Windows), e.g. replace them with an underscore? Why use the branch names in the first place? The names could be SHA-1 hashed to ensure that they only contain valid file name characters while still being based on the branch name.

These are good questions for the Git mailing list (send plain-text messages, HTML messages are dropped silently, and do expect to get "home work" 😄).