logo

stagit

STAtic GIT web view generator (in C) git clone https://hacktivis.me/git/stagit.git

stagit.1 (3509B)

    

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