Skip to content

Commit

Permalink
docs: add golangci-lint integration info (#16)
Browse files Browse the repository at this point in the history
  • Loading branch information
tmzane authored Oct 25, 2023
1 parent b2f5791 commit 134336b
Showing 1 changed file with 28 additions and 13 deletions.
41 changes: 28 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,25 +31,36 @@ The linter has several options, so you can adjust it to your own code style.

## 📦 Install

Download a prebuilt binary from the [Releases][1] page.
`sloglint` is integrated into [`golangci-lint`][1], and this is the recommended way to use it.

## 📋 Usage
To enable the linter, add the following lines to `.golangci.yml`:

```shell
sloglint [flags] ./...
```yaml
linters:
enable:
- sloglint
```
Alternatively, you can download a prebuilt binary from the [Releases][2] page to use `sloglint` standalone.

## 📋 Usage

Run `golangci-lint` with `sloglint` enabled.
See the list of [available options][3] to configure the linter.

When using `sloglint` standalone, pass the options as flags of the same name.

### Key-value pairs only

The `-kv-only` flag causes `sloglint` to report any use of attributes:
The `kv-only` option causes `sloglint` to report any use of attributes:

```go
slog.Info("a user has logged in", slog.Int("user_id", 42)) // sloglint: attributes should not be used
```

### Attributes only

In contrast, the `-attr-only` flag causes `sloglint` to report any use of key-value pairs:
In contrast, the `attr-only` option causes `sloglint` to report any use of key-value pairs:

```go
slog.Info("a user has logged in", "user_id", 42) // sloglint: key-value pairs should not be used
Expand All @@ -59,7 +70,7 @@ slog.Info("a user has logged in", "user_id", 42) // sloglint: key-value pairs sh

Some `slog.Handler` implementations make use of the given `context.Context` (e.g. to access context values).
For them to work properly, you need to pass a context to all logger calls.
The `-context-only` flag causes `sloglint` to report the use of methods without a context:
The `context-only` option causes `sloglint` to report the use of methods without a context:

```go
slog.Info("a user has logged in") // sloglint: methods without a context should not be used
Expand All @@ -74,7 +85,7 @@ slog.InfoContext(ctx, "a user has logged in")
### No raw keys

To prevent typos, you may want to forbid the use of raw keys altogether.
The `-no-raw-keys` flag causes `sloglint` to report the use of strings as keys
The `no-raw-keys` option causes `sloglint` to report the use of strings as keys
(including `slog.Attr` calls, e.g. `slog.Int("user_id", 42)`):

```go
Expand All @@ -97,21 +108,23 @@ func UserId(value int) slog.Attr { return slog.Int("user_id", value) }
slog.Info("a user has logged in", UserId(42))
```

> 💡 Such helpers can be automatically generated for you by the [`sloggen`][2] tool. Give it a try too!
> 💡 Such helpers can be automatically generated for you by the [`sloggen`][4] tool. Give it a try too!

### Key naming convention

To ensure consistency in logs, you may want to enforce a single key naming convention.
The `-key-naming-case=<snake|kebab|camel|pascal>` flag causes `sloglint` to report keys written in a case other than the given one:
The `key-naming-case` option causes `sloglint` to report keys written in a case other than the given one:

```go
slog.Info("a user has logged in", "user-id", 42) // sloglint: keys should be written in snake_case
```

Possible values are `snake`, `kebab`, `camel`, or `pascal`.

### Arguments on separate lines

To improve code readability, you may want to put arguments on separate lines, especially when using key-value pairs.
The `-args-on-sep-lines` flag causes `sloglint` to report 2+ arguments on the same line:
The `args-on-sep-lines` option causes `sloglint` to report 2+ arguments on the same line:

```go
slog.Info("a user has logged in", "user_id", 42, "ip_address", "192.0.2.0") // sloglint: arguments should be put on separate lines
Expand All @@ -126,5 +139,7 @@ slog.Info("a user has logged in",
)
```

[1]: https://github.com/go-simpler/sloglint/releases
[2]: https://github.com/go-simpler/sloggen
[1]: https://golangci-lint.run
[2]: https://github.com/go-simpler/sloglint/releases
[3]: https://golangci-lint.run/usage/linters/#sloglint
[4]: https://github.com/go-simpler/sloggen

0 comments on commit 134336b

Please sign in to comment.