In the previous lesson we used git push several times without explaining it. That was fair enough: the project had to get onto the server before we could study the receiving side. Now we turn the channel around and take the sending command apart.

git push is the command with consequences for other people. Everything you have done so far — committing, branching, merging, even getting things wrong — happened inside your own .git/ and could be undone without anyone noticing. A push changes the repository the whole team treats as the reference. What you send, others download; what you delete from the server, others stop having.

That is why this lesson devotes so much space to rejections and to the force options. Pushing is easy; knowing why the server says no, and what is safe to do about it, is what separates the people who do not destroy their colleagues' work from the people who do.

Ana finally pushes main and her branches to the team server, and Bruno and Carla receive them.

1. What git push actually sends
2. The first push: git push -u origin main
3. What -u actually does
4. The push refspec
5. The short forms and push.default
6. When the server says no: non-fast-forward
7. --force-with-lease versus --force
8. Deleting a branch on the server
9. Pushing tags
10. Ana publishes her branches; Bruno and Carla receive them

The precise definition, which is narrower than most people imagine:

git push does two things: it uploads to the remote the objects it is missing, and it asks it to update a reference so that it points at a specific commit.

Objects and a pointer. Nothing else.

What it does NOT send:

• Your working tree. Modified but uncommitted files stay on your disk. If you have edited app.js and not run commit, that change does not leave your machine however much you push.
• Your index. The staging area is yours and yours alone.
• Your configuration. .git/config does not travel: each person's remotes, aliases and settings are their own.
• Your other branches, unless you ask for them explicitly.
• Your reflog. The record of your movements is local.
• Ignored files. Whatever is not inside a commit does not exist as far as push is concerned.

That first one is the most important and the source of a classic bewilderment: "I pushed and my colleague cannot see the change". Almost always it means the change was never committed. Only what sits inside a commit travels.

That second-to-last step — the fast-forward check — is the heart of section 6 and the reason behind almost every rejection.

And an interesting consequence: pushing is incremental. Git works out which objects the server is missing and sends only those, compressed into a packfile. Sending a project's thousandth commit costs no more than sending its second.

Let us go back to the moment Ana published. Her repository had the remote registered (lesson 04-02) and authentication sorted out (lesson 04-03), but she had never pushed anything:

That output is worth reading in full, because it tells the whole story:

Look at the efficiency: the project's entire history — four base commits, two merges, a squash, a resolved conflict — fits in 4.87 KB. That is the delta compression of the data model we studied in lesson 01-04.

And a check from the server's side:

The repository that was empty now has a branch and a history.

-u is short for --set-upstream, and it turns up in absolutely every Git tutorial without hardly any of them explaining what it does.

What it does is write two lines into .git/config:

That [branch "main"] section is the tracking relationship: the association between your local main and the main branch on origin. And from that moment on, several things change:

The check is immediate:

That up to date with 'origin/main' line appears only if tracking is configured. Without it, git status would have nothing to compare against.

You only need -u the first time you push a branch. After that the configuration is written and plain git push works.

And remember that in lesson 01-06 we configured this:

With that setting (available since Git 2.37), -u becomes unnecessary: when you push a new branch, Git configures the tracking automatically. Ana could simply have typed git push and the result would have been identical. We used it explicitly so that you could see what happens underneath.

Everything to do with tracking branches — how to inspect them, how to change them, what that "2 commits ahead" really means — is the subject of lesson 04-06, the one that closes the module.

In lesson 04-02 we took the fetch refspec apart. The push one uses exactly the same syntax, and seeing it completes the circle.

The full form of a push is:

Read aloud: "send my main branch and use it to update the server's main branch."

Compared with the fetch refspec, the logic is identical and only the direction flips:

In both cases, left = where it comes from, right = where it goes. Once you see it that way, it stops being arbitrary syntax.

The third one, HEAD:main, is useful when you are on a detached HEAD, or on a branch whose local name differs, and you want to send what you have to main.

These two lines are equivalent:

Git expands short names. But there is one case where the full form is mandatory: when the destination branch does not exist yet and the name is ambiguous. If the server had a tag called review and you wanted to create a branch with that name, Git would not know which you meant:

The solution is to be explicit:

If you leave the left-hand side empty, you are sending nothing to that reference, which deletes it:

This is the old deletion syntax, and we come back to it in section 8.

Day to day, hardly anyone writes the full refspec. These are the short forms and what each one means:

Form 4 is the one you will use 95% of the time, and its behaviour depends on a setting we already configured back in lesson 01-06:

The possible values and what they do:

matching deserves a historical warning. It was the default until Git 2.0, and it produced an unpleasant surprise: you typed git push intending to send the branch you were on, and Git sent all eight local branches with namesakes on the server in one go, half-finished experiments you never meant to publish included. Changing it to simple was one of Git's best decisions. Do not set it to matching.

And one option that genuinely is useful when you really do want to send several:

Explicit and deliberate, which is how it should be.

This is Git's most frequent rejection and the one you really must understand.

Bruno starts work in the morning, makes two commits and pushes:

The server has commits you do not have. While Bruno was working, Ana pushed hers. The graph looks like this:

Both started from c2a8f1e and each moved on separately. They have diverged, exactly the concept from lesson 03-01.

If Git accepted Bruno's push, the server's main reference would jump from b4d7e93 to 3e9c2a5. And since b4d7e93 is not an ancestor of 3e9c2a5, Ana's two commits would stop being reachable from any branch: they would vanish from the project without anyone noticing, and anybody cloning afterwards would see no trace of them.

That is why Git rejects the push: so as not to destroy someone else's work. The rule is that a server reference may only advance fast-forward, that is, towards a descendant of where it was. It is the same notion of fast-forward from module 3, now applied as a safety measure.

And here it is worth connecting two things. Remember from lesson 04-02 that the fetch refspec carries a leading +:

That + allows non-fast-forward updates on your remote references, because their job is to mirror the server whatever state it is in. On the push side there is no + by default, and that is deliberate: permissive inwards, protective outwards.

The procedure is always the same, and it is exactly what you learned in the previous lesson:

With pull.ff only configured, step 3 in the form of git pull will stop with Not possible to fast-forward, because there is genuine divergence and Git will not decide for you. At that point you have to integrate explicitly.

What you must never do is what instinct — and the odd bit of ill-advised internet wisdom — suggests:

That overwrites the server's reference with your version, and Ana's commits are left orphaned. She will recover them from her own disk, true, but anyone who clones in the meantime will not see them, and confusion is guaranteed.

This section covers the cause and the basic way out. The full treatment of divergence — how to choose between merging, reapplying or rethinking; what to do if there are conflicts as well; how to get out of the tangled cases — is the subject of lesson 09-03: Resolving Divergence with the Remote. Take three ideas away from here:

1. The rejection is a protection, not a failure.
2. The cause is always the same: the remote has commits you do not have.
3. The default way out is to integrate first and push afterwards.

There are legitimate situations in which you need to overwrite a branch on the server: you have rewritten your own working branch (with the techniques of module 5) and the result is no longer a descendant of what is published. In those cases a normal push will quite rightly be rejected, and you have to force.

But there are two ways to force, and the difference between them can be a colleague's whole afternoon of work.

Git overwrites the server's reference without checking anything. If somebody had pushed something in the meantime, their commits are left orphaned.

Git compares the reference's current value on the server against your origin/feature/alphabetical-order, that is, against the latest photograph you hold. If they match, it overwrites. If they do not — because somebody has pushed since your last fetch — it rejects the push:

The word lease is well chosen: you were holding the reference in a particular state, and if that state has changed the contract is broken and nothing gets written.

The protection rests on your local remote reference. And that opens a hole:

If you fetch immediately beforehand, your origin/branch is updated with whatever your colleague has just pushed, the comparison matches and --force-with-lease happily accepts… overwriting precisely what the option was supposed to protect you from overwriting.

There are two ways to do it properly:

First: look before you force. A fetch followed by a deliberate inspection:

Second, and better: state explicitly which value you expect.

Here you depend on no photograph at all: you tell Git "only write if the server is exactly at 9d1e4b7". It is the safest form, and the one to use in scripts.

Since Git 2.30 there is also a complementary option:

It additionally checks that the commits on the server are included in what you are about to send — that is, that you have genuinely integrated them and not merely downloaded them.

1. Never force main, develop or any shared branch. If the team works on it, rewriting it forces everyone to sort out a mess. And that is exactly what the platforms' protected branches prevent.
2. Force only your own branches, working branches nobody else is using.
3. Always use --force-with-lease. Turn --force into a word you never type.
4. Tell the team if you force a branch somebody might have cloned.
5. If in doubt, do not force. A history with one merge commit too many has never killed anyone; a --force on main on a Friday very nearly has.

One alias helps make the good habit the most convenient one:

And a reassuring note, because there is no need to live in fear: if somebody forces and destroys commits, they can almost always be recovered. Whoever had them on their disk still has them; and on the server, the reflog or the platform's own tools will usually let you rescue them. It is a nuisance, not a catastrophe. Recovery is studied in lesson 09-04.

When a branch has been integrated, it has to be deleted in both places: in your repository (with git branch -d, lesson 03-06) and on the server.

Readable and hard to confuse. This is the one to use.

It does exactly the same thing, and now you can see why: it is the <source>:<destination> refspec with an empty source. You are sending "nothing" to that reference on the server, which removes it.

You will meet it in documentation and in old scripts, so it is worth recognising. But it is also worth knowing the risk: one space too many and you are deleting something you did not mean to. Compare:

One character between publishing and destroying. That is why --delete is better.

Deleting a branch on the server does not delete the references your colleagues hold. Each of them will have to clean up, as we saw in the previous lesson:

And if they also have the local branch, that is deleted separately:

Three different things again: the branch on the server, each person's remote reference and each person's local branch. The next lesson hammers that distinction home.

A warning: deleting a branch on the server can leave its commits with no reference reaching them. If that branch was not merged, those commits are at the mercy of the server's garbage collector. Check beforehand with git log --oneline main..origin/the-branch that there is nothing to lose.

A detail that surprises almost everyone the first time: git push does not send tags.

The tag has been created in your repository and there it stays. The default refspec covers branches only (refs/heads/*), not tags (refs/tags/*).

The ways to send them:

The difference between the last two matters:

--follow-tags is almost always the right option for daily use, and you can leave it configured:

And to delete a tag from the server, the same syntax as always:

What tags are, the difference between lightweight and annotated ones, how they are used to mark versions and how they fit into the release flow is the subject of lesson 05-05: Tagging Commits. Here we care only about the transport: that they do not travel by themselves, and which option sends them.

We close with the full team scenario.

Ana has main published already and two local branches still to share: docs/update-notes and fix/focus-after-delete.

Only main has a tracking branch (the square brackets). The other two do not exist on the server yet.

Note the last line: tracking has configured itself, with no -u. That is push.autoSetupRemote true from lesson 01-06 doing its job.

She did not even have to name the remote or the branch. The final state:

Ana's branches are on his disk as remote references, not as local branches. He can examine them without creating anything:

Carla does the same and decides to carry on with Ana's fix:

She works, commits and pushes:

This is the full cycle closed. Note the shape of that last line, different from the one on the first push:

• * [new branch] X -> X → a branch has been created on the server.
• 8a3f7c1..d5e9b2f X -> X → an existing branch has advanced from one commit to another, fast-forward.

The project that spent three modules shut inside a single laptop now circulates between three machines and three different operating systems.

Mistake 1: "I pushed and they cannot see my change". Ninety per cent of the time, the change was never committed. git push sends commits, not modified files. Check with git status and git log --oneline -3.

Mistake 2: answering a rejection with --force. A non-fast-forward rejection means the server has work you do not have. Forcing destroys it. The right answer is fetch + integrate + push. See 09-03.

Mistake 3: using --force instead of --force-with-lease. The first checks nothing; the second refuses if somebody has pushed since your last fetch. One costs no more to type than the other; make an alias.

Mistake 4: running fetch right before --force-with-lease. It cancels out the protection, because it updates the very reference Git compares against. Either look deliberately at what has arrived, or use the --force-with-lease=branch:hash form.

Mistake 5: forcing a shared branch. Rewriting main forces the whole team to sort out a mess they did not cause. Force only your own working branches.

Mistake 6: believing git push sends tags. It does not: the default refspec covers refs/heads/* only. Use --follow-tags or set push.followTags true.

Mistake 7: typing git push origin :branch without paying attention. One extra space between the : and the name changes the meaning entirely. Use --delete, which says what it does.

Mistake 8: deleting a branch from the server and expecting it to vanish from everyone else's repository. Each person has to run git fetch --prune. Set fetch.prune true across the team.

Tip 1: look before you push. git log --oneline origin/main..main shows you exactly which commits are about to go out. Ten seconds that stop you publishing a wip or a forgotten console.log.

Tip 2: run git fetch before you start, not before you push. That way you spot divergence while it is still cheap to resolve, instead of discovering it with the work already finished.

Tip 3: an alias for safe forcing.

Tip 4: check what push.default is set to. The value simple is the right one. If you work on a team with old configurations, make sure nobody is on matching.

Tip 5: --dry-run for a rehearsal.

It shows what the push would do without doing it. Useful with awkward refspecs or before a deletion.

Set up a bare server and a working repository. Then:

1. Make three commits and push with -u.
2. Show .git/config before and after, and point out which lines -u added.
3. Explain the full push output, line by line.
4. Make another commit and push without -u. What changes in the output, and why?
5. Check from the server that the references are where they should be, without cloning.

With one server and two clones (Ana and Bruno):

1. Both start from the same commit.
2. Ana commits and pushes.
3. Bruno commits (without fetching) and tries to push.
4. Capture the rejection message and explain exactly why it happened, drawing the graph.
5. Resolve it properly without forcing, and demonstrate that both sets of commits are still on the server.
6. Repeat the experiment resolving it with --force, and demonstrate that Ana's commit has vanished from the branch.

With a repository connected to a bare, achieve the following and explain each command:

1. Push your local branch feature/test to a server branch called experimental/test.
2. Push the state of a commit earlier than your branch tip to a server branch called review.
3. Push HEAD to main while on a detached HEAD.
4. Delete experimental/test from the server both possible ways.
5. Check the result with git ls-remote after each step.

Solution 1:

The new lines are the [branch "main"] section with remote and merge. That is all -u does: establish the tracking branch.

3. The output, line by line:

• Enumerating objects: 9 — Git has identified 9 objects to send: 3 commits + 3 trees + 3 blobs.
• Delta compression using up to 8 threads — it compresses in parallel, storing differences between similar objects.
• Writing objects: 100% (9/9), 782 bytes — the actual upload: 782 bytes.
• Total 9 (delta 1), reused 0 — of the 9 objects, 1 has been stored as a difference against another; none has been reused because the server was empty.
• To /tmp/ex-push/server.git — the destination.
• * [new branch] main -> main — the main branch has been created on the server. The asterisk and [new branch] mark the creation.
• branch 'main' set up to track 'origin/main' — the effect of -u.

Two differences, and both have an explanation:

• Plain git push was enough: tracking was already configured by the earlier -u, so Git knows which remote and which branch to send to.
• The result line no longer says [new branch] but 7d2f9a1..4c8e3b6: the branch already existed and moved from one commit to another. That two-dot range signals a fast-forward, exactly the notation we saw with fetch.

On top of that, only 3 new objects were sent instead of the initial 9: pushing is incremental.

Solution 2:

4. Why: both started from 5a1d8f3. Ana created 9e2f4a7 on top and published it; Bruno created 7d1f4b8 on top of the same 5a1d8f3. The graph:

For Bruno's push to be valid, 9e2f4a7 would have to be an ancestor of 7d1f4b8. It is not: they are sibling branches. If the server accepted the update, refs/heads/main would move to 7d1f4b8 and 9e2f4a7 would stop being reachable: Ana's commit would disappear from the project. Git prevents that.

You can check it formally:

If it is the same file, there will be a conflict (both added a line at the end of f.txt). It is resolved with what you learned in 03-05:

Nothing has been lost. Both pieces of work coexist, joined by a merge commit with two parents, exactly as in module 3.

That + and the (forced update) are the mark of the disaster:

Ana's commit is no longer on the branch. Anyone cloning now will not see it. It still exists as a loose object on the server — and certainly in Ana's repository — but no reference reaches it. Now compare with what would have happened using the safe option:

Rejected. The server was not where Bruno's photograph said it was, so the protection kicked in. That, in one line, is the reason never to type --force again.

Solution 3:

The <source>:<destination> refspec decouples the two names: on the left what I send, on the right what it is called over there.

Here the full form refs/heads/review is necessary: since the destination branch does not exist yet, Git cannot work out whether you want to create a branch or a tag. With the full name there is no ambiguity. And notice that the left-hand side is a hash, not a branch name: any expression that resolves to a commit will do.

HEAD resolves to the commit you are on, even with no branch pointing at it. It is the way to publish work from a detached HEAD without having to create a local branch first.

Both do the same thing. The second is the refspec with an empty source: sending "nothing" to that reference removes it. It is exactly the same syntax, taken to its limit.

main and from-detached remain; experimental/test and review have gone. And one important detail: this repository's local branches were untouched by either deletion.

With this lesson, the team's work flows in both directions. The essentials:

• git push sends objects and asks for a reference to be updated. It does not send your working tree, your index, your configuration or your other branches. Only what sits inside a commit travels.
• git push -u origin <branch>: -u writes the [branch "…"] section into .git/config and establishes the tracking branch. From then on, plain git push and git pull work and git status can report the gap. With push.autoSetupRemote true (lesson 01-06) you do not even need it.
• The push refspec uses the same syntax as the fetch one: source:destination, left where it comes from and right where it goes. It lets you push to a branch with a different name, push a specific commit or push HEAD.
• push.default simple pushes only the current branch. The old matching pushed every namesake and was a source of surprises: do not use it.
• A non-fast-forward rejection happens because the remote has commits you do not have. If Git accepted the push, those commits would stop being reachable and would disappear from the project. It is a protection, not a failure. The basic way out is fetch → integrate → push; the full treatment is in lesson 09-03.
• --force-with-lease versus --force: the first checks that the server is still where your remote reference says and rejects if somebody has pushed; the second overwrites without looking and can leave someone else's work orphaned. Always use the first, and do not fetch immediately beforehand (or use the --force-with-lease=branch:hash form). Never force shared branches.
• Deleting a branch from the server: git push origin --delete <branch>, or the old form git push origin :<branch> (a refspec with an empty source). Everyone else will have to run git fetch --prune for it to disappear from their references.
• Tags do not travel on their own: --tags sends them all, --follow-tags only the annotated ones reachable from what you are sending, which is usually what you want. Tags are covered in lesson 05-05.

You now know how to push and how to fetch. But along the way these lessons have thrown up messages we have not yet fully explained: "Your branch is ahead of 'origin/main' by 2 commits", "branch 'main' set up to track 'origin/main'", those square brackets in git branch -vv, and that git switch which creates a local branch from a remote one without being asked.

All of it points to the same concept: tracking branches. In lesson 04-06: Tracking Branches, which closes the module, we will see exactly what a branch's upstream is and where it lives in .git/config, we will settle once and for all the difference between main, origin/main and the server's main, and we will take apart how Git works out that "2 commits ahead". It is the lesson that ties every thread of the module together.