Team training · Block 4 of 6

Remotes

Where other people's copies come in

4.1

What a remote is

Every clone is a complete repository

Not a checkout. Not a working copy of a central server.

When you clone, you get the entire commit graph — every commit, every branch, all of history — plus a set of extra pointers recording what the server looked like when you last checked.

$ git clone git@github.com:team/pricing.git
Cloning into 'pricing'...
remote: Enumerating objects: 1284, done.
Receiving objects: 100% (1284/1284), 412 KiB | 6 MiB/s, done.

$ cd pricing && git log --oneline | wc -l
327        # all 327 commits are already on your disk

Which is why git log works on a plane.

origin is just a name

$ git remote -v
origin  git@github.com:team/pricing.git (fetch)
origin  git@github.com:team/pricing.git (push)

A remote is a nickname for a location. origin is the default name clone gives it — nothing more.

And that location can be almost anything git knows how to reach:

Looks like	Is
`/srv/git/pricing.git`	a directory on this machine
`https://github.com/team/pricing.git`	an HTTPS URL
`git@github.com:team/pricing.git`	SSH, scp-style
`ssh://git@host:22/team/pricing.git`	SSH, full form

Same git underneath — only the transport differs.

4.2

Remote-tracking branches

Three pointers, not two

Watch the note go stale, then catch up

1 · Alice pushes. The server moves to the new commit. Your note still points at the old one — git told you nothing.

2 · You fetch. origin/main catches up; main and your files stay put. Only now can git say “behind by 1”.

3 · You integrate. git pull (fetch + merge/rebase) finally moves main to catch up.

kata · katas/remotes — Tasks 1–3

This replaces the two static Alice/Bob slides with one you drive with the arrow key while narrating. Run it live from katas/remotes as you click. STOP after step 1: ask whether anything is wrong with your repo. The answer is no — the note is simply stale, which is what a note does. Nothing updates behind your back. This is why “my git is out of date” is a category error. Step 2 is the key frame: fetch moves only the amber note. main and the working directory do not move, which is why fetch is always safe and can never cause a conflict. Point at exactly what moved — the middle pointer advanced, the left one did not. Step 3: only now does your branch move, and only because you asked. On our setup pull's merge-vs-rebase choice is free because trunk squashes anyway — but fetch-first-then-look is the habit worth building. The three-pointer picture from the previous slide is exactly this, animated: left box main, amber note origin/main, and the server itself up top.

pull is fetch plus a merge

fetch

Updates your notes about the server. Always safe.

pull

Fetch, then merge or rebase that into your branch. Moves your work.

$ git pull                  # fetch + merge (default)
$ git pull --rebase         # fetch + rebase

If you're unsure what state you're in, fetch first and look. Then decide.

Worst case for a blind pull: you have a stray commit on main that shouldn't be there. Pull silently makes a merge commit to reconcile it — now main and origin/main have diverged further, and you're carrying a merge you never meant to create. fetch first and you'd have seen it coming.

Push the asymmetry hard: fetch-then-look-then-integrate is strictly better than a reflexive pull, every time. Fetch is free and safe; the only thing pull adds is a decision, and pull makes that decision for you, blind. The concrete trap is the danger line. Someone commits to local main by accident — forgot to branch. A blind pull doesn't warn; it merges origin/main into their main, producing a merge commit and a divergence that then has to be pushed and cleaned up. Had they fetched, git status would have said "your branch and origin/main have diverged", and they'd have caught the stray commit before making it worse. This is why "always pull before you push" is folk wisdom rather than a rule — it tells you what to type without telling you what's happening, and it hides the choice between merge and rebase. On our setup either integration works, because trunk gets squashed anyway. The point is choosing deliberately, on main especially, where a stray merge commit is pure noise.

4.3

push, and why it gets rejected

Getting your branch onto the server

$ git switch -c feature/discount
$ git push -u origin feature/discount   # -u = --set-upstream
 * [new branch]      feature/discount -> feature/discount
branch 'feature/discount' set up to track 'origin/feature/discount'.

-u does two things, once: it creates the branch on the server, and it records origin/feature/discount as this branch's upstream. After that, bare git push and git pull already know where to go.

git branch -vv shows the link; git status can now say "ahead 2, behind 1". When the PR is merged, clean up the server side too: git push origin --delete feature/discount.

kata · katas/remotes

The day-one action the rest of the block quietly assumed. Until you push with -u, origin has never heard of your branch and there's no upstream — which is why a bare git push on a fresh branch complains "no upstream branch". Say what upstream actually is: a stored link from your local branch to a remote-tracking branch — the amber note from the three-pointers slide. It's what lets git compute ahead/behind, and what makes a bare push or pull unambiguous. -u is only needed the first time; the link is remembered after that. Some teams set push.autoSetupRemote so even the first bare push works — mention it only if asked. The delete line ties straight to commandment 13: after a squash merge you delete the branch locally and remotely, then re-branch from main. git push origin --delete is the remote half, and it's easy to forget — stale remote branches pile up.

Both developers commit

Bob's commit is not a descendant of where the server now is.

A normal push asks the server to move its label forward. Forward means "to a commit that has the current one as an ancestor". Bob's doesn't.

The rejection, decoded

bob$ git push origin main
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs

hint: Updates were rejected because the remote contains work
hint: that you do not have locally.

bob$ git pull --rebase
bob$ git push origin main

kata · katas/remotes — Task 4

4.4

The shared history rule

What force push actually does

--force tells the server to move its label to your commit regardless of ancestry.

That is precisely the operation git refused to perform two slides ago.

Alice's commit becomes unreferenced on the server. She still has it locally — until she cleans up, or until someone clones fresh and it's simply not there.

Why rewriting shared history hurts

Every rewrite in Block 3 — amend, rebase, interactive rebase — produces new hashes.

If a colleague holds the originals, your histories have genuinely diverged. Their next pull produces duplicated commits and conflicts that look impossible.

Commandment 04

Never rewrite history someone else has pulled. Once it's shared, it's not yours to edit.

The lease

$ git push --force-with-lease origin my-branch

Move the label to my commit — but only if the server is still where I last saw it.

If anyone has pushed since your last fetch, the lease fails and the push is rejected. You find out instead of overwriting them.

Commandment 05

Force push only your own branch, and only with --force-with-lease.

Keeping junk out — `.gitignore`

$ cat .gitignore
node_modules/
dist/
*.env
.DS_Store

A tracked list of path patterns git treats as invisible — build output, dependencies, local secrets, editor cruft. Matching files stop appearing as untracked, so a reflexive git add -A can't sweep them in.

.gitignore only affects untracked files. Something already committed stays tracked no matter what you add here — you have to stop tracking it first: git rm --cached secrets.env, then commit.

The mechanism behind commandment 8, so it lands right before the rule. Callback to Block 1's four states: .gitignore acts on the "untracked" state only. It tells git "don't even offer to track these", which is what makes git add -A safe. The gotcha is the fragment and it catches everyone: people add a file to .gitignore expecting it to vanish from the repo. It doesn't — ignore rules are consulted only for untracked files, and a file git already tracks stays tracked. git rm --cached stops tracking it while leaving it on disk; now it's untracked, the ignore rule applies, and a commit records the removal. Worth one line: a global ignore (git config --global core.excludesfile ~/.gitignore_global) is the right home for editor and OS cruft like .DS_Store, so it doesn't have to clutter every project's file.

One more thing that leaves your machine

Commandment 08

Never commit secrets, build output, or dependencies.

Once a secret is pushed, treat it as compromised. Removing it from history means rewriting every commit since — and everyone re-cloning.

Rotate the credential first. Cleaning history is damage limitation, not a fix.

Where we got to

Thing	What it actually is
`origin`	A nickname for a URL
`origin/main`	Your local note about the server
`fetch`	Refresh the note. Always safe
`pull`	Fetch, then integrate. Moves your work
`push`	Move the server's label forward
Rejected push	Your commit isn't a descendant
`--force-with-lease`	Override, but only from a known state