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 code, get code reviewed, and commit to the main sourceforge git repository.

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 github 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 public github repository. These can only be feed by the official openemr github repository.

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 and public github 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 master
git checkout -b newbranchname

• 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 review and test your code)

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 checkout workbranchname
git rebase master

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

git push origin +workbranchname

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 sourceforge repository at 'sourceforge' or official github mirror repository at 'upstream'.
• First set up the pointer to the sourceforge repo in your local repository with the following (<Your personal sourceforge ssh git link> can be found here: http://sourceforge.net/scm/?type=git&group_id=60081):

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

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

1. Fetch the sourceforge information (this will collect all the commit information):

git fetch sourceforge

2. Check out the master branch:

git checkout master

3. Pull most recent code from the sourceforge master branch:

git pull sourceforge master

4. Ensure your local 'master' branch is exactly the same as the official 'master' branch (if any output is generated from the below command, that means something is wrong, and you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!):

git rev-list master --not sourceforge/master

5. Rebase your custom branch (fix any conflicts that arise during the rebase before proceeding).

git checkout <your_branch>
git rebase master

6. Merge your custom branch into your master branch.:

git checkout master
git merge <your_branch>

7. As a sanity check, look 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

8. Commit it to the official sourceforge git repository:

git push sourceforge master

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

More information

• A very nice article describing the 'merge' and 'rebase' commands: Merge vs Rebase: A Deep Dive into the Mysteries of Revision Control.
• Check out Stephens documentation of git
• Here are links on delicious I compiled while learning how to use git
• And there's always google