Effective use of version control is critical to effective team collaboration on Mifos. Our version control system is how we communicate code changes with one another.

Browse Source

http://mifos.git.sf.net/

Developer Setup

Follow this section completely before cloning any Mifos repositories!

Install Git

Install Git on Windows

Install msysGit (look for a file named similarly to Git-1.7.0.2-preview20100309.exe)
select default components
in "Adjusting your PATH environment" select "Run Git from the Windows Command Prompt"
choose the default for the "Configuring the line ending conversions": "Checkout Windows-style, commit Unix-style line endings"

Install Git on Ubuntu

sudo apt-get install git-core gitk

Install Git on Mac OS

To install using macports, follow instructions here. Alternately, an installer (.dmg) can be found at git's web site. However, at the time of this writing, a .dmg file for the latest version of git is available for Leopard-intel but not Snow Leopard.

Line endings

Tell Git to handle line endings for you so folks on different platforms can live in harmony.

Windows

Do this on the Git Bash MINGW msysGit command line:

git config --global core.autocrlf true

Linux and Mac

Do this:

git config --global core.autocrlf input

More info

Author Info

To make all commits clear/legible/accessible, please configure git to use your full, real name and email. This means...

user.name must be your real/legal first and last name. Do not abbreviate either. If you have more than two names, pick the two you are most commonly known by.

For example:

git config --global user.name "Joe Example"

user.email must be a working email address. This address should be permanent, ie: not something that will change when you change jobs.

For example:

git config --global user.email joe@example.com

Day to day usage

For a quick summary, see the Git homepage.

Clone

For svn users: this is similar to "svn checkout"--you'll get source code you can examine and modify.

For read-only access:

git clone git://mifos.git.sourceforge.net/gitroot/mifos/REPOSITORY_NAME

Where REPOSITORY_NAME is "head", or any of the repositories listed at http://mifos.git.sf.net/. For instance, to check out the head revision:

git clone git://mifos.git.sourceforge.net/gitroot/mifos/head

Read-write access uses a url with an "ssh" schema, and permission granted by a current Mifos maintainer.

ssh://USERNAME@mifos.git.sourceforge.net/gitroot/mifos/head

Where USERNAME is your sf.net username.

Key-based auth

Unless you want to enter your password for every push, post your public SSH key on sf.net. Once you have logged onto your sourceforge account, navigate the the account/ssh page and paste your authorized public key on the form. To reach the edit ssh keys page on sourceforge, click on Account in the upper right corner, then click the Services Tab. Look for "Edit SSH Keys for Shell/CVS" link.

Commit to your local repository

Add files to the git "index" so they will be committed with "git add". Optionally, instead of running "git add", include -a when running "git commit" to commit all local modifications except new files. Then, commit:

git commit

In Git, the first 80 characters of the first line are, by convention, a summary of the rest of the log message. See Commit Log Guide.

Push changes to a remote repository

If the remote repository is called "origin", you might do:

git push origin master

Update your master branch

git pull origin master

Creating a patch

Here are two suggestions.

1)

git format-patch

2) If you have a public git repository, create a pull request with

git request-pull

Either way, send the output to the mifos-developer mailing list, and describe your patch following Commit Log Guide.

Branching basics

Please refer to Pro Git: Basic Branching and Merging.

Creating a local branch

git branch NAME_OF_BRANCH

Deleting a local branch

git branch -d NAME_OF_BRANCH

List branches

Local branches can be listed with:

git branch

To see all "remote" branches:

git branch -a

Note that "remote branch" really means a local copy of a remote branch.

Merging in changes from another branch

git checkout BRANCH_TO_MERGE_CHANGES_TO
git merge OTHER_BRANCH

More on merging

Again, see Pro Git: Basic Branching and Merging.

Moving changes from one repository to another

I'm not sure which way is best.

Cut and Paste

Say you wanted to merge a change from "head" to "1.5.x". Create a patch with "git format-patch". Apply the patch to the other repository with "git am".

Branch and Merge

Say you're following Mifos "head", and you want to pull a change from the 1.5.x line of development. You first have to do:

git remote add 1.5.x ssh://USERNAME@mifos.git.sourceforge.net/gitroot/mifos/1.5.x

Then you mirror the branch "master" from the remote repository "1.5.x", pull in a change, and push it back up to "head":

git fetch 1.5.x
git cherry-pick 5948a92795197bc4e6577173445d0efac09130ae
git push origin master

Resolving merge conflicts

http://stackoverflow.com/questions/161813/how-do-i-fix-merge-conflicts-in-git

Tagging

Releases

The release tag naming convention is simply the exact version number of the release. This tag should be created on the release branch/fork. The tag should be GPG-signed by a Mifos maintainer.

Example done for the 1.5.0 release:

git tag -s 1.5.0 f32b705f09b879bc91324f31cbcbff87637d9fb3
git push --tags origin

Builds

Hudson automatically tags commits as they are built. These are currently only stored locally in Hudson's clones. It might be convenient to automatically propagate these tags elsewhere.

Where to get more help

Eclipse IDE Integration

EGit provides "Team" (version control) capabilities in Eclipse.

EGit does not yet support comparing full trees.

For Mifos administrators and curious contributors

Why Git?

vibrant community
mature, stable toolkit
got help from former Mifos volunteer and git user Tom Bostelmann
separate committer and author fields

Legacy version control

Mifos source code was originally hosted in Subversion. Not everything was imported from Subversion. Neither git-svn nor svn2git could parse Svn 1.5+ mergeinfo, so multiple branches could not be imported simulataneously.

We chose to create multiple git repositories on sf.net, one for every long-lived release branch. Development branches may still be created and shared according to the above documentation.

How to migrate a Subversion branch to Git

Locally, pull down a branch from Subversion:

mkdir mifos-1.5.x && cd mifos-1.5.x
git svn init https://mifos.svn.sourceforge.net/svnroot/mifos/branches/v1.5.x
git svn fetch

This will take a while. While this is running, create a new git repository at sf net for the branch you are about to copy from Subversion.

Once the pull from svn is complete, you can then push to sf.net:

git remote add origin ssh://meonkeys@mifos.git.sourceforge.net/gitroot/mifos/1.5.x
git push origin master

Mid-migration maintenance

There may be an interim period where the bridge between Subversion and Git must be kept alive. Subversion and Git commits can coexist in "head". To grab the latest from svn and push it to "head":

git svn fetch
git merge remotes/git-svn
git push origin master

To move your changes past all svn changes in your local git-svn clone, do:

git svn rebase
git push origin master

If you lose your original git-svn clone of, say, /branches/1.5.x, you can do the following to hook a clone of the 1.5.x repo back up to the corresponding branch in svn:

git config svn-remote.svn.url https://mifos.svn.sourceforge.net/svnroot/mifos/branches/v1.5.x
git config svn-remote.svn.fetch ':refs/remotes/git-svn'

Then try rebase/push as mentioned above.

Hook scripts

In use

All hook scripts used on the sf.net repositories are committed to resources/scripts/githooks in head.

Here's what I did for the cia.vc pinger scripts:

manually copied them into sf.net shell, "~" directory via scp
SSH'd into sf.net shell
copied scripts into /home/scm_git/m/mi/mifos/head/hooks/
from "hooks" dirs of other projects, symlinked to the hook scripts in the "head" hooks dir (so only one version of the scripts needs to be maintained)

Note that the "update" script uses a different path to ciabot.bash than you'd expect based on the git repository paths on sf.net when you SSH in (the repositories aren't in /home/scm_git when the hook scripts are executing).

Testing

The "hooktest" repository can be used for testing hook scripts. If "hooktest" is missing, a new empty repository can be created.

Backups

Backups are done using the git client (to maintain bare clones of repositories at sf.net) and rsync (to maintain files that aren't cloned). They are staged in /home/gitbackup on the backup server.

The gitbackup user performs backups daily as follows:

#!/bin/bash
set -o errexit

for repodotgit in `\ls $HOME/repositories/mifos`
do
    cd $HOME/repositories/mifos/$repodotgit
    repo=`basename $repodotgit .git`
    git fetch --quiet git://mifos.git.sourceforge.net/gitroot/mifos/$repo > /dev/null
    cd - > /dev/null
done

rsync --archive --delete --relative \
    mifos.git.sourceforge.net::gitroot/mifos/*/config \
    mifos.git.sourceforge.net::gitroot/mifos/*/description \
    mifos.git.sourceforge.net::gitroot/mifos/*/hooks \
    $HOME/extra_git_files

Test restores were performed by copying the backup back to sf.net and cloning.

Mifos Version Control Guide