Skip to content

Commit b289102

Browse files
redsun82Copilot
andcommitted
Just: document that overriding a shared variable freezes it
Overriding one of the shared bazel-formatting variables replaces the whole value, so a root wanting most of the default exclusions plus one of its own must restate all of them, not just add to the list. The same `--evaluate name=value` diagnostic used elsewhere for the override contract itself also shows this in practice. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent cf3d79f commit b289102

1 file changed

Lines changed: 16 additions & 5 deletions

File tree

‎misc/just/README.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,16 @@ overriding several loses only the renamed one, leaving a half-applied configurat
8181
total failure would land in a state someone designed, while partial failure lands in one
8282
nobody has ever seen.
8383

84-
Nothing can see it either, because the underscore that keeps these out of `just --list`
84+
An override also freezes what it replaces. A root assigns the whole value, so an
85+
exclusion or a name added here later never reaches one, and `just` offers no way to
86+
append: a root writing `_bazel_excluded := _bazel_excluded + ",mine"` is told the
87+
variable is defined in terms of itself. This runs the opposite way from a rename, where
88+
the override stops applying and the value here wins. Here the override keeps applying
89+
exactly as written, and the roots that never see the addition are the ones that cared
90+
enough about the setting to redirect it. Adding to one of these values is therefore a
91+
change to make on both sides at once.
92+
93+
Neither shows up anywhere, because the underscore that keeps these out of `just --list`
8594
keeps them out of `--variables` and a bare `--evaluate` as well. Asked by name they do
8695
answer, which is how a root checks that an override of its own still overrides anything:
8796

@@ -90,10 +99,12 @@ just --evaluate _bazel_excluded # what mine is now
9099
just --justfile <this-repo>/justfile --evaluate _bazel_excluded # what it would be
91100
```
92101

93-
A name that has gone says so rather than reporting an empty value. That is a diagnostic
94-
to reach for once something looks wrong, though: it answers whether a name still exists,
95-
not whether its meaning has changed, so it passes happily when the value here gains or
96-
loses a pattern. Rename freely, but say so when handing the change over.
102+
A name that has gone says so rather than reporting an empty value. Read as two values
103+
rather than as two names, the same pair also shows a freeze: a pattern appearing only
104+
under what it would be is one this repository added and the override never received.
105+
Expect differences both ways, since a root that overrode a value usually added something
106+
of its own, and only the missing half is a bug. Rename freely, but say so when handing
107+
the change over.
97108

98109
A directory that only makes sense when named explicitly can opt out of being found from
99110
above:

0 commit comments

Comments
 (0)