Main and Master Branch in Git: what it is and why you need a main branch

What is Main / Master Branch in Git

Main Branch (or Master — depending on repository settings) is the default branch that is created when initializing any Git repository. It is the main branch of the project and contains code ready for production deployment.

Unlike develop, where daily work with new features is in full swing, main is the project’s showcase. Each version of code in main has gone through a full cycle: development in a feature branch, integration into develop, release preparation in a release branch, and final testing. Only after that do changes make it to main.

Key principle: main must always be stable. If an error is found in main, it means an urgent hotfix needs to be released out of turn. Therefore, in professional projects, main is protected from accidental changes by branch protection rules.

According to Git Book, main is not a special branch with unique properties, but a regular reference to a commit that is conventionally considered the main one. Git makes no distinction between main and any other branch at the system level.

Transition from master to main

Historically, the default branch in Git was called master. In June 2020, the Black Lives Matter movement drew attention to the terms master and slave in the IT industry. GitHub announced a transition to the term main for the default branch.

Since October 2020, all new repositories on GitHub are created with the main branch. GitLab and Bitbucket have also implemented support for main as the default name. Git 2.28 (July 2020) added the init.defaultBranch option for configuring the default branch name.

Technically, renaming an existing branch from master to main is a simple operation. The main challenge is updating all references in CI/CD configurations, documentation, and developers’ local repositories.

To rename a branch in an existing repository, run:

# Local rename of master to main
git branch -m master main

# Update remote repository
git push -u origin main

# Delete old master on server
git push origin --delete master

# Update HEAD on server
# (via GitHub web interface: Settings → Branches → Default branch)

Role of main in Git Flow and GitHub Flow

Git Flow and GitHub Flow define the role of the main branch differently. The choice of model depends on team size, release frequency, and code stability requirements.

For mobile development, Git Flow is the standard, since publishing an app to the App Store and Google Play has fixed release cycles. GitHub Flow is more suitable for web projects that can be deployed multiple times a day.

GitHub Flow — simplified approach

In GitHub Flow, there is no develop branch. All feature branches are created directly from main, and upon completion, they are merged back via a Pull Request. Each merge into main automatically triggers deployment to production. This model requires a high level of test automation and team discipline.

In GitHub Flow, there is no develop branch. All feature branches are created directly from main, and upon completion, they are merged back via a Pull Request. Each merge into main automatically triggers deployment to production. This model requires a high level of test automation and team discipline.

Main branch protection

Branch protection for main is a mandatory setting in any commercial project. Without it, an accidental push could send unfinished code to production or break a working application for all users.

• Require pull request — direct push to main is prohibited. All changes via PR with review.
• Require approvals — minimum 2 approvals for merging into main (in case one reviewer misses something).
• Require status checks — all CI/CD checks must pass before merging.
• Require up-to-date — the PR must be based on the latest main commit.
• Include administrators — protection applies even to repository owners.
• Require signed commits — all commits to main must be signed with a GPG key.

Configuring all six rules is the standard for mobile projects with an audience of 10,000+ users. For small projects, the first three rules are sufficient.

Protection level comparison for different project types

The level of main protection depends on the project’s scale. A startup can get by with minimal protection, while an enterprise application requires maximum restrictions.

Releases and tags in main

Tagging is the practice of creating named references to specific commits in main. Each tag corresponds to a version of the application released to production. This allows quickly switching to any previous release for debugging or patching.

The standard naming convention for tags in mobile development is SemVer (Semantic Versioning): v1.2.3, where the first number is the major version (breaking changes), the second is the minor version (new features), and the third is the patch (fixes).

A tag is created after the release branch is merged into main. This commit is then built in CI/CD, signed, and sent to the app store. If an error is found in the tag, a hotfix branch is created from that tag.

# Create annotated release tag
git tag -a v2.4.1 -m "Release version 2.4.1"

# Push tag to server
git push origin v2.4.1

# View all tags in repository
git tag -l "v2.*"

# Create hotfix branch from a specific tag
git checkout -b hotfix/crash-fix v2.4.1

Git Flow branch hierarchy

Understanding the branch hierarchy in Git Flow is the foundation for properly organizing collaborative development. Each branch type has its own source, purpose, and merge rules.

• Main (Level 1) — the root branch, contains only release versions. Created when initializing a repository.
• Develop (Level 2) — created from main at project start. Contains integration code for all features.
• Feature (Level 3) — created from develop. Isolated development of individual features.
• Release (Level 2) — created from develop. Preparation of a specific release for launch.
• Hotfix (Level 2) — created from main. Urgent fixes for critical production errors.

Important rule: feature is never merged directly into main. feature → develop → release → main is the correct merge chain. Violating this rule defeats the purpose of the entire Git Flow model.

Command examples for working with main

Consider a scenario: the team has completed preparing release v2.5.0. The release branch is reviewed and ready to be merged into main. After merging, a tag is created and the release is published.

# Switch to main and update
git checkout main
git pull origin main

# Merge verified release branch
git merge --no-ff release/2.5.0

# Create release tag
git tag -a v2.5.0 -m "Release 2.5.0 - Payment integration"

# Push main and tag to server
git push origin main --tags

The --no-ff flag (no fast-forward) guarantees creating a merge commit, even if the merge could have been done by simply moving the pointer. This preserves information that the changes came from a release branch, making history analysis easier.

Working with hotfix through main

If a critical error is discovered in production, the process differs from a normal release. A hotfix is created from main, and after fixing, it is merged into both main and develop.

If a critical error is discovered in production, the process differs from a normal release. A hotfix is created from main, and after fixing, it is merged into both main and develop.

# Create hotfix branch from main
git checkout main
git checkout -b hotfix/2.5.1-crash-fix

# Fix and commit
git add src/fix/
git commit -m "Fix crash on login screen"

# Merge hotfix back to main
git checkout main
git merge --no-ff hotfix/2.5.1-crash-fix
git tag -a v2.5.1 -m "Hotfix 2.5.1"
git push origin main --tags

# Merge hotfix to develop as well
git checkout develop
git merge --no-ff hotfix/2.5.1-crash-fix
git push origin develop

# Delete hotfix branch
git branch -d hotfix/2.5.1-crash-fix