1 # bb - An itty bitty browser for command line file management
   2 
   3 `bb` (bitty browser) is a console file browser with a text user interface that is:
   4 
   5 - Extremely lightweight (under 2k lines of code)
   6 - Highly interoperable with unix pipelines
   7 - Highly customizable and hackable
   8 - Free of any build dependencies other than the C standard library (no ncurses)
   9 - A good proof-of-concept for making a TUI from scratch
  10 
  11 ![BB Preview Video](bb.gif)
  12 
  13 
  14 ## Building
  15 
  16 `bb` has no build dependencies besides `make` and a C compiler, just:
  17 
  18 ```shell
  19 make
  20 sudo make install
  21 ```
  22 
  23 To run `bb`, it's expected that you have some basic unix tools: `cat`, `cp`,
  24 `echo`, `find`, `kill`, `less`, `ln`, `mkdir`, `more`, `mv`, `printf`, `read`,
  25 `rm`, `sed`, `sh`, `tput`, `tr`.
  26 
  27 
  28 ## Usage
  29 
  30 Run `bb` to launch the file browser. `bb` also has the flags:
  31 
  32 - `-d`: when `bb` exits successfully, print the directory `bb` was browsing
  33   (see the section on "Changing Directories with bb" in the FAQ below).
  34 - `-s`: when `bb` exits successfully, print the files that were selected.
  35 - `-0`: use NULL-terminated strings instead of newline-separated strings with
  36   the `-s` flag.
  37 - `-h`: print usage
  38 - `-v`: print version
  39 
  40 Within `bb`, press `?` for a full list of available key bindings. In short:
  41 `h`/`j`/`k`/`l` (or arrow keys) for navigation, `q` to quit, `Enter` to open a
  42 file, `<space>` to toggle selection, `d` to delete, `C` to copy, `Ctrl-v` to
  43 move, `r` to rename, `Ctrl-n` to create a new file or directory, `:` to run a
  44 command with the selected files in `$@`, and `|` to pipe the selected files to
  45 a command.  Pressing `Ctrl-c` will cause `bb` to exit with a failure status and
  46 without printing anything.
  47 
  48 More information about usage can also be found by running `man bb` after
  49 installing.
  50 
  51 
  52 ## bb's Philosophy
  53 
  54 The core idea behind `bb` is that `bb` is a file **browser**, not a file
  55 **manager**, which means `bb` uses shell scripts to perform all modifications
  56 to the filesystem (passing selected files as arguments), rather than
  57 reinventing the wheel by hard-coding operations like `rm`, `mv`, `cp`, `touch`,
  58 and so on.  Shell scripts can be bound to keypresses in
  59 `~/.config/bb/bbkeys`. For example, `D` is bound to a script that prints a
  60 confirmation message, then runs `rm -rf "$@" && bbcmd deselect refresh`,
  61 which means selecting `file1` and `file2`, then pressing `D` will cause `bb` to
  62 run the shell command `rm -rf file1 file2` and then tell `bb` to deselect all
  63 (now deleted) files and refresh.
  64 
  65 
  66 ## Customizing bb
  67 
  68 When `bb` launches, it first updates `bb`'s `$PATH` environment variable to
  69 include, in order, `~/.config/bb/` and `/etc/bb/`. Then, `bb` will run the
  70 command `bbstartup` (the default implementation is found at
  71 [scripts/bbstartup](scripts/bbstartup), along with other default `bb` commands).
  72 `bbstartup` will call `bbkeys` and may also set up configuration options like
  73 which columns to display and what sort order to use. All of these behaviors can
  74 be customized by creating custom local versions of these files in `~/.config/bb/`.
  75 The default versions can be found in `/etc/bb/`.
  76 
  77 You can also create temporary bindings at runtime by hitting `Ctrl-b`, pressing
  78 the key you want to bind, and then entering in a script to run (in case you
  79 want to set up an easy way to repeat some custom workflow).
  80 
  81 
  82 ### API
  83 
  84 `bb` also exposes an API that allows shell scripts to modify `bb`'s internal
  85 state. To do this, call `bbcmd <your command>` from within `bb`. For example, by
  86 default, `j` is bound to `bbcmd move:+1`, which has the effect of moving `bb`'s
  87 cursor down one item. More details about the API can be found in [the API
  88 documentation](API.md) or by running `man bbcmd` after installing.
  89 
  90 ## FAQ
  91 
  92 ### Using bb to Change Directory
  93 
  94 Applications cannot change the shell's working directory on their own, but you
  95 can define a shell function that uses the shell's builtin `cd` function on the
  96 output of `bb -d` (print directory on exit). For bash or sh, you can put the
  97 following function in your `~/.bashrc`:
  98 
  99 ```bash
 100 function bcd() { cd "$(bb -d "$@")"; }
 101 ```
 102 
 103 Zsh is slightly different and requires the following in your `~/.zshrc`:
 104 
 105 ```zsh
 106 bcd() { cd "$(bb -d "$@" <$TTY)"; }
 107 ```
 108 
 109 For [fish](https://fishshell.com/) (v3.0.0+), you can put this in your
 110 `~/.config/fish/functions/`:
 111 
 112 ```fish
 113 function bcd; cd (bb -d $argv); end
 114 ```
 115 
 116 In both versions, the directory will not change if `bb` exits with failure
 117 (e.g. by pressing `Ctrl-c`).
 118 
 119 ### Launching bb with a Keyboard Shortcut
 120 
 121 Using a keyboard shortcut to launch `bb` from the shell is something that is
 122 handled by your shell. Here are some examples for binding `Ctrl-b` to launch
 123 `bb` and change directory to `bb`'s directory (using the `bcd` function defined
 124 above). For sh and bash, put this in your `~/.profile`:
 125 
 126 ```bash
 127 function bcd() { cd "$(bb -d "$@")"; }
 128 bind '"\C-b":"bcd\n"'
 129 ```
 130 
 131 For zsh, instead put this in your `~/.zshrc`:
 132 
 133 ```zsh
 134 bcd() { # Change directory with bb
 135   cd "$(bb -d "$@" <$TTY)"
 136   precmd >/dev/null 2>/dev/null # If precmd sets your $PS1, you may need to re-run it
 137   zle reset-prompt
 138 }
 139 zle -N bcd
 140 bindkey '^B' bcd
 141 ```
 142 
 143 For fish, put this in your `~/.config/fish/functions/fish_user_key_bindings.fish`:
 144 
 145 ```fish
 146 function bcd; cd (bb -d $argv <$TTY); end
 147 bind \cB 'bcd; commandline -f repaint'
 148 ```
 149 
 150 ## License
 151 
 152 `bb` is provided under the MIT license with the [Commons Clause](https://commonsclause.com/)
 153 (you can't sell this software without the developer's permission, but you're
 154 otherwise free to use, modify, and redistribute it free of charge).
 155 See [LICENSE](LICENSE) for details.