Modern development workflows have largely standardized on `main` as the default branch name, yet many repositories still operate with `master` as the primary branch. The shift reflects a broader industry movement toward inclusive language, and for teams using Git, the need to change master to main has become a routine administrative task. This process involves more than a simple rename; it requires coordination, history preservation, and updated remote tracking to ensure the transition is clean and non-disruptive.
Understanding the Branch Rename Process
At its core, changing the default branch name is a two-step operation involving the local repository and the remote hosting service. Locally, you are simply updating the symbolic reference from `master` to `main`. However, because the remote repository is an independent entity, you must explicitly create a `main` branch on the remote and then adjust the upstream tracking relationship. Failing to synchronize both sides will result in pushes being rejected or the new branch not being recognized as the primary line of development.
Preparing Your Local Repository
Before altering the global state of your project, it is wise to ensure your working directory is stable. Commit any pending changes or stash them to avoid conflicts during the rename. The goal is to have a clean `HEAD` that points to the latest commit on the `master` branch. This precaution minimizes the risk of losing work or creating a detached HEAD state, which can complicate the subsequent steps.
Local Renaming Commands
Once your workspace is secure, you can rename the local branch. The recommended approach uses the `git branch` command to create the new reference and delete the old one in a single, atomic operation. This ensures that the history, commits, and tags associated with the branch remain fully intact while only the name itself changes.
Execute git branch -m master main to rename the current branch locally.
Verify the change with git branch to confirm that `main` is now the active branch.
Check the commit log using git log --oneline to ensure no history was lost during the transition.
Synchronizing with the Remote Repository
With the local branch renamed, the remote repository remains unaware of your change. You must push the new `main` branch to the remote origin while simultaneously removing the old `master` reference. This step is critical because the remote server often dictates the default branch used in pull requests and repository settings. Pushing correctly establishes the new branch as the canonical line of development.
Updating Remote References
The push operation requires specific flags to handle the deletion of the old branch and the creation of the new one. By pushing the local `main` to the remote and then deleting the remote `master`, you effectively migrate the primary branch. After this operation, your local `main` should track the remote `main`, creating a seamless connection for future pulls and pushes.
Push the new branch and set upstream tracking: git push -u origin main .
Delete the old remote master branch: git push origin --delete master .
Verify the remote state with git remote show origin to confirm the HEAD is set to `main`.
Adjusting Platform Settings
For repositories hosted on platforms like GitHub, GitLab, or Bitbucket, the default branch setting is a configurable option that controls visibility features such as the main code view and deployment triggers. Even after the Git operations are complete, the web interface may still point to `master`. Teams must manually update these settings to align with the new naming convention, ensuring the user interface reflects the current workflow.
