Post

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 (Part 2): Remotes, origin and Branches as Pointers

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

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:

  • main on GitHub: the real one, on the server.
  • origin/main on your laptop: your memory of it.
  • main on 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 X moves the branch you’re on to X and makes your files match.
  • origin/main is 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 my origin/* memories.
  • [branch "main"] says plain push and pull on this branch go to origin, to its main.

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. origin is a nickname for its URL.
  • origin/main is 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.

This post is licensed under CC BY 4.0 by the author.