github.com/aretext/aretext@v1.3.0/docs/configuration.md (about)

     1  Configuration
     2  =============
     3  
     4  Editing Config
     5  --------------
     6  
     7  Aretext stores its configuration in a single YAML file. You can edit the config file using the `editconfig` flag:
     8  
     9  ```
    10  aretext -editconfig
    11  ```
    12  
    13  The configuration file is located at `$XDG_CONFIG_HOME/aretext/config.yaml`, where `XDG_CONFIG_HOME` is configured according to the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). On Linux, this defaults to `~/.config`, and on macOS it defaults to `~/Library/Application Support`.
    14  
    15  When you open the config file, you should see something like:
    16  
    17  ```yaml
    18  - name: default
    19    pattern: "**"
    20    config:
    21      autoIndent: false
    22      hideDirectories: [".git"]
    23      syntaxLanguage: plaintext
    24      tabExpand: false
    25      tabSize: 4
    26      showLineNumbers: false
    27  
    28  - name: json
    29    pattern: "**/*.json"
    30    config:
    31      autoIndent: true
    32      syntaxLanguage: json
    33      tabExpand: true
    34      tabSize: 2
    35      showLineNumbers: true
    36  ```
    37  
    38  Each item in the configuration file describes a *rule*. For example, in the snippet above, the first rule is named "default" and the second rule is named "json".
    39  
    40  Each rule has a *pattern*. The "\*\*" is a wildcard that matches any subdirectory, and "\*" is a wildcard that matches zero or more characters in a file or directory name.
    41  
    42  When aretext loads a file, it checks each rule in order. If the rule's pattern matches the file's absolute path, it applies the rule to update the configuration.
    43  
    44  For example, if aretext loaded the file "foo/bar.json" using the above configuration, both rules would match the filename. The resulting configuration would be:
    45  
    46  ```yaml
    47  config:
    48    autoIndent: true           # from the "json" rule
    49    hideDirectories: [".git"]  # from the "default" rule
    50    syntaxLanguage: json       # from the "json" rule
    51    tabExpand: true            # from the "json" rule
    52    tabSize: 2                 # from the "json" rule
    53    showLineNumbers: true      # from the "json" rule
    54  ```
    55  
    56  When merging configurations from different rules:
    57  
    58  -	For strings and numbers, the values from later rules overwrite the values from previous rules.
    59  -	For lists, the values from all rules are combined.
    60  -	For dictionaries, the keys from later rules are added to the merged dictionary, potentially overwriting keys set by previous rules.
    61  
    62  This is a powerful mechanism for customizing configuration based on filename extension and/or project location. For example, suppose that the style guidelines for a project mandate four spaces of indentation for JSON. You could add a new rule to your config that overwrites the tabSize for JSON files in that specific project:
    63  
    64  ```yaml
    65  # ... other rules above ...
    66  - name: myproject json
    67    pattern: "**/myproject/**/*.json"
    68    config:
    69      tabSize: 4
    70  ```
    71  
    72  Troubleshooting
    73  ---------------
    74  
    75  ### Fixing errors on startup
    76  
    77  If your YAML config file has errors, aretext will exit with an error message. You can force aretext to ignore the config file by passing the "-noconfig" flag:
    78  
    79  ```
    80  aretext -editconfig -noconfig
    81  ```
    82  
    83  This allows you to start the editor so you can fix the configuration.
    84  
    85  ### Checking which rules were applied
    86  
    87  To see which configuration rules aretext applied when loading a file, start aretext with logging enabled:
    88  
    89  ```
    90  aretext -log debug.log
    91  ```
    92  
    93  If you view the file `debug.log`, you should see lines like this:
    94  
    95  ```
    96  Applying config rule 'default' with pattern '**' for path 'path/to/file.txt'
    97  ```
    98  
    99  This tells you which rules aretext applied when opening a file, which can help you debug your configuration.
   100  
   101  Configuration Reference
   102  -----------------------
   103  
   104  For a complete list of available configuration options, see [Configuration Reference](config-reference.md).