Skip to content

Update shell style #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pbrisbin merged 1 commit into from
Jun 25, 2025
Merged

Update shell style #102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions shell-style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,14 @@
Add explicit annotations as needed. When adding new scripts, confirm that our
CI machinery is configured to run on your files.

1. All scripts end in a `.sh` extension
1. Executable scripts should **not** end in a `.sh` extension

This is typically an anti-pattern, but we currently rely on it to locate
shell scripts within the source tree for the purposes of Shellcheck on CI.
An executable shoudl be opaque and not leak its implementation language. If a
script is meant to be used as libaray (e.g. with `source`), then it can end in
a `.sh` extension but should not be marked exsecutable.

We use to require a `.sh` extension so CI could locate files for linting, but
that is no longer how that works.
Comment on lines +14 to +19
Copy link
Copy Markdown
Member Author

@pbrisbin pbrisbin Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Holy cow there are some typos here. That's what I get for editing in the GitHub UI I guess :/


1. Always use double-quotes, except where interpolation must be prevented

Expand Down Expand Up @@ -174,8 +178,8 @@ if you use `[[` because you want regex or glob matching in one place, don't use
1. Scripts should validate their options and error with proper [usage
syntax][usage-syntax] and conventional [exit code][exit-code]:

[usage-syntax]: https://stackoverflow.com/a/9727046 [exit-code]:
https://www.freebsd.org/cgi/man.cgi?query=sysexits&apropos=0&sektion=0&manpath=FreeBSD%204.3-RELEASE&format=html
[usage-syntax]: https://stackoverflow.com/a/9727046
[exit-code]: https://www.freebsd.org/cgi/man.cgi?query=sysexits&apropos=0&sektion=0&manpath=FreeBSD%204.3-RELEASE&format=html

```sh
if [ "$#" -lt 2 ]; then
Expand Down Expand Up @@ -334,13 +338,13 @@ The following features should give you pause:

Some alternatives:

1. Is this part of CI/Deployment? Try writing it in Shake
1. Is this part of CI/Deployment? Try making a GitHub Action (e.g. in typescript)
1. Is this called from something like `yarn`? Consider using js-specific tooling
1. Is the process infrequent and made simpler by hard-coding some information
about the local environment (paths, passwords, etc)? Consider just
documenting the command with dummy values to be copied, edited, and run
1. Is the process frequent, useful, and complex? Consider adding to FRTool or
creating a standalone Haskell binary
1. Is the process frequent, useful, and complex? Consider building a standalone CLI
or Haskell binary in the package where it's used

## Additional References

Expand Down