Lesson 4 of 8 in Git and collaboration
Remotes, fetch, push and pull requests
A remote is another copy of your repository, usually on a server such as GitHub, that the team shares. You exchange commits with it using fetch, pull and push, and a pull request is a request on the hosting site to merge one branch into another after review.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: Branches and merging
The problem this solves
Your repository lives on your machine. A team needs one agreed copy where everyone sends work and from which pipelines build. Without that, you would email folders around.
Git is distributed, which means every clone holds the full history. The shared copy is not special to git. It is the copy the team agrees to treat as the source of truth. Learners trip over this because git keeps a local record of the remote that can be out of date.
Teams also want a gate before code reaches the shared main line. A pull request is that gate: a place for review, discussion and automated checks before the merge happens.
How it works
- Data
- Runs code
Fetch copies new commits from origin into your local origin/main record without touching your branch, and a merge or pull then moves your own main forward.
- origin to origin/main: 1 git fetch
- origin/main to main: 2 merge
- Runs code
- Data
- Control
- People and clients
You push a branch to origin, open a pull request, reviewers approve and the branch is merged into main on origin, then you pull the result back to your laptop.
- Your branch to Branch on origin: 1 git push
- Branch on origin to Pull request: 2 open a PR
- Pull request to Reviewers: 3 review, checks
- Reviewers to main on origin: 4 approve, merge
- main on origin to Your main: 5 git pull
origin is the default name git gives the remote you cloned from. origin/main is something different: a local note of where main was on origin the last time you talked to it. It only changes when you fetch, pull or push.
git fetch downloads new commits and moves origin/main. It never changes your branches or your files, so it is always safe. git pull is a fetch followed by a merge into your current branch. git push uploads your commits and moves the branch on the remote. Git rejects a push if the remote has commits you do not, so nobody's work gets erased by accident.
A pull request is a feature of the hosting site, not of git. GitLab calls it a merge request. The second diagram shows the usual loop: push a branch, open the request, let reviewers and automated checks look at it, merge on the server, then pull the result. The commands underneath are the same ones you already know.
Try it yourself
You do not need GitHub for this. A bare repository, which is a repository with no working tree, plays the part of the shared server, and two clones play two teammates. Run it all in a throwaway folder.
- 1Create the shared copy and the first clone
mkdir git-lab-remote && cd git-lab-remote git init --bare -b main origin.git git clone origin.git alice cd alice git config user.name "Alice" git config user.email "alice@example.com" echo "v1" > app.txt git add app.txt && git commit -m "Add app.txt" git push -u origin main
Cloning an empty repository prints a warning about that. It is expected.
-ulinks your localmaintoorigin/mainso latergit pushandgit pullneed no arguments. - 2A teammate pushes a change
cd .. git clone origin.git bob cd bob git config user.name "Bob" git config user.email "bob@example.com" echo "v2" > app.txt git commit -am "Update app.txt to v2" git push
- 3Alice fetches and looks before merging
cd ../alice git fetch git status git log --oneline main..origin/main
git statussays your branch is behindorigin/mainby 1 commit and can be fast-forwarded. The log lists the commit you do not have yet. Yourapp.txtstill says v1. - 4Bring it in
git pull cat app.txt
You should see
v2
The last line is the output of
cat. Pull fetched again, found nothing new, and mergedorigin/mainintomainas a fast-forward. - 5Cause a rejected push on purpose
cd ../bob echo "bob" > bob.txt && git add bob.txt && git commit -m "Add bob.txt" && git push cd ../alice echo "alice" > alice.txt && git add alice.txt && git commit -m "Add alice.txt" git push
Alice's push fails with a message containing rejected and fetch first. Origin has Bob's commit and Alice does not. Nothing was lost.
- 6Fix it the normal way
git pull --no-rebase --no-edit git push git log --oneline --graph
The two lines of work were joined by a merge commit and the push now goes through.
--no-rebasechooses merging, which avoids the divergent branches question that recent git versions ask when you run a baregit pullhere.
What breaks, and where to look
! [rejected] main -> main (fetch first) error: failed to push some refs
- WHY IT HAPPENS
- The remote has commits you do not have locally. Git refuses to overwrite them.
- CHECK FIRST
- Run
git fetch, thengit log --oneline --graph --allto see both sides. Rungit pull --no-rebase, orgit pull --rebaseif your team prefers it, then push again. If git says it needs to know how to reconcile divergent branches, that choice is what it wants. Do not reach forgit push --forceto make the error go away.
git@github.com: Permission denied (publickey). fatal: Could not read from remote repository.
- WHY IT HAPPENS
- You cloned over SSH, but the remote does not recognise your key, or no key is loaded. An HTTPS remote has its own failure: the site rejects a password and wants an access token or a credential helper.
- CHECK FIRST
- Run
git remote -vto see which URL form you use. For SSH, runssh -T git@github.comto test the key. Confirm the public key is added to your account.
fatal: The current branch feature has no upstream branch.
- WHY IT HAPPENS
- The new local branch is not linked to a branch on the remote yet, so a bare
git pushdoes not know where to go. - CHECK FIRST
- Run the command git prints, which is
git push --set-upstream origin feature. Short form:git push -u origin feature.
When not to use this
- A pull request is a convention of hosting platforms, not a git feature. Some teams review by patch email or review tools instead. The git commands underneath stay the same.
- Do not use
git pullblindly on a branch with uncommitted work or unclear history. Rungit fetchfirst and read what arrived.
Check yourself
What is origin/main?
A local note of where main was on origin the last time you fetched, pulled or pushed. It can be out of date.
What is the difference between fetch and pull?
Fetch only downloads and updates your note of the remote. Pull is a fetch followed by a merge into your current branch.
Why does git reject some pushes?
The remote has commits you do not have. Accepting your push would drop them from the branch, so you must fetch and combine first.
Keep going
Lesson 34 of 92 in the DevOps path