This page is used to collect notes and documentation about using Git to work on Apache projects.

Related discussion takes place on the infrastructure-dev@apache.org mailing list. See the list archives for past discussion. You can subscribe the mailing list by sending a message to infrastructure-dev-subscribe@apache.org. The mailing list is public and open to everyone.

Git mirrors

Many Apache projects are available as git-svn mirrors at http://git.apache.org/. Please file an INFRA issue (component: Git) to request a new codebase to be mirrored or to change the settings of an existing mirror.

After git cloning a mirror from here, committers can commit back by doing the following once after the clone:

git svn init --prefix=origin/ -s https://svn.apache.org/repos/asf/$PROJECT_NAME
git svn rebase

and then using git commit and git svn dcommit as normal.

The authors file

Before fetching sources directly from svn using git-svn, you may want to set up an authors file that maps svn usernames to the full names and email addresses of the respective committers. An automatically updated authors file that lists all Apache committers is available at http://git.apache.org/authors.txt. This file is also used by the Git mirrors mentioned above. After downloading the file use the following command to tell git-svn where to find it.

git config svn.authorsfile /path/to/authors.txt

It's a good idea to periodically update your copy of the authors file to remain up to date with new committers and possible name changes. If you don't, eventually 'git svn rebase' will fail when it encounters a commit by someone not listed.

Using git-svn

It also is possible to use git-svn to directly access sources in svn. Use the following command to set up a clone of the trunk of a project:

git svn init https://svn.apache.org/repos/asf/<project>/trunk <project>
cd <project>    # go to the empty new directory created above

This sets up an empty git repository with basic git-svn configuration required to fetch code from (and dcommit changes to) the given svn trunk.

Use the following command to fetch the latest sources from svn:

git svn fetch --log-window-size 10000

The --log-window-size option is needed to make git-svn find your project faster and more efficiently in the huge Apache svn repository.

IDE integration

IDE integration tools for git are still evolving and in many cases it's still best to have the command line client readily available. See the list of available tools at the Git wiki for the latest status on IDE integration.

Git for Apache committers

Following instructions are intended for Apache committers only.

This a simple guide showing what combination of commands you need to execute in order to set up Git the way that you can commit your changes back from Git to SVN. This guide is based on experience collected from infrastructure-dev@apache.org and git@vger.kernel.org mailing list. It does not explain all details but should be sufficient to start working with Git effectively.

The following steps are needed to clone project from git-svn mirrors:

PROJECT_NAME="cocoon"
git clone git://git.apache.org/"$PROJECT_NAME"
cd "$PROJECT_NAME"/.git; wget http://git.apache.org/authors.txt; cd ..
git config svn.authorsfile ".git/authors.txt"
git svn init --prefix=origin/ --tags=tags --trunk=trunk --branches=branches https://svn.apache.org/repos/asf/"$PROJECT_NAME"
git svn rebase

At this point everything is set up correctly so if you commit something into Git this can be pushed back to SVN. Before you start experimenting with committing with Git it's probably the best idea to learn two basic yet useful tools: git gui and gitk. They are straightforward enough that they do not need any further explanations; it's enough to run them and play for a while.

After you commit first changes into Git you will probably want to push them back to SVN. Just make sure that you are in master branch (trunk) by using git gui or git branch commands and then execute

git svn dcommit

This command will push your changes back to SVN and that's it!

There are a lot of different introductory pages and the purpose of this little tutorial was to show Apache-specific information.