Browse a Git Repository Locally with git instaweb

git instaweb spins up a throwaway gitweb site so you can click through a repository instead of squinting at the terminal. It starts a temporary gitweb site for the repository you are working in, lets you open it in a browser or copy its URL, and stops the server again afterwards. Allow about ten minutes. This guide uses the installed Git 2.43.0 behaviour.

• You need: Git with the git instaweb command, a repository, gitweb, and one of the supported web servers.
• What it will not do: publish your repository to a hosting service. The command creates and manages a local web server only.

Treat the browser endpoint as a view of repository data, though: do not bind it to a network interface unless you have deliberately planned who may reach it.

1. Enter the repository you want to inspect

Run git instaweb from inside the working repository. Confirm the repository first so you do not accidentally inspect a parent directory or the wrong checkout:

$ cd /path/to/your/repository
$ git rev-parse --show-toplevel
/path/to/your/repository

Use an ordinary user account. Starting the viewer normally needs no sudo. Running it as root can create root-owned generated files and makes the browser service harder to understand later.

2. Start the local viewer

Use --local and choose an unused high port. Explicit options make the network boundary and address easy to review:

$ git instaweb --local --port=4321

In the installed implementation, --local binds the server to 127.0.0.1 and the default port would be 1234. The command uses lighttpd by default. If the browser helper cannot open a window, the URL is printed to standard output; visit http://127.0.0.1:4321/ in a browser on the same machine.

Checkpoint: the page should show gitweb for the repository, with its refs, history and files available to browse. If port 4321 is already in use, stop and choose another port rather than killing an unrelated process.

3. Choose a browser explicitly when needed

The --browser value is passed to Git's git web--browse helper, which is useful on a headless machine, over SSH, or when several browsers are installed:

$ git instaweb --local --port=4321 --browser=false

A browser helper that fails to launch does not necessarily mean gitweb failed. Use the URL printed by the command and test it from the machine running the server. To configure the browser persistently, the repository's web.browser setting works as a fallback, but a repository-specific instaweb.browser setting takes precedence.

4. Select another supported server

If the default server is unavailable, pass a supported HTTP daemon command with --httpd. The installed manual lists apache2, lighttpd, mongoose, plackup, python and webrick. This example asks for Python's server mode:

$ git instaweb --local --httpd=python --port=4321

Do not assume every listed daemon is installed, or that every version accepts identical options. If startup fails, check the executable first:

$ command -v python
/usr/bin/python

The command appends its generated configuration file to the HTTP daemon command line. For Apache, --module-path selects the module directory, defaulting to /usr/lib/apache2/modules on this installation. Apache setup is more involved than the default and may need system packages or permissions. Keep this short-lived inspection separate from a production web-service configuration.

5. Reuse the repository configuration

For repeated inspections, put only stable choices in the repository's .git/config. The manual supports an instaweb section:

[instaweb]
        local = true
        httpd = lighttpd
        port = 4321
        browser = false

Check what Git will read before changing anything:

$ git config --local --get-regexp '^instaweb\.'
instaweb.local true
instaweb.httpd lighttpd
instaweb.port 4321
instaweb.browser false

The exact output depends on your configuration. This changes repository metadata, so make the change deliberately and review the diff with git config --local --list. To remove a setting you no longer want, use the matching git config --local --unset command:

$ git config --local --unset instaweb.port

No elevated privilege is needed for a normal repository. Do not put credentials or a publicly reachable address in this section.

6. Stop the server when finished

Stopping is a separate operation. From the same repository, run:

$ git instaweb --stop

This stops the HTTP daemon but does not close the browser window and does not regenerate startup configuration. Closing the browser alone is not enough: the server may still be listening. If you changed the configuration and want it generated again while restarting, use:

$ git instaweb --restart

Before restarting, check that you are still in the intended repository. If a start command failed, inspect the reported daemon error and the selected port; do not repeatedly restart an unrelated service. There is no content rollback needed for starting or stopping. If you added local configuration in step 5, undo it with the corresponding git config --local --unset command.

Common traps

• It opens the wrong page. Confirm git rev-parse --show-toplevel and remember gitweb shows the repository, not an arbitrary directory.
• The port is busy. Select another port, such as 4322. Do not kill a process merely because it owns 1234.
• The browser does not open. Use the printed URL, or pass a browser understood by git web--browse. A headless host needs a browser on the client side or an SSH forwarding arrangement.
• Another machine cannot connect. --local intentionally restricts access to 127.0.0.1. Removing it changes your exposure; only do that with a firewall and access plan.

Done means

• Gitweb reachable. Gitweb displayed the intended repository on a chosen local port.
• Bound locally. The server was bound to 127.0.0.1 unless broader access was an explicit decision.
• Daemon known. You know which daemon and browser helper were selected.
• Config reviewed. Any repository-local configuration is recorded, understood and removable.
• Server stopped. git instaweb --stop completed when browsing was finished.