Code Reviews on Autopilot: A Quick-Start Guide to Git Reflow

For the past several years, Engine Yard has sponsored the Fukuoka Ruby Awards which highlight interesting projects created with Ruby that help move the industry forward. This year’s winner of the Engine Yard award is git reflow, a tool that helps to enforce development best practices.

What is git reflow?

Git reflow is a ruby gem that extends git with a few additional commands to connect with GitHub, BitBucket, or GitHub Enterprise. These commands let you create pull requests from the command line and provide a standardized method of delivering completed branches.

Let’s take a closer look at how to use this tool.

Installation

For this post, we’ll assume you’re using GitHub, but the process is identical if you’re using BitBucket. Firstly, you install git reflow with gem install git_reflow. Then, connect git reflow with GitHub with git reflow setup.

The first time you install, you will be prompted for your Github credentials. Your credentials are used to interact with the Github API from the command line, and are only used to get the OAuth token which is stored in your global or local git config.

Once you connect with git reflow setup, you’ll see this:

$ git reflow setup
Please enter your GitHub username: nhance
Please enter your GitHub password (we do NOT store this):

Your GitHub account was successfully setup!

Starting a New Feature Branch

The simplest way to identify the owner of each feature branch is for each team member to begin a new feature branch with their initials. So, Ashley Christman would use git reflow start branch-name to create and switch to a new branch for “coalitions” like this:

$ git reflow start ac-coalitions-update

You see how she’s prefixed the branch name with ac- for Ashley Christman.

This command creates the branch and syncs the remote and local git repository with the new branch, so it’s instantly available everywhere. Syncing like this allows you to use simplified git pull and git push to sync with the remote repository.

Code Review

Create a Pull Request From the Command Line

Team culture often dictates how often code reviews are performed. Using git reflow makes it easy to review every line of code the team produces. Running git reflow review [destination-branch] automatically creates a pull request for the current feature branch against master, or another branch if specified.

It looks like this:

Check the Status of My Pull Request

When you’re working with multiple feature branches, it’s a frequent concern that you’ll lose track of where you were on a particular branch. You can run git reflow status to determine if your checked out branch has a review pending or if it is ready to merge.

Running git reflow status also integrates with your Continuous Integration (CI) system, so you can check the status of your build without ever leaving the console. (Please note that CI integration is only available for GitHub at this time.)

Approving a Pull Request

The basic rules for code approval are straightforward:

1. All authors who comment on a pull request must approve the code, so each pull request must have a “LGTM” comment (GitHub) or a click on the Approve button (BitBucket).
2. Any commits made after approval will invalidate the approvals. In that case, the branch must be approved again.

Delivering Completed Work

When your work is completed and the code has been reviewed, merge it down with git reflow deliver. This will provide you with a pre-filled commit message based on the pull request. It automatically includes text that will close the associated pull request. The feature branches are squashed to a single commit and the squashed commit messages are left in the pre-filled commit message so history can be retrieved if desired.

After saving the commit message, a prompt gives you one last chance to confirm that you want to update the remote repository and merge your feature branch. Once confirmed, git reflow updates the remote repository and deletes your feature branch both locally and on the remote.

Conclusion

Git reflow gives you consistent code deliveries, it cleans up after itself, and follows a documented process for all commits that will be released to master.

It’s a handy gem for teams looking to consistently adhere to best practices and can be adapted to suit different workflows. Keep your eyes peeled for a future post on how to use git reflow in more complicated scenarios, including how to use it with a staging branch.

P.S. Have you used git reflow? What do you think? Do you use a different tool to help your team stick to best practices? Let us know in the comments.