Hotfix Branch: What It Is, How to Create and Use in Mobile Development

What is a Hotfix Branch?

Hotfix Branch is a temporary Git branch created for quickly fixing critical defects in a live production environment. Unlike feature branches, which branch off from develop and live for several days or weeks, a hotfix is created from main/master and exists only as long as necessary to fix the bug.

The main goal of a hotfix is to minimize the time between discovering a critical error and fixing it in production. The team does not wait for the current sprint or release cycle to finish — they deploy a patch immediately. This is especially important for mobile applications, where a critical bug can block users and lead to churn.

According to Google Play Console, the average update review time in Google Play ranges from 2 to 24 hours. For the App Store, express review can take from 1 to 4 hours. Hotfix branches allow you to prepare the fix before moderation is complete and deploy it immediately after approval.

How Hotfix Works

The hotfix process consists of three steps: creating a branch from main, making the fix, and merging back into main and develop. The key difference from a regular fix is that a hotfix is always merged into both branches, so the fix is not lost in the next release.

The team should not introduce new functionality or refactoring into a hotfix. Only a targeted fix, minimally necessary to resolve the critical issue. Any deviation from this rule increases the risk of regression and delays the patch release.

When a Hotfix is Needed

A hotfix is necessary in three scenarios: a critical bug blocks users (crash, data loss), a security vulnerability requires immediate closure, or critical business logic is broken (payments, authorization). If the bug is not critical — it can be fixed within the regular release cycle through develop.

For mobile applications, a hotfix can also include server-side changes if the architecture allows remote feature toggling (feature flags). In this case, the hotfix branch may be minimal or unnecessary if the fix can be made on the server side.

Branching Models and Where Hotfix Fits

Not all branching models support hotfix branches. The traditional Git Flow includes hotfix as a full-fledged branch type, while more modern approaches (GitHub Flow, Trunk-based) handle emergency fixes differently.

Git Flow and Hotfix

Git Flow is the only model where hotfix is a built-in branch type alongside feature and release. In Git Flow, a hotfix is created from main, and upon completion, is merged into both main (with a version tag) and develop. This ensures the fix is not lost in the next release.

GitHub Flow and Trunk-based

GitHub Flow does not use a separate branch type for hotfixes. Instead, a developer creates a regular feature branch from main, makes the fix, and opens a Pull Request. After review and CI checks, the branch is merged into main and immediately deployed. The advantage is simplicity; the disadvantage is the lack of a dedicated channel for urgent fixes.

Trunk-based development handles hotfixes through commits directly to main (for critical cases) with mandatory post-factum review. This approach requires a high level of team discipline and reliable automated tests, since changes go into production instantly.

How to Create a Hotfix Branch

Creating a hotfix starts with switching to the main branch and creating a new branch with the hotfix/ prefix. Let's walk through the process using the example of fixing a critical bug in a mobile application.

Creating a Branch from main

First step — switch to main and make sure the branch is up to date. Then create a hotfix branch with a clear name that reflects the nature of the fix.

# Switch to main and get the latest changes
git checkout main
git pull origin main

# Create a hotfix branch
git checkout -b hotfix/crash-on-login

After creating the branch, you can make the fix. It is important to remember: a hotfix should contain a minimal number of changes. Do not refactor code or add new features — only the targeted fix that resolves the problem.

Committing the Fix

The commit in a hotfix should have an informative message that clearly describes the problem and its solution. Format: type(scope): short description + link to the tracker issue.

# Add changed files
git add src/ui/login/LoginActivity.kt

# Create a commit with a description
git commit -m "fix(login): handle null intent on activity resume

Fixes CRASH-142: NullPointerException when LoginActivity
receives onNewIntent after being destroyed by system"

The commit message should contain a problem description and a link to the issue. This simplifies searching the history and helps colleagues understand what was fixed and why. For mobile projects, it is also common to include the application version where the bug was found.

Merging into main and develop

The final step is to merge the hotfix back into main (with a new patch version tag) and into develop (so the fix is preserved in the next release). First, merge into main with a tag, then merge into develop.

# Merge into main and create a tag
git checkout main
git merge --no-ff hotfix/crash-on-login
git tag -a v2.3.1 -m "Hotfix: crash on login"

# Merge into develop
git checkout develop
git merge --no-ff hotfix/crash-on-login

# Push changes to the server
git push origin main --tags
git push origin develop

The --no-ff flag ensures a merge commit is created even if the hotfix could have been applied via fast-forward. This preserves information that an emergency fix was performed and simplifies future history analysis.

Difference Between Hotfix, Feature, and Release Branches

A hotfix is fundamentally different from feature and release branches in terms of purpose, lifespan, and merge rules. Understanding these differences is critical for properly organizing Git processes in a team.

A feature branch is intended for new functionality. It lives from several days to several weeks, is created from develop, and is merged back into develop. A feature may contain many commits, including experimental ones, which are later squashed or rebased.

A release branch prepares a release for deployment. It is created from develop, bugs found during stabilization are fixed in it, and it does not accept new functionality. After completion, the release branch is merged into main (with a tag) and develop.

A hotfix, on the other hand, is created and merged directly with main, bypassing develop (though after the fix it is also synchronized with develop). It contains a minimal amount of changes and exists for a minimal amount of time. While feature or release branches can be postponed until the next cycle, a hotfix cannot.

For mobile development, this distinction is especially important: the App Store and Google Play allow patch versions to be released separately from major releases. The hotfix branch ensures that a patch release is not mixed with unfinished features.

Common Mistakes When Working with Hotfix

Mistakes when working with hotfixes can negate the benefits of emergency fixes. Let's look at five of the most common problems that arise in teams using Git Flow.

• Creating a hotfix from develop — if a hotfix is created from develop, unfinished features may end up in the patch. A hotfix should only be created from main to ensure that only stable code is included in the fix.
• Multiple fixes in one hotfix — each fix should be in its own hotfix branch. Mixing multiple bugs in one branch complicates code review, increases the risk of regression, and makes rollback difficult if needed.
• Skipping the merge into develop — if a hotfix is not merged into develop, the fix will be lost in the next release. The team will find the same bug reappearing and will have to fix it again.
• Incorrect version tag — a hotfix should receive a patch increment (v2.3.0 → v2.3.1), not a minor (v2.4.0) or major (v3.0.0) one. Violating semantic versioning breaks the build system and confuses users.
• Missing CI checks — even an emergency hotfix must pass automated tests. Skipping CI increases the risk of introducing a new error. It is recommended to have a separate pipeline for hotfix branches with accelerated checks.

Each of these mistakes leads to a delay in the patch release or the introduction of new problems in production. Teams should document hotfix rules in CONTRIBUTING.md and automate them through CI/CD checks.