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.
Clone the fork locally to your computer with the following command where W3Guy my GitHub organization username that contains the fork.
git clone https://github.com/W3Guy/html2text.git
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:
<h1>WordPress</h1>
Becomes
** WordPress -------------------------------------------------
With that been implemented, commit and push the changes to your fork GitHub repository.
$ git commit -am "modified header display" [master 38992da] modified header display 1 file changed, 5 insertions(+), 46 deletions(-)
$ git push Counting objects: 12, done. Delta compression using up to 4 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 707 bytes | 0 bytes/s, done. Total 4 (delta 2), reused 0 (delta 0) To https://github.com/W3Guy/html2text.git 2a5fd94..38992da master -> master
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.
Enter a title, description of the pull request and then submit.
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:
git remote add upstream https://github.com/soundasleep/html2text.git
**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.
$ git pull upstream master From https://github.com/soundasleep/html2text * branch master -> FETCH_HEAD * [new branch] master -> upstream/master Already up-to-date.
Run git branch -a to see all the branches.
$ git branch -a * master remotes/origin/HEAD -> origin/master remotes/origin/master remotes/origin/non-breaking-space remotes/upstream/master
To pull in the non-breaking-space branch in upstream, run
git pull upstream non-breaking-space
$ git pull upstream non-breaking-space From https://github.com/soundasleep/html2text * branch non-breaking-space -> FETCH_HEAD * [new branch] non-breaking-space -> upstream/non-breaking-space Already up-to-date.
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.
$ git fetch upstream pull/36/head:SupportElements remote: Counting objects: 8, done. remote: Total 8 (delta 4), reused 4 (delta 4), pack-reused 4 Unpacking objects: 100% (8/8), done. From https://github.com/soundasleep/html2text * [new ref] refs/pull/36/head -> SupportElements
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.
$ git checkout master Switched to branch 'master' Your branch is up-to-date with 'origin/master'.
$ git merge SupportElements Auto-merging src/Html2Text.php CONFLICT (content): Merge conflict in src/Html2Text.php Automatic merge failed; fix conflicts and then commit the result.
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.
git push -u origin featureA
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.