As of August 2012 OpenMRS is using github.com as the hosting provider for their git projects.
This page will go through steps for a person not familiar with github.
Step – 1: Create a Github Account:
Go to this link and create your own github account.
Step – 2: Install git in your system:
Go to this link and follow the instructions given according to your OS.
(It is highly recommended that you also download git bash instead of configuring it in your command prompt , as it gives an informative and colorful description of code status)
Step – 3: Getting the code:
As mentioned earlier almost all of OpenMRS source code is existing in this link (i.e. openmrs account in github).
When you work with git, it is important that you understand the code structure and how the interactions happen. The following image will show it’s structure.
I will base this example on the “openmrs-core” project (the core OpenMRS application).
So there are three components that you need to understand.
- The Light Blue box represents the source code in the openmrs account. This is the working code that everyone is working on.This is stored in the online cloud of github so that everyone can take a copy of it. This is also where the new code changes by developers are updated.
- The Dark Blue box represents your copy of the source code. This is also known as your remote copy of your code.This is where you put up all your code changes. Only your Dark Blue box can interact with the Light Blue box in the form of pull requests(as explained below).
- Finally, the Green box represents the local copy of your online code i.e the Dark blue box. As you can’t directly work on the online copy of your code, you make a copy in your system to work on it. After you commit your changes they are sent to your online account through commits and push.
- So you can have multiple copies of your remote in your system where you can explore and mess with the code, they wont be reflected in your online account until you push them into it.You have full permissions to implement any code in your account.
- Similarly, all developers can mess with their code in any way they would like but , if they want the code to be implemented they need to put up a pull request. This time only after the code is reviewed by a core developer, it can be merged with the openmrs source code(i.e the light blue box). You don’t have the rights to directly merge the code as you can to your online account.
- IMPORTANT: Whenever, you try to push your changes i.e either from Green box to Dark Blue box or from Dark Blue box to Light Blue box, you must make sure that you have the latest code of the code receiver(i.e the Dark Blue box and Light Blue box respectively) and the changes are added after the latest code, otherwise your code changes wont be accepted. It might become clear as you become familiar with git.
So, theory is done and lets get back to practicals.
- Go to https://github.com/openmrs/openmrs-core(Light blue box).
- Click “Fork” button in the upper right. This will create a link as https://github.com/your-username/openmrs-core(Dark Blue box).
- Open your git bash and navigate in your file system where you would like the code to be imported. Clone the fork to your local machine (replace “your-username”):
git clone https:
//github.com/your-username/openmrs-core.git (This will create the Green box)
- Go into the folder just created and set up the “upstream” remote so you can eventually pull changes from the main repository:
git remote add upstream https:
- Fetch and track all branches on remote repositories.
git fetch –all
- 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
- 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.
- Make changes in the local code.
- Add changes to a commit (stage them). To see what files have changed.
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.
- Commit changes.
git commit -m
"Put change summary here (can be a ticket title)"
- Pushing to your fork.
Have you wondered, what happens if there are some unwanted changes in your local code? Simple, just delete this local copy and create another local copy and those unwanted changes are gone!(make sure you save your wanted changes in another file to copy them later in the new local code copy).
What about some unwanted changes in your online code copy? This is not as simple as just creating another copy, you have to learn a lot of git for that that includes resetting, reverting etc. People instead learning all this they again delete their online copy and fork it again.
Though this is a little child like mentality to just push the reset button when not playing the game well, this is a very clean way.
So what is the solution? Branches.
What is a branch in git? it is a sandbox version of the code that you can create, play and delete. It wont affect your main code in any way. So, you can do what you want to i.e delete and create it without having to fork or create a new local copy at another location. You can just switch to another branch from the same location by typing
git checkout branch name
- 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.
git checkout -b TRUNK-
git clean -df
git pull --rebase upstream master
Push the branch to your fork. Treat it as a backup.
git push origin TRUNK-
Step-6: Creating a Pull request:
Before you can open a pull request, you must create a branch in your local repository, commit to it, and push the branch to a repository or fork on GitHub.
- Visit the repository you pushed to
- Click Compare and Review in the repository
- You’ll land right onto the compare page. You can click Edit at the top to pick a new branch to merge in, using the Head Branch dropdown
- Select the target branch your branch should be merged to, using the Base Branch dropdown
- Review your proposed changes.
- Click Click to create a pull request for this comparison
- Enter a title and description for your pull request
- Click Send pull request
This concludes the basics of GIT .