How to rename the git default branch of private repos

In this post, I will explain how to rename the default branch of privately hosted git repositories both locally as well as on remotes.


Let’s suppose that a repository has been created on the “remote”, e. g. by issuing:

$ mkdir -p ${HOME}/git
$ cd ${HOME}/git
$ git init --bare myrepo.git

Then, this repository has been checked out on the “local” machine, e. g. by issuing:

$ git clone username@remote.tld:/home/username/git/myrepo.git

After working with the repository for some time you realize that the default branch you have been working with is called “master”. Now, let’s assume you want to rename this branch to “main” both locally and on the remote. The following sections explain what needs to be done and where these steps need to be performed.

Switching from “master” to “main” locally

Let’s start by renaming the branch on the “local” machine:

$ git branch -m master main
$ git status
On branch main
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

The main branch can then be pushed to the “remote” to make it available there too:

$ git push -u origin main
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To remote.tld:/home/username/git/myrepo.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

Now that the main branch is also available on the remote, we are about to remove it there.

Deleting the “master” branch on the remote (first attempt)

Deleting the “master” branch on the “remote” does not work yet:

$ git push origin --delete master
remote: error: By default, deleting the current branch is denied, because the next
remote: 'git clone' won't result in any file checked out, causing confusion.
remote: You can set 'receive.denyDeleteCurrent' configuration variable to
remote: 'warn' or 'ignore' in the remote repository to allow deleting the
remote: current branch, with or without a warning message.
remote: To squelch this message, you can set it to 'refuse'.
remote: error: refusing to delete the current branch: refs/heads/master
To remote.tld:/home/username/git/myrepo.git
 ! [remote rejected] master (deletion of the current branch prohibited)
error: failed to push some refs to 'remote.tld:/home/username/git/myrepo.git'

The reason is this: on the “remote”, the default branch is still called “master”. Deleting this (still referenced branch) would result in strange error messages when cloning it. In order to come around this, the default branch has to be re-defined on the remote as well.

Defining the default branch on the “remote”

On the remote machine in the directory of the bare git repository, issue the following command:

$ git symbolic-ref HEAD refs/heads/main

Now that the “master” branch is not referenced on the remote anymore, it can finally be deleted.

Deleting the “master” branch on the remote

Back on the “local” machine, let’s try again:

$ git push origin --delete master
To remote.tld:/home/username/git/myrepo.git
 - [deleted]         master

It worked. Goal achieved. Now, even when cloning the repository again, the “main” branch is being checked out automatically.

comments powered by Disqus