Live streamJoin us for "State of code review 2024" on July 18thRegister today

How to upload files to a git repository with git push

Greg Foster
Greg Foster
Graphite software engineer


This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.

The git push command uploads local repository content to a remote repository.

This guide walks you through various git push use cases, including pushing commits, branches, and tags, as well as some more complex usages of the command.

Pushing changes to a remote repository:

  • After committing your changes locally with git commit, use git push to upload your changes to the remote repository.

    git push <remote-name> <branch-name>

  • <remote-name> is typically origin for the default remote, and <branch-name> is the name of your current branch.

  • If you're pushing to a branch that's already set up to track a remote branch (i.e. if it’s a branch you’ve pushed to before), you can simply use:

    git push

You can also push tags that you’ve created locally to a remote repository. A Git tag is a marker used to point to a specific commit in the history of a repository, often used to mark release points like v1.0.**

  • To push a single tag, run:

    git push <remote-name> <tag-name>

  • To push all of your local tags at once, run:

    git push <remote-name> --tags

    This will ensure your remote repository has a record of all your tags. Once pushed, others can pull them down when they update their own local repositories.

If you want to push changes to a specific remote branch:

  • Use the following command format:

    git push <remote-name> <local-branch-name>:<remote-branch-name>

    This is particularly useful if you want to push changes from your local branch to a differently named branch on the remote.

You can also force a remote repository to accept your local changes, even if it means those changes would otherwise conflict. This is useful when you need to correct previous commits that have already been pushed to a remote repository, such as after squashing commits or rewriting commit history with a rebase. However, it should be used cautiously, as it can overwrite changes in the remote repository, potentially causing work to be lost if not properly coordinated with team members.

This is a destructive operation as it will overwrite any history that is different from your local branch’s state, so use with caution.

  • To force push to a specific remote branch, use the -force option:

    git push <remote-name> <branch-name> --force

  • Or, for a safer option that prevents overwriting other collaborators' work, use -force-with-lease:

    git push <remote-name> <branch-name> --force-with-lease

    The --force-with-lease option provides a safer alternative to --force by ensuring that your local copy of the branch is up to date with the remote branch before applying the force push. This prevents accidentally overwriting others' work by only allowing the force push if the remote branch's current state matches what you expect, based on your local repository's knowledge of that branch.

  • To publish a new local branch to the remote repository, use the git push command and set the upstream (tracking) relationship with the -u option:

    git push -u <remote-name> <new-branch-name>

  • This command pushes your new branch to the remote repository and sets it to track the remote branch.

  • Change the default push branch: To change the default push behavior when you're frequently pushing to a different branch than your current one, you can use the git config command to adjust your push settings. Specifically, you can set the push.default configuration to match your preferred push behavior.

    1. Open your terminal or Git Bash.

    2. Run the following git config command to set the push default behavior:

      git config --global push.default <setting>

      Replace <setting> with one of the following options based on your needs:

      • current - push the current branch to update a branch with the same name on the receiving end.

      • upstream - push the current branch to its upstream branch.

      • simple (default in newer Git versions) - push the current branch to its upstream branch, but refuse to push if the upstream branch's name is different from the local one.

      • matching - push all branches that have the same name on both ends. This was the default in older versions of Git.

      • nothing - disable automatic pushing. You must manually specify which branch to push.

    For instance, if you want Git to always push the current branch to its upstream branch regardless of its name, you would use:

    git config --global push.default upstream

    This configuration change will apply globally to all your Git repositories. If you want to make the configuration change apply to a single repository only, navigate to that repository's directory in your terminal or Git Bash, and run the command without the --global flag.

  • Pushing All Branches: Use git push <remote-name> --all to push all of your local branches to the specified remote.

  • Use of Git Bash and command line: The git push command works the same in Git Bash on Windows and the terminal on Linux or Mac. Ensure you've navigated to your repository's directory before executing push commands.

  • Git push explained: When you run the git push command, the output will vary depending on the specifics of what you're pushing and the state of your remote repository. Here's an example of typical output you might see when pushing a local branch to a remote repository:
$ git push origin master
Counting objects: 9, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 528 bytes | 528.00 KiB/s, done.
Total 5 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
a1b2c3d..e4f5g6h master -> master

This output indicates several key things:

  • The number of objects being counted and compressed for the push.

  • The progress of compressing and writing objects.

  • The processing of delta compression on the remote side.

  • The final line shows the hash values of the commits from the local branch (a1b2c3d) and the remote branch (e4f5g6h) before and after the push, alongside the branch name (master), indicating a successful push to the remote repository.

  • Always pull before pushing: To minimize merge conflicts between your local state and the state of the remote repository and ensure you're not overwriting others' work, always pull the latest changes from your branch before pushing.

  • Use force push sparingly: Force pushing can overwrite history on the remote branch, potentially causing issues for other collaborators. Always communicate with your team before force pushing.

For further reading on the git push command see the official git documentation.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2