gitweb Git Command Guide

The gitweb command provides a web interface to Git repositories using a CGI script. It allows browsing repository contents, viewing commit history, diff changes, blame information, and generating RSS/Atom feeds, typically run through web servers like Apache or nginx.

gitweb Configuration and Setup:

Quick Start with git-instaweb:

git instaweb --http=lighthttpd

Starts web server and opens gitweb in browser.

Manual CGI Setup:

cp /usr/share/gitweb/gitweb.cgi /var/www/gitweb/
cp -R /usr/share/gitweb/static/ /var/www/gitweb/

Configuration File (gitweb_config.perl):

# Repository root directory
our $projectroot = '/path/to/git/repositories';

# Site title and settings
our $site_name = 'My Git Repositories';
our $site_html_head_string = '<link rel="stylesheet" type="text/css" href="/gitweb.css"/>';
our $home_link_str = 'Back to home page';

Apache Configuration Example:

<VirtualHost *:80>
    ServerName git.example.com
    DocumentRoot /var/www/gitweb
    ScriptAlias / /usr/share/gitweb/gitweb.cgi/

    <Directory "/usr/libexec/git-core">
        Options ExecCGI
        AllowOverride None
        Require all granted
    </Directory>

    <Directory "/var/www/gitweb">
        AllowOverride None
        Require all granted
    </Directory>
</Directory>

Features and Capabilities:

Repository Browsing:

Feature	Description
Multi-Repository Display	Shows all repositories under common root
Revision Browsing	Navigate any commit, tag, or branch
File Contents	View raw or syntax-highlighted file content
Directory Tree	Browse directory structure at any revision
Commit History	Full history with author, date, and message
Branch Navigation	Switch between branches and tags
Diff Viewing	Side-by-side or unified diffs
Blame Annotation	Line-by-line attribution showing who last changed each line

Feed Generation:

• RSS Feeds: Subscribe to commit updates for any branch
• Atom Feeds: Alternative XML format for feeds
• Auto-Discovery: Browsers automatically detect available feeds

Search Capabilities:

• Commit Message Search: Find commits by content keywords
• Author/Committer Search: Filter by developer names
• Date Range Filtering: Limit results to time periods

Caution

gitweb runs as CGI and requires web server configuration. Ensure proper permissions and avoid exposing internal repositories. Consider authentication for production use.

gitweb Configuration Examples:

Basic repository listing configuration

# Show only specific repositories
our $projects_list = '/etc/gitweb-projects.list';

# Custom logo and styling
our $logo_url = '/git-logo.png';
our $favicon = '/git-favicon.png';

File content for projects.list

repo1.git Project One
repo2.git My Second Repository
utilities.git Utility Scripts

Enable blame feature

# Enable blame links (may be resource intensive)
our $feature{'blame'}{'default'} = [1];

Configure gitweb to work with gitolite

# Point to gitolite repositories
our $projectroot = '/home/gitolite/repositories';

# Use gitolite's project list
our $projects_list = '/home/gitolite/projects.list';

Set up authentication (basic auth)

AuthType Basic
AuthName "Git Repositories"
AuthUserFile /etc/gitweb-users
Require valid-user

Disable certain features for security

# Disable snapshot downloads if not needed
our $feature{'snapshot'}{'default'} = [];

Configure RSS feed limits

# Limit RSS entries to prevent large feeds
our $default_blob_plain_max_load = 10 * 1024 * 1024; # 10MB max

Tip

Use git-instaweb for quick testing. For production, set up proper web server (Apache/nginx) with appropriate permissions. Consider caching and CDN for performance.

What are the hardware requirements for gitweb?

gitweb is lightweight CGI script requiring minimal resources. Memory depends on repository sizes and concurrent users. CPU usage increases with blame operations.

How does gitweb handle large repositories?

Large repositories work but may be slow with blame features enabled. Consider disabling resource-intensive features and implementing caching in web server.

Can gitweb serve multiple repository roots?

Advanced configuration allows multiple project roots. Requires custom configuration file setup and web server aliasing for different repository groups.

What’s the relationship between gitweb and gitolite?

gitolite manages repository access control while gitweb provides browsing interface. They integrate seamlessly - gitolite controls permissions, gitweb shows content.

How do I customize gitweb styling?

Modify CSS files in static directory or use $site_html_head_string in config to include custom stylesheets. Template files are in /usr/share/gitweb directory.

Can gitweb show private repositories?

gitweb shows what web server can access. Private repositories require authentication configuration at web server level, not in gitweb itself.

How do feeds work in gitweb?

RSS/Atom feeds auto-generated per branch showing recent commits. Browsers automatically discover feeds through HTML link tags in gitweb output.

What’s the difference between gitweb and GitHub/GitLab?

gitweb is minimal interface for browsing, while GitHub/GitLab add collaboration features, pull requests, wikis, and extensive APIs beyond gitweb’s capabilities.

Can I integrate gitweb with existing web applications?

gitweb is CGI script that can be embedded in existing web applications. Use iframe embedding or link to gitweb interface from main application.

How do I troubleshoot gitweb permission issues?

Git repositories need proper permissions for web server user. Check CGI execution, file permissions, and SELinux/AppArmor policies preventing access.

Does gitweb support Git LFS (Large File Storage)?

gitweb shows LFS file existence but cannot display large file content directly. LFS pointers shown instead of actual large file content.

Can gitweb handle thousands of repositories?

Scalability depends on filesystem and web server performance. Project list caching helps but thousands of repositories may require optimized configuration.

How do I set up gitweb on Windows?

Possible with CGI-capable web servers like Apache for Windows, but Linux servers more common for gitweb deployment due to native Git integration.

What’s the security model of gitweb?

gitweb honors filesystem permissions and .htaccess files. No additional permission model - repositories accessible to web server are visible to all users.

Can gitweb show submodules?

gitweb shows submodules as regular commits but doesn’t provide seamless navigation into submodule content unless configured separately.

How do I migrate from gitweb to modern alternatives?

Replace with GitLab Community Edition, Gitea, or GitHub Enterprise. These provide gitweb features plus collaboration, CI/CD, and modern interfaces.

Why use gitweb instead of GitHub/GitLab?

gitweb is minimal, self-hosted solution requiring only web server. No external dependencies, full control, suitable for private networks or basic needs.

How do I create custom gitweb templates?

Template files in /usr/share/gitweb are readable. Make local copies, modify them, and point gitweb configuration to custom template directory.

Can gitweb handle non-bare repositories?

gitweb works with bare repositories by default. Non-bare repositories can be displayed but working directory files may interfere with repository state.

Applications of the gitweb command

1. Internal Repository Browsing: Provide web interface for team repositories without external hosting
2. Open Source Project Hosting: Simple web presence for public projects with RSS feeds for updates
3. Educational Demonstrations: Visual Git concepts for teaching version control principles
4. Legacy System Integration: Interface for older systems requiring Git repository access
5. Development Environment: Quick repository visualization during development workflows
6. Backup and Archival: Web access to archived repository collections for reference