This page is used to collect notes and documentation about using Git to work on Apache projects.
Related discussion takes place on the email@example.com mailing list. See the list archives for past discussion. You can subscribe the mailing list by sending a message to firstname.lastname@example.org. The mailing list is public and open to everyone.
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 https://git-wip-us.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.
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
Important --- 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 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 email@example.com and firstname.lastname@example.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".git cd "$PROJECT_NAME"/.git; wget https://git-wip-us.apache.org/authors.txt; cd .. git config svn.authorsfile ".git/authors.txt" # check if your username and email are identical to those in the author file git config user.name git config user.email # if they are not identical, set the ASF values locally # git config user.name <Your Name> # git config user.email <Your Email> 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!
Note that european users may experience troubles with dcommit because dcommit runs a rebase immediately after committing to SVN. Since the svn.apache.org redirects location-based to svn.us.apache.org or svn.eu.apache.org and the latter is sometimes a bit behind the master, the rebase can fail. As a workaround use --no-rebase option along with dcommit and rebase a few seconds later.
There are a lot of different introductory pages and the purpose of this little tutorial was to show Apache-specific information.
Git only revisions files, not directories. If your project requires any empty directories (for example one of the Tomcat unit tests depends on the presence of an empty directory) then you'll need to work around this if you are using git. Possible workarounds include manually adding the empty directory or adding a .gitignore file to the directory so it is non-empty.
The approaches to handling line-endings differ between git and svn. The differences will be more noticeable on projects where developers use a mix of platforms for development. Again, there are various ways to handle this. The configuration property you are most likely to need is git's core.autocrlf. For Tomcat, setting this to false gave the best results. YMMV.