Getting Good with Git & GitHub

I was recently involved in building an email marketing service (think MailChimp) where we needed to automatically send alongside HTML campaigns, their plain text version.

I was assigned to get this feature built out. To accomplish this, I tested a lot of HTML to text libraries and finally, settled for this by Jevon Wright.

Using soundasleep/html2text repository, we will be learning how to fork a Git repository on GitHub, make improvement on a fork, submit pull request, fetching, pulling and merging in changes from remote.

Forking & Improvement

A fork is a copy of a repository while forking is the act of copying a repository to freely experiment with changes without affecting the original project.

First off, head over to the GitHub repository and fork it.

Forking GitHub repository

Clone the fork locally to your computer with the following command where W3Guy my GitHub organization username that contains the fork.

Cloning Git repository

We can now make your improvement to the library. I advice you always create a topic branch for each feature you are to implement; but for simplicity sake, our changes will be made directly on our master branch.

Let’s improve how our fork displays h1 to h4 headers when converted to plain text. That is:

Becomes

With that been implemented, commit and push the changes to your fork GitHub repository.

Submitting Pull Requests

Pull requests let you tell others about changes you’ve pushed to a repository on GitHub. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

To submit your changes to upstream (the parent repository where the fork was derived from), go to your fork GitHub repository and click the New pull request button.

On the page that will be displayed next, click the green Create pull request button.

Create pull request on GitHub

Enter a title, description of the pull request and then submit.

Submit pull request

Pulling, Fetching, Merging and Pushing

To be able to pull changes from upstream to the local clone of your fork, you must add the upstream as a remote as follows:

**Note:** upstream in the git command above could be parent, ancestor or anything.

Let’s see some examples of pulling changes from upstream to local clone.

Running git pull upstream master will pull all the branches in upstream to your local working repository.

Run git branch -a to see all the branches.

To pull in the non-breaking-space branch in upstream, run
git pull upstream non-breaking-space

Fetching Pull Requests

The upstream soundasleep/html2text has some really great pull requests submitted that i wanted our project to take advantage of such as this, this and this.

The command git fetch upstream pull/ID/head:BRANCHNAME fetches a pull request of ID from upstream to a BRANCHNAME branch.

For example, git fetch upstream pull/36/head:SupportElements will fetch the reference to the pull request of ID number 36, creating a SupportElements branch in the process.

In similar fashion, fetch in pull request 31 and 38.

Merging Branches

To incorporate commits in SupportElements into our fork, checkout the master branch and merge the branch into it like so.

Merging SupportElements branch to master result in a merge conflict. To skip / fix this error, open src/Html2Text.php file, fix the conflict and after which, stage the changes and commit.

After making changes to a branch, be sure to always push them to their remote branch. For example, say we created a new branch featureA and made some commits; push the branch to remote as follows where -u or alternatively, --set-upstream setup the local featureA branch to track their remote counterpart.

Conclusion

Git is a tricky tool to get your head around. Knowing the commands is one thing, but knowing how to use them is another.

Mastering of the various Git commands and how to effectively utilise them comes with time and practice. I hope i have been able to give teach us at least it basics or primer that will sufficiently help us version control our codes.

If you have any question or suggestion to improve this article, be sure to let us know in the comments.