reduce scope of repodir, remove unused branch parameter

[stagit.git] / stagit.1

diff --git a/stagit.1 b/stagit.1
index a8c65ebe15562352adbdfeb04e50d2ccc01e1645..90549e1a2a2f8a90c52d10bf217145e694245424 100644 (file)
--- a/stagit.1
+++ b/stagit.1
@@ -1,4 +1,4 @@
-.Dd December 26, 2015
+.Dd May 1, 2016
 .Dt STAGIT 1
 .Os
 .Sh NAME
@@ -6,12 +6,25 @@
 .Nd static git page generator
 .Sh SYNOPSIS
 .Nm
-.Op Ar repodir
+.Op Fl c Ar cachefile
+.Ar repodir
 .Sh DESCRIPTION
 .Nm
 writes HTML pages for the repository
 .Ar repodir
-to the current directory. The following files will be written:
+to the current directory.
+.Pp
+Optionally the
+.Fl c Ar cachefile
+option can be used to 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.
+.Pp
+The following files will be written:
 .Bl -tag -width Ds
 .It atom.xml
 Atom XML feed
@@ -24,21 +37,32 @@ each commit links to a page with a diff and diffstat of the commit.
 Lists references of the repository such as branches and tags.
 .El
 .Pp
-For each file in HEAD a file will be written in the format:
+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"
+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 diff and diffstat of the
-commit. It will write the string "binary files differ" if the data is
-considered to be non-textual.
+commit/commitid.html. This file will contain the diff and diffstat 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
-The basename of the directory is used as the name.
+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 name. The suffix ".git" is
+removed from the basename, this is commonly used for "bare" repos.
 .Pp
-The content of the follow files specifies the meta data for each repository:
+The content of the follow files specifies the metadata for each repository:
 .Bl -tag -width Ds
-.It .git/description or description (bare repos).
+.It .git/description or description (bare repo).
 description
 .It .git/owner or owner (bare repo).
 owner of repository
@@ -46,6 +70,9 @@ owner of repository
 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 logo.png