git-push

Send local changes in the current branch to its default remote counterpart

$ git push

$ git push [remote_name] [local_branch]

$ git push [[-u|--set-upstream]] [remote_name] [local_branch]

$ git push [remote_name] [local_branch]:[remote_branch]

$ git push --all [remote_name]

$ git push [remote_name] [[-d|--delete]] [remote_branch]

$ git push --prune [remote_name]

$ git push --tags

git push [options] [repository [refspec...]]
git push --dry-run | --porcelain

repository
    The remote repository name to push to (e.g., origin). If omitted, the default remote for the current branch is used.

refspec...
    Specifies what to push from your local repository to the remote. Can be a branch name (e.g., main), or a detailed mapping like local_ref:remote_ref. Multiple refspecs can be provided.

-f, --force
    Forces the update even if the remote history has diverged (non-fast-forward update). Use with extreme caution, as it can overwrite history on the remote!

--force-with-lease[=]
    A safer alternative to --force. It only forces the push if the remote branch has not been updated since the last fetch, preventing accidental overwrites by others.

-u, --set-upstream
    For every branch that is successfully pushed, add upstream (tracking) reference, used by argument-less git pull and other commands.

--all
    Pushes all branches (i.e., all refs/heads/ references) to the remote repository.

--tags
    Pushes all local tags (i.e., all refs/tags/ references) to the remote repository.

--dry-run, -n
    Shows what would happen without actually pushing the changes. Useful for previewing potential updates.

--delete
    Deletes the specified remote branches or tags. The syntax is :remote_branch_name or --delete remote_branch_name.

--porcelain
    Produces machine-readable output for programmatic parsing.

git push is a fundamental Git command used to upload local repository content to a remote repository. It transfers committed changes from your local branches and tags to a specified remote, typically origin. When you execute git push, Git examines your local branches and their corresponding upstream branches on the remote. It then attempts to update the remote references, ensuring that all necessary objects (commits, trees, blobs) are also transferred.

The default behavior prevents "non-fast-forward" updates, meaning it will reject pushes if your local branch history has diverged from the remote's history, requiring you to first git pull to merge or rebase. Common uses include sharing new commits, branches, or tags with collaborators, and deploying code. git push is essential for collaborative workflows, allowing team members to synchronize their work and maintain a shared version of the project's history.

Using --force or -f can overwrite remote history, potentially causing lost work or severe issues for collaborators if they have based their work on the overwritten history. Always prefer --force-with-lease if you must force, as it checks if the remote branch has been updated by others before forcing. Non-fast-forward updates occur when your local history has diverged from the remote; pushing these without force requires a merge or rebase first. Improper use can lead to a messy repository history.

The push.default configuration variable dictates the default behavior of git push when no refspec is explicitly provided. Common values include:
simple: Pushes the current branch to its upstream branch if their names match. This is the recommended default since Git 2.0.
upstream: Pushes the current branch to its upstream branch, regardless of name.
current: Pushes the current branch to a branch of the same name on the remote.
matching: Pushes all local branches that have a matching branch on the remote. This was the default before Git 2.0 and is generally discouraged.
nothing: Disables pushing without a refspec.

A refspec specifies what git push should push from your local repository to the remote. It typically follows the format [+]<src>[:<dst>].
src: The source reference in your local repository (e.g., a branch name like main or HEAD, or refs/heads/feature).
dst: The destination reference on the remote repository (e.g., a branch name like main, or refs/heads/feature). If dst is omitted, it defaults to the same name as src.
The + prefix allows a non-fast-forward update for that specific refspec, similar to --force but more granular. Examples:
main: Pushes local main to remote main.
feature:new-feature: Pushes local feature to remote new-feature.
:feature: Deletes the remote feature branch.

The git push command has been a core component of Git since its inception in 2005. Its functionality for updating remote repositories is fundamental to collaborative Git workflows. A significant evolution in its usage involved the introduction and changes to the push.default configuration option. Initially, the default behavior might have varied or been less explicit. Over time, defaults like matching (pushing all matching branches) evolved to safer and more explicit defaults like simple (pushing the current branch only if its upstream branch matches and exists on the remote), to prevent accidental pushes of multiple branches. This reflects a maturation towards more explicit and controlled remote interactions.

git-pull(1), git-fetch(1), git-remote(1), git-config(1), git-status(1)