1[![Crates.io](https://img.shields.io/crates/v/git-interactive-rebase-tool.svg)][crates-io]
2[![Build Status](https://travis-ci.org/MitMaro/git-interactive-rebase-tool.svg?branch=master)][travis-build]
3[![Build status](https://ci.appveyor.com/api/projects/status/3a6j6n4o5x6aa763/branch/master?svg=true)][appveyor-build]
4[![GitHub license](https://img.shields.io/badge/license-GPL-blue.svg)][license]
5
6# Git Interactive Rebase Tool
7
8Native cross-platform full feature terminal based [sequence editor][git-sequence-editor] for interactive rebase in
9Git 1.7.8+. Written in Rust using ncurses.
10
11![Git Interactive Rebase Tool](/docs/assets/images/git-interactive-rebase-demo.gif?raw=true)
12
13**This is the documentation for the development build. For the current stable release please use the
14[1.2.x documentation](https://github.com/MitMaro/git-interactive-rebase-tool/tree/1.2.1/README.md).**
15
16## Install
17
18* [Cargo](./readme/install.md#cargo-package-manager)
19* [Arch](./readme/install.md#arch-linux)
20* [Debian](./readme/install.md#debian-and-derivatives)
21* [FreeBSD](./readme/install.md#freebsd)
22* MacOS
23  * [Homebrew](./readme/install.md#macos-via-homebrew)
24  * [Manual](./readme/install.md#macos-manual-install)
25* [Windows](./readme/install.md#windows)
26
27## Configure
28
29### Most systems
30
31    git config --global sequence.editor interactive-rebase-tool
32
33### Windows
34
35#### Standard Command Pompt
36
37    git config --global sequence.editor "'C:/path/to/interactive-rebase-tool.exe'"
38
39#### GitBash
40
41GitBash requires the use of `winpty` in order to work correctly, so to set the editor use:
42
43    git config --global sequence.editor "winpty /c/path/to/interactive-rebase-tool.exe"
44
45#### Notes
46
47Windows before version 10 has [serious rendering issues with saturated darker colors](https://devblogs.microsoft.com/commandline/updating-the-windows-console-colors/),
48such as the blue color, that are completely illegible on modern displays. While it is possible to avoid using the
49saturated colors, a better option is to update the theme using Microsoft's [ColorTool](https://github.com/Microsoft/Terminal/tree/master/src/tools/ColorTool).
50
51## Usage
52
53```shell
54interactive-rebase-tool <rebase-todo-filepath>
55interactive-rebase-tool --help
56interactive-rebase-tool --version
57```
58
59### Getting Help
60
61The tool has built-in help that can be accessed by hitting the `?` key.
62
63
64### Default Key Bindings
65
66Key bindings can be configured, see [configuration](#configuration) for more information.
67
68| Key          | Mode   | Description |
69| ------------ | ------ | ----------- |
70|  Up          | All    | Move selection up |
71|  Down        | All    | Move selection down |
72|  Page Up     | All    | Move selection up five lines |
73|  Page Down   | All    | Move selection down five lines |
74|  `q`         | Normal | Abort interactive rebase |
75|  `Q`         | Normal | Immediately abort interactive rebase |
76|  `w`         | Normal | Write interactive rebase file |
77|  `W`         | Normal | Immediately write interactive rebase file |
78|  `?`         | All    | Show help |
79|  `c`         | Normal | Show commit information |
80|  `j`         | All    | Move selected commit(s) down |
81|  `k`         | All    | Move selected commit(s) up |
82|  `b`         | Normal | Toggle break action |
83|  `p`         | All    | Set selected commit(s) to be picked |
84|  `r`         | All    | Set selected commit(s) to be reworded |
85|  `e`         | All    | Set selected commit(s) to be edited |
86|  `s`         | All    | Set selected commit(s) to be squashed |
87|  `f`         | All    | Set selected commit(s) to be fixed-up |
88|  `d`         | All    | Set selected commit(s) to be dropped |
89|  `E`         | Normal | Edit the command of an exec action |
90|  `V`         | All    | Enter and exit visual mode |
91
92
93### Temporary Override
94
95You can temporarily use a different sequence editor by using the `GIT_SEQUENCE_EDITOR` environment variable:
96
97    GIT_SEQUENCE_EDITOR=emacs git rebase -i [<upstream> [<branch>]]
98
99
100### Configuration
101
102The tool can be configured using the [git config][git-config] command. Invalid values are ignored and the default used
103instead. String values are case-insensitive.
104
105#### Example
106
107```
108git config --global interactive-rebase-tool.foregroundColor black
109```
110
111#### General
112
113| Key                        | Default | Type   | Description |
114| -------------------------- | ------- | ------ | ----------- |
115| `autoSelectNext`           | false   | bool   | If true, auto select the next line after action modification |
116| `verticalSpacingCharacter` | ~       | String | Vertical spacing character. Can be set to an empty string. |
117
118#### Colors
119
120The valid colors are the [eight original 8 ANSI colors][ANSIColors]. They are `black`, `blue`, `cyan`, `green`,
121`magenta`, `red`, `white` and `yellow`. Each terminal controls the exact color for these color names. On terminals that
122support 256 colors, a color triplet with the format `<red>,<green>,<blue>` can be used. Each color has a range of 0 to
123255 with `255, 255, 255` resulting in white and `0,0,0` resulting in black. A value of `-1` or `transparent` can be used
124to use the default terminal color.
125
126| Key                       | Default  | Type  | Description |
127| ------------------------- | -------- | ----- | ----------- |
128| `breakColor`              | white    | Color | Color used for the break action |
129| `diffAddColor`            | green    | Color | Color used for lines and files added in a diff |
130| `diffChangeColor`         | yellow   | Color | Color used for lines and files changed in a diff |
131| `diffRemoveColor`         | red      | Color | Color used for lines and files removed in a diff |
132| `dropColor`               | red      | Color | Color used for the drop action |
133| `editColor`               | blue     | Color | Color used for the edit action |
134| `fixupColor`              | magenta  | Color | Color used for the fixup action |
135| `foregroundColor`         | white    | Color | Color used for most text and the UI |
136| `indicatorColor`          | cyan     | Color | Color used for text the indicates or needs to standout  |
137| `pickColor`               | green    | Color | Color used for the pick action |
138| `rewordColor`             | yellow   | Color | Color used for the reword action |
139| `selectedBackgroundColor` | 35,35,40 | Color | Color used as the background color for the selected line |
140| `squashColor`             | cyan     | Color | Color used for the squash action |
141
142#### Key Bindings
143
144| Key                        | Default  | Type   | Description |
145| -------------------------- | -------- | ------ | ----------- |
146| `inputAbort`               | q        | String | Key for abort rebase with prompt |
147| `inputActionBreak`         | b        | String | Key for setting action to rebase |
148| `inputActionDrop`          | d        | String | Key for setting action to drop |
149| `inputActionEdit`          | e        | String | Key for setting action to edit |
150| `inputActionFixup`         | f        | String | Key for setting action to fixup |
151| `inputActionPick`          | p        | String | Key for setting action to pick |
152| `inputActionReword`        | r        | String | Key for setting action to reword |
153| `inputActionSquash`        | s        | String | Key for setting action to squash |
154| `inputConfirmNo`           | n        | String | Key for rejecting a confirmation |
155| `inputConfirmYes`          | y        | String | Key for confirming a confirmation |
156| `inputEdit`                | E        | String | Key for entering edit mode |
157| `inputForceAbort`          | Q        | String | Key for forcing an abort of the rebase |
158| `inputForceRebase`         | W        | String | Key for forcing a rebase |
159| `inputHelp`                | ?        | String | Key for showing the help |
160| `inputMoveDown`            | Down     | String | Key for moving the cursor down |
161| `inputMoveLeft`            | Left     | String | Key for moving the cursor left |
162| `inputMoveRight`           | Right    | String | Key for moving the cursor right |
163| `inputMoveSelectionDown`   | j        | String | Key for moving the selected line(s) down |
164| `inputMoveSelectionUp`     | k        | String | Key for moving the selected line(s) up |
165| `inputMoveStepDown`        | PageDown | String | Key for moving the cursor down by a large step |
166| `inputMoveStepUp`          | PageUp   | String | Key for moving the cursor up  by a large step|
167| `inputMoveUp`              | Up       | String | Key for moving the cursor up |
168| `inputOpenInExternalEditor`| !        | String | Key for opening the external editor |
169| `inputRebase`              | w        | String | Key for rebasing with confirmation |
170| `inputShowCommit`          | c        | String | Key for showing the selected commit |
171| `inputToggleVisualMode`    | v        | String | Key for toggling visual mode |
172
173##### Special Keys
174
175| Key        | Description |
176| ---------- | ----------- |
177| `PageDown` | Page Down key |
178| `Down`     | Down arrow key |
179| `Left`     | Left arrow key |
180| `Right`    | Right arrow key |
181| `Up`       | Up arrow key |
182| `PageUp`   | Page Up key |
183
184#### Configuring External Editor
185
186The external editor action will first attempt to start the editor defined by the
187[Git configuration "core.editor"][git-core-editor], followed by the `VISUAL` and
188`EDITOR` environment variables. Finally, if neither is set the external editor
189defaults to using `vi`.
190
191The `%` character in the value will be replaced with the git rebase todo file.
192If the `%` character is not found, then the git rebase todo file will be
193provided as the last argument.
194
195## Development
196
197### Install Rust
198
199To start developing the project you will need to [install Rust][install-rust], which can generally be done using
200[rustup].
201
202
203### Setup
204
205#### Debian and derivatives
206
207You will need `build-essential` and `libncurses5-dev` to build the project. Additionally, you will need `pkg-config` and
208`liblzma-dev` if you wish to build a release. They can be installed using `apt-get`:
209
210    sudo apt-get install build-essential libncursesw5-dev
211    sudo apt-get install pkg-config liblzma-dev
212
213
214### Build and run
215
216Use cargo to build and run the project. From the project root run:
217
218    # only build
219    cargo build --release
220    # build and run
221    cargo run <path-to-git-rebase-todo-file>
222
223
224### Format
225
226Use rust-fmt format project. **You need to run format with nightly.** The current nightly rust version is
227nightly-2019-09-13. You can find the current nightly rust version in the `scripts/format.bash`.
228
229    # format code before you commit
230    cargo +nightly-2019-09-13 fmt
231
232
233### Release
234
235##### Install Cargo Deb
236
237    cargo install cargo-deb
238
239##### Building
240
241    cargo build --release
242    cargo deb
243
244A deb file will be written to `target/debian/interactive-rebase-tool_*.deb`.
245
246## TODO
247
248 - [x] Full support for `exec` action
249 - [ ] Insert action
250 - [x] Configure key bindings
251
252## Related Projects
253
254* [rebase-editor] is a very similar project written in Node.js.
255
256## License
257
258Git Interactive Rebase Tool is released under the GPLv3 license. See [LICENSE](LICENSE).
259
260See [Third Party Licenses](THIRD_PARTY_LICENSES) for licenses for third-party libraries used by this project.
261
262[ANSIColors]:https://en.wikipedia.org/wiki/ANSI_escape_code#3/4_bit
263[appveyor-build]:https://ci.appveyor.com/project/MitMaro/git-interactive-rebase-tool/branch/master
264[cargo]:https://github.com/rust-lang/cargo
265[crates-io]:https://crates.io/crates/git-interactive-rebase-tool
266[git-config]:https://git-scm.com/docs/git-config
267[git-core-editor]:https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_code_core_editor_code
268[git-sequence-editor]:https://git-scm.com/docs/git-config#git-config-sequenceeditor
269[install-rust]:https://doc.rust-lang.org/book/getting-started.html
270[license]:https://raw.githubusercontent.com/MitMaro/git-interactive-rebase-tool/master/LICENSE
271[rebase-editor-issue-7]:https://github.com/sjurba/rebase-editor/issues/7
272[rebase-editor]:https://github.com/sjurba/rebase-editor
273[releases]:https://github.com/MitMaro/git-interactive-rebase-tool/releases
274[rustup]:https://www.rustup.rs/
275[travis-build]:https://travis-ci.org/MitMaro/git-interactive-rebase-tool
276