From 978703ebc86060555da3df4c376e37d16aecce29 Mon Sep 17 00:00:00 2001 From: Christoph Schlosser Date: Sun, 24 Aug 2025 12:07:47 +0200 Subject: g2h: Add suporting docs --- LICENSE | 29 +++++++++++++++++++++++++++ README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ mise.toml | 4 ++-- test_repo/git.tgz | Bin 16086 -> 15988 bytes 4 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..fe24012 --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +Copyright (c) 2025, Christoph Schlosser. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + (1) Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + (2) Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + (3)The name of the author may not be used to + endorse or promote products derived from this software without + specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd14d1c --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# g2h - Generate Hugo style markdown pages from your git repository history + +This program allows you to generate markdown files to have a static web based interface for navigating git repositores. +Something like [cgit](https://git.zx2c4.com/cgit/) for static websites, like [stagit](https://codemadness.org/stagit.html), but emitting Markdown for use in [Hugo](https://gohugo.io)[^1]. + +## Goals + +- Generate static pages for projects fitting for the size of a personal homepage. +- Generate markdown that can easily be integrated with Hugo. +- Make full tree state and individual files for every commit viewable and also downloadable. +- Work for [me](https://c.onl). + +## Non-goals + +- Provide codesearch. +- Replacement for Git forges. +- Replace cgit. +- Work for large projects, as they may be found in a company (like) setting. +- Implement any work that should be taken care of by Hugo, e.g. combining multiple projects onto a single page, feeds and custom styling. + +## Usage + +Let's assume your git project is in `~/development/project` and the sources for your static site are in `~/web/page`. +Then you would run this command: +```bash +g2h --repo ~/development/project --out ~/web/page --title "My awesome project" --static-subdir static/project --content-subdir content/git/project +``` +The markdown files for Hugo will be placed in `~/web/page/content/git/project` and static files, like tarballs for each commit and individual file hashes, into `~/web/page/static/project`. +For a full list of options, their defaults and how they're changing the behavior of the program run `g2h --help`. + +## Features + +- [ ] Overview page. + Table of branches and table of tags. + Each with name, most recent message summary and last modified date. +- [ ] Commit log page. + Table with branch/tag, message summary and last modified date columns. + - [ ] Tabbed log page. +- [ ] Commit page. + Collection of metadata at the beginning of the page. + Consisting of commit hash, commit date, author, (redact email), parent(s) and child(ren). + Followed by the commit message and then a list of changed files. + - [ ] Show diffstat on commit page. +- [ ] Tree view. + Show the state of the tree at the current commit. + Folders should be traversable by clicking and clicking on a file should open that file's page. +- [ ] Individual file page. + File content in a codeblock with file extension based language detection. + For binary files a note that it can't be displayed. + - [ ] Don't treat pictures as binary files. + - [ ] Breadcrumbs for navigating. +- [ ] Nav bar for navigating the pages mentioned above. + - [ ] Link to special readme, if a readme can be found, rendering markdown. +- [ ] Wrapper script that takes care fo `venv` setup. +- [ ] Limit to certain branch(es). +- [ ] Limit commit range. +- [ ] Parallelize generating output. + +[^1]: I'm using Hugo but any static site generator with a similar layout should work. diff --git a/mise.toml b/mise.toml index 0854dbd..78eb153 100644 --- a/mise.toml +++ b/mise.toml @@ -13,8 +13,8 @@ run = "rm -rf ./test_out && python3 -m g2h.cli test_repo test_out" [tasks.commit] run = [ - 'tar czf test_repo/git.tgz -C test_repo .git*', - 'rm -rf test_repo/.git*', + 'tar czf test_repo/git.tgz -C test_repo .git', + 'rm -rf test_repo/.git', './.mise-tasks/co.sh {{arg(name="commit args", var=true)}}', 'tar xzf test_repo/git.tgz -C test_repo' ] diff --git a/test_repo/git.tgz b/test_repo/git.tgz index 45ea338..f0cf7b2 100644 Binary files a/test_repo/git.tgz and b/test_repo/git.tgz differ -- cgit v1.2.3