File: README.md
Broot
Broot is a better way to navigate directories, find files, and launch commands.
Complete Documentation -
Installation Instructions -
Contributing or Getting Help
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 alti and alth shortcuts to toggle those visibilities.
(you can ignore them though, see documentation).
Find a directory, then `cd` to it
type a few letters
Hit altenter 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
- enter on the root line to go up to the parent (staying in broot)
- enter to focus a directory (staying in broot)
- esc to get back to the previous state or clear your search
- โ and โ may be used to move the selection
- altenter to get back to the shell, having
cdto the selected directory - alth to toggle showing hidden files (the ones whose name starts with a dot)
- alti to toggle showing gitignored files
:qif you just want to quit (you can use ctrlq 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 tab 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, 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 enter (or double-click) to open it in your system's default program
- hit altenter to open it in your system's default program and close broot
- hit ctrlโ to preview it (and then a second time to go inside the preview)
- type a verb. For example,
:eopens the file in your preferred editor (which may be a terminal one)
blog: a broot content search workflow
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 ctrlโ and you open another panel (you may open other ones, or navigate between them, with ctrlโ and ctrlโ).
(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 F5 and :move_to_panel to F6.
Preview files
Hit ctrlโ 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, 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 enter.
You can add verbs or configure the existing ones; see documentation.
And you can add shortcuts, for example, a ctrl sequence or a function key
Apply commands on several files
Add files to the 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 alth 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 enter 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
Further Reading
See Broot's web site for instructions regarding installation and usage.
File: resources/syntect/README.md
Broot uses syntect for syntax highlighting in text files.
This (excellent) library needs Sublime Text syntax definitions for all languages (when a language definition isn't found, Broot displays the text monochrome).
Syntect doesn't come with an extensive set of definitions.
The bat project maintains with care an important list of such definitions (most as submodules, some with patches).
It's the best public list I found, so I've included the resulting syntax set here as syntaxes.bin.
You may replace this file with your own, building it with Syntect's syntect::dumps::dump_to_uncompressed_file function.
File: resources/icons/nerdfont/README.md
Nerd Fonts Icons
Requirements
Nerd Fonts installed either through a patched font or available as a fallback font.
Configuration
In broot config file, set
icon_theme: nerdfontLimitations
These icons are limited by availability of symbols in Nerd Fonts, so this feature can only support a subset of filetypes available in vscode theme.
Editing the Icon for a File:
If you want to find an icon for a file: go to https://www.nerdfonts.com/cheat-sheet and search for:
- a icon name like "file", which should return the multiple file icon results. Pick one you like and copy the icon code "ea7b". Copy it into the corresponding mapping prefixed with "0x" in ./data/*.rs. ( "default_file", 0xf15b ), // ๎ฉป
- a icon code like "0xf15b" without the "0x" prefix. This should return the corresponding "๎ฉป" icon.
Tips on editing these files in vi
Open ./icon_name_to_icon_code_point_map.rs
then in the same session, switch to file you want to edit
use C-n and C-y in edit modeThis plugin currently searches for lowercase, make everything so
Remember to run :Tabularize over ')' and ','. The tabular Plugin
:'<,'>!sort
cargo runin debug mode should figure out some problems.
File: website/src/README.md
This directory is the source of the web site which is at https://dystroy.org/broot
File: website/README.md
Broot's website is live at https://dystroy.org/broot
It's built using ddoc
To test it locally, cd to the website directory then
ddoc -- serveTo build it, do
ddoc