/ Git Version Control

Keep your code organized and versioned (with Git and Gitosis)

I do a lot of prototyping and testing with new technologies at home and this tends to leave a trail of lot of small code projects which I work on and off with. To manage these projects I have needed some kind of repository to keep them in to prevent them from accidentally being modifed or removed as well as being versioned while developing.

However, these projects are usually small and not ready for common usage so I typically haven't wanted to use some external service to manage them in. This pretty much only have left one option, hosting them on some version control system in my home network. For a couple of years now I have been using subversion and while it has worked pretty nicely for me in the past, merging and branching has always been the achilles heel of the system.

Here is where git comes in. Git simplifies this quite a bit with it's distributed approach and branching and merging is really made simple. Being able to branch a project locally while assessing different approaches or technologies for a project really helps keep the main branch clean.

But while using local clones of the git repository is great while developing I still want to store them in a centralized backed up location where I have access to it from all my computers. So I started looking for a git server to handle this for me. Now the obvious solution for many probably would be to put their projects on a service like GitHub, and while a great service, I firstly don't want to put all my undfinished code out in the open before it is ready for the public and secondly not all the code I do might not be open source, not yet anyway.

So, in my quest to find a decent Git server to install on my local home server running Fedora 14 I stumbled upon Gitosis http://eagain.net/gitweb/?p=gitosis.git .

Gitosis is a marvellous peace of software written by Tommi Virtanen which allows you to manage your git repositories on a remote server over SSH. While your git repositories are managed under one administrative user on the server side client users can be configured using SSH key authentication. This makes it easy to setup new users without needing to setup shell access for the users.

Installing Gitosis

I am now going to show you have you can set up your own Gitosis server to manage your projects with. Since I did this on Fedora 14 I am going to show how it was done there, the installation on other distributions might vary.

Installing gitosis is really easy, just fire up your package manager, I use yum but any graphical also suffices, and install the following packages to your remote server:

su -c "yum install git gitosis gitweb"

Once it completes you are all set for the next step.

As I mentioned erlier, gitosis uses only one user to manage all the repositories so the first thing we need to to is create that user on the remote server which hosts gitosis. So, I ssh into the server and create a user named "git" for this purpose and give him a password.

su -c "adduser git"
su -c "passwd git"

Once you have the user set up lets make him the administrative user. Every user that uses gitosis need to have an ssh key which he is identified by. Creating the key is easy, just issue the following when logged in as a normal user on the remote system (not the git user):

ssh-keygen -t rsa -f /tmp/git-user

It will create two files in the tmp directory when you run the previous command, one git-user file with your private key and one git-user.pub with your public key. You can name the file differently if you want to. I am saving the keys to /tmp/ since we otherwise can get permission issues in the next step. You can freely move your private key however from the tmp directory at this stage, we will not be using it.

Now lets tell gitosis to use your public key as the administrative user key. To do that we need to log in as the git user to the remote server. If you're still logged in over ssh as the regular user, which you should still be after the previous step, you can just do

su - git

And you should now be logged in as the git user. Now we initilize gitosis by doing

gitosis-init < /tmp/git-user.pub

Which will add you as an administrative user to gitosis. You can now log out from the git account. Don't close the connection to the remote server however, we still have stuff to do there. But that is it for the installation.

Configure gitosis and gitweb

If you already logged out of the remote server where gitosis is installed you should log back in as the regular user we gave administration rights to in the previous section. Gitosis convienintly keeps all configuration files in a git repository which it itself manages so to get those settings we need to clone that repository. This can be done like so

git clone git@server:gitosis-admin.git

That will clone the gitosis-admin repository into a local repository for you (if you have admin rights, that is). If you examine the repository you will notice there are one file named gitosis.conf and a directory named keydir with your administration key in it.

Every time you want to add a user to gitosis you will need to add the users ssh key to the keydir directory. The key filename (without the .pub) extension then works as the username when you configure the users to groups in the gitosis.conf file. I won't go into specifics how that is done, there are plenty of examples around the internet about that.

When you have edited the configuration files you need to commit & push them to the gitosis server for them to take effect.

Gitweb is fully optional and is not needed by gitosis to work but since it is a nice tool to browse the repositories with I thought I would show you how you can get that up and running as well on your git server. When you install gitwev it will install itself with the apache web server and can directly be launced by starting the server and pointing the browser to http://server/git. However, your repositories from gitosis will not be visible.

To get your gitosis repositories to work with gitweb you will have to tell gitweb where the repositories are located. To do that you will need to open gitwebs configurtion file which is located at /etc/gitweb.conf. There are a lot of properties you can set in that file but the property you are interested in in the $projectroot property. Set that property to

$projectroot = "/home/git/repositories";

which is where gitosis currently is saving our repositories. Save and close the file. You will need to restart the apache server for the changes to take effect. Hopefully, when you now navigte to http://server/git you will at least see the gitosis-admin repository.

Adding a project

Okay, so we now have Gitosis configured. Lets add a test project to see how we can use Gitosis.

First lets create a new git managed project. Lets call it TestProject.

mkdir TestProject
cd TestProject
git init

Now, lets add a file to the project..

echo "Hello World!" > hello.txt
git add hello

.. and make that initial commit so we have some history to look at

git commit -m "Initial import"

Okay, now we have a local git repository all set up, now lets see how we can get it exported to our remote gitosis server. For Gitosis to be able to manage our repository we need to add some repository information to gitosis configuration. So, log in as the gitosis admin user you set up earlier ( not the git user however), and go to the gitosis-admin repository and open up the gitosis.conf file.

In that file add the following:

[repo TestProject]
description = Our testing repository
owner=gitadmin

And lets create a user group for our project as well so continue by adding the following:

[group TestProjectDevelopers]
members = git-user
writable= TestProject

Now save the file and close the editor. But we are not quite yet done, we still need to commit the changes and push them to the server.

git commit -am "Added TestProject repository"
git push

Configuration done. Gitosis now knows about your project. Next lets actually export our project to the server.

Return to the local git TestProject we previously create with the hello file. Go into its directory and do:

git remote add origin git@server:TestProject
git push origin master

And finally we are done. You now have a new git project set up on your remote server from where you can push and pull files. To browse the project point your browser to http://server/git and you should see your project there.

PS.. I wrote this tutorial while i was installing and its purpose is more for me to remember how this was done than a complete tutorial, so it may be lacking in some parts. However, I think I am not the only one doing this stuff so if you find it helpful I am happy.