OILS / README.md View on Github | oils.pub

134 lines, 93 significant
1Oils Source Code
2================
3
4[![Build
5Status](https://github.com/oils-for-unix/oils/actions/workflows/all-builds.yml/badge.svg?branch=master)](https://github.com/oils-for-unix/oils/actions/workflows/all-builds.yml) <a href="https://gitpod.io/from-referrer/">
6 <img src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod" alt="Contribute with Gitpod" />
7</a>
8
9[Oils][home-page] is our upgrade path from bash to a better language and runtime!
10
11- [OSH][] runs your existing shell scripts.
12- [YSH][] is for Python and JavaScript users who avoid shell.
13
14[home-page]: https://oils.pub/
15
16[OSH]: https://oils.pub/cross-ref.html#OSH
17[YSH]: https://oils.pub/cross-ref.html#YSH
18
19[rename]: https://www.oilshell.org/blog/2023/03/rename.html
20
21[Oils 2023 FAQ][faq-2023] / [Why Create a New Unix Shell?][why]
22
23[faq-2023]: https://www.oilshell.org/blog/2023/03/faq.html
24[why]: https://www.oilshell.org/blog/2021/01/why-a-new-shell.html
25
26It's written in Python, so the code is short and easy to change. But we
27translate it to C++ with custom tools, to make it fast and small. The deployed
28executable doesn't depend on Python.
29
30This README is at the root of the [git repo][git-repo].
31
32**Important**: If you want to **use** Oils, don't clone this repo. Instead, visit
33<https://oils.pub/release/latest/>.
34See the wiki: [The Oils Repo Is Different From the Tarball Releases](https://github.com/oils-for-unix/oils/wiki/The-Oils-Repo-Is-Different-From-the-Tarball-Releases).
35
36[git-repo]: https://github.com/oils-for-unix/oils
37
38<div id="toc">
39</div>
40
41## Contributing
42
43* Try making the **dev build** of Oils with the instructions on the
44 [Contributing][] page. This should take 1 to 5 minutes if you have a Linux
45 machine.
46* If it doesn't, let us know. You can post on the `#oils-dev` channel of
47 [oilshell.zulipchat.com][], or file an issue on Github.
48* Feel free to grab an [issue from
49 Github](https://github.com/oils-for-unix/oils/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
50 Let us know what you're thinking before you get too far.
51
52[Contributing]: https://github.com/oils-for-unix/oils/wiki/Contributing
53[oilshell.zulipchat.com]: https://oilshell.zulipchat.com/
54[blog]: https://oils.pub/blog/
55
56### Dev Build
57
58After following those instructions, you should have a Python program that you
59can quickly run and change! Try it interactively:
60
61 bash$ bin/osh
62
63 osh$ name=world
64 osh$ echo "hello $name"
65 hello world
66
67- Try running a shell script you wrote with `bin/osh myscript.sh`.
68- Try [YSH][] with `bin/ysh`.
69
70Let us know if any of these things don't work! [The continuous
71build](https://op.oilshell.org/) tests them at every commit.
72
73---
74
75Remember that this is the **dev build** in Python, not a released binary. [The
76Oils Repo Is Different From the Tarball Releases](https://github.com/oils-for-unix/oils/wiki/The-Oils-Repo-Is-Different-From-the-Tarball-Releases).
77
78### Important: We Accept Small Contributions!
79
80Oils is full of [many ideas](https://oils.pub/blog/), which may be
81intimidating at first.
82
83But the bar to contribution is very low. It's basically a medium size Python
84program with many tests, and many programmers know how to change such programs.
85It's great for prototyping.
86
87- For OSH compatibility, I often merge **failing [spec
88 tests](https://oils.pub/cross-ref.html#spec-test)**. You don't even
89 have to write code! The tests alone help. I search for related tests with
90 `grep xtrace spec/*.test.sh`, where `xtrace` is a shell feature.
91- You only have to make your code work **in Python**. Plain Python programs
92 are easy to modify. The semi-automated translation to C++ is a separate
93 step, although it often just works.
94- You can **influence the design** of [YSH][]. If you have an itch to
95 scratch, be ambitious. For example, you might want to show us how to
96 implement [nonlinear pipelines](https://github.com/oils-for-unix/oils/issues/843).
97
98### I aim for 24 hour response time
99
100Please feel free to ping `andychu` on Zulip or Github if you're **waiting** for
101a pull request review! (or to ask questions)
102
103Usually I can respond in 24 hours. I might be traveling, in which case I'll
104respond with something like *I hope to look at this by Tuesday*.
105
106I might have also **missed** your Github message, so it doesn't hurt to ping
107me.
108
109Thank you for the contributions!
110
111## Docs
112
113The [Wiki](https://github.com/oils-for-unix/oils/wiki) has many developer docs. Feel
114free to edit them. If you make a major change, let us know on Zulip!
115
116If you're confused, the best thing to do is to ask on Zulip and someone should
117produce a pointer and/or improve the docs.
118
119Docs for **end users** are linked from each [release
120page](https://oils.pub/releases.html).
121
122## Links
123
124* The [Oils Home Page][home-page] has all the important links.
125* Related:
126 * Repository Structure: See the [Oils Repo Overview][repo-overview]
127 * The [README-index.md](README-index.md) links to docs for some
128 subdirectories. For example, [mycpp/README.md](mycpp/README.md) is pretty
129 detailed.
130 * FAQ: [The Oils Repo Is Different From the Tarball][repo-tarball-faq]
131
132[repo-overview]: doc/repo-overview.md
133
134[repo-tarball-faq]: https://github.com/oils-for-unix/oils/wiki/The-Oils-Repo-Is-Different-From-the-Tarball-Releases