~ivilata/gwit-spec

State mapping of locations with Git remotes & URLs as basic concept.

Otherwise it is introduced too late (initial retrieval) and dispersed among
several places.  Besides making the concept more relevant, this also allows
refactoring some redundant sentences here and there (or at least get to them
with a little more context).
Mention length of short PGP ID as a number.

For readability.
Mention the usual representation of a PGP key fingerprint (site ID).

Inspired by a message from Matograine to the gwit-spec list.
Add "then" when it helps with readability.
Be more explicit about resolving index files across symbolic links.
Make instructions not specific to direct repository access.

Implementations may not use direct repository access as the examples in the
specification; for instance, they may use working trees.  Still, some
instructions were quite specific to the former style.  They should be more
neutral now (even if examples continue to use direct access).

Motivated by a discussion with Mitra Ardron.
Make URI retrieval fail if site config file exists & fails to parse.

Not finding the file should be ok (empty configuration), but a bad
configuration should not be discarded silently, otherwise a commit breaking
the configuration file would result in e.g. clients silently changing the root
directory to the top directory on URI retrieval.
Clients retrieving gwit URIs must parse site configuration files.

Otherwise, a URI in a site with a configured root (different than the top
directory) may end up resolving to different repository paths depending on
whether the client supports site configuration files or not, with no errors.

A client not supporting config files may still work fine with a site with no
such file, but as soon as it had that file, even if it did not contain a root
value, the client would be uncertain about the site's root and URI retrieval
should then fail.

Requiring support for the config files for URI retrieval looks like the most
consistent and least surprising way to go.
Well-Known URIs: clarify to which protocol belong URI and site root.

Especially, try to avoid suggesting that `.well-known/gwit.ini` should be
placed under the root of the gwit site (unless it is the same as the root used
by the other protocol, of course).
Make references to the ban of hex tag/branch names more consistent.

And introduce it when mentioning versions in URIs.
Enhance description of tag or branch versions in URIs.
Swap and enhance descriptions of empty and hash versions in URIs.
Mention "forced Git push" when discussing site history rewrites.
Fix mention to site introductions as supporting just one location.
Minor corrections and enhancements for readability.
Correct mentions to INI "sections" which are actually subsections.

Especially for the `[site "<ID>"]` subsection of site configuration.
Also take into account Git SHA-256 hashes.

Since Git is transitioning to these more secure hashes (see
<https://git-scm.com/docs/hash-function-transition>).

There is an attack scenario where a 40 hex digits string is used as the
`<VERSION>` field in a gwit URI for a repo using SHA-256; since the string
looks like a full hash, a client may take it as a commit name instead of a
prefix (shortened hash), and it may proceed to signature verification with
that string without checking for malicious branches or tags.

Fortunately, if the implementation follows the recommendations in "Security
considerations", such a branch or tag should have been removed anyway after
fetching new Git objects, thus foiling the attack.
Be more clear about the Well-Known URI file path in the repository.
Access via other protocols to the Well-Known URI is not "legacy".

It is just another protocol, so avoid the negative-sounding term.
Note relevant information in Well-Known URI file.

With an example command for retrieving site remotes.
Next