Explanation of how GitHub initially sets the default branch of a repository

How GitHub sets the default branch of a repository?.md

On a repository that already contains multiple branches, you can set (change) the default branch for that repository by:

• Navigating to the repository on GitHub.
• Then to "Settings -> Branches".
• Then by changing the value of the "Default branch" setting.

However, on a new repository, there isn't a default branch yet because there aren't any branches yet! GitHub sets the default branch on the very first push to that repository. It does it as follows:

• In the very first push of the repository to GitHub, try to find a branch that has the same name as the value of the "Repository default branch" setting. (The "Repository default branch" setting is accessed by clicking on your user avatar on GitHub, then "Settings -> Repositories".)
• If the very first push contains a branch whose name is the same as the value of the "Repository default branch" setting, then GitHub sets that branch as the default branch for that repository. Otherwise, the default branch becomes the branch whose name is alphabetically the smallest among the branches of the very first push.

Repository default branch example

The value of the "Repository default branch" setting for your GitHub account is baz. You create a repository named Default Branch Test - Repository Default Branch Setting (or any other name) on GitHub. Then, you launch the shell on your computer and you run the following commands:

# You can give any name to the directory
mkdir 'Test for Repository Default Branch Setting of GitHub'
cd 'Test for Repository Default Branch Setting of GitHub'
git init

git checkout -b foo
echo 'On branch foo. This is the first commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch foo'

git checkout -b baz
echo 'On branch baz. This is the second commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch baz'

git checkout -b qux
echo 'On branch qux. This is the third commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch qux'

git checkout -b bar
echo 'On branch bar. This is the fourth commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch bar'

git push [email protected]:YOUR_GITHUB_USERNAME/Default-Branch-Test---Repository-Default-Branch-Setting.git --all

# Alternatively:
# git remote add github [email protected]:YOUR_GITHUB_USERNAME/Default-Branch-Test---Repository-Default-Branch-Setting.git
# git push github --all

# Yet another alternative:
# git remote add origin [email protected]:YOUR_GITHUB_USERNAME/Default-Branch-Test---Repository-Default-Branch-Setting.git
# git push --all

After these, when you open the repository on GitHub, you will observe that even though the branch baz is not the alphabetically smallest one among these branches (bar is the smallest one), baz is set as the default branch since the value of our "Repository default branch" setting was baz at the time that this repository was created.

Note that changing the value of "Repository default branch" setting will affect only repositories that are created after the change. For example, the value of the "Repository default branch" setting is baz. You created a repository but before making the very first push to that repository, you changed the value of "Repository default branch" setting to bar. When you make the very first push to the repository, GitHub will not search for bar. It will search for baz, since that was the value of the "Repository default branch" at the time that the repository was created. If GitHub does not find baz among the branches of the very first push, then it will compare the branches of the very first push alphabetically and it will set the branch that is alphabetically the smallest as the default branch.

Alphabetical comparison example

Again, the value of the "Repository default branch" setting for your GitHub account is baz. You create a repository named Default Branch Test - Alphabetic Branch Selection (or any other name) on GitHub. Then, you launch the shell on your computer and you run the following commands:

# You can give any name to the directory
mkdir 'Test for Alphabetic Branch Selection of GitHub'
cd 'Test for Alphabetic Branch Selection of GitHub'
git init

git checkout -b grault
echo 'On branch grault. This is the first commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch grault'

git checkout -b qux
echo 'On branch qux. This is the second commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch qux'

git checkout -b corge
echo 'On branch corge. This is the third commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch corge'

git checkout -b quux
echo 'On branch quux. This is the fourth commit.' > some-random-file.txt
git add some-random-file.txt
git commit -m 'Create branch quux'

git push [email protected]:YOUR_GITHUB_USERNAME/Default-Branch-Test---Alphabetic-Branch-Selection.git --all

# Alternatively:
# git remote add github [email protected]:YOUR_GITHUB_USERNAME/Default-Branch-Test---Alphabetic-Branch-Selection.git
# git push github --all

# Yet another alternative:
# git remote add origin [email protected]:YOUR_GITHUB_USERNAME/Default-Branch-Test---Alphabetic-Branch-Selection.git
# git push --all

After these, when you open the repository on GitHub, you will observe that the branch corge is set as the default branch, since the very first push does not contain a branch whose name is the same as the value of the "Repository default branch" setting at the time this repository was created. That is, since the very first push does not contain a branch named baz, GitHub makes an alphabetical comparison of the names of the branches of the very first push and sets the branch whose name is the smallest between an alphabetical comparison of the branches of the very first push as the default branch.

Note that GitHub sets default branch on the very first push and does not change the default branch by itself later. To change it, you, the user, has to manually go to the repository page on GitHub, then to "Settings -> Branches" and edit the value of the "Default branch" setting there. To give an example, let's say that in addition to our latest commits of the last example (the "Alphabetic Branch Selection" example), we create a new branch named baz, make a commit to it and push that branch. (We picked the name baz for the new branch because baz was the value of the "Repository default branch" setting at the time this repository was created). Even though baz was the value of the "Repository default branch" setting at the time this repository was created, when we open the repository page on GitHub after this last push, we observe that the default branch is still corge. That is, it hasn't been changed to baz even though baz was the value of the "Repository default branch" setting at the time this repository was created. The reason is, as we stated, default branch is set on the very first push to that repository and it is not changed later unless the user manually changes it by editing (setting) the value of the "Default branch" setting from the repository page, "Settings -> Branches".