add tutorial for setting up public git repos on tilde.team
This commit is contained in:
parent
b89d2e3d52
commit
a2a6a936dc
|
@ -0,0 +1,312 @@
|
||||||
|
---
|
||||||
|
author: ~kst
|
||||||
|
published: true
|
||||||
|
title: hosting public git repos
|
||||||
|
description: hosting public git repos on tilde.team
|
||||||
|
category:
|
||||||
|
- main
|
||||||
|
---
|
||||||
|
|
||||||
|
hosting public git repos
|
||||||
|
========================
|
||||||
|
|
||||||
|
Besides the [Gitea instance][1] of tildeverse, you could easily setup a
|
||||||
|
read-only clone URL fetchable using git clone similar to this one:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git clone https://tilde.team/~kst/grm.tilde.git
|
||||||
|
```
|
||||||
|
|
||||||
|
tl;dr
|
||||||
|
-----
|
||||||
|
|
||||||
|
If you are not interested in the details, you could use a minimal front end
|
||||||
|
called [git repo manager][2]. It should take care of all the details for you.
|
||||||
|
|
||||||
|
creating a repo
|
||||||
|
---------------
|
||||||
|
|
||||||
|
On tilde.team, the structure of `~name/public_html/<path>` is mapped to
|
||||||
|
`https://tilde.team/~name/<path>` so anything inside the `~name/public_html`
|
||||||
|
directory is publicly accessible. If you want to create a publicly accessible
|
||||||
|
git repository, all you need to do is to create a [bare repository][3] inside
|
||||||
|
`~name/public_html`:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cd ~/public_html
|
||||||
|
$ git init --bare my_repo.git
|
||||||
|
Initialized empty Git repository in /home/name/public_html/my_repo.git/
|
||||||
|
```
|
||||||
|
|
||||||
|
The `.git` suffix is a convention for bare repositories. If you have used GitHub,
|
||||||
|
GitLab, or Gitea before, you should have noticed that the clone URLs all have
|
||||||
|
the `.git` suffix.
|
||||||
|
|
||||||
|
After you have created the bare repository for your project, the URL
|
||||||
|
|
||||||
|
```
|
||||||
|
https://tilde.team/~name/my_repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
is not ready for clone yet. Because we are serving the repository using GET
|
||||||
|
requests, or what git internally called the ["dumb" HTTP protocol][4], git needs
|
||||||
|
some extra info files for cloning the repository. They can be generated by
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cd ~/public_html/my_repo.git
|
||||||
|
$ git update-server-info
|
||||||
|
```
|
||||||
|
|
||||||
|
Now you should be able to clone the repository using
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git clone https://tilde.team/~name/my_repo.git
|
||||||
|
Cloning into 'my_repo'...
|
||||||
|
warning: You appear to have cloned an empty repository.
|
||||||
|
```
|
||||||
|
|
||||||
|
The
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git update-server-info
|
||||||
|
```
|
||||||
|
|
||||||
|
command needs to be run after every update to the repository. This could be
|
||||||
|
automated using the post-update [git hook][5]. Since the sample post-update hook
|
||||||
|
in
|
||||||
|
|
||||||
|
```
|
||||||
|
~/public_html/my_repo.git/hooks
|
||||||
|
```
|
||||||
|
|
||||||
|
already contains this command, we simply rename the sample hook
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cd ~/public_html/my_repo.git
|
||||||
|
$ mv hooks/post-update.sample hooks/post-update
|
||||||
|
```
|
||||||
|
|
||||||
|
so that git will run this script after every update.
|
||||||
|
|
||||||
|
push via ssh
|
||||||
|
------------
|
||||||
|
|
||||||
|
Note that the HTTP clone URL is *read-only*, so you can't push anything using
|
||||||
|
this URL. Normally you would need to set up the ["smart" protocol][4] for
|
||||||
|
authentication, but since we are using SSH already, we could use a remote path
|
||||||
|
of the form `name@host:path`, similar to the arguments of scp, as the git
|
||||||
|
remote url, so you could use
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git clone name@tilde.team:~/public_html/my_repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
to clone the repository on your local machine, or
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git clone ~/public_html/my_repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
if you want to work on the server directly. If you have already made some
|
||||||
|
changes to the local repo, use
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git remote set-url origin <url>
|
||||||
|
```
|
||||||
|
|
||||||
|
to update the remote URL. Now you should be able to push to your remote repo
|
||||||
|
using
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git push
|
||||||
|
```
|
||||||
|
|
||||||
|
if you have a correct SSH keypair setup.
|
||||||
|
|
||||||
|
web front end
|
||||||
|
------------
|
||||||
|
|
||||||
|
Now that we have already figured out the push and clone access of our
|
||||||
|
repository. You could call it an end here, but one of the most important
|
||||||
|
features of git hosting services is a web interface so that people could browse
|
||||||
|
and discuss the source code without cloning it.
|
||||||
|
|
||||||
|
For this, we could use [stagit][6], which is a tool for generating static HTML
|
||||||
|
pages from a git repository. The generated web pages are even browsable using
|
||||||
|
terminal browsers such as elinks, w3m, and lynx. For example, try
|
||||||
|
|
||||||
|
```
|
||||||
|
$ lynx https://tilde.team/~kst/git/grm.tilde/file/TUTORIAL.html
|
||||||
|
```
|
||||||
|
|
||||||
|
Since tilde.team already have libgit2 installed, simply clone the repo and
|
||||||
|
build it:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git clone git://git.codemadness.org/stagit
|
||||||
|
$ cd stagit
|
||||||
|
$ make
|
||||||
|
$ cp stagit stagit-index ~/bin/
|
||||||
|
```
|
||||||
|
|
||||||
|
Here, we will assume that the index page of stagit, which lists all the repos
|
||||||
|
you have, is
|
||||||
|
|
||||||
|
```
|
||||||
|
https://tilde.team/~name/git/
|
||||||
|
```
|
||||||
|
|
||||||
|
and the index page of each repository is
|
||||||
|
|
||||||
|
```
|
||||||
|
https://tilde.team/~name/git/my_repo
|
||||||
|
```
|
||||||
|
|
||||||
|
To build the HTML pages for `my_repo`, we first make the corresponding directory
|
||||||
|
|
||||||
|
```
|
||||||
|
$ mkdir -p ~/public_html/git/my_repo
|
||||||
|
$ cd ~/public_html/git/my_repo
|
||||||
|
```
|
||||||
|
|
||||||
|
and add some metadata to your bare git repo
|
||||||
|
|
||||||
|
```
|
||||||
|
$ echo 'a cool project' > ~/public_html/my_repo.git/description
|
||||||
|
$ echo 'https://tilde.team/~name/my_repo.git' > ~/public_html/my_repo.git/url
|
||||||
|
$ echo 'name' > ~/public_html/my_repo.git/owner
|
||||||
|
```
|
||||||
|
|
||||||
|
then run
|
||||||
|
|
||||||
|
```
|
||||||
|
$ stagit ~/public_html/my_repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
to generate HTML files in the current directory. You could link `index.html` to
|
||||||
|
`log.html`
|
||||||
|
|
||||||
|
```
|
||||||
|
$ ln -sf log.html index.html
|
||||||
|
```
|
||||||
|
|
||||||
|
so that the URL
|
||||||
|
|
||||||
|
```
|
||||||
|
https://tilde.team/~name/git/my_repo
|
||||||
|
```
|
||||||
|
|
||||||
|
is pointed to the commit log page.
|
||||||
|
|
||||||
|
To generate the repository index, go back to
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cd ~/public_html/git/
|
||||||
|
```
|
||||||
|
|
||||||
|
and run
|
||||||
|
|
||||||
|
```
|
||||||
|
$ stagit-index ~/public_html/my_repo.git > index.html
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that the output will be empty if `my_repo` has no commits. In general, use
|
||||||
|
|
||||||
|
```
|
||||||
|
$ stagit-index repo_dir1 repo_dir2 ... > index.html
|
||||||
|
```
|
||||||
|
|
||||||
|
to generate index for multiple repositories. You should also copy over or
|
||||||
|
symlink some of the assets files in stagit's repository, such as `style.css`,
|
||||||
|
`logo.png`, etc. to
|
||||||
|
|
||||||
|
```
|
||||||
|
~/public_html/git/
|
||||||
|
```
|
||||||
|
|
||||||
|
and
|
||||||
|
|
||||||
|
```
|
||||||
|
~/public_html/git/my_repo/
|
||||||
|
```
|
||||||
|
|
||||||
|
you could also modify the source code of stagit to use a common location for
|
||||||
|
the assets.
|
||||||
|
|
||||||
|
Because the web pages generated by stagit is static, you need to run `stagit`
|
||||||
|
and `stagit-index` after each push operation to your repository in order to
|
||||||
|
update the HTML files. This process can be easily automated using a
|
||||||
|
`post-receive` hook. An example of the `post-receive` hook can be found
|
||||||
|
[here][8]. To install it:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cd ~/public_html/my_repo.git/hooks
|
||||||
|
$ curl -o stagit-post-receive https://tilde.team/~kst/bin/stagit-post-receive
|
||||||
|
$ chmod +x stagit-post-receive
|
||||||
|
```
|
||||||
|
|
||||||
|
Now you should see something like this when you do a git push
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git push
|
||||||
|
...
|
||||||
|
remote: [my_repo] stagit HTML pages... done!
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
a minimal front end for stagit
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
Since the process of creating repositories and recompiling stagit pages can be
|
||||||
|
very tedious, there is a simple front end called git repo manager (`grm`) to
|
||||||
|
deal with the chore, see the [readme][9] if you want to use `grm` to automate this
|
||||||
|
process.
|
||||||
|
|
||||||
|
If you want to host git repositories on your own server, you could use the [git
|
||||||
|
daemon][10] to better manage the visibility of your repositories. The remote
|
||||||
|
address exposed by the git daemon will have `git://` prefix. Check out the master
|
||||||
|
branch of [grm][11] if you want to use git daemon instead.
|
||||||
|
|
||||||
|
accepting patches
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Hosting git repositories this way means there will be no fancy features such as
|
||||||
|
issues and pull requests, but git have built-in support for [email workflows][12].
|
||||||
|
|
||||||
|
Contributors could format their commits to patches using
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git format-patch
|
||||||
|
```
|
||||||
|
|
||||||
|
and use the
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git send-email <patches>
|
||||||
|
```
|
||||||
|
|
||||||
|
command (see [here][13]) to send the patches to you, and you could apply the patches by
|
||||||
|
piping the email message or attached patches to the `git am` command
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git am < <patch>
|
||||||
|
```
|
||||||
|
|
||||||
|
See the [blog post][14] of Drew DeVault for using git with mutt, and check out
|
||||||
|
[aerc][15] if you want an modern alternative for mutt built from such workflow.
|
||||||
|
|
||||||
|
[1]: https://tildegit.org/
|
||||||
|
[2]: https://tilde.team/~kst/git/grm.tilde/file/README.html
|
||||||
|
[3]: https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server
|
||||||
|
[4]: https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols
|
||||||
|
[5]: https://git-scm.com/docs/githooks
|
||||||
|
[6]: https://git.codemadness.org/stagit/
|
||||||
|
[7]: https://git.codemadness.org/stagit/file/README.html
|
||||||
|
[8]: https://tilde.team/~kst/git/stagit-postrecv/file/stagit-post-receive.html
|
||||||
|
[9]: https://tilde.team/~kst/git/grm.tilde/file/README.html
|
||||||
|
[10]: https://git-scm.com/book/en/v2/Git-on-the-Server-Git-Daemon
|
||||||
|
[11]: https://sink.krj.st/grm/file/README.html
|
||||||
|
[12]: https://git-scm.com/docs/gitworkflows#_patch_workflow
|
||||||
|
[13]: https://git-send-email.io/
|
||||||
|
[14]: https://drewdevault.com/2019/05/13/Git-email-webcast.html
|
||||||
|
[15]: https://aerc-mail.org/
|
Loading…
Reference in New Issue