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