Throughout this module, messages have kept appearing that we kept putting off:

And behaviours Git worked out on its own: plain git push knowing where to go, git pull with no arguments, and that git switch docs/update-notes which created a local branch that did not exist.

All of it points at the same concept, and it is the one that closes the module: tracking branches. A simple mechanism — two lines of configuration per branch — on which half of Git's conveniences and most of its status messages depend.

Along the way we are going to settle once and for all the confusion we have been carrying since lesson 04-01: main, origin/main and the server's main are three different things with similar names that people mix up constantly. By the end of this lesson that distinction will be automatic, and with it the whole module falls into place.

1. What a tracking branch is
2. Where it lives: branch.<name>.remote and branch.<name>.merge
3. The three things called main
4. Where "ahead of 'origin/main' by 2 commits" comes from
5. git branch -vv: every branch's state at a glance
6. Setting, changing and removing the upstream
7. Creating a local branch from a remote one: Git's DWIM
8. The ambiguous case of several remotes
9. @{upstream} and @{push}: referring to the tracking branch
10. Closing the module

The definition:

A tracking branch is a local branch that has a recorded association with one specific remote reference. That associated reference is called its upstream.

Put plainly: your main branch "knows" that its counterpart on the server is origin/main. And with that one fact, Git can:

• Push with no arguments: git push knows which remote and which branch.
• Fetch and pull with no arguments: git pull too.
• Report the gap: "you are 2 commits ahead and 3 behind".
• Offer shortcuts: @{upstream} to refer to the counterpart without typing its name.

Without that association everything still works, but you have to spell it all out:

One important note on terminology, because Git's own documentation is not always consistent. There are two uses of "tracking branch" that are worth keeping apart:

And remember too the other sense of the word upstream, the one from lesson 04-01: the conventional name for the remote pointing at the original project you forked from (module 7). Three uses of two words. Here, whenever we say upstream, we mean the remote reference associated with a local branch.

As with everything in Git, this is not magic: it is two lines in a text file.

Every branch with tracking has its own section:

One detail throws people the first time they read it: merge = refs/heads/main is the name of the branch on the server, not refs/remotes/origin/main. There is logic to it: the configuration says "my counterpart is the main branch of the remote repository"; it is the refspec's job to know that this branch is stored locally at refs/remotes/origin/main.

You query them like any other setting:

And there is an optional key you may come across:

If it is true, git pull on that branch will use --rebase instead of merging (lesson 05-01).

Take this in: tracking is local configuration in your repository. It does not travel with a push, nobody else can see it and every person on the team has their own. Bruno can have his main following origin/main while Carla has hers following mirror/main, and neither of them will ever know.

This is the key section of the lesson, and it deserves your full attention. These three things have similar names and are not the same:

Whenever something about remotes baffles you, ask yourself: which of the three am I talking about?

Examples you can apply straight away:

• "My colleague says it is already up there but I cannot see it." → You are both talking about the server's main; what you are looking at is your origin/main, which is out of date. Fix: git fetch.
• "I ran fetch and my files have not changed." → A fetch updates origin/main; your files depend on main. That is correct behaviour.
• "I ran git reset --hard origin/main and lost my commits." → You moved your main to where your photograph of the server sits. The commits are still in the reflog (lesson 09-04), but the branch no longer reaches them.
• "git push says Everything up-to-date but my change is not there." → Your main is where your origin/main is; the change was never committed.

One experiment fixes the idea better than any explanation:

A successful push updates your origin/main as well, and that makes sense: Git has just spoken to the server and knows for certain where its reference ended up.

That message does not come from anywhere magical: Git compares your branch against its upstream and counts the commits on each side. It can only do that because tracking is configured; without it, git status would say nothing about the server at all.

Let us take it apart, because every piece matters:

• main...origin/main — three dots, not two. This is the symmetric difference: every commit reachable from one of the two references but not from both. In other words, what is exclusive to each side.
• --left-right — marks each commit according to which side it came from: < for the left one (main), > for the right one (origin/main).
• --count — instead of listing the commits, it counts how many there are on each side.

The result reads like this:

Two dots versus three dots, which is the most common source of confusion:

Without --count, you see it commit by commit:

Two of mine (<) and one of theirs (>): we have diverged, and git status will put it like this:

The gap is measured against your origin/main, which is a photograph. Not against the server.

If you have not run a fetch for two days, that "2 commits ahead" may be completely false: the server may have moved on fifteen times since. git status never touches the network.

That is why the first command of the day is git fetch: without it, all these numbers describe the past.

And that is why this combination exists, doing both things at once:

There is a git status option that sounds as though it does the job by itself:

But --ahead-behind only controls whether the gap is calculated at all; it does not fetch anything from the server. The only way to refresh the photograph is still fetch.

In lesson 03-06 we mentioned -vv and said it would make sense once remotes were in play. That moment has arrived.

With the double v:

The square brackets are the new information, and each line tells a different story:

That last case is the one to learn to recognise. A branch with no brackets does not exist on any server: lose the disk and you lose that work. Having branches like that is perfectly legitimate (experiments, trials), but it pays to know which ones they are.

And this can turn up too:

gone means the branch had an upstream but that upstream no longer exists: somebody deleted the branch on the server and you have run fetch --prune. It is the usual sign of "this branch has been integrated and cleaned up; you can delete yours".

A very useful command for periodic tidying:

These are the natural candidates for git branch -d, and it complements the --merged of lesson 03-06 beautifully (which failed on branches integrated by squash: if the platform deleted it after integrating, it will show up here even though --merged cannot detect it).

Other ways to query the tracking:

The %(upstream:short) and %(upstream:track) placeholders are the same git for-each-ref ones we used in lesson 03-06 for the pretty branch listing.

There are four routes to configuring tracking, and it is worth knowing them all because each one turns up at a different moment.

It pushes and configures the tracking in one step. It is the natural route when you publish a new branch, as we saw in lesson 04-05.

We have had this configured since lesson 01-06. With it, a plain git push on a branch with no upstream creates it on the server and configures the tracking, with no -u:

Without that setting, the same git push would have failed with the classic:

A message you have seen a thousand times if you have used Git without that setting.

For a branch that already exists in both places but is not paired up:

There is a short form with -u (which here means the same as it does in push):

With no branch name, it applies to the current one. It is the command you need when you created the repository with init and added the remote afterwards, or when the configuration has been lost for some reason.

It can point at a branch with a different name, which is useful in migrations:

Now your local main follows origin/develop. It is unusual, but perfectly valid: the association does not require the names to match.

Notice what has disappeared: the line about the gap. With no upstream, Git has nothing to compare against and git status goes silent about the server. It is the best demonstration that the message depends entirely on this configuration.

Let us put it back:

Carla has just cloned and wants to work on Ana's documentation branch. She has only one local branch:

Remote references are not branches of hers, as we have known since lesson 04-01: they are read-only and she cannot commit on them. She needs a local branch.

The explicit route would be this:

Long and repetitive. Which is why Git has a shortcut:

This is Git's DWIM (Do What I Mean). The internal reasoning goes:

1. Is there a local branch called docs/update-notes? No.
2. Is there exactly one remote reference with that name? Yes, origin/docs/update-notes.
3. Then this person wants to work on that branch: create the local one from it and configure the tracking.

And the result is exactly the same as the long form:

The same works with checkout for compatibility, although as we know from lesson 03-02 switch is preferable:

It does not apply if the local name already exists:

If you already have a local main, this simply switches to your existing branch. It creates nothing and reconfigures nothing.

It does not work if you have not fetched:

If a colleague has only just created that branch and you have not fetched the references, Git does not know about it. Fix: git fetch first. It is a very common error when joining work already in progress.

It does not work with several ambiguous remotes: that is the next section.

There is a setting that always demands the explicit form:

With it, git switch <branch> works only with existing local branches. Most people prefer DWIM switched on, but it is worth knowing the setting exists if the automatic behaviour makes you uneasy.

When more than one remote has a branch of the same name, DWIM cannot guess and gives up.

Suppose Bruno has two remotes, as in lesson 04-02:

And now:

Git refuses, and rightly so: choosing for you would mean configuring tracking towards a repository that might not be the one you want, with the risk of pushing work to the wrong place.

1. Be explicit with the remote reference (the clearest):

Or with --track, which also puts the intention on record:

2. Use the disambiguating syntax:

With --track and no -c, Git creates a local branch with the same short name as the remote one.

3. Configure a preferred remote:

From then on, faced with ambiguity Git will always choose origin without asking:

It is the recommended solution if you routinely work with several remotes — for example in the fork workflow of module 7, where having origin and upstream side by side is the norm.

With several remotes it sometimes pays to decouple the names so you do not lose track:

Two local branches with clear names, each following a different remote. Remember that tracking does not require the names to match.

Git offers a syntax for referring to a branch's upstream without typing its name. It is a small saving but a very comfortable one, and it turns up constantly in aliases and scripts.

@{upstream} (shortened to @{u}) resolves to the current branch's upstream:

And it can be applied to another branch:

The most practical uses, all of them independent of whichever branch you happen to be on:

Notice the elegance of @{u}..: by omitting the right-hand side, Git uses HEAD. And ..@{u} omits the left-hand one, to the same effect. These are the ranges of module 2 making the most of their defaults.

There is a second reference, @{push}, pointing at where a git push would go. Normally it coincides with @{upstream}, but not always: if you work with remote.pushDefault configured, or with push refspecs different from the fetch ones, they can differ.

It is the right reference for answering "which commits would go out if I pushed right now?":

In the fork workflow of module 7 — where you read from upstream and write to origin — that distinction becomes very useful.

And a couple of aliases worth their weight in gold:

Aliases in depth, in lesson 06-04.

Let us recap what we have built across these six lessons, because module 4 is a conceptual leap and it helps to see it whole.

We began by demolishing the myth: a remote is not a magic server, it is a short name for a URL stored in .git/config. We saw that in a distributed system there is technically no central server: every repository is equal and the "official" one is only official by team agreement. We finally understood what a bare repository is — the contents of .git/ with no working tree — and why it is the correct way to set up a repository that receives pushes. And we discovered that remote references live in .git/refs/remotes/, on your disk, and that origin/main is a photograph with a date on it, not a live window.

Then Ana published the project. We registered the remote with git remote add — a purely local operation that does not even validate the URL — learned to inspect it, rename it and change its address, and took apart the refspec +refs/heads/*:refs/remotes/origin/*, that line hardly anyone can read and which explains where the slash in origin/main comes from.

We sorted out authentication: why reading a public repository needs no credentials while writing always does, what a personal access token is and why it replaced the password, how an SSH key pair is generated and used, and how each operating system stores credentials — with Git Credential Manager smoothing Carla's way on Windows 11.

We tackled Git's most widespread confusion: fetch versus pull. The first downloads and updates remote references without touching a single file, and is absolutely safe; the second adds an integration that does modify your work and can produce conflicts. We learned to look into the gap between the two, to clear out ghost references with --prune, and Carla finally cloned a repository with the whole of module 3's history inside it.

We turned the channel around with git push: what it actually sends, what -u does, how a push refspec is written, why the server rejects non-fast-forward pushes — so as not to destroy someone else's work — and why --force-with-lease is almost always the right answer when forcing really is necessary.

And we have finished by tying the threads together: tracking branches, two lines of configuration per branch on which git push with no arguments, git pull with no arguments, the git status messages and the DWIM of git switch all depend.

The idea that holds the whole module up, and the one to take away: remotes have changed nothing of what you already knew. Merging Bruno's work is the same git merge from module 3. Conflicts are resolved the same way. Branches are still 41-byte files. All that has been added is the transport: how objects manage to travel from one .git/ to another. Once they have arrived, everything works exactly as you already knew.

The team is collaborating now. All three push, fetch and integrate, and the project moves forward. But if Ana looks at main's history with a critical eye, she starts to see things she does not like:

Two distinct problems living side by side:

• Merge commits that say nothing. Those Merge branch 'main' of https://… are not design decisions: they are the trace of two people pulling at the same time. They clutter the graph and add no information.
• Commits that should not exist in that shape. fix stuff describes nothing. And on the working branches there are wip, wip 2, now it works and the odd forgotten console.log that got pushed by accident.

There is also a whole repertoire of operations that team work makes indispensable: taking one specific commit from one branch to another without dragging the rest along; putting half-finished work aside to deal with an emergency and picking it up afterwards; marking versions with tags that get published on the server; and undoing a commit already pushed without rewriting the history everyone else already has.

Module 5: Advanced Git Operations takes us into that territory. We will look at git rebase — which rewrites commits to produce a linear history, and which we have mentioned three times without developing — interactive rebase for reordering, combining and rewriting commits before publishing them, git cherry-pick for transplanting individual commits, git stash for setting work aside temporarily, tags for marking versions, and git revert for undoing without deleting.

It is a module about precision, and it arrives at the right moment: now that the history is shared, rewriting it has consequences for other people. Everything you have learned here about push, about the non-fast-forward rejection and about --force-with-lease is exactly what will let you tell what can be rewritten from what cannot.

Mistake 1: confusing main, origin/main and the server's main. It is the mistake that contains almost all the others. Whenever in doubt, ask yourself which of the three you are talking about. The first two are on your disk.

Mistake 2: trusting the "ahead/behind" without having fetched. git status never touches the network: it compares against your photograph. If you have not fetched for two days, those numbers describe the past.

Mistake 3: confusing .. with .... Two dots is "what B has and A does not"; three dots is "what is exclusive to each side". For the gap you use ... with --left-right --count.

Mistake 4: fatal: The current branch X has no upstream branch. The branch has no tracking. Fix it with git push -u origin X, or once and for all with push.autoSetupRemote true.

Mistake 5: DWIM failing because you have not fetched. If a colleague has just created the branch and you have not fetched the references, git switch <branch> will give invalid reference. A git fetch sorts it out.

Mistake 6: ignoring branches marked gone. They mean their branch on the server has disappeared, usually because it was integrated. They are the clearest candidates for local deletion.

Mistake 7: not noticing that a branch has no upstream. With no brackets in git branch -vv, that branch exists only on your disk. Fine for an experiment, dangerous for work that matters.

Mistake 8: believing tracking is shared with the team. It is local configuration in your .git/config. Everyone has their own and nobody sees anybody else's.

Tip 1: git fetch && git status as your start-up routine. Two commands that tell you the truth instead of showing you an old photograph.

Tip 2: use git branch -vv for the weekly review. At a glance you see what is unpushed, what is unfetched, what is local only and what can be deleted.

Tip 3: turn on push.autoSetupRemote true. It eliminates the "no upstream branch" error for good. You have had it since lesson 01-06.

Tip 4: learn @{u}. git log @{u}.. for what you have not pushed and git log ..@{u} for what you have not fetched work on any branch without changing a character. Save them as aliases.

Tip 5: with several remotes, set checkout.defaultRemote origin. It avoids the ambiguity error and saves you typing the full reference every time.

Set up a bare server and two clones. Then, with commands, prove each statement:

1. Committing locally moves only main.
2. Pushing moves main, origin/main and the branch on the server.
3. When the other clone pushes something, the first one's origin/main does not change until it fetches.
4. git status works out the gap without touching the network: engineer a situation in which the message is objectively false with respect to the server, and explain why.
5. Reproduce git status's calculation by hand with git rev-list.

In a repository connected to a bare:

1. Create a local branch without an upstream and prove with two different commands that it has none.
2. Check what git push says on that branch if you switch push.autoSetupRemote off.
3. Configure its upstream all three possible ways (undoing between each) and verify the result in .git/config every time.
4. Remove the upstream and observe what disappears from git status.
5. Create a local branch that follows a remote one with a different name and prove that it works.

1. Set up two bare servers and a working repository with both registered.
2. Create a branch of the same name on both, with different content.
3. Try to use DWIM and capture the error.
4. Resolve it in the three ways explained in the lesson.
5. Prove with git branch -vv that in each case the local branch follows the right remote.
6. Check with git log that the content really does differ depending on the remote chosen.

Solution 1:

And nothing has changed on the server either:

All three aligned. The push updates your origin/main because Git has just spoken to the server and knows for certain where it ended up.

The message is objectively false. The server has a commit Ana does not have, so her branch is behind. But git status compares against origin/main, a photograph taken before Bruno's push, and it never touches the network. It is not lying: it is telling the truth about information that has expired.

That is more like it. The only way for those numbers to be true is to fetch first.

Zero commits exclusive to main (nothing to push), one exclusive to origin/main (something to fetch). That is exactly "behind by 1 commit". And in detail:

The > shows it comes from the right-hand side, origin/main.

Solution 2:

Only main shows up. The new branch has no entry at all.

Git does not guess: it insists you say where the branch is going the first time.

All three produce exactly the same configuration. What changes is the moment and the convenience, not the result.

The gap line has disappeared. With no upstream, Git has nothing to compare against. It is the proof that the message depends entirely on this configuration.

Look at that last line: local-order -> feature/alphabetical-order. The local branch is called one thing and the server's another, and the push works perfectly well. Tracking does not require the names to match.

Solution 3:

Git cannot guess which one you want, and guessing wrong would mean pushing work to the wrong repository.

The ambiguity is gone: when in doubt, Git picks origin.

Two different commits under the same branch name on two different servers. This is where you see why Git prefers to fail rather than guess: choosing wrong would have meant working on the wrong base and, worse still, pushing the result to the wrong place.

With this lesson we close module 4. What we learned here:

• A tracking branch is a local branch associated with a remote reference, its upstream. That association is what makes git push and git pull work with no arguments, what produces the gap messages in git status and what powers the @{u} shortcut.
• It lives in two lines of .git/config: branch.<name>.remote (which remote) and branch.<name>.merge (which branch on that remote). It is local configuration: it does not travel with a push and everybody has their own.
• main, origin/main and the server's main are three different things. The first two are on your disk: you move the first by committing, and Git moves the second when it talks to the server. The third is on another machine and anyone on the team can move it. Almost every bewilderment with remotes is settled by asking which of the three is being talked about.
• The "ahead/behind" is worked out with git rev-list --left-right --count main...origin/main, using the three-dot symmetric difference. And it is worked out against your photograph, not against the server: without a prior fetch, those numbers can be false.
• git branch -vv shows every branch's upstream and gap in square brackets. No brackets = no upstream, the branch is purely local. With gone = its branch on the server no longer exists, usually because it was integrated: a candidate for deletion.
• The upstream is set with git push -u, automatically with push.autoSetupRemote true, after the fact with git branch -u origin/<branch>, or when creating the branch with --track. It is removed with --unset-upstream, and git status then stops reporting the gap.
• The DWIM of git switch <branch> creates a local branch from a remote one of the same name and configures the tracking, provided it does not already exist locally and exactly one remote reference matches. With several remotes it fails: resolve it by being explicit, with --track, or by setting checkout.defaultRemote.
• @{upstream} (or @{u}) refers to the current branch's upstream without naming it: git log @{u}.. (what you have not pushed) and git log ..@{u} (what you have not fetched) work on any branch.

The project has left Ana's laptop and circulates between three machines and three operating systems. The team genuinely collaborates: all three push, fetch and integrate, and task-manager moves forward.

But the history is starting to show the strain. It is filling up with merge commits that say nothing, with messages like fix stuff and wip 2, and with half-finished work published by accident. And new needs are appearing that solo work never raised: taking one specific commit from one branch to another, setting unfinished work aside to deal with an emergency, marking a released version or undoing something already on the server.

In module 5: Advanced Git Operations we will learn to manipulate the history with precision: git rebase to rewrite commits and obtain a linear history, interactive rebase to reorder, combine and correct them before publishing, git cherry-pick to transplant individual commits, git stash to set work aside temporarily, tags to mark versions, and git revert to undo without deleting.

And everything you have learned in this module is precisely what will let you use them with judgement. Because from now on the history is shared, and rewriting something another person has already downloaded is not a local operation: it is a decision that affects the whole team.