1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
---
title: git.sr.ht docs
---
[git.sr.ht](https://git.sr.ht) is a service for hosting git repositories on
sr.ht.
**See also**:
- [GraphQL reference](graphql.md)
- [Legacy API reference](api.md)
- [Installation guide](installation.md)
# New to git?
Learning how to use git in general is out of the scope of our documentation.
Here are some good resources:
- [The official Git book](https://git-scm.com/book/en/v2)
- [Git man pages](https://git-scm.com/docs)
We do have some general resources for learning how to use git the sr.ht way:
- [Using git-send-email for sending and reviewing patches on sr.ht](../git.sr.ht/send-email.md)
- [Code review with lists.sr.ht](../lists.sr.ht/code-review.md)
# 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`](https://git-scm.com/docs/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)`](https://manpages.debian.org/buster/manpages-dev/fnmatch.3.en.html)
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](https://man.sr.ht/graphql.md). First, [generate
a personal access token](https://meta.sr.ht/oauth2/personal-token). You'll then
need to fetch the repository ID:
```sh
# 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:
```sh
# 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](https://stedolan.github.io/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](https://man.sr.ht/graphql.md#performing-graphql-queries) to
the git.sr.ht GraphQL endpoint at `git.sr.ht/graphql`, which is piped from jq
into [curl](https://curl.se) 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][secrets] to safely store your OAuth token.
Check out the [example][readme 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 } }
```
[secrets]: https://man.sr.ht/tutorials/builds.sr.ht/using-build-secrets.md
[readme example]: https://git.sr.ht/~nabijaczleweli/html-readme
|
