/
Using Git

Using Git


Git is the version control system which we use to collaborate on the OpenMRS code bases.

Install Git on your computer

To get the git binary, see OS specific sections on installing git page.

This gives you a git command line. Git at the command line is easier to use in some instances than IDE Integration. But if you want
to use your IDE to interact with git (ala subclipse in eclipse), then see Git IDE Integration.

If you are a Windows user, see how to setup your user and password for the git command line here.

Learn how to use Git

You will be using Git all the time when working on OpenMRS and its also very likely that you will use it on other projects. It is therefore very useful to understand git. Don't be afraid its totally ok to start with understanding it a little bit to get started, but try to invest some more time once in a while to dig deeper into its workings. It will pay off (smile)

Here are a few free resources we recommend

Get the code (with the intention of contributing changes)

These instructions are designated for a developer who wants to contribute to projects under https://github.com/openmrs. A private fork will be used only as a backup storage and for pull requests, but not for collaboration with other developers. If you intend to use your fork to work in a team, please make necessary adjustments to the proposed workflow by avoiding the use of rebase.

Create account on github.com

https://github.com/signup/free

Looking for a quick reference to git commands?  Check out the Git for SVN Users page.

We switched OpenMRS core/trunk code from svn to git. As of August 2012 we are using github.com as the hosting provider for our git projects. See the openmrs github organization.

Check out the code to your machine

  1. On github.com, fork a project you want to work on (see tutorial: http://help.github.com/fork-a-repo).
  2. Clone the fork to your local machine (replace "yourusername"):

    git clone https://github.com/yourusername/openmrs-core.git
  3. Go into the folder just created and set up the "upstream" remote so you can eventually pull changes from the main repository (see "Configure Remotes" on http://help.github.com/fork-a-repo):

    git remote add upstream https://github.com/openmrs/openmrs-core.git
  4. Fetch and track all branches on remote repositories.

    git fetch --all
  5. After you cloned the repository you can list available branches:

    git branch -a

    The currently checked out branch is highlighted with an asterisks. The master branch is the latest development branch (trunk was its counterpart in SVN).

  6. Pull changes from the upstream remote:

    git pull --rebase upstream master

    The '--rebase' option reverts any of your commits which are not in upstream/master, then fast forwards your local branch to upstream/master and finally applies your commits on top of that. This allows you to avoid merge commits and keep the history linear, but must not be used if you want others to work with you on a branch in your fork.

    Optional pro tip: To save some key hits we recommend to setup an alias for 'pull --rebase' by running

    git config --global alias.up "pull --rebase"

    From now on you will be able to use 'git up upstream master' instead of 'git pull --rebase upstream master'.

  7. Push changes to your fork on github:

    git push

    This command pushes all your commits from all your tracked branches to your fork. If your fork has commits, which are not in your local repository, the branches containing these commits will not be pushed. You will need to pull on these branches first to have them pushed.


We do not advise you to work on master or maintenance branches of openmrs-core, but create topic branches instead. This way you will be able to send us pull requests to merge your code back to the main repository. See "Create Topic Branches" below, please take a look at our pull requests tips page.

See Maven wiki page for how to build, compile, etc.

Get the code in read-only mode (without intention of contributing)

This will check out the code for "openmrs-core" (the core OpenMRS application):

git clone https://github.com/openmrs/openmrs-core.git


  1. Checkout out a new local branch based on your master and update it to the latest. The convention is to name the branch after the current ticket e.g. TRUNK-123. 

    Make sure you have committed any new files that are not under version control otherwise you will lose them when you run *git clean -df*

    git checkout -b TRUNK-123 master
    git clean -df
    git pull --rebase upstream master
  2. Push the branch to your fork. Treat it as a backup.

    git push origin TRUNK-123

    Pro tip! Git has tab completion here!

Work on your task

NOTE: If the ticket you are working on requires you to work off a development branch say 1.9.x, you will have to use the development branch name instead of master for the instructions in this section. E.g. instead of git pull --rebase upstream master you will run git pull --rebase upstream 1.9.x, where 1.9.x is the development branch you are coding off.

  1. Make changes in code.
  2. Add changes to a commit (stage them). To see what files have changed.

    git status

    To stage all changed and new files.

    git add -A

    To pick only some files.

    git add -i

    You will see a summary of changed and new files. You need to choose '2' to mark files as updated. Now you need to pick files, which you want to mark as updated. You can specify them as a list 1, 2, 3, as a range 1-3, or simply * to select all. Confirm by hitting the enter key twice. If there are new (untracked) files, choose '4' and pick files the same way. Choose '7' to quit.

  3. Commit changes.