browse.1

'\" t
.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "BROWSE" "1" "" "" ""
.hy
.SH NAME
.PP
browse - A simple, unconventional file browser.
.SH SYNOPSIS
.PP
browse [-finv] [-p pattern] [-t title] [filename\&...]
.SH DESCRIPTION
.PP
Browse and search text files, follow changes.
.SS Description
.PP
\f[B]browse\f[R] is a minimalist file browser that focuses on essential
features while providing a user-friendly interface.
It is ideal for developers and system administrators who seek a
lightweight, keyboard-driven alternative to traditional file viewers.
.PP
The browser supports multi-file browsing by accepting a list of files
(or globs expanded by your shell), ensuring that each path is resolved
and validated before browsing.
It also supports input via pipe, treating it as if it were a temporary
file.
Invalid files, such as directories or non-existent files, are safely
skipped, and feedback is provided.
.PP
\f[B]browse\f[R] allows you to temporarily leave your current file list
to explore a new set of files.
Once you finish browsing the new list, \f[B]browse\f[R] automatically
returns you to your previous list.
This feature, known as \[lq]recursive browsing,\[rq] enables deep and
flexible exploration without losing your place in the original file
list.
.SS ✨ Features
.SS 🧭 Navigation
.IP \[bu] 2
Forward and reverse paging
.IP \[bu] 2
Continuous scrolling (forward and reverse)
.IP \[bu] 2
Horizontal scrolling
.IP \[bu] 2
Line jumping
.IP \[bu] 2
Page marking
.SS 🔍 Search & Filter
.IP \[bu] 2
Forward and reverse regex searches
.IP \[bu] 2
Case-sensitive/case-insensitive search toggle
.IP \[bu] 2
Pattern highlighting
.IP \[bu] 2
Search pattern history
.SS 🛠️ Additional Features
.IP \[bu] 2
File completion
.IP \[bu] 2
Shell escape with command completion
.IP \[bu] 2
\f[V]tail -f\f[R] functionality
.IP \[bu] 2
Line numbers
.IP \[bu] 2
Session saving
.IP \[bu] 2
Shell command history
.IP \[bu] 2
Change working directory
.IP \[bu] 2
Built-in help screen
.SS 📖 Usage
.SS Command Line Options
.nf

browse [OPTIONS] [FILE] [FILE...]
\f[R]
.fi
.PP
.TS
tab(@);
lw(20.0n) lx.
T{
Option
T}@T{
Function
T}
_
T{
\f[V]-f\f[R], \f[V]--follow\f[R]
T}@T{
Follow file changes (browsable)
T}
T{
\f[V]-F\f[R], \f[V]--tail\f[R]
T}@T{
Follow file changes (like \f[V]tail -f\f[R])
T}
T{
\f[V]-i\f[R], \f[V]--ignore-case\f[R]
T}@T{
Search ignores case
T}
T{
\f[V]-n\f[R], \f[V]--numbers\f[R]
T}@T{
Start with line numbers turned on
T}
T{
\f[V]-p\f[R], \f[V]--pattern\f[R]
T}@T{
Initial search pattern
T}
T{
\f[V]-t\f[R], \f[V]--title\f[R]
T}@T{
Page title (default is filename, blank for stdin)
T}
T{
\f[V]-v\f[R], \f[V]--version\f[R]
T}@T{
Print browse version number
T}
T{
\f[V]-?\f[R], \f[V]--help\f[R]
T}@T{
Print browse command line options
T}
.TE
.SS Keyboard Shortcuts
.SS Navigation
.PP
.TS
tab(@);
lw(20.0n) lx.
T{
Key
T}@T{
Function
T}
_
T{
\f[V]f\f[R], \f[V]Page Down\f[R], \f[V]Space\f[R]
T}@T{
Page down toward EOF
T}
T{
\f[V]b\f[R], \f[V]Page Up\f[R]
T}@T{
Page up toward SOF
T}
T{
\f[V]Ctrl+F\f[R], \f[V]Ctrl+D\f[R], \f[V]z\f[R]
T}@T{
Scroll half page down toward EOF
T}
T{
\f[V]Ctrl+B\f[R], \f[V]Ctrl+U\f[R], \f[V]Z\f[R]
T}@T{
Scroll half page up toward SOF
T}
T{
\f[V]+\f[R], \f[V]Right\f[R], \f[V]Enter\f[R]
T}@T{
Scroll one line toward EOF
T}
T{
\f[V]-\f[R], \f[V]Left\f[R]
T}@T{
Scroll one line toward SOF
T}
T{
\f[V]d\f[R], \f[V]Down\f[R]
T}@T{
Continuous scroll toward EOF, follow at EOF
T}
T{
\f[V]u\f[R], \f[V]Up\f[R]
T}@T{
Continuous scroll toward SOF, stop at SOF
T}
T{
\f[V]>\f[R], \f[V]Tab\f[R]
T}@T{
Scroll 4 characters right
T}
T{
\f[V]<\f[R], \f[V]Backspace\f[R], \f[V]Del\f[R]
T}@T{
Scroll 4 characters left
T}
T{
\f[V]\[ha]\f[R]
T}@T{
Scroll to column 1
T}
T{
\f[V]$\f[R]
T}@T{
Scroll to end of line
T}
T{
\f[V]j\f[R]
T}@T{
Jump to line number
T}
T{
\f[V]0\f[R], \f[V]Home\f[R]
T}@T{
Jump to start of file, column 1
T}
T{
\f[V]G\f[R]
T}@T{
Jump to end of file
T}
T{
\f[V]m\f[R]
T}@T{
Mark current page with number 1-9
T}
T{
\f[V]1\f[R]-\f[V]9\f[R]
T}@T{
Jump to mark
T}
T{
\f[V]e\f[R], \f[V]End\f[R]
T}@T{
Jump to EOF, follow at EOF
T}
T{
\f[V]t\f[R]
T}@T{
Jump to EOF, tail at EOF
T}
.TE
.SS Search
.PP
.TS
tab(@);
lw(20.0n) lx.
T{
Key
T}@T{
Function
T}
_
T{
\f[V]/\f[R]
T}@T{
Regex search forward (empty pattern repeats or changes direction)
T}
T{
\f[V]?\f[R]
T}@T{
Regex search reverse (empty pattern repeats or changes direction)
T}
T{
\f[V]n\f[R]
T}@T{
Repeat search in current direction
T}
T{
\f[V]N\f[R]
T}@T{
Repeat search in opposite direction
T}
T{
\f[V]i\f[R]
T}@T{
Toggle case-sensitive/insensitive search
T}
T{
\f[V]p\f[R]
T}@T{
Print current search pattern
T}
T{
\f[V]P\f[R]
T}@T{
Clear search pattern
T}
T{
\f[V]&\f[R]
T}@T{
Run \f[V]grep -nP\f[R] on current file for search pattern in a new
session
T}
.TE
.SS Miscellaneous
.PP
.TS
tab(@);
lw(20.0n) lx.
T{
Key
T}@T{
Function
T}
_
T{
\f[V]#\f[R]
T}@T{
Toggle line numbers on/off
T}
T{
\f[V]%\f[R], \f[V]=\f[R], \f[V]Ctrl+G\f[R]
T}@T{
Show file position
T}
T{
\f[V]!\f[R]
T}@T{
Run a bash command (expands \f[V]!\f[R], \f[V]%\f[R], \f[V]&\f[R],
\f[V]\[ti]\f[R])
T}
T{
\f[V]F\f[R]
T}@T{
Run \f[V]fmt -s\f[R] on the current file in a new session
T}
T{
\f[V]B\f[R]
T}@T{
Browse another file (expands \f[V]%\f[R], \f[V]\[ti]\f[R], shell glob)
T}
T{
\f[V]r\f[R]
T}@T{
Re-read the current file from disk
T}
T{
\f[V]a\f[R]
T}@T{
Print filenames in the browse list
T}
T{
\f[V]c\f[R]
T}@T{
Print current working directory
T}
T{
\f[V]C\f[R]
T}@T{
Change working directory
T}
T{
\f[V]q\f[R]
T}@T{
Quit, save session, next file in list
T}
T{
\f[V]Q\f[R]
T}@T{
Quit without saving session, next file in list
T}
T{
\f[V]x\f[R]
T}@T{
Exit list, save session
T}
T{
\f[V]X\f[R]
T}@T{
Exit list, don\[cq]t save session
T}
.TE
.SS Symbol Expansions
.PP
Special symbols expanded in commands:
.PP
.TS
tab(@);
lw(20.0n) lx.
T{
Symbol
T}@T{
Expands To
T}
_
T{
\f[V]!\f[R]
T}@T{
Last bash command
T}
T{
\f[V]%\f[R]
T}@T{
Current file name
T}
T{
\f[V]&\f[R]
T}@T{
Current search pattern
T}
T{
\f[V]\[ti]\f[R]
T}@T{
Home directory
T}
.TE
.SS ⚙️ Configuration
.PP
browse stores configuration and history in \f[V]\[ti]/.browse/\f[R]
.PP
\f[B]Session File:\f[R] \f[V]\[ti]/.browse/browserc\f[R]
.PP
Saves current session state, including:
.IP "1." 3
File name
.IP "2." 3
First line on page
.IP "3." 3
Search pattern
.IP "4." 3
Marks
.IP "5." 3
Page title
.SS ⚙️ Working with Files and Directories
.IP \[bu] 2
\f[B]\f[VB]B\f[B]\f[R] - Open a new file.
You will be prompted to enter a file name or a list of files to open.
You can use wildcards (such as \f[V]*.go\f[R] or \f[V]access_log.*\f[R])
to match multiple files at once.
If you prefix your file name with a tilde (\f[B]\f[VB]\[ti]\f[B]\f[R]),
it will refer to your home directory.
Typing \f[B]\f[VB]%\f[B]\f[R] will use the current file name, and typing
\f[B]\f[VB]-\f[B]\f[R] will bring up the last file you viewed.
You can input multiple file names by separating them with spaces.
If a file name contains spaces, enclose it in quotes.
.IP \[bu] 2
\f[B]\f[VB]a\f[B]\f[R] - Display the list of files you are currently
working with.
When you press \f[B]\f[VB]a\f[B]\f[R], you will see the file you are
currently viewing alongside any other files still in the list.
For instance, if you started with several files (like
\f[V]browse file1 file2 file3\f[R]) and are viewing \f[V]file2\f[R],
pressing \f[B]\f[VB]a\f[B]\f[R] will show \f[V]file2\f[R] and
\f[V]file3\f[R].
This feature is useful when the program is initiated with multiple
filenames or a wildcard (e.g., \f[V]browse *.go\f[R]), as it allows you
to see which file you are currently viewing and which files remain in
the queue.
.IP \[bu] 2
\f[B]\f[VB]r\f[B]\f[R] - Re-read the current file from disk.
Useful when a file has been replaced (e.g.,
\f[V]mv log log.old && app > log\f[R]).
browse detects the replacement silently; press \f[V]r\f[R] at any time
to re-read the new file.
.IP \[bu] 2
\f[B]\f[VB]C\f[B]\f[R] - Change the current working directory.
This command will prompt you to select a directory to switch to.
You can use \f[B]\f[VB]\[ti]\f[B]\f[R] to refer to your home directory,
or \f[B]\f[VB]-\f[B]\f[R] and \f[B]\f[VB]\[ti]-\f[B]\f[R] to return to
the directory you were just in.
If the directory name contains spaces, enclose it in quotes.
If \f[V]CDPATH\f[R] is set, the program will suggest directories from
that path.
\f[B]\f[VB]%\f[B]\f[R] expands to the parent directory of the current
file name.
.IP \[bu] 2
\f[B]\f[VB]q\f[B]\f[R] - Close the file you are currently browsing.
Before closing, the program remembers your last search, any marks, and
your position in the file.
Alternatively, \f[B]\f[VB]Q\f[B]\f[R] also closes the file but does not
save your session.
.IP \[bu] 2
\f[B]\f[VB]x\f[B]\f[R] - If you have files from a previous list,
\f[B]\f[VB]x\f[B]\f[R] stops processing the current list and resumes
processing the next file in the previous list.
If there are no remaining files, the program will close.
The command \f[B]\f[VB]X\f[B]\f[R] functions the same way but does not
save your session.
.SS 🕑 Histories
.PP
\f[B]Browse\f[R] maintains a persistent history to streamline your
workflow and make repetitive tasks faster and easier.
If you\[cq]re familiar with Linux tools like Bash, these history
features will feel instantly familiar:
.IP \[bu] 2
\f[B]Bash Command History:\f[R] Every time you execute a shell command
in Browse (using the \f[B]\f[VB]!\f[B]\f[R] key), it is remembered.
You can quickly recall, edit, and rerun previous commands, just like
using the up-arrow key in Bash.
.IP \[bu] 2
\f[B]Directory History:\f[R] Whenever you change your working directory
in Browse, it is recorded.
You can easily cycle through or return to recently used directories,
which helps you navigate large projects or complex file structures more
efficiently.
.IP \[bu] 2
\f[B]File History:\f[R] Files that you browse are saved (as full
pathnames) for easy access in both current and future sessions.
.IP \[bu] 2
\f[B]Search Pattern History:\f[R] Search patterns entered for regex or
text searches are saved.
This feature allows you to easily repeat searches or revisit common
queries without having to retype them.
.PP
\f[B]History Files:\f[R]
.IP \[bu] 2
\f[V]\[ti]/.browse/browse_dirs\f[R] - Directory history
.IP \[bu] 2
\f[V]\[ti]/.browse/browse_files\f[R] - File browsing history
.IP \[bu] 2
\f[V]\[ti]/.browse/browse_search\f[R] - Search pattern history
.IP \[bu] 2
\f[V]\[ti]/.browse/browse_shell\f[R] - Shell command history
.SS ⚠️ Limitations
.IP \[bu] 2
Xterm specific
.IP \[bu] 2
Logical lines are truncated to screen width
.IP \[bu] 2
May be US-centric
.IP \[bu] 2
Can be confused by non-printable characters
.IP \[bu] 2
Tabs are converted to spaces
.IP \[bu] 2
go-prompt handling changes the terminal title
.IP \[bu] 2
Line lengths internally capped at 4K
.SS 📄 License
.PP
MIT License - see LICENSE file for details
.SH AUTHORS
https://github.com/jjbailey/browse