connect.kak

Installation | Usage | Configuration | Documentation | Contributing

Connect a program to Kakoune clients.

· connect.kak

Dependencies

• prelude.kak
• terminal-mode.kak

Suggestion

• explore.kak
• yank-ring.kak

Installation

Add rc to your autoload or source connect.kak and its modules manually.

Start an interactive shell

Add kak-shell to your path.

Add to desktop

1. Copy kakoune-connect.desktop to $XDG_DATA_HOME/applications.
2. Copy Kakoune’s logo to $XDG_DATA_HOME/icons/hicolor/scalable/apps/kakoune.svg.
3. Add kak-desktop to your path.
4. Open $XDG_CONFIG_HOME/mimeapps.list and add the following MIME type association:

[Default Applications]
text/plain=kakoune-connect.desktop
text/xml=kakoune-connect.desktop

Add more entries to your liking.

Prompt

1. Copy the prompt to $XDG_DATA_HOME/kak/connect/prompt.
2. Depending on your shell:

PS1='$($XDG_DATA_HOME/kak/connect/prompt) $ '

Usage

Connect a terminal with :connect-terminal. Open files with the edit shell command or your favorite program; buffers with the buffer shell command…

You can start an interactive shell (or a program) connected to a session – in the same way nix-shell does – with kak-shell. By default, the connections occur in the same terminal window (try :fzf-files or :fzf-buffers to see); you can change the terminal settings with ,tcr (for user mode – terminal – connect – reset), which resets the detach option and prompts you to choose a windowing system (X11, tmux, etc.). You can change it at your will with ,t. The terminal-mode.kak interface is similar to i3’s split commands.

Illustration

$ kak-shell
Kakoune sessions:
1 kanto
2 johto
+ create new session
Kakoune session: 1█
client0 at kanto $ edit
:fzf-files

Configuration

# Modules
require-module connect-fzf

# Explore files and buffers with fzf
alias global explore-files fzf-files
alias global explore-buffers fzf-buffers

# Terminal settings
map global user t ': enter-user-mode terminal<ret>' -docstring 'Terminal'

# Create a new window
map global normal <c-n> ': new<ret>'
map global normal <c-t> ': connect-terminal<ret>'

# Quit
map global normal <c-q> ': quit<ret>'

# Yank ring
map global normal Y ': yank-ring<ret>'

By setting the option connect_environment, you can specify commands that are run before the shell is executed. This might be useful, if you want to change or export environment variables:

set-option global connect_environment %{
  SHELL=elvish
  export GIT_EDITOR='kak -c "$KAKOUNE_SESSION"'
  export LYEDITOR='edit %(file)s +%(line)s:%(column)s'
}

More controversial mappings

Delapouite – More controversial mappings

# Buffers
map global normal b ': fzf-buffers<ret>'
map global normal B ': enter-user-mode -lock buffers<ret>'

# Move [b] to [q], so that [qwe] actions are aligned.
map global normal q b
map global normal Q B
map global normal <a-q> <a-b>
map global normal <a-Q> <a-B>

# Move macros to ^
map global normal ^ q
map global normal <a-^> Q

Documentation

Kakoune

Defined in connect.kak.

Commands

• connect-terminal (alias: t): Connect a terminal.
• connect-shell (alias: T): Connect a shell.
• connect-detach (alias: d): Write the given shell command to your connect data path and detach the client.

Options

• connect_attach: Attach to terminal. Default is no.
• connect_data_path: Path to connect data. Default is $XDG_DATA_HOME/kak/connect or ~/.local/share/kak/connect.

Modules

Defined in modules.

• connect-broot
• connect-dmenu
• connect-dolphin
• connect-fzf
• connect-lf
• connect-nnn
• connect-rofi
• connect-wofi

Shell

Commands

Defined in commands and aliases.

• edit (alias: e): Open files.
• buffer (alias: b): Open buffers. With no argument, list buffers instead.
• attach (alias: a): Attach a command ran from Kakoune with :connect-detach.
• it: Get the current buffer.
• send: Send a command.
• get: Get a property.

Environment variables

Defined in env.

• IN_KAKOUNE_CONNECT: Determine whether the shell is connected to a Kakoune session.
• KAKOUNE_SESSION: Kakoune session.
• KAKOUNE_CLIENT: Kakoune client.
• KAKOUNE_CONNECT_SCRIPT: Path to connect script, used by :connect-detach for writing shell commands.
• KAKOUNE_CONNECT_ATTACH: Whether to attach to terminal.
• EDITOR: Editor to be used. Default is edit.
• VISUAL: Visual editor to be used. Default is edit.
• GIT_EDITOR: Git editor to be used. Default is edit -wait.