~sircmpwn/sr.ht-docs

ref: 07eeaf7c5fa479c31637b125138f7ca6b7788e8c sr.ht-docs/git.sr.ht/index.md -rw-r--r-- 11.0 KiB
07eeaf7cDrew DeVault git.sr.ht: update git send-email note 3 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.

#Sending patches upstream

git.sr.ht provides a web-based patch preparation UI, which you can use to prepare changes to send upstream online. You can even use this to prepare patches for projects which use email for submission, but are not hosted on SourceHut. This tool may be helpful to users who are used to the "pull request" style contribution popularized by GitHub, GitLab, and others.

Head's up: git also has a built-in CLI tool for preparing patches to send upstream. Check out our tutorial here if you prefer to work from the command line.

#1. Getting the source onto git.sr.ht

If the project is already on git.sr.ht, look for the large blue "Clone repo to your account" button to add a copy of it to your git.sr.ht repos. If the project is hosted elsewhere, clone the upstream source code and add it to git.sr.ht like any other repository.

Write your changes locally with your normal workflow. We recommend studying git rebase as well, because many projects which use the email-based workflow may expect you to be proficient with it. When you've completed your work, push it to your git.sr.ht repository.

#2. Preparing the patchset

On the git.sr.ht website, visit your repository's summary page, and the large blue button is replaced with "Prepare a patchset". Click this to start up the patchset editor.

On the first page, you'll select the oldest commit to include in the patchset. Click "Continue" to select the newest commit to include — the default is probably correct. On this second page, you can add some notes to the patchset. Here's an explanation of the options:

Add a cover letter

A cover letter is added ahead of your patchset. It includes a brief auto-generated summary of the changes, and gives you an opportunity to add any notes or set a subject line for the whole patchset. If you're coming from GitHub, think of this as settting the pull request title and description.

Add commentary

For each commit that you include, you have a space to add some notes specific to that commit. The notes you add here supplement the commit message with additional details which are useful for the reviewer, but shouldn't be immortalized in the commit log.

Patchset revision

After you receive feedback (see below), you'll want to update ths number to reflect how many revisions you've sent upstream. You can leave this at "1" for the first submission.

#3. Sending it upstream

After reviewing all of the details, click "Continue" to proceed to the final step. You'll have to figure out who the emails should be sent to before completing this step. Most projects have a mailing list address listed in their contributor documentation — find that and stick it in the "To" box. You might also want to use tools like git blame to find other people who have recently worked in relevant parts of the code, and add them to the "Cc" field.

Have one more quick look over the emails that have been prepared for you (you can press "back" in your browser to revise any mistakes), then hit "Send patchset" to send your work to the email addresses you've listed. You're done!

#4. How to deal with feedback

When the reviewers look over your work, they may have some comments for things that you should change or clarify. Comments will arrive at your email address, and you can simply reply to them to answer their questions or provide follow-up questions of your own. Please double check our email ettiquite guide to avoid any faux paus!

To incorporate their feedback, you'll want to edit the commits in your git repository. Note that you need to edit your commits — you can't just add new commits which fix the issues introduced by earlier commits. Check out our git rebase guide if you're not comfortable with this workflow. Once you're satisfied with your changes, use git push -f to push the new commits up to your repository on git.sr.ht, and follow this procedure again to send the new version. Update the patchset revision field on step two when you get there — set it to the number of patchset versions you've sent so far.

#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:
bearer_token=xrAV8VvqzChACiu+kR7kDdoPl0RcpkQJNplJCHeQ6Tw169H8C4WXIM9m

# And this with your repository name:
repo_name=example

curl --oauth2-bearer $bearer_token \
  -G --data-urlencode query='query { repositoryByName(name: "'$repo_name'") { id } }' \
  https://git.sr.ht/query

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:
repo_id=1337

# And the readme file:
readme=README.html

jq -sR '{
    "query": "mutation UpdateRepo($id: Int!, $readme: String!) {
      updateRepository(id: $id, 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

This looks a bit complicated, so to explain what's happening here: we want to execute the following GraphQL request:

mutation UpdateRepo($id: Int!, $readme: String!) {
  updateRepository(id: $id, input: { readme: $readme }) { id }
}

The jq command takes the input (your README file) and incorporates it into a JSON string with the following format:

{
  "query": "the desired GraphQL query...",
  "variables": {
    "id": 1337,
    "readme": "your README HTML..."
  }
}

This is the input to the git.sr.ht GraphQL endpoint at git.sr.ht/graphql, which is piped from jq into curl to send the request to git.sr.ht.

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.

If you want to remove the custom README, set the readme to null.

mutation { updateRepository (id: <repo_id>, input: { readme: null }) { id } }