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
h4 headers when converted to plain text. That is:
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)
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
upstream in the git command above could be
ancestor or anything.
Let’s see some examples of pulling changes from upstream to local clone.
git pull upstream master will pull all the branches in upstream to your local working repository.
$ git pull upstream master
* branch master -> FETCH_HEAD
* [new branch] master -> upstream/master
git branch -a to see all the branches.
$ git branch -a
remotes/origin/HEAD -> origin/master
To pull in the
non-breaking-space branch in upstream, run
git pull upstream non-breaking-space
$ git pull upstream non-breaking-space
* branch non-breaking-space -> FETCH_HEAD
* [new branch] non-breaking-space -> upstream/non-breaking-space
Fetching Pull Requests
git fetch upstream pull/ID/head:BRANCHNAME fetches a pull request of
ID from upstream to a
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.
* [new ref] refs/pull/36/head -> SupportElements
In similar fashion, fetch in pull request
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
CONFLICT (content): Merge conflict in src/Html2Text.php
Automatic merge failed; fix conflicts and then commit the result.
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
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.