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.

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 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.

Important: If you want to use Oils, don't clone this repo. Instead, visit https://oils.pub/release/latest/. See the wiki: The Oils Repo Is Different From the Tarball Releases.

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 #oils-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.

Dev Build

After following those instructions, you should 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.

---

Remember that this is the dev build in Python, not a released binary. The Oils Repo Is Different From the Tarball Releases.

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