This documentation refers to an older version of CiviCRM (3.4 / 4.0). View latest version.

Skip to end of metadata
Go to start of metadata
This page refers to CiviCRM 3.4 and 4.0, current STABLE version.

Documentation Search

CiviCRM 3.4 and 4.0 Documentation

Support and Participation

Developer Resources

CiviCRM books!

Make sure to check out the FLOSS Manual Understanding CiviCRM as well! You can also support this project by ordering a hard copy.

Or support us by buying an eBook or hard copy of Using CiviCRM from Packt Publishing.

As suggested in a recent blog post, CiviCRM has decided to transition from using subversion as our revision control system to using git.

If you are a regular user of CiviCRM or if you typically install CiviCRM by downloading the tar ball then this transition will have no impact on your use of the software. This transition is only relevant for developers or integrators who currently checkout CiviCRM via subversion.

We are still in a transitional period. The existing subversion repository is still the canonical repository for CiviCRM. We have not yet released the date when we will stop maintaining the subversion repository.

The planning for the transition is happening via the civicrm-git google group.

General Information about git

The git web site has a documentation section with links to excellent tutorials and information. If you are used to subversion, we would especially recommend the documentation designed to help people transition from subversion to git.

Unlike subversion, with git you are getting a copy of the entire repository, not just the most recent files. That means the first time you do a checkout, it takes a lot longer and you get a lot more files downloaded (several hundred megabytes). If you do not want the entire history of the project, you can used pass --depth 1 to only get the current files.

If you choose to checkout the entire repository, after your initial checkout, you will only be importing changes, so it will go much faster.

The official civicrm git mirror

... has not been officially launched yet.

We are experimenting with a read-only repository that regularly pulls in changes from subversion. Please don't rely on this repository, it may experience major changes in organization. However, testing and feedback is welcome and appreciated. It is available via gitorious. Or via git:

On a reasonably fast broad band connection it takes over 10 minutes to clone the entire repository. For a faster clone (without history):

If you are looking for l10n and tools - please read the submodules section below.

The official civicrm git sandbox

We are maintaining a git sandbox that has a somewhat up-to-date copy of the repository. The purpose of the sandbox is to practice. You are welcome to make and push test commits that will be thrown away. For obvious reasons, please don't rely on the this sandbox to do real work (production or even development). It's purpose is only to practice using git with CiviCRM code.

The sandbox is available va gitorious . Or via git. Use the following command if you do not want to commit changes back to the canonical sandbox repository:

On a reasonably fast broad band connection it takes over 10 minutes to clone the entire repository. For a faster clone (without history):

If you would like write-access so you can push your changes back to the canonical sandbox repository, please register for an account on gitorious and then email your username to If you want write access, you can checkout the project with the following command instead:

Basic Workflow

Most common operations

The most common operations are:

Unlike subversion, if you change a file that has already been added it is considered "new" and won't be committed if you run git commit unless you first git add it.

If you want subversion-like behavior in which all files that have been previously added that are now changed, try:

Getting out of trouble

If you changed a file and you have not git add'ed or committed it, but want to discard your changes:

If you altered a file or files and you have git add'ed them or you just want to blow away all un-committed changes in your repository:

If you committed to your local repository, but you have not pushed, and you want to change your previous commit (or commit message):

If you git pull and git tells you have a conflict with your local changes:

Using submodules

When checking out the code

If you are an integrator or a developer that does not need the tools or lt10n directories, you can ignore this section. You will get a tools and an l10n directory in your checked out repository, but these will be empty.

The civicrm git repository has two directories that are git submodule directories: tools and l10n. git submodules are similar to subversion external repositories.

If you need access to the submodules, you need to execute an extra two command after you checkout the code initially:

Every time you update your code, you will need to run git submodule update to get the most recent version of the submodules as well.

When changing the code

If you ever need to make changes to files in the tools or l10n directories, you must use a slightly different work flow.

One time change

The git submodules are checked out via the git protocol (in read-only mode). That's because we want them available to everyone checking out the master civicrm code. If they were checked out via ssh (in read/write mode), then people who do not have ssh access to those repositories would get an error.

So, assuming you have ssh access to the tools and l10n repositories, you will need to change your git url for the submodules:

(Replace civicrm-sandbox with just civicrm if you are doing this for the real repository.)

Every time you edit a submodule

When you run git submodule update from within the civicrm git repository, you will be pulling in a particular commit of the submodule, not the master branch (or head) of the submodule project. If you want to make a commit to a submodule, you have to first switch to the master branch of the submodule and then make your commit to the submodule repository and publish that commit. Then, in the civicrm repo, make your commit. The civicrm commit says: link HEAD of the civicrm repository to this particular commit of the submodule repository.

First change into the submodule directory:

From inside the submodule directory, checkout the the master branch:

Then, make your file changes and commit:

Publish those changes (to the submodule repository):

Change up a directory to the civicrm repository and commit:

NOTE: do not add a trailing slash to the git add command! It's very easy to do this if you use tab completion. If you type this:

You are saying: rip out the submodule and add this directory to the master repository.

Subversion to git synchronizing

During the transition period, we are running a cron job that sychronizes all changes made to the subversion repository to the gitorious git repository.

Here are the gory details...

All the action happens as the gitsvn user on

I set up three repositories: civicrm, l10n and tools. In these examples I only show the commands for civicrm.

The git repository was initialized with:

For the civicrm repo, it takes more than 8 hours to complete.


At this point, I checked out a copy of each repo from svn and then tested to make sure they were the same (for the civicrm repository, I deleted the tools and l10n remote repositories from the checkout subversion repository because these have not yet been added to git):

This output only shows the difference in the $Id$ line which is automatically populated by subversion and it lists empty directories in the subversion repository (git doesn't store empty directories). It should not show any other differences.

Next, I created an ssh key for the gitsvn user on sushi and gave this key access to the civicrm project on

Then, I created remotes for each of our new git repositories:

I pushed the tools and l10n repos:

Next, I fixed the civicrm git module to use l10n and tools repositories as submodules:

And finally pushed that as well.

Lastly, I modified Roman's bash script that can be run by cron to keep things in sync:

The future of the civicrm git repository

We are currently experimenting with two approaches to handling Drupal 6/Drupal 7 code. For more information about this discussion, see our notes from the Sept 15 meeting

Submodule approach

stub for documentation

Branches approach

stub for documentation

  • None