June 16, 2015
Git & GitHub Conventions
I spend a large majority of my day working with Git and GitHub. I’m also very opinionated, so this is a random collection of opinions and techniques that I employ while working in said technologies.
Breaking up your commits
There are few good methods for handling how/when you commit.
- Break your commits down into smaller chunks
- Make sure each commit contains only necessary, related changes
If you do make several, unrelated changes in the same file, use Git’s Interactive Staging.
git add -p file.html
Then, you can split and stage multiple parts of the file.
Conversely, if you make separate commits that are related to the same thing, you can use Git’s Interactive Rebase.
git rebase -i HEAD~2
It looks strange, but just know that the final number reflects the number of commits from the top of the
HEAD that you want to rebase. In this instance, we want to rebase the last two commits, so we type
Now you’ll be able to squash your last two commits together, and edit the single commit message.
First, read these articles:
- A Note About Git Commit Messages
- 5 Useful Tips For A Better Commit Message
- How to Write a Git Commit Message
I’m not a fan of the single-line commit.
git commit -a -m 'My commit message'
Why? Because it encourages single-line, unnecessarily terse commit messages. Simply do the following:
git add file.html git commit
If you’ve set your editor via
git config --global core.editor, then it will open up when you type
git commit so that you can write your nice commit message there. If you haven’t set this command, run it like so:
git config --global core.editor vim
vim, set yours to
atom, etc. Make sure this command is properly set up, though!
Rather than just doing
git commit, I like to run
git commit --verbose, which will print out the diff of your changes below your commit message writing area. This is nice because you can write, scroll down and look at your changes, go back and write, etc.
Writing Good Commit Messages
Here is the structure I use when writing commit messages:
Subject line (50 chars.) Additional explanation and summary here, if necessary. (72 chars.) - Use hyphens to write out a list - That will break down the commit - If necessary Refs: #12 (Use this format for referencing a GitHub Issue)
The three parts of a well-structured commit message:
- Description (optional)
- References (optional)
- Use the imperative (
- DO NOT end the line with a period
- Limit to 50 characters
- Treat it as you would a subject line in an email
- If it accurately describes the commit, leave it at that
- Try and start the Subject with action words (
Fix spacing on the sign-in form
- Separate from subject line with a newline
- Wrap at 72 characters
- Explain what and why vs. how
- Use bullet points, if necessary
Fix spacing on the sign-in form This is where you would provide additional explanation on the what and why. Also, use bullet points, if you'd like: - Here is a bullet point - These can be helpful
When using an issue tracker (like GitHub), put references at the bottom with a preceding newline.
Fix spacing on the sign-in form This is where you would provide additional explanation on the what and why. Also, use bullet points, if you'd like: - Here is a bullet point - These can be helpful Refs: #245
Feature branches are branches that are created off of
master, and they are, as you’d expect, branches that you use to work on a particular feature that will be merged into
master. The creation looks something like this:
git checkout -b feature_branch_name
You can read more about feature branches in my Git Feature Branch Workflow article.
- Use underscores, not hypens (Why? Hyphens are good for purposeful delineation of multiple words, which isn’t necessary with branch names)
- Make it descriptive (e.g.
Pull Requests are great on GitHub because they allow you to view changes and conversations in a centralized location. Additionally, they are great for code reviews.
Like your commit messages, your Pull Request description should do a thorough job:
- Explaining what your feature branch changes
- Explaining why your feature branch is making these changes
- Showing relevant screenshots, if it’s a design change
- Explaining the status of the feature branch
- Clueing in the right people on the team
Essentially, Who, What, Why, and When.
That’s All, Folks
There is a rundown of some Git and GitHub conventions that I’ve adopted over time. As with all conventions, the most important part is simply that you have them. Decide with your team, or for yourself, what they are, and stick with them.