Module caps 

Capabilities, and the table that keeps the advertisement honest.

The bug this module exists to make impossible

A protocol-v2 client will not send an argument unless the corresponding feature appears in the value of the capability it belongs to. A server that parses filter <spec> but advertises fetch=shallow wait-for-done has partial-clone support that can never activate. Worse, it looks exactly like working code: no error is raised, no test fails, the client simply never exercises the path. Stock git 2.53 does this deliberately (uploadpack.allowFilter defaults off), which is why the shape is easy to copy by accident.

So the advertisement is not written down anywhere. There is one table (FETCH_ARGUMENTS, LS_REFS_ARGUMENTS) that says, per argument, which feature gates it, and both the parser and the advertisement are derived from it. Adding an argument to the parser without advertising its feature is not something you can forget to do; it is something you cannot express. That is a fix by construction rather than a guard watching two copies agree (one implementation), and tests/advertisement.rs still asserts the resulting invariant from the outside, red-first.

The other bug, which the paragraph above did NOT prevent

That paragraph was true of the v2 arguments and of nothing else, and it was read as covering everything — an early audit said outright that “advertised but not honoured is not something this codebase can express”. It was expressible in three other places, and it was expressed:

• upload_pack_v0_capabilities was a hand-written vec![],
• receive_pack_capabilities was a second one, and
• the v2 capability names were a third, in upload_pack.rs.

"push-options".to_owned() sat in the second of those. It was advertised, receive_pack::ReceivePack::serve parsed the section, and the only consumer anywhere in the tree was .len() in a log field. A client that ran git push -o ci.skip was told on the wire that the server speaks push options and the option went nowhere — a wrong answer on the wire, not a missing feature.

ADVERTISED closes it the same way: one place decides what is advertised, for all three surfaces, every row carries a Honoured saying where it is honoured, and tests/advertisement.rs checks each claim against the source with comments stripped — because contains("push-options") is satisfied by the paragraph explaining push-options two lines above the call site.

Structs

Argument

One argument a protocol-v2 command accepts.

Capability

One capability gunnar advertises, and the thing that honours it.

Offered

What a client may turn off in the fetch capability.

PeerCapabilities

The capability set a v0 peer sent on its first line, parsed.

Policy

One field of a serving-side configuration struct, and its verdict.

PolicySurface

A struct whose fields are serving-side policy, with a verdict on every one.

Enums

CapValue

What follows a capability’s name on the wire.

Declared

How a serving-side policy reaches the peer.

Honoured

Where the code that honours a capability lives.

Value

Whether an argument carries a value after its name.

Constants

ADVERTISED

Every surface, so a guard can walk all of them without naming three constants and going stale when a fourth appears.

FETCH_ARGUMENTS

Every argument command=fetch accepts.

LS_REFS_ARGUMENTS

Every argument command=ls-refs accepts.

PRODUCT

The product half of the agent= capability.

RECEIVE_PACK

Every capability git-receive-pack advertises. Push has only v0.

SERVER_POLICIES

Every configuration surface that decides what a peer gets.

UPLOAD_PACK_V0

Every capability git-upload-pack advertises in protocol v0.

UPLOAD_PACK_V2

Every capability the protocol v2 advertisement carries.

Functions

advertise

The wire lines for a whole surface, in table order.

argument

Look an argument up by name.

capability

Render name=<features> for a v2 capability, or bare name when the command has no gated arguments at all.

check_object_format

Check a peer’s object-format against the repository’s actual hash kind.

default_agent

The agent= value gunnar advertises: gunnar/<crate version>.

features

The features of table, in first-seen order and without duplicates.

fetch_capability

The fetch=… capability line for what is on offer.

ls_refs_capability

The ls-refs=… capability line.

object_format_from_name

The inverse of object_format_name.

object_format_name

git’s name for a hash algorithm, as it appears in object-format=.

receive_pack_capabilities

The capabilities git-receive-pack advertises.

render

Render one capability’s wire spelling, or None if it is not on offer.

upload_pack_v0_capabilities

The capabilities git-upload-pack advertises in protocol v0, where they ride on the first reference line rather than in their own section.