README.md
1## Broot
2
3[![CI][s3]][l3] [![MIT][s2]][l2] [![Latest Version][s1]][l1] [![Chat on Miaou][s4]][l4]
4
5[s1]: https://img.shields.io/crates/v/broot.svg
6[l1]: https://crates.io/crates/broot
7
8[s2]: https://img.shields.io/badge/license-MIT-blue.svg
9[l2]: LICENSE
10
11[s3]: https://travis-ci.org/Canop/broot.svg?branch=master
12[l3]: https://travis-ci.org/Canop/broot
13
14[s4]: https://miaou.dystroy.org/static/shields/room.svg
15[l4]: https://miaou.dystroy.org/3490?broot
16
17A better way to navigate directories
18
19[**Installation Instructions**](https://dystroy.org/broot/install/)
20
21## Get an overview of a directory, even a big one
22
23`br -s`
24
25
26
27Notice the *unlisted*?
28
29That's what makes it usable where the old `tree` command would produce pages of output.
30
31`.gitignore` files are properly dealt with to put unwanted files out of your way (you can ignore them though, see [documentation](https://dystroy.org/broot/navigation/#toggles)).
32
33## Find a directory then `cd` to it
34
35type a few letters
36
37
38
39Hit <kbd>alt</kbd><kbd>enter</kbd> and you're back to the terminal in the desired location.
40
41This way, you can navigate to a directory with the minimum amount of keystrokes, even if you don't exactly remember where it is.
42
43broot is fast and doesn't block (any keystroke interrupts the current search to start the next one).
44
45Most useful keys for this:
46
47* the letters of what you're looking for
48* <kbd>enter</kbd> on the root line to go up to the parent (staying in broot)
49* <kbd>enter</kbd> to focus a directory (staying in broot)
50* <kbd>esc</kbd> to get back to the previous state or clear your search
51* <kbd class=b>↓</kbd> and <kbd class=b>↑</kbd> may be used to move the selection
52* <kbd>alt</kbd><kbd>enter</kbd> to get back to the shell having `cd` to the selected directory
53* `:q` if you just want to quit (you can use <kbd>ctrl</kbd><kbd>q</kbd> if you prefer)
54
55## Never lose track of file hierarchy while you search
56
57
58
59broot tries to select the most relevant file. You can still go from one match to another one using <kbd>tab</kbd> or arrow keys.
60
61You may also search with a regular expression. To do this, add a `/` before the pattern.
62
63And you have other types of searches, for example searching on file content (start with `c/`):
64
65
66
67You 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`.
68
69Once the file you want is selected you can
70
71* hit <kbd>enter</kbd> (or double-click) to open it in your system's default program
72* hit <kbd>alt</kbd><kbd>enter</kbd> to open it in your system's default program and close broot
73* hit <kbd>ctrl</kbd><kbd>→</kbd> to preview it (and then a second time to go inside the preview)
74* type a verb. For example `:e` opens the file in your preferred editor (which may be a terminal one)
75
76[blog: a broot content search workflow](https://dystroy.org/blog/broot-c-search/)
77
78## Manipulate your files
79
80
81
82Most often you move your files in the blind. You do a few `ls` before, then your manipulation, and maybe you check after.
83
84You can instead do it without losing the view of the file hierarchy.
85
86Move, copy, rm, mkdir, are built in and you can add your own shortcuts.
87
88## Manage files with panels
89
90When 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>).
91
92
93
94(yes, colors are fully customizable)
95
96Using two panels, you can for example copy or move elements between them:
97
98
99
100If 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>.
101
102## Preview files
103
104Hit <kbd>ctrl</kbd><kbd>→</kbd> when a file is selected and the preview panel appears.
105
106
107
108
109
110The preview panel stays synchronized with the selection in tree panels.
111
112If your terminal is [kitty](https://sw.kovidgoyal.net/kitty/index.html), then the image preview is high definition:
113
114
115
116## Apply a standard or personal shortcut to a file
117
118
119
120Just find the file you want to edit with a few keystrokes, type `:e`, then <kbd>enter</kbd>.
121
122You can add verbs or configure the existing ones; see [documentation](https://dystroy.org/broot/conf_verbs/).
123
124And you can add shortcuts, for example a <kbd>ctrl</kbd> sequence or a function key
125
126## Replace `ls` (and its clones):
127
128If you want to display *sizes*, *dates* and *permissions*, do `br -sdp` which gets you this:
129
130
131
132You may also toggle options with a few keystrokes while inside broot. For example hitting a space, a `d` then enter shows you the dates. Or a space, then `h` then enter and you see hidden files.
133
134## Sort, see what takes space:
135
136You 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.
137
138When sorting, the whole content of directories is taken into account. So if you want to find on Monday morning the most recently modified files, launch `br --sort-by-date ~`.
139
140If 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.
141
142
143
144And you keep all broot tools, like filtering or the ability to delete or open files and directories.
145
146If you hit `:fs`, you can check the usage of all filesystems, so that you focus on cleaning the full ones.
147
148
149
150Sizes, dates, files counts, are computed in the background, you don't have to wait for them when you navigate.
151
152## check git statuses:
153
154
155
156Use `:gf` to display the statuses of files (what are the new ones, the modified ones, etc.), the current branch name and the change statistics.
157
158And 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.
159
160[blog: use broot and meld to diff before commit](https://dystroy.org/blog/gg/)
161
162## Further Reading
163See **[Broot's web site](https://dystroy.org/broot)** for instructions regarding installation and usage.
164
