Github Beginners guide - Fork and submit Pull Request

Today's post is about quick start guide on github. This article is more focused on git add, git commit and git push commands.

1. First you need to download and install latest version of the Git.
2. Once you completed installation, first ever thing to do is setup the configs. Open a new terminal and type;

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS ON GITHUB"

This will tell the Git your name and the email address associated with the Git account hence your commits properly labeled. And your email address is not publicly available under the default settings.

---

Now we have completed the basic steps on our Git. Now we need to fork the repository. A fork is a copy of a repository. It allows you to experiment the code do the bug fixes and submit it to the main repository. Unlike SVN, this workflow allows you to submit bug fixes for well-knows repositories even you do not have the permissions to commit directly. We need to;

1. Fork from the original repository
2. Create a local clone of your fork
3. Do the fix/change on your clone
4. Commit changes to your fork
5. Submit a pull request to the owner of the original repository

For the demonstration purposes we will be using the Spoon-Knife test repository that’s hosted on GitHub.com that lets you test the Pull Request workflow.

1. Fork from the original repository

1. On Github, navigate to the original repository.
2. On the top-right corner click on the fork.

Done! Now you have a copy of the original repository on your account. You can confirm it by navigating into your dashboard.

2. Create a local clone of your fork

Now we need to create a local clone on our fork and keep our fork synced.

On Github account dashboard; you will find the repositories that your have forked. Click on the fork that you created on the previous steps.

On the right-sidebar of your fork repository; click on the 'copy to clipboard' button to copy the clone URL.

Open up the terminal application. Navigate into the place of your computer, where you need to create the clone. For example, I will create a new folder for the clone.

mkdir ~/GitRepo
mkdir ~/GitRepo/SpoonKnife
cd ~/GitRepo/SpoonKnife

Now we are ready to clone. You can use, clone <CLONE_URL_FOR_YOUR_FORK>. This URL should be similar to the "https://github.com/YOUR_USERNAME/YOUR_FORK.git".

clone git clone https://github.com/YOUR_USERNAME/Spoon-Knife.git

Press Enter. Your local clone will be created.

3. Do the Fix/Change on your clone

Now you can do the changes you want for the files on your local clone. Once the changes are done, we need to sync the changes into our fork repository.

4. Commit changes to your fork

A commit is a snapshot of your work. To do a commit; navigate to your local clone.

cd ~/GitRepo/SpoonKnife

you can see the file changes by following command.

git status

This will show up the changes not staged for commit. I have modified the build.xml and pom.xml files. Untracked files are usually newly created files on the local repository. Since I am using MAC OS X, it is automatically creating .DS_Store to track view options on the folders.

NOTICE: You can use `git clean .` (Note the dot) or `git clean <FILE_PATH_AS_SHOWN>` to remove untracked files. Also, `git clean -n ` to do a dry-run and see what files would be removed before actually get removed.

However, there can be newly added config file, or resource that we need to add into our commit other than .DS_Store. So, we can ignore these files by following;

echo ".DS_Store" >> ~/.gitignore

This will ignore all .DS_Store files for the future commits.

Before adding, you can check your changes line-by-line by issuing, `git diff <FILE_PATH_AS_SHOWN >`. This will help you to verify, you are not submitting invalid or unintended changes such as indenting issues.

Now we need to add our modifications for the commit. Simply add, git add < FILE_PATH_AS_SHOWN >.

For example,

git add index.html
git add newfile.txt

NOTICE: You can issue `git add .` to add all files for the commit. If you screwed up adding files, you can use `git reset .`(Note that dot means all files). 

Once you added files for your commit. you can use `git status` to see your changes.

git status

This will show already added files with the green color.  You can simply add the commit into your master branch. But it is good practice is to keep the master branch clean. By clean, it is means without any changes, like that you can create at any time a branch from your master. Therefore, It is recommended, A separate branch for commit a bug or a feature. 

In order to create a new branch and switch into new branch;

git checkout -b change-msg

git branch

For more details on git branches refer this tutorial.

Now you can commit these staged changes to your repository. Use git commit -m "<YOUR_COMMIT_MESSAGE>".

Note that the commit message is important to track what you have done on the particular commit. For example you might fix a JIRA issue. Therefore, you can add JIRA ticket number for ease of tracking.

git commit -m "Fixing JIRA SK:XXX - Changing the message"

Now we need to push our local clone changes into our remote fork. We need to create an upstream for this; `git remote add upstream <CLONE_URL_FOR_ORIGINAL_REPO>`.Notice that CLONE_URL_FOR_ORIGINAL_REPO would be similar to a URL like "https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git.

git remote add upstream https://github.com/octocat/Spoon-Knife.git

you can verify the remote links by, "git remote -v";

git remote -v
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

In this case;

git remote -v
origin https://github.com/YOUR_USERNAME/Spoon-Knife.git (fetch)
origin https://github.com/YOUR_USERNAME/Spoon-Knife.git (push)
upstream https://github.com/octocat/Spoon-Knife.git (fetch)
upstream https://github.com/octocat/Spoon-Knife.git (push)

If you screwed-up, you can use "git remote remove <URL_NAME>". For instance, "git remote remove upstream".

Now issue the following command;

git push origin change-msg

Note that "git push" might work on most of the time. But here, we have created a new branch in our local repository. Hence we need to push our code changes into that branch.

This will push your changes into the remote repository and output something similar to the;

Now goto your Github account and navigate into the forked repository. If everything went fine, when you navigate into `master` branch and the latest commit is still by octocat.

And on the newly created branch, "change-msg"; it should be your commit.

5. Submit a pull request to the owner of the original repository

Now we have pushed our changes/ bug fixes to the forked repository. By submitting a pull request you are asking the owner of the repository to merge your repository with the original. To do that, on Github account dashboard; navigate into your forked repository. On the right hand click on "Pull Requests" tab.

On the "Pull Requests" tab, click on "New Pull Request".

At the beginning it will show "There isn't anything to compare". This is because we are comparing our master branch with original repository. In order to create a pull request from our new branch, you should select the newly created branch which is "change-msg" in our case.

Now you will see your commit changes and click on "Create Pull request".

Add some meaningful details for the `title` and `comment` for the pull request. Before you send the pull request you can verify your changes, on the below of your pull request. Then you can click on "create pull request".

What would happen if the owner of the repository asked for modifications?

In this case, you don't have to cancel your pull-request and start a new request. You can submit the follow-up commits into the same branch(in this example, change-msg branch), Then it will be appeared on the same pull-request.

Links

[1] Guides.github.com, (2014). Forking Projects · GitHub Guides. [online] Available at: https://guides.github.com/activities/forking/ [Accessed 22 Feb. 2015].
[2] Help.github.com, (2015). Using pull requests - User Documentation. [online] Available at: https://help.github.com/articles/using-pull-requests/ [Accessed 22 Feb. 2015].
[3] Help.github.com, (2015). Syncing a fork - User Documentation. [online] Available at: https://help.github.com/articles/syncing-a-fork/ [Accessed 22 Feb. 2015].
[4] George, S. (2015). Kunena/Kunena-Forum. [online] GitHub. Available at: https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches [Accessed 22 Feb. 2015].

SHARE SHARE SHARE

Anonymous

• 
• 
• 
• 
•