.\" 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 August 23, 2022
.Dt GITFS 8
.Os NetBSD 5.2
.Sh NAME
.Nm gitfs
.Nd export a filesystem-ish view of git repos
.Sh SYNOPSIS
.Nm
.Op Fl d Ar kind Ns Op , Ns Ar kind Ns \&...
.Op options ...
.Ar cf
.Ar mp
.Sh DESCRIPTION
.Nm
uses
.Xr libqfs 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 QFS rendezvous point,
.Ar mp .
These can also be specified with
.Fl config
and
.Fl qfs
before them, to disambiguate in case the strings begin, or might begin,
with a dash.
.Pp
There are other options supported:
.Bl -tag -width indent
.It Fl d
Takes as argument a comma-separated list of debugging types, turning
those types of debug output on.  (To get a list of the supported
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 \&'?'.)
.It Fl bg
Makes
.Nm
background itself as soon as it's started up and the rendezvous point
is operational.
.It Fl sync Ar fd
.Ar fd must be a file descriptor number.
.Nm
starts up as normal, up to the point where it normally would actually
perform the mount.  At this point, it writes the character
.Sq R
to file descriptor
.Ar fd
and reads a character in response.  If this read fails for any reason,
or if the character read is not
.Sq G ,
.Nm
exits immediately.  Otherwise, it then continues with its startup,
establishing its rendezvous point and continuing to normal operation.
This is used to synchronize with an external process managing runs so
as to shift responsibility for a rendezvous point from one instance to
another as seamlessly as possible.
.El
.Pp
It does not background itself unless told to, and, if no debugging is
turned on, produces no output unless a bugcheck trips.
.Sh CONFIG FILE
In normal use,
.Nm Ap s
configuration is specified by a config file.  There is another mode,
designed for quick one-off operation, which will be described later.
.Pp
.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.  There is
no way to get a single quote into a single-quoted string or a double
quote into a double-quoted string; switch quoting styles without
intervening whitespace if you want a string containing multiple
different quoting characters.)
.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
.Pf ( Sq on
or
.Sq yes )
or off
.Pf ( Sq off
or
Sq no ) .
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
.Pp
The short alternative configuration method mentioned above is designed
for a quick one-off mount of a single repo.  In this form, you specify
the repo directory name in place of the config file name.  This is
equivalent to a config file containing just a single line, specifying
the last component of the repo directory name (before the trailing
.Sq Pa /.git ,
if present) as the path within the mount point and, of course, the repo
directory name as the repo path.  Big-repo mode is always turned off
when this form is used.
.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 numerous things.  In this description,
a
.Sq commit symlink
is a symlink pointing to a commit's directory under the
.Sq Pa commit
directory; a
.Sq commit file
is a file containing a commit ID, in the form of a string holding
either the relevant commit ID (if big-repo mode is off) or the relevant
commit ID with the appropriate two-character directory and a slash
prepended (if big-repo mode is on).
.Bl -tag -width indent
.It Pa branch-link
Directory holding one commit symlink per branch, each one named after
its branch and pointing to that branch's head commit.
.It Pa branch-file
Directory holding one commit file per branch, each one named after its
branch and pointing to that branch's head commit.
.It Pa tag-link
Directory holding one commit symlink per tag, each one named after its
tag and pointing to that tag's commit.
.It Pa tag-file
Directory holding one commit file per tag, each one named after its tag
and pointing to that tag's commit.
.It Pa HEAD-link
If the repo is on a branch, this is a symlink pointing to the branch
link in the branch-link directory; if the repo is detached, this a
commit symlink pointing to its current HEAD.
.It Pa HEAD-file
If the repo is on a branch, this is a file containing the word
.Sq branch ,
a single space, and the name of the branch; if the repo is detached,
this is a file containing the word
.Sq commit ,
a single space, and the commit ID (formatted as if for a commit file;
the only reason this isn't a commit file in this case is the
.Sq commit
prefix).
.It Pa commit
Directory holding one directory per commit (with an intermediate
grouping layer if big-repo mode is on; see above).
.It Pa diff
This is a directory.  It returns no contents when listed (see
.Xr readdir 2 ) ,
but accessing certain filenames returns files containing
.Sq git diff
output.  Specifically, a name of the form
.Sq COMMIT1-COMMIT2 ,
that is, two commit IDs (or unambiguous abbrevations thereof) with a
dash between them, returns a file containing output from
.Sq git diff COMMIT1 COMMIT2 .
.It Pa abbrev-link
This is a directory.  It returns no contents when listed (see
.Xr readdir 2 ) ,
but accessing certain filenames returns commit links.  Specifically,
any unambiguous abbreviation of any commit ID returns a commit link for
that commit.
.It Pa abbrev-file
This is a directory.  It returns no contents when listed (see
.Xr readdir 2 ) ,
but accessing certain filenames will succeed.  Any unambiguous
abbreviation of any commit ID returns a commit file for that commit.
An ambiguous commit abbreviation (ie, one which matches multiple
commits) returns a file containing
.Sq ambiguous\en .
A string which could be a commit ID or abbreviation (length in the
range 1 through 40, all characters are lowercase hex) but which matches
no commits returns a file containing
.Sq no match\en .
No other strings return anything.
.El
.Pp
Each commit's directory contains six things, with a seventh 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 abbrev
A plain file containing the commit ID abbreviated as far as possible
while remaining unambiguous (within the relevant repo, of course).
.It Pa time-raw
A plain file giving the commit's timestamp, as a decimal integer in
seconds since the UNIX epoch.
.It Pa time-utc
A plain file giving the commit's timestamp, formatted as YYYY-MM-DD
HH:MM:SS in UTC.
.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-link
A directory containing zero or more commit symlinks, named as decimal
integers from 1 upwards, as many of them as the commit has parent
commits, linking to the parent commits.
.It Pa parents-file
A directory containing zero or more commit files, named as decimal
integers from 1 upwards, as many of them as the commit has parent
commits, naming the parent commits.
.It Pa tree
Contains the working tree contents corresponding to the relevant
commit.
.El
.Pp
A root commit (one with no parents) will still have
.Pa parents-link
and
.Pa parents-file
directories, buyt they will be empty.
.Sh BUGS
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 .