1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
## Broot
[![Tests][s3]][l3] [![MIT][s2]][l2] [![Latest Version][s1]][l1] [![Chat on Miaou][s4]][l4] [![Packaging status][srep]][lrep]
[s1]: https://img.shields.io/crates/v/broot.svg
[l1]: https://crates.io/crates/broot
[s2]: https://img.shields.io/badge/license-MIT-blue.svg
[l2]: LICENSE
[s3]: https://github.com/Canop/broot/actions/workflows/tests.yml/badge.svg
[l3]: https://github.com/Canop/broot/actions/workflows/tests.yml
[s4]: https://miaou.dystroy.org/static/shields/room.svg
[l4]: https://miaou.dystroy.org/3490?broot
[srep]: https://repology.org/badge/tiny-repos/broot.svg
[lrep]: https://repology.org/project/broot/versions
Broot is a better way to navigate directories, find files, and launch commands.
[**Complete Documentation**](https://dystroy.org/broot/) -
[**Installation Instructions**](https://dystroy.org/broot/install/) -
[**Contributing or Getting Help**](https://dystroy.org/blog/contributing/)
## Get an overview of a directory, even a big one
Hit `br -s`
Notice the *unlisted*?
That's what makes it usable, where the old `tree` command would produce pages of output.
`.gitignore` files are properly dealt with to put unwanted files out of your way.
As you sometimes want to see gitignored files, or hidden ones, you'll soon get used to the <kbd>alt</kbd><kbd>i</kbd> and <kbd>alt</kbd><kbd>h</kbd> shortcuts to toggle those visibilities.
(you can ignore them though, see [documentation](https://dystroy.org/broot/navigation/#toggles)).
## Find a directory, then `cd` to it
type a few letters
Hit <kbd>alt</kbd><kbd>enter</kbd> and you're back to the terminal in the desired location.
This way, you can navigate to a directory with the minimum amount of keystrokes, even if you don't exactly remember where it is.
Broot is fast and doesn't block (any keystroke interrupts the current search to start the next one).
Most useful keys for this:
* the letters of what you're looking for
* <kbd>enter</kbd> on the root line to go up to the parent (staying in broot)
* <kbd>enter</kbd> to focus a directory (staying in broot)
* <kbd>esc</kbd> to get back to the previous state or clear your search
* <kbd class=b>↓</kbd> and <kbd class=b>↑</kbd> may be used to move the selection
* <kbd>alt</kbd><kbd>enter</kbd> to get back to the shell, having `cd` to the selected directory
* <kbd>alt</kbd><kbd>h</kbd> to toggle showing hidden files (the ones whose name starts with a dot)
* <kbd>alt</kbd><kbd>i</kbd> to toggle showing gitignored files
* `:q` if you just want to quit (you can use <kbd>ctrl</kbd><kbd>q</kbd> if you prefer)
## Never lose track of file hierarchy while you search
Broot tries to select the most relevant file. You can still go from one match to another one using <kbd>tab</kbd> or arrow keys.
You may also search with a regular expression. To do this, add a `/` before the pattern.
And you have [other types of searches](input/#the-filtering-pattern), for example, searching on file content (start with `c/`):
You may also apply logical operators or combine patterns, for example, searching `test` in all files except JSON ones could be `!/json$/&c/test` and searching `carg` both in file names and file contents would be `carg|c/carg`.
Once the file you want is selected, you can
* hit <kbd>enter</kbd> (or double-click) to open it in your system's default program
* hit <kbd>alt</kbd><kbd>enter</kbd> to open it in your system's default program and close broot
* hit <kbd>ctrl</kbd><kbd>→</kbd> to preview it (and then a second time to go inside the preview)
* type a verb. For example, `:e` opens the file in your preferred editor (which may be a terminal one)
[blog: a broot content search workflow](https://dystroy.org/blog/broot-c-search/)
## Manipulate your files
Most often, when not using broot, you move your files in the blind. You do a few `ls` before, then your manipulation, and maybe you check after.
You can instead do it without losing the view of the file hierarchy.
Move, copy, rm, mkdir, are built in, and you can add your own shortcuts.
Here's chmod:
## Manage files with panels
When a directory is selected, do <kbd>ctrl</kbd><kbd>→</kbd> and you open another panel (you may open other ones, or navigate between them, with <kbd>ctrl</kbd><kbd>←</kbd> and <kbd>ctrl</kbd><kbd>→</kbd>).
(yes, colors are fully customizable)
You can, for example, copy or move elements between panels:
If you like, you may do it Norton Commander style by binding `:copy_to_panel` to <kbd>F5</kbd> and `:move_to_panel` to <kbd>F6</kbd>.
## Preview files
Hit <kbd>ctrl</kbd><kbd>→</kbd> when a file is selected, and the preview panel appears.
The preview panel stays synchronized with the selection in the tree panels.
Broot displays images in high resolution when the terminal supports Kitty's graphics protocol
(compatible terminals: [Kitty](https://sw.kovidgoyal.net/kitty/index.html), [WezTerm](https://wezfurlong.org/wezterm/)):
## Apply a standard or personal command to a file
Just find the file you want to edit with a few keystrokes, type `:e`, then <kbd>enter</kbd>.
You can add verbs or configure the existing ones; see [documentation](https://dystroy.org/broot/conf_file/#verbs-shortcuts-and-keys).
And you can add shortcuts, for example, a <kbd>ctrl</kbd> sequence or a function key
## Apply commands on several files
Add files to the [staging area](staging-area), then execute any command on all of them.
## Replace `ls` (and its clones):
If you want to display *sizes*, *dates*, and *permissions*, do `br -sdp` which gets you this:
You may also toggle options with a few keystrokes while inside broot.
For example, you could have typed this `-sdp` while in broot.
Or hit <kbd>alt</kbd><kbd>h</kbd> and you see hidden files.
## Sort, see what takes space:
You may sort by launching broot with `--sort-by-size` or `--sort-by-date`. Or you may, inside broot, type a space, then `sd`, and <kbd>enter</kbd> and you toggled the `:sort_by_date` mode.
When sorting, the whole content of the directories is taken into account. So if you want to find on Monday morning the most recently modified files, launch `br --sort-by-date ~`.
If you start broot with the `--whale-spotting` option (or its shortcut `-w`), you get a mode tailored to "whale spotting" navigation, making it easy to determine what files or folders take space.
Sizes, dates, and file counts are computed in the background; you don't have to wait for them when you navigate.
And you keep all broot tools, like filtering or the ability to delete or open files and directories.
If you hit `:fs`, you can check the usage of all filesystems, so that you focus on cleaning the full ones.
## Check git statuses:
Use `:gf` to display the statuses of files (what are the new ones, the modified ones, etc.), the current branch name and the change statistics.
And if you want to see *only* the files which would be displayed by the `git status` command, do `:gs`. From there it's easy to edit, or diff, selected files.
From there, it's easy to edit, diff, or revert selected files.
[blog: use broot and meld to diff before commit](https://dystroy.org/blog/gg/)
## Further Reading
See **[Broot's web site](https://dystroy.org/broot)** for instructions regarding installation and usage.
|
