Reflow automatically creates pull requests, ensures the code review is approved, and squash merges finished branches to master with a great commit message template.
Ruby
Latest commit 8cbdcb8 Nov 16, 2017 @codenamev codenamev Remove lingering `skip_lgtm` options in favor of `force` option
We started using the `force` option for `deliver` a while ago and I forgot to rip out the old `skip_lgtm` references.

Merges #218

LGTM given by: @nhance

README.rdoc

git-reflow (2015 Fukuoka Ruby Award Winner)

Circle CI Git workflow powered by git-reflow Documentation

RDocs

If your workflow looks like this:

  1. Create a feature branch

  2. Write great code

  3. Create a pull request against master

  4. Get 'lgtm' through a code review

  5. Merge to master (squashed by default, but can be overridden; why is squash merging our preferred workflow? github.com/reenhanced/gitreflow/issues/52)

  6. Delete the feature branch

Reflow will make your life easier.

Reflow automatically creates pull requests, ensures the code review is approved, and merges finished branches to master with a great commit message template.

Quickstart

Create and switch to new branch nh-branchy-branch:

$ git reflow start nh-branchy-branch

Create a pull request for your branch against master or a custom base_branch:

$ git reflow review

If your code is 'LGTM'd, merge to base_branch and delete the feature branch:

$ git reflow deliver

Benefits:

  • Enforce code reviews across your team.

  • Know that your entire team delivers code the same way.

  • Reduce the knowledge needed to deliver great code.

  • Have a commit history that's clean and actually usable.

  • Revert features with ease (if needed).

  • Work with diverse teams with less worry about different processes.

  • Stop searching for other git workflows. Reflow covers 90% of your needs without junk you'll never use.

Features:

  • Automatically create pull requests to master

  • Automatically ensure that your code is reviewed before merging

  • Start with sensible commit messages by default

  • Squash merge feature branches because results are more important than details

  • Automatically clean up obsolete feature branches after a successful merge


How to use

Dependencies

Editor When reviewing the title and body for a new pull request, or reviewing the commit message when delivering a feature, we will open a temporary file with your default editor. We will use git's chosen editor first (“core.editor” git config key), then we try your “EDITOR” environment variable, and lastly we fallback on “vim”. If you would like to use an editor of your choice, we recommend setting it with git's config. As an example, to use Atom as your editor for all git commands:

$ git config --global core.editor "atom --wait"

See GitHub's full article on [associating text editors with Git](help.github.com/articles/associating-text-editors-with-git/) for more information on adding this.

Installation

$ gem install reflow

or

$ gem install git_reflow

(`git_reflow` is the official gem, and `reflow` just declares `git_reflow` as a dependency.)

Setup

On your first install, you'll need to setup your Github credentials. These are used only to get an oauth token that's stored in your global git config. We use the Github credentials so we can create pull requests from the command line.

After installation, run:

git reflow setup

It looks like 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!

This is safe to run multiple times. We don't care.

Customization

There are several git config variables that can be set (either globally or per-project) to override some parts of our workflow.

To set them globally for all your projects, run the following from the command line:

$ git config -f $HOME/.gitconfig.reflow --replace-all "CONFIG_KEY_TO_OVERRIDE_AS_LISTED_BELOW" "REPLACE_WITH_NEW_VALUE"

You can also override your default globals on a per-project basis using:

$ git config --replace-all "CONFIG_KEY_TO_OVERRIDE_AS_LISTED_BELOW" "REPLACE_WITH_NEW_VALUE"
  • `core.editor` – Use an editor of your choice when modifying PR details and commit messages. Our default is `vim`.

  • `reflow.merge-method` – Use a merge method of your choice. For Github, options are `merge` (uses standard `git merge`), `squash`, `rebase`. All other git-servers currently only support `merge` and `squash`. Our default is `squash`.

  • `constants.minimumApprovals` – number of approvals needed in order to deliver a feature. Our default is `0`, which means all commenters need to approve.

  • `constants.approvalRegex` – a regular expression to mark comments as approved. Our default is `/(?i-mx:lgtm|looks good to me|👍|👍|:shipit:)/`

  • `reflow.always-cleanup` – If set to `true`, this will skip the prompt `Would you like to push this branch to your remote repo and cleanup your feature branch?`. Default is unset.

  • `reflow.always-deliver` – If set to `true`, this will skip the prompt `This is the current status of your Pull Request. Are you sure you want to deliver?`

  • `reflow.deploy-to-staging-command` – A command that can be run to deploy the current branch to a staging server. Default is unset.

Usage with Github Enterprise

To use GitReflow with a GitHub Enterprise account, there are some additional switches available to the GitReflow setup command. You should be able to use GitReflow for both your Enterprise and non-Enterprise repositories. Because of this, there are a few scenarios that may apply to your usage of GitReflow:

You use a GitHub Enterprise account for the majority of your repositories:

git reflow setup --enterprise

After this, anytime you want to use GitReflow with project that uses a regular GitHub account:

cd replace_with_your_non_enterprise_project_path
git reflow setup --local

This will setup your project's git config with the OAuth token generated from the credentials you provide

If you only use GitHub Enterprise for a select few repositories, you'll first want to setup GitReflow as normal:

git reflow setup

Then for your Enterprise projects, you have to setup GitReflow for each one:

cd replace_with_your_enterprise_project_path
git reflow setup --enterprise --local

Refreshing your current branch based on your base branch

git reflow refresh

This command updates your feature_branch and base_branch according to the remote_location and then merges your base_branch into your feature_branch. This is just a handy command to keep your branches up to date at any point in time if someone else has committed to the base_branch or the remote.

git reflow refresh -r <remote_location> -b <base_branch_name>

You pass in the name of the remote to fetch from and the name of the base_branch that you would like to merge into your feature_branch. The remote_location defaults to “origin” and the base_branch defaults to “master”. This command also takes in remote and branch name as flag options.

Starting a feature branch

git reflow start

This sets up a feature branch remotely and brings a local copy to your machine. Yeah, you can do this by hand pretty easily, so skip this command if you want. This is just a handy shortcut with no magic.

git reflow start nh-branch-name

“Git Reflow Start” takes in the name of the new branch name that you want to create your feature on. In addition, it takes in an optional flag of a base branch name. If you don't pass in this parameter, then it defaults to “master”. The base branch name is the base branch that you want to base your feature off of. This ensures that everytime you start a new base branch, it will be based off of your latest remote base.

git reflow start nh-branch-name --base base-branch-name
PROTIP

Use your initials at the beginning of each branch so your team knows who is responsible for each. My initials are 'NH', so all of my branches start with nh-

Reviewing your work

git reflow review

All of our work is reviewed by our team. This helps spread knowledge to multiple parties and keeps the quality of our code consistent.

The review step creates a pull request for the currently checked out feature branch against master. That's all you want to do most of the time. We assume you know what you're doing, so if you need something different, do it by hand.

After making commits to your branch, run review. Didn't push it up? We don't care, we'll do it for you.

git reflow review -t <title> -m <message>

If you do not pass the title or message options to the review command, you will be given an editor to write your PR request commit message, similar to `git commit`. The first line is the title, the rest is the body.

$ git reflow review

Review your PR:
--------
Title:
rj_209_test

Body:
[lib] updates review command to address issues
--------
Submit pull request? (Y): <enter>
git fetch origin master
From github.com:meesterdude/gitreflow
 * branch            master     -> FETCH_HEAD

git push origin rj_test
Everything up-to-date

Successfully created pull request #6: rj_test
Pull Request URL: https://github.com/meesterdude/gitreflow/pull/6
Would you like to push this branch to your remote repo and cleanup your feature branch? y

We output the pull request URL so you can distribute it to your team without leaving the terminal.

How it works

Behind the scenes, this is how review works:

git fetch origin

Are we up-to-date with changes from master? If not, fail with “master has newer changes”.

Then,

git push origin current-branch # Updates remote branch

Do we have pull request? If not, create it and print “Pull request created at pull-url/”. If so, print the url for the existing request.

Checking your branch status

git reflow status

Sometimes you start working on a branch and can't get back to it for a while. It happens. Use status to check on the status of your work.

$ git reflow status

Here's the status of your review:
  branches:     reenhanced:nh-readme-update -> reenhanced:master
  number:       35
  reviewed by:
  url:          https://github.com/reenhanced/gitreflow/pull/35

[notice] No one has reviewed your pull request...
Would you like to open it in your browser? n

This gives you details on who's reviewed your pull request. If someone has participated, but not given you a 'LGTM', this will tell you. status prevents you from having to open a browser to find out where your pull request is at. But in case you want to take a look, we give you the option to open it for you.

Delivering approved code

Note: This documentation is for the process for the github “remote” merge process via the github_api.

For the bitbucket standard or github manual process (used when the user applies -f force flag to the “remote” merge via the github_api), please go to section B.

A:

git reflow deliver

You kick butt. You've got your code reviewed and now you're ready to merge it down to master and deploy. Reflow deliver will take care of all of the steps for you to make this happen.

Reflow's deliver requires you to have a pull request, so you'll be protected on those mornings when the coffee isn't working yet. We built this to get in your way and make you follow the process. If you don't like it, do it by hand. You already know what you're doing.

You'll be presented with a prefilled commit message based on the body of your pull request with references to the pull request and reviewers.

Want to clean up your feature branch afterwards? You'll be prompted after you edit your commit message if you want to clean up your feature_branch on github. If you answer 'n', then your feature_branch will exist for you to clean it up later.

This is what it looks like:

$ git reflow deliver
Here's the status of your review:
    branches:     simonzhu24:test1234 -> simonzhu24:master
    number:       51
    reviewed by:
    url:          https://github.com/simonzhu24/test/pull/51

[notice] No one has reviewed your pull request.
Would you like to open it in your browser? n
This is the current status of your Pull Request. Are you sure you want to deliver? Y
Merging pull request #51: 'last commit message', from 'simonzhu24:test1234' into 'simonzhu24:master'
git checkout master
Switched to branch 'master'
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)

[success] Pull Request successfully merged.
Would you like to cleanup your feature branch? Y
git pull origin master
remote: Counting objects: 1, done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (1/1), done.
From https://github.com/simonzhu24/test
 * branch            master     -> FETCH_HEAD
   0d8f5e0..f853efa  master     -> origin/master
Updating 0b6782f..f853efa
Fast-forward
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

git push origin :test1234
To https://github.com/simonzhu24/test.git
 - [deleted]         test1234

git branch -D test1234
Deleted branch test1234 (was e130c7a).
Nice job buddy.

How it works

This is what we do behind the scenes when you do deliver

  • Does a pull request exist?

    If not, stop here. You need to run review.

  • Has the review been completed? Did we get a LGTM from everyone who's participated?

    If not, show a list of authors that need to provide a LGTM.

  • If the review is done, it's time to merge. Here's what happens:

    First, we use the github_api gem to merge the pull request.

    We call the public API for:

    github.pull_requests.merge 'user-name', 'repo-name', 'number', payload
    
    Please take a look at lib/git_reflow/git_server/git_hub/pull_request.rb:102-107 for an example of the call.
    This call makes an HTTP request using the Github API to merge the available pull request passing in the user name, repository name, pull request number, and some additional data in the payload.
    
    The payload contains data in the following format:
    
    data = {
      "commit_title",
      "commit_message",
      "sha",
      "squash"
    }
    
    Notice: "squash" is set to true, meaning that we will do a squash-merge for each pull request.
    
    For more detailed documentation, please read: https://github.com/piotrmurach/github/blob/master/lib/github_api/client/pull_requests.rb#L197
  • Next, we prompt you if you want to cleanup Would you like cleanup your feature branch?

    If 'y', then we'll update the base_branch and delete the feature branch

    git pull origin #{base_branch}
    git push origin :#{feature_branch}
    git branch -D #{feature_branch}

    If 'n', then just stop here. The user can clean up his branch locally.

    And we're done.

Note: This documentation is for the bitbucket standard or github manual process (used when the user applies -f force flag to the “remote” merge via the github_api).

B:

This is what the process looks like for bitbucket or if you force deliver:

From github.com:reenhanced/gitreflow
* branch            master     -> FETCH_HEAD
Merging pull request #36: 'Enforce at least one LGTM before delivery', from 'reenhanced:nh-fail-without-lgtm' into 'reenhanced:master'
Already up-to-date.
Switched to branch 'nh-fail-without-lgtm'
Switched to branch 'master'
Updating c2ec1b1..f90e111
 Squash commit -- not updating HEAD
 lib/git_reflow.rb | 71 +++++++++++++++++++++++++++----------------------------
 1 file changed, 35 insertions(+), 36 deletions(-)
[master d1b4dd5] Enforces LGTM before deliver, even with no comments.
 1 file changed, 35 insertions(+), 36 deletions(-)
Merge complete!
Would you like to push this branch to your remote repo and cleanup your feature branch? y
Counting objects: 7, done.
Delta compression using up to 16 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 1.38 KiB, done.
Total 4 (delta 2), reused 0 (delta 0)
To git@github.com:reenhanced/gitreflow.git
   c2ec1b1..d1b4dd5  master -> master

To git@github.com:reenhanced/gitreflow.git
 - [deleted]         nh-fail-without-lgtm

Deleted branch nh-fail-without-lgtm (was f90e111).

This is what the default commit message looks like:
Enforces LGTM before deliver, even with no comments.
Removes the need to review the pull request yourself if you make a
comment.

Better error message if setup fails.

Bug fixes.

Closes #36

LGTM given by: @codenamev

Squashed commit of the following:

commit f90e111
Author: Nicholas Hance <nhance@reenhanced.com>
Date:   Thu Jul 11 15:33:29 2013 -0400
...

If the review is done, it's time to merge. Here's what happens:

First, update our local +master+ so we don't get conflicts
  git checkout master
  git pull origin master

Next, squash merge our feature branch
  git merge --squash nh-branch-name

Now, we'll apply a little magic so we have a great commit message by default. Your editor will open and you'll see a nice default for your commit message based on the pull request body.

Once you've saved the commit, prompt the user to see if we should continue
  Merge complete!
  Would you like to push this branch to your remote repo and cleanup your feature branch?

If 'y', then we'll push to +master+ and delete the feature branch
  git pull origin master
  git push origin master
  git push origin :nh-branch-name
  git branch -D nh-branch-name

If 'n', then just stop here. The user can reset his local +master+.
And we're done.

Guiding principles:

  • Your workflow should resemble the following:

  • You should already know what you're doing. We assume you know how to use git.

  • The master branch is your codebase. You don't need multiple branches for code actually want to use.

  • master should remain stable at all times. The entire team depends on it.

  • No direct commits to master. All work happens in feature branches. From a single commit to hundreds.

  • All feature branches are reviewed via pull requests.

  • Looks Good To Me. All feature branches require approval. We look for the string 'LGTM' in a comment on the pull request to know it's ready to merge.

  • If you make a new commit in your branch, you require another review.

  • Depending on the minimumApprovals that you specify in your ~/.gitconfig.reflow (created upon reflow setup), you can have the following:

    “” : All participants in a pull request must approve the pull request. “0”: 0 approvals required for you to merge PR. “1”: You need a minimum of 1 LGTM and the last comment on your PR must be an LGTM. “2”: You need a minimum of 2 LGTM and the last comment on your PR must be an LGTM. …

  • Once approved, your feature branch is squash-merged to your base_branch. This makes the history of the base_branch branch extremely clean and easy to follow.

  • Git blame becomes your friend. You'll know who to blame and can see the full context of changes. Squash commits to base_branch mean every commit represents the whole feature, not a “typo fix”.

Configuration

In order to streamline delivery you can set the following git config to:

1. always clean up the feature branch after the PR is merged
2. always deliver without further prompt

git config --global --add "reflow.always-cleanup" "true"
git config --global --add "reflow.always-deliver" "true"

Contributing

Pull requests are welcome. Please fork and submit. We use this tool every single day and as long as what you want to add doesn't change our workflow, we are happy to accept your updates. Feel free to add your github username to the list below.

Authors:

  • @codenamev

  • @armyofgnomes

  • @nhance

Built by Reenhanced: www.reenhanced.com

Looking for a capable team for your project? Get in touch. We're looking to grow.

Licensed using the MIT license. Do whatever you like with this, but don't blame us if it breaks anything. You're a professional, and you're responsible for the tools you use.