X-Git-Url: https://git.armaanb.net/?a=blobdiff_plain;f=stagit.1;h=360f7166826423c27b98044f285669ddfbe25820;hb=dd32948ba00cb30c852de72260255a5ebb24ccff;hp=d3cbb7e543553cf582ce29246c281bdac280318f;hpb=1a3584e2d0689aece46d9832c91f57723296807f;p=stagit.git

diff --git a/stagit.1 b/stagit.1
index d3cbb7e..360f716 100644
--- a/stagit.1
+++ b/stagit.1
@@ -1,4 +1,4 @@
-.Dd May 1, 2016
+.Dd February 6, 2019
 .Dt STAGIT 1
 .Os
 .Sh NAME
@@ -7,6 +7,7 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl c Ar cachefile
+.Op Fl l Ar commits
 .Ar repodir
 .Sh DESCRIPTION
 .Nm
@@ -14,44 +15,71 @@ writes HTML pages for the repository
 .Ar repodir
 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
+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
+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, for example a
-git push \-\-force can screw this up.
+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 HEAD commit, linking to the file.
+List of files in the latest tree, linking to the file.
 .It log.html
-List of commits in order of most recent to old of the commits (top to bottom),
-each commit links to a page with a diff and diffstat of the commit.
+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 file 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.
+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 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 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 name. The suffix ".git" is
-removed from the basename, this is commonly used for "bare" repos.
+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 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 repo).
 description
@@ -61,12 +89,15 @@ 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
-32x32 logo.
 .It favicon.png
 favicon image.
+.It logo.png
+32x32 logo.
 .It style.css
 CSS stylesheet.
 .El