---
title: git.sr.ht annotations reference
---

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](https://git.sr.ht/~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](https://man.sr.ht/tutorials/getting-started-with-builds.md), and find an
annotation generator for your project's programming language(s):

- C: [annotatec](https://git.sr.ht/~sircmpwn/annotatec)
- Go: [annotatego](https://git.sr.ht/~sircmpwn/annotatego)
- POSIX shell: [annotatesh](https://git.sr.ht/~emersion/annotatesh)
- Python: [annotatepy](https://git.sr.ht/~ihabunek/annotatepy)
- Rust: [annotate-rust](https://git.sr.ht/~wezm/annotate-rust)

If your language isn't listed here, see [writing custom
annotators](#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](https://meta.sr.ht/oauth) and generate a personal access token, then
paste the generated token into [builds.sr.ht
secrets](https://builds.sr.ht/secrets) like this:

```sh
#!/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)`](https://git-scm.com/docs/git-ls-tree) 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.

```json
{
  "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.

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

## Full example

Here is a complete example of a valid annotations JSON:

```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"
    }
  ]
}
```