ref: 3fbfacabfffa430639f1d017b5bfd1210387dc1f sr.ht-docs/git.sr.ht/index.md -rw-r--r-- 5.8 KiB
3fbfacabDrew DeVault Update git.sr.ht custom README to API 2.0 8 months ago

#title: git.sr.ht docs

git.sr.ht is a service for hosting git repositories on sr.ht.

See also:

#New to git?

Learning how to use git in general is out of the scope of our documentation. Here are some good resources:

We do have some general resources for learning how to use git the sr.ht way:

#SSH host keys

git.sr.ht ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDZ+l/lvYmaeOAPeijHL8d4794Am0MOvmXPyvHTtrqvgmvCJB8pen/qkQX2S1fgl9VkMGSNxbp7NF7HmKgs5ajTGV9mB5A5zq+161lcp5+f1qmn3Dp1MWKp/AzejWXKW+dwPBd3kkudDBA1fa3uK6g1gK5nLw3qcuv/V4emX9zv3P2ZNlq9XRvBxGY2KzaCyCXVkL48RVTTJJnYbVdRuq8/jQkDRA8lHvGvKI+jqnljmZi2aIrK9OGT2gkCtfyTw2GvNDV6aZ0bEza7nDLU/I+xmByAOO79R1Uk4EYCvSc1WXDZqhiuO2sZRmVxa0pQSBDn1DB3rpvqPYW+UvKB3SOz
git.sr.ht ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCj6y+cJlqK3BHZRLZuM+KP2zGPrh4H66DacfliU1E2DHAd1GGwF4g1jwu3L8gOZUTIvUptqWTkmglpYhFp4Iy4=
git.sr.ht ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMZvRd4EtM7R+IHVMWmDkVU3VLQTSwQDSAvW0t2Tkj60

#Acceptable resource usage

The guidelines on resource usage are somewhat flexible. Here are some tips:

  • As an approximation, aim to have repos no larger than the Linux kernel git repo, which is 3.5 GiB.
  • Don't store lots of large binary objects in your repository, such as images, audio, or video. A couple of small binary files (such as your logo or a screenshot) is fine.

If in doubt, you're probably fine. We monitor resource usage and we'll send you a friendly email if we notice that you're using too much.

#git.sr.ht manual

The following sections document various features of git.sr.ht.

#Attaching files to releases

git.sr.ht allows you to attach files, such as executables (aka binaries), PGP signatures, and so on, to annotated tags. To create an annotated tag, run the following git command:

git tag -a <tag name>

For example, git tag -a 2.3.4 to tag version 2.3.4. Your text editor will open, and you'll be prompted to annotate the tag - fill this in with release notes, a changelog, etc. Consider using git-shortlog to generate your changelog.

Save and close your editor, then use git push --tags to publish the new tag or use git push --follow-tags to push any local commits to the current branch, along with the new tag (this can be made the default behavior by running git config --global push.followTags true). The new tag will appear on the "refs" page of your repository. To attach files to it, click the tag name (e.g. "2.3.4") and use the upload form on this page.

#Push Options

git.sr.ht supports some git push options, which can be specified with -o option or -o option=value.

  • debug: prints the UUID assigned to your git push. You may be asked to provide this when troubleshooting push issues.
  • skip-ci: skips submitting builds.sr.ht jobs for this push.
  • submit: overrides the default comma-separated fnmatch(3) pattern for build manifests to submit (.build.yml,.builds/*.yml).
  • description: set the repository's description.
  • visibility: set the repository's visibility (public, unlisted, or private).

All of your push options, including ones not recognized by git.sr.ht itself, are forwarded to any webhooks you have configured for your repository.

To set any of these options permanently for a specific git repository, use the following command:

git config --add push.pushOption submit=".sourcehut/*.yml"

#Changing the default branch

If you wish to change your default branch, visit the settings tab of your repository. To rename your default branch, use something like the following:

git branch -m master main
git push origin :master main:main

#Setting a custom README

By default, if found, a README plaintext or README.md markdown file will be rendered as the repository's README.

However, you can use an arbitrary HTML snippet as your README instead by using the GraphQL API. First, generate a personal access token. You'll then need to fetch the repository ID:

# Replace the following with your personal access token:

# And this with your repository name:

curl --oauth2-bearer $bearer_token \
  -G --data-urlencode query='query { repositoryByName(name: "'$repo_name'") { id } }' \

Your repo ID never changes, so it's safe to write it down in a script. You can then use the following to set the README for your repository:

# And replace this with your repository ID:

# And the readme file:

jq -R '{
    "query": "mutation UpdateRepo($id: Int!, $readme: String!) {
      updateRepository(id: 60, input: { readme: $readme }) { id }
    }", "variables": {
      "id": '$repo_id',
      "readme": .
    } }' < $readme \
  | curl --oauth2-bearer $bearer_token \
    -H "Content-Type: application/json"
    -d@- https://git.sr.ht/query

It may be desirable to configure a builds.sr.ht job to compile your README from another markup format and submit it on each git push. If so, you will need to review the build secrets tutorial to safely store your OAuth token. Check out the example to avoid some common pitfalls.