commit 5654d2210a26460793c649616d0dc25ab0971fad
parent 608c66ffd117f344ed46c0d56a058e3f636487a8
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 25 Sep 2024 12:13:01 +0200
Write man page
Updates the Makefile to install the man page in addition to the
executable. Updates the lint target so that it also checks the syntax
and mandoc conventions of the man page.
Diffstat:
| M | Makefile | | | 13 | ++++++++++--- |
| M | git-repo | | | 2 | +- |
| A | git-repo.1 | | | 98 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
3 files changed, 109 insertions(+), 4 deletions(-)
diff --git a/Makefile b/Makefile
@@ -16,18 +16,25 @@
.POSIX:
.SUFFIXES: # Clean-up default inference rules
-# Default install directory
+# Default install directories
PREFIX = /usr/local
+MANPREFIX = ${PREFIX}/share/man
# Nothing to do
default:
install:
- mkdir -p $(DESTDIR)$(PREFIX)/bin/
- cp git-repo $(DESTDIR)$(PREFIX)/bin/
+ mkdir -p $(DESTDIR)$(PREFIX)/bin
+ cp -f git-repo $(DESTDIR)$(PREFIX)/bin
+ chmod 755 $(DESTDIR)$(PREFIX)/bin/git-repo
+ mkdir -p $(DESTDIR)$(MANPREFIX)/man1
+ cp -f git-repo.1 $(DESTDIR)$(MANPREFIX)/man1
+ chmod 644 $(DESTDIR)$(MANPREFIX)/man1/git-repo.1
uninstall:
rm -f $(DESTDIR)$(PREFIX)/bin/git-repo
+ rm -f $(DESTDIR)$(MANPREFIX)/man1/git-repo.1
lint:
shellcheck -o all git-repo
+ mandoc -Wbase -Tlint git-repo.1
diff --git a/git-repo b/git-repo
@@ -28,7 +28,7 @@ die()
synopsis()
{
cmd="${0##*/}"
- >&2 printf 'usage: %s [-d] [-s group] path\n' "${cmd}"
+ >&2 printf 'usage: %s [-d] [-s group] directory\n' "${cmd}"
}
share() # repo, group
diff --git a/git-repo.1 b/git-repo.1
@@ -0,0 +1,98 @@
+.\" Copyright (C) 2024 |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 September 24, 2024
+.Dt GIT-REPO 1
+.Os
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm git-repo
+.Nd setting up a bare repository
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.Nm
+.Op Fl d
+.Op Fl s Ar group
+.Ar directory
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+.Nm
+helps to set up a git bare repository.
+If the input
+.Ar directory
+does not exist, it is created and initialized as a bare git repository
+before being configured according to the defined options.
+Otherwise,
+.Nm
+verifies that the given
+.Ar directory
+is indeed a bare git repository before updating its configuration.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl d
+Prepare the repository for read-only access via the HTTP[S] protocol,
+i.e. for use over dumb transports.
+.It Fl s Ar group
+Share write access to the given
+.Ar group
+so that each member of the group can update the repository.
+.Pp
+Once shared, internal files belong to the users who created them, so the
+repository is effectively owned by the co-authors.
+Consequently, all users, including the one who created and shared the
+repository, have write access via their group ID, rather than their user
+ID, which is not sufficient to update all the files in the repository.
+Privatising a shared repository by reconfiguring it without the
+.Fl s
+option is therefore impossible if a co-author has already pushed
+updates.
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+Set up a regular bare repository:
+.Bd -literal -offset Ds
+git repo /path/to/the/git/repository.git
+.Ed
+.Pp
+Set up a bare repository with write access shared with the
+.Ar users
+group :
+.Bd -literal -offset Ds
+git repo -s users /path/to/the/git/repository.git
+.Ed
+.Pp
+Same as above, but enables dump transports to allow read-only access via
+HTTP[S]:
+.Bd -literal -offset Ds
+git repo -d -s users /path/to/the/git/repository.git
+.Ed
+.Pp
+Create a regular bare repository.
+Update it to enable dump transports.
+Then give write access to the
+.Ar users
+group.
+Finally, cancel support for dumb transports but retain shared write
+access with
+.Ar users .
+.Bd -literal -offset Ds
+git repo /path/to/the/git/repository.git
+git repo -d /path/to/the/git/repository.git
+git repo -d -s users /path/to/the/git/repository.git
+git repo -s users /path/to/the/git/repository.git
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr git 1
