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
|
# Broot Documentation
## General Usage & Semantics
A broot command is typed in the input at the bottom and is made of two parts, a **pattern** and a **verb**, both optional, separated by either a space or `:`.
Example:
![command](img/20190110-pattern_verb.png)
There the pattern is `car` and the verb shortcut is `e`.
The pattern filters the tree while you type. It's interpreted in a fuzzy way so that you don't have to type all the letters or even consecutive letters. The best match is automatically selected.
At any moment you can use the arrow keys to move the selection. You can also use the tab key.
When you hit `<enter>`:
* if there's a verb, it is executed, which may quit broot or change its state
* if there's none, and a directory is selected, this directory becomes the new root and the pattern is cleared
* if there's no verb and a file is selected, `xdg-open` is called on the file
Hitting ̀ <esc>` clears the current pattern, or brings you back to the previous root. If there was none, it quits broot.
Hitting `?` brings you to the help screen.
## Flags
Flags are displayed at the bottom right, showing the settings regarding hidden files and .gitignore rules.
![flags](img/20190101-flags.png)
## Verbs
The definition of a verb (which you'll find in the configuration file, see below) is made of three parts:
* an invocation string, which you should make short if you want to use it often
* a name, which is used for inline help
* the execution
For example this one:
[[verbs]]
name = "edit"
invocation = "e"
execution = "/usr/bin/nvim {file}"
This means that typing `:e` then `<enter>` opens the selected file in neovim.
(this is a part of the default configuration, and probably the first verb you should change for your personal setup)
Most verbs aren't based on an external application but calls internal functions:
### `:back` : get back to the previous state of the tree
This is normally achieved with the ̀ esc` key but you might want to remap it.
### `:cd` : cd to a directory
`:cd` is the most useful verb but only works if you're using the [shell integration](README.md#use-broot-for-navigation).
In the default configuration it's mapped to `c`.
### `:focus` : change the tree's root
`:focus` makes the selected directory become the new displayed root.
The difference with ̀just using `<enter>` is that the current filtering pattern is kept.
In the default configuration, it's mapped to `g`.
### `:open` : call the OS standard program for the selected file
This is automatically called when you hit `<enter>` without a verb and a file (not a directory) is selected. Current implementation calls `xdg_open`.
In the default configuration, it's mapped to `o`.
### `:parent` : moves the view one level up
Display the parent directory.
In the default configuration, it's mapped to `p`.
### `:quit`
In the default configuration, it's mapped to `q`.
### `:toggle_files`
Swith between displaying only directories or showing everything.
In the default configuration, it's mapped to `f`.
### `:toggle_gitignore` : adjust git ignore rule respect
.gitignore files are parsed and used depending on the current "gitignore" setting:
* when "no", .gitignore files are ignored
* when "yes", each directory is filtered according to the applied gitignore files (several git repositories may be simultaneously shown and a git repository may define several .gitignore files)
* when "auto" (default value), gitignore rules are ignored unless the root directory is a git repository or inside one
This setting is displayed at the top right of the screen:
![flags](img/20190110-flags.png)
In the default configuration, it's mapped to `gi`.
### `:toggle_hidden`
Switch between showing or hiding hidden files (the ones whose name starts with a dot).
In the default configuration, it's mapped to `h`.
You can start broot with hidden files shown by using `broot --hidden` or `br -h`.
### `:toggle_perm` : display file permissions
Toggle displaying permissions in the classical `rwxrwxrwx user group` way.
In the default configuration, it's mapped to `perm`. You might want to remap it if you use it a lot.
### `:toggle_sizes`
Swith between displaying file & directory sizes or not.
Sizes are computed in the background, so this doesn't slow your navigation.
When sizes are displayed, all the direct children of the current root are displayed, which means there can be a scrollbar (you may use the page up and page down keys).
In the default configuration, it's mapped to `s` and can be activated at launch using `broot --sizes`.
## Configuration File
When broot starts, it checks for a configuration file in the standard location defined by your OS and creates one if there's none.
You can see this location by opening the help with ̀`?`. You can also open it directly from the help screen by typing `:o`.
## Passing commands as program argument
*Note: this feature is experimental and will probably change.*
Commands to be executed can be passed using the `--cmd` argument, separated with a space.
### Direcly search
broot --cmd miaou /
This opens broot and immediately search for "miaou" in `/` as if it were typed in broot's input.
### Go to the most relevant directory
broot -c ":p miaou :g"
This opens broot, goes to the parent directory, searches for "miaou", then opens the selected directory (staying in broot).
A variant searching from your home directory:
br -f -c "miaou :g" ~
### define a function for deep fuzzy cd
In my .bashrc, I have this:
# deep fuzzy cd
function dcd {
br --only-folders --cmd "$1 :c"
}
This is the *"I'm feeling lucky"* of broot, I use it to directly jump to directories I know, when I don't need the interactive search of br.
|