Document custom format and add tips to integrate with Github Actions (c…

…lj-kondo#848)
roosta · Apr 9, 2020 · 9533596 · 9533596
1 parent 8a8a8dc
commit 9533596
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 0 deletions.
diff --git a/doc/ci-integration.md b/doc/ci-integration.md
@@ -20,4 +20,34 @@ A number of [GitHub Actions](https://github.com/features/actions) that use `clj-
 
 - [clojure-lint-action](https://github.com/marketplace/actions/clj-kondo-checks)
 - [lint-clojure](https://github.com/marketplace/actions/clj-kondo)
+- [setup-clj-kondo](https://github.com/marketplace/actions/setup-clj-kondo)
 
+### Linter Output Integration
+
+Github Actions can integrate with clj-kondo output using a custom output pattern. To enable this, set `clj-kondo`'s config to: 
+
+``` edn
+{:output {:pattern "::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}"}}
+```
+
+Example configuration with action [setup-clj-kondo](https://github.com/marketplace/actions/setup-clj-kondo):
+
+```
+on: push
+name: Push / PR Builder
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Setup clj-kondo
+      uses: DeLaGuardo/setup-clj-kondo@822352b8aa37d5c94135e67f7b4e2f46c08008a8
+      with:
+        version: '2020.04.05'
+        
+    - uses: actions/checkout@v2
+    
+    - name: Lint
+      run: clj-kondo --lint src --config '{:output {:pattern "::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}"}}'
+```
+
+For more information on Github Action Commands, see [Workflow Commands for Github Actions](https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-a-warning-message).
diff --git a/doc/config.md b/doc/config.md
@@ -344,6 +344,24 @@ $ clj-kondo --lint corpus --config '{:output {:format :json}}' | jq '.findings[0
 
 Printing in EDN format is also supported.
 
+### Print results with a custom format
+
+``` shell
+$ clj-kondo --lint corpus --config '{:output {:pattern "::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}"}}'
+::warning file=corpus/compojure/core.clj,line=2,col=19::Unsorted namespace: foo
+```
+
+The custom pattern supports these template values:
+
+| Template Variable | Notes                                                     |
+|-------------------|-----------------------------------------------------------|
+| `{{filename}}`    | File name                                                 |
+| `{{row}}`         | Row where linter violation starts                         |
+| `{{col}}`         | Column where linter violation starts                      |
+| `{{level}}`       | Lowercase level of linter warning, one of info,warn,error |
+| `{{LEVEL}}`       | Uppercase variant of `{{level}}`                          |
+| `{{message}}`     | Linter message                                            |
+
 ### Include and exclude files from the output
 
 ``` shellsession