commit 69c6052c783bca20094e8a22ff55135942595b4c
parent c682b2a1359134765801ea56e4e3584a65977707
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 26 May 2025 16:57:37 +0200
Add git-publish manual page
Diffstat:
3 files changed, 163 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
@@ -32,12 +32,14 @@ install:
}; \
install 755 "$(DESTDIR)$(BINPREFIX)" git-publish; \
install 755 "$(DESTDIR)$(BINPREFIX)" git-repo; \
- install 644 "$(DESTDIR)$(MANPREFIX)/man1" git-repo.1
+ install 644 "$(DESTDIR)$(MANPREFIX)/man1" git-repo.1; \
+ install 644 "$(DESTDIR)$(MANPREFIX)/man1" git-publish.1
uninstall:
rm -f $(DESTDIR)$(PREFIX)/bin/git-publish
rm -f $(DESTDIR)$(PREFIX)/bin/git-repo
rm -f $(DESTDIR)$(MANPREFIX)/man1/git-repo.1
+ rm -f $(DESTDIR)$(MANPREFIX)/man1/git-publish.1
lint:
shellcheck -o all git-publish
diff --git a/git-publish b/git-publish
@@ -34,7 +34,7 @@ tmpdir="$(mktemp -d "${TMPDIR:-/tmp}/git_publish_XXXXXX")"
synopsis()
{
>&2 printf \
-'usage: %s [-u base_url] [-g dir_git] [-w dir_www] repository ...\n' \
+'usage: %s [-g dir_git] [-u base_url] [-w dir_www] repository ...\n' \
"${0##*/}"
}
diff --git a/git-publish.1 b/git-publish.1
@@ -0,0 +1,159 @@
+.\" Copyright (C) 2024, 2025 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" This program is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.Dd May 26, 2025
+.Dt GIT-PUBLISH 1
+.Os
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm git-publish
+.Nd make public bare repositories
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.Nm
+.Op Fl g Ar dir_git
+.Op Fl u Ar base_url
+.Op Fl w Ar dir_www
+.Ar repository No ...
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+.Nm
+helps make bare git repositories public.
+It creates a link to them in a directory that would be publicly exposed
+via a git server
+.Pq e.g. Xr git-daemon 1 .
+.Pp
+It also generates HTML pages of their contents
+.Pq commits, files, license, README, etc.
+and an index listing published repositories.
+These files are stored in a directory which can then be publicly exposed
+via a simple static WEB server.
+To make sure they're up to date, a post-receipt hook is added to
+published repositories to update HTML pages on new commits
+.Pq see Xr githooks 5
+.Pp
+.Nm
+assumes that all publicly accessible repositories also have their own
+set of HTML pages.
+In other words, they have been made public via
+.Nm .
+The HTML index is therefore generated from all publicly accessible git
+repositories.
+If this constraint is not met, some entries in the index will refer to
+an invalid URL.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl g Ar dir_git
+Directory in which git repositories are publicly exposed.
+By default, the
+.Ev GIT_PUBLISH_DIR_GIT
+environment variable is used.
+.It Fl u Ar base_url
+Base URL to make links in the Atom feeds absolute.
+By default, the
+.Ev GIT_PUBLISH_BASE_URL
+environment variable is used.
+.It Fl w Ar dir_www
+Directory in which HTML pages are generated.
+By default, the
+.Ev GIT_PUBLISH_DIR_WWW
+environment variable is used.
+.Pp
+Pages from each repository are stored in a subdirectory whose name is
+the repository name, without the
+.Qq .git
+suffix that characterizes a bare git repository.
+The HTML index listing all published repositories, i.e. all repositories
+stored in the
+.Ar dir_git
+directory, is stored at the root of
+.Ar dir_www .
+.Pp
+External HTML resources, such as the CSS file and icons, are assumed to
+be present in this directory
+.Po see
+.Sx FILES
+section
+.Pc .
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev GIT_PUBLISH_DIR_GIT
+Directory in which bare repositories are made public.
+The default is
+.Pa /srv/git .
+.It Ev GIT_PUBLISH_BASE_URL
+Base URL to make links in the ATOM feed absolute.
+It has no default value and must be explicitly defined if the
+.Fl u
+option is not used.
+.It Ev GIT_PUBLISH_DIR_WWW
+Directory where public repository HTML pages are stored.
+The default is
+.Pa /srv/www/git .
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh FILES
+The following files are assumed to be in the
+.Ar dir_www
+directory:
+.Bl -tag -width Ds
+.It Pa style.css
+HTML stylesheet.
+.It Pa favicon.png
+favicon image (used by graphical browser).
+.It Pa logo.png
+32x32 logo.
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXIT
+.Ex -std
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+Make a bare repository public, i.e. link to it in the
+.Pa /srv/git
+directory
+.Pq default value of Ev GIT_PUBLISH_DIR_GIT .
+Store generated HTML pages in the
+.Pa /srv/www/git/
+directory
+.Pq default value of Ev GIT_PUBLISH_DIR_WWW .
+Make Atom feed URLs to repository commits absolute at URL
+https://www.example.com/git:
+.Bd -literal -offset Ds
+git-publish -u https://www.example.com/git /path/to/repository.git
+.Ed
+.Pp
+Make public a set of bare git repositories:
+.Bd -literal -offset Ds
+git-publish -u https://www.example.com/git /path/to/*.git
+.Ed
+.Pp
+Same as above, but using specific directories for public git
+repositories and WEB pages.
+In addition, use the environment variable instead of the command-line
+option to define the base URL where repository HTML pages are stored:
+.Bd -literal -offset Ds
+export GIT_PUBLISH_BASE_URL="https://www.example.com/git"
+git-publish -g /var/git -w /var/www/git /path/to/*.git
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr git 1 ,
+.Xr git-daemon 1 ,
+.Xr stagit 1 ,
+.Xr stagit-index 1 ,
+.Xr githooks 5
