Enforce lowercase branch names on GitHub

In this post I describe how to set up a branch name rule to avoid issues with case-sensitive branches in GitHub.

To introduce the problem: Git uses case-sensitive branches, but stores the branches in a file system on disk. If the filesystem is not case sensitive this will cause problems with git.

For example: Given two branches: feature/cool-feature and Feature/awesome-button. If a Windows user tries to checkout both these branches git will complain that the second branch is not found. (See StackOverflow discussion. You may find it with another casing, but that will then again fail on GitHub when pushing changes! The best way to avoid this (without fixing git itself…) is to enforce lower case branch names.

Note: I suggest enforcing this only if all existing GitHub branches are lower case. Try to adjust the regex to your naming standard if its different from the one suggested in this post.

To enforce lower case branch names in GitHub we can use a repository setting called Code and automation -> Rules -> Rulesets

By creating a ruleset, we can mandate that branch names be lowercase.

1. Go to your repo. Find the Settings. Find the Rulesets menu item.
2. Create a ruleset:
   1. Name the ruleset: Avoid git case-sensitivity issues by enforcing lowercase branch names
   2. Target all branches.
   3. Enable the “Restrict branch names” rule
   4. Create a restriction for the branch name:
      1. Branch name rule
      2. Must NOT match the following regex
      3. (?-i)([A-Z])(Branch name must be fully lower case)*
         • The (?-i) part is crucial as it disables case-insensitive matching for the following pattern!
         • Also note the Optional description (Branch name must be fully lower case)*. This helps give a message to the user of what is wrong. (Standard error message displayed in git cli is remote: - Branch name must not match a given regex pattern: (?-i)[A-Z], so adding the description into the regex helps indicate whats wrong)
      4. Description Branch name must be fully lowercase (This description is not available in the git terminal, so not sure where its used)
3. Press Save Changes button and test this in your repo

When pushing a branch with a upper-case letter the client will get an error message that’s descriptive enough to pinpoint the problem! This avoids them from pushing the branch, and affecting other users.

Thats it for this time, I hope this helps avoid the branch name case sensitivity issue for you. I’ts also my hope that git or GitHub at some point will fix the issue for all users.

// Nils Henrik