Have you ever tried to contribute to someones project on GitHub ? If you ever have done this you will know how hard it is to work Github , if it is your first time with git.
This is my experience of contributing to Open source Organization (FOSSASIA) on GitHub. And What I have learned from them.And this blog post contains commands to do most essential git operations.
Here I’m going to describe all the things I learned about git and GitHub from the sketch .
How to do contributions to others repository?
If you need to contribute to others repository. first you need to do is “Fork” it.you can fork it by just clicking the fork button which is in top right corner of repository that you need to contribute.
By forking you can get a copy of the project to your account. you can see these forked repository list on your profile.
After you Forked it to your account you need to get it to your local machine. To get that you need to clone it.
How to Clone a Forked git repository.
to clone your repository on your local computer you need to have git installed on your machine.
you can install git in following ways.
install git on ubuntu: go to your terminal and run these commands one by one
sudo apt-get update sudo apt-get install git
install git on Mac OS X: go to this url and install it.
To check whether git is installed properly run this command and it will show your current git version.
If it shows git version , now you need to add your GiHub account details.If you do not add your email like this, GitHub identify you as a different user.Contributions you do, will not recognise by GitHub.
(use the same email address you have used in GitHub account)
git config --global user.name "Your name" git config --global user.email "email@example.com"
Now you are ready for git operations.
go to your repository > clone or download> copy the url
open your terminal and run this command.
“https://github.com/isuruAb/susper.git” url should replace with your repository web URL
git clone https://github.com/isuruAb/susper.git
and it will take a clone of the repository.
now go to the inside the directory(folder) by running this command ( it makes new folder by your repository name )
now you can edit code by using your favourite editor. I’m have done little change in “README.md” file
run this command to see which files have changed.
if we need to discard changes that you have done to that file you need to run this command.
git checkout -- README.md
git checkout README.md
If you have changed multiple files and you need to discard all these changes. you have to run this command.
git checkout .
If you need to add your changes to your repository that we cloned earlier. we have to run these commands.
If we done changes to multiple files, we have to choose changes which need to be added into cloned repository.
git add README.md
if we need to add all changes we can add all by this command.
git add .
next, you have to add commit message.before we push our changes to Forked repository we have to write a log about changes.That task is doing by “commit” command.
use this command for add commit message.
git commit -m "your commit message"
Sometimes you need to add commit title and description for that you have to do this. you can use multiple “-m” and add description.
git commit -m "your commit message" -m "commit description"
Shortcut for commit
we can do add all modified files and commit by below one command.
git commit -a
after you execute this command you will get a file to edit. press “i” on key board to change to insert mode.
first line you add is your commit’s topic.other lines after first line are description. after you typed all you need to mention in commit. like this,
press “esc” button on keyboard and type “wq” . (wq is for write and quite from file)
Now we have added our changes to the log. If you need to see the log you can do it by this command
press “q” on key board to quite from the log.
add these changes to Forked repository (push).
you can push these changes by using this command.
git push origin master
these are the meanings of this command’s keywords
origin – your forked repository
master- branch that you need to push your changes in my case it is master
If it ask you for username and password . type email address as your username.
now you can see it pushing…. after it finishes check the Forked repository > commits
you will see those pushed changes.
Normally we fork a repository when we want to build our own customised version of that software or If we want to contribute the software by codes/documentation.
Most of organisations have list of issues on GitHub repository that reported by users and contributors .Some organisations do not accept pull requests via GitHub and they do not maintaining GitHub for issue tracking.some of them are maintaining separate issue trackers like jira, bug zilla .
If the organization accept pull requests from GitHub you just need to do this.
Make a pull request
go to Forked Repository > Pull requests > New pull request
in new window click the “Create pull request”
in this page you will see there is 4 drop down menus to select your branch and repository that contains commits to be pulled(called head fork- your repo | compare-brach contains new changes) and base fork( original repository) and base branch(branch that new changes to be applied)
in new window add your pull a topic in description mention the issue number by typing “#issue number here” it will give you suggestions as well. when you creating a pull request there are few best practices contributors follow in FOSSASIA. there should be a screenshot and preview link . after all click “Create pull request” button.
If your pull contains several commits.it will show like this on your pull request.
if base repository (original repository) maintainer accepted this pull request it records as 3 commits . If we can make one commit from all these commits, it is easy to refer in future because one particular issue solved in one commit. so we have to squash these commits.
go to your project directory from terminal and run this command.
In my case there is 3 commits in my pull request. so what we need to to do is make one commit from last 3 commits. to do that we can run this command.
git rebase -i HEAD~3
“rebase” is use for rewrite history
“-i” is for work interactively
“HEAD~3” is for grab last 3 commits.
after executing this you will get this kind of output
in this we are going to combine last two commits with first commit so we have to change “pick” to “squash” in this. press “i” on key board and turn on the insert mode.then change it like this.
then “esc” then type “:wq” and press enter to save and quite.if it ask you whether you need to write or not type y.
then it will agin show commits we squash .in this stage we can change commit messages if we need. we can just leave it as it is by “esc” > “:wq”> enter
now you need to push it to the forked repository. (then it automatically update our pull request if it is not merged to base repo)
run this command to push this changes.
git push -f origin master
in my case i push to master branch .your will be different.
“-f ” is for force push ,force push wants to use after change something or reverting something.
Let’s assume that you need to undo changes you have committed to your repository.
just run this command
git reset --hard HEAD~1
we use “–hard” to delete commits if you need to get your commits to staging area you can use this:
git reset --soft HEAD~1
if you need to change the commit message of a commit that you have pushed to repository.
you can change your commit message using this command.
git commit --amend
now it will open the editor. edit the commit message as you want (you need to press i for enable insert )then after “esc” > “:wq” >press enter
to check the commit message see the “git log”
assume that, while we are committing to our local repository, base repository also got few new commits from merged pull requests.If you are hoping to contribute continuously you have to get new commits to your forked repository. to that you have to run these commands .
Rebase from base repository
git remote add upstream https://github.com/fossasia/susper.com.git
here “upstream” is just a name you can use any name for that.
url is your base repository web url
git fetch upstream
this fetch all changes from base repository
git checkout master
move to branch you want to apply new changes
git rebase upstream/master
in this command.changes apply to the your local master branch from upstream / master branch
git push -f origin master
push all changes to forked repository
these few git commands are enough for contributing to git repository. but you need to utilise best fit command for relevant situations. It is all for today . see you soon.cheers.