HOWTO · Git

How to Push and Track a New Local Git Branch to a Remote Repository

Learn how to push and track a new local Git branch to a remote repository with ease. This step-by-step guide covers creating a branch, pushing it, and managing tracking relationships, essential for effective collaboration and code management. Perfect for developers looking to enhance their Git skills.

On this page

To publish a new local branch, create or select the branch, commit the work you want to share, then push it while setting its upstream. The upstream records which remote branch this local branch follows, so later pushes can use the shorter command git push.

Creating a New Local Branch

A branch is a movable name for a commit. Creating one starts it at the commit currently checked out; it does not copy or transfer commits. Create and switch in one step with git switch -c my-feature-branch. The older git checkout -b my-feature-branch does the same. To create a branch without switching to it, use git branch my-feature-branch, then switch with git switch my-feature-branch.

Make and commit the changes on the branch before pushing. For example, stage the intended files with git add <paths> and create a commit with git commit -m "Describe the change". A push publishes commits reachable from the branch that the remote does not yet have; uncommitted working-tree changes are not sent.

Pushing the Local Branch to a Remote

Push the current branch and set its upstream in one command:

set -eu
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT

git init --quiet "$work/repo"
git init --quiet --bare "$work/origin.git"
cd "$work/repo"
git config user.name 'Example User'
git config user.email 'example@example.com'
git remote add origin "$work/origin.git"
printf 'Starting point\n' > README.md
git add README.md
git commit --quiet -m 'Add starting point'
git switch --quiet -c my-feature-branch
printf 'Feature work\n' > feature.txt
git add feature.txt
git commit --quiet -m 'Add feature work'
git push --quiet --set-upstream origin my-feature-branch
printf '%s\n' 'Pushed my-feature-branch to origin and set its upstream.'

This self-contained example creates a local bare repository as the remote, so it demonstrates a real push without contacting a hosting service. In your project, origin is only a common remote name; substitute the name shown by git remote -v if your remote has another name. The -u option is shorthand for --set-upstream. It configures the local branch to track the remote branch created by this push. This relationship is also used by commands such as git pull.

Verifying the Upstream Tracking Relationship

Run git branch -vv to see local branches and their upstreams. On the current branch, look for a bracketed name such as [origin/my-feature-branch] beside the local branch name. That indicates the configured upstream. The commit hash and ahead/behind counts in the listing describe how the local branch compares with its upstream; they do not replace reviewing the commits you intend to share.

If the branch name is not the one you expected, check the current branch with git branch --show-current. Check configured remote names and URLs with git remote -v, then inspect tracking configuration with git branch -vv. These commands help distinguish a wrong current branch from a remote-name mismatch before you push.

Pushing Later Changes

After making and committing additional changes on the tracked branch, run git push. Git uses that branch’s configured upstream, so you do not need to repeat the remote and branch names. If you have not set an upstream, use the first-push form again with the correct remote and branch: git push --set-upstream origin my-feature-branch.

Common Problems and Their Fixes

  • The remote name is unknown. List remotes with git remote -v. Use the name it shows in place of origin, or configure a remote if the repository has none.
  • The wrong branch would be pushed. Check git branch --show-current and switch to the intended branch before pushing. You can also name the source branch explicitly, but verify that it is the branch containing the commits you mean to publish.
  • The push is rejected because the remote branch has commits you lack. Fetch and inspect the remote changes, then integrate them according to your project’s workflow before trying again. Do not treat force-pushing as a routine fix: it can overwrite remote history used by collaborators.
  • A later git push has no upstream. Set it with git push --set-upstream <remote> <branch>, replacing both placeholders with the actual remote and local branch names.