Git (Part 2): Remotes, origin and Branches as Pointers
Once commits and branches are clear, remotes are easy: what origin really is, what origin/main is, how fetch, pull and push move pointers, what refs/heads means, tracking, git reset --hard to any remote, and using several repositories from one folder.
Git series: Quick Summary · 1. Commits, Branches and Merging · 2. Remotes and Pointers · Cheat Sheet
Part 1 was all on one machine: commits, and labels pointing at them. Nothing changes here. We’re just adding another machine, and it turns out to work the same way.
For a long time I thought origin was a built-in part of Git. It isn’t, and once I understood what it really was, a lot of commands I’d been typing from memory finally made sense.
📑 Table of Contents
- A remote is just another copy
originis just a nicknameorigin/mainlives on your laptop- Fetch: update your memory
- Pull: you already know this part
- Push: asking GitHub to move its label
- Branch names, and what Git really calls them
git reset --hard origin/main, finally explained- Tracking: a separate setting
- Several repositories in one folder
- It’s all written in
.git/config - Author and committer
- Force push: moving GitHub’s label anyway
- The whole picture
A remote is just another copy
GitHub holds a copy of your repository: the same commits, and its own labels.
1
2
3
GitHub Your laptop
A ← B ← C main A ← B ← C main
That’s all a remote is: another copy of the repo, somewhere else. GitHub adds a website, pull requests and protected branches on top, which is why branches feel more solid there. Underneath it’s still commits and labels.
origin is just a nickname
You don’t want to type the full URL every time, so Git lets you save it under a short name.
1
2
3
$ git remote -v
origin git@github.com:you/prism.git (fetch)
origin git@github.com:you/prism.git (push)
origin is a nickname for that URL, and nothing more. It exists only in your local repo, and Git doesn’t care what it’s called. git clone happens to pick origin, but it could just as well be abc or myorigin, and a teammate can call the same repo something else entirely. You can have as many as you want:
1
2
3
git remote add origin git@github.com:you/prism.git
git remote add myremote git@github.com:you/prism.git # same place, another nickname
git remote add aiprism git@github.com:you/prism-ai.git # a different repo entirely
You don’t even need git clone. It’s only a shortcut for this:
1
2
3
4
git init
git remote add origin git@github.com:you/prism.git
git fetch origin
git checkout main # creates local main, following origin/main
origin/main lives on your laptop
Git works offline, so your laptop can’t know what’s on GitHub without asking. Instead it keeps a label that remembers where GitHub’s main was the last time you checked. That label is origin/main.
1
2
3
4
5
6
7
Your laptop
A ← B ← C
↑
main, origin/main
│ └── the branch "main" on the remote I call "origin"
└────────── my local branch
Read origin/main as nickname/branch. If I’d called the remote abc, it would be abc/main.
So there are really three things here, and it’s worth keeping them apart:
mainon GitHub: the real one, on the server.origin/mainon your laptop: your memory of it.mainon your laptop: your own branch.
git branch -a lists your memories as remotes/origin/....
Fetch: update your memory
A teammate pushes commit D to GitHub:
1
2
3
GitHub Your laptop
A ← B ← C ← D main A ← B ← C main, origin/main
Your laptop has no idea. Even git status will happily say “up to date”, because it’s only comparing against your memory.
Now run git fetch:
1
2
3
4
5
Your laptop
A ← B ← C ← D
↑ ↑
main origin/main
Look at what happened. Fetch downloaded D and moved origin/main, and that’s all. Your main didn’t move, HEAD didn’t move, and your files didn’t change. Fetched work doesn’t land where you are. It just becomes available.
My main tracks origin/main, meaning that’s the remote branch it follows. (Any branch can track any remote branch. More below.) So after the fetch, Git can tell me where I stand:
1
2
$ git status
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
The branch being tracked moved ahead, and mine is lagging. Catching up is my choice: merge, rebase, or reset --hard.
Pull: you already know this part
Look at that picture again. main is behind and origin/main is ahead, on the same line. That’s exactly the fast-forward from Part 1:
1
git merge origin/main
1
A ← B ← C ← D main, origin/main
git pull is simply these two steps together: git fetch, then merge.
And if you’d also committed something locally, it’s Part 1 again:
1
2
3
A ← B ← C ← D origin/main
\
E main (HEAD)
The two lines have split, so git pull has to do a three-way merge, or a rebase if you run git pull --rebase. There’s nothing new here. A remote branch is just another line of commits.
Push: asking GitHub to move its label
Push goes the other way. It uploads your commits, then asks GitHub to move its main.
1
git push origin main
1
2
3
GitHub Your laptop
A ← B ← C ← E main A ← B ← C ← E main, origin/main
GitHub only agrees if that’s a fast-forward. If a teammate pushed D first, moving the label to E would throw D away, so the push is rejected:
1
2
3
4
5
GitHub A ← B ← C ← D main
Laptop A ← B ← C ← E main
! [rejected] main -> main (fetch first)
The fix is to fetch, combine the work with a merge or a rebase, and push again.
Branch names, and what Git really calls them
We say main. Git has a fuller name for everything, and it’s simply where the label’s file lives inside .git/refs/:
1
2
3
refs/heads/main my branch "main"
refs/remotes/origin/main my memory of origin's main
refs/tags/v1.0 a tag
main is just the short form of refs/heads/main. You type the short one and Git works out the rest.
You’ll see the full names in Git’s config, and they explain a push you may have run without thinking about it. The full form of a push is from:to:
1
2
3
4
git push origin main # my main to their main
git push origin main:release # my main to their release
git push origin HEAD:refs/heads/test # wherever I am now, to a branch called test
git push gerrit HEAD:refs/for/master # Gerrit: send it for code review
That last one is a nice example. refs/for/master isn’t under refs/heads/, so it isn’t a branch. Gerrit sees that name and opens a review instead.
git reset --hard origin/main, finally explained
This was my big confusion, and now it’s easy. From Part 1:
git reset --hard Xmoves the branch you’re on to X and makes your files match.origin/mainis a label on your laptop.
So this command says: move my current branch to wherever origin/main points.
1
2
3
4
5
Before After git reset --hard origin/main
A ← B ← C ← D origin/main A ← B ← C ← D main (HEAD), origin/main
\ \
E main (HEAD) E (nothing points here now)
It doesn’t talk to GitHub at all. It only reads your local memory. That’s why you always fetch first, or you’re resetting to old information:
1
2
git fetch origin
git reset --hard origin/main
And since a branch can point anywhere, the target can be anything at all:
1
2
3
4
5
git reset --hard feature # another local branch
git reset --hard origin/main # my memory of a remote branch
git reset --hard aiprism/dev # a branch from a completely different remote
git reset --hard v1.0 # a tag
git reset --hard 796e2c3 # a commit ID
It’s the same operation every time.
Tracking: a separate setting
When you run a plain git push or git pull, how does Git know where to go? Each branch can have a remote branch it tracks. It’s just a setting:
1
2
3
git branch -u origin/feature # set it
git push -u origin feature # first push: push and set it together
git branch -vv # see what everything tracks
Here’s the catch: being at a commit and tracking a branch are two separate things. git reset --hard origin/x moves your branch but doesn’t change what it tracks. If you want both, that’s two commands.
Tracking also has nothing to do with where a branch came from. What a branch was created from is in the arrows. What it tracks is only a setting, and you can change it whenever you like.
Several repositories in one folder
Here’s what started all this for me. Nothing ties a folder to one repository. Remotes are just nicknames and branches are just labels, so one clone can work with completely separate repos:
1
2
3
4
5
6
7
git clone git@github.com:you/prism.git
cd prism
git remote add aiprism git@github.com:you/prism-ai.git # add a second repo
git fetch aiprism # get its commits and labels
git checkout -b prism-ai/main aiprism/main # a local branch that tracks it
Now one folder has branches following different repositories:
1
2
3
4
5
$ git branch -vv
* development 5e79ec9 [origin/development] ...
main 880f533 [origin/main] ...
prism-ai/development 7f19f12 [aiprism/development] ...
prism-ai/main e804e6b [aiprism/main] ...
1
2
3
4
5
6
7
8
GitHub: prism GitHub: prism-ai
main development main development
↑ ↑ ↑ ↑
┌───┼──────┼─────────────────────────────┼──────┼─────┐
│ origin/main origin/development aiprism/main ... │ memories
│ ↑ ↑ ↑ │
│ main development prism-ai/main │ my branches
└───────────────────── one .git ──────────────────────┘
git checkout between them and your whole folder turns into the other project. The local name prism-ai/main is just a name I picked, and the slash means nothing special.
And none of this is fixed. A development branch can follow origin/development today and a branch from another remote tomorrow, say prism/feature, and you can swap it whenever the work needs it:
1
2
3
git checkout development
git reset --hard prism/feature # put the branch on that commit
git branch -u prism/feature # and follow it from now on
One thing to watch: a local name that differs from the remote’s confuses a plain git push. On prism-ai/main it will refuse, so I tell it exactly where to go: git push aiprism HEAD:main.
It’s all written in .git/config
Everything we’ve set is plain text in one file:
1
2
3
4
5
6
7
[remote "origin"]
url = git@github.com:you/prism.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
remote = origin
merge = refs/heads/main
You can read it now:
[remote "origin"]is the nickname and its URL.fetch = ...is the from:to again: take all their branches and store them as myorigin/*memories.[branch "main"]says plainpushandpullon this branch go toorigin, to itsmain.
That word merge confused me for ages. It doesn’t mean “was merged from”. It only means “the remote branch I follow”.
Author and committer
Each commit stores two people, and both come from user.name and user.email in your config:
- Author: who wrote the change.
- Committer: who created this particular commit.
Usually that’s the same person. They differ when a commit gets re-created, which you now know is what rebase and cherry-pick do. If I cherry-pick Ravi’s commit, Ravi stays the author and I become the committer. A plain merge doesn’t change either one, because it doesn’t touch the original commits.
1
2
git log --format='%h author: %an committer: %cn' # see both
git config user.email "you@example.com" # set for this repo
Force push: moving GitHub’s label anyway
Remember that after a rebase your commits are new copies. GitHub’s main can’t fast-forward to them, so a normal push is rejected.
git push --force tells GitHub to move the label anyway. It’s only a label, so Git will happily do it, and you can rewrite a branch’s entire history this way. The only thing stopping you on GitHub is a protected-branch setting, and that’s GitHub’s rule, not Git’s.
It’s also how you delete a teammate’s work by accident. So use the safer one:
1
git push --force-with-lease
This means “only if GitHub’s branch is still where my memory says it is”. If someone pushed in the meantime, it stops with stale info.
Be careful with what you do next, though. If you just run git fetch and try again, your memory is now up to date, so the check passes and their work gets overwritten. After stale info, fetch and actually look at what arrived before pushing.
The whole picture
1
2
3
4
5
6
7
GitHub A ← B ← C ← D main
fetch ↓ ↑ push
Your laptop A ← B ← C ← D origin/main memory of GitHub's main
↑
main (HEAD) your own branch
- A remote is another copy of the repo.
originis a nickname for its URL. origin/mainis your laptop’s memory of where the server’s branch was.- Fetch updates your memory. Pull is fetch plus merge. Push asks the server to move its label.
- A branch is a pointer, so you can reset it to any commit, from any branch, on any remote.
- One folder can work with as many repositories as you like.
For the commands and flags, the cheat sheet has everything on one page.