Restructure repo

[stagit.git] / man / stagit.1

diff --git a/man/stagit.1 b/man/stagit.1
new file mode 100644 (file)
index 0000000..23e7ca7
--- /dev/null
+++ b/man/stagit.1
@@ -0,0 +1,108 @@
+.Dd March 2021
+.Dt STAGIT 1
+.Os
+.Sh NAME
+.Nm stagit
+.Nd static git page generator
+.Sh SYNOPSIS
+.Nm
+.Op Fl c Ar cachefile
+.Op Fl l Ar commits
+.Ar repodir
+.Sh DESCRIPTION
+.Nm
+writes HTML pages for the repository
+.Ar repodir
+to the current directory.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl c Ar cachefile
+Cache the entries of the log page up to the point of
+the last commit.
+The
+.Ar cachefile
+will store the last commit id and the entries in the HTML table.
+It is up to the user to make sure the state of the
+.Ar cachefile
+is in sync with the history of the repository.
+.It Fl l Ar commits
+Write a maximum number of
+.Ar commits
+to the log.html file only.
+However the commit files are written as usual.
+.El
+.Pp
+The options
+.Fl c
+and
+.Fl l
+cannot be used at the same time.
+.Pp
+The following files will be written:
+.Bl -tag -width Ds
+.It atom.xml
+Atom XML feed
+.It files.html
+List of files in the latest tree, linking to the file.
+.It log.html
+List of commits in reverse chronological applied commit order, each commit
+links to a page with a diffstat and diff of the commit.
+.It refs.html
+Lists references of the repository such as branches and tags.
+.El
+.Pp
+For each entry in HEAD a file will be written in the format:
+file/filepath.html.
+This file will contain the textual data of the file prefixed by line numbers.
+The file will have the string "Binary file" if the data is considered to be
+non-textual.
+.Pp
+For each commit a file will be written in the format:
+commit/commitid.html.
+This file will contain the diffstat and diff of the commit.
+It will write the string "Binary files differ" if the data is considered to
+be non-textual.
+Too large diffs will be suppressed and a string
+"Diff is too large, output suppressed" will be written.
+.Pp
+When a commit HTML file exists it won't be overwritten again, note that if
+you've changed
+.Nm
+or changed one of the metadata files of the repository it is recommended to
+recreate all the output files because it will contain old data.
+To do this remove the output directory and
+.Ar cachefile ,
+then recreate the files.
+.Pp
+The basename of the directory is used as the repository name.
+The suffix ".git" is removed from the basename, this suffix is commonly used
+for "bare" repos.
+.Pp
+The content of the follow files specifies the metadata for each repository:
+.Bl -tag -width Ds
+.It .git/description or description (bare repo).
+description
+.It .git/owner or owner (bare repo).
+owner of repository
+.It .git/url or url (bare repo).
+primary clone url of the repository, for example: git://git.2f30.org/stagit
+.El
+.Pp
+When a README or LICENSE file exists in HEAD or a .gitmodules submodules file
+exists in HEAD a direct link in the menu is made.
+.Pp
+For changing the style of the page you can use the following files:
+.Bl -tag -width Ds
+.It favicon.png
+favicon image.
+.It logo.png
+32x32 logo.
+.It style.css
+CSS stylesheet.
+.El
+.Sh SEE ALSO
+.Xr stagit-index 1
+.Sh AUTHORS
+.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
+.An Armaan Bhojwani Aq Mt me@armaanb.net