diff options
| -rw-r--r-- | Makefile | 4 | ||||
| -rw-r--r-- | README.md | 5 | ||||
| -rw-r--r-- | bb.1 | 26 | ||||
| -rw-r--r-- | bbcmd.1 | 238 |
4 files changed, 261 insertions, 12 deletions
@@ -69,7 +69,7 @@ install: $(NAME) [ ! "$$sysconfdir" ] && sysconfdir=/etc; \ mkdir -pv -m 755 "$$prefix/share/man/man1" "$$prefix/bin" "$$sysconfdir/xdg/bb" \ && cp -v bbstartup.sh bindings.bb "$$sysconfdir/xdg/bb/" \ - && cp -v $(NAME).1 "$$prefix/share/man/man1/" \ + && cp -v bb.1 bbcmd.1 "$$prefix/share/man/man1/" \ && rm -f "$$prefix/bin/$(NAME)" \ && cp -v $(NAME) "$$prefix/bin/" @@ -82,6 +82,6 @@ uninstall: [ ! "$$prefix" ] && prefix="/usr/local"; \ [ ! "$$sysconfdir" ] && sysconfdir=/etc; \ echo "Deleting..."; \ - rm -rvf "$$prefix/bin/$(NAME)" "$$prefix/share/man/man1/$(NAME).1" "$$sysconfdir/xdg/bb"; \ + rm -rvf "$$prefix/bin/$(NAME)" "$$prefix/share/man/man1/bb.1" "$$prefix/share/man/man1/bbcmd.1" "$$sysconfdir/xdg/bb"; \ printf "\033[1mIf you created any config files in ~/.config/bb, you may want to delete them manually.\033[0m" @@ -41,6 +41,9 @@ command with the selected files in `$@`, and `|` to pipe the selected files to a command. Pressing `Ctrl-c` will cause `bb` to exit with a failure status and without printing anything. +More information about usage can also be found by running `man bb` after +installing. + ## bb's Philosophy The core idea behind `bb` is that `bb` is a file **browser**, not a file @@ -77,7 +80,7 @@ up an easy way to repeat some custom workflow). state. To do this, call `bbcmd <your command>` from within `bb`. For example, by default, `j` is bound to `bbcmd move:+1`, which has the effect of moving `bb`'s cursor down one item. More details about the API can be found in [the API -documentation](API.md). +documentation](API.md) or by running `man bbcmd` after installing. ## FAQ @@ -1,6 +1,6 @@ .\" Manpage for bb. .\" Contact bruce@bruce-hill.com to correct errors or typos. -.TH man 8 "22 May 2019" "1.0" "bb manual page" +.TH man 1 "23 Feb 2020" "1.0" "bb manual page" .SH NAME bb \- A bitty browser for command line file management .SH SYNOPSIS @@ -10,8 +10,8 @@ bb \- A bitty browser for command line file management [\fI-0\fR] [\fI-v\fR|\fI--version\fR] [\fI-h\fR|\fI--help\fR] -[\fI+command\fR]* -[[--] \fIdirectory\fR] +[+\fI<command>\fR]* +[[--] \fI<directory>\fR | \fI<file>\fR] .SH DESCRIPTION \fBbb\fR is a tiny TUI console application for browsing and managing files. .SH OPTIONS @@ -22,8 +22,8 @@ Print the current directory on exit. Print the selected files on exit. .B \-0 -If printing the selected files on exit, use NULL-terminated strings instead of -newline-separated. +If printing the selected files on exit, use \fBNULL\fR-terminated strings +instead of newline-separated. .B \-d Print the current directory on exit. @@ -34,12 +34,16 @@ Print the version and exit. .B \--help Print the usage and exit. -.B +command -As soon as \fBbb\fR has launched, run the given command. +.B <command> +As soon as \fBbb\fR has launched, run the given command. See \fBbbcmd\fR(1) for +more details about \fBbb\fR commands. -.B directory +.B <directory> Open \fBbb\fR viewing this directory. +.B <file> +Open \fBbb\fR in the directory containing this file, with the cursor on it. + .SH CONTROLS For full details on all key bindings, press \fB?\fR from inside \fBbb\fR to get a help menu. @@ -69,7 +73,7 @@ Begin browsing in /usr/local/ .TP .B -alias bcd="cd '`bb -d`'" +alias bcd='cd "$(bb -d)"' Create an alias to launch \fBbb\fR and change directory to wherever it's located when you exit (unless you exit with Ctrl-c). @@ -83,5 +87,9 @@ Select some files to add to a zip archive. bb +select: *.txt Launch \fBbb\fR with all the .txt files in the current directory selected. +.SH "SEE ALSO" +.sp +\fBbbcmd\fR(1) + .SH AUTHOR Bruce Hill (bruce@bruce-hill.com) @@ -0,0 +1,238 @@ +.\" Manpage for bbcmd. +.\" Contact bruce@bruce-hill.com to correct errors or typos. +.TH man 1 "23 Feb 2020" "1.0" "bbcmd manual page" + +.de TPx +. TP 4n +.. + +.SH NAME +\fBbbcmd\fR \- Run commands in \fBbb\fR, the command line file browser +.SH SYNOPSIS +.B bbcmd +(\fIcmd\fR[\fI:value\fR])* [\fIcmd\fR: \fIvalue\fR*] + +.SH DESCRIPTION +\fBbbcmd\fR is a script that can be run from within \fBbb\fR (the command line +file browser). \fBbbcmd\fR is used to manipulate \fBbb\fR's behavior and state. +Typically, this is done through scripts that are bound to keypresses, or during +\fBbb\fR's startup scripts. + +.SH TRAILING ARGUMENTS +If a command ends with a colon and there are more arguments after it, the +additional arguments are treated as repeated invocations of that command. +Example: `\fBbbcmd select: one two\fR` is equivalent to `\fBbbcmd +select:one select:two\fR` + +.SH PIPED VALUES +If no arguments are given, commands are read from \fBstdin\fR, separated by +\fBNULL\fR bytes (\fB\\0\fR). Example: `\fBprintf 'select:%s\\0' one two | bbcmd\fR` +is equivalent to `\fBbbcmd select:one select:two\fR`. + +If the last argument given is a command with a trailing colon, arguments for +that command are read from \fBstdin\fR, separated by \fBNULL\fR bytes +(\fB\\0\fR). Example: `\fBprintf '%s\\0' one two | bbcmd select:\fR` is equivalent +to `\fBbbcmd select:one select:two\fR` + +.SH COMMANDS +Each of the following are commands that can be run with \fBbbcmd\fR from within +\fBbb\fR, typically through keyboard-bound scripts: + +.RS +.IP \fBbind\fR:\fIkeys\fR:\fIscript\fR +Bind the given key presses to run the given script. + +.IP \fBcd\fR:\fIpath\fR +Navigate \fBbb\fR to \fIpath\fR. + +.IP \fBcolumns\fR:\fIcolumns\fR +Change which columns are visible, and in what order. The default setting is +\fB*smpn\fR. The available columns are: +. +. +.P +.PD 0 +.RS +. +.TPx +.B * +Whether or not the file is selected. +. +.TPx +.B n +The name of the file +. +.TPx +.B s +The size of the file +. +.TPx +.B p +The permissions of the file +. +.TPx +.B m +The modification time of the file (relative) +. +.TPx +.B M +The modification time of the file (absolute) +. +.TPx +.B c +The creation time of the file (relative) +. +.TPx +.B C +The creation time of the file (absolute) +. +.TPx +.B a +The access time of the file (relative) +. +.TPx +.B A +The access time of the file (absolute) +. +.TPx +.B r +The random index of the file +. +.RE +.PD + +.IP \fBdeselect\fR[:\fIfilename\fR] +Deselect \fIfilename\fR (default: all selected files). + +.IP \fBfg\fR[:\fInum\fR] +Send background process \fInum\fR to the foreground (default: the most recent +process). + +.IP \fBglob\fR:\fIpattern\fR +The glob pattern for which files to show (default: `*`). See: \fBglob\fR(7) for +more details on globbing. + +.IP \fBgoto\fR:\fIfilename\fR +Move the cursor to filename (changing directory if needed). + +.IP \fBhelp\fR +Show the help menu. + +.IP \fBinterleave\fR[:\fI0\fR|\fI1\fR] +Whether or not directories should be interleaved with files in the display +(default: toggle) + +.IP \fBmove\fR:\fInum\fR +Move the cursor a numeric amount. See the \fBNUMBERS\fR section below. + +.IP \fBquit\fR +Quit \fBbb\fR. + +.IP \fBrefresh\fR +Refresh the file listing. + +.IP \fBscroll\fR:\fInum\fR +Scroll the view a numeric amount. See the \fBNUMBERS\fR section below. + +.IP \fBselect\fR[:\fIfilename\fR] +Select \fIfilename\fR (default: all visible files). + +.IP \fBsort\fR:([\fI+\fR|\fI-\fR]\fImethod\fR)+ +Sort files according to \fImethod\fR (\fI+\fR: normal, \fI-\fR: reverse, +default: toggle the current direction). Additional methods (if any) act as +tiebreaker. The default setting is \fB+n\fR. The values for \fImethod\fR must +be one or more of the following single-letter characters: +.P +.PD 0 +.RS +.TPx +.B n +name +.TPx +.B s +size +.TPx +.B m +modification time +.TPx +.B c +creation time +.TPx +.B a +access time +.TPx +.B r +random +.TPx +.B p +permissions +.RE +.PD + +.IP \fBspread\fR:\fInum\fR +Spread the selection state at the cursor. See the \fBNUMBERS\fR +section below. + +.IP \fBtoggle\fR[:\fIfilename\fR] +Toggle the selection status of \fIfilename\fR (default: all visible files). + +.RE + +.SH NUMBERS +In commands which take a number (\fBscroll\fR, \fBmove\fR, and \fBspread\fR), +the number can be one of the following: + +.PD 0 +.RS +.TP 8 +.B N +An absolute number (e.g. \fB5\fR), meaning the \fBN\fRth visible file. +.TP 8 +.B N% +A percentage of screen height (e.g. \fB50%\fR), meaning the visible file +\fBN%\fR of the way down the screen. +.TP 8 +.B N%n +A percentage of the files (e.g. \fB50%n\fR), meaning the visible file \fBN%\fR +of the way down the list. +.TP 8 +.B +/-num +An offset (e.g. \fB+1\fR, \fB-1\fR, \fB+25%\fR, \fB-10%n\fR), which interprets +the following number as relative to the current cursor position. +.RE +.PD + +.SH EXAMPLES +.TP +.B +bbcmd cd:/usr/local/ +Navigate to /usr/local/ + +.TP +.B +bbcmd select:"$BBCURSOR" move:+1 +Select the file under the cursor, then move the cursor down one file. + +.TP +.B +bbcmd select: *.jpg +Select all \fB.jpg\fR files in the current directory. + +.TP +.B +for f in *.jpg; do printf 'select:%s\\0'; done | bbcmd +Select all \fB.jpg\fR files in the current directory, using the "pipe commands +to bbcmd" functionality. + +.TP +.B +find . -name '*.jpg' -print0 | bbcmd select: +Select all \fB.jpg\fR files in the current directory or its subdirectories, +using the "pipe arguments to a command" functionality. + +.SH "SEE ALSO" +.sp +\fBbb\fR(1) + +.SH AUTHOR +Bruce Hill (bruce@bruce-hill.com) |