.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents.montreal.qc.ca, 2022-05-07
.Dd May 7, 2022
.Dt GITFS 8
.Os NetBSD 5.2
.Sh NAME
.Nm gitfs
.Nd mount git repos as a filesystem
.Sh SYNOPSIS
.Nm
.Op Fl d Ar kind Ns Op , Ns Ar kind Ns \&...
.Op Fl config Ar cf
.Op Fl mount Ar mp
.Ar cf
.Ar mp
.Sh DESCRIPTION
.Nm
uses
.Xr puffs 3
to provide a filesystem view of one or more git repos.  Its operation
is driven off a config file; see the
.Sx CONFIG FILE
section for details.
.Pp
The command line, at its simplest, consists of a config file,
.Ar cf ,
and a mount point path,
.Ar mp .
These can also be specified with
.Fl config
and
.Fl mount
before them, to disambiguate in case the strings begin, or might begin,
with a dash.
.Pp
The only other option supported is
.Fl d ,
which takes as argument a comma-separated list of debugging types,
turning those types of debug output on.  To get a list of the debugging
types, specify
.Fl d
with a single question mark, \&?, as the argument.  (Depending on your
shell, you will likely have to quote this, eg \e\&? or \&'?'.)
.Pp
It does not background itself, and, if no debugging is turned on,
produces no output unless a bugcheck trips.  Killing the
.Nm
process will forcibly unmount the filesystem; unmounting it manually
will cause the
.Nm
process to exit.
.Sh CONFIG FILE
.Nm Ap s
config file consists, at its simplest, of a series of lines, each
specifying two paths.
.Pp
The first one is a path, relative to the mount point, of the repo's
top-level directory.  (For the filesystem view presented within this
directory, see the
.Sx DIRECTORY STRUCTURE
section.)  This path must not begin or end with a slash, must not
contain consecutive slashes, and must not attempt to use any pathname
components named
.Sq \&.
or
.Sq \&.. .
.Pp
The second one is a path which names a git repo.  (If the repo is not a
bare repo, the path must be to the repo's git directory, typically
called
.Sq Pa \&.git
in its working tree.)  This path has no particular restrictions beyond
naming a git repo's git directory.
.Pp
Config-file lines that are empty, completely blank, or whose first
nonblank character is
.Sq \&# ,
.Sq \&; ,
or NUL are comments and are ignored.  Non-comment lines that end with a
.Sq \e ,
possibly followed by whitespace, have the backslash, any following
whitespace, and the newline deleted, thus concatenating it with the
following line.  (Comments are deleted before this concatenation
happens; comment lines can appear amid a continued line.)
.Pp
Non-comment lines support three quoting mechanisms: backslashes, single
quotes, and double quotes.  A backslash quotes the next character;
paired single or double quotes quote all characters within them.
(Quoting any of these characters removes its special meaning.)
.Pp
Lines whose first noblank character is an unquoted percent sign,
.Sq \&% ,
are an escape mechanism.  There are two kinds of such lines supported:
.Bl -tag -width indent
.It \&%include Ar PATH
Reads the file named by
.Ar PATH
and effectively inserts it in place of the
.Sq \&%include
line.  Note that lines cannot be continued between files; it is an
error for EOF to occur when a line continuation is indicated.
.It \&%bigrepo Ar ONOFF
.Ar ONOFF
must be one of the four strings
.Sq on ,
.Sq off ,
.Sq yes ,
or
.Sq no .
This turns big-repo mode on or off.  Big-repo mode is designed to
support large repos better.  With it off, a repo's
.Sq Pa commit
directory contains one subdirectory per commit, with the subdirectory
name being the commit's 40-character hex hash.  With big-repo mode on,
the
.Sq Pa commit
directory instead contains up to 256 subdirectories which then contain
the commit subdirectories; each intermediate subdirectory name is two
characters long and groups together all the commit hashes beginning
with those two characters.  Symlinks into the commit directory are
adjusted correspondingly.  The big-repo setting that is in effect when
a repo spec is encountered is the one that is used for that repo.
.El
.Sh DIRECTORY STRUCTURE
There are two kinds of directory structure involved.  Each repo has a
directory of its own; there also may be directory structure above the
repo directories.  (Attempts to place two repos at the same place in
the structure, or to place one repo within another's repo directory,
are rejected as errors.)  Directories are created under the mount point
as necessary to place each repo at the relative path specified.  These
intermediate directories are empty except for subdirectories necessary
to reach repo directories.
.Pp
Thus, for example, if
.Pa /sources/prog
is a non-bare repo with a working tree and a
.Pa .git
subdirectory,
.Pa /home/games/bridge
is similar, and
.Pa /repos/git/depapp
is a bare repo, then
.Bd -literal -offset indent
games/bar/prog  /sources/prog/.git
# see Eric for more on bridge
games/cards/bridge /home/games/bridge/.git
configs         /repos/git/depapp
.Ed
\ \&
.br
would cause the mount point to have two subdirectories,
.Sq Pa games
and
.Sq Pa configs .
.Sq Pa configs
would contain the depapp repo's directory;
.Sq Pa games
would have two subdirectories,
.Sq Pa bar
and
.Sq Pa cards ,
with
.Sq Pa bar
having a
.Sq Pa prog
subdirectory containing the prog repo and
.Sq Pa cards
having a
.Sq Pa bridge
subdirectory containing the bridge repo.
.Pp
As the last line of this example implies, there does not have to be any
particular relationship between the two pathnames in a repo-spec line.
.Pp
Within a repo's directory there are four things.  There is a directory
.Sq Pa branch
which holds branch symlinks, a directory
.Sq Pa tag
which holds tag symlinks, a directory
.Sq Pa commit
which holds commit directories (but see the discussion of big-repo
mode, above), and a symlink
.Sq Pa HEAD
which links either to a symlink in the
.Sq Pa branch
subdirectory, if the repo is on a branch, or to a commit in the
.Sq Pa commit
subdirectory, if the repo is in detached HEAD mode.
.Pp
The branch and tag symlinks are named after the branch or tag in
question and symlink to the commit that is the branch head or the
tagged commit, as the case may be.
.Pp
Commit directories contain five things, with a sixth possibly but not
necessarily present.  These are:
.Bl -tag -width indent
.It Pa author
A plain file giving the name and email recorded as the commit's author.
.It Pa time
A plain file giving the commit's timestamp, as a decimal integer in
seconds since the UNIX epoch.
.It Pa message
A plain file containing the commit's commit-log message.  (See also the
.Pa encoding
file.)
.It Pa encoding
If the commit has an
.Sq encoding
header, this is a plain file containing that header's contents; if not,
this does not exist.  This exists to describe the encoding of the
commit message; while the plumbing treats the commit message as an
opaque blob of octets, you are normally supposed to treat it as encoded
in the encoding named here, or as UTF-8 if there is no encoding
specified.
.It Pa parents
A directory containing zero or more symlinks, named as decimal integers
from 1 upwards, as many of them as the commit has parent commits.  (A
root commit will still have a parents directory, but it will be empty.)
.It Pa tree
Contains the working tree contents corresponding to the relevant
commit.  But see the
.Sx BUGS
section.
.El
.Sh BUGS
Tree directories are not yet implemented (or, more precisely, they
exist but are always empty).
.Pp
Presuming commits with unmarked encoding are in UTF-8 is arguably
broken, but it's how git is defined to work.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents-montreal.org .