If you want your local branch to look exactly like the remote one and you don't care about your local commits or edits, this is the command pair you need:
shell
1git fetch origin2git reset --hard origin/mainReplace main with your branch name. git fetch downloads the latest commits without touching your files. git reset --hard moves your branch to the remote commit and overwrites every tracked file in your working directory.
Warning: this deletes uncommitted changes in tracked files and drops local commits from the branch. Committed work can still be recovered with git reflog (see below). Uncommitted edits cannot. If there is any chance you need them, run git stash or create a backup branch first.
The rest of this guide walks through the whole thing on a test repository, so you can see what each command does before you run it on real work. The commands were tested on Git 2.54.0 and on Git 2.43.0 (the version in Ubuntu 24.04), with the same output.
What git pull --force actually does
Many people search for a "force pull" and try git pull --force. It doesn't overwrite anything local.
git pull is git fetch followed by git merge (or git rebase). The --force flag is passed to the fetch step only. It allows fetch to update a local ref when the remote branch was rewritten, which the default remote-tracking setup already allows anyway. It has no effect on the merge step, your local commits or your files.
Here is what happens on a branch that has diverged from the remote:
shell
1$ git pull --force2hint: You have divergent branches and need to specify how to reconcile them.3...4fatal: Need to specify how to reconcile divergent branches.Nothing changed. Your local commit is still there. To really replace local state with the remote, use git fetch plus git reset --hard, as shown in this guide.
Set up a test repository
We'll use one bare repository as the "remote" and two clones that play two developers, user1 and user2. Everything stays on your disk.
Create the remote repository
shell
1mkdir git-force-pull && cd git-force-pull2mkdir repository user1 user23git init --bare --initial-branch=main repository/myproject.gitThe --initial-branch=main flag sets the default branch name. Without it, current Git still names the first branch master (the default switches to main in Git 3.0) unless you set init.defaultBranch in your config. If your real repository uses master, replace main with master in every command below.
Clone as user1 and push the first commit
shell
1cd user12git clone ../repository/myproject.git3cd myproject4echo "Project readme" > ReadMe.txt5echo "image 1" > Image1.txt6git add ReadMe.txt Image1.txt7git commit -m "Initial commit"8git push -u origin mainOutput of the push:
shell
1To /work/git-force-pull/user1/../repository/myproject.git2 * [new branch] main -> main3branch 'main' set up to track 'origin/main'.Clone as user2
shell
1cd ../../user22git clone ../repository/myproject.git3cd myproject4git log --onelineshell
12fd9f90 Initial commitBoth users now have the same ReadMe.txt and Image1.txt. Your commit hashes will be different.
Reproduce the problem: divergent branches
Both users start working on a new file, Image2.txt. user1 finishes first and pushes.
user1 commits and pushes
In user1/myproject:
shell
1echo "USER1" > Image2.txt2git add Image2.txt3git commit -m "Add Image2.txt (user1)"4git pushshell
1To /work/git-force-pull/user1/../repository/myproject.git2 2fd9f90..6c2a284 main -> mainuser2 commits locally
In user2/myproject:
shell
1echo "USER2" > Image2.txt2git add Image2.txt3git commit -m "Add Image2.txt (user2)"git pull stops on divergent branches
Now user2 runs git pull to get user1's work:
shell
1$ git pull2From /work/git-force-pull/user2/../repository/myproject3 2fd9f90..6c2a284 main -> origin/main4hint: You have divergent branches and need to specify how to reconcile them.5hint: You can do so by running one of the following commands sometime before6hint: your next pull:7hint:8hint: git config pull.rebase false # merge9hint: git config pull.rebase true # rebase10hint: git config pull.ff only # fast-forward only11hint:12hint: You can replace "git config" with "git config --global" to set a default13hint: preference for all repositories. You can also pass --rebase, --no-rebase,14hint: or --ff-only on the command line to override the configured default per15hint: invocation.16fatal: Need to specify how to reconcile divergent branches.This is the default behavior of current Git when pull.rebase and pull.ff are not set. Each side has a commit the other doesn't have, so a fast-forward is impossible, and Git refuses to pick merge or rebase for you. The fetch part still worked: origin/main now points to user1's commit.
shell
1$ git status -sb2## main...origin/main [ahead 1, behind 1]3$ git log --oneline --graph --all4* 45bb472 Add Image2.txt (user2)5| * 6c2a284 Add Image2.txt (user1)6|/7* 2fd9f90 Initial commitYou have three options:
git pull --rebasereplays your local commits on top of the remote ones. Use it when you want to keep your work.git pull --no-rebasecreates a merge commit. If both sides changed the same lines, you get a conflict to resolve.- Throw away your local work and match the remote. That's the "force pull", covered in the next section.
What a merge conflict looks like
If user2 picks the merge option, both versions of Image2.txt collide:
shell
1$ git pull --no-rebase2Auto-merging Image2.txt3CONFLICT (add/add): Merge conflict in Image2.txt4Automatic merge failed; fix conflicts and then commit the result.5$ cat Image2.txt6<<<<<<< HEAD7USER28=======9USER110>>>>>>> 6c2a284e922ce798822bc19841dec7a635f74c35In most cases you should resolve the conflict by hand. Here user2 decides that user1's version is the right one and wants to start from where user1 left off. First, cancel the merge:
shell
1git merge --abortOverwrite local changes with git fetch and git reset --hard
Step 1: Create a backup branch
This takes a second and makes the reset fully reversible:
shell
1git branch backup-before-resetThe branch keeps a pointer to user2's local commit, so nothing is lost even after the reset.
Step 2: Fetch the remote branch
shell
1git fetch originStep 3: Reset to the remote branch
shell
1$ git reset --hard origin/main2HEAD is now at 6c2a284 Add Image2.txt (user1)Step 4: Check the result
shell
1$ git log --oneline26c2a284 Add Image2.txt (user1)32fd9f90 Initial commit4$ cat Image2.txt5USER1user2's branch now matches the remote. The local commit is gone from main, but it's still in the backup branch:
shell
1$ git log --oneline backup-before-reset245bb472 Add Image2.txt (user2)32fd9f90 Initial commitWhen you're sure you don't need it, delete the backup with git branch -D backup-before-reset.
Uncommitted changes: stash before you reset
If you have edits that are not committed, git pull refuses to run:
shell
1$ git pull2From /work/git-force-pull/user2/../repository/myproject3 6c2a284..a9d0aea main -> origin/main4Updating 6c2a284..a9d0aea5error: Your local changes to the following files would be overwritten by merge:6 ReadMe.txt7Please commit your changes or stash them before you merge.8Abortinggit reset --hard would delete those edits without asking, and reflog can't bring them back because they were never committed. Put them aside first:
shell
1git stash push -m "before reset"2git fetch origin3git reset --hard origin/mainYour edits are saved in the stash:
shell
1$ git stash list2stash@{0}: On main: before reset3$ git stash show -p stash@{0}4diff --git a/ReadMe.txt b/ReadMe.txt5index 28fc22c..7f33680 1006446--- a/ReadMe.txt7+++ b/ReadMe.txt8@@ -1 +1,2 @@9 Project readme10+my local notesRun git stash pop to apply them on top of the new code, or git stash drop if you don't need them.
Untracked files: git clean
git reset --hard only touches tracked files. Untracked files stay where they are, and they can still block a pull. Here user1 added config.yml to the repository, while user2 has an untracked local file with the same name:
shell
1$ git pull2From /work/git-force-pull/user2/../repository/myproject3 a9d0aea..fbf507a main -> origin/main4Updating a9d0aea..fbf507a5error: The following untracked working tree files would be overwritten by merge:6 config.yml7Please move or remove them before you merge.8Abortinggit clean removes untracked files. Always start with a dry run, which only prints what would be deleted:
shell
1$ git clean -n -d2Would remove .gitignore3Would remove config.yml4Would remove tmp/If the list looks right, run it for real. -f is required to delete, and -d includes untracked directories:
shell
1$ git clean -fd2Removing .gitignore3Removing config.yml4Removing tmp/Now the pull goes through as a fast-forward.
A few things to know about git clean:
- It skips files listed in
.gitignore(in this example, a local.envsurvived). Add-xto delete ignored files too:git clean -fdx. Check withgit clean -n -d -xfirst, because ignored files are often local secrets and build caches. - Deleted files don't go to the trash. There is no undo.
git reset --hard origin/mainsilently overwrites an untracked file if a file with the same path exists in the commit you reset to. Untracked files with other names are left alone.
Recover a lost commit with git reflog
Say user2 ran the reset without a backup branch and now needs the old commit back. Git keeps a log of every position HEAD has been at, and the commits in it stay in the repository even when no branch points to them. By default, reflog entries for commits that are no longer on any branch are kept for 30 days, the rest for 90 days.
shell
1$ git reflog -n 526c2a284 HEAD@{0}: reset: moving to origin/main345bb472 HEAD@{1}: reset: moving to HEAD445bb472 HEAD@{2}: commit: Add Image2.txt (user2)52fd9f90 HEAD@{3}: clone: from /work/git-force-pull/user2/../repository/myproject.gitThe line reset: moving to HEAD comes from the git merge --abort we ran earlier. The commit we lost is 45bb472, the position right before the reset. Put a branch on it:
shell
1git branch recovered HEAD@{1}shell
1$ git log --oneline recovered245bb472 Add Image2.txt (user2)32fd9f90 Initial commitThe commit is back. From here you can cherry-pick it onto main, compare it with the remote version, or push the branch.
You can also use the hash directly: git branch recovered 45bb472. And to undo the reset completely, run git reset --hard HEAD@{1}.
The push side: --force vs --force-with-lease
The opposite problem is overwriting the remote with your local history, for example after git commit --amend or a rebase on a branch you already pushed. A normal push is rejected, so you need to force it. How you force it matters.
--force-with-lease refuses to overwrite work you haven't seen
user1 pushes a new commit, Add feature A. user2 hasn't fetched it. user2 amends their own last commit and tries to push it:
shell
1$ git push --force-with-lease2To /work/git-force-pull/user2/../repository/myproject.git3 ! [rejected] main -> main (stale info)4error: failed to push some refs to '/work/git-force-pull/user2/../repository/myproject.git'--force-with-lease compares the remote branch with your origin/main. They don't match, because someone pushed after your last fetch, so the push is rejected. Nothing is lost.
--force overwrites whatever is there
shell
1$ git push --force2To /work/git-force-pull/user2/../repository/myproject.git3 + 401b119...4fd3bc9 main -> main (forced update)user1's Add feature A commit is no longer on the remote. On user1's next fetch, Git reports the rewrite:
shell
1$ git fetch2From /work/git-force-pull/user1/../repository/myproject3 + 401b119...4fd3bc9 main -> origin/main (forced update)4$ git status -sb5## main...origin/main [ahead 1, behind 1]Here the damage is fixable: user1 still has the commit locally and can run git rebase origin/main and push again. If nobody had the commit locally, it would be gone from the shared repository.
Add --force-if-includes if anything fetches in the background
--force-with-lease has a weak spot. It trusts your origin/main, and many IDEs run git fetch in the background. After such a fetch, the lease sees an up-to-date origin/main and allows the push, even though you never looked at the new commits. --force-if-includes (Git 2.30 and newer) closes the gap: it also checks that the remote commit is part of your local branch history.
In this run user1 pushed Add feature B, user2's Git fetched it, and user2 amended and pushed without integrating it:
shell
1$ git push --force-with-lease --force-if-includes2To /work/git-force-pull/user2/../repository/myproject.git3 ! [rejected] main -> main (remote ref updated since checkout)4error: failed to push some refs to '/work/git-force-pull/user2/../repository/myproject.git'5hint: Updates were rejected because the tip of the remote-tracking branch has6hint: been updated since the last checkout. If you want to integrate the7hint: remote changes, use 'git pull' before pushing again.The same push with --force-with-lease alone went through and replaced user1's commits. If you force-push regularly, set it once:
shell
1git config --global push.useForceIfIncludes trueThen plain git push --force-with-lease includes the check. The simple rule: never use bare --force on a shared branch.
Force sync in a CI/CD pipeline
Build agents that reuse a workspace between runs can end up with modified files, leftover build output or a stale branch. That can make a pipeline build old code without any error. A CI/CD pipeline that reuses a checkout should reset it at the start of every job:
shell
1git fetch origin2git reset --hard origin/main3git clean -fdxOn a test agent with a modified tracked file, an untracked file and an ignored build/ directory, this left a clean checkout of the latest commit:
shell
1$ git status --short --ignored2 M app.txt3?? stray.txt4!! build/5$ git fetch origin && git reset --hard origin/main && git clean -fdx6From /tmp/r7 da66388..9908dd4 main -> origin/main8HEAD is now at 9908dd4 v29Removing build/10Removing stray.txt11$ git status --short --ignored12$Use -x only on machines where nothing in the workspace is worth keeping. On a developer laptop, git clean -fd without -x is the safer default.
Quick reference
- Overwrite local branch with remote:
git fetch originthengit reset --hard origin/<branch>. - Keep a way back:
git branch backup-before-resetbefore the reset. - Keep uncommitted edits:
git stash push -m "before reset", latergit stash pop. - See what untracked files would be deleted:
git clean -n -d. - Delete untracked files and directories:
git clean -fd(add-xfor ignored files). - Find a commit you lost:
git reflog, thengit branch recovered <hash>. - Keep your local commits instead:
git pull --rebase. - Force-push safely:
git push --force-with-lease --force-if-includes.
Wrapping up
There is no real "git force pull". What people mean by it is git fetch plus git reset --hard, and it does exactly what it says: your branch becomes a copy of the remote. Take a backup branch or a stash first, dry-run git clean, and remember that git reflog can bring back commits but not uncommitted edits.
Used as a habit, a hard reset will eventually eat someone's work. Used deliberately, it saves time on build agents, broken local branches and test repositories.
Need help with Git workflows or CI/CD pipelines? Our DevOps automation and CI/CD team can set them up and keep them running for you.
