source | all docs for version 0.7.0 | all versions | oilshell.org
Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.
This doc describes every aspect of Oil and OSH briefly, and is indexed by keywords.
The help builtin prints portions of it.
You can also navigate this doc with the help index.
This section describes how to use the Oil binary.
bin/osh UsageUsage: osh [OPTION]... SCRIPT [ARG]...
osh [OPTION]... -c COMMAND [ARG]...
The command line accepted by bin/osh is compatible with /bin/sh and bash.
osh -c 'echo hi'
osh myscript.sh
echo 'echo hi' | osh
It also has a few enhancements:
osh -n -c 'hello' # pretty-print the AST
osh --ast-format text -n -c 'hello' # print it full
osh accepts POSIX sh flags, with these additions:
-n parse the program but don't execute it. Print the AST. --ast-format what format the AST should be in
bin/oil UsageUsage: oil [OPTION]... SCRIPT [ARG]...
oil [OPTION]... -c COMMAND [ARG]...
bin/oil is the same as bin/osh with a the oil:all option group set. So
bin/oil also accepts shell flags.
oil -c 'echo hi'
oil myscript.oil
echo 'echo hi' | oil
Usage: oil.ovm MAIN_NAME [ARG]...
MAIN_NAME [ARG]...
oil.ovm behaves like busybox. If it's invoked through a symlink, e.g. 'osh', then it behaves like that binary. Otherwise the binary name can be passed as the first argument, e.g.:
oil.ovm osh -c 'echo hi'
If the --rcfile flag is specified, that file will be executed on startup. Otherwise:
bin/osh runs ~/.config/oil/oshrcbin/oil runs ~/.config/oil/oilrcPass --rcfile /dev/null to disable this behavior.
History is read?
A comment starts with # and goes until the end of the line.
echo hi # print a greeting
A backslash \ at the end of a line continues the line without executing it:
ls /usr/bin \
/usr/lib \
~/src # A single command split over three lines
The %%% prefix Starts a Single Command Over Multiple Lines (?)
This special lexer mode has several use cases:
Long command lines without trailing \
%%% chromium-browser
--no-proxy-server
# comments allowed
--incognito
Long pipelines or and-or chains without trailing \
%%% find .
# exclude tests
| grep -v '_test.py'
| xargs wc -l
| sort -n
%%% ls /
&& ls /bin
&& ls /lib
|| error "oops"
TODO
Commands are composed of words. The first word may by the name of a shell builtin, an Oil proc / shell "function", an external command, or an alias:
echo hi # a shell builtin doesn't start a process
ls /usr/bin ~/src # starts a new process
myproc "hello $name"
myshellfunc "hello $name"
myalias -l
Redirects are also allowed in any part of the command:
echo 'to stderr' >&2
echo >&2 'to stderr'
echo 'to file' > out.txt
echo > out.txt 'to file'
Run two commands in sequence like this:
echo one; echo two
or this:
echo one
echo two
Match a string against a series of glob patterns. Execute code in the section below the matching pattern.
path='foo.py'
case "$path" in
*.py)
echo 'python'
;;
*.sh)
echo 'shell'
;;
esac
Test if a command exited with status zero (true). If so, execute the corresponding block of code.
Shell:
if test -d foo; then
echo 'foo is a directory'
elif test -f foo; then
echo 'foo is a file'
else
echo 'neither'
fi
Oil:
if test -d foo {
echo 'foo is a directory'
} elif test -f foo {
echo 'foo is a file'
} else {
echo 'neither'
}
Do nothing and return status 0.
if true; then
echo hello
fi
Do nothing and return status 1.
if false; then
echo 'not reached'
else
echo hello
fi
Three variants of redirecting stdout:
echo foo > out.txt # write to a file
echo foo >> out.txt # append to a file
echo foo >| out.txt # clobber the file even if set -o noclobber
Redirect stdin:
cat < in.txt
Redirect to a file descriptor:
echo 'to stderr' >&2
cat <<EOF
here doc with $double ${quoted} substitution
EOF
myfunc() {
cat <<-EOF
here doc with one tab leading tab stripped
EOF
}
cat <<< 'here string'
time [-p] pipeline
Measures the time taken by a command / pipeline. It uses the getrusage()
function from libc.
Note that time is a KEYWORD, not a builtin!
${x@P} evaluates x as a prompt string, e.g. the string that would be printed if PS1=$x.
These builtins take input and output. They're often used with redirects.
Register completion policies for different commands.
Generate completion candidates inside a user-defined completion function.
It can also be used in scripts, i.e. outside a completion function.
Change completion options inside a user-defined completion function.
Adjust COMP_ARGV according to specified delimiters, and optionally set variables cur, prev, words (an array), and cword. May also set 'split'.
This is an OSH extension that makes it easier to run the bash-completion project.
TODO
Bash has this, but OSH won't implement it.
help index # list all help topics
help index GROUP... # list help topics in the given groups
help TOPIC # show help on a given topic
help osh-usage # same as osh --help
help oil-usage # same as oil --help
View on the web: http://www.oilshell.org/$VERSION/doc/osh-quick-ref.html
For the 'set' builtin.
For the 'shopt' builtin.
$HOME is used for:
Note: The shell doesn't set $HOME. According to POSIX, the program that invokes the login shell sets it based on /etc/passwd.
A colon-separated string that's used to find executables to run.
Used for word splitting. And the builtin split() function.
An array of words, split by : and = for compatibility with bash. New completion scripts should use COMP_ARGV instead.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
User-defined completion functions should Fill this array with candidates. It is cleared on every completion request.
An array of partial command arguments to complete. Preferred over COMP_WORDS. The compadjust builtin uses this variable.
(An OSH extension to bash.)
First line of a prompt.
Second line of a prompt.
For the 'select' builtin (unimplemented).
For 'set -o xtrace'. The leading character is special.
Useful for logging callbacks. NOTE: bash has this with the obscure printf '%(...)' syntax.