Skip to content
Get packs

Guide · Open source

How to use broot: navigate, search and manage files

Updated · written with AI from the project's own documentation and checked against our catalogue data

Broot is a command-line program that shows a directory as a tree you can navigate, search and act on without leaving the view. This guide explains the core workflow for a terminal user who wants a more usable alternative to ls or the tree command. By the end you will know how to find a directory and cd into it, search by name or content, manage files, and check sizes and git status.

brootCanop/broot · ★ 13.1k · MIT

Quick start

  1. 1Clone the repository. The README's install command is git clone https://github.com/Canop/broot. Follow the project's installation instructions on the website for building and running it.
  2. 2Start broot in a directory. Run br -s to see an overview of the current directory with gitignored files hidden.
  3. 3Find the directory you want. Type a few letters to filter the tree.
  4. 4Return to the shell in that directory. Press Alt+Enter on the selected directory to cd there.
  5. 5Search file contents. Start a pattern with c/ to search inside files.
  6. 6Check git status. Type :gf to see file statuses, branch and ahead or behind counts.

Get an overview of a directory with broot

Start broot with br -s to see an overview of a directory. Broot hides files listed in .gitignore by default, which keeps large directories readable where the tree command would produce pages of output.

Hidden files and gitignored files can be shown when you need them. Alt+h toggles hidden files (names starting with a dot), and Alt+i toggles gitignored files.

  • Alt+h: toggle showing hidden files
  • Alt+i: toggle showing gitignored files
br -s

Find a directory and cd to it from the shell

Type a few letters to narrow the tree to matching directories. When the one you want is selected, press Alt+Enter to return to the shell with the working directory changed to the selected directory. This lets you reach a folder with few keystrokes even if you do not remember its exact location.

Inside broot, Enter on the root line goes up to the parent, Enter on a directory focuses it, and Esc goes back to the previous state or clears the search.

  • Type letters: filter the tree
  • Enter on the root line: go to the parent directory
  • Enter on a directory: focus it
  • Esc: go back or clear the search
  • Up and down arrows: move the selection
  • Alt+Enter: return to the shell and cd to the selected directory
  • :q: quit (Ctrl+q also works)

Search by file name, regex or content

Broot tries to select the most relevant match. Use Tab or the arrow keys to move between matches. To use a regular expression, put a / before the pattern. To search file contents, start the pattern with c/.

You can combine patterns with logical operators. The source gives these examples: !/json$/&c/test searches for test in all files except JSON ones, and carg|c/carg searches for carg in file names and file contents.

  • Regular expression: prefix the pattern with /
  • File content search: prefix the pattern with c/
  • Exclude matches: use ! with a pattern
  • Combine patterns: use & for AND and | for OR
!/json$/&c/test

Open, edit and manage files without leaving broot

When a file is selected, Enter opens it in your system's default program, and Alt+Enter opens it and closes broot. Ctrl+Right previews the file. Typing :e opens the file in your preferred editor.

Move, copy, rm and mkdir are built in, and you can add your own verbs and shortcuts. For operations on several files, add them to the staging area and run a command on all of them. Ctrl+Right opens a second panel, and :copy_to_panel and :move_to_panel can be bound to F5 and F6 for a Norton Commander style workflow.

  • Enter: open the file in the default program
  • Alt+Enter: open the file and close broot
  • :e: edit the file in your preferred editor
  • Ctrl+Right: preview the file
  • Staging area: run one command on several files

Show sizes, dates, permissions and git status

Run br -sdp to show sizes, dates and permissions, a replacement for ls. Use --sort-by-size or --sort-by-date to sort at startup, or toggle sorting from inside broot. The --whale-spotting option (or -w) gives a mode for finding which files and folders take the most space. Sizes, dates and file counts are computed in the background.

Use :fs to see the usage of all filesystems. Use :gf to show file git statuses, the current branch, and how many commits the branch is ahead or behind its upstream. Use :gs to show only the files that git status would list.

  • N: untracked
  • A: staged addition
  • S: staged modification
  • M: modified in the working tree
  • R: staged rename
  • C: conflict
  • I: ignored
  • ?: other change, for example a file replaced by a symlink
br -sdp

What people use it for

  • Jump between project folders in a terminal and cd into one with a few keystrokes.
  • Get a readable overview of a large directory without the output flood of the tree command.
  • Find which files or folders take the most space with whale-spotting mode or :fs.
  • Move, copy or chmod files while keeping the view of the hierarchy.
  • Review git file statuses and edit, diff or revert selected files.

Frequently asked questions

Is broot free to use?

Yes. The project is licensed under the MIT licence, as shown in the repository. Check the LICENSE file in the repository for the full terms.

What do I need to install broot?

The source does not list any prerequisites. The README gives a git clone command for the repository, and the project website has installation instructions.

Does broot work on Windows or with a mouse?

The source says broot runs in a terminal and does not describe Windows support, so check the installation instructions. It does support double-clicking to open a file, and the source notes Kitty graphics protocol support for images in compatible terminals such as Kitty and WezTerm.

How is broot different from the tree command?

The README says the tree command produces too much output on large directories, while broot hides gitignored files by default and lets you navigate and search interactively. It also lets you move, copy, delete or open files from the view.

What are good alternatives to broot?

The project lists tree, ranger, nnn and lf as comparable projects. Choose tree for plain output, and one of the file managers if you want a different interactive interface.

Why does broot hide some of my files?

Broot hides files listed in .gitignore by default. Press Alt+i to show gitignored files and Alt+h to show hidden files whose names start with a dot.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Broot suits developers who work in a terminal and often move between project folders, or who have large directories that make tree output unreadable. It is less suitable if you prefer a graphical file manager, or if you need plain text output for scripts because its interface is interactive.

Install options & downloads