My name is Hassan McKusick, you can also find me by the moniker @hmcq6. I've been a professional Software Engineer for a little over 7 years, and I've been a hobbyist programmer for over 18. I've made over 1,600 commits on 700+ pull requests with a ~90%+ merge rate.
Since 2011 I have used git for every professional project and serious side project that I've worked on. The following details my normal git flow, and will include tips to make using git easier and more effective.
Right off the bat I'd like to acknolwedge that there are many ways to use git/github. I'm not claiming my way is the only way, this process however has always worked for me.
To begin we need to create or clone a git repository. If the project you're cloning does not accept contributions from unauthorized users, make sure to fork the project as well. I consider these topics out of the scope of the topic of this article, and will move forward under the asumption that you are comfortable and familiar with basic git operations. (ex. checkout, branch, add, ...)
The first step in proper git hygiene is starting from a clean branch. If you want a building to last 1000 years, build it on a good foundation. If you want your food to taste good, use fresh ingredients. If you want your pull request to get merged, start from a clean branch.
Before you write a single line of code, you must make sure you're working with the most up to date version of the repository. First ensure that origin/master is up to date, if you're branch is forked from another repository make sure that origin/master matches upstream/master. If you start from an out of date reference, you may find that you're missing required pieces of code. You may be forced to duplicate work that was already done, or you may find that you have conflicting changes that will require manual resolution. There are two primary sources of merge conflict, and the easiest one to avoid is starting from an unclean, or out of date reference*.
git stash && git clean -f && git pull && git checkout master
This series of commands will:
stashall the changes to files currently in the repository.- force
clean(or delete) all files not commited to the repository. pullthe latest reference for mastercheckoutthe master branch
At this point there are either two paths you can follow. Ultimately it does not matter whether steps number 2 & 3 are creating you're new branch, or adding your code changes. They are interchangeable, let it happen natrually. The only thing to focus on here is that you must create a new branch before you commit. It doesn't matter if you add the changes to master and then switch to a new branch (without committing), or if you switch branches before starting your code changes.
So in no particular order developers will either:
# Edit the code before
git checkout -b new_branch_name
or
git checkout -b new_branch_name
# Edit the code after
You can even
git add .
But DO NOT git commit
Once you have some changes that you're happy with and you are no longer on the master branch, it's time to commit your changes. Git commits are like screenshots of your code at any given point. To process a commit, first change or remove an existing file, or create a new file. Once you've made a change schedule that file for committing using either git add or git rm. Use git add for reworking existing files or adding new files, and git rm for removing existing files. Once you have at least once file scheduled for update, addition, or removal you can finalize the commit with:
git commit -m "Your message here"
With your new changes commited, it's time to git push origin new_branch_name. After your branch has been pushed you can create a pull request at GitHub. The website will guide you through the process. Be sure to include a reasonable name for your pull request, make a references to any bugs you solved, and please leave documentation/specifications for any features that have been implemented, or API endpoints that have been added/removed.
In all honesty this guide is an idealistic simplification of the real process of software development. There are times where I do not follow this process to a T. That said this process does exemplify a propper git flow, and when I'm off, it's not by much. The most common place I find myself disobeying the advice of this guide is that I frequently add multiple commits to one new branch. Theres nothing wrong with this practice, it just requires that I rebase my commits.
* The other primary cause of merge conflicts occurs when one of the files in your commit has been changed on master since your branch was created.
If you would like a better understanding of how git works, or why the process should be handled this way, I would ask you to read these 2 links. The first is a basic tutorail from Github. It should take no more than 5 minutes to read and outlines a very straight forward set of steps for proper git flow. The second, more substantive one, is about the philosophy of why git commits should be atomic.
https://guides.github.com/introduction/flow/
https://medium.com/@fagnerbrack/one-commit-one-change-3d10b10cebbf