Skip to content

Latest commit

 

History

History
456 lines (333 loc) · 15.6 KB

help.md

File metadata and controls

456 lines (333 loc) · 15.6 KB

Flow Control: a programmer's text editor

Terminal configuration

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+alt

For other terminals you will probably have to disable or rebind them each individually.

Searching

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 and logs

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.

Input Modes

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.

Flow mode

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.

Vim 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.

Helix 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)

Tabs and panel tabs

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

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

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 150

Most 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 than background_syntax_threshold lines 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.

Language servers

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 __.

Initialization options

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.

Settings

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.

EditorConfig and save options

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_style sets the indent mode.
  • indent_size sets the indent size.
  • tab_width sets the tab width.
  • end_of_line sets the line end mode that a save writes. Flow Control ignores end_of_line = cr, because it has no CR mode.
  • trim_trailing_whitespace sets whether a save removes trailing whitespace.
  • insert_final_newline sets 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.

Clicks in shell prompts

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 true

terminal_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.

Flags and options

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.