Mindstab.net

• Hg Init: a Mercurial tutorial by Joel Spolsky
  A tutorial for how to think about using distributed version control systems like git and mercurial by Joel Spolsky
  (tags: git, dvcs)

• Learn.GitHub
  "Here we have tried to compile the best online learning Git resource available. There are a number of articles and screencasts, written and arranged to try to make learning Git as quick and easy as possible."
  (tags: git, howto)

• Git for Subversion users, Part 1: Getting started
  Decent intro to Git tutorial on IBM Developer Works
  (tags: git, howto)

Ok, hopefully this will be the last mention of this for a bit. I've gone back and completely rewritten and expanded greatly on my old Git tutorial. It's still at the same place, Mindstab's Git Guide, just with a new name. It still needs lots more work and expanding, which will eventually happen, but probably not right now. As it is it's now good enough to let stand on its own while I get back to cl-pack. It has everything you need to set up a repository and get it on a server in one of many configurations. It just doesn't have a lot on longer term development and multi team management of multiple repositories and branches. Haha, I also recast it as an Alice and Bob story.

Just a note, I updated my 2008 how to set up a git repository entry. If you're curious, here it is
http://www.mindstab.net/wordpress/archives/288

This is a 'living document' in that I'll try to keep updating it from time to time so it keeps working with git as git "matures" and as I learn more about git.
- Last Updated 2009 07

I've found documentation on the setup of git servers and public repositories kind of lacking, so here is my best attempt at documenting what works for me. Feel free to comment with bugs or enhancements please.

Contents

• 1. Setting Up A Local Repository
  • 1.1 From Scratch
  • 1.2 From An Existing Project
• 2. Setting Up A Remote Repository
  • 2.1 Remote Repository For Developer Only (ssh)
  • 2.2 Remote Repository For Public Access (git://)
  • 2.3 Shared Multi-Developer Public Repository
• 3. Managing Multiple Developers, Repositories and Branches
• References

1. Setting Up A Local Repository

Alice is going to start developing a project and she wants to add source control to it. There are a couple of reasons to set up a local repository that Alice likes including branch control, so that she can revert her code to previous releases, fix, patch or merge a bug fix, roll a release, and then pop back to the current development branch.

1.1 From Scratch

To set up a git repository for her project, Alice does the following:

alice@home $ mkdir proj
alice@home $ cd proj
alice@home $ git init

The project directory is now an empty git repository. As she creates files, she can add them to the respository with

alice@home $ git add newfile.src

And when she's done work or at least reached some break point, she can commit the new files, and all changes with

alice@home $ git commit -a

1.2 From An Existing Project

Also, occasionally Alice gets excited and starts coding before creating a repository. To create a repository from an already started project is as simple as

alice@home $ cd ~/proj
alice@home $ git init

and either

alice@home $ git add .

to add all the files, or

alice@home $ git add file1 file2 file3

to add just some of the files, both followed by

alice@home $ git commit -a

for the initial commit of the code to the new repository.

2. Setting Up A Remote Repository

Some times Alice needs her repositories to be remote and internet accessible. Sometimes she needs to work on them from several locations, and sometimes she wants her project's code to always be accessible to the public.

There are two primary methods for making remote git repositories accessible online. The first method is over ssh, which developers can use to both read and write to the repository and the second is through a dedicated git server which the public can use for read only access.

2.1 Remote Repository For Developer Only (ssh)

If Alice's project is personal and she just needs a central repository to access from a few locations like both work and home, she can set up a repository on any unix machine she has access to as follows.

Alice needs to create a bare repository clone of her working code and then transfer it to the server she will be using as the repository host

alice@home $ git clone --bare ~/proj proj.git
alice@home $ tar -czf proj.git.tar.gz proj.git
alice@home $ scp proj.git.tar.gz alice@server.com:~

Then, on the server

alice@server $ tar -xzf proj.git.tar.gz
alice@server $ mv proj.git proj

Now Alice can create working copies of the repository from anywhere, like work, and work on the code as normal as follows

alice@work $ git clone ssh://alice@server.com/home/alice/proj
alice@work $ cd proj
...
alice@work $ commit -a

However all this does is create a local clone of the repository and commit the changes to the new local clone. To push changes to the local repository back to the central repository, Alice does

alice@work $ git push

(As a note, Alice will also need to perform this clone of the remote repository at home so that her repository is aware of the remote repository, or she can use 'git remote add' to make her current original repository aware of the remote one)

When Alice gets home she can check out the latest changes with a simple

alice@home $ git pull

which pulls all the latest changes from the remote repository. Then she can develop, commit and push her changes and then the next day at work she can pull all those changes.

2.2 Remote Repository For Public Access (git://)

Now, to allow public read only access of the repository over the git:// protocol the steps of setting up a remote repository are all the same, however there are additional steps that need to be taken.

At a minimum, Alice needs to setup the git daemon on the server and tell each git repository that she wants to be publically accessible that it is so.

Setting up the a basic git daemon is up to Alice and her server's distribution, but once it is installed and running, it will try to export any directory on the server filesystem that is a) a git repository, and is b) flagged to be publically accessible.

To make her repositories accessible, Alice does the following

alice@server $ touch ~/proj/git-daemon-export-ok

Now when Bob hears about Alice's project, he can check out a copy of the repository himself as follows

bob@home $ git clone git://server.com/home/alice/proj

Bob actually ends up with the a full clone of the repository and can work with the code, and if he wants he can make changes and commit them to his local clone of the repository as normal. However, the one thing Bob cannot do is 'push' his changes back to the central repository.

He can, however, even stay up to date with the repository with git pull

bob@home $ git pull

and he'll always get the latest changes.

2.3 Shared Multi-Developer Public Repository

(Note: This is for those more used to CVS and Subversion style source control. Defacto and "proper" git style is outlined in section 3. Managing Multiple Developers, Repositories and Branches.)

Alice happens to have root access to her server and wants to set up a multiple developer git repository.

First she creates a git user group and makes a root git directory.

root@server # groupadd git
root@server # mkdir /git

Then Alice configures the git daemon to only export repositories in /git in the git-daemon's config file

GITDAEMON_OPTS="--syslog --verbose /git"

Now Alice creates a shared repository. She untars the git repository like normal, but sets its group to git and makes sure it'll stick by setting the stick bit, and then she makes it "shared" which means all the files are writeable by the group git.

root@server # cd /git
root@server # tar -xzf proj.git.tar.gz
root@server # mv proj.git proj
root@server # chgrp -R git proj
root@server # chmod g+ws proj -R
root@server # cd proj
root@server # git config core.sharedRepository true

And of course if Alice wants it to be publically viewable

root@server # touch git-daemon-export-ok

Now Alice has a git repository that several developers on the server can all use. Anyone in the git group can commit to the repository.

Alice's friend Charlie wants to develop for the project so Alice gives him an account on the server. Charlie can then start developing just like normal

charlie@home $ git clone ssh://charlie@server.com/git/proj
charlie@home $ cd proj
...
charlie@home $ git commit -a
charlie@home $ git push

Alice can get these changes at home, and any she's made from work with a simple

alice@home $ git pull

And if the repository was made public and exportable then Bob can checkout the code and keep up to date too

bob@home $ git clone git://server.com:/git/proj
bob@home $ cd proj
...
bob@home $ git pull

3. Managing Multiple Developers, Repositories and Branches

The proper way to use git with multiple developers is for each developer to have their own repository and branches and have a central manager who pulls from all the other branches and merges the code together before release. This is how Linux works (git was created by Linux's creator Linus).

Note: I know this is the proper way but I haven't really had any experience with it, so until I get time to play with it unfortunately this part of the document will be empty. Check out the official git manual for a good idea of how this should be managed, especially chapter 4 Sharing Development.

References

• Git User's Manual (for version 1.5.3 or newer)
• Setting up your Git repositories for open source projects at GitHub
• Google

WARNING: This howto is now old and deprecated! Check the newer version linked to below for a current working howto:

http://www.mindstab.net/wordpress/archives/288

So I went back and got my git server working 100%. Reread some docs and now everything is working quite well. It's pretty nice.

To get a git server setup, emerge dev-utils/git and cogito. Cogito is a "front end" of sorts for git. It supplies some better commands in some cases. Then run

/etc/init.d/git-daemon start

and you now have a git server. Yes, it's that easy.

Of course you don't have anything in it and you aren't quite setup to, but it's fine to have the server running with a somewhat empty system. Next create a directory to store your git repositories, like /git. Now all you have to do is create repositiories, which is made very easy by the command

cg-admin-setuprepo -g git /git/repoName

'git' being a user group that committers on the system will be members of so that they can all have write access. Now of course you have an empty repository. Also, you have a non shared repository. Other system users/'committers' can access it, but it's not exported by the git server. To do that, simply

touch /git/repoName/git-daemon-export-ok

To populate the repository, change into a directory where you have the code you want to go into the repository. This can be on any computer, not necessarily the server. We will set up more git stuff 'client' side and then 'commit' it to the git server. So where ever the code is, you need ssh access from that location to an account on the git server that is a member of the 'git' group that can write to the repository. Now, once if the code directory, set it up as a git repository with

cg-init

If all went well you now have a local git respiratory of the code. It might give you an error involving AUTHOR_NAME and COMMITTER_NAME. IF this happens it is because the name field for your user account is blank. Edit /etc/passwd and add a name (can be the same as the account name) to the 5th field of the account you are using. Now it should work (rm -r .git to restart). Now to connect the local repository to the server and update the server, we do as follows, first we add a branch to the local repository that is connected to the server.

cg-branch-add origin git+ssh://serverName.com/git/repoName

Now they are connected. 'origin' will be the default branch (I believe it's a special branch, whose purpose should be obvious). Now just update the server.

cg-push

Done. Now you have a git server with a repository of your code. You can update the repository with further changes by

cg-commit
cg-push

Other non-system/non-commit users can access the repository with

git clone git://serverName.com/git/repoName

or

cg-clone git://serverName.com/git/repoName

and once in it they can update it from the server with

cg-pull

And there you have it, how to set up a git server on Gentoo and populate it.

References:

• A tutorial introduction to git
• Git - CVS crash course
• Cogito README
• Various git and cogito man pages.