Working with Remote Repositories

Sometimes we end up with repositories that take a bit to type.

 git://example.com/var/repositories/eng/sateam/repos/pocus

Git allows you to configure aliases to these repositories to make the names shorter and easier to remember. To add an alias you need to add a few lines to your .gitconfig file. If you're on Linux or Mac OS X, it is located in your home directory. Remember, it's a hidden file so it won't show up in your file browser by default.

If you're in Windows, the file is located in your username's directory in the Documents and Settings directory.

Once you've located the file, add the following to it:

	[url "git://example.com/var/repositories/eng/sateam/repos"]
	insteadOf = sateam:

Now you would just clone sateam:pocus. The value after insteadOf can be any value you want to use as short-hand for referencing remote repositories.

With the the git protocol, SSH (Secure Shell), and HTTP/HTTPS, it may seem like there's a lot of choices to determine which networking option you should use. Choosing one is straight-forward though. If you value:

Speed above all else: you want the git protocol
Security above all else: SSH is the protocol for you
Not having to reconfigure restrictive firewalls: HTTP or HTTPS is the way to go.

Authentication is an issue. The git protocol is anonymous, so allowing a repository to be written using it means anyone can write to your repository. SSH requires proper user permissions for your repository to work and HTTP/HTTPS requires a working WebDAV server.

You're not locked into just one protocol, though. You can mix and match protocols to get an optimal balance of speed and security.

For the my personal Git repository, I use a mixture of SSH and git. To write to my server, I SSH keys for authenticating users and allow anonymous reads via the git protocol. Though the configuration may sound complex, it's made simple by a program called Gitosis, which we'll cover in [XREF: sec.gitosis].

Cloning a Remote Repository

Sharing your work with other developers means you need a remote repository. The easiest way to work with a remote repository is to just clone an existing repository. Cloning creates a local copy of the remote repository.

For projects that are already in progress, this is the normal route, but it isn't the only one. A remote repository can be configured later if you start working on a project by yourself and then need to share it. See the sidebar "Adding a Remote Repository Later" for details.

Your local copy created by cloning works just like it would if you had created it yourself using git init like we talked about in Section Creating a Local Repository, the only difference is that you get the history of the repository up to the point you created the clone.

You use the git clone command any time you want to clone a repository to work with. In its simplest form, it takes only one parameter: the name of the repository you're cloning. Let's clone the hocus repository from my public repository, git://github.com/tswicegood/hocus.git

	prompt> cd /work
	prompt> git clone git://git.gitbook.com/hocus.git
	Initialized empty Git repository in /work/hocus/.git/
	remote: Counting objects: 4, done.
	remote: Compressing objects: 100% (3/3), done.
	remote: Total 4 (delta 0), reused 0 (delta 0)
	Receiving objects: 100% (4/4), done.

This downloads the repository stored on the server and sets up a local copy of it in the hocus directory. You can change into that directory and see the contents, the two files we created earlier.

	prompt> cd hocus
	prompt> ls
	days.txt numbers.txt

You now have a fully functioning clone of the remote repository that is setup to track both your own local changes and those you pull from the remote server.

Keeping Up-To-Date

Cloning gets you the history of a repository up to the point you clone it, but other developers will still be making changes and updating the repository with those changes after you clone it.

You need to pull those changes from the remote repository. You do this by using the command git pull. Pulling the changes fetches them from the remote repository and merges them into you local branch.

	prompt> git pull origin
	remote: Counting objects: 5, done.
	remote: Compressing objects: 100% (3/3), done.
	remote: Total 3 (delta 0), reused 0 (delta 0)
	Unpacking objects: 100% (3/3), done.
	From /work/hocus/
	40264dd..d48c920 master -> origin/master
	Updating 40264dd..d48c920
	Fast forward
	days.txt \| 2 +-
	1 files changed, 1 insertions(+), 1 deletions(-)

This syncs you with your origin. The term origin refers to the name of a repository. Since Git is distributed, you may be pulling from multiple repositories. Their “names” are just short-hand for the full repository URL.

The origin repository is the default repository that Git pulls from, but Git is distributed so you don't have to always pull from just one source. You can specify another repository to pull from, but its best to pull from other repositories with a common history. Otherwise, you run the risk of having conflicts run rampant as the two projects try to merge. For more information on configuring new named repositories, check [XREF: sec.common.remote].

You can provide the optional <repository> <branch-name> to git pull to just pull the changes from that repository's branch. Most of the time, you want to sync with someone's HEAD, or current development, so just use <repository> HEAD

	prompt> git pull ../alt_hocus/ HEAD
	Updating 5ef8232..d49d1e5
	Fast forward
	days.txt \| 4 ++--
	months.txt \| 4 ++++
	2 files changed, 6 insertions(+), 2 deletions(-)
	create mode 100644 months.txt

This pulls the latest changes from a second repository called alt_hocus that is located at ../alt_hocus/ in my file system.

You may run into conflicts when you pull changes. Git tries to merge the changes as best it can, but when in doubt, it lets you choose which code is correct. Next up, we'll cover handling those conflicts.

Extracted from Chapter 8Working with Remote Repositories

Cloning a Remote Repository

Keeping Up-To-Date