## Table of Contents
* [Workflow](#workflow)
* [Scope](#scope)
* [Installation](#installation)
  * [GIT](#git)
* [Usage](#usage)
  * [Arguments](#help)
    * [Help](#help)
    * [Repository](#repository)
    * [Branches](#branches)
  * [Commands](#commands)
    * [Rebase](#rebase)
    * [Purge](#purge)
    * [Aggregate](#aggregate)

## Workflow
This script will facilitate adopting a subset of the branch-featuring workflow characterised by:
* each feature will have its own branch
* feature branches derive directly form master
* integration of master to feature branch happens via rebasing
* force pushing of feature branches to origin is not an issue
* release branches are created aggregating multiple branches

## Scope
The scope of this gem is helping out in the following cases:
* you have multiple feature branches waiting for release due to some reason (i.e. long QA time...), and need to keep them aligned with master
* you need to quickly aggregate branches for a release
* you want to cleanup local and remote branches upon release

## Installation
Just install the gem to use the binaries commands.
```
gem install git_commands
```

### GIT
The library uses the Ruby command line execution to invoke the **git** command as a separate process.  
I assume you have the GIT program on your path.

## Usage
Here are the main commands:

### Arguments
All of the available commands come with the same set of arguments:

#### Help
Display the help of a specific command by:

```
rebase --help
Usage: rebase --repo=/Users/Elvis/greatest_hits --branches=feature/love_me_tender,fetaure/teddybear
    -r, --repo=REPO                  The path to the existing GIT repository
    -b, --branches=BRANCHES          Specify branches as: 1. a comma-separated list of names 2. the path to a file containing names on each line 3. via pattern matching
    -h, --help                       Prints this help
```

#### Repository
You have to specify the path (absolute or relative) to the GIT repository you want to work with. The path must be a folder initialized as a valid GIT repository (a check via *rev-parse* is performed), otherwise an error is raised:

```
rebase --repo=invalid
'invalid' is not a valid GIT repository!
```

#### Branches
As with the repository you always have to specify the list of branches you want to work with. There are different options:

##### List of branches
Specify a comma separated list of branch names:

```
rebase --repo=/Users/Elvis/greatest_hits --branches=feature/love_me_tender,feature/teddybear,feature/return_to_sender

Loading branches file...
Successfully loaded 3 branches:
01. feature/love_me_tender
02. feature/teddybear
03. feature/return_to_sender
```

##### Path to a names file
Specify a path (absolute or relative) to a file containing the branches names on each line:

File */Users/Elvis/greatest_hits/.branches*:
```
feature/love_me_tender
feature/teddybear
feature/return_to_sender
feature/in_the_ghetto
```

```
rebase --repo=/Users/Elvis/greatest_hits --branches=/Users/Elvis/greatest_hits/.branches

Loading branches file...
Successfully loaded 4 branches:
01. feature/love_me_tender
02. feature/teddybear
03. feature/return_to_sender
04. feature/in_the_ghetto
```

##### Pattern matching
In case you want to work with a set of branches with a common pattern, you have to specify a greedy operator with the wild card you want to match.  
Just consider you have not to specify *origin/* as the name of the branch, since is managed by the script for you: 

```
rebase --repo=/Users/Elvis/greatest_hits --branches=*der

Loading branches file...
Successfully loaded 2 branches:
01. feature/love_me_tender
02. feature/return_to_sender
```

##### Checking
Each loaded branch is validated for existence (but for branches loaded via pattern matching). In case the validation fails, the branch is filtered from the resulting list.

```
rebase --repo=/Users/Elvis/greatest_hits --branches=noent,feature/love_me_tender

Loading branches file...
Successfully loaded 1 branch:
01. feature/love_me_tender
```

In case no branches have been loaded, an error is raised:

```
cd /Users/Elvis
rebase --repo=./greatest_hits --branches=noent1, noent2
No branches loaded!
```

##### Master branch
Master branch cannot be included into the branches list for obvious reasons (from useless to dangerous ones):

```
rebase --repo=/Users/Elvis/greatest_hits --branches=master,feature/love_me_tender

Loading branches file...
Successfully loaded 1 branch:
01. feature/love_me_tender
```

### Commands
Here are the available GIT commands:

#### Rebase
This is probably the most useful command in case you have several branches to rebase with _origin/master_ frequently.
A confirmation is asked to before rebasing.  

```
rebase --repo=/Users/Elvis/greatest_hits --branches=feature/love_me_tender,feature/teddybear,feature/return_to_sender
...
```

#### Purge
This command remove the specified branches locally and remotely.  
A confirmation is asked before removal.  

```
purge --repo=/temp/top_20 --branches=*obsolete*
...
```

#### Aggregate
This command aggregates all of the specified branches into a single one in case you want to create a release branch.  
It uses the following naming convention: *release/yyyy_mm_dd*  
A confirmation is asked before aggregating.  

```
aggregate --repo=/Users/Elvis/greatest_hits --branches=*ready*
```