Lesson 01 of 06Concept

Work with Remote Branches

Goal: Understand how local branch names, remote-tracking names like origin/main, and the branches on the server relate.

As soon as a repository has somewhere to push to, three things called "main" exist: your main, the server's main, and your local record of where the server's main was the last time you looked.

Keeping those three apart is the single most useful idea in collaborative Git. Almost every confusing message about pushing and pulling makes sense once you can tell them apart.

A remote is a nickname for a URL

A remote is a name your repository gives to another copy of itself. origin is the conventional name for the one you cloned from; there is nothing special about the word.

Remotes are just configuration: adding one does not copy anything, and nothing about your history changes.

Listing what your repository knows about

$ git remote -v

origin	https://github.com/acme/weather-app.git (fetch)
origin	https://github.com/acme/weather-app.git (push)

One remote, with the same URL for reading and writing. git remote add upstream <url> adds a second, which is how you track the original repository after forking it.

Three kinds of branch name

- Local branch — main. Yours. git switch moves onto it, commits move it forward. - Remote-tracking branch — origin/main. A read-only bookmark recording where origin's main was the last time you talked to the server. You never commit to it; it moves only when you fetch, pull or push. - The branch on the server — the real main in the remote repository. You cannot see it without asking over the network.

After a fetch, before you commit

Both names point at the same commit, so you are "up to date with origin/main". Make a commit and main moves on while origin/main stays put: you are then one commit ahead.

Who moves which name

main

Moves when you commit
Moves when you merge, rebase or reset
Only you change it

origin/main

Moves when you git fetch or git pull
Moves when your git push succeeds
Never moves on its own

How git status reports the gap

$ git status

On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

"Ahead", "behind" and "diverged" are all comparisons between your branch and its upstream: the remote-tracking branch it is paired with. The count is only as fresh as your last fetch.

Seeing them all

git branch — your local branches
git branch -r — remote-tracking branches, such as origin/main
git branch -a — both, so you can see what exists where
git branch -vv — each local branch with its upstream and how far ahead or behind it is