brookjeynes.dev
地圖 (Jido) is a lightweight Unix TUI file explorer designed for speed and simplicity.
1# 地圖 (Jido)
2
3
4
5**Jido** is a lightweight Unix TUI file explorer designed for speed and
6simplicity.
7
8The name 地圖 (지도) translates to "map" in English, reflecting Jido's
9purpose: helping you navigate and explore your file system with ease. With
10Vim-like bindings and a minimalist interface, Jido focuses on speed and
11simplicity.
12
13Jido is built with Zig v`0.15.2`.
14
15- [Installation](#installation)
16- [Integrations](#integrations)
17- [Key manual](#key-manual)
18- [Configuration](#configuration)
19- [Contributing](#contributing)
20
21## Installation
22To install Jido, check the "Releases" page or build locally
23via `zig build --release=safe`.
24
25## Integrations
26- `pdftotext` to view PDF text previews.
27- A terminal supporting the `kitty image protocol` to view images.
28
29## Key manual
30Below are the default keybinds. Keybinds can be overwritten via the `Keybinds`
31config option. Some keybinds are unbound by default, see [Configuration](#configuration)
32for more information.
33
34```
35Global:
36<CTRL-c> :Exit.
37<CTRL-r> :Reload config.
38
39Normal mode:
40j / <Down> :Go down.
41k / <Up> :Go up.
42h / <Left> / - :Go to the parent directory.
43l / <Right> :Open item or change directory.
44g :Go to the top.
45G :Go to the bottom.
46c :Change directory via path. Will enter input mode.
47R :Rename item. Will enter input mode.
48D :Delete item.
49u :Undo delete/rename.
50d :Create directory. Will enter input mode.
51% :Create file. Will enter input mode.
52/ :Fuzzy search directory. Will enter input mode.
53. :Toggle hidden files.
54: :Allows for Jido commands to be entered. Please refer to the
55 "Command mode" section for available commands. Will enter
56 input mode.
57v :Verbose mode. Provides more information about selected entry.
58y :Yank selected item.
59p :Past yanked item.
60x :Extract archive to `<name>/`.
61
62Input mode:
63<Esc> :Cancel input.
64<CR> :Confirm input.
65
66Command mode:
67<Up> / <Down> :Cycle previous commands.
68:q :Exit.
69:h :View available keybinds. 'q' to return to app.
70:config :Navigate to config directory if it exists.
71:trash :Navigate to trash directory if it exists.
72:empty_trash :Empty trash if it exists. This action cannot be undone.
73:cd <path> :Change directory via path. Will enter input mode.
74:extract :Extract archive under cursor.
75```
76
77## Configuration
78Configure `jido` by editing the external configuration file located at either:
79- `$HOME/.jido/config.json`
80- `$XDG_CONFIG_HOME/jido/config.json`.
81
82Jido will look for these env variables specifically. If they are not set, Jido
83will not be able to find the config file.
84
85An example config file can be found [here](https://github.com/BrookJeynes/jido/blob/main/example-config.json).
86
87Config schema:
88```
89Config = struct {
90 .show_hidden: bool = true,
91 .sort_dirs: bool = true,
92 .show_images: bool = true, -- Images are only supported in a terminal
93 supporting the `kitty image protocol`.
94 .preview_file: bool = true,
95 .empty_trash_on_exit: bool = false, -- Emptying the trash permanently deletes
96 all files within the trash. These
97 files are not recoverable past this
98 point.
99 .true_dir_size: bool = false, -- Display size of directory including
100 all its children. This can and will
101 cause lag on deeply nested directories.
102 .archive_traversal_limit: usize = 100, -- How many files to be traversed when reading
103 an archive (zip, tar, etc.).
104 .keep_partial_extraction: bool = false, -- If extraction fails, keep the partial
105 extracted directory instead of cleaning up.
106 .keybinds: Keybinds,
107 .styles: Styles
108}
109
110Keybinds = struct {
111 .toggle_hidden_files: ?Char = '.',
112 .delete: ?Char = 'D',
113 .rename: ?Char = 'R',
114 .create_dir: ?Char = 'd',
115 .create_file: ?Char = '%',
116 .fuzzy_find: ?Char = '/',
117 .change_dir: ?Char = 'c',
118 .enter_command_mode: ?Char = ':',
119 .jump_top: ?Char = 'g',
120 .jump_bottom: ?Char = 'G',
121 .toggle_verbose_file_information: ?Char = 'v',
122 .force_delete: ?Char = null -- Files deleted this way are
123 not recoverable
124 .yank: ?Char = 'y'
125 .paste: ?Char = 'p'
126 .extract_archive: ?Char = 'x'
127}
128
129NotificationStyles = struct {
130 .box: vaxis.Style,
131 .err: vaxis.Style,
132 .warn: vaxis.Style,
133 .info: vaxis.Style
134}
135
136Styles = struct {
137 .selected_list_item: Style,
138 .list_item: Style,
139 .file_name: Style,
140 .file_information: Style
141 .notification: NotificationStyles,
142 .git_branch: Style
143}
144
145Style = struct {
146 .fg: Color,
147 .bg: Color,
148 .ul: Color,
149 .ul_style = .{
150 off,
151 single,
152 double,
153 curly,
154 dotted,
155 dashed
156 }
157 .bold: bool,
158 .dim: bool,
159 .italic: bool,
160 .blink: bool,
161 .reverse: bool,
162 .invisible: bool,
163 .strikethrough: bool
164}
165
166Color = enum{
167 default,
168 index: u8,
169 rgb: [3]u8
170}
171
172Char = enum(u21)
173```
174
175## Contributing
176Contributions, issues, and feature requests are always welcome via
177[GitHub](https://github.com/brookjeynes/jido) or
178[tangled](https://tangled.sh/@brookjeynes.dev/jido).