shellstreak

git push and git pull explained

Updated · Every command on this page ran in our practice shell

Short answer

git pull downloads new commits from the remote and brings them into your branch; git push uploads your commits. Push a new branch the first time with git push -u origin branch. If a push is rejected because someone pushed first, run git pull --no-rebase (plain git pull refuses when both sides have new commits), then git push again. Never use --force on shared branches.

Your repository and the team's server each have their own copy of every branch. git fetch and git pull bring the server's new commits to you; git push sends yours to the server. Most remote trouble comes from those copies drifting apart. In the practice shell below, the "server" is a folder inside your browser tab, so you can push and pull without a network.

Clone a repository

git clone URL copies a repository into a new folder and records the source as a remote called origin. git remote -v shows the URL it fetches from and pushes to.

example
learner@shellstreak:~/shop$ git clone https://git.example.test/pebble/shop.git && cd shop && git remote -v
origin	https://git.example.test/pebble/shop.git (fetch)
origin	https://git.example.test/pebble/shop.git (push)
note: simulated remote: this "server" is a folder inside your practice shell.
Cloning into 'shop'...
done.

fetch: download without touching your work

git fetch downloads new commits and updates origin/main, your record of where the server's main is. Your own main and your files don't change. git status then tells you how far behind you are, and git branch -r lists the server's branches as your copy last saw them.

example
learner@shellstreak:~/shop$ git fetch && git status
On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean
From https://git.example.test/pebble/shop.git
   a2b3648..9cfd3be  main       -> origin/main

pull: fetch and merge

git pull is git fetch followed by integrating the upstream branch into yours. When you have no new commits of your own it's a fast-forward. git pull --ff-only refuses to do anything else, which avoids surprise merge commits.

example
learner@shellstreak:~/shop$ git pull --ff-only && git log --oneline -n 2
Updating a2b3648..9cfd3be
Fast-forward
 notes.txt | 1 +
 1 file changed, 1 insertion(+)
9cfd3be (HEAD -> main, origin/main, origin/HEAD) Add gift wrap idea
a2b3648 Add price calculator

Push a new branch with -u

A brand-new branch has no upstream yet, so plain git push fails with has no upstream branch. git push -u origin delivery pushes it and links your branch to origin/delivery; after that, plain git push and git pull know where to go.

example
learner@shellstreak:~/shop$ git push -u origin delivery
branch 'delivery' set up to track 'origin/delivery'.
To https://git.example.test/pebble/shop.git
 * [new branch]      delivery -> delivery

Why a push gets rejected

If someone pushed to the branch after your last pull, the server has a commit you don't. Accepting your push would throw theirs away, so it's rejected with (fetch first) or (non-fast-forward).

example
learner@shellstreak:~/shop$ git push
To https://git.example.test/pebble/shop.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://git.example.test/pebble/shop.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. Integrate the remote changes (e.g. 'git pull ...')
hint: before pushing again.

Fix it: pull --no-rebase, then push

When both sides have new commits, plain git pull (git 2.27 and later) stops with fatal: Need to specify how to reconcile divergent branches. Tell it how: git pull --no-rebase merges their commit with yours (resolve any conflicts), and git config pull.rebase false makes that the default for the repository. Real git can also replay your commits on top of theirs with git pull --rebase for a straight-line history; the practice shell doesn't support rebase. Then push again.

example
learner@shellstreak:~/shop$ git pull --no-rebase && git push
Merge made by the 'ort' strategy.
 notes.txt | 1 +
 1 file changed, 1 insertion(+)
From https://git.example.test/pebble/shop.git
   a2b3648..9cfd3be  main       -> origin/main
To https://git.example.test/pebble/shop.git
   9cfd3be..5bbe4f0  main -> main

--force-with-lease vs --force

After rewriting commits you already pushed (say, git commit --amend on your own branch), a normal push is rejected. git push --force overwrites the server's branch no matter what's there. git push --force-with-lease only overwrites it if it still matches your origin/... branch, but any git fetch updates that, and IDEs and agents fetch in the background, so a teammate's commit can slip through unseen. Add --force-if-includes, or pin the exact commit you reviewed: --force-with-lease=menu-fix:<sha>. And never force-push a shared branch like main.

example
learner@shellstreak:~/shop$ seen=$(git rev-parse origin/menu-fix) && git push --force-with-lease=menu-fix:$seen
To https://git.example.test/pebble/shop.git
 + a1e38c8...ae67d52 menu-fix -> menu-fix (forced update)

Check yourself

One real exercise from the “Working with remotes (simulated)” unit. No account needed.

Your git push was rejected with (fetch first): Rosa pushed while you were committing. Bring in her commit, then push your work. Don't force anything.

What's checked: the repository's commits on the remote, commits ahead of the remote, commits behind the remote.

Common mistakes

  • Answering a rejected push with --force. That deletes your teammate's commits from the server; pull first.

  • Thinking git fetch updated your branch. It only updates origin/main; merge or pull to bring the commits into main.

  • Running git reset --hard origin/main to "sync" while you have unpushed commits. They disappear from your branch.

  • Forgetting -u on a new branch's first push, then wondering why plain git push and git pull complain.

Questions

What's the difference between git fetch and git pull?+

`git fetch` only downloads: it updates your `origin/...` branches and leaves your work alone. `git pull` downloads and then merges the upstream branch into the branch you're on.

What does git push -u do?+

It pushes the branch and sets its **upstream**, the remote branch it tracks. Afterwards `git push`, `git pull` and `git status` use that branch automatically.

When is git push --force OK?+

On a branch only you use, after rewriting its history on purpose, and preferably as `--force-with-lease --force-if-includes` or with a pinned lease. On shared branches like `main`, don't, and protect them on the server so nobody can.

Why does git pull say "Need to specify how to reconcile divergent branches"?+

You and the remote both have new commits, and since git 2.27 `git pull` won't pick merge or rebase for you. Use `git pull --no-rebase` (merge) or `git pull --rebase`, or set a default once with `git config pull.rebase false`.

Reading is step one. Now make it stick.

Practise this in a five-minute lesson with instant feedback. No account needed.

Practise it now