Effective Shell, an open book on shell scripting with runnable samples

What the repository actually contains

Effective Shell is described as text, samples and references for the Effective Shell series, and the hosted book lives at effective-shell.com. The repository is the source of that book, not a tool you link against, and that distinction shapes how you should treat it.

Three things live here. The prose is under docs/, written in MDX so it can carry interactive components. The site is a Docusaurus project with its configuration in docusaurus.config.js, the navigation in sidebars.js and a second file sidebarsSnippets.js for the snippet pages, and the custom React components under src/. The samples are a separate tree under samples/, and the README notes that folder is automatically zipped and attached to the website so it can be downloaded directly as effective-shell-samples.zip or effective-shell-samples.tar.gz.

The samples directory is organised into directories that map to how a shell user actually works: scripts, dotfiles, programs, logs, quotes, templates, text, data, docs, pictures and websites. There is also a samples/.bashrc file, so the sample tree is meant to be sourced rather than merely read.

The interactive layer is where the site differs from a plain book. The dependencies include docusaurus-plugin-drawio for diagrams, asciinema-player for terminal recordings, theme-live-codeblock for runnable code blocks, and docusaurus-search-local for search. The terminal recordings are all built with asciinema, and the README credits Marcin Kulik for that tool.

The content itself is a long-form book rather than a reference, and the README lists named reviewers and proof-readers for specific chapters, which tells you the text has been through several rounds of technical review.

Installing the samples and running the site locally

The samples install into a folder called ~/effective-shell, and the README gives a one-line installer:

curl effective.sh | sh

There are also direct archive downloads from the site, as a zip or a tarball. The installer itself lives in a separate repository, dwmkerr/effective-shell-installer, which is worth noting if you are the kind of team that reviews a script before piping it into a shell. Piping a network response straight into an interpreter gives whoever controls that endpoint the ability to run code as you, and reading the installer source first costs a minute.

For working on the book itself, the Makefile is the entry point. Dependencies are set up with:

make setup

Type checking is a separate target, which matters because the site is TypeScript and React rather than plain Markdown:

make typescript-check

Serving and building are the other two:

make serve
make build

The built site lands in the build directory. The port for local work is 3745, which the README explains is the phone keypad spelling of ESHL, and the same port appears in the package.json scripts where docusaurus start and docusaurus serve both bind to it. There is also a live component preview page served from that port at the zz-developer-guide/components path, which is a fast way to check a styling change without reading the whole book.

Components become globally available by adding them to the swizzled MDXComponents.js file under src/theme, which is the standard Docusaurus mechanism for injecting components into the Markdown rendering pipeline.

Versioning, releases and the shape of the project

The package.json holds the version of both the site and the code, currently 0.53.0. Releases are handled by Release Please through the release-please.yaml workflow, which means the version bump and the changelog are generated from conventional commit messages rather than edited by hand. The CHANGELOG.md file in the repository is the record of that process.

A manual release is still possible, and the README gives the exact command:

git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"

The release history shows a steady cadence: v0.52.1 on 2026-06-03, v0.52.2 on 2026-07-09 and v0.53.0 on 2026-09-01, with the last push to the repository on 2026-10-18. A patch version moving frequently like this is what you expect from a book that gets edited as feedback arrives, rather than from a library with an API surface.

The repository also carries a CLAUDE.md file and a.claude directory, plus a.husky directory with the prepare script wired to husky in package.json, so the project has some agent-facing configuration in place. There is an ideas.md file for notes that have not become chapters yet.

The site's own dependencies are pinned to Docusaurus 2.2.0 with React 17 and TypeScript 4.6.3. That pin is the most consequential technical fact in package.json: it is a generation-old toolchain that works, but it will not pick up newer Docusaurus features without a migration.

Licensing, and the question of reusing the chapters

This is the part that decides whether the book is usable in a commercial context, and the answer is more restrictive than most open source readers expect.

The README states that all content is Copyright (c) Dave Kerr, and that the work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. The badge in the README header points at the same licence, and the repository carries a sponsorship link for the author rather than a permissive software licence. The licence field on the repository says it is unknown, which matches the fact that this is content rather than code with a standard software licence.

The practical reading is straightforward. You can read it, you can link to it, you can adapt and repost it with attribution provided you stay inside non-commercial use and share adaptations under the same terms. You cannot drop a chapter into a commercial training product, a customer-facing handbook or a paid course without a different arrangement with the author.

The samples directory deserves a separate check rather than an assumption. The README applies the Creative Commons statement to the content of the book, and the samples are described as part of the same repository of text, samples and references, but the licence text covers the work as a whole. If you plan to lift a script from samples/ into your own codebase, read the licence file in the repository and confirm the terms for that specific file rather than inferring them from the prose.

The repository does invite direct contact: the README says to get in touch by opening an issue with questions on copyright or licensing.

How this compares with other shell learning resources

The alternative most people will think of first is the official Bash manual, which is complete, authoritative and free, and which this book does not replace. The difference in approach is that the manual is a specification you consult, while Effective Shell is a sequence of chapters that builds up a way of working, with each idea backed by files you can run.

The other common alternative is a course or a video series. Those tend to present a fixed order and a fixed pace, and they usually stop at the demonstration. What a sample repository adds is that you can read a chapter, then inspect the directory of scripts it refers to, then run them. The samples/.bashrc file, the dotfiles directory and the scripts directory turn the advice into something with an expected file layout.

A third comparison, with documentation tools such as tldr or cheat sheet collections, is instructive because the two serve different moments. A cheat sheet is for recall under pressure. A chapter with samples is for changing how you write scripts, and for arguing about why a construct is the way it is. The README credits specific reviewers for exactly that kind of detail, including one contributor acknowledged for helping with the nuances of word splitting and filename expansion and another for proof-reading the Python in the chapter on how to avoid shell scripting.

What this project does not do is teach a different shell. Everything here targets Bash and the standard Unix toolchain, with topics covering the shell, Linux, terminal work, DevOps and programming. If your daily driver is zsh or fish, the samples will still mostly apply but the site is not tuned to them.

Editorial conclusion

Adopt Effective Shell as a reference if you write Bash regularly and want chapters that pair an explanation with a runnable sample tree rather than a snippet in isolation. Do not reuse its chapters or sample code in a commercial product without checking the licence, because the content is Creative Commons Attribution-NonCommercial-ShareAlike 3.0 and the repository records the copyright as Dave Kerr. Verify first by running make setup and make serve to read the book locally, and by installing the samples into ~/effective-shell to see how the chapter files are organised on disk.

Frequently asked questions

Official sources

1. dwmkerr/effective-shell on GitHub
2. Issues
3. Project website
4. README
5. Releases