keymap.toml.md

keymap.toml

This file is for mapping keyboard keys to commands.

# keymapping for default view
[default_view]
keymap = [
    { keys = [ "T" ], command = "new_tab" },
    # ...
]

# keymapping for task view
[task_view]
keymap = [
    # ...
]

# keymapping for help view
[help_view]
keymap = [
    # ...
]

For more examples, take a look at config/keymap.toml

Keys available:

To combine keys with Ctrl and Alt, simply have ctrl+key/alt+key where key is a valid key.

In addition to the standard alphabet, Joshuto currently also support the following keys.

backspace
backtab     # this is shift+tab
arrow_left
arrow_right
arrow_up
arrow_down
home
end
page_up
page_down
delete
insert
escape
f1
f2
f3
f4
f5
f6
f7
f8
f9
f10
f11
f12

Commands available:

• General
• Navigation
• Tabs
• Search
• Integration

General

quit: quit joshuto

• will not quit if there are pending IO work (paste jobs)
• quit
  • exit code 0
• quit --force: does NOT wait for pending IO work
  • exit code 100
• quit --output-current-directory: if --output-file argument is set, output the current directory to it
  • exit code 101
• quit --output-selected-files: if --output-file argument is set, output the selected files to it
  • exit code 102

The following is a bash snippet on how to integrate with quit

function joshuto() {
	ID="$$"
	mkdir -p /tmp/$USER
	OUTPUT_FILE="/tmp/$USER/joshuto-cwd-$ID"
	env joshuto --output-file "$OUTPUT_FILE" $@
	exit_code=$?

	case "$exit_code" in
		# regular exit
		0)
			;;
		# output contains current directory
		101)
			JOSHUTO_CWD=$(cat "$OUTPUT_FILE")
			cd "$JOSHUTO_CWD"
			;;
		# output selected files
		102)
			;;
		*)
			echo "Exit code: $exit_code"
			;;
	esac
}

:: opens the command prompt

• this does not execute the command, but merely sets the text to it
• Example: :cd / will open up the command prompt with cd / already written

shell: runs a shell command

• %s and %p are substituted by a list of all selected files or by the file under the cursor, if none is selected
• When running the external program, the directory shown in Joshuto is set as “working directory”, the file names substituted for %s are given without path. If you want the absolute path, use %p.
• Example: :shell touch file.txt will create a file called file.txt
• Example for keymap.toml: To open all selected files with nvim, one can add a keybinding like this:

  keymap = [ //..
     { keys = [ "e", "v" ], commands = ["shell nvim %s"] }
  ]

• To set a wallpaper on sway using the absolute path of an image file:

  keymap = [ //..
    { keys = ["m", "w"], commands = ["shell swaymsg output * bg %p fit"] }
  ]

spawn: runs a shell command in the background

• Supports %sand %p, just like the shell command.
• Example for keymap.toml: To open all selected files or directories with sxiv, one can add a keybinding like this:

  keymap = [ //..
     { keys = [ "i" ], commands = ["spawn sxiv -t %s"] }
  ]

suspend: suspends the current session

can be mapped to Ctrl+z to behave similarly to other programs

sort: change the sort method

• sort lexical: sort lexically (10.txt comes before 2.txt)
• sort natural: sort naturally (2.txt comes before 10.txt)
• sort mtime: sort via last modified time
• sort size: sort by file size
• sort ext: sort by extension
• sort reverse: reverse the sorting

All methods (except reverse) support the --reverse flag:

• --reverse=true applies sort method and sets reverse to true
• --reverse=false applies sort method and sets reverse to false

linemode: change the line-mode (textual representation of files and directories in the “current view”)

• linemode size: show the entry’s size (bytes for files, number of entries for directories) (default) ^✻
• linemode mtime: show the entry’s modified time (aka. “mtime”) ^✻
• linemode sizemtime: show the entry’s size and modified time ^✻

^{✻: file- or directory-name is shown on left, the respective meta-data is shown on the right, preceded by a symlink indicator}

show_workers: show the pending IO operations and the current progress

• press escape to exit view

toggle_hidden: toggle hidden files

line_nums: switch displaying of entry numbers

• line_nums 0 or line_nums none: disable displaying
• line_nums 1 or line_nums absolute: enable absolute numbers for each entry
• line_nums 2 or line_nums relative: enable numbers relative to selected entry

flat: flattens the directory view up to the specified depth.

• flat 3: flatten directory up to 3 directories deep. depth of 0 corresponds to the current directory. its direct descendents have depth 1, and their descendents have depth 2, and so on.

Navigation

cursor_move_up: moves the cursor up by x amount

• cursor_move_up: moves the cursor up by 1
• cursor_move_up x: moves the cursor up by x where x is a non-negative number

cursor_move_down: moves the cursor down by x amount

• cursor_move_down: moves the cursor down by 1
• cursor_move_down x: moves the cursor down by x where x is a non-negative number

cursor_move_home: moves cursor to beginning of directory list

cursor_move_end: moves cursor to end of directory list

cursor_move_page_up: moves the cursor up by x

• where x is the number of items that can be seen on the screen

cursor_move_page_down: moves the cursor down by x

• where x is the number of items that can be seen on the screen

parent_cursor_move_up: same as cursor_move_up but for parent directory

parent_cursor_move_down: same as cursor_move_down but for parent directory

preview_cursor_move_up: moves the preview up

preview_cursor_move_down: moves the preview down

cd: change directory

• cd ..: go to parent directory
• cd ~: go to home directory
• cd -: go to previous directory in history (If it exists)

open: open file or directory

• if joshuto does not know how to open the file format (via extension currently), it will prompt :open_with to open with a specific command
• if xdg_open is true in joshuto.toml, joshuto will try to open it via xdg settings

numbered_command: opens a new mode where user can input numbers and jump to the specified location via hard-coded keybindings

• numbered_command 3: initial input is 3

Tabs

new_tab [--last] [--current|--cursor|dir]: opens a new tab

• new_tab, without any argument, opens a new tab with the default directory.

(Note: the default directory for new tabs is specified in joshuto.toml in the tab section.)

• new_tab some-dir opens new tab with directory some-dir
• new_tab --current opens new tab with the same directory as the current tab
• new_tab --cursor opens new tab with the directory which is currently marked by the cursor
• new_tab --last new tab will be placed at the end of the stack. This is the only flag that can be combined with the others described above.

close_tab: close current tab

tab_switch: switch to next/previous tab by x

• where x is an integer
• tab_switch 1: go to next tab
• tab_switch -1: go to previous tab

tab_switch_index: switch to a given tab index

• tab_switch_index 3: go to third tab if it exists, create one if it does not exist and there is already 3 - 1 = 2 tabs open

File Operations

reload_dirlist: reloads the current directory listing

mkdir: create a new directory (usually used as :mkdir )

cut_files: store selected files (or current file if none were selected) to be moved later

copy_files: store selected files (or current file if none were selected) to be copied later

symlink_files: store selected files (or current file if none were selected) to be symlinked later

• --relative=true: relative symlink paths
• --relative=false: absolute symlink paths

paste_files: move/copy files stored from a previous cut_files or copy_files command

delete_files: delete selected files (or current file if none were selected).

• --foreground=true: will delete files in the foreground
• --permanently: force permanent deletion regardless of use_trash value.
• --noconfirm: files will be deleted without asking for confirmation (can be dangerous when use_trash is false)
• will permanently delete files if use_trash is false in joshuto.toml/wiki/Configuration#joshutotoml)
• if use_trash is true, joshuto will try to use the following command-line tools to try to put the files in the trash can instead of permanently deleting them
  • gio trash
  • trash-put: https://github.com/andreafrancia/trash-cli
  • trash
  • gtrash put

rename: rename the current file the cursor is on

• :rename new_name

rename_append: opens the command prompt with the rename command and the current file name filled in.

• cursor will be set to the end of the file name

rename_append_base: opens the command prompt with the rename command and the current file name filled in.

• cursor will be set right after the base name of the file. (beginning of the file name if no base name)

rename_prepend: opens the command prompt with the rename command and the current file name filled in.

• cursor will be set to the beginning of the file name

rename_keep_ext: opens the command prompt with the rename command and the extension of the current file filled in.

• cursor will be set right before the extension of the file

copy_filename: copy the file name to clipboard

• clipboard support requires xsel, xclip, or wl-copy

copy_filename_without_extension: copy the file name without the extension to clipboard

copy_filepath: copy the current file path to clipboard

copy_dirpath: copy the current directory path to clipboard

set_mode: Set read, write, execute permissions of current file

touch: create a new file or update the modified date of an existing file

Search and Selection

search: search the current directory via a string

search_glob: search the current directory via shell globbing (exact match)

• :search_glob *.png

search_regex: search the current directory via regex (exact match)

• :search_regex .+\.(jpg|png|gif)

search_next: go to next search result in the current directory

search_prev: go to previous search result in the current directory

select: select current file

• --toggle=true: toggle the selected state rather than selecting the entry (default)
• --toggle=false: select the current file (doesn't change anything if the current file is already selected)
• --deselect=true: deselect rather than select the entry
• --all=true: select/deselect/toggle all visible files in the current view. (Files not visible due to a set filter are not affected.)
• when a pattern is given, joshuto selects files whose names contain the pattern
  • select png

This example keybinding can be used for deselecting all files:

keymap = [ //..
   {keys = [ "x" ], command = "select --all=true --deselect=true"}
]

select_glob: select files in the current directory via globbing (exact match)

• :select_glob --toggle=false '*.png'

This command has the same options for select. Notice that it's necessary to quote the pattern when spaces are contained.

select_regex: select files in the current directory via regex (exact match)

• :select_regex --toggle=false '.+\.(jpg|png|gif)'

This command has the same options for select. Notice that it's necessary to quote the pattern when spaces and \ are contained.

select_fzf: select files in the current directory via fzf

This command has the same options for select. Use tab to select or deselect files in fzf.

filter: filter the current directory list.

• :filter ca: filter the current directory and show only items with ca in the name

filter_glob: filter the current directory list via globbing.

• :filter_glob *.png

filter_regex: filter the current directory list via regex.

• :filter_regex .+\.(jpg|png|gif)

toggle_visual: enables or disables “visual mode”.

When disabling, the current “visual mode selection” is turned into normal selection. (See also Visual Mode.)

escape: leave visual mode and withdraw the visual-mode-selection.

(See also Visual Mode.)

set_case_sensitivity: set case sensitivity for different search operations.

• Options
  • --type=string: change configurations of operations using substring matching
  • --type=glob: change configurations of operations using glob matching
  • --type=regex: change configurations of operations using regex
  • --type=fzf: change configurations of operations using fzf
  • when no option is added, type is set to string by default
• Value
  • insensitive
  • sensitive
  • smart

An example:

:set_case_sensitivity --type=fzf sensitive

custom_search

Define search command using custom_command

custom_search_interactive

Similar to select and custom_search. Allows user to execute custom_command and then interactively operate on the results.

Bookmarks

add_bookmark: adds a bookmark to the bookmarks.toml file

cd_bookmark: prompts a menu of bookmarks and navigates to selected bookmark

Integration

bulk_rename: rename all selected files

• this will create a file inside $TMP_DIR (or /tmp if $TMP_DIR is not set) and open up your text editor of choice via $EDITOR environment variable
• once you've made your changes to the file, saved and quit, it will use the mv command to rename everything

search_fzf: search the current directory via fzf

subdir_fzf: go to a subdirectory via fzf

z: cd via zoxide

zi: cd via interactive zoxide