lodash 中文文档

  reviewdog - A code review dog who keeps your codebase healthy.

GitHub Actions reviewdog release

reviewdog provides a way to post review comments to code hosting service, such as GitHub, automatically by integrating with any linter tools with ease. It uses an output of lint tools and posts them as a comment if findings are in diff of patches to review.

reviewdog also supports run in the local environment to filter an output of lint tools by diff.

design doc

Table of Contents


Installation
Input Format
'errorformat'
Available pre-defined 'errorformat'
Reviewdog Diagnostic Format (RDFormat)
Diff
checkstyle format

Code Suggestions
reviewdog config file
Reporters
Reporter: Local (-reporter=local) [default]
Reporter: GitHub Checks (-reporter=github-pr-check)
Reporter: GitHub Checks (-reporter=github-check)
Reporter: GitHub PullRequest review comment (-reporter=github-pr-review)
Reporter: GitLab MergeRequest discussions (-reporter=gitlab-mr-discussion)
Reporter: GitLab MergeRequest commit (-reporter=gitlab-mr-commit)
Reporter: Bitbucket Code Insights Reports (-reporter=bitbucket-code-report)

Supported CI services
GitHub Actions
Travis CI
Circle CI
GitLab CI
Bitbucket Pipelines
Common (Jenkins, local, etc...)
Jenkins with GitHub pull request builder plugin

Exit codes
Filter mode
Articles

Installation


  1. ``` shell
  2. # Install the latest version. (Install it into ./bin/ by default).
  3. $ curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s

  5. # Specify installation directory ($(go env GOPATH)/bin/) and version.
  6. $ curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b $(go env GOPATH)/bin [vX.Y.Z]

  8. # In alpine linux (as it does not come with curl by default)
  9. $ wget -O - -q https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s [vX.Y.Z]
  10. ```

Nightly releases


You can also use nightly reviewdog release to try the latest reviewdog improvements every day!

  1. ``` shell
  2. $ curl -sfL https://raw.githubusercontent.com/reviewdog/nightly/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
  3. ```

GitHub Action: reviewdog/action-setup


  1. ``` yaml
  2. steps:
  3. - uses: reviewdog/action-setup@v1
  4.   with:
  5.     reviewdog_version: latest # Optional. [latest,nightly,v.X.Y.Z]
  6. ```

homebrew / linuxbrew


You can also install reviewdog using brew:

  1. ``` shell
  2. $ brew install reviewdog/tap/reviewdog
  3. $ brew upgrade reviewdog/tap/reviewdog
  4. ```

Scoop on Windows


  1. ``` sh
  2. > scoop install reviewdog

  4. ```

Build with go install


  1. ``` shell
  2. $ go install github.com/reviewdog/reviewdog/cmd/reviewdog@latest
  3. ```

Input Format


'errorformat'


reviewdog accepts any compiler or linter result from stdin and parses it with scan-f like 'errorformat', which is the port of Vim's errorformat feature.

For example, if the result format is {file}:{line number}:{column number}: {message}, errorformat should be %f:%l:%c: %m and you can pass it as -efm arguments.

  1. ``` shell
  2. $ golint ./...
  3. comment_iowriter.go:11:6: exported type CommentWriter should have comment or be unexported
  4. $ golint ./... | reviewdog -efm="%f:%l:%c: %m" -diff="git diff FETCH_HEAD"
  5. ```

name description
:--- :---
%f file name
%l line number
%c column number
%m error message
%% the single '%' character
... ...

Please see reviewdog/errorformat and :h errorformat if you want to deal with a more complex output. 'errorformat' can handle more complex output like a multi-line error message.

You can also try errorformat on the Playground !

By this 'errorformat' feature, reviewdog can support any tools output with ease.

Available pre-defined 'errorformat'


But, you don't have to write 'errorformat' in many cases. reviewdog supports pre-defined errorformat for major tools.

You can find available errorformat name by reviewdog -list and you can use it with -f={name}.

  1. ``` shell
  2. $ reviewdog -list
  3. golint          linter for Go source code                                       - https://github.com/golang/lint
  4. govet           Vet examines Go source code and reports suspicious problems     - https://golang.org/cmd/vet/
  5. sbt             the interactive build tool                                      - http://www.scala-sbt.org/
  6. ...
  7. ```

  1. ``` shell
  2. $ golint ./... | reviewdog -f=golint -diff="git diff FETCH_HEAD"
  3. ```

You can add supported pre-defined 'errorformat' by contributing to reviewdog/errorformat

Reviewdog Diagnostic Format (RDFormat)


reviewdog supports Reviewdog Diagnostic Format (RDFormat) as a generic diagnostic format and it supports both rdjson and rdjsonl formats.

This rdformat supports rich feature like multiline ranged comments, severity, rule code with URL, and code suggestions.

  1. ``` shell
  2. $ <linter> | <convert-to-rdjson> | reviewdog -f=rdjson -reporter=github-pr-review
  3. # or
  4. $ <linter> | <convert-to-rdjsonl> | reviewdog -f=rdjsonl -reporter=github-pr-review
  5. ```

Example: ESLint with RDFormat


You can use eslint-formatter-rdjson to output rdjson as eslint output format.

  1. ``` shell
  2. $ npm install --save-dev eslint-formatter-rdjson
  3. $ eslint -f rdjson . | reviewdog -f=rdjson -reporter=github-pr-review
  4. ```

Or you can also use reviewdog/action-eslint for GitHub Actions.

Diff


reviewdog supports diff (unified format) as an input format especially useful for code suggestions. reviewdog can integrate with any code suggestions tools or formatters to report suggestions.

-f.diff.strip : option for -f=diff : strip NUM leading components from diff file names (equivalent to 'patch -p') (default is 1 for git diff) (default 1)

  1. ``` shell
  2. $ <any-code-fixer/formatter> # e.g. eslint --fix, gofmt
  3. $ TMPFILE=$(mktemp)
  4. $ git diff >"${TMPFILE}"
  5. $ git stash -u && git stash drop
  6. $ reviewdog -f=diff -f.diff.strip=1 -reporter=github-pr-review < "${TMPFILE}"
  7. ```

Or you can also use reviewdog/action-suggester for GitHub Actions.

If diagnostic tools support diff output format, you can pipe the diff directly.

  1. ``` shell
  2. $ gofmt -s -d . | reviewdog -name="gofmt" -f=diff -f.diff.strip=0 -reporter=github-pr-review
  3. $ shellcheck -f diff $(shfmt -f .) | reviewdog -f=diff
  4. ```

checkstyle format


reviewdog also accepts checkstyle XML format as well. If the linter supports checkstyle format as a report format, you can use -f=checkstyle instead of using 'errorformat'.

  1. ``` shell
  2. # Local
  3. $ eslint -f checkstyle . | reviewdog -f=checkstyle -diff="git diff"

  5. # CI (overwrite tool name which is shown in review comment by -name arg)
  6. $ eslint -f checkstyle . | reviewdog -f=checkstyle -name="eslint" -reporter=github-check
  7. ```

Also, if you want to pass other Json/XML/etc... format to reviewdog, you can write a converter.

  1. ``` shell
  2. $ <linter> | <convert-to-checkstyle> | reviewdog -f=checkstyle -name="<linter>" -reporter=github-pr-check
  3. ```

Code Suggestions


reviewdog supports code suggestionsfeature with rdformat or diff input. You can also use reviewdog/action-suggester for GitHub Actions.

reviewdog can suggest code changes along with diagnostic results if a diagnostic tools supports code suggestions data. You can integrate reviewdog with any code fixing tools and any code formatter with diff input as well.

Code Suggestions Support Table


Note that not all reporters provide support of code suggestion.

-reporter Suggestion support
:--- :---
local NO [1]
github-check NO [2]
github-pr-check NO [2]
github-pr-review OK
gitlab-mr-discussion NO [1]
gitlab-mr-commit NO [2]
gerrit-change-review NO [1]
bitbucket-code-report NO [2]

[1] The reporter service support code suggestion feature, but reviewdog does not support it yet. See #678 for the status.
[2] The reporter service itself doesn't support code suggestion feature.

reviewdog config file


reviewdog can also be controlled via the .reviewdog.yml configuration file instead of "-f" or "-efm" arguments.

With .reviewdog.yml, you can run the same commands both CI service and local environment including editor integration with ease.

.reviewdog.yml


  1. ``` yaml
  2. runner:
  3.   <tool-name>:
  4.     cmd: <command> # (required)
  5.     errorformat: # (optional if you use `format`)
  6.       - <list of errorformat>
  7.     format: <format-name> # (optional if you use `errorformat`. e.g. golint,rdjson,rdjsonl)
  8.     name: <tool-name> # (optional. you can overwrite <tool-name> defined by runner key)
  9.     level: <level> # (optional. same as -level flag. [info,warning,error])

  11.   # examples
  12.   golint:
  13.     cmd: golint ./...
  14.     errorformat:
  15.       - "%f:%l:%c: %m"
  16.     level: warning
  17.   govet:
  18.     cmd: go vet -all .
  19.     format: govet
  20.   your-awesome-linter:
  21.     cmd: awesome-linter run
  22.     format: rdjson
  23.     name: AwesomeLinter
  24. ```

  1. ``` shell
  2. $ reviewdog -diff="git diff FETCH_HEAD"
  3. project/run_test.go:61:28: [golint] error strings should not end with punctuation
  4. project/run.go:57:18: [errcheck]        defer os.Setenv(name, os.Getenv(name))
  5. project/run.go:58:12: [errcheck]        os.Setenv(name, "")
  6. # You can use -runners to run only specified runners.
  7. $ reviewdog -diff="git diff FETCH_HEAD" -runners=golint,govet
  8. project/run_test.go:61:28: [golint] error strings should not end with punctuation
  9. # You can use -conf to specify config file path.
  10. $ reviewdog -conf=./.reviewdog.yml -reporter=github-pr-check
  11. ```

Output format for project config based run is one of the following formats.

<file>: [<tool name>] <message>
<file>:<lnum>: [<tool name>] <message>
<file>:<lnum>:<col>: [<tool name>] <message>

Reporters


reviewdog can report results both in local environment and review services as continuous integration.

Reporter: Local (-reporter=local) [default]


reviewdog can find newly introduced findings by filtering linter results using diff. You can pass diff command as -diff arg.

  1. ``` shell
  2. $ golint ./... | reviewdog -f=golint -diff="git diff FETCH_HEAD"
  3. ```

Reporter: GitHub Checks (-reporter=github-pr-check)


github-pr-check reporter reports results to GitHub Checks.

You can change report level for this reporter by level field in configfile or -level flag. You can control GitHub status check result with this feature. (default: error)

Level GitHub Status
:--- :---
info neutral
warning neutral
error failure

There are two options to use this reporter.

Option 1) Run reviewdog from GitHub Actions w/ secrets.GITHUB_TOKEN


Example: .github/workflows/reviewdog.yml

  1. ``` yaml
  2. - name: Run reviewdog
  3.   env:
  4.     REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  5.   run: |
  6.     golint ./... | reviewdog -f=golint -reporter=github-pr-check
  7. ```

See GitHub Actions section too. You can also use public reviewdog GitHub Actions.

Option 2) Install reviewdog GitHub Apps


reviewdog CLI send a request to reviewdog GitHub App server and the server post results as GitHub Checks, because Check API only supported for GitHub App and GitHub Actions.

Install reviewdog Apps. https://github.com/apps/reviewdog
Set REVIEWDOG_TOKEN or run reviewdog CLI in trusted CI providers.

Get token from https://reviewdog.app/gh/{owner}/{repo-name}.

  1. ``` shell
  2. $ export REVIEWDOG_TOKEN="<token>"
  3. $ reviewdog -reporter=github-pr-check
  4. ```

Note: Token is not required if you run reviewdog in Travis or AppVeyor.

Caution

As described above, github-pr-check reporter with Option 2 depends on reviewdog GitHub App server. The server is running with haya14busa's pocket money for now and I may break things, so I cannot ensure that the server is running 24h and 365 days.

UPDATE:Started getting support by opencollective and GitHub sponsor. See Supporting reviewdog

You can use github-pr-review reporter or use run reviewdog under GitHub Actions if you don't want to depend on reviewdog server.

Reporter: GitHub Checks (-reporter=github-check)


It's basically same as -reporter=github-pr-check except it works not only for Pull Request but also for commit.

You can create reviewdog badge for this reporter.

Reporter: GitHub PullRequest review comment (-reporter=github-pr-review)


github-pr-review reporter reports results to GitHub PullRequest review comments using GitHub Personal API Access Token. GitHub Enterprise is supported too.

Go to https://github.com/settings/tokens and generate new API token.
Check repo for private repositories or public_repo for public repositories.

  1. ``` shell
  2. $ export REVIEWDOG_GITHUB_API_TOKEN="<token>"
  3. $ reviewdog -reporter=github-pr-review
  4. ```

For GitHub Enterprise, set API endpoint by environment variable.

  1. ``` shell
  2. $ export GITHUB_API="https://example.githubenterprise.com/api/v3/"
  3. $ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL
  4. ```

See GitHub Actions section too if you can use GitHub Actions. You can also use public reviewdog GitHub Actions.

Reporter: GitLab MergeRequest discussions (-reporter=gitlab-mr-discussion)


Required GitLab version: >= v10.8.0

gitlab-mr-discussion reporter reports results to GitLab MergeRequest discussions using GitLab Personal API Access token. Get the token with api scope from https://gitlab.com/profile/personal_access_tokens.

  1. ``` shell
  2. $ export REVIEWDOG_GITLAB_API_TOKEN="<token>"
  3. $ reviewdog -reporter=gitlab-mr-discussion
  4. ```

The CI_API_V4_URL environment variable, defined automatically by Gitlab CI (v11.7 onwards), will be used to find out the Gitlab API URL.

Alternatively, GITLAB_API can also be defined, in which case it will take precedence over CI_API_V4_URL.

  1. ``` shell
  2. $ export GITLAB_API="https://example.gitlab.com/api/v4"
  3. $ export REVIEWDOG_INSECURE_SKIP_VERIFY=true # set this as you need to skip verifying SSL
  4. ```

Reporter: GitLab MergeRequest commit (-reporter=gitlab-mr-commit)


gitlab-mr-commit is similar to gitlab-mr-discussion reporter but reports results to each commit in GitLab MergeRequest.

gitlab-mr-discussion is recommended, but you can use gitlab-mr-commit reporter if your GitLab version is under v10.8.0.

  1. ``` shell
  2. $ export REVIEWDOG_GITLAB_API_TOKEN="<token>"
  3. $ reviewdog -reporter=gitlab-mr-commit
  4. ```

Reporter: Gerrit Change review (-reporter=gerrit-change-review)


gerrit-change-review reporter reports result to Gerrit Change using Gerrit Rest APIs.

The reporter supports Basic Authentication and Git-cookie based authentication for reporting results.

Set GERRIT_USERNAME and GERRIT_PASSWORD environment variables for basic authentication, and put `GIT_GITCOOK