Documentation/config-gitweb.txt - gerrit - Git at Google


            
            :linkattrs:

            
            == Gitweb Integration


            Gerrit Code Review can manage and generate hyperlinks to gitweb,

            
            allowing users to jump from Gerrit content to the same information,

            
            but shown by gitweb.


            === Internal/Managed gitweb


            In the internal configuration, Gerrit inspects the request, enforces

            
            its project level access controls, and directly executes `gitweb.cgi`

            
            if the user is authorized to view the page.


            To enable the internal configuration, set

            
            link:config-gerrit.html#gitweb.cgi[gitweb.cgi] with the path of the

            
            installed CGI.  This defaults to `/usr/lib/cgi-bin/gitweb.cgi`,

            
            which is a common installation path for the 'gitweb' package on

            
            Linux distributions.


            ----

            
              git config -f $site_path/etc/gerrit.config gitweb.type gitweb

            
              git config -f $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi

            
              git config -f $site_path/etc/gerrit.config --unset gitweb.url

            
            ----


            Alternatively, if Gerrit is served behind reverse proxy, it can

            
            generate different URLs for gitweb's links (they need to be

            
            rewritten to `<gerrit>/gitweb?args` on the web server). This allows

            
            for serving gitweb under a different URL than the Gerrit instance.

            
            To enable this feature, set both: `gitweb.cgi` and `gitweb.url`.


            ----

            
              git config -f $site_path/etc/gerrit.config gitweb.type gitweb

            
              git config -f $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi

            
              git config -f $site_path/etc/gerrit.config gitweb.url /pretty/path/to/gitweb

            
            ----


            After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must

            
            be restarted and clients must reload the host page to see the change.


            ==== Configuration


            Most of the gitweb configuration file is handled automatically

            
            by Gerrit Code Review.  Site specific overrides can be placed in

            
            `'$site_path'/etc/gitweb_config.perl`, as this file is loaded as

            
            part of the generated configuration file.


            ==== Logo and CSS


            If the package-manager installed CGI (`/usr/lib/cgi-bin/gitweb.cgi`)

            
            is being used, the stock CSS and logo files will be served from

            
            either `/usr/share/gitweb` or `/var/www`.


            Otherwise, Gerrit expects `gitweb.css` and `git-logo.png` to be found

            
            in the same directory as the CGI script itself.  This matches with

            
            the default source code distribution, and most custom installations.


            ==== Access Control


            Access controls for internally managed gitweb page views are enforced

            
            using the standard project READ +1 permission.


            Also, in order for a user to be able to view any gitweb information for a

            
            project, the user must be able to read all references (including

            
            refs/meta/config, refs/meta/dashboards/*, etc.). If you have exclusive read

            
            permissions for any references, make sure to include all parties that should be

            
            able to read the gitweb info for any of the branches in that project.


            === External/Unmanaged gitweb


            For the external configuration, gitweb runs under the control of an

            
            external web server, and Gerrit access controls are not enforced. Gerrit

            
            provides configuration parameters for integration with gitweb.


            [[linuxGitWeb]]

            
            ==== Linux Installation


            ===== Install Gitweb


            On Ubuntu:


            ----

            
              sudo apt-get install gitweb

            
            ----


            With Yum:


            ----

            
              yum install gitweb

            
            ----


            ===== Configure Gitweb


            Update `/etc/gitweb.conf`, add the public GIT repositories:


            ----

            
            $projectroot = "/var/www/repo/";


            # directory to use for temp files

            
            $git_temp = "/tmp";


            # target of the home link on top of all pages

            
            #$home_link = $my_uri || "/";


            # html text to include at home page

            
            $home_text = "indextext.html";


            # file with project list; by default, simply scan the projectroot dir.

            
            $projects_list = $projectroot;


            # stylesheet to use

            
            # I took off the prefix / of the following path to put these files inside gitweb directory directly

            
            $stylesheet = "gitweb.css";


            # logo to use

            
            $logo = "git-logo.png";


            # the favicon

            
            $favicon = "git-favicon.png";

            
            ----


            ==== Configure & Restart Apache Web Server


            ===== Configure Apache


            Link gitweb to `/var/www/gitweb`, check `/etc/gitweb.conf` if unsure of paths:


            ----

            
              sudo ln -s /usr/share/gitweb /var/www/gitweb

            
            ----


            Add the gitweb directory to the Apache configuration by creating a "gitweb"

            
            file inside the Apache conf.d directory:


            ----

            
              touch /etc/apache/conf.d/gitweb

            
            ----


            Add the following to /etc/apache/conf.d/gitweb:


            ----

            
            Alias /gitweb /var/www/gitweb


            Options Indexes FollowSymlinks ExecCGI

            
            DirectoryIndex /cgi-bin/gitweb.cgi

            
            AllowOverride None

            
            ----


            [NOTE]

            
            This may have already been added by yum/apt-get. If that's the case, leave as

            
            is.


            ===== Restart the Apache Web Server


            ----

            
              sudo /etc/init.d/apache2 restart

            
            ----


            Now you should be able to view your repository projects online:


            link:http://localhost/gitweb[http://localhost/gitweb]


            [[WindowsGitWeb]]

            
            ==== Windows Installation


            Instructions are available for installing the gitweb module distributed with

            
            MsysGit:


            link:https://github.com/msysgit/msysgit/wiki/GitWeb[GitWeb,role=external,window=_blank]


            If you don't have Apache installed, you can download the appropriate build for

            
            Windows from link:http://www.apachelounge.com/download[apachelounge.org].


            After you have installed Apache, you will want to create a link:http://httpd.apache.org/docs/2.0/platform/windows.html#winsvc[new service user

            
            account,role=external,window=_blank] to use with Apache.


            If you're still having difficulty setting up permissions, you may find this

            
            tech note useful for configuring Apache Service to run under another account.

            
            You must grant the new account link:http://technet.microsoft.com/en-us/library/cc794944(WS.10).aspx["run as service",role=external,window=_blank] permission:


            The gitweb version in msysgit is missing several important and required

            
            perl modules, including CGI.pm. The perl included with the msysgit distro 1.7.8

            
            is broken.. The link:http://groups.google.com/group/msysgit/browse_thread/thread/ba3501f1f0ed95af[unicore folder is missing along with utf8_heavy.pl and CGI.pm,role=external,window=_blank]. You can

            
            verify by checking for perl modules. From an msys console, execute the

            
            following to check:


            ----

            
              perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""

            
            ----


            You may encounter the following exception:


            ----

            
            $ perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""

            
            Can't locate CGI.pm in @INC (@INC contains: /usr/lib/perl5/5.8.8/msys

            
            /usr/lib/p erl5/5.8.8 /usr/lib/perl5/site_perl/5.8.8/msys

            
            /usr/lib/perl5/site_perl/5.8.8 /u sr/lib/perl5/site_perl .). BEGIN

            
            failed--compilation aborted.

            
            ----


            If you're missing CGI.pm, you'll have to deploy the module to the msys

            
            environment: You will have to retrieve them from the 5.8.8 distro on :


            http://strawberryperl.com/releases.html[role=external,window=_blank]


            File: strawberry-perl-5.8.8.3.zip


            contents: `bin/` `lib/` `site/`


            copy the contents of lib into `msysgit/lib/perl5/5.8.8` and overwrite existing files.


            **NOTE**: Windows is not recommended as a server-side platform for

            
            running Gerrit Code Review, because of the lack of adoption from the Gerrit Community,

            
            incomplete functional validation and lack of security testing. Gerrit on

            
            Windows Server is not actively supported even though it may still be

            
            fully or partially functioning as expected.


            ==== Enable Gitweb Integration


            To enable the external gitweb integration, set

            
            link:config-gerrit.html#gitweb.url[gitweb.url] with the URL of your

            
            gitweb CGI.


            The CGI's `$projectroot` should be the same directory as

            
            gerrit.basePath, or a fairly current replica.  If a replica is

            
            being used, ensure it uses a full mirror, so the `+refs/changes/*+`

            
            namespace is available.


            ----

            
              git config -f $site_path/etc/gerrit.config gitweb.type gitweb

            
              git config -f $site_path/etc/gerrit.config --unset gitweb.cgi

            
              git config -f $site_path/etc/gerrit.config gitweb.url https://gitweb.corporation.com

            
            ----


            If you're not following the traditional `\{projectName\}.git` project naming conventions,

            
            you will want to customize Gerrit to read them. Add the following:


            ----

            
              git config -f $site_path/etc/gerrit.config gitweb.type custom

            
              git config -f $site_path/etc/gerrit.config gitweb.project ?p=\${project}\;a=summary

            
              git config -f $site_path/etc/gerrit.config gitweb.revision ?p=\${project}\;a=commit\;h=\${commit}

            
              git config -f $site_path/etc/gerrit.config gitweb.branch ?p=\${project}\;a=shortlog\;h=\${branch}

            
              git config -f $site_path/etc/gerrit.config gitweb.roottree ?p=\${project}\;a=tree\;hb=\${commit}

            
              git config -f $site_path/etc/gerrit.config gitweb.file ?p=\${project}\;hb=\${commit}\;f=\${file}

            
              git config -f $site_path/etc/gerrit.config gitweb.filehistory ?p=\${project}\;a=history\;hb=\${branch}\;f=\${file}

            
            ----


            After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must

            
            be restarted and clients must reload the host page to see the change.


            Note that when using a custom gitweb configuration, values must be

            
            specified for all of the `project`, `revision`, `branch`, `roottree`,

            
            `file`, and `filehistory` settings, otherwise the configuration will

            
            not be used.


            ===== Access Control


            Gitweb access controls can be implemented using standard web server

            
            access controls.  This isn't typically integrated with Gerrit's own

            
            access controls.  Caution must be taken to ensure the controls are

            
            consistent if access needs to be restricted.


            ===== Caching Gitweb


            If your repository set is large and you are expecting a lot

            
            of users, you may want to look at the caching forks used by

            
            high-traffic sites like kernel.org or repo.or.cz.


            === Alternatives to gitweb

            
            There are other alternatives to gitweb that can also be used with

            
            Gerrit, such as cgit.


            cgit can be used by specifying `gitweb.type` to be 'cgit'.


            It is also possible to define custom patterns. Gitea can be used

            
            with custom patterns for example:


            ----

            
              git config -f $site_path/etc/gerrit.config gitweb.type custom

            
              git config -f $site_path/etc/gerrit.config gitweb.urlEncode false

            
              git config -f $site_path/etc/gerrit.config gitweb.linkname gitea

            
              git config -f $site_path/etc/gerrit.config gitweb.url https://gitea.example.org/

            
              git config -f $site_path/etc/gerrit.config gitweb.branch ${project}/src/branch/${branch}

            
              git config -f $site_path/etc/gerrit.config gitweb.file ${project}/src/commit/${hash}/${file}

            
              git config -f $site_path/etc/gerrit.config gitweb.filehistory ${project}/commits/branch/${branch}/${file}

            
              git config -f $site_path/etc/gerrit.config gitweb.project ${project}

            
              git config -f $site_path/etc/gerrit.config gitweb.revision ${project}/commit/${commit}

            
              git config -f $site_path/etc/gerrit.config gitweb.roottree ${project}/src/commit/${commit}

            
              git config -f $site_path/etc/gerrit.config gitweb.tag ${project}/src/tag/${tag}

            
            ----


            === SEE ALSO


            * link:config-gerrit.html#gitweb[Section gitweb]

            
            * link:http://git.zx2c4.com/cgit/about/[cgit,role=external,window=_blank]


            GERRIT

            
            ------

            
            Part of link:index.html[Gerrit Code Review]


            SEARCHBOX

            
            ---------
	:linkattrs:
	== Gitweb Integration

	Gerrit Code Review can manage and generate hyperlinks to gitweb,
	allowing users to jump from Gerrit content to the same information,
	but shown by gitweb.

	=== Internal/Managed gitweb

	In the internal configuration, Gerrit inspects the request, enforces
	its project level access controls, and directly executes `gitweb.cgi`
	if the user is authorized to view the page.

	To enable the internal configuration, set
	link:config-gerrit.html#gitweb.cgi[gitweb.cgi] with the path of the
	installed CGI. This defaults to `/usr/lib/cgi-bin/gitweb.cgi`,
	which is a common installation path for the 'gitweb' package on
	Linux distributions.

	----
	git config -f $site_path/etc/gerrit.config gitweb.type gitweb
	git config -f $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi
	git config -f $site_path/etc/gerrit.config --unset gitweb.url
	----

	Alternatively, if Gerrit is served behind reverse proxy, it can
	generate different URLs for gitweb's links (they need to be
	rewritten to `<gerrit>/gitweb?args` on the web server). This allows
	for serving gitweb under a different URL than the Gerrit instance.
	To enable this feature, set both: `gitweb.cgi` and `gitweb.url`.

	----
	git config -f $site_path/etc/gerrit.config gitweb.type gitweb
	git config -f $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi
	git config -f $site_path/etc/gerrit.config gitweb.url /pretty/path/to/gitweb
	----

	After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
	be restarted and clients must reload the host page to see the change.

	==== Configuration

	Most of the gitweb configuration file is handled automatically
	by Gerrit Code Review. Site specific overrides can be placed in
	`'$site_path'/etc/gitweb_config.perl`, as this file is loaded as
	part of the generated configuration file.

	==== Logo and CSS

	If the package-manager installed CGI (`/usr/lib/cgi-bin/gitweb.cgi`)
	is being used, the stock CSS and logo files will be served from
	either `/usr/share/gitweb` or `/var/www`.

	Otherwise, Gerrit expects `gitweb.css` and `git-logo.png` to be found
	in the same directory as the CGI script itself. This matches with
	the default source code distribution, and most custom installations.

	==== Access Control

	Access controls for internally managed gitweb page views are enforced
	using the standard project READ +1 permission.

	Also, in order for a user to be able to view any gitweb information for a
	project, the user must be able to read all references (including
	refs/meta/config, refs/meta/dashboards/*, etc.). If you have exclusive read
	permissions for any references, make sure to include all parties that should be
	able to read the gitweb info for any of the branches in that project.

	=== External/Unmanaged gitweb

	For the external configuration, gitweb runs under the control of an
	external web server, and Gerrit access controls are not enforced. Gerrit
	provides configuration parameters for integration with gitweb.

	[[linuxGitWeb]]
	==== Linux Installation

	===== Install Gitweb

	On Ubuntu:

	----
	sudo apt-get install gitweb
	----

	With Yum:

	----
	yum install gitweb
	----

	===== Configure Gitweb


	Update `/etc/gitweb.conf`, add the public GIT repositories:

	----
	$projectroot = "/var/www/repo/";

	# directory to use for temp files
	$git_temp = "/tmp";

	# target of the home link on top of all pages
	#$home_link = $my_uri \|\| "/";

	# html text to include at home page
	$home_text = "indextext.html";

	# file with project list; by default, simply scan the projectroot dir.
	$projects_list = $projectroot;

	# stylesheet to use
	# I took off the prefix / of the following path to put these files inside gitweb directory directly
	$stylesheet = "gitweb.css";

	# logo to use
	$logo = "git-logo.png";

	# the favicon
	$favicon = "git-favicon.png";
	----

	==== Configure & Restart Apache Web Server

	===== Configure Apache


	Link gitweb to `/var/www/gitweb`, check `/etc/gitweb.conf` if unsure of paths:

	----
	sudo ln -s /usr/share/gitweb /var/www/gitweb
	----

	Add the gitweb directory to the Apache configuration by creating a "gitweb"
	file inside the Apache conf.d directory:

	----
	touch /etc/apache/conf.d/gitweb
	----

	Add the following to /etc/apache/conf.d/gitweb:

	----
	Alias /gitweb /var/www/gitweb

	Options Indexes FollowSymlinks ExecCGI
	DirectoryIndex /cgi-bin/gitweb.cgi
	AllowOverride None
	----

	[NOTE]
	This may have already been added by yum/apt-get. If that's the case, leave as
	is.

	===== Restart the Apache Web Server

	----
	sudo /etc/init.d/apache2 restart
	----

	Now you should be able to view your repository projects online:

	link:http://localhost/gitweb[http://localhost/gitweb]

	[[WindowsGitWeb]]
	==== Windows Installation

	Instructions are available for installing the gitweb module distributed with
	MsysGit:

	link:https://github.com/msysgit/msysgit/wiki/GitWeb[GitWeb,role=external,window=_blank]

	If you don't have Apache installed, you can download the appropriate build for
	Windows from link:http://www.apachelounge.com/download[apachelounge.org].

	After you have installed Apache, you will want to create a link:http://httpd.apache.org/docs/2.0/platform/windows.html#winsvc[new service user
	account,role=external,window=_blank] to use with Apache.

	If you're still having difficulty setting up permissions, you may find this
	tech note useful for configuring Apache Service to run under another account.
	You must grant the new account link:http://technet.microsoft.com/en-us/library/cc794944(WS.10).aspx["run as service",role=external,window=_blank] permission:

	The gitweb version in msysgit is missing several important and required
	perl modules, including CGI.pm. The perl included with the msysgit distro 1.7.8
	is broken.. The link:http://groups.google.com/group/msysgit/browse_thread/thread/ba3501f1f0ed95af[unicore folder is missing along with utf8_heavy.pl and CGI.pm,role=external,window=_blank]. You can
	verify by checking for perl modules. From an msys console, execute the
	following to check:

	----
	perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""
	----

	You may encounter the following exception:

	----
	$ perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""
	Can't locate CGI.pm in @INC (@INC contains: /usr/lib/perl5/5.8.8/msys
	/usr/lib/p erl5/5.8.8 /usr/lib/perl5/site_perl/5.8.8/msys
	/usr/lib/perl5/site_perl/5.8.8 /u sr/lib/perl5/site_perl .). BEGIN
	failed--compilation aborted.
	----

	If you're missing CGI.pm, you'll have to deploy the module to the msys
	environment: You will have to retrieve them from the 5.8.8 distro on :

	http://strawberryperl.com/releases.html[role=external,window=_blank]

	File: strawberry-perl-5.8.8.3.zip

	contents: `bin/` `lib/` `site/`

	copy the contents of lib into `msysgit/lib/perl5/5.8.8` and overwrite existing files.

	NOTE: Windows is not recommended as a server-side platform for
	running Gerrit Code Review, because of the lack of adoption from the Gerrit Community,
	incomplete functional validation and lack of security testing. Gerrit on
	Windows Server is not actively supported even though it may still be
	fully or partially functioning as expected.

	==== Enable Gitweb Integration

	To enable the external gitweb integration, set
	link:config-gerrit.html#gitweb.url[gitweb.url] with the URL of your
	gitweb CGI.

	The CGI's `$projectroot` should be the same directory as
	gerrit.basePath, or a fairly current replica. If a replica is
	being used, ensure it uses a full mirror, so the `+refs/changes/*+`
	namespace is available.

	----
	git config -f $site_path/etc/gerrit.config gitweb.type gitweb
	git config -f $site_path/etc/gerrit.config --unset gitweb.cgi
	git config -f $site_path/etc/gerrit.config gitweb.url https://gitweb.corporation.com
	----

	If you're not following the traditional `\{projectName\}.git` project naming conventions,
	you will want to customize Gerrit to read them. Add the following:

	----
	git config -f $site_path/etc/gerrit.config gitweb.type custom
	git config -f $site_path/etc/gerrit.config gitweb.project ?p=\${project}\;a=summary
	git config -f $site_path/etc/gerrit.config gitweb.revision ?p=\${project}\;a=commit\;h=\${commit}
	git config -f $site_path/etc/gerrit.config gitweb.branch ?p=\${project}\;a=shortlog\;h=\${branch}
	git config -f $site_path/etc/gerrit.config gitweb.roottree ?p=\${project}\;a=tree\;hb=\${commit}
	git config -f $site_path/etc/gerrit.config gitweb.file ?p=\${project}\;hb=\${commit}\;f=\${file}
	git config -f $site_path/etc/gerrit.config gitweb.filehistory ?p=\${project}\;a=history\;hb=\${branch}\;f=\${file}
	----

	After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
	be restarted and clients must reload the host page to see the change.

	Note that when using a custom gitweb configuration, values must be
	specified for all of the `project`, `revision`, `branch`, `roottree`,
	`file`, and `filehistory` settings, otherwise the configuration will
	not be used.

	===== Access Control

	Gitweb access controls can be implemented using standard web server
	access controls. This isn't typically integrated with Gerrit's own
	access controls. Caution must be taken to ensure the controls are
	consistent if access needs to be restricted.

	===== Caching Gitweb

	If your repository set is large and you are expecting a lot
	of users, you may want to look at the caching forks used by
	high-traffic sites like kernel.org or repo.or.cz.

	=== Alternatives to gitweb
	There are other alternatives to gitweb that can also be used with
	Gerrit, such as cgit.

	cgit can be used by specifying `gitweb.type` to be 'cgit'.

	It is also possible to define custom patterns. Gitea can be used
	with custom patterns for example:

	----
	git config -f $site_path/etc/gerrit.config gitweb.type custom
	git config -f $site_path/etc/gerrit.config gitweb.urlEncode false
	git config -f $site_path/etc/gerrit.config gitweb.linkname gitea
	git config -f $site_path/etc/gerrit.config gitweb.url https://gitea.example.org/
	git config -f $site_path/etc/gerrit.config gitweb.branch ${project}/src/branch/${branch}
	git config -f $site_path/etc/gerrit.config gitweb.file ${project}/src/commit/${hash}/${file}
	git config -f $site_path/etc/gerrit.config gitweb.filehistory ${project}/commits/branch/${branch}/${file}
	git config -f $site_path/etc/gerrit.config gitweb.project ${project}
	git config -f $site_path/etc/gerrit.config gitweb.revision ${project}/commit/${commit}
	git config -f $site_path/etc/gerrit.config gitweb.roottree ${project}/src/commit/${commit}
	git config -f $site_path/etc/gerrit.config gitweb.tag ${project}/src/tag/${tag}
	----

	=== SEE ALSO

	* link:config-gerrit.html#gitweb[Section gitweb]
	* link:http://git.zx2c4.com/cgit/about/[cgit,role=external,window=_blank]

	GERRIT
	------
	Part of link:index.html[Gerrit Code Review]

	SEARCHBOX
	---------