Gitgo

A static site generator for Git repositories. Creates a fast and beautiful web interface for browsing code, without server-side processing or JS needed.

Static Git Pages

In a world of heavy and complex git hosting platforms, Gitgo offers a fresh breath of air. Static pages have a few key advantages:

• Scalability: Serve from any static host.
• Simplicity: No server-side processing, no runtime dependencies.
• Performance: Pages load instantly.
• Security: Minimal attack surface.
• No JS Required: Works with any browser, including the likes of Lynx.

One tradeoff is that pages must be regenerated after each push. Generation time grows with repository size, so Gitgo is currently best suited for small repositories rather than massive monorepos.

What Makes Gitgo Different?

Originally, this project was inspired by stagit (written in C). Gitgo modernizes this concept: It is written in Go, features precalculated syntax highlighting, and a beautiful modern user interface.

Gitgo is ideal for anyone who values lightweight, performant git browsing over feature-heavy platforms. What's more, tt easy to extend.

Requirements

• Go: You must have Go installed locally on your system (version 1.23 or later)
• libgit2: You must have libgit2 v1.5.x installed locally on your system
  • Note: git2go v34 specifically requires libgit2 v1.5.x
  • Note: git2go is no longer actively maintained, so you may need to build libgit2 v1.5.0 from source
  • If you have a different version, you may need to install libgit2 v1.5.x or downgrade:

    # On macOS with Homebrew
    brew uninstall libgit2
    brew install libgit2@1.5

• Go package: github.com/libgit2/git2go/v34

Building libgit2 v1.5.0 from Source

If the Homebrew version doesn't work (since git2go is no longer maintained), you can build libgit2 v1.5.0 manually:

# 1. Clone libgit2
git clone https://github.com/libgit2/libgit2.git
cd libgit2

# 2. Checkout v1.5.0
git checkout v1.5.0

# 3. Build libgit2
mkdir build
cd build
cmake ..
cmake --build .

# 4. Note the path to the build directory (e.g., /Users/username/personal/libgit2/build)

Then when building gitgo, use the PKG_CONFIG_PATH to point to your libgit2 build:

PKG_CONFIG_PATH=/path/to/libgit2/build make

For example:

PKG_CONFIG_PATH=/Users/henrik/personal/libgit2/build make

Usage

1. Obtain a copy of this repo: git clone https://github.com/hltk/gitgo.git

2. Build the program:

   # If libgit2 v1.5.x is installed system-wide
   make
   
   # If you have a custom libgit2 build (e.g., in /path/to/libgit2)
   PKG_CONFIG_PATH=/path/to/libgit2/build LIBGIT2_PATH=/path/to/libgit2 make

3. Run ./gitgo with a git repository path. The program accepts the following optional flags:

   • --destdir: Directory where static pages will be stored (default: build)
   • --installdir: Directory containing the templates/ folder (default: current directory)

Examples

Basic usage with defaults (outputs to build/ directory):

./gitgo ../rustgrad
./gitgo .

Custom output directory:

./gitgo --destdir output ../rustgrad
./gitgo --destdir /path/to/output ../rustgrad

Custom installation directory (if templates are installed elsewhere):

./gitgo --installdir /usr/share/gitgo ../rustgrad

4. There is an optional extra step: install gitgo for all users with the command make install

If there is a logo.png file in the installation directory, the program will detect it, and add it to every page.

Preview Generated Pages

To preview the generated static pages locally:

make serve

This will start a web server on http://localhost:8000 serving the build/ directory. Open that URL in your browser to view the generated pages.

Testing

Gitgo includes comprehensive test coverage for all major components. The test suite is organized into four main test files:

• util_test.go - Tests for utility functions
• git_test.go - Tests for Git operations
• main_test.go - Integration tests for the main application logic
• cmd/serve/server_test.go - Tests for the HTTP server functionality

Running Tests

Since gitgo depends on libgit2, you need to set the appropriate environment variables when running tests:

PKG_CONFIG_PATH=/path/to/libgit2/build \
CGO_CFLAGS="-I/path/to/libgit2/include" \
CGO_LDFLAGS="-L/path/to/libgit2/build -Wl,-rpath,/path/to/libgit2/build" \
go test ./...

Run with verbose output:

PKG_CONFIG_PATH=/path/to/libgit2/build \
CGO_CFLAGS="-I/path/to/libgit2/include" \
CGO_LDFLAGS="-L/path/to/libgit2/build -Wl,-rpath,/path/to/libgit2/build" \
go test -v ./...

The server tests can be run independently without libgit2:

go test -v ./cmd/serve/

License

Gitgo retains the MIT/X Consortium License of stagit.

Authors

• Henrik Aalto