sh

prettier-plugin-sh

An opinionated shellscript formatter plugin for Prettier, also support simple format of Dockerfile, properties, gitignore, dotenv, hosts, jvmoptions...

Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing, taking various rules into account.

This plugin adds support for various file formats through mvdan-sh via sh-syntax and dockerfmt.

Notice

This plugin is still under development, its printer just wraps mvdan-sh's default printer with powered by sh-syntax. Of course it should just work, but may not match prettier's format sometimes.

Warning

ignore files are not officially supported by mvdan-sh what means only basic and simple ignore usage cases can be handled correctly. We cannot do much on our side. See also #336.

Requirements

prettier-plugin-sh is an evergreen module. 🌲 This module requires an LTS Node version (v16.0.0+).

Install

Using npm:

# npm
npm i -D prettier prettier-plugin-sh

# yarn
yarn add -D prettier prettier-plugin-sh

Usage

Once installed, Prettier plugins must be added to .prettierrc:

{
  "plugins": ["prettier-plugin-sh"]
}

Then:

# npx
npx prettier --write script.sh

# yarn
yarn prettier --write script.sh

Parser Options

interface ShOptions {
  // parser
  /**
   * KeepComments makes the parser parse comments and attach them to
   * nodes, as opposed to discarding them.
   */
  keepComments?: boolean
  /**
   * LangVariant describes a shell language variant to use when tokenizing and
   * parsing shell code. The zero value is [LangBash].
   */
  variant?: LangVariant
  /**
   * StopAt configures the lexer to stop at an arbitrary word, treating it
   * as if it were the end of the input. It can contain any characters
   * except whitespace, and cannot be over four bytes in size.
   *
   * This can be useful to embed shell code within another language, as
   * one can use a special word to mark the delimiters between the two.
   *
   * As a word, it will only apply when following whitespace or a
   * separating token. For example, StopAt("$$") will act on the inputs
   * "foo $$" and "foo;$$", but not on "foo '$$'".
   *
   * The match is done by prefix, so the example above will also act on
   * "foo $$bar".
   */
  stopAt?: string
  /**
   *  RecoverErrors allows the parser to skip up to a maximum number of
   *  errors in the given input on a best-effort basis.
   *  This can be useful to tab-complete an interactive shell prompt,
   *  or when providing diagnostics on slightly incomplete shell source.
   *
   *  Currently, this only helps with mandatory tokens from the shell grammar
   *  which are not present in the input. They result in position fields
   *  or nodes whose position report [Pos.IsRecovered] as true.
   *
   *  For example, given the input
   *
   * 	(foo |
   *
   *  the result will contain two recovered positions; first, the pipe requires
   *  a statement to follow, and as [Stmt.Pos] reports, the entire node is recovered.
   *  Second, the subshell needs to be closed, so [Subshell.Rparen] is recovered.
   */
  recoverErrors?: number
  /**
   * KeepComments makes the parser parse comments and attach them to
   * nodes, as opposed to discarding them.
   * @default true
   */
  keepComments: boolean
  /**
   * LangVariant describes a shell language variant to use when tokenizing and
   * parsing shell code. The zero value is [LangBash].
   */
  variant: LangVariant
  /**
   * StopAt configures the lexer to stop at an arbitrary word, treating it
   * as if it were the end of the input. It can contain any characters
   * except whitespace, and cannot be over four bytes in size.
   *
   * This can be useful to embed shell code within another language, as
   * one can use a special word to mark the delimiters between the two.
   *
   * As a word, it will only apply when following whitespace or a
   * separating token. For example, StopAt("$$") will act on the inputs
   * "foo $$" and "foo;$$", but not on "foo '$$'".
   *
   * The match is done by prefix, so the example above will also act on
   * "foo $$bar".
   */
  stopAt: string
  /**
   *  RecoverErrors allows the parser to skip up to a maximum number of
   *  errors in the given input on a best-effort basis.
   *  This can be useful to tab-complete an interactive shell prompt,
   *  or when providing diagnostics on slightly incomplete shell source.
   *
   *  Currently, this only helps with mandatory tokens from the shell grammar
   *  which are not present in the input. They result in position fields
   *  or nodes whose position report [Pos.IsRecovered] as true.
   *
   *  For example, given the input
   *
   * 	(foo |
   *
   *  the result will contain two recovered positions; first, the pipe requires
   *  a statement to follow, and as [Stmt.Pos] reports, the entire node is recovered.
   *  Second, the subshell needs to be closed, so [Subshell.Rparen] is recovered.
   */
  recoverErrors: number

  // printer
  /**
   * Indent sets the number of spaces used for indentation. If set to 0,
   * tabs will be used instead.
   */
  indent: number
  /**
   * BinaryNextLine will make binary operators appear on the next line
   * when a binary command, such as a pipe, spans multiple lines. A
   * backslash will be used.
   * @default true
   */
  binaryNextLine: boolean
  /**
   * SwitchCaseIndent will make switch cases be indented. As such, switch
   * case bodies will be two levels deeper than the switch itself.
   */
  switchCaseIndent: boolean
  /**
   * SpaceRedirects will put a space after most redirection operators. The
   * exceptions are '>&', '<&', '>(', and '<('.
   */
  spaceRedirects: boolean
  /**
   * KeepPadding will keep most nodes and tokens in the same column that
   * they were in the original source. This allows the user to decide how
   * to align and pad their code with spaces.
   *
   * Note that this feature is best-effort and will only keep the
   * alignment stable, so it may need some human help the first time it is
   * run.
   *
   * @deprecated: this formatting option is flawed and buggy, and often does
   * not result in what the user wants when the code gets complex enough.
   *
   * The next major version, v4, will remove this feature entirely.
   * See: https://github.com/mvdan/sh/issues/658
   */
  keepPadding: boolean
  /**
   * Minify will print programs in a way to save the most bytes possible.
   * For example, indentation and comments are skipped, and extra
   * whitespace is avoided when possible.
   */
  minify: boolean
  /**
   * SingleLine will attempt to print programs in one line. For example, lists of
   * commands or nested blocks do not use newlines in this mode. Note that some
   * newlines must still appear, such as those following comments or around
   * here-documents.
   *
   * Print's trailing newline when given a [*File] is not affected by this option.
   */
  singleLine: boolean
  /**
   * FunctionNextLine will place a function's opening braces on the next line.
   */
  functionNextLine: boolean
}

More details on godoc

Sponsors

1stG	RxTS	UnTS

Backers

1stG	RxTS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

MIT © JounQin@1stG.me