Oils Source Code

Oils is our upgrade path from bash to a better language and runtime!

• OSH runs your existing shell scripts.
• YSH is for Python and JavaScript users who avoid shell.

(The project was slightly renamed in March 2023, so there are still old references to "Oil". Feel free to send pull requests with corrections!)

Oils 2023 FAQ / Why Create a New Unix Shell?

It's written in Python, so the code is short and easy to change. But we automatically translate it to C++ with custom tools, to make it fast and small. The deployed executable doesn't depend on Python.

This README is at the root of the git repo.

Contributing

• Try making the dev build of Oils with the instructions on the Contributing page. This should take 1 to 5 minutes if you have a Linux machine.
• If it doesn't, let us know. You can post on the #oil-dev channel of oilshell.zulipchat.com, or file an issue on Github.
• Feel free to grab an issue from Github. Let us know what you're thinking before you get too far.

Quick Start on Linux

After following the instructions on the Contributing page, you'll have a Python program that you can quickly run and change! Try it interactively:

bash$ bin/osh

osh$ name=world
osh$ echo "hello $name"
hello world

• Try running a shell script you wrote with bin/osh myscript.sh.
• Try YSH with bin/ysh.

Let us know if any of these things don't work! The continuous build tests them at every commit.

Dev Build vs. Release Build

Again, note that the developer build is very different from the release tarball. The Contributing page describes this difference in detail.

The release tarballs are linked from the home page. (Developer builds don't work on OS X, so use the release tarballs on OS X.)

Important: We Accept Small Contributions!

Oils is full of many ideas, which may be intimidating at first.

But the bar to contribution is very low. It's basically a medium size Python program with many tests, and many programmers know how to change such programs. It's great for prototyping.

• For OSH compatibility, I often merge failing spec tests. You don't even have to write code! The tests alone help. I search for related tests with grep xtrace spec/*.test.sh, where xtrace is a shell feature.
• You only have to make your code work in Python. Plain Python programs are easy to modify. The semi-automated translation to C++ is a separate step, although it often just works.
• You can influence the design of YSH. If you have an itch to scratch, be ambitious. For example, you might want to show us how to implement nonlinear pipelines.

I aim for 24 hour response time

Please feel free to ping andychu on Zulip or Github if you're waiting for a pull request review! (or to ask questions)

Usually I can respond in 24 hours. I might be traveling, in which case I'll respond with something like I hope to look at this by Tuesday.

I might have also missed your Github message, so it doesn't hurt to ping me.

Thank you for the contributions!

Docs

The Wiki has many developer docs. Feel free to edit them. If you make a major change, let us know on Zulip!

If you're confused, the best thing to do is to ask on Zulip and someone should produce a pointer and/or improve the docs.

Docs for end users are linked from each release page.

Links

• The Oils Home Page has all the important links.
• Related:
  • Repository Structure: See the Oils Repo Overview
  • The README-index.md links to docs for some subdirectories. For example, mycpp/README.md is pretty detailed.
  • FAQ: The Oils Repo Is Different From the Tarball