Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 78 ยท Remotes and Collaboration

Remotes: clone, remote, fetch

Learn what a Git remote is: clone a repository, create bare repos, manage origin with git remote, understand remote-tracking branches and the difference between fetch and pull.

Until now, everything happened in one repository on one machine. Git is a distributed system: every clone is a complete repository with the full history. To collaborate you connect repositories to each other. A remote is simply a name (like origin) bound to a URL (or a path) of another repository that you can fetch commits from and push commits to.

In this lesson you will clone a repository, see what a bare repository is, add and manage remotes, and learn the most important idea of the chapter: remote-tracking branches, the local, read-only bookmarks that remember where the remote's branches were the last time you looked. We also settle the difference between fetch and pull.

Our runner has no network, so every example uses local paths as remotes (../server.git). Git treats a path exactly like a URL such as https://host/repo.git or git@host:repo.git; only the transport differs. Everything you learn here transfers one to one to GitHub, GitLab or your company server.

Bare repositories: the shared hub

A normal repository has a working tree (your files) and a .git folder. A bare repository has only what is inside .git: no checked-out files. It is what servers use as the central meeting point, because nobody edits files there, so pushes never collide with a working copy. By convention bare repositories end in .git.

Bash Create a bare repository and clone it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git clone printed a warning, "You appear to have cloned an empty repository." That is expected: there was nothing to copy yet. Notice that server.git contains HEAD, objects, refs and so on directly, and no readme.txt. After the first push, the server has the history but still no files.

git clone

git clone <url> [folder] does five things in one command:

  1. creates the folder and runs git init in it,
  2. adds a remote called origin that points to the source,
  3. downloads every commit, tag and branch,
  4. creates remote-tracking branches (origin/main, ...) for the remote's branches,
  5. creates and checks out a local branch (the remote's default, e.g. main) that tracks origin/main.
Bash What git clone sets up

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

You only have one local branch (main), but git branch -a also lists remotes/origin/main, remotes/origin/feature and remotes/origin/HEAD. The local feature branch does not exist yet; you can create it with git switch feature, which sees the matching remote branch and creates a tracking branch for you. The two branch.main.* settings (remote = origin and merge = refs/heads/main) are what "tracking" means: the default place for git pull and git push.

Useful clone options:

  • git clone --branch v1.2 <url> checks out a branch or tag.
  • git clone --depth 1 <url> makes a shallow clone with only the latest commit (see Large Repositories).
  • git clone --bare <url> makes a bare copy and --mirror also copies all refs.
  • git clone -o upstream <url> names the remote upstream instead of origin.

Managing remotes

A remote is only a small entry in .git/config. The git remote command edits it:

Command Effect
git remote / git remote -v list remote names / with their URLs
git remote add <name> <url> add a remote
git remote rename <old> <new> rename it (and its tracking branches)
git remote set-url <name> <newurl> change the URL (after a repository moved)
git remote remove <name> delete the remote and its tracking branches
git remote show <name> details: branches, tracking, stale branches
git ls-remote <name> list the refs on the remote without fetching
Bash Add, inspect, rename and remove remotes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git remote add backup ../backup.git succeeds even though that path does not exist yet: adding a remote only writes configuration and never contacts the server. The first command that actually talks to it (fetch or push) would fail. git ls-remote shows the refs the server has: HEAD and refs/heads/main. After git remote rename origin hub, the tracking branch became hub/main, and the -vv listing shows [hub/main] as the upstream of main.

origin is not a special word. It is only the default name git clone gives the remote you cloned from. You can have as many remotes as you like: a fork (origin), the original project (upstream), a deploy server (production), a colleague's machine.

Remote-tracking branches

When you run git fetch origin, Git asks the remote which branches it has and downloads the new commits. It then updates the remote-tracking branches under refs/remotes/origin/. These are your local, read-only snapshot of where the remote's branches were at your last contact. You cannot commit onto origin/main directly: it only moves when you fetch, pull or push.

TEXT
        remote "origin" (the server)            your repository

   main:  A---B---C---D                   main:         A---B---C
                                          origin/main:  A---B---C     <- as of your last fetch

        after "git fetch origin":
                                          main:         A---B---C
                                          origin/main:  A---B---C---D   <- moved

Because your local main and origin/main are two separate pointers, you can see exactly how they differ, even offline:

  • git log main..origin/main shows commits on the server that you do not have in main yet.
  • git log origin/main..main shows your commits that are not on the server.
  • git status and git branch -vv print "ahead 1, behind 2" based on the last fetch.
Bash Fetch, then compare main with origin/main

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Before the fetch Git reported only ahead 1, because my copy of origin/main was out of date. git fetch updated origin/main and revealed that we have diverged: ahead 1, behind 1. And most importantly, main and the working directory were not touched by the fetch. That safety property is why many people prefer to fetch first and look before they integrate.

fetch versus pull

git fetch git pull
Downloads new commits yes yes
Updates origin/* yes yes
Changes your local branch and files no yes: merges (or rebases) into the current branch
Can cause conflicts no yes
Safe to run any time yes only with a clean idea of what will happen

git pull is exactly git fetch followed by git merge origin/main (or git rebase, if you configure pull.rebase true, as in Rebasing). Pull is convenient when you know your branch is behind and has no local commits. When you are unsure, fetch, inspect with git log and git diff main origin/main, and then merge or rebase deliberately. We cover pushing and pulling in detail in push, pull and Tracking Branches.

Bash pull is fetch plus merge

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

After git fetch, the working directory still only had a.txt. git merge --ff-only origin/main fast-forwarded and brought b.txt in; that merge step is the other half of what pull would have done.

Cleaning up: prune and stale branches

When someone deletes a branch on the server, your origin/<branch> bookmark stays behind. git fetch --prune (or git remote prune origin) removes bookmarks whose branch no longer exists on the remote. Set git config --global fetch.prune true to do it automatically. Your local branches are never removed this way.

Bash Prune a remote-tracking branch that was deleted upstream

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The plain git fetch left origin/topic in place (it is a stale bookmark), and git fetch --prune reported - [deleted] (none) -> origin/topic and removed it.

Inside the .git folder

The clone's .git/config shows how it all fits together:

INI
[remote "origin"]
	url = ../server.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main

The fetch = +refs/heads/*:refs/remotes/origin/* line is a refspec: copy every remote branch refs/heads/X to the local bookmark refs/remotes/origin/X. The leading + allows the bookmark to move non-fast-forward. Refspecs are the mechanism behind fetch and push; see Transfer Protocols.

Common situations

  • "I cloned, but there is only one branch." Other branches exist as origin/*; git switch <name> creates a local tracking branch.
  • "fatal: 'origin' does not appear to be a git repository." The URL or path is wrong or unreachable: git remote -v and check it.
  • "remote origin already exists." Use git remote set-url origin <url> instead of add.
  • Moving a project to a new host: git remote set-url origin <new-url> then git push -u origin --all and git push origin --tags.
  • Credentials and access (HTTPS tokens, SSH keys) are covered in Signing, Credentials and Security.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a bare repository?

    A bare repository has no checked-out files, so pushing into it cannot disturb anyone's working copy. Servers use them.
  2. 2. Which of these does git clone NOT do?

    Clone creates one local branch (the default branch) that tracks origin. Other remote branches exist only as origin/* bookmarks until you switch to them.
  3. 3. What does git fetch do to your current branch and working files?

    Fetch downloads objects and moves origin/* only. Your branches and files change when you merge, rebase or pull.
  4. 4. git pull is equivalent to:

    Pull = fetch + integrate. With pull.rebase=true the integration step is a rebase.
  5. 5. A branch was deleted on the server, but origin/old-topic still shows in git branch -r. How do you remove the stale bookmark?

    git fetch --prune (or git remote prune origin) deletes remote-tracking branches whose branches no longer exist on the remote.

Summary

  • A remote is a named URL (or path) of another repository; origin is just the default name given by git clone.
  • A bare repository has no working tree and acts as the shared hub that people push to.
  • git clone copies everything, adds origin, creates remote-tracking branches and checks out one local branch that tracks origin.
  • git remote add/rename/set-url/remove/show and git ls-remote manage and inspect remotes; adding a remote never contacts it.
  • Remote-tracking branches (origin/main) are read-only bookmarks of the remote as of your last fetch, which fetch, pull and push update.
  • fetch only downloads; pull is fetch plus merge (or rebase); fetch --prune cleans stale bookmarks.

Next: push, pull and Tracking Branches