How to rename 'master' in an organization
Tags: devops, inclusion, git
Published: 2020-07-07 03:48:47

We were deciding what to rename our primary development branch...

{% link https://dev.to/mousepawmedia/goodbye-master-hello-what-34b9 %}

**The result: `devel` won!** It will join `fresh` and `stable` as our triad of protected branches.

Today, we started the transition from `master` to `devel`. While many guides exist to explain how to rename `master` on your own repositories, this gets a little more complicated in a team.

Here's a few things you can do to make that transition easier.

## Phase 0: Prepare

Make sure your team knows what's happening. Give them a few weeks notice. Explain your motivation for renaming `master`. 

Seriously consider giving them a say in what the new primary branch should be. Cultural and historic issues aside, `master` was never a particularly insightful name, so take the occasion to find one the majority of your team actually *likes*! You can see some of our thoughts on four candidate names for the primary branch on the article mentioned above.

Set a date for the start of the transition. It's best if you pick a period somewhere towards the start of a development cycle, whatever that means to you, to limit disruption to workflow. Don't let the word "disruption" scare you off; chances are, this will go smoothly, but you still don't want to risk a hiccup a few days before something is supposed to ship to prod. ;)

## Phase 1: Renaming

This is where you actually rename the branches! For this guide, I'll use `devel` for the new name, since that's what we picked, but you can substitute whatever name you prefer in there.

Here's the command for this, taken from [this article by Alexis Moody](https://dev.to/afrodevgirl/replacing-master-with-main-in-github-2fjf), and adapted to our use:

```
git branch -m master devel
git push -u origin devel
```

Next, on your repository management tool ­— GitHub, GitLab, Bitbucket, Phabricator (in our case), or whatever) — set the new `devel` branch as the primary.

***Do not yet delete `master`!!!*** This helps protect against initial bumps in the road:

* Developers can still pull *from* master.
* The CI/CD pipeline won't all break right away.
* It's extra insurance against data loss.

Instead, create a Git hook to block any changes pushed to `master`. This is a gentle way to transition your developers until they get into the new habit.

Now, go change your build pipeline. This part may or may not take a while.

## Phase 2: Retraining

Instruct your developers to update their local copies, and give them time ­— say, a month? — to do it! Be sure to provide the commands to do so (see below).

That commit hook will prevent them from pushing to `master` out of habit, but the fact that `master` still exists (but not as the primary branch) will help smooth the transition.

To update a local copy to the new branch name, we're using the following code, based on [this article by Scott Hanselman](https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx):

```
git checkout master
git branch -m master devel
git fetch
git branch --unset-upstream
git branch -u origin/devel
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/devel
```

At this point, you should also update your workflow documentation. If one or more of your team members has some extra bandwidth, consider asking them to undertake this. It will help them get into the habit of thinking of "devel" instead of "master".

During this time, builds should still be running, but on the new branch name (barring errors). Most issues with the changes to the CI/CD will resolve during this time.

## Phase 3: Deleting `master`

After about a month, your team will likely have updated their workflows and habits, at least for the most part. You can now delete `master` on each of your repositories:

```
git push origin --delete master
```

Each of your developers can see the change by running the following on their local copies:

```
git fetch -p
```

Expect a few fresh issues with your CI/CD (there's always *one* typo, isn't there?), but most of those should be easy to iron out.

And, you're done! You have a shiny new primary branch with a *useful* name. What's further, you'll never have to do this again.

# ...or so we hope!

Okay, at least that's how it's supposed to go. We're through Phase 1 without any hiccups, but we'll be sure to update this post if there's anything else that comes up in the next month.

For us, `master` is set to be deleted on all our repositories on Monday, 03 August 2020! If there's any dramatic explosions of the build pipeline, we'll share the details on Twitter. :)

Is there anything you or your team has done to make this transition go smoother? Let us know in the comments!

---

<sup>WARNING: This is not the place to debate about whether master should be renamed. Any comments to that effect will be hidden and reported.</sup>