MGS3018: a directory as a job write path

magus job fork, the client tool (magus\job.put) and a magusfile's magus\job.put refused a job because one of its write paths names a directory that already exists:

[MGS3018] job: wave/docs-fix declares a directory as a write path: "internal/job",
  inside project ".". A write path names files: a directory, a project root
  included, claims every file under it, so the job would overlap every job editing
  anything there. List the files the job will edit, and name each file it creates
  by its path

Nothing was written to the job store.

Why

A write path is a claim. A directory claims every file under it, so a job that declares one overlaps every other job that edits anything in that directory, whether or not the two ever touch the same file. The overlap report then fills with pairs that share no file, and an orchestrator reading it as a queue holds work back that could have started.

A project root is no exception. . claims the whole repository, so a job declaring it overlaps every other job and its write paths say nothing about what it will change. A sub-project root such as console does the same inside that project.

A job's brief names the files it will change. The write paths should name the same files.

What passes

• A file, existing or not: internal/job/store.go.
• A path that does not exist yet. The job creates it, so nobody else can be editing anything under it.
• A file pattern, such as internal/job/*.go or internal/**/*_test.go.

A glob whose last segments are only wildcards, such as internal/**, internal/* or internal/**/*, names everything under its directory, so it is judged as that directory; ** alone is the workspace root. When the directory part is itself a pattern (libs/*/src/**), each directory it matches is judged.

The refusal says where each directory sits: the workspace root, the root of project "console", or inside project ".".

What to do

List the files the job will edit:

magus job fork wave/docs-fix --write-paths internal/job/store.go,internal/job/store_test.go

magus refs <symbol> --occurrences lists the files a change to a symbol touches. There is no flag that accepts a directory.

See also

• Leases: what a write path grants and what the guard enforces.