GitList: A PHP Web Viewer for Multiple Git Repositories

The gap GitList fills between git and a browser

A directory of bare repositories on a server is easy to create and awkward to read. Gitweb has covered that ground for years, and the README's own comparison point is implicit: GitList is a PHP application that renders repositories in a browser with commit history, blame, diffs, multiple branches and multiple tags. It is aimed at teams or individuals who host their own git remotes and want a web view over them without running a full forge.

The scope is deliberately narrow. The feature list covers browsing, history, blame, diff, RSS and Atom feeds, syntax highlighting through CodeMirror or Ace, and repository statistics. There is no mention of merge requests, code review, issue tracking or authentication roles. If you need those, GitList is a viewer, not a collaboration platform, and the README does not pretend otherwise.

Symfony, Twig and AssetMapper: how the pieces fit

GitList runs on the Symfony framework with the Twig template engine, and the README states that this is what makes it easy to install and customize. The frontend is Bootstrap-based. Assets are handled by Symfony AssetMapper, so the README says there is no bundler and no Node.js in the asset pipeline. Stylesheets are compiled by symfonycasts/sass-bundle, which downloads a standalone Sass binary into var/dart-sass on first use. In the Docker setup that directory is a named volume rather than part of the bind mount, so the container and the host each keep a build matching their own C library.

Two details in the README show where the asset pipeline has edges. Bootstrap appears twice on purpose: the twbs/bootstrap package provides Sass sources the theme customizes, and the importmap.php entry provides the browser module, and the README asks that both stay pinned to the same version. The Ace and CodeMirror runtimes live in public/vendor because both resolve the URLs of their syntax modes at runtime, so the asset mapper cannot rename their files. That directory is committed and regenerated with bin/vendor-assets. This is a reasonable design, but it means an asset upgrade is not a single version bump.

Installing GitList from a release zip

The README is explicit that you should download the latest release or the nightly build and decompress it, and warns against using the source release or a branch or tag from GitHub, which it says is not suited for end-users. Requirements are PHP 8.4 with php-xml and php-mbstring, git 2, and a webserver such as Apache or nginx. The target folder in the example is /var/www/gitlist.

After unpacking, configure where repositories live. The README offers two routes: edit config/config.yml, or export DEFAULT_REPOSITORY_DIR with the directory containing your repositories. The README's own example for the cache and log folders is reproduced below.

cd /var/www/gitlist
mkdir -p var/cache
chmod 777 var/cache
mkdir -p var/log
chmod 777 var/log

Those four lines create the cache and log directories and give them read and write permissions for the web server user. The README uses 777 in its example, which is broad; on a shared host you may want tighter ownership instead. Finally point the webserver document root at /var/www/gitlist/public, where index.php lives. Once that is done, the README says installation is complete, and it points to a Troubleshooting wiki page if it is not. A first real use is simply opening the site root in a browser and clicking into a repository to read a file at a given revision, then following the commit history and a diff.

The Docker Compose file is for development, not deployment

The repository ships a docker-compose.yml with two services: webserver, built from docker/nginx/, and php-fpm, built from docker/php-fpm/, with a 1GB shm_size and the repository bind-mounted at /application. The README frames this configuration as intended for development purposes, and says it contains a PHP image with all necessary extensions, including the headless Chromium and chromedriver binaries used by the end-to-end test suite.

That distinction matters. If you want GitList in production, the release zip plus your own webserver is the path the README describes. The Compose file is the path for working on GitList itself. The setup script in the README is short.

git clone https://github.com/klaussilveira/gitlist.git
make setup

After that, the README says to run the test suite to make sure everything is in order, first make test and then make acceptance. The end-to-end suite lives in tests/e2e and runs on Symfony Panther, with JavaScript-free pages driven over plain HTTP and the rest through headless Chromium; both share a server Panther starts on port 9080 against the repositories in tests/fixtures. Running it outside the container needs chromedriver on your PATH. The README also documents make watch for keeping stylesheets compiling while you work on them, and make help to list the other commands.

Where GitList is the wrong tool

The README's feature list is the honest boundary. There is no authentication layer, no permissions model, no pull request workflow and no issue tracker documented. A repository viewer that serves every repository under a configured directory is a poor fit for anything that must be private per user, and the install steps do not describe how to restrict who sees what. If that is a requirement, GitList is the wrong starting point.

There is also a version question the README raises without resolving. It notes that GitList was born in May 2012 on Silex, that the PHP ecosystem changed enough to make maintenance time consuming, and that 2.0 moved to Symfony 6 while 3.0 follows Symfony 8. The legacy branch remains available and the README says the project will try to keep it secure and working on newer PHP versions. The recent releases include 3.0.0-beta2 and 3.0.0-beta alongside the stable 2.0.1, so anyone deploying today has to choose between a stable line and a beta that tracks a newer framework. The README does not document a rollback procedure between them.

GitList against Gitea and Gitweb

Gitea is the alternative most people will weigh, and the difference is architectural rather than cosmetic. Gitea is a self-hosted forge: it owns users, issues and pull requests, and typically stores its own database. GitList owns none of that. It reads repositories that already exist on disk and renders them. If your repositories live in a Gitolite or plain SSH setup and you only want a read view, GitList adds one PHP application and no database.

Gitweb is the closer comparison, since both are viewers. Gitweb is the Perl tool that ships with git itself, so it is present wherever git is installed and needs no separate release download. GitList trades that ubiquity for a Symfony and Twig codebase, Bootstrap theming, and an asset pipeline that a PHP developer can modify. The README's customization and troubleshooting pages are the entry points for that work. Neither tool gives you a forge; the choice is between the one that comes with git and the one you can restyle in Twig.

Maintenance, licence and the upgrade bill

The repository is not archived, and the last push was on 2026-09-09, with 3.0.0-beta2 published the same day and 2.0.1 published minutes earlier. That is recent activity, and the release cadence shows the project moving 2.0 and 3.0 lines in parallel.

Upgrade cost is where GitList asks for attention. The README describes a deliberate effort to keep the legacy branch working on newer PHP versions, which is a maintenance commitment the project has taken on rather than a feature. On the current line, PHP 8.4 is the stated requirement, and 3.0 follows Symfony 8, so a PHP version bump on your server can force a GitList version decision. The asset pipeline adds its own constraints: Bootstrap must stay pinned to the same version in twbs/bootstrap and importmap.php, and public/vendor is regenerated with bin/vendor-assets rather than resolved by the asset mapper. The README also notes that the icon sprite in assets/themes/default/templates/icons.html.twig derives from Ionicons 4.6.3 under the MIT licence, a separate licence from the project's own.

GitList itself is licensed BSD-3-Clause, which is permissive and generally allows modification and redistribution with the licence and copyright notice retained. That is a general description of the licence family, not legal advice; check the LICENSE file and your own obligations before redistributing a modified build.

Editorial conclusion

Adopt GitList if you already run PHP 8.4 and git 2 on a server and want a read-only browser over a directory of bare repositories, without a database or a background service. It is the wrong tool if you need pull requests, issue tracking or write access from the browser, since the README lists none of those. Before committing, verify that DEFAULT_REPOSITORY_DIR or config/config.yml points at repositories readable by the web server user, and that var/cache and var/log are writable, because those are the two things the install steps depend on. Also decide between the stable 2.0.1 release and the 3.0.0-beta2 line, which targets Symfony 8.

Frequently asked questions

Official sources

1. klaussilveira/gitlist on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases