~ivilata/gwit-spec

Set `GNUPGHOME` environment variable when Git verifies signatures.

To ensure that it accesses the client's GnuPG keyring.  Give it the
`<CLIENT-GPG-DIR>` pseudo-variable value used elsewhere.
Use less confusing example for gwit site branch name.

Which is now clearly the end of the `0xfed...ef76543210` example ID used
elsewhere, instead of the end of the other ID `0x012...effedcba98`, which
happened to end like the beginning of the first one, hence the possible
confusion.  The end of the first example ID does not clash with the beginning
nor the end of the second one.
Update project description and target sites.

As per the new definition of site history.
Add note on caching commit ancestry checks.

Since this now happens on URI retrieval, which may be potentially frequent
with more complex sites involving several requests, like HTML-based ones.
Remove note on caching verified commits.

Since verification now only happens on initial retrieval and update (less
frequent), and not on URI retrieval (potentially frequent, esp. with more
complex sites involving several requests, like HTML-based ones).
Redefine site history as ancestor commits of site branch head.

This breaking change allows commits in a non-site branch to become reachable
via a gwit site, e.g. by merging that branch into the site branch, without
requiring each of them to be signed by the site key.  For instance, merging
`main` would enable `gwit://<COMMIT-IN-MAIN>@<SITE-ID>/` (or even
`gwit://main@<SITE-ID>/` if supported by the client) to work.

This turns the site key into a kind of "certification key" for that branch
which may be handled by a third party.  For instance, I may "certify" Foo's
repository by creating a clone with a site branch where upstream `main` is
merged and published periodically, even if I have no relationship with Foo's
developer team.  And it applies to all commits in `main`, even the ones older
than the site itself.

This turns gwit into a hyperlinking system for generic Git repositories.
Minor rewordings and fixes.
Do not fail if named ref exists for shortened hash on URI retrieval.

Give the client the chance to just warn about its presence.  This is to avoid
a malicious remote breaking a particular URI using shortened hashes by
crafting tags with such hash names (as tags end up in `refs/tags`).

In combination with the support for arbitrary Git revisions in URIs, that
means that now it is possible to have (and use) tags and branches with only
hexadecimal digits in their name.  Some hints are provided for that purpose.
Fix check for signed tag name.

Since a Git revision like `tags/v1.23` may be used but the tag would only
contain the name `v1.23`, only the tag name in the revision must be checked,
not the whole revision string.

In example commands, that implies first getting the abbreviated object
name (as `git tag -l` only accepts those in the pattern).
Allow generic Git revisions in unsafe URI versions.

Since they are anyway considered unsafe, this approach avoids extra
restrictions and checks while not getting in the way of advanced uses for
authoring (like referring to a branch in a remote, or the commit before some
current head).
Move note about percent-encoding URI version further up.

So that it is clear that it applies to all the cases below.
Note Git repository hash type in permanent link example.

Since the given commit hash would be too short if the repository used SHA-256
hashes.
Allow URIs with tags signed by keys other than the site key.

Instead of resulting in URI retrieval failure.  However, consider such URIs as
unsafe, as happens with plain branches and unsigned tags.  This relaxation
aalows using non-gwit signed tags in the repo if desired,
Be more precise and consistent about full format of commit hashes.

Clarify that the precise format depends on which type of hashes is used by the
particular Git repository.
Clarify note on percent-encoded Git tag or branch names in URIs.
Make it more clear how to use the new site key on update.

To avoid suggesting that the whole key should be imported, when it should only
be used to update an existing key.
Less convoluted mention to `.gwit/self.key` in site retrieval.
Be more precise about origin commit of site configuration values.
More consistent wording for (most recent) site version.
Avoid the use of "version" when it may lead to confusion.

Also, use "Git" when introducing the use of "tag" or "branch" in the context
of Git.

This is all to clarify that "version" is a loose concept without a strict
mapping to Git.
Next