Create a remote Git branch

Publish a local branch with tracking, create a branch from an existing remote-tracking ref, and verify the result without confusing local and server state.

Best practices
Illustration of Git branches and version history

The usual command-line workflow is to create a local branch, then push it:

git switch -c feature/pay
# Make and commit your changes.
git push -u origin feature/pay

A successful push creates the remote branch if it does not already exist and records origin/feature/pay as the local branch's upstream. Repository permissions or branch rules may reject creation. The branch must point to a commit; an unborn branch in a brand-new repository cannot be pushed before its first commit.

Publish an existing branch

git push -u origin existing-branch

The branch does not have to be checked out for this explicit push. If a remote branch with that name already exists, this command attempts to update it, subject to normal fast-forward and server checks.

You can also create a server branch from a fetched commit without creating a corresponding local branch:

git fetch origin
git push origin origin/develop:refs/heads/feature/pay

Here the source is your local origin/develop snapshot. Fetch it first and verify that it is the intended starting point.

Use a hosting-platform interface

GitHub and GitLab also provide branch-creation interfaces. This is another valid way to create a branch on the server; a local push is not the only possibility. After creating it there:

git fetch origin
git switch --track origin/feature/pay

Use this switch form when a local branch with that name does not already exist.

Verify tracking and the server ref

git branch -r
git branch -vv
git ls-remote --heads origin refs/heads/feature/pay

The first two inspect local refs and configuration. ls-remote queries the server's advertised ref. If you forgot -u, you can set tracking without another push:

git branch --set-upstream-to=origin/feature/pay feature/pay

That remote-tracking ref must exist locally. Repeating git push -u is also possible, but it is a real push that can publish additional local commits or invoke server hooks; it is not always a no-op.

Use a different destination name or remove a mistake

git push -u origin local-name:refs/heads/remote-name

Different names are valid, but the default push.default=simple policy can reject a later plain push when the upstream name differs. Keep using an explicit mapping or choose an appropriate policy.

To remove a mistakenly created server branch, use git push origin --delete feature/pay after checking that no one needs it. The local branch is separate; switch away from it before considering git branch -d feature/pay.

See git-push and git-branch.

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting