Git Push: Publishing Local Refs to a Remote Repository

Intermediate

Push sends local refs and required objects to another repository

`git push` updates one or more refs in another repository using local refs as the source, and transfers the objects needed for those refs when they are not already present there. The simplest explicit form is `git push origin main`: the local `main` ref is the source and the remote `main` ref is the destination.

git rev-parse HEAD
git push origin main
git ls-remote origin refs/heads/main

The local repository has a commit that the remote does not yet contain.?After the push, the selected remote ref can point to that commit.

An explicit refspec separates source from destination

A push refspec has the form `[+]src:dst`. A short branch name such as `main` normally expands to pushing the local `main` branch to the corresponding remote branch. A different destination can be selected explicitly, for example `main:review`. Fully qualified refs such as `refs/heads/main:refs/heads/release` remove ambiguity about both sides.

git push origin main
git push origin main:review
git push origin refs/heads/main:refs/heads/release

The local repository has refs/heads/main.?The remote repository can receive that object under refs/heads/review.

A successful push can advance the matching remote-tracking ref locally

When a push successfully updates a remote ref, Git can also update the corresponding remote-tracking ref in the pushing repository. This is not a second fetch: the local repository already knows the object and the ref update it just requested. Verify both the remote ref and the local `refs/remotes/origin/...` state instead of assuming push and fetch have identical side effects.

git rev-parse refs/remotes/origin/main
git push origin main
git rev-parse refs/remotes/origin/main

The local main ref was pushed successfully to origin/main.?The pushing repository can now have origin/main at the pushed commit.

Fast-forward safety protects an existing remote ref

By default, Git refuses to update an existing remote branch when the proposed new tip is not a descendant of the remote tip. This fast-forward check prevents an ordinary push from silently replacing remote history. The detailed non-fast-forward rejection and safe integration workflow is reserved for V447; here, verify the boundary itself.

git push origin main
# divergent remote state: push is rejected
git rev-parse refs/remotes/origin/main

The remote branch contains a commit that is not an ancestor of the local branch tip.?An ordinary push refuses to replace the remote tip.

Dry-run previews the push without updating the destination

`git push --dry-run` performs the push negotiation and reports what would be updated without actually sending the ref updates to the destination. It is useful for inspecting a refspec before making a real publication.

git push --dry-run origin main
git ls-remote origin refs/heads/main

A local branch is ready to be pushed.?The command can report the proposed update while leaving the destination unchanged.

Push does not change the current branch or working tree

Publishing is a ref-transfer operation. A successful push does not switch branches, create a commit, or rewrite the current branch tip. The local commit must already exist before it can be pushed. Likewise, push does not perform the integration work owned by `git pull`.

git rev-parse --abbrev-ref HEAD
git rev-parse HEAD
git push origin main
git rev-parse HEAD

HEAD identifies the current local branch tip before the push.?HEAD still identifies the same local commit after the push.

A new remote branch is a destination ref, not a local branch creation

A push can create a remote branch by naming a destination that does not yet exist, for example `git push origin topic`. The push transfers the local `topic` ref and creates the corresponding remote ref. It does not create a new local branch because the local branch already supplied the source.

git branch topic
git switch topic
git push origin topic
git ls-remote origin refs/heads/topic

The local topic branch points at a commit that the remote does not yet have under topic.?The remote can gain refs/heads/topic at that commit.

Do not confuse push with pull or fetch

The three operations have different directions and state effects: `git fetch` obtains remote state without integrating it into the current branch; `git pull` fetches and then integrates; `git push` publishes selected local refs to another repository. V445 owns the publishing operation. Upstream configuration that controls argument-less push/pull behavior is deliberately deferred to V446.

git fetch origin
git pull --ff-only origin main
git push origin main

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.