Git for dummies

Overview of Using git in OpenEMR

The goal of these instructions are to get you started using git in OpenEMR as quickly as possible, and to avoid losing any of our valuable developers to suicide. Once you master the below information, then should be easy to at least get by and make patches.

Step 1: You too can have your very own public openemr repository on github.com!

1. Sign up for an account on github.com

2. Make a key, and put it in your gihthub.com account

3. Make a fork from the main openemr github repository at: http://github.com/openemr/openemr

Step 2: Now, set up your local repository

1. Install a git client on your local computer.

2. Clone your github repository:

git clone git@github.com:yourRepositoryName/openemr.git openemr

• (now your github repository is called 'origin')

3. Set up a connection to the main openemr respository:

git remote add upstream git://github.com/openemr/openemr.git

• (now the main openemr github repository is called 'upstream')

4. All the pieces are now set up. You have your local repository that is connected to your public github repository(origin) and is connected to the official openemr github repository(upstream)

Step 3: Feeding your repository

1. The 'master' and 'rel-320' are sacred branches that should not be modified by mere mortals. Never ever manually modify these branches on your local or github repository(origin). These can only be feed by the official openemr github respository(upstream).

2. First, feed your local repository(from upstream):

git checkout master
git pull upstream master
git checkout rel-320
git pull upstream rel-320

• (Now your local repository sacred branches are feed by most current official OpenEMR code)

3. Second, feed your github repository:

git push origin

• (This command will feed your public github repository with updated code from your local repository; note there is no need to mention specific branches)

4. That's it. You now have the most current codebase in your local repository and your github public repository. I recommend repeating these steps frequently to keep your repositories well feed.

Tenet 1: Branches are Supreme

• You may ask: If I can't work in the master or rel-320 branches, then where do I work in. The answer is your make new branches and put your work in there. Make a branch for every new project, bug fix, etc. To make a branch off of 'master' and go into it do the following:

git checkout -b newbranchname master

• Then do your work in this branch for your project. Recommend committing often via :

git commit -a

• You can upload your branch to your public github repository via:

git push origin newbranchname

• (Now others can see your branch and code, and can try it out)

• You can also create an easy patch of your branch(ensure all changes have been committed)(I am assuming that the workbranchname was originally branched off master):

git checkout workbranchname
git format-patch master

• Another thing, always commit before moving to another branch.

Tenet 2: My custom branch and code is now out of date... time for rebase...

• What happens to my custom branches as the master and rel-320 continue to get updated (via step 3 above)? Your patches and branches get out of date!!
• This can be dealt by doing the following):

1. rebase your outdated branch (I am assuming that the workbranchname was originally branched off master):

git rebase master workbranchname

2. replace your outdated branch from your public git repository(origin)(yes, the plus-sign is supposed to be there):

git push origin +workbranchname

Putting that OpenEMR code to work

• Now you want to test the branch that is currently checked out. I recommend never running OpenEMR directly from your git repository. Instead, it is best to copy the current checked out git copy to your web server directory and test it there. I have posted two scripts below that will do this automatically for you (hopefully a windows scripting guru will post a windows script soon).

• Ubuntu script
• Mandriva script

Committing to the official git repository on Sourceforge

• This is for developers whom have commit access to the sourceforge git repository (we give commit access to developers after they submit several patches).
• It is best to do it from the repository that you created in the above tutorial and ensure you are following the steps and tenets above! This means all work is done in custom branches, and that you have not manually touched the 'master' or 'rel-320' branches, which are only updated from the official github repo at 'upstream'.
• First set up the pointer to the sourceforge repo in your local repository with the following (<Your personal sourceforge ssh git login> can be found here: http://sourceforge.net/scm/?type=git&group_id=60081):

git remote add sourceforge <Your personal sourceforge ssh git login>

• Then when you have a custom branch on your local repository ready to commit to the sourceforge git repository, do the following:

• First, check out the master branch:

git commit master

• Second, pull most recent code from the sourceforge master branch (note we are using sourceforge instead of the github official mirror(as used above), since the github official mirror may be out of date since it is only updated every 30 minutes):

git pull sourceforge master

• Third, merge your custom branch (contains your commit(s)) into your master branch. If you've kept your local official branches (via pull) and custom branches (via rebase) updated as described in above tutorial, then this should be straighforward without any conflicts.:

git merge <your_branch>

• Fourth, as a sanity check, looks at the log and ensure that the applicable number of commits are happening and nothing looks funny (if any oddities/confusion/questions, feel free to post this log in the sourceforge forums before moving on to the next irreversible step)

git log

• Fifth, commit it to the official sourceforge git repository:

git push sourceforge master

More information

• Check out Stephens documentation of git
• Here are links on delicious I compiled while learning how to use git
• And there's always google