summaryrefslogtreecommitdiffstats
path: root/website/docs/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'website/docs/documentation')
-rw-r--r--website/docs/documentation/configuration.md165
-rw-r--r--website/docs/documentation/installation.md50
-rw-r--r--website/docs/documentation/tricks.md39
-rw-r--r--website/docs/documentation/usage.md254
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"`.