GIT: Remote repositories

11.1. What are remotes?

Git allows that you can synchronize your repository with more than one remote repository.

In the local repository you can address each remote repository by a shortcut. This shortcut is simply called remote. Such a remote repository point to another remote repository that can hosted on the Internet, locally or on the network.

You can specify properties for the remove, e.g. URL, branches to fetch or branches to push.

Think of remotes as shorter bookmarks for repositories. You can always connect to a remote repository if you know its URL and if you have access to it. Without remotes the user would have to type the URL for each and every command which communicates with another repository.

It is possible that users connect their individual repositories directly, but a typically Git workflow involves one or more remote repositories which are used to synchronize the individual repository. Typically the remote repository which is used for synchronization is located on a server which is always available.

A remote repository can also be hosted in the local file system.

11.2. Bare repositories

A remote repository on a server typically does not require a working tree. A Git repository without a working tree is called a bare repository. You can create such a repository with the --bare option. The command to create a new empty bare remote repository is displayed below.

# create a bare repository
git init --bare

By convention the name of a bare repository should end with the .git extension.

To create a bare Git repository in the Internet you would, for example, connect to your server via the SSH protocol or you use some Git hosting platform, e.g., GitHub.com.

11.3. Convert a Git repository to a bare repository

Converting a normal Git repository to a bare repository is not directly support by Git.

You can convert it manually by moving the content of the .git folder into the root of the repository and by removing all others files from the working tree. Afterwards you need to update the Git repository configuration with the git config core.bare true command.

As this is officially not supported, you should prefer cloning a repository with the --bare option.

11.4. Cloning a repository

The git clone command copies an existing Git repository. This copy is a working Git repository with the complete history of the cloned repository. It can be used completely isolated from the original repository.

Git supports several transport protocols to connect to other Git repositories; the native protocol for Git is also called git.

The following command clones an existing repository using the Git protocol. The Git protocol uses the port 9148 which might be blocked by firewalls.

# switch to a new directory
mkdir ~/online
cd ~/online

# clone online repository
git clone git://github.com/vogella/gitbook.git

If you have SSH access to a Git repository, you can also use the ssh protocol. The name preceding @ is the user name used for the SSH connection.

# clone online repository
git clone ssh://git@github.com/vogella/gitbook.git

# older syntax
git clone git@github.com:vogella/gitbook.git

Alternatively you could clone the same repository via the http protocol.

# the following will clone via HTTP
git clone http://github.com/vogella/gitbook.git

11.5. Adding remote repositories

If you clone a repository, Git implicitly creates a remote named origin by default. The origin remote links back to the cloned repository.

You can push changes to this repository via git push as Git uses origin as default. Of course, pushing to a remote repository requires write access to this repository.

You can add more remotes via the git remote add [name] [URL_to_Git_repo] command. For example, if you cloned the repository from above via the Git protocol, you could add a new remote with the name github_http for the http protocol via the following command.

# add the HTTPS protocol
git remote add github_http https://vogella@github.com/vogella/gitbook.git

11.6. Rename remote repositories

To rename an existing remote repository use the git remote rename command. This is demonstrated by the following listing.

# rename the existing remote repository from
# github_http to github_testing
git remote rename github_http github_testing

If you create a Git repository from scratch with the git init command, the origin remote is not created automatically.

11.7. Remote operations via HTTP

HTTP as Git protocol proxy support in Git It is possible to use the HTTP protocol to clone Git repositories. This is especially helpful if your firewall blocks everything except HTTP or HTTPS.

git clone http://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git

For secured SSL encrypted communication you should use the SSH or HTTPS protocol in order to guarantee security.

11.8. Using a proxy

Git also provides support for HTTP access via a proxy server. The following Git command could, for example, clone a repository via HTTP and a proxy. You can either set the proxy variable in general for all applications or set it only for Git.

The following listing configures the proxy via environment variables.

# Linux and Mac
export http_proxy=http://proxy:8080
export https_proxy=https://proxy:8443

# Windows
set http_proxy http://proxy:8080
set https_proxy http://proxy:8080

git clone http://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git

The following listing configures the proxy via Git config settings.

# set proxy for git globally
git config --global http.proxy http://proxy:8080
# to check the proxy settings
git config --get http.proxy
# just in case you need to you can also revoke the proxy settings
git config --global --unset http.proxy

Git is able to store different proxy configurations for different domains, see core.gitProxy in Git config manpage.

11.9. Adding a remote repository

You add as many remotes to your repository as desired. For this you use the git remote add command.

You created a new Git repository from scratch earlier. Use the following command to add a remote to your new bare repository using the origin name.

# add ../remote-repository.git with the name origin
git remote add origin ../remote-repository.git

11.10. Synchronizing with remote repositories

You can synchronize your local Git repository with remote repositories. These commands are covered in detail in later sections but the following command demonstrates how you can send changes to your remote repository.

# do some changes
echo "I added a remote repo" > test02

# commit
git commit -a -m "This is a test for the new remote origin"

# to push use the command:
# git push [target]
# default for [target] is origin
git push origin

11.11. Show the existing remotes

To see the existing definitions of the remote repositories, use the following command.

# show the details of the remote repo called origin
git remote show origin

To see the details of the remotes, e.g., the URL use the following command.

# show the existing defined remotes
git remote

# show details about the remotes
git remote -v

11.12. Push changes to another repository

The git push command allows you to send data to other repositories. By default it sends data from your current branch to the same branch of the remote repository.

By default you can only push to bare repositories (repositories without working tree). Also you can only push a change to a remote repository which results in a fast-forward merge. 

11.13. Pull changes from a remote repository

The git pull command allows you to get the latest changes from another repository for the current branch.

The git pull command is actually a shortcut for git fetch followed by the git merge or the git rebase command depending on your configuration. In Avoid merge commits for pulling you configured your Git repository so that git pull is a fetch followed by a rebase.