Most terminals have default keybindings that conflict with common editor commands. I highly recommend rebinding them to keys that are not generally used anywhere else.
For Kitty rebinding kitty_mod by adding this line to your kitty.conf is
usually enough:
kitty_mod ctrl+altFor other terminals you will probably have to disable or rebind them each individually.
Press ctrl+f to search this help file. Type a search term and press ctrl+n/ctrl+p or f3/shift+f3 to jump through the matches. Press Enter to exit find mode at the current match or Escape to return to your starting point.
Normal text search and regular expression search are supported. While the find prompt is open:
- alt+c => Cycle case mode: auto, exact, case-folded
- alt+r => Toggle between normal search and regular expression search
The auto case mode is smart-case: a query with no uppercase letters searches case-folded, while a query containing uppercase letters searches exactly. Regex search has the same case modes: regex auto, regex exact and regex case-folded.
The selected find mode is persisted between sessions.
Messages of issues regarding tasks that are not accomplished, like trying to
close flow with unsaved files, as well as other information are shown
briefly in the bottom status bar; most recent messages can be seen in the
log view too, to open it, use ctrl+shift+p > View log; it's possible to
make it taller dragging the toolbar with the mouse up or downwards.
Flow Control supports multiple input modes that may be changed interactively at runtime. The current input mode (and some other settings) is persisted in the configuration file automatically.
- f4 => Cycle major input modes (flow, emacs, vim, helix,...)
The current input mode is displayed at the left side of the statusbar.
- ctrl+shift+p or alt+x => Show the command palette
The command palette allows you to fuzzy search and select commands to run. It also shows any available keybind that may be used to run the command without opening the palette.
- ctrl+f2 => Show all available commands and keybinds
This shows all currently available commands. Including commands that are normally only executed via a keybinding. Selecting a command in this view will insert the command name into the current document instead of executing it. This is very useful for editing keybinding definition files.
Run the Edit keybindings command to customize the current keybinding mode.
It will write a customization file for the current mode into the keys
directory, under the same name as the current mode, and open it for editing.
This file inherits everything from the built-in mode of the same name. So
keybindings that are added or changed by future updates of Flow Control are
picked up automatically. Each sub-mode is an empty section you can fill in:
add new keybindings or override one by binding the same key to another
command. Delete the file from the keys directory to revert entirely to the
built-in mode. Changes to keybinding files take effect on restart.
You can also create additional, independently named keybinding modes by
saving a file under a new name in the same directory. You can select the new
mode with f4.
Keybinding modes may inherit all non-conflicting keybindings from another
mode by adding an inherit option to the settings section of the keybind
file like this:
{
"settings": {
"inherit": "vim",
},
"normal": {
...This allows you to make only minor additions/changes to an existing builtin mode without copying the whole mode and is easier to keep up-to-date.
Use the special value <<builtin>> to inherit from the built-in mode with
the same name as your file. This lets a file customize a built-in mode while
still inheriting from it, and is what Edit keybindings writes:
{
"settings": {
"inherit": "<<builtin>>",
},
...A sub-mode that is left out of your file entirely is inherited whole from the mode you inherit from, so you only need to include the sub-modes you actually want to change.
Additionally, individual sub-modes may inherit all non-conflicting
keybindings from another sub-mode of the same mode by adding an inherit
option to the sub-mode section like this:
"normal": {
"inherit": "project",
...Multiple inheritance is supported with the inherits options like this:
"normal": {
"inherits": ["project", "tasks"],
...A sub-mode may inherit only the keybindings that begin with a particular
prefix key by using the inherit_prefix option. Each entry is a prefix key
followed by one or more parent sub-modes to copy the matching keybindings
from. For example, this makes every keybinding that starts with ctrl+alt+a
in the project mode also work in the terminal mode:
"terminal": {
"inherit_prefix": [["ctrl+alt+a", "project"]],
...The inherit_breakout option copies every keybinding from a parent sub-mode
and prepends a "breakout" prefix key to each, claiming that key in this
sub-mode. It is used to implement vim's insert-normal (CTRL-O) behaviour:
pressing the breakout key in insert mode runs a single normal mode command
and then returns to insert mode. For example:
"insert": {
"inherit_breakout": [["<C-o>", "normal"]],
...A numeric count typed before the command (e.g. <C-o>3w) is not currently
supported.
The default input mode, called just flow, is based on common GUI programming editors. It most closely resembles Visual Studio Code, but also takes some inspiration from Emacs and others. This mode focuses on powerful multi cursor support with a find -> select -> modify cycle style of editing.
See the ctrl+f2 palette when flow mode is selected to see the full list of
keybindings for this mode.
The vim modes, shown as NORMAL, INSERT or VISUAL in the status bar, follow the basic modal editing style of vim. The basics follow vim closely, but more advanced vim functions (e.g. macros and registers) are not supported (yet). Keybindings from flow mode that do not conflict with vim keybindings also work in vim mode.
The helix modes, shown as NOR, INS or SEL in the status bar, follow the basic modal editing style of helix. The basics are being adapted closely, more advanced functions (e.g. surround, macros, selections, registers) are not supported (yet). Usual keybinding with LSPs are used for tasks like 'go to definition', 'go to reference' and 'inline documentation' featuring inline diagnostics. Keybindings from flow mode that do not conflict with helix keybindings also work in helix mode.
(work in progress)
These are the default flow mode keybindings for tabs. The vim and helix modes inherit them.
Editor tabs:
-
ctrl+page_down, ctrl+page_up => Switch to the next/previous tab
-
ctrl+shift+page_down, ctrl+shift+page_up => Move the tab to the next/previous position. At the end of a split, the tab moves into the next/previous split. At the end of the last split, the tab moves into a new split.
-
ctrl+alt+shift+page_down, ctrl+alt+shift+page_up => Move the tab to the next/previous split. In the last split, the tab moves into a new split.
-
ctrl+alt+tab, ctrl+alt+shift+tab => Switch to the next/previous panel tab without focusing it.
Mouse commands are NOT rebindable and are not listed in the command palette.
-
Left Click => Clear all cursors and selections and the place cursor at the mouse pointer
-
Double Left Click => Select word at mouse pointer
-
Triple Left Click => Select line at mouse pointer
-
Drag Left Click => Extend selection to mouse pointer
-
Alt + Left Click => Add cursor at mouse click
-
Ctrl + Left Click => Goto definition of symbol at click
-
hold Alt => Enable jump/hover mouse mode
-
Right Click => Extend selection to mouse pointer
-
Middle Click => Close tab
-
Back Button, Forward Button => Jump to previous/next location in the location history
-
Scroll Wheel => Scroll
-
Alt + Scroll Wheel => Fast scroll
-
Ctrl + Scroll Wheel => Zoom (GUI only)
Configuration is stored in the standard location
${XDG_CONFIG_HOME}/flow/config. This is usually ~/.config/flow/config.
The default configuration will be written the first time Flow Control is started and looks similar to this:
frame_rate 60
theme "default"
input_mode "flow"
gutter_line_numbers true
gutter_line_numbers_relative false
enable_terminal_cursor false
highlight_current_line true
highlight_current_line_gutter true
show_whitespace false
animation_min_lag 0
animation_max_lag 150Most of these options are fairly self explanatory.
theme, input_mode and show_whitespace are automatically persisted when
changed interactively with keybindings.
frame_rate can be tuned to control the maximum number of frames rendered.
animation_max_lag controls the maximum amount of time allowed for
rendering scrolling animations. Set to 0 to disable scrolling animation
altogether.
background_syntax controls where Flow Control does parsing for syntax
highlighting.
"auto": parse files with more thanbackground_syntax_thresholdlines in the background. This is the default."always": parse all files in the background."never": parse all files before they are shown.
background_syntax_threshold is a number of lines. The default is 20000.
syntax_injection_depth sets how deep Flow Control highlights embedded
languages, for example Rust code in a Rust macro in another Rust macro. The
default is 6. With 1, only languages that are embedded directly in the file
get highlights. With 0, embedded languages get no highlights.
File types may be configured with the Edit file type configuration
command. You can also create a new file type by adding a new .conf file to
the file_type directory. Have a look at an existing file type to see what
options are available.
The file type configuration names the language server of a file type in its
language_server option. When you open a file of that type, flow starts the
server.
You can give a language server two JSON files. Each file exists in a global form and in a project form. If the project file exists, flow uses it and ignores the global file. Flow does not merge the two.
In the file names below, <server> is the name of the server program, for
example rust-analyzer. <project> is the path of the project directory
with each path separator replaced by __.
The initialization options file holds the value that flow sends to the
server once, when the server starts (initializationOptions in the
initialize request).
- Global:
~/.config/flow/lsp/<server>.json - Project:
~/.config/flow/project/<project>/<server>.json
Open these files with the commands Edit LSP configuration (global) and
Edit LSP configuration (project).
Example, ~/.config/flow/lsp/rust-analyzer.json:
{
"check": {
"command": "clippy"
}
}If you change this file, restart the server with the command
Language: Restart language server.
The settings file holds the values that the server asks for while it runs
(the workspace/configuration request). Some servers, for example nixd,
read their values only this way.
- Global:
~/.config/flow/lsp/<server>.settings.json - Project:
~/.config/flow/project/<project>/<server>.settings.json
Open these files with the commands Edit LSP settings (global) and
Edit LSP settings (project).
A server asks for a section by name, for example nixd or
nixd.formatting. Flow looks up that name as a path in the file, so the
file must have the shape that the server asks for. Most servers put all
values below a top key with the name of the server. The documentation of a
server usually shows this shape as its VS Code settings.
Example, ~/.config/flow/lsp/nixd.settings.json:
{
"nixd": {
"formatting": {
"command": ["nixfmt"]
}
}
}When you save a settings file, flow tells the running server of the current
project (workspace/didChangeConfiguration). You do not need to restart the
server. If a server does not react, use the command
Language: Send settings to language server, or restart the server.
Some servers accept the same values in both files, but in different shapes. Read the documentation of the server to find out which file it uses.
Flow Control supports the EditorConfig standard.
When a file opens, Flow Control reads the .editorconfig file in the
directory of the file and in each parent directory. A .editorconfig file
with root = true stops the search. Flow Control watches these files up to
the nearest file with root = true, or else up to the project directory. If
you change, add or remove a watched .editorconfig file, the new values
apply to the open files immediately.
The supported properties set these editor values:
indent_stylesets the indent mode.indent_sizesets the indent size.tab_widthsets the tab width.end_of_linesets the line end mode that a save writes. Flow Control ignoresend_of_line = cr, because it has no CR mode.trim_trailing_whitespacesets whether a save removes trailing whitespace.insert_final_newlinesets whether a save adds (true) or removes (false) the newline at the end of the file.
Flow Control ignores the other properties, for example charset and
max_line_length.
You can also set the save values in the configuration, without EditorConfig:
trim_trailing_whitespace_on_save false
final_newline_on_save "keep"final_newline_on_save is "keep", "insert" or "remove".
A save does not remove trailing whitespace from a line that has a cursor. Save all and quit with save apply these values to the files that are open in an editor, but not to files in background tabs.
To disable EditorConfig, set enable_editorconfig false.
In a terminal panel, a left click on the command line of a shell prompt moves the shell's cursor to the clicked character. This works only if the shell marks its prompt with OSC 133 escape sequences. Fish 4.1 and later receives the click and moves its cursor itself. For other shells that mark their prompt, Flow Control sends left or right arrow keys. The arrow keys only move the cursor inside the current line.
A click with a modifier key, a double click and a drag select text as before.
Bash does not mark its prompt. To add the marks, add these lines to
~/.bashrc:
PS1='\[\e]133;A;cl=line\e\\\]'"$PS1"'\[\e]133;B\e\\\]'
PS0='\[\e]133;C\e\\\]'133;A marks the start of the prompt, and cl=line asks for arrow keys.
133;B marks the start of the command line. 133;C in PS0 marks the
start of the command output. Without 133;C, Flow Control does not know
that a command is running, and a click sends arrow keys to the command.
These options control prompt clicks:
terminal_prompt_click_to_move true
terminal_prompt_click_implicit_line trueterminal_prompt_click_to_move false disables prompt clicks. Use it if your
shell does not handle them well.
terminal_prompt_click_implicit_line false sends arrow keys only to shells
that ask for them with cl=. With true, Flow Control also sends arrow
keys to a shell that marks its prompt but does not ask for them.
As every respectable terminal program, flow provide various invoking options
that among others, will allow you to inspect various aspects of the running
session. Feel free to run flow --help to explore them.