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!

Changing permissions (ownership) of directory or file including access permissions in Ubuntu

Sometimes users may need to change the permissions of a directory or a file in order to prevent of unauthorized accesses.If sometimes you need to give access to some user on file or a directory which owns by the root, then you need to give the permission to that particular user.Let's see how this goin to work.

Changing the ownership of filename

To change the ownership of a single file, you can run following command with specifing username and user group. 

         sudo chown <username>:<groupname> <filename>

         example :

                        sudo chown harsha:harsha textfile.txt

To change the ownership of a single file with only specifying username only you can run following command.

          sudo chown <username> <filename>

          example :
                        sudo chown harsha textfile.txt


Changing the ownership of directory

To change the ownership of a directory you can following command which recursively apply the ownership changes to sub directories and files also.

         sudo chown -R <username>:<groupname> < directory >

         example :
                              sudo chown harsha:harsha textDirectory/


By only username

         sudo chown -R <username> < directory >

         example :
                        sudo chown harsha textDirectory/


Access permissions

In the above posts I have describe how to change the ownership of a directory  or file.But for a movement if you change the ownership to root and let only root can access the directory and files you may need to change the access permissions to particular directory.

If you want to get a quick understanding about the permission matrices which  show the read write and execute permissions in Linux I recommand this link will provide better understanding.Numbers coming along with "chmod" command are the way of expressiong permissions.

How To change permission of file folder so only root can access open it

Step 1

•  Change the ownership of the directory / file to root

       sudo chown root:root <direcotry or filename>
         
         example:
                sudo chown root:root textDirecotry/
Step 2             

• Change the permissions so that only the owner of the file can read/write/execute it.(There is no point of applying permission for all the directories,cause if particular user cannot access root directory,then user won't be able to access the files and directories inside the root directory)

                 sudo chmod 700 <direcotry or filename>
        
         example:

                              sudo chmod 700 textDirecotry/

If file is a executable file you may give "sudo chmod 700" instead of "sudo chmod 600".

Details about permission numbers

• chmod 700 

The directory’s owner can read or write files in that directory as well as change to it.
All other users (except root) have no access.

• chmod 771 

Same as for the owner. All other users can change to the directory, but not view or change files
in the directory. This can be useful for server hardening,where you prevent someone from listing directory contents,but allow access to a file in the directory if someone already knows it’s there.

• chmod 777 

All permissions are wide open.

• chmod 0000 

All permissions are closed. Good to protect a directory from errant changes.
However, backup programs that run as non-root may fail to back up the directory’s contents.

• chmod 666 

Open read/write permissions completely on a file.

• chmod 644 

Only the owner can change or delete the file, but all can view it.

The first 0 in the mode line can usually be dropped (so you can use 777 instead of 0777).
The -R option is a handy feature of the chmod command. With -R, you can
recursively change permissions of all files and directories starting from a
point in the file system. Here are some

examples:

$ sudo chmod -R 700 /tmp/test Open permission only to owner below /tmp/test
$ sudo chmod -R 000 /tmp/test Close all permissions below /tmp/test
$ sudo chmod -R a+rwx /tmp/test Open all permissions to all below /tmp/test

Reference:http://fosshelp.blogspot.com/2011/06/how-to-change-permission-of-file-folder.html

How to start Apache Tomcat or Jetty Server using maven plugin in remote debugger mode in Ubuntu/Linux

Debugging is one of major requirement of a software debugging process.To fix a bug developer may need to find the exact bug and fix it.Debugging provides efficient way to analyse the variables and execution path of the code.Apache tomcat and Jetty are two of well known server which act as a container for web applications.So debug a web application server need to start in debugger mode.Here simple steps to start tomcat in debugger mode.

In bash console of Ubuntu execute following arguments.

Apache tomcat debugging mode

export JPDA_ADDRESS=8000
export JPDA_TRANSPORT=dt_socket
bin/catalina.sh jpda start

Done!
User can remotely connect through the port 8000 for debug the application!


Jetty debugging mode

Jetty server can start through maven plugin.So in order to enable remote debugging in jetty user can follow the following way.
Just two steps.

step 1
export MAVEN_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE - Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

step 2
mvn jetty:run

Done!

Server listen on port 8000 until debugging client connecting to the server.
Simple as that!