GIT basics for start working on a open source projects

GIT is kind of pretty amazing version control system which allow user to manage their software development in a very handy manner.Subversion was another popular version control system which was one of another well known piece of software.Since GIT become a handy piece of software the popularity among the version control systems move towards to GIT.For get deep understanding about the GIT I recommand this link to study about GIT.GIT has very flexible source code managing architecture which allow users to manage and version their source codes.
                                                                                                         During this tutorial I try to give an brief idea about using GIT for contribute open source software development.I assume you have basic GIT knowledge which you can get from any tutorial.

Github is a GIT deployed environment which allow you to deploy your source code.This allow users to go through the publicly available repositories and start contributing to existing opensource software.Make sure you signup for a account in Github.Let's start!.

Fork a repository

Fork a repository means taking a snapshot of opensource software source code which is available publicly in a Github account which manage by set of people to your own repository which is manage by Github.You  only have read access to the source code of the publicly available open source software. After you forking it's like your own repository which you can do changes to the source code in your repository.

Forking from openMRS reporting module which is publicly available in Github

Above image I do as example.I'm going to fork from this link.You can see the fork button in right hand top corner which allow you to simply fork the repository to your own repository on Github.After words you direct to your own repository location.

After forked

After you can see your own repository.Then you can clone it by your Git client of your computer.The cloning link is the one which appear in the image after "Git Read-Only" phrase.

Note: After forked you need to manually update the branches of your fork with original open source repository.After forked there won't any automatic communication happen with open source software code repository and your forked one.You only take snapshot of the open source software code base which create a copy of the current instance of the repository to your Github repository.

Now you can think you have your own repository of open source code base at that instance.

Cloning

Now you take a copy of your own repository to your working environment which is your computer.

Command :

       git clone <repository location>

                 example:

                                   git clone https://github.com/harsha89/openmrs-module-webservices.rest.git

Now you have your own snapshot at your computer.Let's start working on it.

Note: Always origin is point to the location where user clone the repository from remote GIT location

Useful commands

• git remote -v 

          This command will output the locations of origin and other remote repositories.

git remote -v output

• git branch -a

          This command will output the all the branches in your local git repository where star ("*")  

           symbol points to currant working branch.

git branch -a output

• git fetch --all

          This command will fetch the all the branches from remote repositories to your local repository.

• git remote add {name}  {url}

          This command is very useful in GIT.This allow users to add remote repositories to the user local    

          repository which is at user's computer.By default cloned repository has one remote location 

          which is known as origin.But when user need to add repository location where user fork the 

          source code for get the on going changes of the original repository,user needs to add that location   

          to their local GIT repository. 

        example:
                           git remote add upstream https://github.com/openmrs/openmrs-core.git

• git remote set-url {remote name} {new location}

         This also another important command in GIT.Think there is a situation user want to change the 

          remote repository location of a particular remote.So above command comes to play at that 

          movement.

         

         example:

                      git remote set-url origin ssh://newhost.com/usr/local/gitroot/myproject.git

• git remote rm {remote name}

           When user need to remove a remote git repository location.User needs to use this command.

          example: removing remote name as upstream

                        git remote rm upstream

• git reset --hard

           This command will discard any changes in your working branch.

• git pull --rebase {remote name} {branch name}

         This command used to get the changes of the user specified remote and the user specified  

          branch.Command the '--rebase' option reverts any of your commits which are not in user 

          specified remote and the branch then fast forwards your local branch to user specified remote and 

          the branch 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.

         

          example: Pulling from remote known as upstream and branch known as master

                              git pull --rebase upstream master

Continue on opensource software contributing

                       

          Most of the time for contribute to the open source software you may need to work on issues which are known as tickets.Those are can be bugs or new features of the open source software which are manage by a issue tracker.If you want to start on working ticket or experiment something on your own,you better to make a new branch from existing branch in the repository.Most of the time it will be the master branch which need to be branch again.The new branch can be work as new independent branch where changes on that branch will not effect to the other branches.Let's see how it going.

1. You need to create new branch from the existing branch

           command: git checkout -b {new branch name} {existing branch}

           example :git checkout -b working_branch master

     2. Cleaning the currant branch  

         

           command: git clean -df

     

     3. To proceed,user need to be up to date with remote original repository branch.Update with the  

         remote original repository known as upstream and the branch master
  

           command : git pull --rebase {original remote repository} {branch name}

           example:Update with the  remote original repository known as upstream and the branch           

                                master

                                   git pull --rebase upstream master

     

Now you have a brand new branch which you can work on your own.

    4. If you want to push the created branch to your remote repostory which is Github you can execute  

        following command.

        

         command  :git push {remote name} {newly created branch name}

         example  :git push origin working_branch

   5. Now user can work on their own on the newly created branch.I

   6. If user wants switch between branches they can execute following command

       command:git checkout {branch name}

       example:git checkout master

  7. If you have uncommitted changes and git refuses to merge, you can stash your changes, perform a   

      pull and then unstash them.Follwong commands need to be executed.

      commands:

                           git stash
                           git pull --rebase upstream master

           git stash pop

  8.After finishing your works you can push the changes into your branch in the repository.

Create the pull request

After user user done with the changes.User needs to make a pull request to the original branch.This pull request indicates your changes done in the source code and let commiters of original repository of open source software to evaluate the quality and the accuracy of user's changes and commit it to the original repository.

Pull requesr

Above image you can see the pull request button which you allow to create the pull request.Follow the steps after you clicking it.

Deleting the branch

After you have done your works you may merge the created branch into the your master branch or simply update your master branch after user's changes applied to the original repository branch and delete the newly created branch.

1. Delete the branch need to you to switch from currant branch to another branch.Then execute following command

           command: git branch -D {newly created branch name}

      example: git branch -D working_branch




    2.Push changes to the remote  to delete the created branch from remote repository too.

             command: git push {remote} :{newly created branch name} 

             example: git push origin:working_branch
Done!