jsh-man.1

.\" @BEGIN_COMMENT Manpage for jsh: Makefile processes this file to include the version number (@VERSION)
.\"      and date (@DATE) and writes it to ./jsh.1 @END_COMMENT
.\"
.TH JSH 1 "@DATE" "jsh @VERSION" "jsh man page"
.SH NAME
jsh \- A basic UNIX shell implementation in C
.SH SYNOPSIS
\fBjsh\fP [options]
.SH DESCRIPTION
\fBjsh\fP is a UNIX command interpreter (shell) that executes commands read from the standard input or from a file. \fBjsh\fP implements a subset of the \fBsh\fP language grammar and is intended to be POSIX-conformant.

\fBjsh\fP is written 'just for fun' and is not intented to be a full competitor to advanced UNIX shells such as \fBbash\fP and \fBzsh\fP. \fBjsh\fP is free software and you are welcome to collaborate on the github page (https://github.com/jovanbulck/jsh) or to redistribute \fBjsh\fP under the conditions of the GNU General Public License.
.SH OPTIONS
\fBjsh\fP supports any combination of the following options:
.TP
\fB\-h, \--help\fP
display an informative help message and exit
.TP
\fB\-d, \--debug\fP
turn printing of debug messages on
.TP
\fB\-n, \--nodebug\fP
turn printing of debug messages off
.TP
\fB\-c, \--color\fP
turn coloring of jsh output messages on
.TP
\fB\-o, \--nocolor\fP
turn coloring of jsh output messages off
.TP
\fB\-d, \--norc\fP
disable autoloading of the ~/.jshrc file
.TP
\fB\-l, \--license\fP
display licence information and exit
.TP
\fB\-v, \--version\fP
display version information and exit
.SH CONFIG FILES
.TP
\fI~/.jshrc\fP
file containing commands to be executed at login (note using the \fBsource\fP builtin, one can include any other file to be processed at startup)
.TP
\fI~/.jsh_login\fP
file containing a text message verbatim printed at login of an interactive session
.TP
\fI~/.jsh_logout\fP
file containing commands to be executed at logout of an interactive session
.TP
\fI~/.jsh_history\fP
file containing the command history auto loaded and saved at login/logout
.SH PROMPT CUSTOMIZING
You can define a custom \fBjsh\fP prompt using the \fBprompt\fP builtin command: \fBprompt\fP "prompt_string" [max_cwd_length]. The first argument defines the new prompt string. The second optional argument defines the maximum length for the current working directory, included with '%d'.  One can include the following prompt expansion options preceded by a '%' char in the prompt string:
.TP
\fB%u\fP
includes the current username
.TP
\fB%U\fP
includes the current username, colored red and bold iff \fBsudo\fP access is activated
.TP
\fB%h\fP
includes the current hostname
.TP
\fB%s\fP
includes the return value of the last executed shell command
.TP
\fB%S\fP
includes the return value of the last executed shell command, colored red and bold iff non-zero
.TP
\fB%d\fP
includes the current working directory. When this directory path is longer then the value specified by the optional \fBmax_cwd_length\fP second argument (default is 25), the directory path is 'smart' truncated to include the maximum number of individual trailing directories of the path. If the path contains the current user's home directory, it is replaced with a '~' char.
.TP
\fB%g\fP
includes the \fBgit\fP branch name iff the current working directory is a \fBgit\fP repository
.TP
\fB%c\fP
includes a bold and red '*' char iff the current working directory is a \fBgit\fP repository and \fBgit\fP indicates files have changed since the last commit
.TP
\fB%$\fP
includes a '$' char or a '#' char iff \fBsudo\fP access is activated (usefull for the prompt ending)
.TP
\fB%%\fP
includes the verbatim '%' character
.TP
\fB%B\fP
turns on bold/bright text coloring
.TP
\fB%n\fP
restores normal coloring: turns off bold/bright text coloring
.TP
\fB%f{color_name}\fP
Enables the specified foreground non-bold text color. Recognized colors are \fB{black, red, green, yellow, blue, magenta, cyan, white}\fP. The special colors \fB{reset, resetall}\fP can be used to respectively reset the foreground color to the default or reset all color properties to default.
.TP
\fB%F{color_name}\fP
Enables the specified foreground bold/bright text color. Recognized colors are the same as with \fB%f\fP above. The special colors \fB{reset, resetall}\fP can be used to respectively disable bold style and reset the foreground color to the default or reset all color properties to default.
.TP
\fB%b{color_name}\fP
Enables the specified background text color. Recognized colors are the same as with \fB%f\fP above. The special colors \fB{reset, resetall}\fP can be used to respectively reset the background color to the default or reset all color properties to default.
.SH THE JSH WIKI
\fBjsh\fP has a wiki (https://github.com/jovanbulck/jsh/wiki) where you can find up-to-date information and installation instructions for various platforms.
.SH BUGS REPORTS
If you find a bug or vulnerability in \fBjsh\fP, you should report it on the github page (https://github.com/jovanbulck/jsh/issues). Please include the output of \fBjsh --version\fP in all bug reports.
.SH KNOWN BUGS
\fBjsh\fP only supports a small subset of the \fBsh\fP language grammar and its interpretation can sometimes be ambiguous. You're welcome to propose better interpretations on the github page, linked above.

Single quotes (') and backticks (`) are not (yet) interpreted by the \fBjsh\fP shell.

Environment variables are not yet implemented. This will be added in future releases.

Job control is not yet implemented; pressing ^Z will suspend the \fBjsh\fP shell. Background jobs will be implemented in future releases.
.SH DISCLAIMER
\fBjsh\fP is not a master thesis.

\fBjsh\fP can be time-consuming and school-distracting. 

Any resemblance of \fBjsh\fP to actual persons is purely coincidental.
.SH AUTHOR
\fBjsh\fP was orginally written by Jo Van Bulck <jo.vanbulck@student.kuleuven.be>. For additional contributors, use \fBgit shortlog -sn\fP on the jsh.git repository.
.SH LICENSE
\fBjsh\fP is free software, licensed under the GNU General Public License (https://gnu.org/licenses/gpl.html). Try \fBjsh --license\fP for more information.
.SH SEE ALSO
\fIsh(1)\fR, \fIbash(1)\fR, \fIreadline(1)\fR.