DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

Cover image for Rename Your Default Branch with Custom Subcommands
Eva Deane
Eva Deane

Posted on • Updated on

Rename Your Default Branch with Custom Subcommands

UPDATE: As of Git version 2.28, this whole process is much simpler! Now $ git config --global init.defaultBranch <NAME>, replacing <NAME> with whatever you want your new default branch name to be, will get you sorted right out. For more information, check out the release notes.

The year is 2020 and you've finally decided that a default "master" branch is no longer such a great option. Maybe you're still at the beginning of your software development journey and don't know where to begin, or you're looking at the sheer number of repositories you have to change and grimacing. When my employers, Andromeda Galactic Solutions, committed to making this change and assigned the task to me, it was a little bit of both -- but ultimately, it ended up being a great learning experience, and with the power of custom Git subcommands, lightning fast, even with our multiple projects!

A couple of notes before we start:

  • I had to cherry-pick information from multiple sources to get a method in place for myself that was truly beginner-friendly; those sources are linked at the end of the post.
  • I use Linux Mint for my development work, so I'm writing from that perspective, but will provide links to instructions for Windows where necessary.
  • As of this original posting, there is no industry-wide standard for a replacement default branch name. I chose latest and so that's reflected in my subcommands and naming, but many others have chosen main, trunk, etc. If you don't want to switch master to latest, just replace all instances of latest with whatever you want to use.

Adding a Custom Subcommand

So what's a subcommand? You know how you use git branch and git push? branch and push are subcommands.

If you're just changing one repository and don't plan on having to switch any others, you can probably skip this bit. But if you've got multiple repos in need of updating, this is a HUGE timesaver! I needed to set up two subcommands, which I called git latest and git local.

In your Terminal (or admin-level command line utility)...

  1. Enter mkdir ~/.gitbin; touch ~/.gitbin/git-<SUBCOMMAND> on a single line. This creates a new directory in your $HOME location called .gitbin and adds a blank text file where you'll write the instructions for your subcommand. Replace the after the dash with whatever you want your subcommand to be -- e.g. local if you want to be able to run the instructions by entering git local. It's important to keep the git- part in the filename because that's what signals to Git "hey buddy, run this!"

  2. Again remembering to replace with the subcommand you picked, chmod u+x ~/.gitbin/git-<SUBCOMMAND> modifies the permissions of your subcommand's text file to allow it to be executed by the user account you're currently logged into on your system.

  3. Open ~/.bashrc with your preferred text editor -- in my case this command looks like nano ~/.bashrc, which opens the .bashrc file using Nano. Add export PATH="$HOME/.gitbin:$PATH" to the end of the file, save your changes, and exit the text editor. (Windows folks, go here for instructions on how to update your $PATH variable.)

  4. cd ~/.gitbin to move to the .gitbin directory you created and open the subcommand file with your preferred text editor -- like in the last step, for me, that was nano git-<SUBCOMMAND> with the replaced with the subcommand I chose. Either enter your own instructions or copy and paste the relevant subcommand from a little further along in the article, save your changes, and exit the editor.

  5. Congratulations on writing a brand-spankin'-new git subcommand, you crafty and efficient person, you! You should now be able to run it from the CLI of your choice.

Here are the git latest and git local subcommands I used for my changes. For both, the #!/bin/bash line is only required if you're adding these to a subcommand file; if you're just manually running the individual commands, ignore it.

git latest

What it does: Changes the default branch from master to whatever you've chosen.
When to use it: Only once, and only in repos that don't already contain this change. You'll need to run this before anyone else can git local the repository.
NOTE: checkout and pull are included here because this process requires an up-to-date master branch on your local machine.

#!/bin/bash
git checkout master
git pull master
git branch -m master latest
git push -u origin latest
Enter fullscreen mode Exit fullscreen mode

git local

What it does: Updates the default branch for a local repository clone on your machine.
When to use it: Only after someone else has run git latest in the repository to make the initial change. If you are the person who ran git latest, you don't need to run this, too.
NOTE: Like with git latest, you must have an up-to-date master branch on your local machine. Also, just in case formatting rears its ugly head, git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/latest should be a single line.

#!/bin/bash
git checkout master
git pull
git branch -m master latest
git fetch
git branch --unset-upstream
git branch -u origin/latest
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/latest
Enter fullscreen mode Exit fullscreen mode

Oh no, latest is set to track origin/master!

In making these changes myself, I noticed that some repositories played nicer than others -- likely due to individual settings. If you change the branch and the output reports that the new default branch is still set up to track origin/master, you can manually unset and reset it with the following:

git branch --unset-upstream
git push -u origin latest
Enter fullscreen mode Exit fullscreen mode

Your new default branch should now be tracking origin/latest.

Change default branch for all newly-created repositories

This is all well and good, but you're going to have to re-run those subcommands every time you make a new repo with git init, right? Do I have news for YOU!

You can change the default branch set with git init to a non-master option. The default branch for new repositories is defined by a HEAD text file telling Git which ref it should use. Once it is set up, everything contained in the templateDir variable will be copied to the .git directory when you make a new repository using git init.

  1. Open ~/.gitconfig with your preferred text editor (e.g. nano ~/.gitconfig) and add the following:
[init]
      templateDir = ~/.config/git/template/
Enter fullscreen mode Exit fullscreen mode
  1. Save your changes and exit the editor.

  2. cd ~/.config and then ls to list all files and directories it contains. If there is no directory called "git" already, mkdir ~/.config/git/template; touch ~/.config/git/template/HEAD to create the required path and a blank text file named HEAD.

  3. Open ~/.config/git/template/HEAD with your preferred text editor (e.g. nano ~/.config/git/template/HEAD) and add the following with a linebreak after it:

ref: refs/heads/latest

Enter fullscreen mode Exit fullscreen mode
  1. Save your changes to HEAD and exit the editor.

Change default branch in version control host

If you don't have admin permissions for the repository you're changing, you'll need to ask someone who does to update the default branch in the actual host from master to whatever you picked.

BitBucket

  1. Open BitBucket in your browser and navigate to the repository you want to update.

  2. From the side panel, click Repository Settings.

  3. On Repository Details, change Main branch to the desired new default branch and click Save repository details.

  4. From the side panel, click Branches and verify that the MAIN and DEVELOPMENT tags appear next to new default branch.

  5. Delete master. (No, really. At this point, if you’ve followed all of the directions, latest is a perfect and up-to-date copy of master, so you shouldn’t need to worry about losing any history or data. Just feel powerful for a few seconds.)

GitHub

  1. Open GitHub in your browser and navigate to the repository you want to update.

  2. Click the Settings tab.

  3. Under Default Branch, select your default-to-be and click Update.

  4. Delete master.

Updating CI/CD and pipelines

Some CI/CD or pipeline code may reference the now-defunct master branch specifically, so we need to be sure that we change these mentions to the name of our new branch. An easy way to do this is to open the local repository in your IDE and search for all instances of master. Results will likely be returned for files like:

README.md
bitbucket-pipelines.yml
package.json

Replace references to master with the name of your new default branch. (Note that some URLs to third-party documentation may include a reference to master in their own hosted filepaths – obviously, don’t change those. Use common sense or ask for advice if you're not sure whether a master reference needs changing.)

When creating the pull request for these changes, double-check that the destination branch is correctly set to the new default branch.

Resources

With massive thanks to these authors:

Top comments (2)

Collapse
tfantina profile image
Travis Fantina

Before I ask my question let me say that I recently initialized a new repo with a "main" branch instead of "master". I'm making strides to decolonize my life and support more black and minority businesses and artists. So please don't take this the wrong way but I'm really curious about the reasoning for this change. I understand the problematic language of "master" and "slave" terminology but the word "master" has many different meanings. One could be a master of their field, literally, and hold a Master's degree. One could master a course or skill. Personally, when I thought of the master branch until about two years ago I thought of it as sort of an omnipotent presence like the master of the universe.

Honestly, I'm happy to make the change because if it helps just one person to feel more included or more comfortable it's such a small thing to do I figure why not but I'm wondering if there is a historical context to the naming that makes it more problematic then just using the term master.

Collapse
bunnyladame profile image
Eva Deane Author • Edited on

It's a legitimate question, and thank you for asking it and giving someone a chance to answer. As disclosure, I am a non-Black POC so there are definitely people more fit to answer this, but I will do my best and hope that if there are any Black developers out there who are willing to give a better one, they feel empowered to do so -- I'm not trying to take anybody's space! I'm offering my view of it based solely on being a linguistics nerd.

You are correct about the different usages of "master," and it's really related to the connotation of the word. All of the definitions still indicate a position of dominance over other "lesser" beings. And if you break down the horrible thought processes behind slavery in the first place... there you go. Even though there's no "slave" branch, that superiority is still implied.

It can also be jarring to see the word for folks who are closer to the historical usage. I'm Jewish, and everytime I see someone refer to something as "a holocaust" I clench a bit. Even though they're not talking about THE Holocaust, it still summons up some deeply negative and frightening emotions for me.

I hope this helps a little bit! Thank you for your maturity, too -- despite having questions, you are still willing to make the change to spare other people's suffering. :) Good on you.

πŸ€” Did you know?

Β 
🌚 Dark mode is available in Settings.