README 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. stagit
  2. ------
  3. static git page generator.
  4. It generates static HTML pages for a git repository.
  5. gearsix changes
  6. ---------------
  7. Mostly just changes to the html templating.
  8. stagit-index.c
  9. - changed description value
  10. - added the option for contain details
  11. - changed favicon.png -> /logo.png
  12. - changed style.css -> /style.css
  13. - added #logo id to td displaying logo
  14. - added "binary" (argv[0]) for error messages "$binary: ..."
  15. - added optional "contact" row below description in table header
  16. - split repo list into "original" and "forks", see "writebody()"
  17. stagit.c
  18. - added seperator between Refs | Atom
  19. - added atom.xml feed link to menu
  20. - changed favicon.png -> logo.png
  21. - added rootpath ("/")
  22. - logo.png & style.css paths are prepended with rootpath value
  23. - added #logo id to td displaying logo
  24. - added "forked from ..." in description (if repo is fork)
  25. - added index.html for repo pages that redirect to ./log.html
  26. misc
  27. - changed logo size to 50x50
  28. - moved style.css -> style-default.css
  29. - added style-gearsix.css
  30. Usage
  31. -----
  32. Make files per repository:
  33. $ mkdir -p htmlroot/htmlrepo1 && cd htmlroot/htmlrepo1
  34. $ stagit path/to/gitrepo1
  35. repeat for other repositories
  36. $ ...
  37. Make index file for repositories:
  38. $ cd htmlroot
  39. $ stagit-index path/to/gitrepo1 \
  40. path/to/gitrepo2 \
  41. path/to/gitrepo3 > index.html
  42. Build and install
  43. -----------------
  44. $ make
  45. # make install
  46. Dependencies
  47. ------------
  48. - C compiler (C99).
  49. - libc (tested with OpenBSD, FreeBSD, NetBSD, Linux: glibc and musl).
  50. - libgit2 (v0.22+).
  51. - POSIX make (optional).
  52. Documentation
  53. -------------
  54. See man pages: stagit(1) and stagit-index(1).
  55. Building a static binary
  56. ------------------------
  57. It may be useful to build static binaries, for example to run in a chroot.
  58. It can be done like this at the time of writing (v0.24):
  59. cd libgit2-src
  60. # change the options in the CMake file: CMakeLists.txt
  61. BUILD_SHARED_LIBS to OFF (static)
  62. CURL to OFF (not needed)
  63. USE_SSH OFF (not needed)
  64. THREADSAFE OFF (not needed)
  65. USE_OPENSSL OFF (not needed, use builtin)
  66. mkdir -p build && cd build
  67. cmake ../
  68. make
  69. make install
  70. Extract owner field from git config
  71. -----------------------------------
  72. A way to extract the gitweb owner for example in the format:
  73. [gitweb]
  74. owner = Name here
  75. Script:
  76. #!/bin/sh
  77. awk '/^[ ]*owner[ ]=/ {
  78. sub(/^[^=]*=[ ]*/, "");
  79. print $0;
  80. }'
  81. Set clone URL for a directory of repos
  82. --------------------------------------
  83. #!/bin/sh
  84. cd "$dir"
  85. for i in *; do
  86. test -d "$i" && echo "git://git.codemadness.org/$i" > "$i/url"
  87. done
  88. Update files on git push
  89. ------------------------
  90. Using a post-receive hook the static files can be automatically updated.
  91. Keep in mind git push -f can change the history and the commits may need
  92. to be recreated. This is because stagit checks if a commit file already
  93. exists. It also has a cache (-c) option which can conflict with the new
  94. history. See stagit(1).
  95. git post-receive hook (repo/.git/hooks/post-receive):
  96. #!/bin/sh
  97. # detect git push -f
  98. force=0
  99. while read -r old new ref; do
  100. hasrevs=$(git rev-list "$old" "^$new" | sed 1q)
  101. if test -n "$hasrevs"; then
  102. force=1
  103. break
  104. fi
  105. done
  106. # remove commits and .cache on git push -f
  107. #if test "$force" = "1"; then
  108. # ...
  109. #fi
  110. # see example_create.sh for normal creation of the files.
  111. Create .tar.gz archives by tag
  112. ------------------------------
  113. #!/bin/sh
  114. name="stagit"
  115. mkdir -p archives
  116. git tag -l | while read -r t; do
  117. f="archives/${name}-$(echo "${t}" | tr '/' '_').tar.gz"
  118. test -f "${f}" && continue
  119. git archive \
  120. --format tar.gz \
  121. --prefix "${t}/" \
  122. -o "${f}" \
  123. -- \
  124. "${t}"
  125. done
  126. Features
  127. --------
  128. - Log of all commits from HEAD.
  129. - Log and diffstat per commit.
  130. - Show file tree with linkable line numbers.
  131. - Show references: local branches and tags.
  132. - Detect README and LICENSE file from HEAD and link it as a webpage.
  133. - Detect submodules (.gitmodules file) from HEAD and link it as a webpage.
  134. - Atom feed of the commit log (atom.xml).
  135. - Atom feed of the tags/refs (tags.xml).
  136. - Make index page for multiple repositories with stagit-index.
  137. - After generating the pages (relatively slow) serving the files is very fast,
  138. simple and requires little resources (because the content is static), only
  139. a HTTP file server is required.
  140. - Usable with text-browsers such as dillo, links, lynx and w3m.
  141. Cons
  142. ----
  143. - Not suitable for large repositories (2000+ commits), because diffstats are
  144. an expensive operation, the cache (-c flag) is a workaround for this in
  145. some cases.
  146. - Not suitable for large repositories with many files, because all files are
  147. written for each execution of stagit. This is because stagit shows the lines
  148. of textfiles and there is no "cache" for file metadata (this would add more
  149. complexity to the code).
  150. - Not suitable for repositories with many branches, a quite linear history is
  151. assumed (from HEAD).
  152. In these cases it is better to just use cgit or possibly change stagit to
  153. run as a CGI program.
  154. - Relatively slow to run the first time (about 3 seconds for sbase,
  155. 1500+ commits), incremental updates are faster.
  156. - Does not support some of the dynamic features cgit has, like:
  157. - Snapshot tarballs per commit.
  158. - File tree per commit.
  159. - History log of branches diverged from HEAD.
  160. - Stats (git shortlog -s).
  161. This is by design, just use git locally.