github/repo2html
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
No description
21 commits 2 branches 0 tags 162 KiB
Scheme 74.4%
HTML 12.8%
Shell 7.2%
Makefile 4.8%
Dockerfile 0.8%
Find a file
pho4cexa b3719a005d build html only when HEAD branch changes; cleanup: 
post-receive commit hooks receive on standard input lines of the form:

old-commit new-commit ref
old-commit new-commit ref
old-commit new-commit ref

so we can inspect those lines to determine whether or not the current
branch (aka HEAD) has been changed. because there's no reason to rebuild
the html representation of other branches.

in future we might even use the git tree-diff between old-commit and
new-commit to determine the set of files that have been added, removed,
or changed, and regenerate the html representation for only those files,
instead of deleting and rebuilding all files every time.
2022-12-04 20:57:07 -05:00
.gitignore lightened shade of the default pink 2022-12-02 16:47:20 -05:00
git-daemon.service first commit 2022-12-02 16:41:55 -05:00
LICENSE added license :) 2022-12-04 00:51:48 -05:00
main.scm build html only when HEAD branch changes; cleanup: 2022-12-04 20:57:07 -05:00
Makefile first commit 2022-12-02 16:41:55 -05:00
post-receive updated readme 2022-12-04 00:46:31 -05:00
README.md small wording edit 2022-12-04 01:34:19 -05:00

README.md

repo2html

a post-receive hook that generates an html view of a git repository.

features

  • static html files
  • no background process other than git-daemon
  • default repository view is an html-rendered README.md file

caveats

  • binary file contents are just... shown
  • images don't render
  • directory tree is shown as a flat list of files, so git repositories with many files and directories will look awful
  • no commit log (yet?)
  • no line numbers (yet?)

disclaimer

no one is liable if this software breaks, deletes, corrupts, or ruins anything

requirements

note: if you have chicken scheme installed, then you can install the eggs above by running sudo make dependencies.

quickstart

on your server, run the following commands, changing anything occurs between angled brackets ("<" and ">"):
adduser git
mkdir /var/www/git
chown git:git /var/www/git
cp git-daemon.service /etc/systemd/system/
ufw allow 9418
systemctl enable --now git-daemon.service
su git
cd
mkdir .ssh && chmod 700 .ssh
touch .ssh/authorized_keys && chmod 600 .ssh/authorized_keys
add your public ssh key to .ssh/authorized_keys
mkdir projects
clone this repository
cd into this repository
sudo make dependencies
make
sudo make install
edit the post-receive file
cp post-receive <path/to/bare/git/repository>/hooks/
chmod u+x <path/to/bare/git/repository>/hooks/post-receive
then in a git repository on your local machine, run git remote add origin git@<example.com>:~/projects/<repository-name>
git push

compilation

chicken scheme runs faster if it's compiled to a binary file. by default, the binary is named repo2html, and is added to /usr/local/bin.

to compile repo2html into a binary file, follow the steps below:

  1. ensure you're in the repo2html git repository
  2. run make dependencies as root
  3. run make
  4. run make install as root

server setup

TODO (git user, ssh, ufw ports, web directory, git-daemon, mkdir /home/git/projects, post-receive hook, systemd service)

usage

after you've set up your server and set your remote git url on your local machine, you can use git push to push updates to your projects, and the post-receive hook will generate an html version of your git repository.

configuration

you can configure repo2html by changing environment variables in the post-receive hook file.

refer to the list of environment variable names and their descriptions to learn more:

  • GIT_WWW: the web directory where repo2html generates static git repositories. for example, /var/www/git/.
  • GIT_WWW_CLONE_URL: the url that people will use when downloading your git repository. if you have git-daemon set up, then you can prefix the url with git://. otherwise, prefix the url with http://. for example, git://git.example.com. note: avoid slashes at the end of the url.
  • GIT_WWW_TITLE: the text that populates the <title> html tag.
  • GIT_WWW_DESCRIPTION: a string that populates the description meta information about your git repository.
  • GIT_WWW_H1: the text that populates the <h1> html tag.

todos

  • ☐ if no README.md file exists in the root directory of the repository, then don't create the "about" nav link. instead, make the files page the index.html
  • ☐ add a "license" nav link if a LICENSE file exists in the root directory of the repository. if no LICENSE file exists, then don't create the "license" nav link
  • ☐ add a "contributors" nav link

hopes

  • ☐ clickable line numbers in source files
  • ☐ render images
  • ☐ make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?)
  • ☐ nav link: Releases