Invocation Examples

The following examples illustrate how precious executes a command with different invocation
options.

For these examples we will assume that the command is configured to execute for any file ending in
.go. The executable is some-linter and only takes paths as argument. The file tree looks like
this:

example
├── app.go
├── main.go
├── pkg1
│  ├── pkg1.go
├── pkg2
│  ├── pkg2.go
│  ├── pkg2_test.go
│  └── subpkg
│     └── subpkg.go
└── precious.toml

  - Runs once per file
  - Working directory is the project root
  - Relative file path as the argument

This is the default configuration.

[commands.some-linter]
invoke = "per-file"
working-dir = "root"
path-args = "file"

some-linter app.go
some-linter main.go
some-linter pkg1/pkg1.go
some-linter pkg2/pkg2.go
some-linter pkg2/pkg2_test.go
some-linter pkg2/subpkg/subpkg.go

  - Runs once per file
  - From the root
  - Absolute file path as the argument

[commands.some-linter]
invoke = "per-file"
working-dir = "root"
path-args = "absolute-file"

some-linter /example/app.go
some-linter /example/main.go
some-linter /example/pkg1/pkg1.go
some-linter /example/pkg2/pkg2.go
some-linter /example/pkg2/pkg2_test.go
some-linter /example/pkg2/subpkg/subpkg.go

  - Runs once per file
  - Working directory changes per-directory
  - Relative file path as the argument

[commands.some-linter]
invoke = "per-file"
working-dir = "dir"
path-args = "file"

some-linter app.go
some-linter main.go
cd /example/pkg1
some-linter pkg1.go
cd /example/pkg2
some-linter pkg2.go
some-linter pkg2_test.go
cd /example/pkg2/subpkg
some-linter subpkg.go

  - Runs once per file
  - Working directory changes per-directory
  - Absolute file path as the argument

[commands.some-linter]
invoke = "per-file"
working-dir = "dir"
path-args = "absolute-file"

some-linter /example/app.go
some-linter /example/main.go
cd /example/pkg1
some-linter /example/pkg1/pkg1.go
cd /example/pkg2
some-linter /example/pkg2/pkg2.go
some-linter /example/pkg2/pkg2_test.go
cd /example/pkg2/subpkg
some-linter /example/pkg2/subpkg/subpkg.go

It's odd to combine working-dir = "dir" with path-args = "absolute-file", but it will work.

  - Runs once per file
  - Working directory is the given subdirectory
  - Relative file path as the argument

[commands.some-linter]
invoke = "per-file"
working-dir.chdir-to = "pkg1"
path-args = "file"

cd /example/pkg1
some-linter ../app.go
some-linter ../main.go
some-linter ../pkg2/pkg2.go
some-linter ../pkg2/pkg2_test.go
some-linter ../pkg2/subpkg/subpkg.go
some-linter pkg1.go

  - Runs once per file
  - Working directory is the given subdirectory
  - Absolute file path as the argument

[commands.some-linter]
invoke = "per-file"
working-dir.chdir-to = "pkg1"
path-args = "absolute-file"

cd /example/pkg1
some-linter /example/app.go
some-linter /example/main.go
some-linter /example/pkg1/pkg1.go
some-linter /example/pkg2/pkg2.go
some-linter /example/pkg2/pkg2_test.go
some-linter /example/pkg2/subpkg/subpkg.go

  - Runs once per directory
  - Working directory is the root
  - Relative directory path as pargument

[commands.some-linter]
invoke = "per-dir"
working-dir = "root"
path-args = "dir"

some-linter .
some-linter pkg1
some-linter pkg2
some-linter pkg2/subpkg

  - Runs once per directory
  - Working directory is the root
  - Absolute directory path as pargument

[commands.some-linter]
invoke = "per-dir"
working-dir = "root"
path-args = "absolute-dir"

some-linter /example
some-linter /example/pkg1
some-linter /example/pkg2
some-linter /example/pkg2/subpkg

  - Runs once per directory
  - Working directory is the root
  - Relative file paths as arguments

[commands.some-linter]
invoke = "per-dir"
working-dir = "root"
path-args = "file"

some-linter app.go main.go
some-linter pkg1/pkg1.go
some-linter pkg2/pkg2.go pkg2/pkg2_test.go
some-linter pkg2/subpkg/subpkg.go

  - Runs once per directory
  - Working directory is the root
  - Absolute file paths as arguments

[commands.some-linter]
invoke = "per-dir"
working-dir = "root"
path-args = "absolute-file"

some-linter /example/app.go /example/main.go
some-linter /example/pkg1/pkg1.go
some-linter /example/pkg2/pkg2.go /example/pkg2/pkg2_test.go
some-linter /example/pkg2/subpkg/subpkg.go

  - Runs once per directory
  - Working directory is each directory in turn
  - Dot (.) as the path argument

[commands.some-linter]
invoke = "per-dir"
working-dir = "dir"
path-args = "dot"

some-linter .
cd /example/pkg1
some-linter .
cd /example/pkg2
some-linter .
cd /example/pkg2/subpkg
some-linter .

  - Runs once per directory
  - Working directory is each directory in turn
  - No path argument

[commands.some-linter]
invoke = "per-dir"
working-dir = "dir"
path-args = "none"

some-linter
cd /example/pkg1
some-linter
cd /example/pkg2
some-linter
cd /example/pkg2/subpkg
some-linter

  - Runs once per directory
  - Working directory is the given subdirectory
  - Relative file paths as the argument

[commands.some-linter]
invoke = "per-dir"
working-dir.chdir-to = "pkg1"
path-args = "file"

cd /example/pkg1
some-linter ../app.go ../main.go
some-linter ../pkg2/pkg2.go ../pkg2/pkg2_test.go
some-linter ../pkg2/subpkg/subpkg.go
some-linter pkg1.go

  - Runs once per directory
  - Working directory is the given subdirectory
  - Absolute file paths as the argument

[commands.some-linter]
invoke = "per-dir"
working-dir.chdir-to = "pkg1"
path-args = "absolute-file"

cd /example/pkg1
some-linter /example/app.go /example/main.go
some-linter /example/pkg1/pkg1.go
some-linter /example/pkg2/pkg2.go /example/pkg2/pkg2_test.go
some-linter /example/pkg2/subpkg/subpkg.go

  - Runs once per directory
  - Working directory is the given subdirectory
  - Relative directory path as the argument

[commands.some-linter]
invoke = "per-dir"
working-dir.chdir-to = "pkg1"
path-args = "dir"

cd /example/pkg1
some-linter .
some-linter ..
some-linter ../pkg2
some-linter ../pkg2/subpkg

  - Runs once per directory
  - Working directory is the given subdirectory
  - Absolute directory path as the argument

[commands.some-linter]
invoke = "per-dir"
working-dir.chdir-to = "pkg1"
path-args = "absolute-dir"

cd /example/pkg1
some-linter /example
some-linter /example/pkg1
some-linter /example/pkg2
some-linter /example/pkg2/subpkg

  - Runs once for all files
  - Working directory is the root
  - Relative file paths as arguments

[commands.some-linter]
invoke = "once"
working-dir = "root"
path-args = "file"

some-linter \
    app.go \
    main.go \
    pkg1/pkg1.go \
    pkg2/pkg2.go \
    pkg2/pkg2_test.go \
    pkg2/subpkg/subpkg.go

  - Runs once for all files
  - Working directory is the root
  - Absolute file paths as arguments

[commands.some-linter]
invoke = "once"
working-dir = "root"
path-args = "absolute-file"

some-linter \
    /example/app.go \
    /example/main.go \
    /example/pkg1/pkg1.go \
    /example/pkg2/pkg2.go \
    /example/pkg2/pkg2_test.go \
    /example/pkg2/subpkg/subpkg.go

  - Runs once for all directories
  - Working directory is the root
  - Relative directory paths as arguments

[commands.some-linter]
invoke = "once"
working-dir = "root"
path-args = "dir"

some-linter . pkg1 pkg2 pkg2/subpkg

  - Runs once for all directories
  - Working directory is the root
  - Absolute directory paths as arguments

[commands.some-linter]
invoke = "once"
working-dir = "root"
path-args = "absolute-dir"

some-linter \
    /example \
    /example/pkg1 \
    /example/pkg2 \
    /example/pkg2/subpkg

  - Runs once for all paths
  - Working directory is the root
  - Dot (.) as the path argument

[commands.some-linter]
invoke = "once"
working-dir = "root"
path-args = "dot"

some-linter .

  - Runs once for all paths
  - Working directory is the root
  - No path argument

[commands.some-linter]
invoke = "once"
working-dir = "root"
path-args = "none"

some-linter

  - Runs once
  - Working directory is the given subdirectory
  - Relative file paths as the arguments

[commands.some-linter]
invoke = "once"
working-dir.chdir-to = "pkg1"
path-args = "file"

cd /example/pkg1
some-linter ../app.go ../main.go pkg1.go ../pkg2/pkg2.go ../pkg2/pkg2_test.go ../pkg2/subpkg/subpkg.go

  - Runs once
  - Working directory is the given subdirectory
  - Absolute file paths as the arguments

[commands.some-linter]
invoke = "once"
working-dir.chdir-to = "pkg1"
path-args = "absolute-file"

cd /example/pkg1
some-linter \
    /example/app.go \
    /example/main.go \
    /example/pkg1/pkg1.go \
    /example/pkg2/pkg2.go \
    /example/pkg2/pkg2_test.go \
    /example/pkg2/subpkg/subpkg.go

  - Runs once
  - Working directory is the given subdirectory
  - Relative directory paths as the arguments

[commands.some-linter]
invoke = "once"
working-dir.chdir-to = "pkg1"
path-args = "dir"

cd /example/pkg1
some-linter .. . ../pkg2 ../pkg2/subpkg

  - Runs once
  - Working directory is the given subdirectory
  - Absolute directory paths as the arguments

[commands.some-linter]
invoke = "once"
working-dir.chdir-to = "pkg1"
path-args = "absolute-dir"

cd /example/pkg1
some-linter /example /example/pkg1 /example/pkg2 /example/pkg2/subpkg

  - Runs once
  - Working directory is the given subdirectory
  - Dot (.) as the path argument

[commands.some-linter]
invoke = "once"
working-dir.chdir-to = "pkg1"
path-args = "dot"

cd /example/pkg1
some-linter .

  - Runs once
  - Working directory is the given subdirectory
  - No path argument

[commands.some-linter]
invoke = "once"
working-dir.chdir-to = "pkg1"
path-args = "none"

cd /example/pkg1
some-linter
