BeginnerLesson 9 of 308 min read

Remotes: Push, Pull and Clone

Share a project through a remote: connect, push, clone as a teammate, fetch, pull, and fix a rejected push calmly.

In this lesson you will

  • Add a remote and push to it
  • Clone a project as a teammate
  • Tell fetch from pull
  • Fix a rejected push

About 32 minutes

One laptop is a single point of failure

So far, Nia’s whole history lives on one laptop. If it is lost, the history goes with it, and Dev cannot see any of it. The solution is a remote: another copy of the repository that lives somewhere else and that people can send work to and fetch work from. The conventional name for the main remote is origin. GitHub is one popular place to keep a remote, and many other services do the same job. Git itself only needs an address.

A safe place to practise

GitHub cannot be reached from the machine that builds these lessons, and you do not need it to learn the commands. A remote is just another repository, so a folder on the same computer can stand in for it. The only difference from the real thing is the address: a folder path here, a web or SSH address for GitHub. Every command is identical. The stand-in is a bare repository, one with no working files, only history, which is how hosting services store projects.

$ mkdir garden
$ cd garden
$ git init
Initialized empty Git repository in /home/nia/garden/.git/
$ echo "Beans: row 1" > plan.txt
$ git add plan.txt
$ git commit -m "Add planting plan"
[main (root-commit) cd4328a] Add planting plan
 1 file changed, 1 insertion(+)
 create mode 100644 plan.txt
$ cd ..
$ git init --bare remote.git
Initialized empty Git repository in /home/nia/remote.git/
$ cd garden
$ git remote add origin ../remote.git
$ git remote -v
origin	../remote.git (fetch)
origin	../remote.git (push)
$ git push -u origin main
To ../remote.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
$ git status -sb
## main...origin/main

Nia created the bare repository, told her project where it lives with git remote add origin, and checked the address with git remote -v. Then git push -u origin main uploaded her history. The -u option remembers that her main branch is paired with origin/main, which is why the final status can say the two match. Next time she can type just git push.

A teammate joins

Now Dev wants the project. He uses git clone with the address, which creates a new folder holding a complete copy of the history, with the remote already set up. He sets his own name for this copy, makes a commit and pushes it. Back in Nia’s folder, git fetch downloads the news without changing her files, and her status says she is one commit behind. Then git pull brings the change in.

$ cd ..
$ git clone remote.git dev-copy
Cloning into 'dev-copy'...
done.
$ cd dev-copy
$ git config user.name "Dev Patel"
$ git config user.email "dev@example.com"
$ echo "Carrots: row 2" >> plan.txt
$ git commit -am "Add carrots"
[main 625fc7a] Add carrots
 1 file changed, 1 insertion(+)
$ git push
To /home/nia/remote.git
   cd4328a..625fc7a  main -> main
$ cd ../garden
$ git fetch
From ../remote
   cd4328a..625fc7a  main       -> origin/main
$ git status -sb
## main...origin/main [behind 1]
$ git pull
Updating cd4328a..625fc7a
Fast-forward
 plan.txt | 1 +
 1 file changed, 1 insertion(+)
$ cat plan.txt
Beans: row 1
Carrots: row 2

Remember the difference. Fetch only downloads, so it is always safe. Pull is fetch followed by a merge, so it changes your files. Many people fetch and look first, then pull when they are ready. The address looks different in the two folders because Git keeps Nia’s as she typed it, and turns Dev’s, which came from a clone, into a full path. It is the same remote.

When the push is rejected

The next session shows the most common message a beginner meets. Nia pushes a commit. Dev, who has not pulled yet, makes his own commit and tries to push. Git refuses, and the message explains why: the remote contains work Dev does not have locally. Git will not let him overwrite a teammate’s work. The fix is to pull, which merges the two lines of work, and then push again.

$ echo "Peas: row 3" >> plan.txt
$ git commit -am "Add peas"
[main 5308614] Add peas
 1 file changed, 1 insertion(+)
$ git push
To ../remote.git
   625fc7a..5308614  main -> main
$ cd ../dev-copy
$ echo "Mon: Dev" > rota.txt
$ git add rota.txt
$ git commit -m "Add the rota"
[main aefa158] Add the rota
 1 file changed, 1 insertion(+)
 create mode 100644 rota.txt
$ git push
To /home/nia/remote.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to '/home/nia/remote.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
$ git pull
From /home/nia/remote
   625fc7a..5308614  main       -> origin/main
Merge made by the 'ort' strategy.
 plan.txt | 1 +
 1 file changed, 1 insertion(+)
$ git push
To /home/nia/remote.git
   5308614..76fe069  main -> main
$ git log --oneline --graph
*   76fe069 Merge branch 'main' of /home/nia/remote
|\  
| * 5308614 Add peas
* | aefa158 Add the rota
|/  
* 625fc7a Add carrots
* cd4328a Add planting plan
$ cd ../garden
$ git pull
From ../remote
   5308614..76fe069  main       -> origin/main
Updating 5308614..76fe069
Fast-forward
 rota.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 rota.txt
$ git log --format="%h %an: %s"
76fe069 Dev Patel: Merge branch 'main' of /home/nia/remote
aefa158 Dev Patel: Add the rota
5308614 Nia Okafor: Add peas
625fc7a Dev Patel: Add carrots
cd4328a Nia Okafor: Add planting plan

Read the error and the hints: they tell you what to do. After the pull, the graph shows the two lines of work joined by a merge commit, and the second push succeeded. The final log shows both authors, with the right name on each commit. A pull needs to know whether to merge or rebase when both sides changed, and recent versions of Git ask you to choose. This lesson’s setup chose merge, which matches lesson 8. Many teams prefer rebasing, and both are valid, so follow your team.

import subprocess
def head(*gitdir):
    return subprocess.run(["git", *gitdir, "rev-parse", "main"], capture_output=True, text=True).stdout.strip()
ids = {
    "garden": head("-C", "/home/nia/garden"),
    "dev-copy": head("-C", "/home/nia/dev-copy"),
    "remote.git": head("--git-dir", "/home/nia/remote.git"),
}
for name, sha in ids.items():
    print(name + ":", sha[:7])
print("all three agree:", len(set(ids.values())) == 1)
garden: 76fe069
dev-copy: 76fe069
remote.git: 76fe069
all three agree: True

All three copies agree, and all name the same latest commit, starting 76fe069. That is what “in sync” means.

Using GitHub for the same job

With GitHub, the steps are the same, and only the address changes. These are patterns, not something this lesson ran, and the website’s screens change over time, so follow its current instructions.

  1. Create an account and a new, empty repository on the website.
  2. Copy the repository’s address. For web access it starts with https://github.com/, followed by your account name and the project name, and for SSH it starts with git@github.com.
  3. In your project, run git remote add origin followed by that address.
  4. Run git push -u origin main.

Proving who you are is the part that surprises people. GitHub stopped accepting account passwords for Git operations on 13 August 2021. You sign in instead with a personal access token over HTTPS, with an SSH key, or through a credential helper, such as the one installed with Git for Windows, that signs you in through your browser. Turning on two step sign-in is strongly encouraged. Check GitHub’s current help pages for the exact steps, because they change.

Common mistake: careless pushes and shared tokens

Pushing to the wrong remote or branch. Check git remote -v and the branch name before you push, and never share an access token in a message or commit it to a repository.

A local stand-in for a hosting site

Everything above ran against a folder on the same computer, with made-up names and files. Hosting sites differ in screens, names and sign-in methods, so treat the GitHub steps as an outline and confirm them on the site.

Make a bare repository next to a practice project, push to it, clone it into a second folder, change something there, and pull it back. You have then practised the whole teamwork loop on one computer.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

What is a remote?

  1. A kind of branch
  2. A file in .git
  3. A text editor
  4. Another copy of the repository kept somewhere else

The bare folder stood in for a hosting site.

What does git clone do?

  1. Deletes the remote
  2. Makes a complete copy of a repository, with the remote set up
  3. Merges two branches
  4. Writes a commit message

Dev got the whole history in a new folder.

How do fetch and pull differ?

  1. They are identical
  2. Pull only uploads
  3. Fetch only downloads; pull downloads and merges
  4. Fetch changes your files

After fetch, the status said behind 1. Pull then moved the files.

Why was Dev’s first push rejected?

  1. The remote had work he did not have locally
  2. His password was wrong
  3. The file was too big
  4. He used the wrong editor

Git will not let you overwrite a teammate’s work; pull first.

How does GitHub check who you are for Git operations?

  1. Your account password
  2. Your email address alone
  3. A token, an SSH key or a credential helper, not an account password
  4. Nothing

GitHub stopped accepting account passwords for Git on 13 August 2021.

Summary

  • A remote is another copy of the repository, usually named origin.
  • push sends commits; clone copies a project; fetch downloads; pull downloads and merges.
  • A rejected push means the remote has work you lack: pull, then push.
  • GitHub needs a token, SSH key or credential helper, not a password.

Next lesson

Lesson 10 is your first project: a tracked repository with a clear history.

Questions

Do I need GitHub to practise remotes?

No. Any folder, drive or server can act as a remote. This lesson used a folder on the same computer, and the commands were exactly the ones you would use with GitHub.

Is it safe to run git fetch at any time?

Yes. Fetch only downloads new commits and never changes your files. It is a good way to see what has happened before you pull.

What is the difference between merging and rebasing on pull?

Merging keeps both lines of work and adds a merge commit. Rebasing replays your commits on top of the new work for a straighter history. Both are valid, and teams choose one.

Progress is saved in this browser.