Overwriting a remote branch with your local changes is a common need when you want to force the central repository to match your local work exactly. This process gives you full control but must be handled carefully to avoid losing work from teammates.
Below is a quick reference that explains common commands, risks, and best practices in a scannable format so you can choose the safest approach for each situation.
| Method | Command | When to Use | Risk Level |
|---|---|---|---|
| Force push new branch | git push origin local-branch:remote-branch --force | Creating a new remote branch from local work | Medium |
| Overwrite existing branch | git push origin local-branch:remote-branch --force-with-lease | Updating a shared branch only if no one else pushed | Low to Medium |
| Reset remote to local state | git push origin --force-with-lease local-branch:remote-branch | Discarding remote changes and matching local exactly | High |
| Replace remote history entirely | git push origin +local-branch:remote-branch | Full history replacement, similar to --force | High |
How Remote Branch Overwrite Works in Practice
When you run a push command, Git compares your local branch pointer to the remote branch pointer and decides whether to accept, reject, or update the remote reference. By default, Git prevents you from losing work on the remote unless you explicitly ask it to overwrite.
Understanding this behavior helps you choose between safe options like --force-with-lease and more aggressive ones like --force. The right choice depends on whether the remote branch is shared, how much history rewriting you need, and how much collaboration is involved.
Preparing Your Local Branch Before Overwriting
Before you push any changes that rewrite history, ensure your local branch is clean and ready. Stash or commit all modifications, and verify the branch contains exactly what you intend to push.
Review the latest commits with git log and, if needed, run tests locally to avoid pushing broken code. This discipline reduces the chance that a forced push will break builds or remove important work from the remote.
Using Force-With-Lease for Safer Overwrites
The --force-with-lease option checks the remote ref before overwriting and cancels the push if someone else has updated it. This behavior is safer than plain --force, because it protects you from accidentally erasing a teammate's commits.
Use this option whenever you are updating a branch that other people may have pushed to, even if you are confident that no one else is working on it at this moment.
When Force Pushing to a New Remote Branch Makes Sense
If the remote branch does not exist yet, you can safely push your local branch to create it without worrying about overwriting shared history. In this scenario, you are simply publishing your work for the first time.
Still, double-check the branch name and the commit you are pushing to ensure that you are not publishing experimental changes or sensitive information that should remain local.
Recovering From an Unwanted Remote Overwrite
Even with careful planning, mistakes happen, and you may need to restore a previous state of a remote branch. Git keeps every reachable commit in reflog on the remote server for a period, which allows repository administrators to recover lost work.
Collaborators who have not yet pulled the overwritten commits can also rescue their changes by checking out their local copies and pushing them to a new branch for safekeeping.
Best Practices for Managing Remote Branches
- Prefer --force-with-lease over --force to avoid unintentionally removing others' work.
- Coordinate with your team before rewriting shared branch history.
- Verify your current branch and commit range before executing any push command.
- Use pull requests and code reviews instead of direct force pushes for shared branches when possible.
- Keep important work in feature branches and merge to main via merge commits or squash merges.
FAQ
Reader questions
Will force pushing overwrite my colleague's commits?
Yes, a plain git push --force will replace the remote branch entirely, potentially removing commits your colleague has added. Use --force-with-lease or coordinate with your team to avoid this.
Can I restore a branch after it has been overwritten?
Yes, if the repository retains reflog entries or the overwritten commits were fetched by teammates, an admin or you can recover them using a specific commit SHA or a reflog reference.
Is it safe to force push to main or master branch?
Generally, no. For shared branches like main or master, prefer merging or rebasing and avoid rewriting history. If you must force push, use --force-with-lease and notify the team first.
What should I do if my push is rejected due to non-fast-forward?
First, fetch the latest changes, rebase or merge the remote work into your branch, and then push again. Reserve forced pushes for cases where discarding remote changes is the intended outcome.