aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThorben Günther <admin@xenrox.net>2023-10-30 17:30:53 +0100
committerDrew DeVault <sir@cmpwn.com>2023-10-31 08:10:35 +0100
commit27e9e59f8f68482e717f45e4536a20f572b6f6c9 (patch)
treee75e116b319f16137941448c1d6617160ee1a037
parent67c1822bca2462c56852ada9e0ff21a546088ee2 (diff)
downloadsr.ht-docs-27e9e59f8f68482e717f45e4536a20f572b6f6c9.tar.gz
git.sr.ht: Recommend hut(1) to set custom README
-rw-r--r--git.sr.ht/index.md73
1 files changed, 8 insertions, 65 deletions
diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index e69280e..db6f22d 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -359,80 +359,23 @@ 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:
+the [GraphQL API](https://man.sr.ht/graphql.md).
-```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 { me { repository(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:
+[hut] can easily do this:
```
-mutation UpdateRepo($id: Int!, $readme: String!) {
- updateRepository(id: $id, input: { readme: $readme }) { id }
-}
+hut git update --readme readme.html --repo https://git.sr.ht/~foo/bar
```
-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:
+Or if you want to remove the custom README:
```
-{
- "query": "the desired GraphQL query...",
- "variables": {
- "id": 1337,
- "readme": "your README HTML..."
- }
-}
+hut git update --readme "" --repo https://git.sr.ht/~foo/bar
```
-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.
+another markup format and submit it on each git push.
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
+[readme example]: https://git.xenrox.net/~xenrox/custom-readme
+[hut]: https://sr.ht/~emersion/hut/