github.com/chainguard-dev/yam@v0.0.7/README.md (about)

     1  # yam 🍠
     2  
     3  A sweet little formatter for YAML
     4  
     5  ## Installation
     6  
     7  ```shell
     8  go install github.com/chainguard-dev/yam@latest
     9  ```
    10  
    11  ## Usage
    12  
    13  ### Format...
    14  
    15  To update file contents to match your formatting configuration, just specify one or more YAML files.
    16  
    17  ```shell
    18  yam a.yaml b.yaml
    19  ```
    20  
    21  You can also specify directories with YAML files in them. (Yam doesn't recurse through directories in directories.)
    22  
    23  ```shell
    24  yam ./dir-with-some-yamls
    25  ```
    26  
    27  And you can format files in the current working directory if you don't pass any arguments:
    28  
    29  ```shell
    30  yam
    31  ```
    32  
    33  ### Lint...
    34  
    35  To **_lint_** files instead of formatting them, just add `--lint` to the command. With this flag, Yam doesn't make any changes to your files, but it will exit `1` if any files don't match your formatting configuration.
    36  
    37  ```shell
    38  yam a.yaml --lint
    39  ```
    40  
    41  When linting, if Yam finds any files that don't pass the lint check, it will output a diff of what it got vs. what it expected to see.
    42  
    43  ## Formatting/Linting Options
    44  
    45  ### Gap Lines
    46  
    47  To expect a gap (empty line) in between child elements of a given node, just pass a `yq`-style path to the node, using `--gap`. You can use this flag as many times as needed.
    48  
    49  ```shell
    50  yam a.yaml --gap '.'
    51  ```
    52  
    53  ```shell
    54  yam a.yaml --gap '.foo.bar'
    55  ```
    56  
    57  ```shell
    58  yam a.yaml --gap '.people[].address'
    59  ```
    60  
    61  ```shell
    62  yam a.yaml --gap '.recipes[0].ingredients'
    63  ```
    64  
    65  ```shell
    66  yam a.yaml --gap '.types.*.inputs'
    67  ```
    68  
    69  ### Indentation
    70  
    71  You can also set the indent size (number of spaces) using `--indent`. Yam uses 2-space indentation by default.
    72  
    73  ```shell
    74  yam a.yaml --indent 4
    75  ```
    76  
    77  ### Sorting sequences
    78  
    79  You can also sort sequences so that for example you get alphabetized packages
    80  list using `--sort` where `--sort` takes in a `yq`-style path to the node that
    81  should be sorted.
    82  
    83  ```shell
    84  yam a.yaml --sort .packages
    85  ```
    86  
    87  **Note** This is only meant to be used for scalars, behavior for objects is not
    88  supported.
    89  
    90  ### Using a config file
    91  
    92  Yam will also look for a `.yam.yaml` file in the current working directory as a source of configuration. Using a config file is optional. CLI flag values take priority over config file values. The config file can be used to configure `indent` and `gap` values only.
    93  
    94  Example `.yam.yaml`:
    95  
    96  ```yaml
    97  indent: 4   # Defaults to 2
    98  
    99  gap:        # Defaults to none
   100  - "."
   101  - ".users"
   102  ```
   103  
   104  ## Yam's Encoder
   105  
   106  Yam has a special YAML encoder it uses to handle formatting as it writes out YAML bytes. This encoder is configurable.
   107  
   108  Yam bases its encoder on the YAML encoder from https://github.com/go-yaml/yaml, and uses this library's `yaml.Node` type as the input to encoding operations.
   109  
   110  This means you're able to decode data using https://github.com/go-yaml/yaml, modify data as needed, and then encode the `yaml.Node` using **yam's encoder** instead. This is nifty if you want to write YAML data that's correctly formatted from the beginning.
   111  
   112  For example, before:
   113  
   114  ```go
   115  import (
   116      // ...
   117      "gopkg.in/yaml.v3"
   118  )
   119  
   120  func someFunction(myData yaml.Node, w io.Writer) {
   121      enc := yaml.NewEncoder(w)
   122  
   123      // use the encoder!
   124  	_ = enc.Encode(myData)
   125  }
   126  ```
   127  
   128  And after:
   129  
   130  ```go
   131  import (
   132      // ...
   133      "github.com/chainguard-dev/yam/pkg/yam/formatted"
   134  )
   135  
   136  func someFunction(myData yaml.Node, w io.Writer) {
   137      enc := formatted.NewEncoder(w)
   138  
   139      // use the encoder!
   140      _ = enc.Encode(myData)
   141  }
   142  ```
   143  
   144  ### Configuring the encoder
   145  
   146  Yam's encoder has chainable methods that can be used for configuring its options.
   147  
   148  For example:
   149  
   150  ```go
   151  enc := formatted.NewEncoder(w).SetIndent(2).SetGapExpressions(".", ".users")
   152  ```
   153  
   154  #### Configuring the encoder with `.yam.yaml`
   155  
   156  You can also tell the encoder to behave similarly to the `yam` command, in that a `.yam.yaml` is automatically read if available.
   157  
   158  ```go
   159  enc := formatted.NewEncoder(w).AutomaticConfig()
   160  ```