Pivotal Tracker Project

THIS PROJECT IS NO LONGER UNDER DEVELOPMENT

UPDATE: This project is abandoned and I won't be continuing to work on it. The most important and still-relevant take-away from it is my argument for using a rebase-based workflow instead of merge-based workflow for managing feature branches, which you can read in the Goals, and Philosophy page

This is because I have evolved in my thinking on the process of updating feature branches, and whether it should be scripted or not:

1. A solid understanding of how to manage your own feature branches directly via git is a prerequisite for any dev working in modern software development teams.
2. In my opinion, the process for managing a feature branch shouldn't be attempted to be automated or scripted, for two reasons:
   1. You can't, because it will often involve manual conflict resolution, which can't be scripted. Or, even if you did, it sort of defeats the point, because the conflict resolution is the hardest part anyway, and you have to have some complex script process to "resume" after the conflict resolution step.
   2. Developers should understand the underlying git commands and what they are doing. This is because there's invariably eventually some unexpected or edge case situation that you need to resolve, and if you always rely on a script that only handles the happy path case, you will be lost as to how to handle these edge cases.

Other people's opinions may differ, though. If you feel like this would be useful, feel free to steal any ideas or code from this repo :)

Also, my plan to use bash as a cross-platform language was a bad idea. If I did attempt to write a cross-platform CLI such as this today, I would definitely use the Rust language.

gitrflow

Git extensions to provide high-level repository operations for a rebase-based git workflow. Similar to gitflow, but uses constant automatic rebasing instead of manual merges to manage feature branches.

gitrflow is based upon an opinionated premise:

"You should use a rebase-based workflow to manage Git feature/story branches."

If you understand and agree with this, then gitrflow is for you! Scroll down for the TL;DR docs and summary of gitrflow usage, or use the command line help.

If you don't understand what that means, or if you disagree with using a rebase-based workflow for feature branches, then I respectfully invite you to review the Goals, and Philosophy page with an open mind.

Thanks for reading. :)

Table of Contents

• Installing
• Usage
  • Init Command
  • Update Command
  • Feature Branch Commands
    • rflow feature start
    • rflow feature publish
    • rflow feature finish
  • Release Branch Commands
    • rflow release start
    • rflow release tag
  • Hotfix Branch Commands
    • rflow hotfix start
    • rflow hotfix finish
• Compatibility
• Goals, and Philosophy
  • Intro
  • Merge or rebase?
    • The debate
    • The Git Book's summary of positions
    • The case for rebasing feature branches
  • Problems and their solutions
  • "But rebasing loses information..." - A history lesson
  • Lack of tool support
    • Handling changing SHAs
    • Delivery and testing of rebased feature branches
    • Considerations
  • Public / Open Source feature branches - safe to rebase?
  • Squash merges - they DO lose information
  • When committing merge conflicts is unavoidable
  • Goals and Benefits of rebase over a merge workflow
• Further Reading
  • Articles Supporting a Rebase Workflow
  • General Articles on Git, Branching, and SCM Workflows
• Glossary
• Hacking / Contributing
• Credits

Installing

• gitrflow is a single bash script, for maximum portability and ease of installation
• For now, simply put gitrflow on your PATH. Eventually, it will be distributed via various package managers: Rubygems, Homebrew, Npm, Maven, etc...
• Development is still in early stage, see "Usage" section for which commands are implemented

Usage

TODO: Work in progress, for now this is just a high-level description of the commands, they will be labeled "unimplemented", "in progress", or "implemented" for now.

Usage:
  gitrflow [global options] init [--defaults]
  gitrflow [global options] <branch type> <command> [command options]

'init' command options:
    --defaults                  Use defaults for init config without prompting

Branch Types:
    feature

'feature' branch type commands and options:
    feature start <branch_name>

Global options:
    -c, --print-git-commands    Print git [c]ommands as they are run
    -d, --debug                 Debug git-rflow script with bash xtrace
    -h, --help                  Display this [h]elp
    -o, --print-git-output      Print [o]utput from git commands
    -V, --version               Display the program [v]ersion
    --                          Ignore all following options

Init Command

(implemented for feature branch prefix)

rflow init [--defaults: Initializes a git repo for use with gitrflow, and prompts you to define prefixes for different branch types. Branch type prefixes are required by gitrflow to know what type of branch you are on, so that it can perform the proper validations and actions. If you pass the --default option, the default branch prefixes will be automatically used with no prompting.

Update Command

(unimplemented)

rflow update: For feature branches, pulls the current feature branch from the remote, then rebases it onto the tip of the upstream branch (currently, only master is supported as an upstream). For master and all other non-feature branches, does a pull. Always first verifies local working copy is clean with no unpushed changes.

Feature Branch Commands

rflow feature start

(implemented)

rflow feature start <feature branch name>: creates a new feature branch off of the current branch, which is then considered the "upstream" of the feature branch.

rflow feature publish

(unimplemented)

rflow feature publish: safely publishes the current feature branch to the remote branch. "safely" means that the current feature branch is rebased onto the remote branch before force-pushing it. If there are any rebase conflicts which cannot be automatically resolved by Git, gitrflow will pause, allow you to manually resolve them, then --continue (just like the --continue option on the underlying rebase command)

rflow feature finish

(unimplemented)

rflow feature finish: merges (merge --no-ff) a feature branch back into the upstream branch, after first ensuring it is fully rebased onto the remote branch and the upstream branch.

Release Branch Commands

"Production" release branches should never have their history rewritten by rebase, because their previous history is very important to preserve. So, the merge --no-ff command is used to manage the production release branches.

TODO: Since they don't involve rebasing, managing release branches is a secondary goal for gitrflow, and won't be implemented until the feature branch support (the primary goal) is solid and complete.

gitflow has very good support for managing production release branches and hotfix branches via merge, and there's no reason (AFAIK) that it couldn't be used in conjunction with gitrflow - e.g. manage feature branches with gitrflow, and everything else with gitflow.

However, after carefully reading many articles on gitflow, and all the comments on them, there will be some fundamental differences in the release branch support in gitrflow:

UPDATE: Actually you can have a "develop" branch as your main if you want. My thinking has evolved on this, it doesn't really matter what you name your upstream branch, or if you have it "promoted" to other branches, e.g. the standard Gitflow develop -> master approach. I'll update the docs accordingly, but everything else still applies. TODO: UPDATE ACCORDINGLY.

1. There will be no "develop" branch.

• All feature and release branches will have the "master" branch as their upstream. The only purpose of the "master" branch in the gitflow workflow is