LinuxCommandLibrary

git-instaweb

Browse Git repository in web browser

TLDR

Launch a GitWeb server for the current Git repository

$ git instaweb --start
copy

Listen only on localhost
$ git instaweb --start [[-l|--local]]
copy

Listen on a specific port
$ git instaweb --start [[-p|--port]] [1234]
copy

Use a specified HTTP daemon
$ git instaweb --start [[-d|--httpd]] [lighttpd|apache2|mongoose|plackup|webrick]
copy

Also auto-launch a web browser
$ git instaweb --start [[-b|--browser]]
copy

Stop the currently running GitWeb server
$ git instaweb --stop
copy

Restart the currently running GitWeb server
$ git instaweb --restart
copy

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)

Copied to clipboard