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.

1. Break your commits down into smaller chunks
2. Make sure each commit contains only necessary, related changes

Interactive Staging

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.

Interactive Rebase

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 HEAD~2.

Now you’ll be able to squash your last two commits together, and edit the single commit message.

Commit Messages

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

Instead of vim, set yours to subl, atom, etc. Make sure this command is properly set up, though!

Verbose

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:

1. Subject
2. Description (optional)
3. References (optional)

Subject

• Capitalize
• Use the imperative (Fix, not Fixes or Fixed)
• 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 (Add, Update, Remove, Fix, etc.)

Fix spacing on the sign-in form

Description

• 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

References

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

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.

Naming Branches

• 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. fix_user_bar, refactor_widget_module)

Pull Requests

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.