Git & Github

Introduction

This page describes how we use Git & Github. It is aimed at individuals and organisations who may wish to get/use the source code, or contribute back to the source code through the collaboration model.

We use Github & Git as we want:

• To simplify the way individuals and organisations can get access to the source code of our software.
• Allow individuals and organisations to independently make changes and extend the software for their own needs
• Allow individuals and organisations to easily contribute back any work they do through the Fork & Pull model.

Developers should follow the instructions below to make the above possible.

Useful links

1. Pro Git book - http://git-scm.com/book/
2. Git workflows book - http://documentup.com/skwp/git-workflows-book
3. Git quick reference - http://gitref.org
4. ThinkUp develop from source

Note: The ThinkUp documentation on developing from source is very good. I will most likely change our documentation to that style/format and come up with a graphic to illustrate what we do which would be very much the same as the one they have created.

Install Git on your local machine & First time setup

There are a few places which contain good instructions on how to do this:

1. set-up-git
2. Git pro book online http://git-scm.com/book/en/Getting-Started-Installing-Git
3. Git pro book for what to do for first time setup: http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup

Of note is:

$ git config --global user.name "John Doe"

$ git config --global user.email [email protected]

and git config --list to check your git configuration.

When on windows, make sure to check that the following is set: core.autocrlf=true

We do this when using git on windows as all the files in the respository should have LF line endings. With core.autocrlf=true, all LF line endings are converted to CRLF line endings on checkout to a Windows machine. All files are converted back to LF line endings on commit from a Windows PC.

Fork the project on your personal or organisation github account.

If you dont have a github account already then you need to sign up and create one on on github.com (free accounts are fine).

Once you have a github account, the next step is to fork https://github.com/openMF/android-client.

see https://help.github.com/articles/fork-a-repo for help on forking in github.

Clone the repository to your local machine.

Create a directory in which you want the cloned project to exist within: e.g. in directory c:/dev/githubrepos/

git clone [fork repository url]

For example: [email protected]:USERNAME/android-client.git

see https://help.github.com/articles/fork-a-repo for help on forking in github

see https://help.github.com/articles/which-remote-url-should-i-use

After the clone operation has completed (should be pretty quick), you should have a directory structure like the following:

android-client:

• gradle
• mifosng-android

Configure remotes

When a repository is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you should add another remote named upstream:

The easiest way is to use the https url:

git remote add upstream https://github.com/openMF/android-client.git

or if you have ssh set up you can use that url instead:

git remote add upstream [email protected]:openMF/android-client.git

Master and Develop branches

By default when using git you will always have a branch named 'master'.

• master: represents the bleeding edge development changes planned for next release of mifos.

Create a topic branch for each unique piece of work

Its probably easiest if you create a new 'topic' branch on your forked repository for each unique piece of work rather than commit changes directly into master or our special develop branch. Why?

It means you can work on something very specific, get it up to date and send a 'pull request', To move on to a seperate piece of work, you simply create a different branch. It might also make it easier to keep up to date with the openMF/mifosx repository as explained in next section.

Pull in upstream changes & Keeping your forked repository up to date.

There will be development changes to the openMF/android-client almost every day for the foreseeable future so its important to keep your fork of the software up to date with the latest changes.

To pull in upstream changes from repository you forked:

git checkout develop ... to make sure you are on the develop branch

git fetch upstream ...fetches changes from upstream respository but does not merge/rebase them

git merge upstream/develop ... merge in the new changes from upstream/develop repository into your repositories develop branch (You should not have any local changes on your master branch, if you do, use rebase)

git push origin develop ... push up the just merged changes to the develop branch on your fork

git checkout my-topic-branch ... switch to the topic branch you are using for piece of development work

git rebase develop ... rebase your topic branch which means, take in all latest changes and replay your work in topic branch on top of this - this produces cleaner versions/history

Note: the use of rebase for pulling in changes on top of your possible local dev changes as opposed to merge.

git push origin [branchname] ... do this if you are ready to push up your topic branch to your github account.

Read more about this at http://help.github.com/fork-a-repo/

Push local changes to forked repository

git push origin [branchname] e.g. git push origin master

Contributing back changes to original repository/authors

We would expect people to use the Fork & Pull model for collaborating back. Simply this means that we expect you to use Githubs tools here and to send pull-requests to us when you have a piece of work you want to contribute back.

Read more here: https://help.github.com/articles/using-pull-requests

Optional: If possible, it would nice if you could have your work in one commit rather than several broken up commits. If you followed advice on using a 'topic-branch' for you work and you have used rebase to get your changes up to date with the latest, and its only you doing work, you should be able to squash your changes over several commits into one commit as follows:

Suppose I want to squash last three commits I did on this branch into one,The command to accomplish this is:

git rebase -i HEAD~3

This will open up your editor with the following as for example

pick f392571 Added new feature X

pick ba9df9a Updated layout.xml

pick df71a28 Updated string.xml

Now you can tell git what to do with each commit. Let’s keep the commit f392571, the one were we added our feature. We’ll squash the following two commits into the first one - leaving us with one clean commit with features X in it, including the updated layout and string xml file.

Change your file to this:

pick f392571 Added new feature X

squash ba9df9a Updated layout.xml

squash df71a28 Updated string.xml

When done,come out of edit mode by pressing escape then save and quit your editor by pressing :x . Git will now squash the commits into one. All done!

or you can also reset your latest commits and re-commit as one as follows:

git reset HEAD~2 ... reset last two commits (uncommits all changes in last two commits back to local changes)

git status should show last two commits as uncommitted again, then simply re-commit git commit -a -m "my commit message"

Squashing commits that have been pushed

If you want to squash new commits with commit that has already been pushed to remote, follow the steps:

git checkout [branchname]

git reset --soft HEAD~n where n is the number of commits to be squashed

git commit -m "combined commit message"

git push --force origin [branchname]