Why Sponsor Oils? | source | all docs for version 0.23.0 | all versions | oilshell.org
There are many ways to use Oils!
bin/osh
, or in legacy-free mode
with bin/ysh
.As of 2024, OSH is mature, and YSH is under development. See blog posts tagged #FAQ for more detail.
This doc walks you through setting up Oils, explains some concepts, and links to more documentation.
The releases page links to source tarballs for every release. It also links to the documentation tree, which includes this page.
After running the instructions in INSTALL, run:
mkdir -p ~/.config/oils # for oshrc and yshrc
mkdir -p ~/.local/share/oils # for osh_history
rc
FilesNote that
bin/osh
runs ~/.config/oils/oshrc
bin/ysh
runs ~/.config/oils/yshrc
These are the only files that are "sourced". Other shells have a
confusing initialization sequence involving many files (original).
It's very hard to tell when and if /etc/profile
, ~/.bashrc
,
~/.bash_profile
, etc. are executed.
OSH and YSH intentionally avoid this. If you want those files, simply source
them in your oshrc
.
I describe my own oshrc
file on the Wiki: How To Test
OSH.
~/.config/oils/oshrc
, symlink it to ~/.oshrc
.bash
or zsh
, then the prompt string $PS1
may
be unintentionally inherited. Running PS1=''
before bin/osh
avoids this.
This is also true for $PS2
, $PS4
, etc.$LANG
may not get set without
/etc/profile
. Adding source /etc/profile
to your oshrc
may solve this
problem.sh
and Bash Docs Are Useful for OSHExisting educational materials for the Unix shell apply to OSH, because they generally don't teach the quirks that OSH disallows. For example, much of the information and advice in BashGuide can be used without worrying about which shell you're using. See the end of this manual for more resources.
For this reason, we're focusing efforts on documenting YSH.
"Batch" programs are most likely to run unmodified under OSH. On the other
hand, Interactive programs like .bashrc
and bash completion scripts may
require small changes.
The -n
flag tells OSH to parse the program rather than executing it. By
default, it prints an abbreviated abstract syntax tree:
$ bin/osh -n -c 'ls | wc -l'
(command.Pipeline children:[(C {(ls)}) (C {(wc)} {(-l)})] negated:F)
You can also ask for the full text
format:
$ bin/osh -n --ast-format text -c 'ls | wc -l'
(command.Pipeline
children: [
(command.Simple
words: [
(word.Compound
parts: [(word_part.Literal
token:(token id:Lit_Chars val:ls span_id:0))]
)
]
)
(command.Simple
words: [
(word.Compound
parts: [(word_part.Literal
token:(token id:Lit_Chars val:wc span_id:4))]
)
(word.Compound
parts: [(word_part.Literal
token:(token id:Lit_Chars val:-l span_id:6))]
)
]
)
]
negated: F
spids: [2]
)
This format is subject to change. It's there for debugging the parser, but sophisticated users may use it to interpret tricky shell programs without running them.
OILS_HIJACK_SHEBANG
This environment variable can be set to the path of a shell. Before OSH executes a program, it will inspect the shebang line to see if it looks like a shell script. If it does, it will use this shell instead of the one specified in the shebang line.
For example, suppose you have myscript.sh
:
#!/bin/sh
# myscript.sh
./otherscript.sh --flag ...
and otherscript.sh
:
#!/bin/sh
# otherscript.sh
echo 'hello world'
Then you can run myscript.sh
like this:
OILS_HIJACK_SHEBANG=osh osh myscript.sh
and otherscript.sh
will be executed with OSH rather than the /bin/sh
.
Note that osh
appears twice in that command line: once for the initial
run, and once for all recursive runs.
(This is an environment variable rather than a flag because it needs to be inherited.)
--debug-file
Print internal debug logs to this file. It's useful to make it a FIFO:
mkfifo _tmp/debug
osh --debug-file _tmp/debug
Then run this in another window to see logs as you type:
cat _tmp/debug
Related:
OSH_DEBUG_DIR
environment variable is the inherited version of
--debug-file
. A file named $PID-osh.log
will be written in that
directory for every shell process.--xtrace-to-debug-file
flag sends set -o xtrace
output to that file
instead of to stderr
.OSH_CRASH_DUMP_DIR
This is implemented, but a JSON library isn't in the release build.
For more features unique to Oils, see Why Use Oils?
External: