git.sr.ht annotations reference

Table of Contents

This commit

commit 3f0e4882444362cf0f87d0a1aec9d5c376b8e08d
Author: Drew DeVault <sir@cmpwn.com>
Date:   2019-07-11T21:01:54

Correct list of supported characters in tags
Clone this wiki
man@man.sr.ht:root
https://man.sr.ht/root

Annotations are a feature of git.sr.ht which allows you to upload arbitrary annotations to files in your source code, which will then be shown on the web. An example repo with annotations configured is ~sircmpwn/scdoc, where they are used to link C function calls to their definitions.

To add annotations to your repo, you'll need to have a builds.sr.ht set up, and find an annotation generator for your project's programming language(s):

If your language isn't listed here, see writing custom annotators.

See each annotator's instructions for generating the annotation file. You'll then need to add an OAuth token to builds.sr.ht - go to your oauth settings and generate a personal access token, then paste the generated token into builds.sr.ht secrets like this:

#!/bin/sh
oauth_token=# your oauth token here
curl -X PUT \
    -H "Authorization: token $oauth_token" \
    -H "Content-Type: application/json" \
    -d @"$1" \
    https://git.sr.ht/api/"~$2"/repos/"$3"/annotate

Set the path to ~/upload-annotations and the file mode to 755, then add the UUID to the secrets list in your build manifest. Call the annotator to generate annotations for your code, then use the secret script to upload them. The result will look something like this:

# ...
secrets:
- your-uuid-here
tasks:
# ...
- annotate: |
    cd your-project
    find . -name "*.c" | xargs annotatec -g > annotations.json
    ../upload-annotations annotations.json your-username your-reponame

Writing custom annotators

The annotations.json format is a mapping of blob IDs to annotations. The blob ID is the ID of the blob which the annotations supplement, you can find it for a given file like so:

git ls-tree HEAD path/to/file.c

When writing an annotator, you may find it useful to add the -r flag to scan the entire git tree at once, and -z to make the output more easily machine readable. See git-ls-tree(1) for details on this command.

Once you have the blob ID, you can specify a list of annotations. Each annotation must have a type, which can be one of the following:

type: link

This annotates your code with a link, either an external link or a link to another part of your source code.

{
  "type": "link",
  "lineno": integer,
  "colno": integer,
  "len": integer,
  "to": "url...",
  "title": "anchor title attribute", (optional)
  "color": "background color (#RRGGBB or 'transparent')" (optional)
}

If to is a relative URL, it will be assumed to be a link to another part of this repository's source tree. Otherwise it's used-as is, for example as a link to some external documentation.

type: markdown

A markdown annotation adds an expandable annotation to the end of the annotated line, which when clicked, shows an arbitrary markdown snippet.

{
  "type": "markdown",
  "lineno": integer,
  "title": "title of the annotation",
  "content": "markdown text..."
}

Full example

Here is a complete example of a valid annotations JSON:

{
  "98bc0394a2f15171fb113acb5a9286a7454f22e7": [
    {
      "type": "markdown",
      "lineno": 33,
      "title": "2 references",
      "content": "- [../main.c:123](https://example.org)\n- [../main.c:321](https://example.org)"
    },
    {
      "type": "link",
      "lineno": 38,
      "colno": 7,
      "len": 15,
      "to": "#L6"
    },
    {
      "type": "link",
      "lineno": 34,
      "colno": 13,
      "len": 11,
      "to": "src/utf8_encode.c#L5"
    },
    {
      "type": "link",
      "lineno": 41,
      "colno": 2,
      "len": 11,
      "to": "src/utf8_encode.c#L5"
    }
  ]
}