is a service for hosting git repositories on

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 way:

SSH host keys

If you are cloning via ssh, these lines should be added to ~/.ssh/known_hosts. ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDZ+l/lvYmaeOAPeijHL8d4794Am0MOvmXPyvHTtrqvgmvCJB8pen/qkQX2S1fgl9VkMGSNxbp7NF7HmKgs5ajTGV9mB5A5zq+161lcp5+f1qmn3Dp1MWKp/AzejWXKW+dwPBd3kkudDBA1fa3uK6g1gK5nLw3qcuv/V4emX9zv3P2ZNlq9XRvBxGY2KzaCyCXVkL48RVTTJJnYbVdRuq8/jQkDRA8lHvGvKI+jqnljmZi2aIrK9OGT2gkCtfyTw2GvNDV6aZ0bEza7nDLU/I+xmByAOO79R1Uk4EYCvSc1WXDZqhiuO2sZRmVxa0pQSBDn1DB3rpvqPYW+UvKB3SOz ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCj6y+cJlqK3BHZRLZuM+KP2zGPrh4H66DacfliU1E2DHAd1GGwF4g1jwu3L8gOZUTIvUptqWTkmglpYhFp4Iy4= 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.

Sending patches upstream 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 that 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.

Heads 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.
Heads up: we also have a video demonstrating this procedure if you would prefer to watch that.
1. Getting the source onto

If the project is already on, look for the large blue "Clone repo to your account" button to add a copy of it to your repos. If the project is hosted elsewhere, clone the upstream source code and add it to 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 repository.

2. Preparing the patchset

On the 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 setting 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 this 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 etiquette guide to avoid any faux pas!

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, 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.

Referencing tickets in git commit messages

If your source repository is linked to a project, you may interact with tickets via specific git commit trailers. The trailer values must be valid URLs to tickets. Any other value will be ignored. A comment will be inserted in the referenced tickets with a back-link to the git commit and its original author.

For example, the following commit message:

build: work around gcc 4.2 bug

Fix build with ancient gcc.

Signed-off-by: John Doe <>

Will cause the following change on the referenced issue:

~arkanoid UNRESOLVED -> FIXED 9 seconds ago

John Doe referenced this ticket with commit badcaca0.

Note: The user pushing the commit must have comment and triage access to the bug tracker, otherwise the trailers will be ignored. The commit author is only used in the inserted comment.
Attention: Only the last 25 commits will be considered when pushing large series. Any referenced issue in a commit preceding the last 25 will be ignored. If you really need to push more than 25 commits for a single feature, do it in multiple pushes.

The following trailers are supported:


If the ticket is unresolved, it will be resolved with the FIXED resolution. If it is already resolved, only a comment will be inserted.


build: work around gcc 4.2 bug

Fix build with ancient gcc.

Signed-off-by: John Doe <>

If the ticket is unresolved, it will be resolved with the IMPLEMENTED resolution. If it is already resolved, only a comment will be inserted.


foo: add support for yaml config files

Signed-off-by: John Doe <>

The ticket status will not be changed, only a comment will be inserted.


foo: add missing docs for yaml config

Signed-off-by: John Doe <>

If the ticket is unresolved, it will be resolved with the neutral CLOSED resolution. If it is already resolved, only a comment will be inserted.

Attaching files to releases 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.

Signing tags' tarballs

In addition to serving tarballs for tags, may also serve PGP signatures for those tarballs with .asc appended.

This is done by storing the signatures as notes in the refs/notes/signatures/tar{,.gz} namespaces.

As an example, the following shell program will sign the given tags in the given format:

[ $# -lt 1 ] && { echo "usage: $0 tar|tar.gz tag..." >&2; exit 1; }
fmt=$1; shift
repo=$(git remote get-url origin)
for tag; do
  git -c tar.tar.gz.command='gzip -n' archive --format "$fmt" --prefix "${repo##*/}-$tag/" "$tag" |
    gpg --detach-sign -a |
    git notes --ref refs/notes/signatures/"$fmt" add -F- "$tag"
git push origin refs/notes/signatures/"$fmt"

Be 'ware of compressor variance: you must compress with gzip -n! If signatures for both tar and tar.gz are set, tar wins.

Push Options 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 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 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


You may create a README file for your repository which will be displayed on the repo summary page, and on a project hub project if you list your project there. The following file names are accepted:

  • README.markdown

The latter two options are rendered as markdown. You may use other formats by preparing a custom readme, see the next section for details.

You are also encouraged to add a LICENSE file which details the use and distribution terms of your software. The following names are accepted:


If your project has more than one license, your license file should explain what licenses apply to what parts of the code in plain English, and include the text of all applicable licenses.

For cases like this, the web UI supports version 3.0 of the REUSE Specfication:

If you include your licences as files matching the pattern LICENSES/$SPDX.$suffix, where $SPDX is the SPDX identifier for the licence and $suffix is any string without a dot, the licences will be enumerated in the repo summary and /licenses pages, alongside a short description and links to their corresponding entries on

Setting a custom README

By default, if found, a README plaintext or 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.

hut can easily do this:

hut git update --readme readme.html --repo

Or if you want to remove the custom README:

hut git update --readme "" --repo

It may be desirable to configure a job to compile your README from another markup format and submit it on each git push. Check out the example to avoid some common pitfalls.

About this wiki

commit a290ce243e74f89fc35cd4e3467a580edbc35399
Author: Drew DeVault <>
Date:   2024-05-27T14:24:11+02:00 add link to joinup chooser
Clone this wiki (read-only) (read/write)