How to Use Git Force Pull Properly

Published Updated

9 min read

Git has no command that pulls and throws away your local work in one step, and git pull --force does not do it. This guide shows the safe way to make a local branch match the remote: back up, fetch, reset, clean untracked files, and get a lost commit back with reflog. It also covers why git pull now stops on divergent branches and how --force-with-lease protects a push. Every command was run on a real repository.


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 origin
2git reset --hard origin/main

Replace 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 --force
2hint: 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-pull
2mkdir repository user1 user2
3git init --bare --initial-branch=main repository/myproject.git

The --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 user1
2git clone ../repository/myproject.git
3cd myproject
4echo "Project readme" > ReadMe.txt
5echo "image 1" > Image1.txt
6git add ReadMe.txt Image1.txt
7git commit -m "Initial commit"
8git push -u origin main

Output of the push:

shell

1To /work/git-force-pull/user1/../repository/myproject.git
2 * [new branch] main -> main
3branch 'main' set up to track 'origin/main'.

Clone as user2

shell

1cd ../../user2
2git clone ../repository/myproject.git
3cd myproject
4git log --oneline

shell

12fd9f90 Initial commit

Both 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.txt
2git add Image2.txt
3git commit -m "Add Image2.txt (user1)"
4git push

shell

1To /work/git-force-pull/user1/../repository/myproject.git
2 2fd9f90..6c2a284 main -> main

user2 commits locally

In user2/myproject:

shell

1echo "USER2" > Image2.txt
2git add Image2.txt
3git 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 pull
2From /work/git-force-pull/user2/../repository/myproject
3 2fd9f90..6c2a284 main -> origin/main
4hint: 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 before
6hint: your next pull:
7hint:
8hint: git config pull.rebase false # merge
9hint: git config pull.rebase true # rebase
10hint: git config pull.ff only # fast-forward only
11hint:
12hint: You can replace "git config" with "git config --global" to set a default
13hint: preference for all repositories. You can also pass --rebase, --no-rebase,
14hint: or --ff-only on the command line to override the configured default per
15hint: 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 -sb
2## main...origin/main [ahead 1, behind 1]
3$ git log --oneline --graph --all
4* 45bb472 Add Image2.txt (user2)
5| * 6c2a284 Add Image2.txt (user1)
6|/
7* 2fd9f90 Initial commit

You have three options:

  • git pull --rebase replays your local commits on top of the remote ones. Use it when you want to keep your work.
  • git pull --no-rebase creates 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-rebase
2Auto-merging Image2.txt
3CONFLICT (add/add): Merge conflict in Image2.txt
4Automatic merge failed; fix conflicts and then commit the result.
5$ cat Image2.txt
6<<<<<<< HEAD
7USER2
8=======
9USER1
10>>>>>>> 6c2a284e922ce798822bc19841dec7a635f74c35

In 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 --abort

Overwrite 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-reset

The 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 origin

Step 3: Reset to the remote branch

shell

1$ git reset --hard origin/main
2HEAD is now at 6c2a284 Add Image2.txt (user1)

Step 4: Check the result

shell

1$ git log --oneline
26c2a284 Add Image2.txt (user1)
32fd9f90 Initial commit
4$ cat Image2.txt
5USER1

user2'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-reset
245bb472 Add Image2.txt (user2)
32fd9f90 Initial commit

When 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 pull
2From /work/git-force-pull/user2/../repository/myproject
3 6c2a284..a9d0aea main -> origin/main
4Updating 6c2a284..a9d0aea
5error: Your local changes to the following files would be overwritten by merge:
6 ReadMe.txt
7Please commit your changes or stash them before you merge.
8Aborting

git 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 origin
3git reset --hard origin/main

Your edits are saved in the stash:

shell

1$ git stash list
2stash@{0}: On main: before reset
3$ git stash show -p stash@{0}
4diff --git a/ReadMe.txt b/ReadMe.txt
5index 28fc22c..7f33680 100644
6--- a/ReadMe.txt
7+++ b/ReadMe.txt
8@@ -1 +1,2 @@
9 Project readme
10+my local notes

Run 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 pull
2From /work/git-force-pull/user2/../repository/myproject
3 a9d0aea..fbf507a main -> origin/main
4Updating a9d0aea..fbf507a
5error: The following untracked working tree files would be overwritten by merge:
6 config.yml
7Please move or remove them before you merge.
8Aborting

git clean removes untracked files. Always start with a dry run, which only prints what would be deleted:

shell

1$ git clean -n -d
2Would remove .gitignore
3Would remove config.yml
4Would 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 -fd
2Removing .gitignore
3Removing config.yml
4Removing 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 .env survived). Add -x to delete ignored files too: git clean -fdx. Check with git clean -n -d -x first, 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/main silently 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 5
26c2a284 HEAD@{0}: reset: moving to origin/main
345bb472 HEAD@{1}: reset: moving to HEAD
445bb472 HEAD@{2}: commit: Add Image2.txt (user2)
52fd9f90 HEAD@{3}: clone: from /work/git-force-pull/user2/../repository/myproject.git

The 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 recovered
245bb472 Add Image2.txt (user2)
32fd9f90 Initial commit

The 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-lease
2To /work/git-force-pull/user2/../repository/myproject.git
3 ! [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 --force
2To /work/git-force-pull/user2/../repository/myproject.git
3 + 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 fetch
2From /work/git-force-pull/user1/../repository/myproject
3 + 401b119...4fd3bc9 main -> origin/main (forced update)
4$ git status -sb
5## 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-includes
2To /work/git-force-pull/user2/../repository/myproject.git
3 ! [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 has
6hint: been updated since the last checkout. If you want to integrate the
7hint: 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 true

Then 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 origin
2git reset --hard origin/main
3git clean -fdx

On 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 --ignored
2 M app.txt
3?? stray.txt
4!! build/
5$ git fetch origin && git reset --hard origin/main && git clean -fdx
6From /tmp/r
7 da66388..9908dd4 main -> origin/main
8HEAD is now at 9908dd4 v2
9Removing build/
10Removing stray.txt
11$ git status --short --ignored
12$

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 origin then git reset --hard origin/<branch>.
  • Keep a way back: git branch backup-before-reset before the reset.
  • Keep uncommitted edits: git stash push -m "before reset", later git stash pop.
  • See what untracked files would be deleted: git clean -n -d.
  • Delete untracked files and directories: git clean -fd (add -x for ignored files).
  • Find a commit you lost: git reflog, then git 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.

Alex Kondratiev

Alex Kondratiev

Founder and CEO of ITsyndicate. DevOps engineer with 15+ years in cloud infrastructure, Infrastructure as Code, Kubernetes and automation, focused on secure, scalable and resilient systems.

More about Alex

Stay online.
Stay in command.