Lesson 4 of 8 in Git and collaboration

Remotes, fetch, push and pull requests

Core13 minWritten for Git 2.28 or newer

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

Fetch downloads, merge updates your branch
Fetch downloads, merge updates your branchFetch 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.1 git fetch2 mergeoriginthe shared copyorigin/mainyour note of origin's mainmainyour own branch
  • 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.

  1. origin to origin/main: 1 git fetch
  2. origin/main to main: 2 merge
One change travelling through a pull request
One change travelling through a pull requestYou 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.1 git push2 open a PR3 review, checks4 approve,merge5 git pullYour branchon your laptopBranch on originPull requestreview plus checksReviewersmain on originYour mainupdated by pull
  • 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.

  1. Your branch to Branch on origin: 1 git push
  2. Branch on origin to Pull request: 2 open a PR
  3. Pull request to Reviewers: 3 review, checks
  4. Reviewers to main on origin: 4 approve, merge
  5. 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.

  1. 1
    Create 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. -u links your local main to origin/main so later git push and git pull need no arguments.

  2. 2
    A 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
  3. 3
    Alice fetches and looks before merging
    cd ../alice
    git fetch
    git status
    git log --oneline main..origin/main

    git status says your branch is behind origin/main by 1 commit and can be fast-forwarded. The log lists the commit you do not have yet. Your app.txt still says v1.

  4. 4
    Bring 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 merged origin/main into main as a fast-forward.

  5. 5
    Cause 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.

  6. 6
    Fix 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-rebase chooses merging, which avoids the divergent branches question that recent git versions ask when you run a bare git pull here.

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, then git log --oneline --graph --all to see both sides. Run git pull --no-rebase, or git pull --rebase if 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 for git push --force to 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 -v to see which URL form you use. For SSH, run ssh -T git@github.com to 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 push does 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 pull blindly on a branch with uncommitted work or unclear history. Run git fetch first 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.

Lesson 34 of 92 in the DevOps path

Search

Search cheat sheets and projects