diff options
Diffstat (limited to 'website/docs/documentation')
-rw-r--r-- | website/docs/documentation/configuration.md | 165 | ||||
-rw-r--r-- | website/docs/documentation/installation.md | 50 | ||||
-rw-r--r-- | website/docs/documentation/tricks.md | 39 | ||||
-rw-r--r-- | website/docs/documentation/usage.md | 254 |
4 files changed, 508 insertions, 0 deletions
diff --git a/website/docs/documentation/configuration.md b/website/docs/documentation/configuration.md new file mode 100644 index 0000000..6433ac9 --- /dev/null +++ b/website/docs/documentation/configuration.md @@ -0,0 +1,165 @@ + +# Opening the configuration file + +The configuration file location follows the XDG convention and its location depends on your OS. + +The easiest way to read and edit broot's configuration file is to go the help screen (using <kbd>?</kbd>) then to type `:open`. + +This file is called conf.toml and is in [TOML](https://github.com/toml-lang/toml). + +Currently, you can configure + +* verbs +* colors + +# Verbs + +You can define a new verb in the TOML configuration file with a `[[verbs]]` section similar to this one: + + [[verbs]] + invocation = "edit" + shortcut = "e" + execution = "/usr/bin/nvim {file}" + +## Verb Definition Attributes + +name | mandatory | role +-|-|- +invocation | yes | how the verb is called by the user, with placeholders for arguments +execution | yes | how the verb is executed +shorcut | no | an alternate way to call the verb (without the arguments part) +leave_broot | no | whether to quit broot on execution (default: `true`) +from_shell | no | whether the verb must be executed from the parent shell (needs `br`, default: `false`) + +### Shortcuts and Verb search + +**broot** looks for the first token following a space or `:` and tryes to find the verb you want. + +* If what you typed is exactly the shorcut or name of a verb, then this verb is selected: broot explains you what it would do if you were to type `enter` +* If there's exactly one verb whose name or shortcut starts with the characters you typed, then it's selected +* if there are several verbs whose name or shortcut start with the characters you typed, then broot waits for more +* if no verb has a name or shortcut starting with those characters, broot tells you there's a problem + +Knowing this algorithm, you may understand the point in the following definition: + + [[verbs]] + invocation = "p" + execution = ":parent" + +This verb is an alias to the internal builtin already available if you type `:parent`. + +Its interest is that if you do `:p`, then `enter`, it is executed even while there are other verbs whose invocation pattern starts with a `p`. + +Use shortcuts for verbs you frequently use. + + +### Arguments + +The execution of a verb can take one or several arguments. + +For example it may be defined as `/usr/bin/vi {file}̀ . + +Some arguments are predefined in broot and depends on the current selection: + +name | expanded to +-|- +`{file}` | the complete path of the current selection +`{parent}` | the complete path of the current selection's parent +`{directory}` | the closest directory, either `{file}` or `{parent}` + +!!! Note + when you're in the help screen, `{file}` is the configuration file, while `{directory}` is the configuration directory. + +But you may also define some arguments in the invocation pattern. For example: + + [[verbs]] + invocation = "mkdir {subpath}" + execution = "/bin/mkdir -p {directory}/{subpath}" + +(this one has now been made standard so you don't have to write it in the configuration file) + +In this case the subpath is read from what you type: + +![md sub](../img/20190306-md.png) + +As you see, there's a space in this path, but it works. **broot** tries to determine when to wrap path in quotes and when to escape so that such a command correctly works. + +It also normalizes the paths it finds which eases the use of relative paths: + +![mv](../img/20190306-mv.png) + +Here's another example, where the invocation pattern defines two arguments by destructuring: + + [[verbs]] + invocation = "blop {name}\\.{type}" + execution = "/bin/mkdir {parent}/{type} && /usr/bin/nvim {parent}/{type}/{name}.{type}" + from_shell = true + +And here's how it would look like: + +![blop](../img/20190306-blop.png) + +Notice the `\\.` ? That's because the invocation pattern is interpreted as a regular expression +(with just a shortcut for the easy case, enabling `{name}`). +The whole regular expression syntax may be useful for more complex rules. +Let's say we don't want the type to contain dots, then we do this: + + [[verbs]] + invocation = "blop {name}\\.(?P<type>[^.]+)" + execution = "/bin/mkdir {parent}/{type} && /usr/bin/nvim {parent}/{type}/{name}.{type}" + from_shell = true + +# Colors + +You can change all colors by adding a `[skin]` section in your `conf.toml` file. + +For example: + + [skin] + status_normal_fg = "grayscale(18)" + status_normal_bg = "grayscale(3)" + status_error_fg = "red" + status_error_bg = "yellow" + tree_fg = "red" + selected_line_bg = "grayscale(7)" + permissions_fg = "grayscale(12)" + size_bar_full_bg = "red" + size_bar_void_bg = "black" + directory_fg = "lightyellow" + input_fg = "cyan" + flag_value_fg = "lightyellow" + table_border_fg = "red" + code_fg = "lightyellow" + +which would look like this: + +![custom colors tree](../img/20190217-custom-colors-tree.png) + +![custom colors help](../img/20190217-custom-colors-help.png) + +Complete list of keys (expected to change before the v1 of broot): + + char_match + code + directory + file + file_error + flag_label + flag_value + exe + input + link + permissions + selected_line + size_bar_full + size_bar_void + size_text + spinner + status_error + status_normal + table_border + tree + unlisted + +Add `_fg` for a foreground color while `_bg` is for background colors. + diff --git a/website/docs/documentation/installation.md b/website/docs/documentation/installation.md new file mode 100644 index 0000000..0302111 --- /dev/null +++ b/website/docs/documentation/installation.md @@ -0,0 +1,50 @@ + +The current version of broot only runs on linux. + +Precompiled binaries and the crates.io repository are updated at the same time, with tested releases. + +If you prefer to get the very last version, even when not tagged, you may compile from the sources available on GitHub. + +# From precompiled binaries + +The last one is always made available at: + +* [x86_64-linux](https://dystroy.org/broot/download/x86_64-linux/broot) + +You may download previous releases on [GitHub releases](https://github.com/Canop/broot/releases). + +# From crates.io + +You'll need to have the [Rust development environment](https://www.rust-lang.org/tools/install) installed. + +Once it's installed, use cargo to install broot: + + cargo install broot + +# From source + +You'll need to have the [Rust development environment](https://www.rust-lang.org/tools/install) installed. + +Fetch the Canop/broot repository, move to the broot directory, then run + + cargo build --release + +The executable is written in the `target/release` directory (you might want to move it to your `/usr/bin`, or to add the release directory to your path). + +# Installation Completion : the `br` shell function + +broot is convenient to find a directory then `cd` to it, which is done using `<alt><enter>` or `:cd`. + +But broot needs a companion function in the shell in order to be able to change directory. + +When you start broot, it checks whether the `br` shell function seems to have been installed (or +to have been refused). If needed, and if the used shell seems compatible (supported shells today are bash, zsh and fish), +then broot asks the permission to register this shell function. + +If you have messed with the configuration files, you might want to have the shell function reinstalled. + +In order to do this, either remove all broot config files, or launch `broot --install`. + +When it's done, you can do just `br` to launch broot, and typing `<alt><enter>` will cd for you. + + diff --git a/website/docs/documentation/tricks.md b/website/docs/documentation/tricks.md new file mode 100644 index 0000000..18d3fa3 --- /dev/null +++ b/website/docs/documentation/tricks.md @@ -0,0 +1,39 @@ + +## `dcd` : Deep fuzzy cd + +When you want to cd to a deep directory, using `br` is fast and easy enough: + +* you type `br` (and `enter`) +* you type the name of the deep folder (or part of it) +* you check the right line is selected +* you do `alt-enter` +* you're done + +But when you frequently go to a few specific places, you may prefer a shortcut. + +As broot can be driven by commands, you can define this function: + + # deep fuzzy cd + function dcd { + br --only-folders --cmd "$1 :c" + } + +(paste this for example in your .bashrc) + +This is the *"I'm feeling lucky"* of broot, you can use it to directly jump to directories you know, when you don't need the interactive search of br. + +Example: + +![dcd ruleset](../img/20190122-dcd_rulset.png) + +## focus a new directory but keep the current filter + +Similarly, `:back` keeps can be used in place of `esc` to keep the filter when going to the previous state. + +## Going from a fixed search to an exact one + +Let's assume you type `too` to search for some files. You might have got too many matches including some where the letters aren't consecutive. + +You may switch to an exact search by just adding `/`, which changes the fuzzy pattern to a regular expression. + +Or if you realize you want to match `tOo` too, then you make it case insensitive by adding an i: `too/i`. diff --git a/website/docs/documentation/usage.md b/website/docs/documentation/usage.md new file mode 100644 index 0000000..f4948d6 --- /dev/null +++ b/website/docs/documentation/usage.md @@ -0,0 +1,254 @@ + +# Launch Broot + +When the installation is [complete](installation.md##installation-completion-the-br-shell-function), you may start broot with either + + broot + +or + + br + +If your shell is compatible, you should prefer `br` which enables some features like `cd` from broot. + +You can pass as argument the path you want to see, for example + + br ~ + +# Navigate + +## Basics + +When you start broot, the current directory is displayed, with some directories open and or some lines truncated, in order to fit the available height. + +The first line is called the root, and is currently selected. + +From here you may navigate using the following keys: + +* <kbd class=b>↓</kbd> or <kbd class=b>↑</kbd> : select the next or previous line +* <kbd class=b>⏎</kbd> on a simple file : leave broot and open the file using xdg-open +* <kbd class=b>⏎</kbd> on a directory : focus the directory (i.e. make it the new root) +* <kbd>esc</kbd> gets you back to the previous state (or leave broot if there's none) +* <kbd>alt</kbd> + <kbd class=b>⏎</kbd> on a directory : leave broot and `cd` the shell to that directory. +* <kbd>?</kbd> brings you to the help screen + +## Fuzzy Patterns + +You would usually not just navigate this way: you'll filter the tree. + +This is done simply by typing a few letters. + +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. + +For example: + +![search hel](../img/20190305-search-hel.png) + +Hitting <kbd>esc</kbd> clears the current pattern. + +## Regular Expressions + +If there's a `/` before or after the patten, it's interpreted as a regular expression. + +For example `/pat+ern` would match `"patern.zip"` or `"some_patttern.rar"` but not `"pATTern"`. + +If you want the regex to be case insensitive, add the `i` flag: `pat+ern/i`. + +## Flags + +Flags are displayed at the bottom right, showing the settings regarding hidden files and .gitignore rules. + +![flags](../img/20190101-flags.png) + +## Toggles + +Initially, broot doesn't show files whose name starts with a dot, or files declared as ignored by a `.gitignore` file. Permissions and file sizes aren't shown. + +This behavior is tuned with several toggles. + + | name | shortcut | description + |-------------------|----------|-------------------------------------------------- + | toggle_files | files | toggle showing files (or just folders) + | toggle_git_ignore | gi | toggle use of .gitignore + | toggle_hidden | h | toggle showing hidden files + | toggle_perm | perm | toggle showing file permissions + | toggle_sizes | sizes | toggle showing sizes + | toggle_trim_root | t | toggle removing nodes at first level too (default) + +To apply one, just type a space (or `:`), then the start of its shortcut, then hit <kbd class=b>⏎</kbd>. + +For example typing `:s` then enter will show directory sizes: + +![dev sizes](../img/20190305-dev-sizes.png) + +You may notice a scrollbar on this screenshot. +You may sometimes want to *not* trim the first level of the tree, which is done by using the `toggle_trim_root` (and which is also automatically done when displaying sizes). + +## gitignore + +The gitignore "toggle" has 3 modes: + +mode | display | filtering +-|-|- +no | `gi:n` | .gitignore files aren't applied +yes | `gi:y` | .gitignore rules are applied whenever they're found. If the root contains several git projects, it means different visible subtrees follow different sets of rules +auto| `gi:a` | if the current root is a git directory or inside one, then the rules are applied. Otherwise they aren't + +## Quitting broot + +Other than executing a command leaving broot, there are several ways to quit: + +* if the current root is selected, just hit `enter` +* hit <kbd>ctrl</kbd>+<kbd>Q</kbd> +* type `:q` or ` q` then `enter` + +# Verbs & Command + +When you used a toggle, you executed a command in it simplest form: without argument and independant from the current selection. + +The simplest verbs are just executed by typing a space (or `:`), then its first letters, then enter. + +A verb can be related to the current selection. For example typing `:p` will execute the `:parent` verb, which focuses the parent of the selection (*focusing* means taking the selected directory and making it the current root). + +## Verbs using the selection + +The `rm` verb executes the standard `rm` command. + +It's defined by this couple (invocation, execution): + + invocation = "rm" + execution = "/bin/rm -rf {file}" + +When you type a verb, the execution pattern is completed using the selection (`{file}`), the exact command is displayed in the status line: + +![rm](../img/20190305-rm.png) + +As for filters, hitting <kbd>esc</kbd> clears the command. + +Selection based arguments: + +name | expanded to +-|- +`{file}` | the complete path of the current selection +`{parent}` | the complete path of the current selection's parent +`{directory}` | the closest directory, either `{file}` or `{parent}` + +## Verbs using arguments + +Some commands not only use the selection but also takes one or several argument(s). + +For example mkdir is defined as + + invocation = "mkdir {subpath}" + execution = "/bin/mkdir -p {directory}/{subpath}" + +which means that if you type `c/d`, and the file `/a/b/some_file.rs` is selected, then the created directory would be `a/b/c/d`. + +Example: + +![md](../img/20190306-md-c-client.png) + +In this screenshot, we didn't type `mkdir` or its start but `md`. That's because the complete definition of this verb includes this line: + + shortcut = "md" + +!!! Note + The help screen lists the whole set of available verbs, including the ones coming from the configuration. + +## Builtins & external commands, leaving or not + +There are two types of verbs, differing by their *execution* pattern (which will be covered in more details in the [configuration page](configuration.md#verbs)): + +* buitin features, whose execution starts with `:`, apply internal functions, for example `:toggle_perm` to trigger computation and display of unix file permissions +* external commands, whose execution implies calling an external program, for example `rm -rf {file}` + +A command may leave broot (for example to start a program), or not (the tree will be refreshed). + +## Most common Commands + +!!! Note + Remember that you may select a verb by just typing the first letters of its name or shorcut + +### Navigation + +Command | Shortcut | Usage +-|-|- +back| | revert to the previous state (mapped to `esc`) +cd | | leave broot and change directory (mapped to `alt-enter`) +focus | goto | display the selected directory (mapped to `enter`) +help | ? | go to the help screen +open | | open file according to OS settings (mapped to `enter` ) +parent | p | move to the parent directory +print_path | pp | print path and leaves broot +quit | q | quit the application + +### File Manipulation + +Command | Shortcut | Usage +-|-|- +mkdir | md | create a new directory, using a name you provide as argument +mv | | move a file or directory, to a relative path you provide as argument +rm | | remove the selected file or directory + +## Adding verbs + +You may start with the common set of verbs but you'll very quickly want to define how to edit or create files, and probably have a few personal commands. + +That's why should see [how to configure verbs](configuration.md#verbs). + +# Launch Arguments + +**broot** and **br** can be passed as argument the path to display. + +They also accept a few other arguments which you can view with `br --help`. + +Most of them are display toggles, which may be useful when aliasing the function but which are accessible from inside the application anyway. + +Some of them are a little special, though, and are explained below: + +## the `--outcmd` launch argument + +Some external commands can't be executed from a program. + +This is especially the case of `cd`, which isn't a program but a shell function. In order to have any useful effect, it must be called from the parent shell, the one from which broot was launched, and a shell which isn't accessible from broot. + +The trick to enable broot to `cd` your shell when you do `alt-enter` is the following one: + +* **br** is a shell function. It creates a temp file whose path it gives as argument to **broot** using `--outcmd` +* when you do `alt-enter`, **broot** writes `cd your-selected-path` in this file, then quits +* **br** reads the file, deletes it, then evals the command + +Most users have no reason to use `--outcmd` on their own, but it can still be used to write an alternative to **br** or to port it to shells which aren't currently supported. + +## the `--out` launch argument + +If you provide a path to broot with `--out`, then a few commands won't execute anything directly but will instead write the relevant path as a line in the given file. + +This may be used by shell functions or other programs calling broot, in a similar way to `--outcmd`, for example in conjonction with ̀ --cmd`. + +## the `--cmd` launch argument + +This argument lets you pass commands to broot. Those commands are executed exactly like any command you would type yourself in the application, a space meaning broot must wait for the end of execution. + +For example if you launch + + br --cmd cow / + +Then broot is launched in the / directory and there's simply a filter typed for you. + +If you do + + br --cmd "/^vache :p" + +Then broot looks for a file whose name starts with "vache" and focus its parent. + +If you do + + br --cmd "mucca$/ :cd" + +then broot searches for a file whose name ends with "mucca", and `cd` to the closest directory, leaving you on the shell, in your new directory (you may not have the time to notice the broot guy was displayed). + +The `--cmd` argument may be the basis for many of your own shell functions or programs. + +!!! Note + Due to the way a new char cancels an in progress search, you can't pass both a search and a verb in the same command, you have to separate them with a space. That is, if you want to search for `thing` then do `:rm` on the best match (assuming you like to live dangerously), you have to do `br --cmd "thing :rm"` instead of `br --cmd "thing:rm"`. |