Gitreflow

<h1> git-reflow – Automate your git workflow<br/> <small><em>(2015 Fukuoka Ruby Award Winner)</em></small> </h1> <p> <a href="https://actions-badge.atrox.dev/reenhanced/gitreflow/goto?ref=master" title="git workflow"> <img alt="Git workflow powered by git-reflow" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Freenhanced%2Fgitreflow%2Fbadge%3Fref%3Dmaster&style=flat"> </a> <a href="https://github.com/reenhanced/gitreflow" title="git workflow"> <img alt="Git workflow powered by git-reflow" src="https://img.shields.io/badge/git--reflow-v0.9.0-blue.svg?style=flat"> </a> <a href="http://inch-ci.org/github/reenhanced/gitreflow" title="documentation coverage"> <img src="http://inch-ci.org/github/reenhanced/gitreflow.svg?branch=master&style=shields" alt="Git-Reflow Documentation" /> </a> </p>

• Usage Overview
• Getting Started
• Documentation
• Guiding Priciples

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 we prefer squash-merge)
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.

Usage Overview

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 approved, 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

---

Prerequisites

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 (git config core.editor), 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 for more information on adding this.

Getting Started

On your first install, you'll need to setup your Github credentials. These are used only to get an OAuth token that we will store in a reflow-specific git config file. We use this token so we can create pull requests from the command line.

$ gem install git_reflow

... installs gem ...

$ 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. We save this information in a special git configuration file (~/.gitconfig.reflow) that get's included into your global ~/.gitconfig file.

For usage with Github Enterprise, or other custom configurations, see our Advanced Usage Guide.

Starting a feature branch

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 (--base). If you don't pass in this parameter, then it will look up the reflow.base-branch git configuration or default to "master". The base branch name is the base branch that you want to base your feature off of. This ensures that every time 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 N.H., so all of my branches start with nh-

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>

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.

Note: If no base-branch argument is provided, then we'll look for a reflow.base-branch git configuration and fallback to master as the default.

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? No problem, we'll do it for you.

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

Note: -t and -m are optional, as is the base-branch argument. If no base-branch is provided, then we'll look for a reflow.base-branch git configuration and fallback to master as the default.

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<enter>

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

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 http://pull-url/". If so, print the url for the existing request.

Checking your branch status

git reflow status <base-branch>

Note: If no base-branch is provided, then we'll look for a reflow.base-branch git configuration and fallback to master as the default.

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.

This gives you details on who's reviewed your pull request. If someone has participated in reviewed, but not given you an approval, 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

git reflow deliver <base-branch>

Note: If no base-branch argument is provided, then we'll look for a reflow.base-branch git configuration and fallback to master as the default.

Also: 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 forc