Improve Project Communication With These Git Tips
Simple communication tips for software developers using Git.
Collaboration is a critical component of successful software development. While there are many opinions on how to build the best software, one decision is a given for most projects: using Git for version control.
The data in Git is critical to understanding how things change over time in a project. Is this work a feature or a bug fix? Does it resolve an open issue? Does it introduce a breaking change?
These days, Git extends beyond version control. Web services like GitHub provide tools for issue tracking, sprint planning, and more. In these integrations, Git data is a critical piece of digital project management. With that in mind, this article will share some tips to communicate effectively using Git.
In the following examples, I'll be referencing tie-ins with GitHub. Most concepts apply to services such as GitLab and Atlassian's Bitbucket.
Tip 1: Use Great Branch Names #
$ git checkout -b login-pageWhen starting a new feature, naming the Git branch something relevant makes sense. But what if there is more than one active issue referencing the login page?
$ git checkout -b 4-login-pageIncluding the issue number in the branch name is one convention that communicates more without any extra effort. The reference makes it clear why this branch exists and provides more immediate context in any project branch cleanup that could occur weeks or months later (related tip: delete your merged branches ASAP). The exact convention is not as important as standardizing across the team.
Tip 2: Reference Issues in Commit Messages #
$ git commit -m 'Add login page.'Here's another easy win: always add #4 (or the pattern matching required for your issue tracker) to your commit messages.
$ git commit -m 'Add login page. #4'This adds convenient context in only a few characters. Have look at GitHub's timeline to see what I mean:
By simply referencing the issue number, you've created a hyperlink to the issue for other GitHub users. Workflow bonus: automatically resolve an issue on merge with certain language patterns.
Tip 3: Write Descriptive Commit Messages #
It's often helpful to outline details in a commit message beyond the "summary" first line, where characters are limited. When things get complicated, these longer notes can be invaluable to other developers. They are also great material for pull request descriptions and documentation.
If you're unsure about format, one common convention for multiline messages is the 50/72 rule. TLDR: use 50 characters for the summary, enter a new line, then wrap at 72 characters per line for the description text.
Note: I've used -m for simplicity in the examples so far, but I recommend using a text editor for multiline messages. There are a lot of Git GUI tools like GitX that are useful for staging and message writing. You can also double-quote your inline message, which allows new lines until the ending quote.
$ git commit -m "Add login page. #4
>
> Create new `/login` route, template.
> Add rounded corners to text input.
>
> TODO: fix failing test."Tip 4: Eliminate Extraneous Commits #
$ git commit -m 'Add login page. #4'
$ git commit -m 'Login copy text typo.'
$ git commit -m 'Fix HTML indent.'
$ git pushThere's a common need to add code that is only a small correction or amendment to the original commit. This can occur frequently during code review, where it results in a good feedback loop on pull requests.
Unfortunately, these kinds of additions are rarely meaningful to the overall project history. They are also more difficult to revert than a single commit. Here are a few popular methods to keep things nice and neat:
- Update the most recent commit with
git commit --amend - Interactive Rebase
- Rebase and
git commit --fixup. See Auto-squashing Git Commits from thoughtbot for more. - GitHub's "Squash and Merge" button for pull requests (option must be enabled in repo settings).
$ git commit -m 'Add login page. #4'
$ git commit -m 'Login copy text typo.'
$ git commit -m 'Fix HTML indent.'
$ git rebase -i HEAD~3
$ git pushThe code snippet above uses an interactive rebase to rewrite commits. If this is new to you, git rebase -i HEAD~3 launches something like this in a text editor:
pick 6dc980a Add login page. #4
pick 3253ac5 Login copy text typo.
pick 2d5a694 Fix HTML indent.
# Rebase 845e601..2d5a694 onto 845e601 (3 command(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented outThis is the interactive part. You can choose what to do via text edits (pick, squash, etc.) based on the commented-out guide. Then save and exit to rewrite as specified. This method prunes quickly, but it also offers a lot of editing control of the commit messages you want to keep. See this in-depth interactive rebase post for more on the topic.
Caution: rebase rewrites history. This can be dangerous, i.e. losing work. If you're not comfortable yet, duplicate a Git branch (or create a test repo) and try it there!
Fin #
I try to practice these simple tips every day. When in doubt, a little extra effort can go a long way towards helping a project run smoothly. Got your own Git project tips? Share with us below.
