Unclear error handling when trying to create a branch with Windows filesystem disallowed characters < > | "

[whitneyschmidt]

• I was not able to find an open or closed issue matching what I'm seeing

Setup

• Which version of Git for Windows are you using? Is it 32-bit or 64-bit?

64 bit

$ git --version --build-options
git version 2.29.2.windows.2
cpu: x86_64
built from commit: 3464b98ce6803c98bf8fb34390cd150d66e4a0d3
sizeof-long: 4
sizeof-size_t: 8
shell-path: /bin/sh

• Which version of Windows are you running? Vista, 7, 8, 10? Is it 32-bit or 64-bit?

Windows 10 Enterprise 20H2

$ cmd.exe /c ver

Microsoft Windows [Version 10.0.19042.630]

• What options did you set as part of the installation? Or did you choose the
  defaults?

Choose the defaults.

# One of the following:
> type "C:\Program Files\Git\etc\install-options.txt"
> type "C:\Program Files (x86)\Git\etc\install-options.txt"
> type "%USERPROFILE%\AppData\Local\Programs\Git\etc\install-options.txt"
$ cat /etc/install-options.txt

$ cat install-options.txt
Editor Option: VIM
Custom Editor Path:
Default Branch Option:
Path Option: Cmd
SSH Option: OpenSSH
Tortoise Option: false
CURL Option: OpenSSL
CRLF Option: CRLFAlways
Bash Terminal Option: MinTTY
Git Pull Behavior Option: Merge
Use Credential Manager: Core
Performance Tweaks FSCache: Enabled
Enable Symlinks: Disabled
Enable Pseudo Console Support: Disabled

• Any other interesting things about your environment that might be related
  to the issue you're seeing?

** insert your response here **

Details

• Which terminal/shell are you running Git from? e.g Bash/CMD/PowerShell/other

Git for Windows 👍

• What commands did you run to trigger this issue? If you can provide a
  Minimal, Complete, and Verifiable example
  this will help us understand the issue.

$ 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 "hi>"
fatal: cannot lock ref 'refs/heads/hi>': Unable to create 'C:/Users/whschm/source/repos/TestRepo/.git/refs/heads/hi>.lock': Invalid argument

$ git checkout -b ":"
fatal: ':' is not a valid branch name.

• What did you expect to occur after running these commands?

A nicer error message, like the one for ":" that indicates that there's an invalid character in the branch name.

• What actually happened instead?

fatal: cannot lock ref 'refs/heads/hi>': Unable to create 'C:/Users/whschm/source/repos/TestRepo/.git/refs/heads/hi>.lock': Invalid argument

< and > are both disallowed characters for file names in the windows file system, so this seems likely to be related to how Git for Windows handles these characters.

The git (Linux) repo doesn't sanitize input for < or > and the man page doesn't indicate that either of these are invalid characters.

• https://www.linux.org/docs/man1/git-check-ref-format.html
• https://github.com/git/git/blob/7f7ebe054af6d831b999d6c2241b9227c4e4e08d/refs.c#L63

It would be great to have better error handling/user experience for this case!

• If the problem was occurring with a specific repository, can you provide the
  URL to that repository to help us with testing?

N/A

[dscho]

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.

[rimrul]

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.

[rimrul]

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.

[dscho]

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.

[whitneyschmidt]

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 🙈

[rimrul]

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?

[whitneyschmidt]

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

[cristanpale]

Thanks for sharing a helpful and useful post to us.I have a same issue i also try but in vain please anybody help me
https://netmodapk.com/netflix-cracked-apk/
https://netmodapk.com/netflix-cookies/
https://netmodapk.com/

thanks

[dscho]

@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?

[pinguin999]

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.

[Simran-B]

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.