| Document | draft-fossil-repo-state-01 |
| Section | 6.2, Branch creation (a sym tag both applied and cancelled on the root); 5.3, Direct Application Procedure, step 1 |
| Type | Technical (a combined effect left undefined that Fossil determines) |
| Status | Applied in draft-fossil-repo-state-01 (2026-10-14) |
| Reported | 2026-10-14 |
| Submitter | Dan Mestas |
| Found via | A review of the drafts from libfossil; confirmed by running Fossil 2.28 and reading its source |
1. Summary
§6.2 records that fossil branch new can write both T *sym-NAME * and
T -sym-NAME * on a branch root, when the parent already carries a
propagating sym-NAME, and then says "this document does not define their
combined effect". Fossil determines it. Crosslink applies an artifact's tag
cards one at a time in card order, all with the artifact's own mtime, so the
§5.3 skip rule decides: the * card sorts first and writes the row, and the
- card meets a row with an equal mtime and is skipped. The root keeps the
propagating tag.
§5.3 calls the equal-mtime case implementation-defined because the winner depends on write order. For two cards of one artifact the order is fixed by the artifact, so the case is defined once the draft says the cards are applied in card order.
2. The text in error
Page 18 (§6.2, informative paragraph):
If the parent itself carries a propagating sym-* tag of the new branch's own name, branch new emits both the propagating card and a cancel card for that name; this document does not define their combined effect.
Page 15 (§5.3 step 1):
If two competing applications for the same (tag, artifact) pair carry exactly equal mtime, the >= skip rule makes the winner depend on write order, so that equal-mtime case is implementation-defined rather than crosslink-order-independent.
3. What Fossil implements
manifest_crosslink() in src/manifest.c:
for(i=0; i<p->nTag; i++){
...
switch( p->aTag[i].zName[0] ){
case '-': type = 0; break;
case '+': type = 1; break;
case '*': type = 2; break;
}
tag_insert(&p->aTag[i].zName[1], type, p->aTag[i].zValue,
rid, p->rDate, tid);
}
Every card of the artifact goes to tag_insert() with the same mtime,
p->rDate, in the order the cards appear. The artifact format sorts T
cards by their full name token, sign included ([FossilArtifact] §4.7.16),
and * (0x2A) and + (0x2B) sort before - (0x2D). tag_insert() skips a
write when the existing row's mtime is greater than or equal to the
incoming one (§5.3 step 1).
Checked with Fossil 2.28 [52445a27f1]: commit c1 on trunk; commit c2 with
--branch feat; add a closed tag to c2; fossil branch new feat c2. The
new root's manifest carries
T *branch * feat
T *sym-feat *
T -sym-feat *
and its tagxref rows after crosslink, and again after fossil rebuild, are
| tag | tagtype | srcid |
|---|---|---|
branch |
2 (feat) |
the root |
sym-feat |
2 | the root |
The cancel left nothing behind. zit trunk, given the same repository
through import-fossil, lists branch feat and sym-feat as active on the
root.
4. Corrected text
§5.3 step 1, replace the sentence quoted in Section 2 with:
If two competing applications for the same (tag, artifact) pair carry exactly equal mtime, the >= skip rule makes the winner depend on write order. The tag cards of one artifact MUST be applied in the order they appear in the artifact, all with that artifact's mtime, so between two cards of one artifact the first in card order wins. Between applications from different artifacts with equal mtime the case is implementation-defined rather than crosslink-order-independent.
§6.2, replace the sentence quoted in Section 2 with:
If the parent itself carries a propagating sym-* tag of the new branch's own name, branch new emits both the propagating card and a cancel card for that name. The card order decides their combined effect (Section 5.3, step 1): the sign is part of the ordering key ([FossilArtifact], Section 4.7.16), so the * card precedes the - card, and the cancel meets the row the * card wrote with an equal mtime and is skipped. The root carries the propagating sym-* tag as if the cancel card were absent.
5. Observable consequence of the uncorrected text
An implementation that applies a cancel last regardless of card order, or
that treats the case as undefined and picks the cancel, leaves the root
without its own sym-NAME. Branch listings and name resolution for that
branch then differ from Fossil's for the same artifacts.
6. Implementations
zit already applies an artifact's tag cards in card order and matches Fossil. No change is needed.