git push | Pushing changes to a remote repository
Table of Contents
- What is Git Push?
- How to use Git Push – Step by Step Instructions
- Adding a Git remote
- After Push
- Git push options
- Git Push vs. Git Fetch
- Git Push vs. Git Pull
- Git Push vs. Git Remote
- Can Git Push Be Reversed?
- Next Steps
Programmers often use version control systems (VCS) like Git for collaborating on coding projects. Because Git stores your code and projects in a repository or "repo," you can maintain an accurate history of your project and view the changes that have taken place in your code base.
Once you’ve made changes in your local repository, like adding new features or fixing bugs, you may want to push these changes to the remote repository hosted on a site like GitHub or BitBucket. Updating a remote repository in this manner uses the
git push command.
Continue reading if you’d like to learn more about git push, including a step-by-step how-to guide for git push and how git push differs from
git merge and other commands. Let’s get started!
What is Git Push?
Git push is a command to upload content from your local repository to a remote repository. By using Git push, you can keep other developers in your team up to date on all the changes you have made to the codebase.
Git push is a helpful command for syncing your local changes to a remote repository. This command is essential for developers working on basic projects and larger projects with other collaborators. When you’re finished adding a feature or fixing a bug, you can push all your changes to the remote repository so other collaborators can see the changes.
By integrating changes into the code base often, your team can continually test the code and catch merge conflicts and bugs faster. Once you have pushed your changes, your colleagues can pull your latest edits and build upon them.
How to use Git Push – Step by Step Instructions
Let’s break down the git push command by looking at this example step-by-step:
Select a Git Repository to Push to
Before you can push changes to a remote repository, you need to identify the path to the specific remote repository you want to link to. If you’ve cloned your repository or already synched your local remote repository, the remote is already identified and will be the default when using the git push command.
The default remote repository can be referred to using the name
origin. In this case, the git push origin command will come in handy as the default remote git push option.
Push Authentication and Git Credential Manager
You may encounter an authentication requirement when working with remote repositories, especially when working on private or enterprise projects.
Repositories may be protected over HTTPS with a username or password. These credentials can be embedded into the repository URL (https://
As a part of Git Credential Manager, repositories may also be protected with SSH keys. SSH keys provide authentication without requiring collaborators to remember a password. A key can be revoked if the credentials are compromised.
Now that you understand a bit about Git's options for credentials, we can continue with the example.
Adding a Git remote
git remote add command to update a remote repository link, which takes two arguments, the remote name and the remote URL:
$ git remote add origin https://github.com/git-test/test.git
Run a quick
git pull to ensure your local repo is synchronized to the current remote, along with specifying the branch to pull from, in this case,
$ git pull origin master
Now, you are ready to push to the remote repository using the
git push <remote> <branch> format:
$ git push origin master
Git remote rejected changes - pull before push
If you encounter the following error message when attempting to git push, your local branch is either not synced or updated:
! [rejected] master -> master (fetch first)
error: failed to push some refs to 'https://github.com/git-test-/test.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
The issue, as stated, is that Updates were rejected because the remote contains work that you do not have locally.
This means a colleague has pushed a commit to the remote repository since you last ran the git pull command. Git does not allow conflicts on a remote repository to ensure it remains in a healthy state. Any push requests that require a three-way merge instead of a fast-forward merge are automatically rejected.
By far, the most common option is to take the suggestion in the error message: You may want first to integrate the remote changes (e.g., 'git pull ...') before pushing again.
You can do this by simply running the
git pull command, which will both remote git fetch the commits down to your local repo and merge them into your local copy of the branch.
Now that your local branch has integrated the changes from the remote repository, you can safely git push again and won't get the error above.
Alternatively, if you aren't concerned about losing changes on the remote since your last git pull, you can use git push --force (with the force option).
It is usually bad practice to rewrite or overwrite history that has already been pushed to the remote repository. A last resort, it is usually avoided unless there is no other option. So keep that in mind and be very careful using the git push --force or -f flag.
If you've decided that Git force pushing is necessary, you can use the
git push --force or
git push -f flag. This overrides Git’s safety feature and should be used with extreme caution. Any divergences (commits from other colleagues) will be deleted and lost if you haven’t pulled from the repository in a while.
In most situations, force pushing is a bad idea. The only appropriate situation for using
git push --force is when you have just pushed and need to change and rapidly fix those new commits. But first, communicate with your colleagues to ensure no one has pulled those commits. Here is an example of force pushing in action:
$ git push <remote> <branch name> --force
--force-with-lease flag offers a safer alternative if you’re convinced you need to force push. Any remote commits that have been added since your last pull will not be deleted if you use this flag. This protects your teammates' hard work so you don’t accidentally delete their commits.
$ git push <remote><branch name> --force-with-lease
Once you’ve completed a git push, you can safely return to your local development workflow as normal, moving new work from the working directory to the staging area to the central repository. From there, it can be pushed to the remote repository as the cycle continues.
Git push options
Let’s take a look at other common options and git push flags that were not covered above:
git push for each branch. Alternatively, you can use the
git push --all flag to push all commits on all branches to the remote repository.
Git Push vs. Git Fetch
Essentially, git push is the opposite of git fetch. Fetching downloads commits to your local repository while pushing uploads commits to the remote repository. You would turn to git fetch when you want to get the commits made on a remote repository or remote branch since the last time you pulled.
Git Push vs. Git Pull
Most new Git users think of git push and pull as opposites because data flows in opposite directions across the network (or "over the wire," as technical folks like to call it).
git pull actually combines the git fetch command and the Git merge command into one convenient command. So as mentioned in the previous section
git fetch is better thought of as the "opposite" of
git push, since it simply downloads commits and other Git objects into the local repository while pushing uploads them to the remote.
Git Push vs. Git Remote
git remote command is a helpful command in any developer’s workflow. The main function of this command is creating, viewing, or deleting connections between repositories. Applying the git remote command is the first step in the git push process if you haven’t linked your local repository to a specific remote repository.
Can Git Push Be Reversed?
As mentioned above, Git pushes are not always easy to reverse or undo. When working on a basic project, reversing commits can be an option in your workflow, but it becomes difficult on bigger teams. Look for better options to undo Git changes that don't involve a need to rewrite Git history, such as the
git revert command.
In this article, we looked closely at git push, an essential Git command for team collaboration.
We explained what git push does and how to use it. Then we discussed how to choose the remote to push to and work with push authentication and Git's credential manager and add a new remote repository.
Next, we learned how to deal with rejected push changes, usually by pulling and merging before pushing. We saw that force pushing could be performed in certain exceptional cases, but this will overwrite remote changes since you last pulled from the remote repository.
Finally, we touched on some standard Git push options and explained the difference between git push and other similar Git commands.
It’s an essential part of a good workflow to regularly sync your changes to the remote repository to ensure your work is updated and available to your colleagues and vice versa.
If you're interested in learning more about how Git works under the hood, check out our Baby Git Guidebook for Developers, which dives into Git's code in an accessible way. We wrote it for curious developers to learn how Git works at the code level. To do this, we documented the first version of Git's code and discuss it in detail.
We hope you enjoyed this post! Feel free to shoot me an email at email@example.com with any questions or comments.
- Git SCM Docs, Git credentials - https://git-scm.com/docs/gitcredentials
- Git SCM Docs, Git SSH keys - https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key
Recommended product: Decoding Git Guidebook for Developers