Don't assume CWD is a valid path.

[rover.git] / rover.1

.TH ROVER 1 rover\-0.4.2
.SH NAME
rover \- file browser for the terminal
.SH SYNOPSIS
.B rover
[\fB\-d\fR|\fB\-\-save\-cwd\fR \fIFILE\fR]
[\fB\-m\fR|\fB\-\-save\-marks\fR \fIFILE\fR]
[\fIDIR\fR [\fIDIR\fR [\fIDIR\fR [...]]]]
.br
.B rover
\fB\-h\fR|\fB\-\-help\fR
.br
.B rover
\fB\-v\fR|\fB\-\-version\fR
.SH DESCRIPTION
Browse current working directory or the ones specified.
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-save\-cwd\fR
write last visited path to \fIFILE\fR before exiting
.TP
\fB\-m\fR, \fB\-\-save\-marks\fR
append path of marked entries to \fIFILE\fR before exiting;
if \fIFILE\fR doesn't exist, it'll be created
.TP
\fB\-h\fR, \fB\-\-help\fR
print help message and exit
.TP
\fB\-v\fR, \fB\-\-version\fR
print program version and exit
.SH CONCEPTS
.SS TABS
.PP
Rover is operated via a tabbed interface. There are always ten tabs in total,
numbered from 0 to 9. At any given moment, one (and only one) tab is visible on
the screen. The number of the tab currently visible is shown on the top right
corner of the screen. To view a different tab, one just needs to press its
corresponding number. Each tab has a \fBcurrent working directory\fR (\fBCWD\fR)
associated to it, also shown on the top of the screen. The \fBCWD\fR of the
visible tab is changed as the user navigates through the file system.
.PP
It's also possible to set the \fBCWD\fR of tabs at Rover start-up by passing the
desired paths as command-line arguments. The tab number 0 always starts at
\fB$HOME\fR. If more than nine directories are specified, only the first nine
are used for tabs 1\-9 and the rest are ignored. Tabs for which an invalid path
was assigned will also start at \fB$HOME\fR. Remaining tabs not specified on
the command line start at the current working directory of the parent process.
.SS ENTRIES
.PP
An \fBentry\fR is anything that may be found inside a directory in some file
system. It may be a file, a directory, a link, a socket, a FIFO, etc. In its
most basic usage, Rover will gather a list of entries inside the \fBCWD\fR
and present it on the screen.
.PP
There is always one (and only one) highlighted entry visible. This is both the
\fBcursor\fR location and the current \fBselection\fR. The highlighting moves as
the user navigates the entry list with cursor commands. Simple operations, like
entering a subdirectory or renaming a file, are done by first selecting the
relevant entry and then issuing the appropriate command (see the \fBCOMMANDS\fR
section). For commands that operate on more than one entry at once (batch
commands), selection is not sufficient, since it's not possible to select more
than one entry. Batch commands are performed on marked entries.
.SS MARKS
.PP
For some file operations, it is convenient to first \fBmark\fR all entries that
are to be processed, so that the appropriate command only needs to be issued
once. For such purpose, Rover allows an arbitrary number of entries to be
marked, with the limitation that they must be all in the same directory.
.PP
Unlike simple selection, the effect of marks is not constrained by visibility.
This is so one can mark a number of entries in some directory, navigate to another
directory, and then finally issue a copy or move command. Moreover, marks are
shared over all tabs. This allows one to mark some entries in one tab that is
pointed to the "source" directory of the operation and then issue the command on
another tab that is pointed to the "destination" directory.
.SH COMMANDS
.TP
.B q
Quit rover.
.TP
.B j/k
Move cursor down/up.
.TP
.B J/K
Move cursor down/up 10 lines.
.TP
.B g/G
Move cursor to top/bottom of listing.
.TP
.B l
Enter selected directory.
.TP
.B h
Go to parent directory.
.TP
.B H
Go to \fB$HOME\fR directory.
.TP
.B t
Go to the target of the selected link.
.TP
.B y
Copy location to clipboard.
.TP
.B p
Go to location in clipboard.
.TP
.B r
Refresh directory listing.
.TP
.B <RETURN>
Open \fB$SHELL\fR on the current directory.
.TP
.B <SPACE>
Open \fB$PAGER\fR with the selected file.
.TP
.B e
Open \fB$EDITOR\fR with the selected file.
.TP
.B o
Open \fB$OPEN\fR with the selected file.
.TP
.B /
Start incremental search.
.TP
.B f/d/s
Toggle file/directory/hidden listing.
.TP
.B n/N
Create new file/directory.
.TP
.B R
Rename selected file or directory.
.TP
.B E
Toggle execute permission of the selected file.
.TP
.B D
Delete selected file or (empty) directory.
.TP
.B m
Toggle mark on the selected entry.
.TP
.B M
Toggle mark on all visible entries.
.TP
.B a
Mark all visible entries.
.TP
.B X/C/V
Delete/copy/move all marked entries.
.TP
.B 0-9
Change tab.
.SH LINE EDITING
.PP
Some commands will prompt for an input string. For example, in order to rename a
file, the user must supply the new name. This string will appear at the bottom
of the screen and must be edited interactively using the keyboard. Printable
keys will insert characters at the cursor position. The following shortcuts are
available for line editing:
.TP
.B <TAB>
Finish editing and \fBcancel\fR command.
.TP
.B <RETURN>
Finish editing and \fBconfirm\fR command.
.TP
.B <LEFT>/<RIGHT>
Move insertion cursor left/right.
.TP
.B <UP>/<DOWN>
Move insertion cursor to beginning/end of string.
.TP
.B <BACKSPACE>
Remove one character before cursor.
.TP
.B <DELETE>
Remove one character after cursor.
.TP
.B <CONTROL>+u
Clear line (remove all characters).
.SH ENVIRONMENT VARIABLES
.TP
.B HOME
Full path of the home directory.
.TP
.B PATH
Colon\-separated path list for program directories.
.TP
.B SHELL
Name of shell program (e.g. \fI/bin/sh\fP).
.TP
.B PAGER
Name of pager program (e.g. \fIless\fP).
.TP
.B EDITOR
Name of editor program (e.g. \fIvim\fP or \fIemacs\fP).
.TP
.B CLIP
Path of clipboard file (e.g. \fI/tmp/clipboard\fP).
The user must have read and write permissions on this path.
If this variable is not defined, Rover will use an internal, in-memory, clipboard.
.TP
.B RVSEL
Rover writes the name of the selected entry to this variable before running a
subprocess. This allows one to use the selection as part of an arbitrary command
by first invoking a shell from Rover (see the \fBCOMMANDS\fR section) and then
typing something like \fBgrep abc "$RVSEL"\fR.
.TP
.B OPEN
This variable can be set to a command accepting a single argument: a filename.
The command is supposed to open the given file with an appropriate program.
.TP
.B ROVER_SHELL, ROVER_PAGER, ROVER_EDITOR, ROVER_OPEN
If any of these variables are set, they override \fBSHELL\fR, \fBPAGER\fR,
\fBEDITOR\fR and \fBOPEN\fR, respectivelly.
.SH CONFIGURATION
.PP
If you want to change Rover key bindings or colors, you can edit the
\fIconfig.h\fP file in the source distribution and recompile the program. Rover
will not use or create any external file during its execution, except when asked
to do so by user commands or command-line options.
.SH NOTES
.PP
\fBImportant\fR: Currently, Rover never asks for confirmation before overwriting
existing files while copying/moving marked entries. Please be careful to not
accidentally lose your data.
.SH LINKS
Rover homepage: <http://lecram.github.io/p/rover/>.
.SH SEE ALSO
\fBnoice(1)\fR, \fBmc(1)\fR, \fBvifm(1)\fR, \fBranger(1)\fR