git-instaweb
Browse Git repository in web browser
TLDR
Launch a GitWeb server for the current Git repository
Listen only on localhost
Listen on a specific port
Use a specified HTTP daemon
Also auto-launch a web browser
Stop the currently running GitWeb server
Restart the currently running GitWeb server
SYNOPSIS
git instaweb [--local] [--httpd=<command>] [--port=<port>] [--browser=<browser>] [--config=<name>=<value>] [--start] [--stop] [--restart] [--dry-run] [--default]
PARAMETERS
--local
Binds the web server only to the local IP address (127.0.0.1).
--httpd=<command>
Specifies the HTTP daemon to use. Common choices include lighttpd, apache2, webrick, or python.
--port=<port>
Sets the port number for the web server to listen on. Default is usually 1234.
--browser=<browser>
Specifies the web browser to launch. Uses the system default if not specified.
--config=<name>=<value>
Passes a configuration variable directly to the web server being launched.
--start
Starts the web server (this is the default action if no other action is specified).
--stop
Stops a currently running git-instaweb server instance.
--restart
Restarts a running git-instaweb server.
--dry-run
Shows what commands would be executed without actually starting or stopping the server.
--default
Makes the currently specified --httpd and --port the default for future git-instaweb invocations, persisting them in Git configuration.
DESCRIPTION
git-instaweb is a convenient Git command that sets up and starts a local web server to browse the current Git repository in a web browser. It automates the process of making your repository's history, commits, branches, and files viewable through a simple web interface. This command typically leverages lightweight web servers like Lighttpd, Apache, Webrick, or Python's built-in HTTP server, detecting which is available on your system. It automatically launches your default web browser to the correct URL once the server is running. This functionality is invaluable for quick, on-the-fly repository exploration, sharing a local view of a project, or demonstrating Git features without needing a full-fledged Git web frontend. When you exit, git-instaweb gracefully stops the server process, cleaning up temporary resources. It provides a quick and accessible way to visualize your project's history and structure.
CAVEATS
Requires a compatible web server (like lighttpd, apache2, webrick, or python) to be installed and available on the system.
Binding to privileged ports (below 1024) may require elevated permissions.
The web interface provided is basic and not intended for public production use like a full Git hosting solution.
Ensure the chosen browser or its executable is in your system's PATH.
CONFIGURATION PERSISTENCE
You can configure git-instaweb's default behavior by setting Git configuration variables. For instance, git config --global instaweb.httpd lighttpd will make Lighttpd your preferred web server for instaweb globally. Similarly, git config --global instaweb.port 8000 will set a default port. The --default option is a convenient shortcut to persist the current --httpd and --port settings for future use.
SUPPORTED WEB SERVERS
git-instaweb has built-in detection and support for several common web servers: lighttpd, apache2, webrick (Ruby's simple server), and python's built-in HTTP server. It attempts to find an available one in your system's PATH. If none are found, it may default to the Python server or prompt an error. You can explicitly specify your choice using the --httpd option.
HISTORY
git-instaweb was introduced to Git around version 1.5.0 in late 2006, aiming to simplify local repository browsing. Its primary goal was to provide a quick, temporary web interface for Git repositories without requiring complex manual web server setup. Initially, it often leveraged gitweb (Git's official CGI-based web interface) by setting up a minimal environment for it. Over time, support for various lightweight and commonly available web servers like Lighttpd, Webrick, and Python's built-in server was added, reflecting a broader compatibility and ease-of-use focus. Its development has consistently targeted a frictionless user experience for quick, on-the-fly repository inspection.
SEE ALSO
gitweb(1), git-config(1), git-daemon(1), git(1)