Chapter 23 Remotes
Remote repositories are versions of your project that are hosted on the Internet or another network. A single project can have 1, 2 or even hundreds of remotes. You pull others changes from remotes and push your changes to remotes.
23.1 Listing what remotes exist
git remote lists the names of available remotes, but usually it is more
useful to see what URLs each note corresponds to (with
## origin https://github.com/jennybc/happy-git-with-r (fetch) ## origin https://github.com/jennybc/happy-git-with-r (push)
23.2 Adding a new remote
git clone automatically adds a new remote, so often you do not need to do
this manually initially. However, after the initial clone, it is often useful to
add additional remotes.
git remote add to add a new remote
git remote add happygit https://github.com/jennybc/happy-git-with-r.git
Note: when you add a remote you give it a nickname (here
happygit), which you can use in git commands in place of the entire URL.
git fetch happygit
Sidebar on nicknames: there is a strong convention to use
origin as the nickname of your main remote. At this point, it is common for the main remote of a repo to be hosted on GitHub (or GitLab or Bitbucket). It is tempting to use a more descriptive nickname (such as
github), but you might find that following convention is worth it. It makes your setup easier for others to understand and for you to transfer information that you read in documentation, on Stack Overflow, or in blogs.
A common reason to add a second remote is when you have done a “fork and clone” of a repo and your personal copy is set up as the
origin remote. Eventually you will want to pull changes from the original repository. It is common to use
upstream as the nickname for this remote.
23.3 Fetching data from remotes
To get new data from a remote use
git fetch <remote_name>. This retrieves the
data locally, but importantly it does not change the state of your repository
or your files in any way. To incorporate the data into your repository, you need to merge or rebase your project with the remote project.
# Fetch the data git fetch happygit # Now merge it with our local master git merge happygit/master master # git pull is a shortcut which does the above in one command git pull happygit master
For more detail on
git pull workflows, see 28.
23.4 Pushing to remotes
git push <remote> <branch> to push your local changes to the
branch on the
# push my local changes to the origin remote's master branch git push origin master # push my local changes to the happygit remote's test branch git push happygit test
23.5 Renaming and changing remotes
git remote rename can be used to rename a remote
git remote rename happygit hg
git remote set-url can be used to change the URL for a remote. This is
sometimes useful if you initially set up a remote using https, but now want to
use the SSH URL instead (or vise versa).
git remote set-url happygit email@example.com:jennybc/happy-git-with-r.git
One fairly common workflow is you initially cloned a repository on GitHub
locally (without forking it), but now want to create your own fork and push
changes to it. As described earlier, it is common to call the main repository
upstream and to call your fork
origin. So, in this case, you need to first rename the existing remote (from
upstream). Then add your fork as a new remote, with the name
git remote rename origin upstream git remote add origin firstname.lastname@example.org:jimhester/happy-git-with-r.git
23.6 Upstream tracking branches
It is possible to set the branch on the remote each of your local remotes
git clone sets this up automatically, so for your own master
branch this is not something you will run into. However by default if you
create a new branch and try to push to it you will see something like this.
git checkout -b mybranch git push # fatal: The current branch foo has no upstream branch. # To push the current branch and set the remote as upstream, use # # git push --set-upstream origin foo
You can do as the error message says and explicitly set the upstream branch
--set-upstream. However I would recommend instead changing the default
push to automatically set the upstream branch to the branch with
the same name on the remote.
You can do this by changing the git
push.default option to
git config --global push.default current
See also Working with Remotes: