1 | # Hophop
|
2 | ![](https://img.shields.io/npm/v/@buildo/hophop.svg)
|
3 |
|
4 | A minimal tool to accelerate the GitHub workflow from the command line.
|
5 |
|
6 | ## Installation
|
7 |
|
8 | `npm install -g @buildo/hophop` with a non-ancient version of `npm`
|
9 |
|
10 | ## Setup
|
11 |
|
12 | - `hophop gh setup` to set the GitHub API access token
|
13 | - 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)
|
14 | 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
|
15 |
|
16 | ## Requirements
|
17 |
|
18 | hophop requires **Git version 2.22.0 or higher** to work correctly.
|
19 |
|
20 | ## GitHub Workflow
|
21 |
|
22 | #### `hophop gh feature`
|
23 |
|
24 | to create a local branch referencing an open issue
|
25 |
|
26 | ```bash
|
27 | hophop gh feature # if you don't know the issue number
|
28 | hophop gh feature 123 # if you already know the issue number
|
29 | ```
|
30 |
|
31 | #### `hophop gh pr`
|
32 |
|
33 | 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.
|
34 |
|
35 | ```bash
|
36 | hophop gh pr # to open pull request on master
|
37 | hophop gh pr --base # to open pull request on a different branch (hophop will ask you to select a branch)
|
38 | ```
|
39 |
|
40 | #### `hophop gh commit`
|
41 |
|
42 | to create a commit that closes an open issue.
|
43 |
|
44 | #### `hophop gh open`
|
45 |
|
46 | to open on Chrome the PR associated with current branch.
|
47 |
|
48 | ## .hophoprc
|
49 |
|
50 | add an optional `.hophoprc` file in your project root folder in order to set default answers to the `hophop gh feature` task questions.
|
51 |
|
52 | Config:
|
53 |
|
54 | ```ts
|
55 | type Option = 'ask' | 'no' | 'n' | 'nope' | 'yes' | 'y' | 'yep' | 'si' | 'of course' | 'youbetcha';
|
56 |
|
57 | type Config = {
|
58 | apiUrl?: string; // default: 'https://api.github.com'
|
59 | branchSuffix?: Option; // default: 'ask'
|
60 | moveToWIP?: Option; // default: 'y'
|
61 | openPRWithTestPlanTemplate?: Option; // default: 'y'
|
62 | closeIssueWithPR?: Option // default: 'y',
|
63 | openPRAsDraft?: 'Option' // default: 'n'
|
64 | kaiten?: { // default: undefined
|
65 | boardId: number;
|
66 | backlogColumnId: number;
|
67 | };
|
68 | };
|
69 | ```
|
70 |
|
71 | #### example
|
72 |
|
73 | ```yaml
|
74 | branchSuffix: y
|
75 | ```
|
76 |
|
77 | ## Kaiten support
|
78 | hophop supports using Kaiten for issue tracking. To enable Kaiten add the `kaiten` section in `.hophoprc`, for example:
|
79 |
|
80 | ```yaml
|
81 | kaiten:
|
82 | - boardId: 123123
|
83 | backlogColumnId: 123123
|
84 | ```
|
85 |
|
86 | You can configure as many combinations of boardId/backlogColumnId as you want:
|
87 |
|
88 | ```yaml
|
89 | kaiten:
|
90 | - boardId: 123123
|
91 | backlogColumnId: 123123
|
92 | - boardId: 456456
|
93 | backlogColumnId: 456456
|
94 | ```
|
95 |
|
96 | > 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
|
97 |
|
98 | Once Kaiten is configured all hophop commands will automatically use it instead of GitHub.
|
99 | 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.
|
100 |
|
101 | ## zsh autocompletion
|
102 |
|
103 | After installing the package, an autocompletion file is available at
|
104 | ```
|
105 | NPM_PREFIX/lib/node_modules/@buildo/hophop/_hophop
|
106 | ```
|
107 |
|
108 | where `NPM_PREFIX` is usually `/usr/local` and it can be retrieved using `npm prefix -g`
|
109 |
|
110 | #### Installation using oh-my-zsh
|
111 |
|
112 | If you use [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh), installing the autocompletion is as easy as:
|
113 |
|
114 | ```bash
|
115 | mkdir -p ~/.oh-my-zsh/custom/plugins/hophop
|
116 | ln -s `(npm prefix -g)`/lib/node_modules/@buildo/hophop/bin/_hophop ~/.oh-my-zsh/custom/plugins/hophop/_hophop
|
117 | touch ~/.oh-my-zsh/custom/plugins/hophop/hophop.plugin.zsh
|
118 | ```
|
119 |
|
120 | Then enable the plugin in your `.zshrc`, for example:
|
121 | ```bash
|
122 | plugins=(git brew hophop)
|
123 | ```
|