dotfiles

  1.Dd August 2, 2021
  2.Dt STAGIT 1
  3.Os
  4.Sh NAME
  5.Nm stagit
  6.Nd static git page generator
  7.Sh SYNOPSIS
  8.Nm
  9.Op Fl c Ar cachefile
 10.Op Fl l Ar commits
 11.Op Fl u Ar baseurl
 12.Op Fl n Ar sitename
 13.Ar repodir
 14.Sh DESCRIPTION
 15.Nm
 16writes HTML pages for the repository
 17.Ar repodir
 18to the current directory.
 19.Pp
 20The options are as follows:
 21.Bl -tag -width Ds
 22.It Fl c Ar cachefile
 23Cache the entries of the log page up to the point of
 24the last commit.
 25The
 26.Ar cachefile
 27will store the last commit id and the entries in the HTML table.
 28It is up to the user to make sure the state of the
 29.Ar cachefile
 30is in sync with the history of the repository.
 31.It Fl l Ar commits
 32Write a maximum number of
 33.Ar commits
 34to the log.html file only.
 35However the commit files are written as usual.
 36.It Fl u Ar baseurl
 37Base URL to make links in the Atom feeds absolute.
 38For example: "https://github.com/maydayv7/stagit/".
 39.It Fl n Ar sitename
 40Set the site name used in the header link.
 41.El
 42.Pp
 43The options
 44.Fl c
 45and
 46.Fl l
 47cannot be used at the same time.
 48.Pp
 49The following files will be written:
 50.Bl -tag -width Ds
 51.It atom.xml
 52Atom XML feed of the last 100 commits.
 53.It tags.xml
 54Atom XML feed of the tags.
 55.It files.html
 56List of files in the latest tree, linking to the file.
 57.It log.html
 58List of commits in reverse chronological applied commit order, each commit
 59links to a page with a diffstat and diff of the commit.
 60.It refs.html
 61Lists references of the repository such as branches and tags.
 62.El
 63.Pp
 64For each entry in HEAD a file will be written in the format:
 65file/filepath.html.
 66This file will contain the textual data of the file prefixed by line numbers.
 67The file will have the string "Binary file" if the data is considered to be
 68non-textual.
 69.Pp
 70For each commit a file will be written in the format:
 71commit/commitid.html.
 72This file will contain the diffstat and diff of the commit.
 73It will write the string "Binary files differ" if the data is considered to
 74be non-textual.
 75Too large diffs will be suppressed and a string
 76"Diff is too large, output suppressed" will be written.
 77.Pp
 78When a commit HTML file exists it won't be overwritten again, note that if
 79you've changed
 80.Nm
 81or changed one of the metadata files of the repository it is recommended to
 82recreate all the output files because it will contain old data.
 83To do this remove the output directory and
 84.Ar cachefile ,
 85then recreate the files.
 86.Pp
 87The basename of the directory is used as the repository name.
 88The suffix ".git" is removed from the basename, this suffix is commonly used
 89for "bare" repos.
 90.Pp
 91The content of the follow files specifies the metadata for each repository:
 92.Bl -tag -width Ds
 93.It .git/description or description (bare repo).
 94description
 95.It .git/owner or owner (bare repo).
 96owner of repository
 97.It .git/url or url (bare repo).
 98primary clone URL of the repository, for example:
 99https://github.com/maydayv7/stagit
100.El
101.Pp
102When a README or LICENSE file exists in HEAD or a .gitmodules submodules file
103exists in HEAD a direct link in the menu is made.
104.Pp
105For changing the style of the page you can use the following files:
106.Bl -tag -width Ds
107.It favicon.png
108favicon image.
109.It /style.css
110Global CSS stylesheet (must be present at root).
111.El
112.Sh EXIT STATUS
113.Ex -std
114.Sh EXAMPLES
115.Bd -literal
116mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1
117stagit path/to/gitrepo1
118# repeat for other repositories.
119.Ed
120.Pp
121To update the HTML files when the repository is changed a git post-receive hook
122can be used, see the file example_post-receive.sh for an example.
123.Sh SEE ALSO
124.Xr stagit-index 1
125.Sh AUTHORS
126.An V7