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).