Skip to content

OSH versus Oil

Jump to bottom Edit New page
andychu edited this page Mar 27, 2023 · 27 revisions

Here is a short guide:

  • bin/osh runs the OSH language, which is extremely compatible with POSIX shell and bash. It's designed to run existing scripts.
  • bin/oil runs the Oil language, a new shell language that's designed to be familiar to Python and JavaScript users. You can gracefully upgrade your shell scripts to it, or write brand new scripts in it.

But they actually run in the same binary and use the same parser and interpreter! bin/osh and bin/oil are symlinks (or one line "forwarding" scripts).

This means that underneath there isn't a sharp line between OSH and Oil. (The fuzzy line has also changed as the project has matured.)

Specifically, there are many global shell options like shopt --set parse_brace that change OSH into Oil. Running bin/oil is equivalent to running bin/osh with the option group shopt --set oil:all. See the full option list below.

(As of 12/2021, OSH is a lot more mature than Oil.)

Examples

For examples of the syntax, see The Simplest Explanation of Oil.

What's the Difference between strict:all, oil:upgrade, and oil:all ?

  • strict:all. Use this if you want to run the same script under multiple shells, like bash and OSH.

  • oil:upgrade. Use this if you're upgrading existing script, and dropping compatibility with other shells.

    • You can use new Oil features, but you won't have to worry about every last strict_ bug.
    • You can start writing if (x > 0) { echo 'positive' } without worrying about unrelated breakage.

  • oil:all. Use this for a brand new program.

    • This is equivalent to running bin/oil rather than bin/osh.

  • Blog: What Options Should I Use For a New Script?

  • Docs: Global Shell Options

What are the use cases for OSH and Oil?

Here's another way of phrasing the same info above.

  1. Run old scripts as is (no options)
  2. Improve old scripts while keeping compatibility with sh or bash (strict:all)
  3. Start upgrading old scripts, dropping compatibility (oil:upgrade)
  4. Write new scripts (oil:all or bin/oil)

More Detail

Full Option List in oil:all

This command lets you see the difference between OSH and Oil in detail! -s means that the option is set when running in Oil mode, and -u means that it's unset.

$ oil -c 'shopt -p oil:all'
shopt -s command_sub_errexit
shopt -u dashglob
shopt -s errexit
shopt -u expand_aliases
shopt -s inherit_errexit
shopt -s nounset
shopt -s nullglob
shopt -s parse_amp
shopt -s parse_at
shopt -s parse_at_all
shopt -u parse_backslash
shopt -u parse_backticks
shopt -s parse_brace
shopt -u parse_dollar
shopt -s parse_equals
shopt -u parse_ignored
shopt -s parse_paren
shopt -s parse_raw_string
shopt -s parse_triple_quote
shopt -s pipefail
shopt -s process_sub_fail
shopt -u redefine_proc
shopt -s sigpipe_status_ok
shopt -s simple_echo
shopt -s simple_eval_builtin
shopt -s simple_test_builtin
shopt -s simple_word_eval
shopt -s strict_argv
shopt -s strict_arith
shopt -s strict_array
shopt -s strict_control_flow
shopt -s strict_errexit
shopt -s strict_glob
shopt -s strict_nameref
shopt -s strict_tilde
shopt -s strict_word_eval
shopt -u xtrace_details
shopt -s xtrace_rich

Related

Gradually Upgrading Shell to Oil

Add a custom footer
Add a custom sidebar
Clone this wiki locally