Where to Find Oils Documentation, Blog, and Community Support

Updated

Oils (oils.pub) is the home of OSH and YSH, two shells that ship inside a single oils-for-unix binary. The site itself is mainly a landing page: it points you to the install page, the docs, the blog, and the community channels rather than hosting long-form content. If you are looking for reference material, release notes, or a place to ask questions, use the links below.

Documentation and reference

  • Docs — linked from the top navigation on oils.pub. This is the entry point for written documentation.
  • Oils Reference — the reference section for OSH and YSH. Use it when you need exact syntax or builtin behavior rather than a tutorial.
  • Install — the install page, also in the top navigation. OSH and YSH live inside the same oils-for-unix binary, so one install gives you both.
  • All Releases — the site links to /release/latest/ and an "All Releases" page for version history.

The homepage shows a short example of the difference between the two shells: OSH runs existing shell scripts and reports errors such as fatal: Undefined variable 'oops', while YSH is aimed at Python and JavaScript users who want to avoid shell quirks, with examples like json read < x.json.

Blog and release announcements

The blog lives at oilshell.org, not on oils.pub. The site describes it as covering 2016–2024 and lists posts including "Oils 2023 FAQ," "Why Create a New Unix Shell?," "The Simplest Explanation," "A Tour of YSH," and "YSH vs. Shell Idioms."

To get notified about new posts, the site offers:

  • Mastodon: @oilsforunix
  • Twitter: @oilsforunix
  • RSS
  • Reddit

Community and support

Channel Where Purpose
Zulip oilshell.zulipchat.com #oil-help for user questions, #oil-discuss-public for general discussion, #oil-dev for changing the code (login required)
Reddit /r/oilsforunix Community discussion
GitHub oils-for-unix/oils Source code, issues, and contributions
Email andy at oilshell dot org Direct contact about shells and programming languages

The site also links a #help-wanted section for places to start contributing, and notes that build results are published to ci.oilshell.org, mb.oilshell.org, or op.oilshell.org.

Editor support

For Vim users, the project points to oils.vim editor support, linked from the GitHub repo.

Quick answer

If you want to read: start with Docs and the Oils Reference on oils.pub, then the blog at oilshell.org. If you want to ask: use Zulip #oil-help. If you want to contribute: check #help-wanted and the GitHub repo. If you want to follow updates: RSS, Mastodon, or Twitter under @oilsforunix.