@buildo/hophop/README.md

# Hophop
![](https://img.shields.io/npm/v/@buildo/hophop.svg)

A minimal tool to accelerate the GitHub workflow from the command line.

## Installation

`npm install -g @buildo/hophop` with a non-ancient version of `npm`

## Setup

- `hophop gh setup` to set the GitHub API access token
  - to generate a GitHub token click on the url printed by `hophop` in the terminal ![image](https://cloud.githubusercontent.com/assets/4029499/23462847/cb5654ea-fe8f-11e6-88d0-92e1f411ee54.png)
  with that link, the required permissions are already filled: all you need to do is click the green "Generate token" button at the bottom of the page

## Requirements

hophop requires **Git version 2.22.0 or higher** to work correctly.

## GitHub Workflow

#### `hophop gh feature`

to create a local branch referencing an open issue

```bash
hophop gh feature # if you don't know the issue number
hophop gh feature 123 # if you already know the issue number
```

#### `hophop gh pr`

to push the current feature branch and, if needed, open a Pull Request. The name of the pull request will cause GitHub to auto-close the issue when the PR is merged.

```bash
hophop gh pr # to open pull request on master
hophop gh pr --base # to open pull request on a different branch (hophop will ask you to select a branch)
```

#### `hophop gh commit`

to create a commit that closes an open issue.

#### `hophop gh open`

to open on Chrome the PR associated with current branch.

## .hophoprc

add an optional `.hophoprc` file in your project root folder in order to set default answers to the `hophop gh feature` task questions.

Config:

```ts
type Option = 'ask' | 'no' | 'n' | 'nope' | 'yes' | 'y' | 'yep' | 'si' | 'of course' | 'youbetcha';

type Config = {
  apiUrl?: string; // default: 'https://api.github.com'
  branchSuffix?: Option; // default: 'ask'
  moveToWIP?: Option; // default: 'y'
  openPRWithTestPlanTemplate?: Option; // default: 'y'
  closeIssueWithPR?: Option // default: 'y',
  openPRAsDraft?: 'Option' // default: 'n'
  kaiten?: { // default: undefined
    boardId: number;
    backlogColumnId: number;
  };
};
```

#### example

```yaml
branchSuffix: y
```

## Kaiten support
hophop supports using Kaiten for issue tracking. To enable Kaiten add the `kaiten` section in `.hophoprc`, for example:

```yaml
kaiten:
  - boardId: 123123
    backlogColumnId: 123123
```

You can configure as many combinations of boardId/backlogColumnId as you want:

```yaml
kaiten:
  - boardId: 123123
    backlogColumnId: 123123
  - boardId: 456456
    backlogColumnId: 456456
```

> You can retrieve board and column ids in the Kaiten UI by using the "copy link" functionality and getting the id from the resulting url

Once Kaiten is configured all hophop commands will automatically use it instead of GitHub.
Note that, in this case, the command `hophop gh feature` will also push the newly created local branch to the remote repository in order to move the issue's card from Backlog to WIP.

## zsh autocompletion

After installing the package, an autocompletion file is available at
```
NPM_PREFIX/lib/node_modules/@buildo/hophop/_hophop
```

where `NPM_PREFIX` is usually `/usr/local` and it can be retrieved using `npm prefix -g`

#### Installation using oh-my-zsh

If you use [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh), installing the autocompletion is as easy as:

```bash
mkdir -p ~/.oh-my-zsh/custom/plugins/hophop
ln -s `(npm prefix -g)`/lib/node_modules/@buildo/hophop/bin/_hophop ~/.oh-my-zsh/custom/plugins/hophop/_hophop
touch ~/.oh-my-zsh/custom/plugins/hophop/hophop.plugin.zsh
```

Then enable the plugin in your `.zshrc`, for example:
```bash
plugins=(git brew hophop)
```