# package-directory-match

Source: https://api-genie.dev/docs/linter/protobuf/rules/package-directory-match

A rule of the Protobuf linter, which reads proto3 files; the reader rejects proto2 and editions files. Since 0.9.0. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule checks whether every Protobuf file is in the directory that corresponds to its
package, for example `acme/pets/v1` for the package `acme.pets.v1`.

## Rule details

When the directories mirror the packages, the import path of a file tells where its
declarations live, and the files of a package are easy to find. Many code generators and build
tools expect this layout.

The expected directory of a package is its name with the dots replaced by slashes. The
`package-directory-match` rule compares it with the directory of the file in one of two ways:

- If the file is inside one of the import paths (given with `--proto-path` or with the
  `import_paths` key of the configuration), the directory of the file relative to the first
  import path that contains it must be the expected directory. Otherwise the rule reports
  `Package '<package>' should be in directory '<expected>' of import path '<import path>', not
  in '<directory>'`, where `<directory>` is `.` for a file directly in the import path. The
  import path is shown as an absolute path.
- Otherwise, the directory of the file must end with the expected directory. If it does not,
  the rule reports `Package '<package>' should be in a directory ending with '<expected>'`.

Import paths in the configuration are relative to the directory of the configuration file:

```yaml
version: "1.0"
commands:
  lint:
    protobuf:
      import_paths: [proto]
```

Files without a package, and files linted without a path, are not checked.

The rule uses the path of the linted file and the import paths, but does not read other files.

Turn the rule off if your build places the files in directories that are unrelated to their
packages, for example a flat directory of `.proto` files.

## Examples

**Good**. The file `proto/acme/pets/v1/pet.proto`:

```proto
syntax = "proto3";

package acme.pets.v1;

message Pet {
  string name = 1;
}
```

**Bad**. Without import paths, the file `proto/pets/v1/pet.proto` makes the linter report
`Package 'acme.pets.v1' should be in a directory ending with 'acme/pets/v1'`. With the import
path `proto`, and the project in `/work`, it reports `Package 'acme.pets.v1' should be in
directory 'acme/pets/v1' of import path '/work/proto', not in 'pets/v1'`.

```proto
syntax = "proto3";

package acme.pets.v1;

message Pet {
  string name = 1;
}
```
