commit 87a196d720a9cc04902fd14f448ef8d569a85234
parent fd8fda1375e370d39f663542870f5d59a62d7146
Author: kst
Date: 2020-07-18 05:23Z
add tutorial
Diffstat:
| A | TUTORIAL | | | 244 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 244 insertions(+), 0 deletions(-)
diff --git a/TUTORIAL b/TUTORIAL
@@ -0,0 +1,244 @@
+hosting public git repos on tildes
+==================================
+
+You don't actually need the Gitea instance of tildeverse [1] to host your
+public git repositories. As long as your shell provider allows you to use git
+serve public web pages via HTTP, you could easily set up a read-only clone URL
+fetchable using git clone similar to this one:
+
+ $ git clone https://tilde.team/~kst/grm.tilde.git
+
+We will use tilde.team as an example, but it should work on all tildes/pubnix
+servers with minor modifications.
+
+tl;dr
+-----
+
+If you are not interested in the details, I wrote a minimal frontend 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 githook [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*, you can't push anything using this
+URL. Normally you would need to set up the "smart" protocol [4] for authentica-
+tion, but since most tildes uses 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 frontend
+------------
+
+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
+
+If your server 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/
+
+If not, ask the admin to install it, or follow the instruction in stagit
+README [7] to build a statically-linked binary on your local machine and copy
+it to the server.
+
+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
+
+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 at [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 frontend
+------------------
+
+Since the process of creating repositories and recompiling stagit pages can be
+very tedious, I wrote up a simple frontend 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 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].
+
+Other people could format their commits to patches using
+
+ $ git format-patch
+
+and use the
+
+ $ git send-email <patches>
+
+command [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 of Drew DeVault [14] 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/
