Git Remote Names and Remote-Tracking References

Intermediate

A remote name is a local identifier, not a second repository

A remote repository lives somewhere else, but your local repository needs a local name by which Git can refer to it. A name such as origin or upstream identifies that configured remote locally. The name does not itself contain the remote repository's commits; it is part of local configuration and the namespace used for remote-tracking references.

git remote
git remote -v
git config --get-regexp '^remote\.'

The repository has a configured remote named origin.?origin identifies that remote in local commands and configuration.

Remote-tracking references record what your repository last learned

A remote-tracking branch is a local reference used to follow a branch from another repository. With the usual fetch refspec for origin, a remote branch such as refs/heads/main maps to refs/remotes/origin/main. The remote-tracking reference is local state: it records the remote branch tip known from fetching. It is not the same ref as your local refs/heads/main branch.

git fetch origin
git rev-parse refs/remotes/origin/main
git rev-parse refs/heads/main
git for-each-ref refs/remotes/origin

origin has a remote branch named main.?The corresponding local remote-tracking ref is refs/remotes/origin/main.

Fetch updates the remote-tracking state

Fetching obtains refs and the objects needed for their histories. Under the usual configured fetch refspec, fetching origin updates refs/remotes/origin/* to reflect the remote branches just observed. This is a reference update in the local repository; it does not switch your current branch or rewrite its working tree merely because the remote moved.

git fetch origin
git rev-parse HEAD
git rev-parse refs/remotes/origin/main
git status --short --branch

The remote main branch has a newer commit than the local knowledge of origin/main.?origin/main advances locally; HEAD and the current branch remain where they were.

FETCH_HEAD is fetch-result information, not a branch replacement

A fetch also records the names and object IDs of fetched refs in FETCH_HEAD. This is separate fetch-result information. Do not confuse FETCH_HEAD with refs/remotes/origin/main: the latter is a persistent remote-tracking ref maintained by the configured fetch mapping, while FETCH_HEAD records what the particular fetch reported.

git fetch origin main
cat .git/FETCH_HEAD
git rev-parse refs/remotes/origin/main

A fetch has completed.?FETCH_HEAD contains fetch-result information, while origin/main remains a named remote-tracking ref.

A fetched remote branch does not automatically become a local branch

When a remote repository gains a new branch, fetching can create the corresponding remote-tracking ref without creating a local refs/heads/ branch. Fetch observes and records remote state locally; it does not decide that the remote branch should become your current local branch.

git fetch origin
git show-ref --verify refs/remotes/origin/topic
git show-ref --verify refs/heads/topic

origin has a new topic branch and the local repository has no topic branch.?fetch can create refs/remotes/origin/topic without creating refs/heads/topic.

Remote names and tracking refs form a reference boundary

The essential model is: a remote name identifies a configured repository; a remote branch is a ref in that other repository; a remote-tracking ref is your local record of that remote ref after fetch. The local branch, the remote-tracking ref, and the remote repository's own branch are distinct state locations. Later lessons cover remote administration, fetching workflows, pulling, pushing, and upstream configuration separately.

You know a remote named origin and its main branch.?origin identifies the remote, origin/main records fetched remote state locally, and main is a separate local branch ref.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.