Git for dummies

From OpenEMR Project Wiki

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


Submit your code for review

  • Now you've done some coding on a custom branch and want to submit it for review (with the goal of getting it included in the main OpenEMR codebase).
  • No code is too small (ie. a quick bug patch) or too big; please do not feel the need to submit "perfect" code. We are just glad to get any contributions, and we will gladly provide a friendly review of your code.
  • It is best to do this 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 mirror repository at 'upstream'.
  • The steps involve updating your local openemr repository, updating your custom branch, and then notifying the OpenEMR developers to review your code.
1. Update your local repository:
git checkout master
git pull upstream master
2. Update your custom branch (fix any conflicts that arise during the rebase before proceeding):
git checkout <your_branch>
git rebase master
3. Publish your custom branch to your public github repository:

If this is the first time you are publishing this branch: 

git push origin <your_branch>

If you have already published this branch previously, then can refresh it with the following command (note the plus sign before your custom branch name): 

git push origin +<your_branch>
4. Let the developers know to review your code by posting an item in the 'Code Review' OpenEMR tracker on sourceforge and posting a message in the sourceforge OpenEMR developer forum (simply provide a link to your published github branch along with a quick explanation of your code).


Try out somebody else's code

  • It is best to do this 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 mirror repository at 'upstream'.
  • The steps involve creating a pointer to somebody else's repository, fetching their repository information, and then collecting the desired code from them.
1. Create a pointer to the other user's repository:
git remote add <user_repo_name> <actual repository address>
(for example to create a pointer to brady's repository, do the following 'git remote add brady git://github.com/bradymiller/openemr.git')
2. Fetch the information from the other user's repository:
git fetch <user_repo_name>
(for example to fetch info from brady's repository, do the following 'git fetch brady')
3. Create a branch that you will put the other user's code into:
git co master
git co -b test_branch
4. 'pull' or 'cherry-pick' the other user's code into your repository (into your test_branch). The decision to use 'pull' or 'cherry-pick' depends on how much you trust the other user. If the other user is updating their repository frequently and correctly then 'pull' will suffice, however the safest route to go is the 'cherry-pick' method especially if planning to commit this code to the sourceforge repository.:

If use 'pull': 

git pull <user_repo_name> <user_branch_name>
(for example to pull a branch of code from brady's repository, do the following 'git pull brady <branch_from_brady_repo>')

If use 'cherry-pick': (SHA numbers of other user's commits can be found in the log of their branch(for example 'git log brady/<branch_from_brady_repo>'). Remember to cherry-pick them in the order they were created.) 

git cherry-pick <sha# of first commit>
git cherry-pick <sha# of second commit, if there is a second commit>
etc.


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).


More information


Advanced Usage

Submit your code for commit (For Privileged Developers)

  • Now you've done some coding on a custom branch and want to submit it for commit to the OpenEMR codebase. Note this is a method for Privileged Developers to fast-track their commit into the sourceforge OpenEMR repository. If you want your code reviewed or you aren't a Privileged Developer then follow the instructions located above instead.
  • It is best to do this 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 mirror repository at 'upstream'.
  • The steps involve updating your local openemr repository, updating your custom branch, and then notifying an OpenEMR Integration Developer to commit your code.
1. Update your local repository:
git checkout master
git pull upstream master
2. Update your custom branch (fix any conflicts that arise during the rebase before proceeding):
git checkout <your_branch>
git rebase master
3. Publish your custom branch to your public github repository:

If this is the first time you are publishing this branch: 

git push origin <your_branch>

If you have already published this branch previously, then can refresh it with the following command (note the plus sign before your custom branch name): 

git push origin +<your_branch>
4. Let the "Integration Developers" know to commit your code by posting a message in the sourceforge OpenEMR developer forum (simply provide a link to your published github branch, and it will be committed within 24 hours).


Committing to the official git repository on Sourceforge (merge method) (For Integration Developers)

  • This is for "Integration Developers" whom have commit access to the sourceforge git repository.
  • 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'.
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. This step is extremely important to ensure your local repository is compatible with the sourceforge repository (otherwise you risk breaking the official sourceforge repository). The following commands will fetch the sourceforge commit information and then ensure you have no local incompatible commits. If the 'git rev-list' command produces any output that means something is wrong, and you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!:
git fetch sourceforge
git rev-list master --not sourceforge/master
2. Checkout your local 'master' branch:
git checkout master
3. Pull the most recent code from the sourceforge 'master' branch:
git pull sourceforge master
4. Rebase your custom branch (fix any conflicts that arise during the rebase before proceeding).
git checkout <your_branch>
git rebase master
5. Merge your custom branch into your master branch.:
git checkout master
git merge <your_branch>
6. Now need to do two sanity checks to ensure you do not break the main repository before you perform the commit operation. First, look at the log and ensure that the applicable number of commits are happening and nothing looks funny (if any oddities/confusion/questions, then post this log in the sourceforge forums before proceeding). Second, run the below 'git rev-list' command; the number of commits you plan to push should equal the number of lines of output you get with this command (if this is not the case, then you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!)
git log
git rev-list master --not sourceforge/master
7. Commit it to the official sourceforge git repository:
git push sourceforge master


Committing to the official git repository on Sourceforge (cherry-pick method) (For Integration Developers)

  • This is for "Integration Developers" whom have commit access to the sourceforge git repository.
  • 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'.
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. This step is extremely important to ensure your local repository is compatible with the sourceforge repository (otherwise you risk breaking the official sourceforge repository). The following commands will fetch the sourceforge commit information and then ensure you have no local incompatible commits. If the 'git rev-list' command produces any output that means something is wrong, and you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!:
git fetch sourceforge
git rev-list master --not sourceforge/master
2. Checkout your local 'master' branch:
git checkout master
3. Pull the most recent code from the sourceforge 'master' branch:
git pull sourceforge master
4. Rebase your custom branch (fix any conflicts that arise during the rebase before proceeding).
git checkout <your_branch>
git rebase master
5. Cherry-pick each of your commits from your custom branch into your master branch. SHA numbers of your commits can be found in the log of your custom branch('git log <your_branch>'). Remember to cherry-pick them in the order they were created.:
git checkout master
git cherry-pick <sha# of first commit>
git cherry-pick <sha# of second commit if there is a second commit>
etc.
6. Now need to do two sanity checks to ensure you do not break the main repository before you perform the commit operation. First, look at the log and ensure that the applicable number of commits are happening and nothing looks funny (if any oddities/confusion/questions, then post this log in the sourceforge forums before proceeding). Second, run the below 'git rev-list' command; the number of commits you plan to push should equal the number of lines of output you get with this command (if this is not the case, then you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!)
git log
git rev-list master --not sourceforge/master
7. Commit it to the official sourceforge git repository:
git push sourceforge master


Committing other user's code to the official git repository on Sourceforge (quick and safe method) (For Integration Developers)

  • This is for "Integration Developers" whom have commit access to the sourceforge git repository, and is the quickest way to commit someboday else's code. This means the other user needs to provide a a branch with their code that is rebased to the most recent official 'master' branch on sourceforge (or github).
  • 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'.
1. Create a pointer to the other user's repository (if you do not already have a pointer for the other user's repository):
git remote add <user_repo_name> <actual repository address>
(for example to create a pointer to brady's repository, do the following 'git remote add brady git://github.com/bradymiller/openemr.git')
2. This step is extremely important to ensure your local repository is compatible with the sourceforge repository (otherwise you risk breaking the official sourceforge repository). The following commands will fetch the sourceforge commit information and then ensure you have no local incompatible commits. If the 'git rev-list' command produces any output that means something is wrong, and you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!:
git fetch sourceforge
git rev-list master --not sourceforge/master
3. Checkout your local 'master' branch:
git checkout master
4. Fetch the information from the other user's repository:
git fetch <user_repo_name>
(for example to fetch info from brady's repository, do the following 'git fetch brady')
5. 'cherry-pick' the other user's code into your 'master' branch. (SHA numbers of other user's commits can be found in the log of their branch(for example 'git log brady/<branch_from_brady_repo>'). Remember to cherry-pick them in the order they were created.) If the cherry-pick's do not work then ask the other developer to produce a rebased branch, and then try again:
git cherry-pick <sha# of first commit>
git cherry-pick <sha# of second commit, if there is a second commit>
etc.
6. Now need to do two sanity checks to ensure you do not break the main repository before you perform the commit operation. First, look at the log and ensure that the applicable number of commits are happening and nothing looks funny (if any oddities/confusion/questions, then post this log in the sourceforge forums before proceeding). Second, run the below 'git rev-list' command; the number of commits you plan to push should equal the number of lines of output you get with this command (if this is not the case, then you need to get help from the sourceforge developer forum to fix your repository before proceeding!!!!)
git log
git rev-list master --not sourceforge/master
7. Commit it to the official sourceforge git repository:
git push sourceforge master
Retrieved from "https://www.open-emr.org/wiki/index.php?title=Git_for_dummies&oldid=6586"