Renaming master to main in Git

[mdlbear]

If you've been paying attention to the software-development world, you may have noticed a movement to [remove] racist terms in tech contexts. The most obvious such terms are "master" and "slave", and there are plenty of good alternatives: primary/secondary, main/replica, leader/follower, etc. The one that almost every software developer sees every day is Git's "master" default branch. This issue on GitLab includes some good discussion of what makes "main" the best choice for git. (I've also seen "mainline" used.)

Renaming your master branch is easy. If you have a local repo that isn't a clone of anything (so it doesn't have any remotes), it's a one-liner:

   git branch -m master main

Renaming the default branch on an existing repo is trivial. If it has no remotes, for example if it's purely local or a shared repo on a server you have an ssh account on, it's a one-liner:

   git branch -m master main

It's a little more complicated for a clone, but not much more complicated:

   git branch -m master main
   git push -u origin main
   git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
   git pull

What you need to do at this point depends on where your origin repo is located. If you've already renamed its default branch, you're done. If you haven't, the git push -u created it. At this point if your origin repo is on GitHub, need to log in and change its default branch from master to main because it won't let you delete its default branch.

Then, delete the old master branch with

   git push --delete master

This works for simple cases. It gets a little more complicated on GitHub because you might have web hooks, pull requests, and so on that still refer to master. GitHub says that renaming master will be a one-step process later in the year, so you may want to wait until then. For less complicated situations, any URLs that reference master will get automatically redirected to main. See this page for details.

I had a slightly different problem: my shared repositories are on my web host, and there are hook scripts that pull from the shared repo into the web directory. My version of the post-update only looks for changes in the master branch. Fortunately that's a one-liner, too:

   ssh HOST sed -i -e s/master/main/g REPO/hooks/post-update

 

The next problem is creating a new repo with main as the default branch. GitHub already does this, so if you are starting your project there you're good to go. Otherwise, read on:

The Git project has also added a configuration variable, init.defaultBranch, to specify the default branch for new repositories, but it's probably not in many distributions yet. Fortunately, there's a workaround, so if you don't want to wait for your distribution to catch up, you can take advantage of the way git init works, as described in this article by Leigh Brenecki:

1. Find out where Git keeps the template that git init copies to initialize a new repo. On Ubuntu, that's /usr/share/git-core/templates, but if it isn't there look at the man page for git-init.
2. Copy it to someplace under your control; I used .config/git/init-template.
3. cd to the (new) template and create a file called HEAD, containing ref: refs/heads/main.
4. Set the init.templateDir config variable to point to the new template.

Now when git wants to create a new repo, it will use HEAD to tell it which branch to create. Putting all that together, it looks like:

   cp -a /usr/share/git-core/templates/ ~/.config/git/init-template
   echo ref: refs/heads/main > ~/.config/git/init-template/HEAD
   git config --global init.templateDir ~/.config/git/init-template

You can actually replace that initial copy with mkdir; git is able to fill in the missing pieces. Alternatively, you can add things like a default config file, hooks, and so on.

(I've already updated my configuration repository, Honu, to set up the modified template along with all the other config files it creates. But that probably doesn't help anyone but me.)

Resources

• Removing racist terms in tech | Go Make Things
• How to rename your default GitHub branch to main | Go Make Things
• web tool: Rename GitHub Default Branches
• 5 steps to change GitHub default branch from master to main | Steven M. Mortimer
• github: Guidance for changing the default branch name for GitHub repositories -> there will be a seamless 1-step process later this year.
• Links to deleted branches now redirect to the default branch - GitHub Changelog
• Easily rename your Git default branch from master to main - Scott Hanselman
• Git: Renaming the "master" branch - DEV -> instructions for github and gitlab
• Change the default initial branch name for new projects on GitLab (#221164)
• Changing the default branch for new Git repositories — Leigh Brenecki
• Change Default branch in gitlab - Stack Overflow

Another fine post from The Computer Curmudgeon (also at computer-curmudgeon.com).
Donation buttons in profile.

NaBloPoMo stats:
   2146 words in 4 posts this month (average 536/post)
    814 words in 1 post today

Comments

[madfilkentist]

I suppose I should note that "master" is not a "racist term." ("Slave" is another matter, and replacing it with something that causes less cringing is fine with me.) The southern United States didn't invent the word. The word derives from the Latin "magistare," which originally referred primarily to mastery of knowledge or a skill. It has had many uses. I have a Master's degree in computer science, reflecting the old usage (and perhaps giving me too much credit). Medieval guilds had masters. There are ship's masters, again referring to professional capacity rather than command. There are master craftsmen (or craftspeople).

It doesn't bother me whether a branch is called "main," "master," "top," or anything else. It bothers me when people accept the notion that all of history is about race. The idea that the human species is divided into genetically distinct "races" is a relatively modern concept and a fictitious one. This idea has been used to promote identity politics, a notion found on both the right and left, which says that people should regard each other not as people, but as members of "racial" groups. That is an idea which is both false and dangerous. Rewriting history and etymology based on the notion that words have a fundamentally racial purpose when they don't contributes to the damage.

[mdlbear]

Perhaps I should have made that more clear; many of the articles I refer to go into some detail about it.

I said nothing about "the notion that all of history is about race"-- obviously it isn't. But a great deal of American history over the last three centuries is about racism. "Racism" is not about biology, it's purely a social construct, and in the absence of other context (e.g. "master copy", "re-mastered recordings", etc.) the association between "slave" and "master" is strong enough to make some people, especially those of African descent, uncomfortable, as shown in a few informal surveys.

And as you'll find in the discussion on GitLab of issue #221164, "main" is used far fewer contexts than "master", and is both unique and descriptive in the context of version control. It also preserves muscle-memory for tab completion; the only other proposed term that does this is "mainline" (used in Amazon, I think because of their former use of Perforce).