https://github.com/mvdan/sh/blob/master/cmd/shfmt/shfmt.1.scd

Skip to content Toggle navigation
 
Sign up

  * Product
      +  
        Actions
        Automate any workflow
      +  
        Packages
        Host and manage packages
      +  
        Security
        Find and fix vulnerabilities
      +  
        Codespaces
        Instant dev environments
      +  
        Copilot
        Write better code with AI
      +  
        Code review
        Manage code changes
      +  
        Issues
        Plan and track work
      +  
        Discussions
        Collaborate outside of code
      + Explore
      + All features
      + Documentation
      + GitHub Skills
      + Blog
  * Solutions
      + For
      + Enterprise
      + Teams
      + Startups
      + Education
      + By Solution
      + CI/CD & Automation
      + DevOps
      + DevSecOps
      + Case Studies
      + Customer Stories
      + Resources
  * Open Source
      +  
        GitHub Sponsors
        Fund open source developers
      +  
        The ReadME Project
        GitHub community articles
      + Repositories
      + Topics
      + Trending
      + Collections
  * Pricing

[                    ] 

  *  
    #
    In this repository All GitHub |
    Jump to |

  * No suggested jump to results

  *  
    #
    In this repository All GitHub |
    Jump to |
  *  
    #
    In this user All GitHub |
    Jump to |
  *  
    #
    In this repository All GitHub |
    Jump to |

Sign in
Sign up
{{ message }}
mvdan / sh Public

  * 
  * Notifications
  * Fork 295
  * Star 5.5k

  * Code
  * Issues 80
  * Pull requests 6
  * Discussions
  * Actions
  * Security
  * Insights

More

  * Code
  * Issues
  * Pull requests
  * Discussions
  * Actions
  * Security
  * Insights

Permalink
master
Switch branches/tags
[                    ]
Branches Tags
Could not load branches
Nothing to show
{{ refName }} default View all branches
Could not load tags
Nothing to show
{{ refName }} default
View all tags

Name already in use

A tag already exists with the provided branch name. Many Git commands
accept both tag and branch names, so creating this branch may cause
unexpected behavior. Are you sure you want to create this branch?
Cancel Create

sh/cmd/shfmt/shfmt.1.scd

Go to file

  * Go to file T
  * Go to line L
  * 
  * Copy path
  * Copy permalink

This commit does not belong to any branch on this repository, and may
belong to a fork outside of the repository.
@mvdan
mvdan cmd/shfmt: implement --from-json and improve -tojson
...
Latest commit c016564 Jul 13, 2022 History

For the sake of consistency, -tojson is now also available as --to-json.

The following changes are made to --to-json:

1) JSON object keys are no longer sorted alphabetically.
   The new order is: the derived keys (Type, Pos, End),
   and then the Node's struct fields in their original order.
   This helps consistency across nodes and with the Go documentation.

2) File.Name is empty by default, rather than `<standard input>`.
   It did not make sense as a default for emitting JSON,
   as the flag always required the input to be stdin.

3) Empty values are no longer emitted, to help with verbosity.
   This includes `false`, `""`, `null`, `[]`, and zero positions.
   Positions offsets are exempt, as 0 is a valid byte offset.

4) All position fields in Node structs are now emitted.
   Some positions are redundant given the derived Pos and End keys,
   but some others are entirely separate, like IfClause.ThenPos.

As part of point 1 above, JSON encoding no longer uses Go maps.
It now uses reflect.StructOf, which further leans into Go reflection.

Any of these four changes could potentially break users,
as they slightly change the way we encode syntax trees as JSON.
We are working under the assumption that the changes are reasonable,
and that any breakage is unlikely and easy to fix.
If those assumptions turn out to be false once this change is released,
we can always swap the -tojson flag to be exactly the old behavior,
and --to-json can then add the new behavior in a safer way.

We also had other ideas to further improve the JSON format,
such as renaming the Type and Pos/End JSON keys,
but we leave those as v4 TODOs as they will surely break most users.

The new --from-json flag does the reverse; it decodes the typed JSON,
and fills a *syntax.File with all the information.
The derived Type field is used to select syntax.Node types,
and the derived Pos and End fields are ignored entirely.

It's worth noting that neither --to-json nor --from-json are optimized.
The decoding side first decodes into an empty interface, for example,
which leaves plenty of room for improvement.
Once we're happy with the functionality, we can look at faster
implementations and even dropping the need for reflection.

While here, I noticed that the godoc for Pos.IsValid was slightly wrong.

As a proof of concept, the following commands all produce the same result:

        shfmt <input.sh
        shfmt --to-json <input.sh | shfmt --from-json
        shfmt --to-json <input.sh | jq | shfmt --from-json

Fixes #35 again, as we never implemented the "read JSON" side.

3 contributors

Users who have contributed to this file

@mvdan @mikepqr @tmillr
[                    ]
NAME SYNOPSIS DESCRIPTION OPTIONS Generic flags Parser flags Printer
flags Utility flags EXAMPLES AUTHORS
152 lines (103 sloc) 3.82 KB
Raw Blame
Edit this file
E
Open in GitHub Desktop

  * Open with Desktop
  * View raw
  * 
  * View blame

shfmt(1)

 NAME

shfmt - Format shell programs

 SYNOPSIS

shfmt [flags] [path...]

 DESCRIPTION

shfmt formats shell programs. If the only argument is a dash (-) or
no arguments are given, standard input will be used. If a given path
is a directory, all shell scripts found under that directory will be
used.

If any EditorConfig files are found, they will be used to apply
formatting options. If any parser or printer flags are given to the
tool, no EditorConfig files will be used. A default like -i=0 can be
used for this purpose.

shfmt's default shell formatting was chosen to be consistent, common,
and predictable. Some aspects of the format can be configured via
printer flags.

 OPTIONS

 Generic flags

-version Show version and exit.

-l, --list List files whose formatting differs from shfmt's.

-w, --write Write result to file instead of stdout.

-d, --diff Error with a diff when the formatting differs.

The diff uses color when the output is a terminal.
To never use color, set a non-empty *NO_COLOR* or *TERM=dumb*.
To always use color, set a non-empty *FORCE_COLOR*.

-s, --simplify Simplify the code.

-mn, --minify Minify the code to reduce its size (implies -s).

 Parser flags

-ln, --language-dialect Language dialect (bash/posix/mksh/bats,
default auto).

When set to *auto*, the language is detected from the input filename,
as long as it has a shell extension like *foo.mksh*. Otherwise, if the input
begins with a shell shebang like *#!/bin/sh*, that's used instead.
If neither come up with a result, *bash* is used as a fallback.

The filename extension *.sh* is a special case: it implies *posix*,
but may be overriden by a valid shell shebang.

-p, --posix Shorthand for -ln=posix.

-filename str Provide a name for the standard input file.

 Printer flags

-i, --indent Indent: 0 for tabs (default), >0 for number of spaces.

-bn, --binary-next-line Binary ops like && and | may start a line.

-ci, --case-indent Switch cases will be indented.

-sr, --space-redirects Redirect operators will be followed by a
space.

-kp, --keep-padding Keep column alignment paddings.

-fn, --func-next-line Function opening braces are placed on a
separate line.

 Utility flags

-f, --find Recursively find all shell files and print the paths.

--to-json Print syntax tree to stdout as a typed JSON.

--from-json Read syntax tree from stdin as a typed JSON.

 EXAMPLES

Format all the scripts under the current directory, printing which
are modified:

shfmt -l -w .

For CI, one can use a variant where formatting changes are just shown
as diffs:

shfmt -d .

The following formatting flags closely resemble Google's shell style
defined in https://google.github.io/styleguide/shell.xml:

shfmt -i 2 -ci -bn

Below is a sample EditorConfig file as defined by https://
editorconfig.org/, showing how to set any option:

[*.sh]
# like -i=4
indent_style = space
indent_size = 4

shell_variant      = posix # --language-variant
binary_next_line   = true
switch_case_indent = true  # --case-indent
space_redirects    = true
keep_padding       = true
function_next_line = true  # --func-next-line

# Ignore the entire "third_party" directory.
[third_party/**]
ignore = true

shfmt can also replace bash -n to check shell scripts for syntax
errors. It is more exhaustive, as it parses all syntax statically and
requires valid UTF-8:

$ echo '${foo:1 2}' | bash -n
$ echo '${foo:1 2}' | shfmt >/dev/null
1:9: not a valid arithmetic operator: 2
$ echo 'foo=(1 2)' | bash --posix -n
$ echo 'foo=(1 2)' | shfmt -p >/dev/null
1:5: arrays are a bash feature

 AUTHORS

Maintained by Daniel Marti mvdan@mvdan.cc, who is assisted by other
open source contributors. For more information and development, see
https://github.com/mvdan/sh.

[                    ] Go
Footer

 (c) 2023 GitHub, Inc.

Footer navigation

  * Terms
  * Privacy
  * Security
  * Status
  * Docs
  * Contact GitHub
  * Pricing
  * API
  * Training
  * Blog
  * About

You can't perform that action at this time.
You signed in with another tab or window. Reload to refresh your
session. You signed out in another tab or window. Reload to refresh
your session.