* Re: [RFC/PATCH] Configurable hyperlinking in gitk
From: Jakub Narebski @ 2011-09-18 18:50 UTC (permalink / raw)
To: Chris Packham; +Cc: Jeff Epler, git
In-Reply-To: <4E7467B7.1090201@gmail.com>
Chris Packham <judge.packham@gmail.com> writes:
> On 17/09/11 14:29, Jeff Epler wrote:
> > Some time ago I hardcoded this into gitk for $DAY_JOB and find it very
> > useful. I made it configurable in the hopes that it might be adopted
> > upstream. (unfortunately, the configurable version is radically
> > different from the original hard-coded version, so I can't say this
> > has had much testing yet)
>
> This is definitely something folks at my $dayjob would be interested in.
> We've already done some customisation of gitweb to do something similar.
> I'm not actually sure what the changes where or how configurable they
> are. I'll see if I can dig them out on Monday someone else might want to
> polish them into something suitable (I might do it myself if I get some
> tuits).
That would be nice. So called "committags" support was long planned
for gitweb, and even some preliminary work exists...
> > There are probably better names for the configuration options, too.
>
> It'd be nice if the config variables weren't gitk specific. .re and .sub
> could be applied to gitweb and maybe other git viewers outside of
> gig.git might decide to use them. My bikeshedding suggestion would be to
> just drop the gitk prefix and have linkify.re and linkify.sub.
Perhaps more descriptive name, i.e.
linkify.<name>.regexp
linkify.<name>.subst
would be better?
I guess that regexp is an extended regular expression, isn't it?
--
Jakub Narębski
^ permalink raw reply
* Re: [PATCH v2] Add a credential-helper for KDE
From: Jeff King @ 2011-09-18 18:49 UTC (permalink / raw)
To: Lukas Sandström; +Cc: Git Mailing List
In-Reply-To: <4E7605CA.7020204@gmail.com>
On Sun, Sep 18, 2011 at 04:52:58PM +0200, Lukas Sandström wrote:
> Right. Multiple usernames per "unique" context is supported in this version.
> I looked at the git-credential-storage helper when I wrote the first patch,
> which didn't have obvious support for multiple usernames per unique context.
Yeah, sorry about that. The -cache helper is much more fully fleshed out
(though I have improved the -store helper in the past few days to handle
multiple usernames better).
> Keeping the username outside the token is probably a good thing, but perhaps it
> should be clarified in the api-docs that multiple usernames has to be supported.
OK, I'll try to write up a clarification.
> Also; what about rejecting credentials. This code currently deletes just a
> username/password pair if a username is specified, and all credentials associated
> with the token if only --unique and --reject is specified. Is this correct/expected
> behavior?
Yes, that's what I think should happen, and what both of my helpers do.
In practice, I don't think it will be called that way by git, which
will always be rejecting a username we just tried. But I wanted to leave
things flexible in case a user wants to manually remove a credential
from a store.
> When I first wrote the helper I tried to immediately ask for a new password if a
> credential was rejected, but this didn't work with the HTTP auth code, since it
> doesn't retry the auth with the new credentials after a reject. I think it would
> be better if we asked for a new password instead of just saying "auth failed" and
> having the user retry the fetch/pull when the stored credentials are incorrect.
Yeah, I had a patch early on to retry authentication a few times before
exiting, but I wondered how helpful it was. It's usually pretty easy to
retry your command again via shell history, and sometimes looping on
asking for authentication can be annoying (because things like askpass
will actually grab the keyboard focus).
So I dunno what is best. I don't consider it a big deal, but maybe
others do.
Even if we did do the retry from git, the helper shouldn't ask
immediately for the new credential inside a --reject. It should wait to
be invoked again asking for the password. I know this may be an extra
fork/exec/startup cycle, but it keeps the interface to the helper simple
and flexible.
-Peff
^ permalink raw reply
* Re: Most elegant way to reference to SVN from GIT?
From: Jakub Narebski @ 2011-09-18 18:47 UTC (permalink / raw)
To: Manuel Reimer; +Cc: git, Jeff King
In-Reply-To: <j54keg$ug9$1@dough.gmane.org>
Manuel Reimer <Manuel.Spam@nurfuerspam.de> writes:
> Jeff King wrote:
> > You can pull their commits into git using git-svn, and then merge them.
Nb. there is also so called "remote helper" approach, where you can
use repositories using other SCM just like native remote Git
repositories. But I think it is in early beta, or even alpha stages -
- adding support for Subversion was this year Google Summer of Code
2011 project.
> Tried that, but maybe I did something wrong.
>
> If I have a git-svn repo inside my git repo, then for some reason my
> own repo doesn't known the git-svn repo. Means that I cannot push
> changes, that occured in the SVN repo, to my GIT server.
Errr... isn't it more or less expected for _any_ remote repository
added, be it native (git) or Subversion one?
Remote tracking branches are not usually pushed / fetched, unless you
clone in a mirror mode, or set refspecs for fecthing / pushing by
hand...
--
Jakub Narębski
^ permalink raw reply
* Re: [PATCH] git-web--browse: invoke kfmclient directly
From: Jeff King @ 2011-09-18 18:38 UTC (permalink / raw)
To: Chris Packham; +Cc: git, chriscool, jepler
In-Reply-To: <1316341224-4359-1-git-send-email-judge.packham@gmail.com>
On Sun, Sep 18, 2011 at 10:20:24PM +1200, Chris Packham wrote:
> Instead of using eval which causes problems when a URL contains an
> appropriately escaped ampersand (\&).
I think this probably should just remove all of the evals. I don't see
how any of them is doing any good, and they're actively breaking URLs
that need quoting.
Hmm. Actually, the one for custom browser commands might need it,
because that one is expected to be a shell snippet. I suspect the
simplest thing is to do something like:
eval "$browser_cmd \"\$@\""
The other option would be to actually shell-quote each argument, which
is a pain to do in the shell (but is what C git does).
> For what it's worth I've included a testcase that detects my problem. I'm not
> sure if the testcase is really worth it because the test library suppresses X
> applications and even if it didn't the testcase is fairly trivial and might
> just annoy people by opening web-browsers (and it snaps up the last t99xx
> prefix).
Ick, yeah. Actually starting real browsers interacts too much with the
world outside of the test scripts. The results will be annoying (new
browser windows) and cause non-deterministic test results.
If you want to make a test, I think you would do better with something
like:
echo someurl_with_&_in_it >expect &&
git config browser.custom.cmd echo &&
git web--browse --browser=custom someurl_with_&_in_it >actual &&
test_cmp expect actual
That won't test that we are invoking kfmclient correctly, obviously, but
you can confirm at least that URLs are making it through to the browser
script intact.
-Peff
^ permalink raw reply
* Re: git subtree merging with a SVN remote?
From: Ronan Keryell @ 2011-09-18 18:00 UTC (permalink / raw)
To: Manuel Reimer; +Cc: git
In-Reply-To: <j550cl$218$1@dough.gmane.org>
>>>>> On Sun, 18 Sep 2011 16:44:33 +0200, Manuel Reimer <Manuel.Spam@nurfuerspam.de> said:
Manuel> Hello, I want to use "subtree merging" to get stuff from an
Manuel> external SVN repo into my project.
Manuel> Is it possible to do this directly using the external SVN
Manuel> server or should I set up a GIT mirror of this SVN repo?
I guess you can move *manually* the files from the SVN repository into
the git repository directly. :-)
More seriously, if you want to automate things, you have to go through a
git svn clone process.
Manuel> Is this "subtree merging" a pure local thing or do I push
Manuel> some information about this to the central GIT server?
Since the concept of central git server is a pure convention, you can
rely only on your local git repository only.
For a compiler project, I use these kinds of tricks to subtree 5
upstream svn projects with the ability to apply on top of them some
local commits, for example to avoid some upstream errors (it has just
happened last Friday :-( ).
Having all this operational is a little bit tedious, so I've developed
scripts to have all the infrastructure running and easy to be updated.
You may read
http://download.par4all.org/doc/organization/par4all_organization.htdoc/par4all_organization.html#x1-240007
or the PDF version and look at the p4a_git command I use to run this process:
https://git.hpc-project.com/cgit/par4all/tree/src/dev/p4a_git?h=p4a-own
https://git.hpc-project.com/cgit/par4all/tree/src/dev/p4a_git_lib.bash?h=p4a-own
and there are also some scripts around in the same directory to
bootstrap the infrastructure.
If you want to look at the resulting project history, study the p4a
branch from the Par4All project.
I've found this very powerful and efficient... once it is correctly
set up. :-)
I hope that helps,
--
Ronan KERYELL |\/ Cell: +33 613 143 766
HPC Project, Inc. |/) Ronan.Keryell@hpc-project.com
5201 Great America Parkway #3241 K skype:keryell
Santa Clara, CA 95054 |\ http://hpc-project.com
USA | \
^ permalink raw reply
* Re: [PATCH] Prevent users from adding the file that has all-zero SHA-1
From: Mikael Magnusson @ 2011-09-18 17:06 UTC (permalink / raw)
To: Nguyễn Thái Ngọc Duy; +Cc: git
In-Reply-To: <1316259574-1291-1-git-send-email-pclouds@gmail.com>
2011/9/17 Nguyễn Thái Ngọc Duy <pclouds@gmail.com>:
> This particular SHA-1 has special meaning to git, very much like NULL
> in C. If a user adds a file that has this SHA-1, unexpected things can
> happen.
>
> Granted, the chance is probably near zero because the content must
> also start with valid blob header. But extra safety does not harm.
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
> Another way than die() is to detect this situation and update header a
> little to give different SHA-1 (for example a leading 0 in object
> size in header). Older git versions may not be happy with such an
> approach.
>
> The same check can be added to commit, tree, tag creation and fsck.
> Maybe I'm too paranoid.
>
> By the way, are any other SHA-1s sensitive to git like this one?
Bad things will happen if you get an object with the same hash as any
already existing one, and AFAIK, there are no checks for this. I don't
think there's much point in treating 000...0 more specially than
HEAD^0 for example. The only two hashes that mean something in an
empty repo I guess are this one and the empty tree hash though.
PS there's a typo in your error message, "unluckly".
--
Mikael Magnusson
^ permalink raw reply
* Re: Pull From Mirrored Repository
From: Andrew Ardill @ 2011-09-18 15:15 UTC (permalink / raw)
To: Jean Sacren; +Cc: git
In-Reply-To: <20110918144514.GL15295@mail.gmail.com>
On 19 September 2011 00:45, Jean Sacren <sakiwit@gmail.com> wrote:
> After pull from a mirrored repository, git status shows
>
> # On branch master
> # Your branch is ahead of 'origin/master' by [NUMBER] commits.
> #
> nothing to commit (working directory clean)
>
>
> How to bring 'origin/master' update without syncing with the original
> repository?
>
Am I correct in thinking that you have done the following:
$ git clone original-server/repo.git
$ cd repo
$ git pull mirror-server/repo.git
$ git status
# On branch master
# Your branch is ahead of 'origin/master' by [NUMBER] commits.
#
nothing to commit (working directory clean)
and now you want the remote ref 'origin/master' to point to the same
thing as 'mirror/master' (assuming that you create the ref for the
mirror)?
This can be done (by editing the file .git/refs/remotes/origin/master
and specifying the correct sha1) however this is probably not the best
idea. It is best for git to know the actual state of the remote the
last time you synced with it so that it can act intelligently the next
time you sync with it.
If you intend to sync with the mirror, you might as well set it as the
upstream ref of you master branch. That way you will not get the 'Your
branch is ahead' message when you pull new updates (unless you have
local changes, of course).
This can be done by:
$ git checkout master
$ git branch --set-upstream mirror
This assumes that you have already added mirror as a remote ref.
Regards,
Andrew
^ permalink raw reply
* [PATCH v2] Add a credential-helper for KDE
From: Lukas Sandström @ 2011-09-18 14:52 UTC (permalink / raw)
To: Jeff King; +Cc: Lukas Sandström, Git Mailing List
In-Reply-To: <20110831014237.GA2519@sigill.intra.peff.net>
This Python script plugs into the credentials API
of Git to ask the user for passwords with a nice
KDE password dialog.
The password is saved in the KWallet.
Signed-off-by: Lukas Sandström <luksan@gmail.com>
---
On 2011-08-31 03:42, Jeff King wrote:
> Can we call it git-credential-kdewallet or similar? Then users can just
> do:
>
> git config credential.helper kdewallet
>
> (where "kdewallet" can be whatever you think is most appropriate; the
> key is naming it git-credential-*).
Done.
[...]
> If I am reading this correctly, you look up based purely on the context
> token. Which means that if I do something like this:
>
> $ git push https://host.com/repo.git
> [enter username: user1, password: foo]
> $ git push https://user2@host.com/other-repo.git
>
> We will invoke the helper as:
>
> git credential-kdewallet --unique=https:host.com --username=user2
>
> but the helper will ignore the "user2" bit, and return "user1 / foo".
>
> The "cache" helper I wrote handles this situation better, by indexing
> both on the token and the username. I wonder if the username should
> become part of the token. Or if the token should really just become a
> canonicalized URL, minus the actual path. So the first one would get:
>
> --unique=https://host.com
>
> and the second would get:
>
> --unique=https://user2@host.com
>
> Then helpers wouldn't need to worry about doing anything special.
>
> What do you think? Also, any comments in general on writing a helper?
> You are the first one besides me to do so. Did you find anything in the
> interface or the documentation confusing? Suggestions are very welcome,
> as nothing has been released yet and we're free to tweak as much as we
> want.
>
> -Peff
Right. Multiple usernames per "unique" context is supported in this version.
I looked at the git-credential-storage helper when I wrote the first patch,
which didn't have obvious support for multiple usernames per unique context.
Keeping the username outside the token is probably a good thing, but perhaps it
should be clarified in the api-docs that multiple usernames has to be supported.
Also; what about rejecting credentials. This code currently deletes just a
username/password pair if a username is specified, and all credentials associated
with the token if only --unique and --reject is specified. Is this correct/expected
behavior?
When I first wrote the helper I tried to immediately ask for a new password if a
credential was rejected, but this didn't work with the HTTP auth code, since it
doesn't retry the auth with the new credentials after a reject. I think it would
be better if we asked for a new password instead of just saying "auth failed" and
having the user retry the fetch/pull when the stored credentials are incorrect.
/Lkas
.../git-credential-kdewallet.py | 137 ++++++++++++++++++++
1 files changed, 137 insertions(+), 0 deletions(-)
create mode 100755 contrib/git-credential-kdewallet/git-credential-kdewallet.py
diff --git a/contrib/git-credential-kdewallet/git-credential-kdewallet.py b/contrib/git-credential-kdewallet/git-credential-kdewallet.py
new file mode 100755
index 0000000..29c4ae1
--- /dev/null
+++ b/contrib/git-credential-kdewallet/git-credential-kdewallet.py
@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+# encoding=utf-8
+#
+# Copyright 2011, Lukas Sandström
+#
+# Licensed under the GPL version 2.
+
+import sys
+from PyQt4.QtCore import QString
+from PyKDE4.kdecore import i18n, ki18n, KAboutData, KCmdLineArgs, KCmdLineOptions
+from PyKDE4.kdeui import KApplication, KWallet, KPasswordDialog
+
+appName = "git-credential-kdewallet"
+catalog = ""
+programName = ki18n ("Git KDE credentials helper")
+version = "0.1"
+description = ki18n ("Credentials storage helper for Git")
+license = KAboutData.License_GPL_V2
+copyright = ki18n ("(c) 2011 Lukas Sandström")
+text = ki18n ("none")
+homePage = "http://www.git-scm.com"
+bugEmail = "luksan@gmail.com"
+
+aboutData = KAboutData (appName, catalog, programName, version, description,
+ license, copyright, text, homePage, bugEmail)
+
+class CredentialHelper(KApplication):
+ def __init__(self, token, username = None, desc = None, reject = False):
+ super(CredentialHelper, self).__init__()
+ self.password = None
+ self.username = username
+ self.save_password = False
+ self.token = token
+ self.desc = desc
+
+ if not self.token:
+ return
+
+ self.open_wallet()
+
+ if reject:
+ self.reject_credential()
+ return
+
+ if not self.check_wallet():
+ self.ask_password_dialog()
+
+ if self.save_password:
+ self.store_password()
+
+ self.output_credentials()
+
+ def output_credentials(self):
+ if self.username:
+ print "username=" + self.username
+ if self.password:
+ print "password=" + self.password
+
+ def reject_credential(self):
+ (res, data) = self.wallet.readMap(self.token)
+ if self.username:
+ try:
+ del data[QString(self.username)]
+ except KeyError:
+ pass
+ self.wallet.writeMap(self.token, data)
+ else:
+ self.wallet.removeEntry(self.token)
+
+ def store_password(self):
+ (res, data) = self.wallet.readMap(self.token)
+ data[QString(self.username)] = QString(self.password)
+ self.wallet.writeMap(QString(self.token), data)
+
+ def open_wallet(self):
+ self.wallet = KWallet.Wallet.openWallet(
+ KWallet.Wallet.LocalWallet(), 0, KWallet.Wallet.Synchronous)
+ if not self.wallet.isOpen():
+ return None
+ if not self.wallet.hasFolder("GitCredentials"):
+ self.wallet.createFolder("GitCredentials")
+ self.wallet.setFolder("GitCredentials")
+
+ def check_wallet(self):
+ (res, data) = self.wallet.readMap(self.token)
+ if res != 0:
+ return None
+ for u, p in data.iteritems():
+ # Pick the first complete credential if no username is specified
+ if not self.username and u and p:
+ self.username = u
+ self.password = p
+ return True
+ if self.username == u:
+ self.password = p
+ return True
+ return None
+
+ def ask_password_dialog(self):
+ dlg = KPasswordDialog(None,
+ KPasswordDialog.KPasswordDialogFlag(
+ KPasswordDialog.ShowKeepPassword |
+ KPasswordDialog.ShowUsernameLine))
+ if self.desc:
+ desc = self.desc
+ else:
+ desc = self.token
+ dlg.setPrompt(i18n("Please enter username and password for %s" % (desc)))
+ dlg.setUsername(self.username)
+ dlg.setKeepPassword(True)
+ if not dlg.exec_():
+ return
+ self.username = dlg.username()
+ self.password = dlg.password()
+ self.save_password = dlg.keepPassword()
+
+def main():
+ KCmdLineArgs.init(sys.argv, aboutData)
+
+ options = KCmdLineOptions()
+ options.add("unique <token>", ki18n("Unique token identifying the credential"))
+ options.add("description <desc>", ki18n("Human readable description of the credential"))
+ options.add("username <username>", ki18n("Requested username"))
+ options.add("reject", ki18n("Purge credential"))
+
+ KCmdLineArgs.addCmdLineOptions(options)
+ args = KCmdLineArgs.parsedArgs();
+
+ username = args.getOption("username")
+ token = args.getOption("unique")
+ desc = args.getOption("description")
+ reject = args.isSet("reject")
+
+ app = CredentialHelper(token, username, desc, reject)
+
+if __name__ == "__main__":
+ main()
--
1.7.6.1
^ permalink raw reply related
* git subtree merging with a SVN remote?
From: Manuel Reimer @ 2011-09-18 14:44 UTC (permalink / raw)
To: git
Hello,
I want to use "subtree merging" to get stuff from an external SVN repo into my
project.
Is it possible to do this directly using the external SVN server or should I set
up a GIT mirror of this SVN repo?
Is this "subtree merging" a pure local thing or do I push some information about
this to the central GIT server?
Yours
Manuel
^ permalink raw reply
* Re: git web--browse error handling URL with & in it (Was Re: [RFC/PATCH] Configurable hyperlinking in gitk)
From: Christian Couder @ 2011-09-18 14:46 UTC (permalink / raw)
To: Jeff King; +Cc: Chris Packham, Jeff Epler, git
In-Reply-To: <20110918032933.GA17977@sigill.intra.peff.net>
Hi,
On Sunday 18 September 2011 05:29:34 Jeff King wrote:
> On Sun, Sep 18, 2011 at 12:32:04PM +1200, Chris Packham wrote:
> > Update: it's the call to eval that causes the problem
> >
> > eval kfmclient newTab https://internalhost/code\&stuff/bugs.php?id=foo
> > [1] 14728
> > bash: stuff/bugs.php?id=foo: No such file or directory
>
> Hmm. The offending lines look like:
>
> eval "$browser_path" "$@" &
>
> Normally in git we treat user-configured commands as shell snippets,
> meaning the user is responsible for any quoting. But in this script, we
> seem to run:
>
> type "$browser_path"
>
> several times. Which implies that "$browser_path" must be the actual
> executable. In which case, I would think that:
>
> "$browser_path" "$@" &
>
> would be the right thing. And indeed, that is what the firefox arm of
> the case statement does. But chrome, konqueror, and others use eval.
Yeah, I don't remember why I sometimes used 'eval "$browser_path" "$@"' when I
wrote this code. Sorry!
> Unrelated, but it also looks like $browser_path is used unquoted in the
> firefox case (see inside the vers=$(...)).
Thanks,
Christian.
^ permalink raw reply
* Pull From Mirrored Repository
From: Jean Sacren @ 2011-09-18 14:45 UTC (permalink / raw)
To: git
After pull from a mirrored repository, git status shows
# On branch master
# Your branch is ahead of 'origin/master' by [NUMBER] commits.
#
nothing to commit (working directory clean)
How to bring 'origin/master' update without syncing with the original
repository?
Thanks,
--
Jean Sacren
^ permalink raw reply
* [PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec
From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw)
To: git, Drew Northup
Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin,
Jakub Narebski
In-Reply-To: <1316352884-26193-1-git-send-email-jnareb@gmail.com>
This patch follows similar lines in %files section for 'gitk' and
'git-gui' subpackages.
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
New in this version of series... though IIRC this change was present
in some version of those patches (probably not as separate patch,
though).
git.spec.in | 7 +++++++
1 files changed, 7 insertions(+), 0 deletions(-)
diff --git a/git.spec.in b/git.spec.in
index 91c8462..dfc5093 100644
--- a/git.spec.in
+++ b/git.spec.in
@@ -199,7 +199,11 @@ rm -rf $RPM_BUILD_ROOT
%files -n gitweb
%defattr(-,root,root)
+%doc Documentation/*gitweb*.txt
%{_datadir}/gitweb
+%{!?_without_docs: %{_mandir}/man1/*gitweb*.1*}
+%{!?_without_docs: %{_mandir}/man5/*gitweb*.5*}
+%{!?_without_docs: %doc Documentation/*gitweb*.html }
%files -n perl-Git -f perl-files
%defattr(-,root,root)
@@ -208,6 +212,9 @@ rm -rf $RPM_BUILD_ROOT
# No files for you!
%changelog
+* Sun Sep 18 2011 Jakub Narebski <jnareb@gmail.com>
+- Add gitweb manpages to 'gitweb' subpackage
+
* Wed Jun 30 2010 Junio C Hamano <gitster@pobox.com>
- Add 'gitweb' subpackage.
--
1.7.6
^ permalink raw reply related
* [PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb
From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw)
To: git, Drew Northup
Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin,
Jakub Narebski
In-Reply-To: <1316352884-26193-1-git-send-email-jnareb@gmail.com>
Most of what is in gitweb.txt it has been pulled directly from the
README and INSTALL files of gitweb.
Current version is somewhat based on structure of SVN::Web manpage
(one of web interfaces for Subversion).
gitweb.conf(5) i.e. gitweb configuration manpage now refers to
appropriate sections in gitweb(1). gitweb/README now refers to
gitweb/INSTALL and gitweb(1) manpage. gitweb/INSTALL now refers to
gitweb.conf(5) and gitweb(1).
Inspired-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
Changes from v3 version include:
* Force URLs in SYNOPSIS into hyperlinks in HTML output
* Fixed formatting of continued description list
Documentation/Makefile | 2 +-
Documentation/gitweb.conf.txt | 8 +
Documentation/gitweb.txt | 703 +++++++++++++++++++++++++++++++++++++++++
gitweb/INSTALL | 96 +-----
gitweb/README | 278 ++---------------
5 files changed, 741 insertions(+), 346 deletions(-)
create mode 100644 Documentation/gitweb.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6d71943..aebab11 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,7 +1,7 @@
MAN1_TXT= \
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
$(wildcard git-*.txt)) \
- gitk.txt git.txt
+ gitk.txt gitweb.txt git.txt
MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
gitrepository-layout.txt gitweb.conf.txt
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 2769302..1b276dd 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -35,6 +35,10 @@ CGI script with the default name 'gitweb_config.perl' -- allowing
one to have multiple gitweb instances with different configurations by
the use of symlinks.
+Note that some configuration can be controlled on per-repository rather than
+gitweb-wide basis: see "Per-repository gitweb configuration" subsection on
+linkgit:gitweb[1] manpage.
+
DISCUSSION
----------
@@ -106,6 +110,8 @@ Location of repositories
Configuration variables described below control finding git repositories by
gitweb, and control display and access to repositories.
+See also "Repositories" and later subsections in linkgit:gitweb[1] manpage.
+
$projectroot::
Absolute filesystem path which will be prepended to project path;
the path to repository is `$projectroot/$project`. Set to
@@ -172,6 +178,8 @@ though the above might be done by using `$export_ok` instead
----------------------------------------------------------------------------
our $export_ok = "git-daemon-export-ok";
----------------------------------------------------------------------------
+See also more involved example in "Controlling access to git repositories"
+subsection on linkgit:gitweb[1] manpage.
$strict_export::
Only allow viewing of repositories also shown on the overview page.
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
new file mode 100644
index 0000000..4de6de3
--- /dev/null
+++ b/Documentation/gitweb.txt
@@ -0,0 +1,703 @@
+gitweb(1)
+=========
+
+NAME
+----
+gitweb - Git web interface (web frontend to Git repositories)
+
+SYNOPSIS
+--------
+To get started with gitweb, run linkgit:git-instaweb[1] from a git repository.
+This would configure and start your web server, and run web browser pointing to
+gitweb page.
+
+See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or
+http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code,
+browsed using gitweb itself.
+
+
+DESCRIPTION
+-----------
+Gitweb provides a web interface to git repositories. It's features include:
+
+* Viewing multiple Git repositories with common root.
+* Browsing every revision of the repository.
+* Viewing the contents of files in the repository at any revision.
+* Viewing the revision log of branches, history of files and directories,
+ see what was changed when, by who.
+* Viewing the blame/annotation details of any file (if enabled).
+* Generating RSS and Atom feeds of commits, for any branch.
+ The feeds are auto-discoverable in modern web browsers.
+* Viewing everything that was changed in a revision, and step through
+ revisions one at a time, viewing the history of the repository.
+* Finding commits which commit messages matches given search term.
+
+CONFIGURATION
+-------------
+Various aspects of gitweb's behavior can be controlled through the configuration
+file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5]
+for details.
+
+Repositories
+~~~~~~~~~~~~
+Gitweb can show information from one or more Git repositories. These
+repositories have to be all on local filesystem, and have to share common
+repository root, i.e. be all under a single parent repository (but see also
+"Advanced web server setup" section, "Webserver configuration with multiple
+projects' root" subsection).
+
+-----------------------------------------------------------------------
+our $projectroot = '/path/to/parent/directory';
+-----------------------------------------------------------------------
+
+The default value for `$projectroot` is '/pub/git'. You can change it during
+building gitweb via `GITWEB_PROJECTROOT` build configuration variable.
+
+By default all git repositories under `$projectroot` are visible and available
+to gitweb. The list of projects is generated by default by scanning the
+`$projectroot` directory for git repositories (for object databases to be
+more exact; gitweb is not interested in a working area, and is best suited
+to showing "bare" repositories).
+
+The name of repository in gitweb is path to it's `$GIT_DIR` (it's object
+database) relative to `$projectroot`. Therefore the repository $repo can be
+found at "$projectroot/$repo".
+
+
+Projects list file format
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Instead of having gitweb find repositories by scanning filesystem
+starting from $projectroot, you can provide a pre-generated list of
+visible projects by setting `$projects_list` to point to a plain text
+file with a list of projects (with some additional info).
+
+This file uses the following format:
+
+* One record (for project / repository) per line; does not support line
+continuation (newline escaping).
+
+* Leading and trailing whitespace are ignored.
+
+* Whitespace separated fields; any run of whitespace can be used as field
+separator (rules for Perl's "`split(" ", $line)`").
+
+* Fields use modified URI encoding, defined in RFC 3986, section 2.1
+(Percent-Encoding), or rather "Query string encoding" (see
+link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference
+being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be
+also percent-encoded).
++
+Reserved characters are: "%" (used for encoding), "{plus}" (can be used to
+encode SPACE), all whitespace characters as defined in Perl, including SP,
+TAB and LF, (used to separate fields in a record).
+
+* Currently recognized fields are:
+<repository path>::
+ path to repository GIT_DIR, relative to `$projectroot`
+<repository owner>::
+ displayed as repository owner, preferably full name, or email,
+ or both
+
+You can generate the projects list index file using the project_index action
+(the 'TXT' link on projects list page) directly from gitweb; see also
+"Generating projects list using gitweb" section below.
+
+Example contents:
+-----------------------------------------------------------------------
+foo.git Joe+R+Hacker+<joe@example.com>
+foo/bar.git O+W+Ner+<owner@example.org>
+-----------------------------------------------------------------------
+
+
+By default this file controls only which projects are *visible* on projects
+list page (note that entries that do not point to correctly recognized git
+repositories won't be displayed by gitweb). Even if a project is not
+visible on projects list page, you can view it nevertheless by hand-crafting
+a gitweb URL. By setting `$strict_export` configuration variable (see
+linkgit:gitweb.conf[5]) to true value you can allow viewing only of
+repositories also shown on the overview page (i.e. only projects explicitely
+listed in projects list file will be accessible).
+
+
+Generating projects list using gitweb
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We assume that GITWEB_CONFIG has its default Makefile value, namely
+'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:
+----------------------------------------------------------------------------
+read_config_file("gitweb_config.perl");
+$projects_list = $projectroot;
+----------------------------------------------------------------------------
+
+Then create the following script to get list of project in the format
+suitable for GITWEB_LIST build configuration variable (or
+`$projects_list` variable in gitweb config):
+
+----------------------------------------------------------------------------
+#!/bin/sh
+
+export GITWEB_CONFIG="gitweb_make_index.perl"
+export GATEWAY_INTERFACE="CGI/1.1"
+export HTTP_ACCEPT="*/*"
+export REQUEST_METHOD="GET"
+export QUERY_STRING="a=project_index"
+
+perl -- /var/www/cgi-bin/gitweb.cgi
+----------------------------------------------------------------------------
+
+Run this script and save its output to a file. This file could then be used
+as projects list file, which means that you can set `$projects_list` to its
+filename.
+
+
+Controlling access to git repositories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default all git repositories under `$projectroot` are visible and
+available to gitweb. You can however configure how gitweb controls access
+to repositories.
+
+* As described in "Projects list file format" section, you can control which
+projects are *visible* by selectively including repositories in projects
+list file, and setting `$projects_list` gitweb configuration variable to
+point to it. With `$strict_export` set, projects list file can be used to
+control which repositories are *available* as well.
+
+* You can configure gitweb to only list and allow viewing of the explicitly
+exported repositories, via `$export_ok` variable in gitweb config file; see
+linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows
+repositories only if this file named by `$export_ok` exists in its object
+database (if directory has the magic file named `$export_ok`).
++
+For example linkgit:git-daemon[1] by default (unless `--export-all` option
+is used) allows pulling only for those repositories that have
+'git-daemon-export-ok' file. Adding
++
+--------------------------------------------------------------------------
+our $export_ok = "git-daemon-export-ok";
+--------------------------------------------------------------------------
++
+makes gitweb show and allow access only to those repositories that can be
+fetched from via `git://` protocol.
+
+* Finally, it is possible to specify an arbitrary perl subroutine that will
+be called for each repository to determine if it can be exported. The
+subroutine receives an absolute path to the project (repository) as its only
+parameter (i.e. "$projectroot/$project").
++
+For example, if you use mod_perl to run the script, and have dumb
+http protocol authentication configured for your repositories, you
+can use the following hook to allow access only if the user is
+authorized to read the files:
++
+--------------------------------------------------------------------------
+$export_auth_hook = sub {
+ use Apache2::SubRequest ();
+ use Apache2::Const -compile => qw(HTTP_OK);
+ my $path = "$_[0]/HEAD";
+ my $r = Apache2::RequestUtil->request;
+ my $sub = $r->lookup_file($path);
+ return $sub->filename eq $path
+ && $sub->status == Apache2::Const::HTTP_OK;
+};
+--------------------------------------------------------------------------
+
+
+Per-repository gitweb configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can configure individual repositories shown in gitweb by creating file
+in the 'GIT_DIR' of git repository, or by setting some repo configuration
+variable (in 'GIT_DIR/config', see linkgit:git-config[1]).
+
+You can use the following files in repository:
+
+README.html::
+ A html file (HTML fragment) which is included on the gitweb project
+ "summary" page inside `<div>` block element. You can use it for longer
+ description of a project, to provide links (for example to project's
+ homepage), etc. This is recognized only if XSS prevention is off
+ (`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include
+ a README safely when XSS prevention is on may be worked out in the
+ future.
+
+description (or `gitweb.description`)::
+ Short (shortened to `$projects_list_description_width` in the projects
+ list page, which is 25 characters by default; see
+ linkgit:gitweb.conf[5]) single line description of a project (of a
+ repository). Plain text file; HTML will be escaped. By default set to
++
+-------------------------------------------------------------------------------
+Unnamed repository; edit this file to name it for gitweb.
+-------------------------------------------------------------------------------
++
+from the template during repository creation, usually installed in
+'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo
+configuration variable, but the file takes precedence.
+
+category (or `gitweb.category`)::
+ Singe line category of a project, used to group projects if
+ `$projects_list_group_categories` is enabled. By default (file and
+ configuration variable absent), uncategorized projects are put in the
+ `$project_list_default_category` category. You can use the
+ `gitweb.category` repo configuration variable, but the file takes
+ precedence.
++
+The configuration variables `$projects_list_group_categories` and
+`$project_list_default_category` are described in linkgit:gitweb.conf[5]
+
+cloneurl (or multiple-valued `gitweb.url`)::
+ File with repository URL (used for clone and fetch), one per line.
+ Displayed in the project summary page. You can use multiple-valued
+ `gitweb.url` repository configuration variable for that, but the file
+ takes precedence.
++
+This is per-repository enhancement / version of global prefix-based
+`@git_base_url_list` gitweb configuration variable (see
+linkgit:gitweb.conf[5]).
+
+gitweb.owner::
+ You can use the `gitweb.owner` repository configuration variable to set
+ repository's owner. It is displayed in the project list and summary
+ page.
++
+If it's not set, filesystem directory's owner is used (via GECOS field,
+i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset
+(gitweb scans `$projectroot` for repositories); if `$projects_list`
+points to file with list of repositories, then project owner defaults to
+value from this file for given repository.
+
+various `gitweb.*` config variables (in config)::
+ Read description of `%feature` hash for detailed list, and descriptions.
+ See also "Configuring gitweb features" section in linkgit:gitweb.conf[5]
+
+
+ACTIONS, AND URLS
+-----------------
+Gitweb can use path_info (component) based URLs, or it can pass all necessary
+information via query parameters. The typical gitweb URLs are broken down in to
+five components:
+
+-----------------------------------------------------------------------
+.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>
+-----------------------------------------------------------------------
+
+repo::
+ The repository the action will be performed on.
++
+All actions except for those that list all available projects,
+in whatever form, require this parameter.
+
+action::
+ The action that will be run. Defaults to 'projects_list' if repo
+ is not set, and to 'summary' otherwise.
+
+revision::
+ Revision shown. Defaults to HEAD.
+
+path::
+ The path within the <repository> that the action is performed on,
+ for those actions that require it.
+
+arguments::
+ Any arguments that control the behaviour of the action.
+
+Some actions require or allow to specify two revisions, and sometimes even two
+pathnames. In most general form such path_info (component) based gitweb URL
+looks like this:
+
+-----------------------------------------------------------------------
+.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>
+-----------------------------------------------------------------------
+
+
+Each action is implemented as a subroutine, and must be present in %actions
+hash. Some actions are disabled by default, and must be turned on via feature
+mechanism. For example to enable 'blame' view add the following to gitweb
+configuration file:
+
+-----------------------------------------------------------------------
+$feature{'blame'}{'default'} = [1];
+-----------------------------------------------------------------------
+
+
+Actions:
+~~~~~~~~
+The standard actions are:
+
+project_list::
+ Lists the available Git repositories. This is the default command if no
+ repository is specified in the URL.
+
+summary::
+ Displays summary about given repository. This is the default command if
+ no action is specified in URL, and only repository is specified.
+
+heads::
+remotes::
+ Lists all local or all remote-tracking branches in given repository.
++
+The latter is not available by default, unless configured.
+
+tags::
+ List all tags (lightweight and annotated) in given repository.
+
+blob::
+tree::
+ Shows the files and directories in a given repository path, at given
+ revision. This is default command if no action is specified in the URL,
+ and path is given.
+
+blob_plain::
+ Returns the raw data for the file in given repository, at given path and
+ revision. Links to this action are marked 'raw'.
+
+blobdiff::
+ Shows the difference between two revisions of the same file.
+
+blame::
+blame_incremental::
+ Shows the blame (also called annotation) information for a file. On a
+ per line basis it shows the revision in which that line was last changed
+ and the user that committed the change. The incremental version (which
+ if configured is used automatically when JavaScript is enabled) uses
+ Ajax to incrementally add blame info to the contents of given file.
++
+This action is disabled by default for performance reasons.
+
+commit::
+commitdiff::
+ Shows information about a specific commit in a repository. The 'commit'
+ view shows information about commit in more detail, the 'commitdiff'
+ action shows changeset for given commit.
+
+patch::
+ Returns the commit in plain text mail format, suitable for applying with
+ linkgit:git-am[1].
+
+tag::
+ Display specific annotated tag (tag object).
+
+log::
+shortlog::
+ Shows log information (commit message or just commit subject) for a
+ given branch (starting from given revision).
++
+The 'shortlog' view is more compact; it shows one commit per line.
+
+history::
+ Shows history of the file or directory in a given repository path,
+ starting from given revision (defaults to HEAD, i.e. default branch).
++
+This view is similar to 'shortlog' view.
+
+rss::
+atom::
+ Generates an RSS (or Atom) feed of changes to repository.
+
+
+WEBSERVER CONFIGURATION
+-----------------------
+This section explains how to configure some common webservers to run gitweb. In
+all cases, `/path/to/gitweb` in the examples is the directory you ran installed
+gitweb in, and contains `gitweb_config.perl`.
+
+If you've configured a web server that isn't listed here for gitweb, please send
+in the instructions so they can be included in a future release.
+
+Apache as CGI
+~~~~~~~~~~~~~
+Apache must be configured to support CGI scripts in the directory in
+which gitweb is installed. Let's assume that it is '/var/www/cgi-bin'
+directory.
+
+-----------------------------------------------------------------------
+ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
+
+<Directory "/var/www/cgi-bin">
+ Options Indexes FollowSymlinks ExecCGI
+ AllowOverride None
+ Order allow,deny
+ Allow from all
+</Directory>
+-----------------------------------------------------------------------
+
+With that configuration the full path to browse repositories would be:
+
+ http://server/cgi-bin/gitweb.cgi
+
+Apache with mod_perl, via ModPerl::Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can use mod_perl with gitweb. You must install Apache::Registry
+(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable
+this support.
+
+Assuming that gitweb is installed to '/var/www/perl', the following
+Apache configuration (for mod_perl 2.x) is suitable.
+
+-----------------------------------------------------------------------
+Alias /perl "/var/www/perl"
+
+<Directory "/var/www/perl">
+ SetHandler perl-script
+ PerlResponseHandler ModPerl::Registry
+ PerlOptions +ParseHeaders
+ Options Indexes FollowSymlinks +ExecCGI
+ AllowOverride None
+ Order allow,deny
+ Allow from all
+</Directory>
+-----------------------------------------------------------------------
+
+With that configuration the full path to browse repositories would be:
+
+ http://server/perl/gitweb.cgi
+
+Apache with FastCGI
+~~~~~~~~~~~~~~~~~~~
+Gitweb works with Apache and FastCGI. First you need to rename, copy
+or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is
+installed in '/usr/share/gitweb' directory. The following Apache
+configuration is suitable (UNTESTED!)
+
+-----------------------------------------------------------------------
+FastCgiServer /usr/share/gitweb/gitweb.cgi
+ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi
+
+Alias /gitweb/static /usr/share/gitweb/static
+<Directory /usr/share/gitweb/static>
+ SetHandler default-handler
+</Directory>
+-----------------------------------------------------------------------
+
+With that configuration the full path to browse repositories would be:
+
+ http://server/gitweb
+
+
+ADVANCED WEB SERVER SETUP
+-------------------------
+All of those examples use request rewriting, and need `mod_rewrite`
+(or equivalent; examples below are written for Apache).
+
+Single URL for gitweb and for fetching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to have one URL for both gitweb and your `http://`
+repositories, you can configure Apache like this:
+
+-----------------------------------------------------------------------
+<VirtualHost *:80>
+ ServerName git.example.org
+ DocumentRoot /pub/git
+ SetEnv GITWEB_CONFIG /etc/gitweb.conf
+
+ # turning on mod rewrite
+ RewriteEngine on
+
+ # make the front page an internal rewrite to the gitweb script
+ RewriteRule ^/$ /cgi-bin/gitweb.cgi
+
+ # make access for "dumb clients" work
+ RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
+ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
+</VirtualHost>
+-----------------------------------------------------------------------
+
+The above configuration expects your public repositories to live under
+'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`,
+both as cloneable GIT URL and as browseable gitweb interface. If you then
+start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all`
+then you can even use the `git://` URL with exactly the same path.
+
+Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the
+named file (i.e. in this example '/etc/gitweb.conf') as a configuration for
+gitweb. You don't really need it in above example; it is required only if
+your configuration file is in different place than built-in (during
+compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See
+linkgit:gitweb.conf[5] for details, especially information about precedence
+rules.
+
+If you use the rewrite rules from the example you *might* also need
+something like the following in your gitweb configuration file
+('/etc/gitweb.conf' following example):
+----------------------------------------------------------------------------
+@stylesheets = ("/some/absolute/path/gitweb.css");
+$my_uri = "/";
+$home_link = "/";
+$per_request_config = 1;
+----------------------------------------------------------------------------
+Nowadays though gitweb should create HTML base tag when needed (to set base
+URI for relative links), so it should work automatically.
+
+
+Webserver configuration with multiple projects' root
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to use gitweb with several project roots you can edit your
+Apache virtual host and gitweb configuration files in the following way.
+
+The virtual host configuration (in Apache configuration file) should look
+like this:
+--------------------------------------------------------------------------
+<VirtualHost *:80>
+ ServerName git.example.org
+ DocumentRoot /pub/git
+ SetEnv GITWEB_CONFIG /etc/gitweb.conf
+
+ # turning on mod rewrite
+ RewriteEngine on
+
+ # make the front page an internal rewrite to the gitweb script
+ RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT]
+
+ # look for a public_git folder in unix users' home
+ # http://git.example.org/~<user>/
+ RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+ [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
+
+ # http://git.example.org/+<user>/
+ #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+ [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
+
+ # http://git.example.org/user/<user>/
+ #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+ [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
+
+ # defined list of project roots
+ RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+ [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
+ RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+ [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
+
+ # make access for "dumb clients" work
+ RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
+ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
+</VirtualHost>
+--------------------------------------------------------------------------
+
+Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`
+environment variable from a web server, so you need to put the following
+line in gitweb configuration file ('/etc/gitweb.conf' in above example):
+--------------------------------------------------------------------------
+$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
+--------------------------------------------------------------------------
+*Note* that this requires to be set for each request, so either
+`$per_request_config` must be false, or the above must be put in code
+referenced by `$per_request_config`;
+
+These configurations enable two things. First, each unix user (`<user>`) of
+the server will be able to browse through gitweb git repositories found in
+'~/public_git/' with the following url:
+
+ http://git.example.org/~<user>/
+
+If you do not want this feature on your server just remove the second
+rewrite rule.
+
+If you already use `mod_userdir` in your virtual host or you don't want to
+use the \'~' as first character, just comment or remove the second rewrite
+rule, and uncomment one of the following according to what you want.
+
+Second, repositories found in '/pub/scm/' and '/var/git/' will be accesible
+through `http://git.example.org/scm/` and `http://git.example.org/var/`.
+You can add as many project roots as you want by adding rewrite rules like
+the third and the fourth.
+
+
+PATH_INFO usage
+~~~~~~~~~~~~~~~
+If you enable PATH_INFO usage in gitweb by putting
+----------------------------------------------------------------------------
+$feature{'pathinfo'}{'default'} = [1];
+----------------------------------------------------------------------------
+in your gitweb configuration file, it is possible to set up your server so
+that it consumes and produces URLs in the form
+
+ http://git.example.com/project.git/shortlog/sometag
+
+i.e. without 'gitweb.cgi' part, by using a configuration such as the
+following. This configuration assumes that '/var/www/gitweb' is the
+DocumentRoot of your webserver, contains the gitweb.cgi script and
+complementary static files (stylesheet, favicon, JavaScript):
+
+----------------------------------------------------------------------------
+<VirtualHost *:80>
+ ServerAlias git.example.com
+
+ DocumentRoot /var/www/gitweb
+
+ <Directory /var/www/gitweb>
+ Options ExecCGI
+ AddHandler cgi-script cgi
+
+ DirectoryIndex gitweb.cgi
+
+ RewriteEngine On
+ RewriteCond %{REQUEST_FILENAME} !-f
+ RewriteCond %{REQUEST_FILENAME} !-d
+ RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+ </Directory>
+</VirtualHost>
+----------------------------------------------------------------------------
+The rewrite rule guarantees that existing static files will be properly
+served, whereas any other URL will be passed to gitweb as PATH_INFO
+parameter.
+
+*Notice* that in this case you don't need special settings for
+`@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client"
+access to your project .git dirs (described in "Single URL for gitweb and
+for fetching" section). A possible workaround for the latter is the
+following: in your project root dir (e.g. '/pub/git') have the projects
+named *without* a .git extension (e.g. '/pub/git/project' instead of
+'/pub/git/project.git') and configure Apache as follows:
+----------------------------------------------------------------------------
+<VirtualHost *:80>
+ ServerAlias git.example.com
+
+ DocumentRoot /var/www/gitweb
+
+ AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
+ <Directory /var/www/gitweb>
+ Options ExecCGI
+ AddHandler cgi-script cgi
+
+ DirectoryIndex gitweb.cgi
+
+ RewriteEngine On
+ RewriteCond %{REQUEST_FILENAME} !-f
+ RewriteCond %{REQUEST_FILENAME} !-d
+ RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+ </Directory>
+</VirtualHost>
+----------------------------------------------------------------------------
+
+The additional AliasMatch makes it so that
+
+ http://git.example.com/project.git
+
+will give raw access to the project's git dir (so that the project can be
+cloned), while
+
+ http://git.example.com/project
+
+will provide human-friendly gitweb access.
+
+This solution is not 100% bulletproof, in the sense that if some project has
+a named ref (branch, tag) starting with 'git/', then paths such as
+
+ http://git.example.com/project/command/abranch..git/abranch
+
+will fail with a 404 error.
+
+
+BUGS
+----
+Please report any bugs or feature requests to git@vger.kernel.org,
+putting "gitweb" in the subject of email.
+
+SEE ALSO
+--------
+linkgit:gitweb.conf[5], linkgit:git-instaweb[1]
+
+'gitweb/README', 'gitweb/INSTALL'
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index f5efe74..d134ffe 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -229,7 +229,7 @@ Gitweb config file
------------------
See also "Runtime gitweb configuration" section in README file
-for gitweb (in gitweb/README).
+for gitweb (in gitweb/README), and gitweb.conf(5) manpage.
- You can configure gitweb further using the per-instance gitweb configuration file;
by default this is a file named gitweb_config.perl in the same place as
@@ -287,97 +287,19 @@ adding the following lines to your $GITWEB_CONFIG:
Gitweb repositories
-------------------
-- By default all git repositories under projectroot are visible and
- available to gitweb. The list of projects is generated by default by
- scanning the projectroot directory for git repositories (for object
- databases to be more exact).
-
- You can provide a pre-generated list of [visible] repositories,
- together with information about their owners (the project ownership
- defaults to the owner of the repository directory otherwise), by setting
- the GITWEB_LIST build configuration variable (or the $projects_list
- variable in the gitweb config file) to point to a plain file.
-
- Each line of the projects list file should consist of the url-encoded path
- to the project repository database (relative to projectroot), followed
- by the url-encoded project owner on the same line (separated by a space).
- Spaces in both project path and project owner have to be encoded as either
- '%20' or '+'.
-
- Other characters that have to be url-encoded, i.e. replaced by '%'
- followed by two-digit character number in octal, are: other whitespace
- characters (because they are field separator in a record), plus sign '+'
- (because it can be used as replacement for spaces), and percent sign '%'
- (which is used for encoding / escaping).
-
- You can generate the projects list index file using the project_index
- action (the 'TXT' link on projects list page) directly from gitweb.
-
-- By default, even if a project is not visible on projects list page, you
- can view it nevertheless by hand-crafting a gitweb URL. You can set the
- GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export
- variable in the gitweb config file) to only allow viewing of
- repositories also shown on the overview page.
-
-- Alternatively, you can configure gitweb to only list and allow
- viewing of the explicitly exported repositories, via the
- GITWEB_EXPORT_OK build configuration variable (or the $export_ok
- variable in gitweb config file). If it evaluates to true, gitweb
- shows repositories only if this file exists in its object database
- (if directory has the magic file named $export_ok).
-
-- Finally, it is possible to specify an arbitrary perl subroutine that
- will be called for each project to determine if it can be exported.
- The subroutine receives an absolute path to the project as its only
- parameter.
-
- For example, if you use mod_perl to run the script, and have dumb
- http protocol authentication configured for your repositories, you
- can use the following hook to allow access only if the user is
- authorized to read the files:
-
- $export_auth_hook = sub {
- use Apache2::SubRequest ();
- use Apache2::Const -compile => qw(HTTP_OK);
- my $path = "$_[0]/HEAD";
- my $r = Apache2::RequestUtil->request;
- my $sub = $r->lookup_file($path);
- return $sub->filename eq $path
- && $sub->status == Apache2::Const::HTTP_OK;
- };
-
-
-Generating projects list using gitweb
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We assume that GITWEB_CONFIG has its default Makefile value, namely
-gitweb_config.perl. Put the following in gitweb_make_index.perl file:
-
- $GITWEB_CONFIG = "gitweb_config.perl";
- do $GITWEB_CONFIG if -e $GITWEB_CONFIG;
-
- $projects_list = $projectroot;
-
-Then create the following script to get list of project in the format
-suitable for GITWEB_LIST build configuration variable (or
-$projects_list variable in gitweb config):
-
- #!/bin/sh
-
- export GITWEB_CONFIG="gitweb_make_index.perl"
- export GATEWAY_INTERFACE="CGI/1.1"
- export HTTP_ACCEPT="*/*"
- export REQUEST_METHOD="GET"
- export QUERY_STRING="a=project_index"
-
- perl -- /var/www/cgi-bin/gitweb.cgi
+By default gitweb shows all git repositories under single common repository
+root on a local filesystem; see description of GITWEB_PROJECTROOT build-time
+configuration variable above (and also of GITWEB_LIST).
+
+More advanced usage, like limiting access or visibility of repositories and
+managing multiple roots are described on gitweb manpage.
Example web server configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See also "Webserver configuration" section in README file for gitweb
-(in gitweb/README).
+See also "Webserver configuration" and "Advanced web server setup" sections
+in gitweb(1) manpage.
- Apache2, gitweb installed as CGI script,
diff --git a/gitweb/README b/gitweb/README
index cf528d3..6da4778 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -7,9 +7,18 @@ The one working on:
From the git version 1.4.0 gitweb is bundled with git.
+Build time gitweb configuration
+-------------------------------
+There are many configuration variables which affect building gitweb (among
+others creating gitweb.cgi out of gitweb.perl by replacing placeholders such
+as `++GIT_BINDIR++` by their build-time values).
+
+Building and installing gitweb is described in gitweb's INSTALL file
+(in 'gitweb/INSTALL').
+
+
Runtime gitweb configuration
----------------------------
-
Gitweb obtains configuration data from the following sources in the
following order:
@@ -44,266 +53,19 @@ as comments inside 'gitweb.cgi'.
See also gitweb.conf(5) manpage.
-Projects list file format
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Instead of having gitweb find repositories by scanning filesystem starting
-from $projectroot (or $projects_list, if it points to directory), you can
-provide list of projects by setting $projects_list to a text file with list
-of projects (and some additional info). This file uses the following
-format:
-
-One record (for project / repository) per line, whitespace separated fields;
-does not support (at least for now) lines continuation (newline escaping).
-Leading and trailing whitespace are ignored, any run of whitespace can be
-used as field separator (rules for Perl's "split(' ', $line)"). Keyed by
-the first field, which is project name, i.e. path to repository GIT_DIR
-relative to $projectroot. Fields use modified URI encoding, defined in
-RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding"
-(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference
-being that SP (' ') can be encoded as '+' (and therefore '+' has to be also
-percent-encoded). Reserved characters are: '%' (used for encoding), '+'
-(can be used to encode SPACE), all whitespace characters as defined in Perl,
-including SP, TAB and LF, (used to separate fields in a record).
-
-Currently list of fields is
- * <repository path> - path to repository GIT_DIR, relative to $projectroot
- * <repository owner> - displayed as repository owner, preferably full name,
- or email, or both
-
-You can additionally use $projects_list file to limit which repositories
-are visible, and together with $strict_export to limit access to
-repositories (see "Gitweb repositories" section in gitweb/INSTALL).
-
-
-Per-repository gitweb configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can also configure individual repositories shown in gitweb by creating
-file in the GIT_DIR of git repository, or by setting some repo configuration
-variable (in GIT_DIR/config).
-
-You can use the following files in repository:
- * README.html
- A .html file (HTML fragment) which is included on the gitweb project
- summary page inside <div> block element. You can use it for longer
- description of a project, to provide links (for example to project's
- homepage), etc. This is recognized only if XSS prevention is off
- ($prevent_xss is false); a way to include a readme safely when XSS
- prevention is on may be worked out in the future.
- * description (or gitweb.description)
- Short (shortened by default to 25 characters in the projects list page)
- single line description of a project (of a repository). Plain text file;
- HTML will be escaped. By default set to
- Unnamed repository; edit this file to name it for gitweb.
- from the template during repository creation. You can use the
- gitweb.description repo configuration variable, but the file takes
- precedence.
- * category (or gitweb.category)
- Singe line category of a project, used to group projects if
- $projects_list_group_categories is enabled. By default (file and
- configuration variable absent), uncategorized projects are put in
- the $project_list_default_category category. You can use the
- gitweb.category repo configuration variable, but the file takes
- precedence.
- * cloneurl (or multiple-valued gitweb.url)
- File with repository URL (used for clone and fetch), one per line.
- Displayed in the project summary page. You can use multiple-valued
- gitweb.url repository configuration variable for that, but the file
- takes precedence.
- * gitweb.owner
- You can use the gitweb.owner repository configuration variable to set
- repository's owner. It is displayed in the project list and summary
- page. If it's not set, filesystem directory's owner is used
- (via GECOS field / real name field from getpwiud(3)).
- * various gitweb.* config variables (in config)
- Read description of %feature hash for detailed list, and some
- descriptions.
-
-
-Webserver configuration
------------------------
-
-If you want to have one URL for both gitweb and your http://
-repositories, you can configure apache like this:
-
-<VirtualHost *:80>
- ServerName git.example.org
- DocumentRoot /pub/git
- SetEnv GITWEB_CONFIG /etc/gitweb.conf
-
- # turning on mod rewrite
- RewriteEngine on
-
- # make the front page an internal rewrite to the gitweb script
- RewriteRule ^/$ /cgi-bin/gitweb.cgi
-
- # make access for "dumb clients" work
- RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
-</VirtualHost>
-
-The above configuration expects your public repositories to live under
-/pub/git and will serve them as http://git.domain.org/dir-under-pub-git,
-both as cloneable GIT URL and as browseable gitweb interface.
-If you then start your git-daemon with --base-path=/pub/git --export-all
-then you can even use the git:// URL with exactly the same path.
-
-Setting the environment variable GITWEB_CONFIG will tell gitweb to use
-the named file (i.e. in this example /etc/gitweb.conf) as a
-configuration for gitweb. Perl variables defined in here will
-override the defaults given at the head of the gitweb.perl (or
-gitweb.cgi). Look at the comments in that file for information on
-which variables and what they mean.
-
-If you use the rewrite rules from the example you'll likely also need
-something like the following in your gitweb.conf (or gitweb_config.perl) file:
-
- @stylesheets = ("/some/absolute/path/gitweb.css");
- $my_uri = "/";
- $home_link = "/";
-
-
-Webserver configuration with multiple projects' root
-----------------------------------------------------
-
-If you want to use gitweb with several project roots you can edit your apache
-virtual host and gitweb.conf configuration files like this :
-
-virtual host configuration :
-
-<VirtualHost *:80>
- ServerName git.example.org
- DocumentRoot /pub/git
- SetEnv GITWEB_CONFIG /etc/gitweb.conf
-
- # turning on mod rewrite
- RewriteEngine on
-
- # make the front page an internal rewrite to the gitweb script
- RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT]
-
- # look for a public_git folder in unix users' home
- # http://git.example.org/~<user>/
- RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
-
- # http://git.example.org/+<user>/
- #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
-
- # http://git.example.org/user/<user>/
- #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
-
- # defined list of project roots
- RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
- RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
-
- # make access for "dumb clients" work
- RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
-</VirtualHost>
-
-gitweb.conf configuration :
-
-$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
-
-These configurations enable two things. First, each unix user (<user>) of the
-server will be able to browse through gitweb git repositories found in
-~/public_git/ with the following url : http://git.example.org/~<user>/
-
-If you do not want this feature on your server just remove the second rewrite rule.
-
-If you already use mod_userdir in your virtual host or you don't want to use
-the '~' as first character just comment or remove the second rewrite rule and
-uncomment one of the following according to what you want.
-
-Second, repositories found in /pub/scm/ and /var/git/ will be accesible
-through http://git.example.org/scm/ and http://git.example.org/var/.
-You can add as many project roots as you want by adding rewrite rules like the
-third and the fourth.
-
-
-PATH_INFO usage
------------------------
-If you enable PATH_INFO usage in gitweb by putting
-
- $feature{'pathinfo'}{'default'} = [1];
-
-in your gitweb.conf, it is possible to set up your server so that it
-consumes and produces URLs in the form
-
-http://git.example.com/project.git/shortlog/sometag
-
-by using a configuration such as the following, that assumes that
-/var/www/gitweb is the DocumentRoot of your webserver, and that it
-contains the gitweb.cgi script and complementary static files
-(stylesheet, favicon):
-
-<VirtualHost *:80>
- ServerAlias git.example.com
-
- DocumentRoot /var/www/gitweb
-
- <Directory /var/www/gitweb>
- Options ExecCGI
- AddHandler cgi-script cgi
-
- DirectoryIndex gitweb.cgi
-
- RewriteEngine On
- RewriteCond %{REQUEST_FILENAME} !-f
- RewriteCond %{REQUEST_FILENAME} !-d
- RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
- </Directory>
-</VirtualHost>
-
-The rewrite rule guarantees that existing static files will be properly
-served, whereas any other URL will be passed to gitweb as PATH_INFO
-parameter.
-
-Notice that in this case you don't need special settings for
-@stylesheets, $my_uri and $home_link, but you lose "dumb client" access
-to your project .git dirs. A possible workaround for the latter is the
-following: in your project root dir (e.g. /pub/git) have the projects
-named without a .git extension (e.g. /pub/git/project instead of
-/pub/git/project.git) and configure Apache as follows:
-
-<VirtualHost *:80>
- ServerAlias git.example.com
-
- DocumentRoot /var/www/gitweb
-
- AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
- <Directory /var/www/gitweb>
- Options ExecCGI
- AddHandler cgi-script cgi
-
- DirectoryIndex gitweb.cgi
-
- RewriteEngine On
- RewriteCond %{REQUEST_FILENAME} !-f
- RewriteCond %{REQUEST_FILENAME} !-d
- RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
- </Directory>
-</VirtualHost>
-
-The additional AliasMatch makes it so that
-
-http://git.example.com/project.git
-
-will give raw access to the project's git dir (so that the project can
-be cloned), while
-
-http://git.example.com/project
-
-will provide human-friendly gitweb access.
-
-This solution is not 100% bulletproof, in the sense that if some project
-has a named ref (branch, tag) starting with 'git/', then paths such as
-
-http://git.example.com/project/command/abranch..git/abranch
-
-will fail with a 404 error.
+Web server configuration
+------------------------
+Gitweb can be run as CGI script, as legacy mod_perl application (using
+ModPerl::Registry), and as FastCGI script. You can find some simple examples
+in "Example web server configuration" section in INSTALL file for gitweb (in
+gitweb/INSTALL).
+See "Webserver configuration" and "Advanced web server setup" sections in
+gitweb(1) manpage.
+AUTHORS
+-------
Originally written by:
Kay Sievers <kay.sievers@vrfy.org>
--
1.7.6
^ permalink raw reply related
* [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)
From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw)
To: git, Drew Northup
Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin,
Jakub Narebski
In-Reply-To: <1316352884-26193-1-git-send-email-jnareb@gmail.com>
From: Drew Northup <drew.northup@maine.edu>
Much of what is in gitweb.conf.txt has been pulled directly from the
README file of gitweb. The manpage was supplemented with description
of missing gitweb config variables, and with description of gitweb's
%features.
There remains a bit of redundancy, which should be reduced if
possible... but I think some of duplication of information is
inevitable.
[jn: Improved, extended, removed duplicate info from README]
Signed-off-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
Differences from v3 version include:
* SYNOPSIS changed from ssh_config(5) like to gitignore(5) like,
i.e. [verse] changed to straight list of files
* The beginning of DISCUSSION section now mentions new gitweb-common.conf
file, and was significantly rewritten for better readibility, following
gitweb/README.
* FILES and ENVIRONMENT section mention /etc/gitweb-common.conf and
GITWEB_CONFIG_COMMON, respectively.
* Added information about inclusion mechanism, i.e. read_config_file()
subroutine.
* Fixed formatting of continued description list
* Infrastructure for supporting "make -C gitweb doc" (used to test
formatted output of manpages from those patches) is now moved to a
separate, earlier commit.
Documentation/Makefile | 2 +-
Documentation/gitweb.conf.txt | 781 +++++++++++++++++++++++++++++++++++++++++
gitweb/README | 133 +-------
3 files changed, 783 insertions(+), 133 deletions(-)
create mode 100644 Documentation/gitweb.conf.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 44be67b..6d71943 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -3,7 +3,7 @@ MAN1_TXT= \
$(wildcard git-*.txt)) \
gitk.txt git.txt
MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
- gitrepository-layout.txt
+ gitrepository-layout.txt gitweb.conf.txt
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
new file mode 100644
index 0000000..2769302
--- /dev/null
+++ b/Documentation/gitweb.conf.txt
@@ -0,0 +1,781 @@
+gitweb.conf(5)
+==============
+
+NAME
+----
+gitweb.conf - Gitweb (git web interface) configuration file
+
+SYNOPSIS
+--------
+/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl
+
+DESCRIPTION
+-----------
+
+The gitweb CGI script for viewing Git repositories over the web uses a
+perl script fragment as its configuration file. You can set variables
+using "`our $variable = value`"; text from a "#" character until the
+end of a line is ignored. See *perlsyn*(1) for details.
+
+An example:
+
+ # gitweb configuration file for http://git.example.org
+ #
+ our $projectroot = "/srv/git"; # FHS recommendation
+ our $site_name = 'Example.org >> Repos';
+
+
+The configuration file is used to override the default settings that
+were built into gitweb at the time 'gitweb.cgi' script was generated.
+
+While one could just alter the configuration settings in the gitweb
+CGI itself, those changes would be lost upon upgrade. Configuration
+settings might also be placed into a file in the same directory as the
+CGI script with the default name 'gitweb_config.perl' -- allowing
+one to have multiple gitweb instances with different configurations by
+the use of symlinks.
+
+
+DISCUSSION
+----------
+Gitweb obtains configuration data from the following sources in the
+following order:
+
+ * built-in values (some set during build stage),
+
+ * common system-wide configuration file (defaults to
+ '/etc/gitweb-common.conf'),
+
+ * either per-instance configuration file (defaults to 'gitweb_config.perl'
+ in the same directory as the installed gitweb), or if it does not exists
+ then system-wide configuration file (defaults to '/etc/gitweb.conf').
+
+Values obtained in later configuration files override values obtained earlier
+in above sequence.
+
+The location of common system-wide configuration file, of fallback system-wide
+configuration file and of per-instance configuration file is defined at compile
+time using the build-time Makefile configuration variables, respectively
+`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`.
+
+You can override location of gitweb configuration files during runtime
+by setting respective environment variables: `GITWEB_CONFIG_COMMON`,
+`GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` to non-empty value.
+
+
+The syntax of the configuration files is that of Perl, as these files are
+indeed handled as fragments of Perl code (the language that gitweb itself is
+written in). Variables may be set using "`our $variable = value`"; text from
+"#" character until the end of a line is ignored. See the *perlsyn*(1) man
+page for more information.
+
+Actually using `our` qualifier in `our $variable = <value>;` is a safety
+check: if newer gitweb does no longer use given variable, by using `our` we
+won't get syntax errors.
+
+You can include other configuration file using read_config_file()
+subroutine. For example, you can read defaults in fallback
+system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding
+
+ read_config_file($GITWEB_CONFIG_SYSTEM);
+
+at very beginning of per-instance GITWEB_CONFIG file. In this case
+settings in said per-instance file will override settings from
+system-wide configuration file. Note that read_config_file checks
+itself that the file it reads exists.
+
+
+The default configuration with no configuration file at all may work
+perfectly well for some installations. Still, a configuration file is
+useful for customizing or tweaking the behavior of gitweb in many ways, and
+some optional features will not be present unless explicitly enabled using
+the configurable `%features` variable (see also "Configuring gitweb
+features" section below).
+
+
+CONFIGURATION VARIABLES
+-----------------------
+Some of configuration variables have their default values (embedded in CGI
+file) set during building gitweb -- if that is the case, it is put in their
+description. See gitweb's 'INSTALL' file for instructions on building and
+installing gitweb.
+
+
+Location of repositories
+~~~~~~~~~~~~~~~~~~~~~~~~
+Configuration variables described below control finding git repositories by
+gitweb, and control display and access to repositories.
+
+$projectroot::
+ Absolute filesystem path which will be prepended to project path;
+ the path to repository is `$projectroot/$project`. Set to
+ `$GITWEB_PROJECTROOT` during installation. This variable has to be
+ set correctly for gitweb to find repositories.
++
+For example if `$projectroot` is set to "/srv/git" by putting the following
+in gitweb config file:
++
+----------------------------------------------------------------------------
+our $projectroot = "/srv/git";
+----------------------------------------------------------------------------
++
+then
++
+------------------------------------------------
+http://git.example.com/gitweb.cgi?p=foo/bar.git
+------------------------------------------------
++
+or its path_info based equivalent
++
+------------------------------------------------
+http://git.example.com/gitweb.cgi/foo/bar.git
+------------------------------------------------
++
+will map to path '/srv/git/foo/bar.git' on filesystem.
+
+$project_maxdepth::
+ Filesystem traversing depth limit for recursively scanning for git
+ repositories, used if `$projects_list` (below) is unset. The default
+ value of this variable is determined by build-time configuration
+ variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.
+
+$projects_list::
+ Plain text file listing projects or name of directory
+ to be scanned for projects.
++
+Project list files should list one project per line, with each line
+having the following format
++
+-----------------------------------------------------------------------------
+<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
+-----------------------------------------------------------------------------
++
+The default value of this variable is determined by the `GITWEB_LIST`
+makefile variable at installation time. If this variable is empty, gitweb
+will fall back to scanning the `$projectroot` directory for repositories.
+
+$export_ok::
+ Show repository only if this file exists (in repository). Only
+ effective if this variable evaluates to true. Can be set during
+ building gitweb via `GITWEB_EXPORT_OK`. [No default / Not set]
+
+$export_auth_hook::
+ Show repository only if this subroutine returns true, when given as
+ the only parameter the full path to the project. Example:
++
+----------------------------------------------------------------------------
+our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
+----------------------------------------------------------------------------
++
+though the above might be done by using `$export_ok` instead
++
+----------------------------------------------------------------------------
+our $export_ok = "git-daemon-export-ok";
+----------------------------------------------------------------------------
+
+$strict_export::
+ Only allow viewing of repositories also shown on the overview page.
+ This for example makes `$gitweb_export_ok` file decide if repository is
+ available and not only if it is shown. If `$gitweb_list` points to
+ file with list of project, only those repositories listed would be
+ available for gitweb. Can be set during building gitweb via
+ `GITWEB_STRICT_EXPORT`. [No default / Not set]
+
+
+Finding files
+~~~~~~~~~~~~~
+Those configuration variables tell gitweb where to find files. Values of
+those variables are paths on filesystem. Of those only `$GIT` is required
+to be (correctly) set for gitweb to be able to work; all the rest are
+required only for extra configuration or extra features.
+
+$GIT::
+ Core git executable to use. By default set to `$GIT_BINDIR/git`, which
+ in turn is by default set to `$(bindir)/git`. If you use git from binary
+ package, set this to "/usr/bin/git". This can just be "git" if your
+ webserver has a sensible PATH. If you have multiple git versions installed
+ it can be used to choose which one to use.
+
+$mimetypes_file::
+ File to use for (filename extension based) guessing of MIME types before
+ trying '/etc/mime.types'. Path, if relative, is taken currently as
+ relative to the current git repository. [Unset by default]
+
+$highlight_bin::
+ Path to the highlight executable to use (must be the one from
+ http://www.andre-simon.de due to assumptions about parameters and output).
+ Useful if 'highlight' is not installed on your webserver's PATH.
+ [Default: 'highlight']
++
+*NOTE*: if you want to add support for new syntax (supported by
+"highlight" but not used by gitweb), you need to modify `%highlight_ext`
+or `%highlight_basename`, depending on whether you detect type of file
+based on extension (for example "*.sh") or on its basename (for example
+"Makefile"). Keys of those hashes are extension or basename,
+respectively, and value for given key is name of syntax to be passed via
+`--syntax <syntax>` to highlighter.
+
+
+Links and their targets
+~~~~~~~~~~~~~~~~~~~~~~~
+Configuration variables described below configure some of gitweb links:
+their target and their look (text or image), and where to find page
+prerequisites (stylesheet, favicon, images, scripts). Usually they are left
+at their default values, with the possible exception of `@stylesheets`
+variable.
+
+@stylesheets::
+ List of URIs of stylesheets (relative to base URI of a page). You
+ might specify more than one stylesheet, for example use gitweb.css
+ as base, with site specific modifications in separate stylesheet
+ to make it easier to upgrade gitweb. You can add a `site` stylesheet
+ for example by putting
++
+----------------------------------------------------------------------------
+push @stylesheets, "gitweb-site.css";
+----------------------------------------------------------------------------
++
+in the gitweb config file. Those values that are relative paths, are
+relative to base URI of gitweb.
++
+This list should contain URI of gitweb's stylesheet. The URI of gitweb
+stylesheet is set during build time via `GITWEB_CSS` variable. It's default
+value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`
+variable is defined, i.e. if CSS minifier is used during build).
++
+*Note*: there is also legacy `$stylesheet` configuration variable, which was
+used by older gitweb.
+
+$logo::
+ Points to the location where you put 'git-logo.png' on your web
+ server, or to be more generic URI of logo, 72x27 size). This image
+ is displayed in top right corner of each gitweb page, and used as
+ logo for Atom feed. Relative to base URI of gitweb (as a path).
+ Can be adjusted during building gitweb using `GITWEB_LOGO` variable
+ [Default: 'static/git-logo.png']
+
+$favicon::
+ Points to the location where you put 'git-favicon.png' on your web
+ server, or to be more generic URI of favicon, assumed to be
+ "image/png" type; web browsers that support favicons (website icons)
+ may display them in the browser's URL bar and next to site name in
+ bookmarks. Relative to base URI of gitweb. Can be adjusted during
+ build time using `GITWEB_FAVICON` variable.
+ [Default: 'static/git-favicon.png']
+
+$javascript::
+ Points to the location where you put 'gitweb.js' on your web server,
+ or to be more generic URI of JavaScript code used by gitweb.
+ Relative to base URI of gitweb. Set during build time using
+ `GITWEB_JS` build-time configuration variable.
++
+Default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if
+`JSMIN` build variable is defined, i.e. if JavaScript minifier is used
+during build. *Note* that this single file is build (composed) of
+individual JavaScript "modules".
+
+$home_link::
+ Target of the home link on top of all pages (the first part of view
+ "breadcrumbs"). By default set to absolute URI of a page ($my_uri).
+
+$home_link_str::
+ Description of the home link on top of all pages, leading to $home_link
+ (usually main gitweb page, which means projects list). Used as first
+ part of gitweb view "breadcrumb trail": `<home> / <project> / <view>`.
+ Can be set during build time using `GITWEB_HOME_LINK_STR` variable.
+ [Default: "projects"]
+
+$logo_url::
+$logo_label::
+ URI and label (title) of GIT logo link (or your site logo, if you choose
+ to use different logo image). By default they point to git homepage;
+ in the past they pointed to git documentation at www.kernel.org.
+
+
+Changing gitweb look
+~~~~~~~~~~~~~~~~~~~~
+You can adjust how pages generated by gitweb look using variables described
+below. You can change site name, add common headers and footers for all
+pages, and add description of gitweb installation on its main page (which is
+projects list page), etc.
+
+$site_name::
+ Name of your site or organization to appear in page titles. Set it
+ to something descriptive for clearer bookmarks etc. If not set (if
+ empty) then gitweb uses value of `SERVER_NAME` CGI environment
+ variable setting prefix of each page title to "$SERVER_NAME Git", or
+ "Untitled Git" if this variable is not set (e.g. if running gitweb
+ as standalone script).
++
+Can be set using `GITWEB_SITENAME` during building. [No default]
+
+$site_header::
+ Filename of html text to include at top of each page. Relative to
+ 'gitweb.cgi' script. Can be set using `GITWEB_SITE_HEADER` during
+ building. [No default]
+
+$site_footer::
+ Filename of html text to include at bottom of each page. Relative to
+ gitweb.cgi script. Can be set using `GITWEB_SITE_FOOTER` during
+ building. [No default]
+
+$home_text::
+ Points to an HTML file which, if it exists, is included on the
+ gitweb projects overview page ("projects_list" view). Relative to
+ gitweb.cgi script. Default value can be adjusted using during build
+ via `GITWEB_HOMETEXT` variable.
+ [Default: 'indextext.html']
+
+$projects_list_description_width::
+ The width (in characters) of the projects list "Description" column.
+ Longer descriptions will be cut (trying to cut at word boundary);
+ full description is available as 'title' attribute (usually shown on
+ mouseover). By default set to 25, which might be too small if you
+ use long project descriptions.
+
+$default_projects_order::
+ Default value of ordering of projects on projects list page. Valid
+ values are "none" (unsorted), "project" (by project name, i.e. path
+ to repository relative to `$projectroot`), "descr" (project
+ description), "owner", and "age" (by date of most current commit).
++
+Default value is "project". Unknown value means unsorted.
+
+
+Changing gitweb behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+Those configuration variables control _internal_ gitweb behavior.
+
+$default_blob_plain_mimetype::
+ Default mimetype for blob_plain (raw) view, if mimetype checking
+ doesn't result in some other type; by default "text/plain".
+
+$default_text_plain_charset::
+ Default charset for text files. If not set, web server configuration
+ would be used.
+
+$fallback_encoding::
+ Gitweb assumes this charset if line contains non-UTF-8 characters.
+ Fallback decoding is used without error checking, so it can be even
+ "utf-8". Value must be valid encoding; see *Encoding::Supported*(3pm)
+ man page for a list. By default "latin1", aka. "iso-8859-1".
+
+@diff_opts::
+ Rename detection options for git-diff and git-diff-tree. By default
+ (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies,
+ or set it to () i.e. empty list if you don't want to have renames
+ detection.
+
+Extra features, administrative
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Most of features are configured via `%feature` hash; however some of extra
+gitweb features can be turned on and configured using variables described
+below. This list beside configuration variables that control how gitweb
+looks does contain variables configuring administrative side of gitweb
+(e.g. cross-site scripting prevention; admittedly this as side effect
+affects how "summary" pages look like, or load limiting).
+
+@git_base_url_list::
+ List of git base URLs used for URL to where fetch project from, shown
+ in project summary page. Full URL is "`$git_base_url/$project`". You
+ can setup multiple base URLs (for example one for `git://` protocol
+ access, and one for `http://` "dumb" protocol access). Note that per
+ repository configuration can be set in '$GIT_DIR/cloneurl' file, or as
+ values of multi-value `gitweb.url` configuration variable in project
+ config.
++
+You can setup one single value (single entry/item in this list) during
+building by using `GITWEB_BASE_URL` built-time configuration variable.
+[No default]
+
+$projects_list_group_categories::
+ Enables the grouping of projects by category on the project list page.
+ The category of a project is determined by the `$GIT_DIR/category` file
+ or the `gitweb.category` variable in its repository configuration.
+ [Disabled by default].
+
+$project_list_default_category::
+ Default category for projects for which none is specified. If set to
+ the empty string, such projects will remain uncategorized and listed at
+ the top, above categorized projects. Used only if project cateories are
+ enabled, which means if `$projects_list_group_categories` is true.
+ [Default: "" (empty string)]
+
+$prevent_xss::
+ If true, some gitweb features are disabled to prevent content in
+ repositories from launching cross-site scripting (XSS) attacks. Set this
+ to true if you don't trust the content of your repositories.
+ [Default: false].
+
+$maxload::
+ Used to set the maximum load that we will still respond to gitweb queries.
+ If server load exceed this value then return "503 Service Unavailable"
+ error. Server load is taken to be 0 if gitweb cannot determine its value.
+ Set it to undefined value to turn it off. [Default: 300]
+
+$per_request_config::
+ If set to code reference, it would be run once per each request. You can
+ set parts of configuration that change per session, e.g. by adding
+ the following code to gitweb configuration file
++
+--------------------------------------------------------------------------------
+our $per_request_config = sub {
+ $ENV{GL_USER} = $cgi->remote_user || "gitweb";
+};
+--------------------------------------------------------------------------------
++
+Otherwise it is treated as boolean value: if true gitweb would process
+config file once per request, if false it would process config file only
+once. [Default: true]
++
+*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default
+values before every request, so if you want to change them, be sure to set
+this variable to true or a code reference effecting the desired changes.
+
+
+Other variables
+~~~~~~~~~~~~~~~
+Usually you should not need to change (adjust) any of configuration
+variables described below; they should be automatically set by gitweb to
+correct value.
+
+
+$version::
+ Gitweb version, set automatically when creating gitweb.cgi from
+ gitweb.perl. You might want to modify it if you are running modified
+ gitweb, for example
++
+---------------------------------------------------
+our $version .= " with caching";
+---------------------------------------------------
+
+$my_url::
+$my_uri::
+ Full URL and absolute URL of gitweb script;
+ in earlier versions of gitweb you might have need to set those
+ variables, now there should be no need to do it. See
+ `$per_request_config` if you need to set them still.
+
+$base_url::
+ Base URL for relative URLs in pages generated by gitweb,
+ (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),
+ needed and used only for URLs with nonempty PATH_INFO via
+ '<base href="$base_url">'. Usually gitweb sets its value correctly,
+ and there is no need to set this variable, e.g. to $my_uri or "/".
+ See `$per_request_config` if you need to set it anyway.
+
+
+CONFIGURING GITWEB FEATURES
+---------------------------
+Many gitweb features can be enabled (or disabled) and configured using the
+`%feature` hash. Names of gitweb features are keys of this hash.
+
+Each `%feature` hash element is a hash reference and has the following
+structure:
+----------------------------------------------------------------------
+"<feature_name>" => {
+ "sub" => <feature-sub (subroutine)>,
+ "override" => <allow-override (boolean)>,
+ "default" => [ <options>... ]
+},
+----------------------------------------------------------------------
+Some of features does not support project specific override. For those
+features the structure of appropriate `%feature` hash element has a simpler
+form:
+----------------------------------------------------------------------
+"<feature_name>" => {
+ "override" => 0,
+ "default" => [ <options>... ]
+},
+----------------------------------------------------------------------
+As one can see it lacks \'sub' element.
+
+The meaning of respective parts of feature configuration are described
+below:
+
+default::
+ List (array reference) of feature parameters (if there are any),
+ used also to toggle (enable or disable) given feature.
++
+Note that it is currently *always* an array reference, even if
+feature doesn't accept any configuration parameters, and \'default'
+is used only to turn it on or off. In such case you turn feature on
+by setting this element to `[1]`, and torn it off by setting it to
+`[0]`. See also part about "blame" feature in the "Examples"
+section.
++
+To disable feature that accepts parameters (is configurable), you
+need to set this element to empty list i.e. `[]`.
+
+override::
+ If it has a true value then given feature is overridable, which
+ means that it can be configured (or enabled/disabled) on
+ per-repository basis.
++
+Usually given "<feature>" is configurable via `gitweb.<feature>`
+config variable in per-repository git configuration file.
++
+*Note* that no feature is overridable by default.
+
+sub::
+ Subroutine that will be called with default options as parameters to
+ examine per-repository configuration, but only if feature is
+ overridable (\'override' is set to true). If not present then
+ per-repository override for given feature is not supported.
++
+You wouldn't need to ever change it in gitweb config file.
+
+
+Features in `%feature`
+~~~~~~~~~~~~~~~~~~~~~~
+Below there are described gitweb features that are configurable via
+`%feature` hash. For a complete list please consult gitweb sources.
+
+blame::
+ Enable the "blame" and "blame_incremental" blob views, showing for
+ each line the last commit that modified it; see linkgit:git-blame[1].
+ This can be very CPU-intensive and is therefore disabled by default.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.blame` configuration variable (boolean).
+
+snapshot::
+ Enable and configure "snapshot" action, providing a compressed
+ archive of any tree or commit; see also linkgit:git-archive[1].
+ This can potentally generate high traffic if you have large project.
++
+The value (of \'default') is a list of names of snapshot formats
+defined in `%known_snapshot_formats` hash, that you wish to offer.
+Among supported formats are "tgz", "tbz2", "txz" (gzip/bzip2/xz
+compressed tar archive) and "zip"; please consult gitweb sources for
+a definitive list. By default only "tgz" is offered.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.blame` configuration variable, which contains
+a comma separated list of formats, or "none" to disable snapshots.
+Unknown values will be ignored.
+
+grep::
+ Enable grep search, which will list the files in currently selected
+ tree (directory) containing the given string; see linkgit:git-grep[1].
+ This can be potentially CPU-intensive, of course. Enabled by default.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.grep` configuration variable (boolean).
+
+pickaxe::
+ Enable the so called pickaxe search, which will list the commits
+ that modified a given string in a file. This can be practical and
+ quite faster alternative to "blame" action, but still potentially
+ CPU-intensive. Enabled by default.
++
+The pickaxe search is described in linkgit:git-log[1] (the
+description of `-S<string>` option, which refers to pickaxe entry in
+linkgit:gitdiffcore[7] for more details).
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.pickaxe` configuration variable (boolean).
+
+show-sizes::
+ Enable showing size of blobs (ordinary files) in a "tree" view, in a
+ separate column, similar to what `ls -l` does; see description of
+ `-l` option in linkgit:git-ls-tree[1] manpage. This cost a bit of
+ I/O. Enabled by default.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.showsizes` configuration variable (boolean).
+
+patches::
+ Configure "patches" view, which displays list of commits in email
+ (plain text) output format; see also linkgit:git-format-patch[1].
+ The value is the maximum number of patches in a patchset generated
+ in "patches" view. Set this to 0 or undef to disable patch view, or
+ to a negative number to remove any limit. Default value is 16.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.patches` configuration variable (integer).
+
+avatar::
+ Avatar support. When this feature is enabled, views such as
+ "shortlog" or "commit" will display an avatar associated with
+ the email of the committer(s) and/or author(s).
++
+Currently available providers are *"gravatar"* and *"picon"*.
+If an unknown provider is specified, the feature is disabled.
+*Note* that some provides might require extra Perl packages to be
+installed; see 'gitweb/INSTALL' for more details.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.avatar` configuration variable.
++
+See also `%avatar_size` with pixel sizes for icons and avatars
+("default" is used for one-line like "log" and "shortlog", "double"
+is used for two-line like "commit", "commitdiff" or "tag"). If the
+default font sizes or lineheights are changed (e.g. via adding extra
+CSS stylesheet in `@stylesheets`), it may be appropriate to change
+these values.
+
+highlight::
+ Server-side syntax hightlight support in "blob" view. It requires
+ `$highlight_bin` program available (see description of this variable
+ in "Configuration variables" section above), and therefore is
+ disabled by default.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.highlight` configuration variable (boolean).
+
+remote_heads::
+ Enable displaying remote heads (remote-tracking branches) in the "heads"
+ list. In most cases it is unnecessary internal private detail, and it
+ is therefore disabled by default. linkgit:git-instaweb[1], which is
+ usually used to browse local repositories, enables and uses this
+ feature.
++
+This feature can be configured on a per-repository basis via
+repository's `gitweb.remote_heads` configuration variable (boolean).
+
+
+The list below presents features that do not allow project specific
+overrides.
+
+search::
+ Enable text search, which will list the commits which match author,
+ committer or commit text to a given string; see description of
+ `--author`, `--committer` and `--grep` options in linkgit:git-log[1]
+ manpage. Enabled by default.
++
+Project specific override is not supported.
+
+forks::
+ Make gitweb consider projects in subdirectories of project root
+ (basename) to be forks of existing projects. Given project
+ `$projname.git`, projects matching `$projname/*.git` will not be
+ shown in the main projects list, instead a \'+' mark will be added
+ to `$projname` there and a "forks" view will be enabled for the
+ project, listing all the forks. If project list is taken from a
+ file, forks have to be listed after the main project.
++
+Project specific override is not supported.
+
+actions::
+ Insert custom links to the action bar of all project pages. This
+ enables you to link to third-party scripts integrating into gitweb.
++
+The "default" value consists of a list of triplets in the form
+`("<label>", "<link>", "<position>")` where "position" is the label
+after which to insert the link, "link" is a format string where `%n`
+expands to the project name, `%f` to the project path within the
+filesystem, `%h` to the current hash (\'h' gitweb parameter) and
+`%b` to the current hash base (\'hb' gitweb parameter); `%%` expands
+to \'%'.
++
+For example http://repo.or.cz git hosting site sets it to the
+following to enable graphical log (via third party tool
+*git-browser*):
++
+----------------------------------------------------------------------
+$feature{'actions'}{'default'} =
+ [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
+----------------------------------------------------------------------
++
+This adds link titled "graphiclog" after "summary" link, leading to
+`git-browser` script, passing `r=<project>` as a query parameter.
++
+Project specific override is not supported.
+
+timed::
+ Enable displaying how much time and how many git commands it took to
+ generate and display page in the page footer (at the bottom of
+ page). For example it might be: "This page took 6.53325 seconds and
+ 13 git commands to generate." Disabled by default.
++
+Project specific override is not supported.
+
+javascript-timezone::
+ Enable and configure ability to change common timezone for dates in
+ gitweb output via JavaScript. Dates in gitweb output include
+ authordate and comitterdate in "commit", "commitdiff" and "log"
+ views, and taggerdate in "tag" view. Enabled by default.
++
+Value is list of three values: default timezone (if client didn't
+select other timezone and saved it in a cookie), name of cookie
+where to store selected timezone, and CSS class used to mark up
+dates for manipulation. If you want to turn it off, set "default"
+to empty list: `[]`.
++
+In most case you would want to change only default timezone:
++
+---------------------------------------------------------------------------
+$feature{'javascript-timezone'}{'default'}[0] = "utc";
+---------------------------------------------------------------------------
++
+Timezone value can be "local" (for local timezone that browser uses), "utc"
+(what gitweb uses when JavaScript or this feature is disabled), or numerical
+timezone in the form of "+/-HHMM" for example "+0200". This way is
+guaranteed to be backward compatibile.
++
+Project specific override is not supported.
+
+
+EXAMPLES
+--------
+
+To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
+"zip" snapshots), while allowing individual projects to turn them off, put
+the following in your GITWEB_CONFIG file:
+
+ $feature{'blame'}{'default'} = [1];
+ $feature{'blame'}{'override'} = 1;
+
+ $feature{'pickaxe'}{'default'} = [1];
+ $feature{'pickaxe'}{'override'} = 1;
+
+ $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
+ $feature{'snapshot'}{'override'} = 1;
+
+If you allow overriding for the snapshot feature, you can specify which
+snapshot formats are globally disabled. You can also add any command line
+options you want (such as setting the compression level). For instance, you
+can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by
+adding the following lines to your gitweb configuration file:
+
+ $known_snapshot_formats{'zip'}{'disabled'} = 1;
+ $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
+
+ENVIRONMENT
+-----------
+The location of per-instance and system-wide configuration files can be set
+using the following environment variables:
+
+GITWEB_CONFIG::
+ Sets location of per-instance configuration file.
+GITWEB_CONFIG_SYSTEM::
+ Sets location of fallback system-wide configuration file.
+ This file is read only if per-instance one does not exist.
+GITWEB_CONFIG_COMMON::
+ Sets location of common system-wide configuration file.
+
+
+FILES
+-----
+gitweb_config.perl::
+ This is default value for per-instance configuration file. The
+ format of this file is described above.
+/etc/gitweb.conf::
+ This is default value for fallback system-wide configuration
+ file. This file is used only if per-instance configuration
+ variable is not found.
+/etc/gitweb-common.conf::
+ This is default value for common system-wide configuration
+ file.
+
+
+SEE ALSO
+--------
+linkgit:gitweb[1], linkgit:git-instaweb[1]
+
+'gitweb/README', 'gitweb/INSTALL'
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/gitweb/README b/gitweb/README
index a998820..cf528d3 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -41,139 +41,8 @@ Ultimate description on how to reconfigure the default features setting
in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found
as comments inside 'gitweb.cgi'.
-See also the "Gitweb config file" (with an example of config file), and
-the "Gitweb repositories" sections in INSTALL file for gitweb.
-
-
-The gitweb config file is a fragment of perl code. You can set variables
-using "our $variable = value"; text from "#" character until the end
-of a line is ignored. See perlsyn(1) man page for details.
-
-Below is the list of variables which you might want to set in gitweb config.
-See the top of 'gitweb.cgi' for the full list of variables and their
-descriptions.
-
-Gitweb config file variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can set, among others, the following variables in gitweb config files
-(with the exception of $projectroot and $projects_list this list does
-not include variables usually directly set during build):
- * $GIT
- Core git executable to use. By default set to "$GIT_BINDIR/git", which
- in turn is by default set to "$(bindir)/git". If you use git from binary
- package, set this to "/usr/bin/git". This can just be "git" if your
- webserver has a sensible PATH. If you have multiple git versions
- installed it can be used to choose which one to use.
- * $version
- Gitweb version, set automatically when creating gitweb.cgi from
- gitweb.perl. You might want to modify it if you are running modified
- gitweb.
- * $projectroot
- Absolute filesystem path which will be prepended to project path;
- the path to repository is $projectroot/$project. Set to
- $GITWEB_PROJECTROOT during installation. This variable have to be
- set correctly for gitweb to find repositories.
- * $projects_list
- Source of projects list, either directory to scan, or text file
- with list of repositories (in the "<URI-encoded repository path> SP
- <URI-encoded repository owner>" line format; actually there can be
- any sequence of whitespace in place of space (SP)). Set to
- $GITWEB_LIST during installation. If empty, $projectroot is used
- to scan for repositories.
- * $my_url, $my_uri
- Full URL and absolute URL of gitweb script;
- in earlier versions of gitweb you might have need to set those
- variables, now there should be no need to do it. See
- $per_request_config if you need to set them still.
- * $base_url
- Base URL for relative URLs in pages generated by gitweb,
- (e.g. $logo, $favicon, @stylesheets if they are relative URLs),
- needed and used only for URLs with nonempty PATH_INFO via
- <base href="$base_url">. Usually gitweb sets its value correctly,
- and there is no need to set this variable, e.g. to $my_uri or "/".
- See $per_request_config if you need to set it anyway.
- * $home_link
- Target of the home link on top of all pages (the first part of view
- "breadcrumbs"). By default set to absolute URI of a page ($my_uri).
- * @stylesheets
- List of URIs of stylesheets (relative to base URI of a page). You
- might specify more than one stylesheet, for example use gitweb.css
- as base, with site specific modifications in separate stylesheet
- to make it easier to upgrade gitweb. You can add 'site' stylesheet
- for example by using
- push @stylesheets, "gitweb-site.css";
- in the gitweb config file.
- * $logo_url, $logo_label
- URI and label (title) of GIT logo link (or your site logo, if you choose
- to use different logo image). By default they point to git homepage;
- in the past they pointed to git documentation at www.kernel.org.
- * $projects_list_description_width
- The width (in characters) of the projects list "Description" column.
- Longer descriptions will be cut (trying to cut at word boundary);
- full description is available as 'title' attribute (usually shown on
- mouseover). By default set to 25, which might be too small if you
- use long project descriptions.
- * $projects_list_group_categories
- Enables the grouping of projects by category on the project list page.
- The category of a project is determined by the $GIT_DIR/category
- file or the 'gitweb.category' variable in its repository configuration.
- Disabled by default.
- * $project_list_default_category
- Default category for projects for which none is specified. If set
- to the empty string, such projects will remain uncategorized and
- listed at the top, above categorized projects.
- * @git_base_url_list
- List of git base URLs used for URL to where fetch project from, shown
- in project summary page. Full URL is "$git_base_url/$project".
- You can setup multiple base URLs (for example one for git:// protocol
- access, and one for http:// "dumb" protocol access). Note that per
- repository configuration in 'cloneurl' file, or as values of gitweb.url
- project config.
- * $default_blob_plain_mimetype
- Default mimetype for blob_plain (raw) view, if mimetype checking
- doesn't result in some other type; by default 'text/plain'.
- * $default_text_plain_charset
- Default charset for text files. If not set, web server configuration
- would be used.
- * $mimetypes_file
- File to use for (filename extension based) guessing of MIME types before
- trying /etc/mime.types. Path, if relative, is taken currently as
- relative to the current git repository.
- * $fallback_encoding
- Gitweb assumes this charset if line contains non-UTF-8 characters.
- Fallback decoding is used without error checking, so it can be even
- 'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man
- page for a list. By default 'latin1', aka. 'iso-8859-1'.
- * @diff_opts
- Rename detection options for git-diff and git-diff-tree. By default
- ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
- set it to () if you don't want to have renames detection.
- * $prevent_xss
- If true, some gitweb features are disabled to prevent content in
- repositories from launching cross-site scripting (XSS) attacks. Set this
- to true if you don't trust the content of your repositories. The default
- is false.
- * $maxload
- Used to set the maximum load that we will still respond to gitweb queries.
- If server load exceed this value then return "503 Service Unavailable" error.
- Server load is taken to be 0 if gitweb cannot determine its value. Set it to
- undefined value to turn it off. The default is 300.
- * $highlight_bin
- Path to the highlight executable to use (must be the one from
- http://www.andre-simon.de due to assumptions about parameters and output).
- Useful if highlight is not installed on your webserver's PATH.
- [Default: highlight]
- * $per_request_config
- If set to code reference, it would be run once per each request. You can
- set parts of configuration that change per session, e.g. by setting it to
- sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
- Otherwise it is treated as boolean value: if true gitweb would process
- config file once per request, if false it would process config file only
- once. Note: $my_url, $my_uri, and $base_url are overwritten with
- their default values before every request, so if you want to change
- them, be sure to set this variable to true or a code reference effecting
- the desired changes. The default is true.
+See also gitweb.conf(5) manpage.
+
Projects list file format
~~~~~~~~~~~~~~~~~~~~~~~~~
--
1.7.6
^ permalink raw reply related
* [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages
From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw)
To: git, Drew Northup
Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin,
Jakub Narebski
In-Reply-To: <1316352884-26193-1-git-send-email-jnareb@gmail.com>
Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL
and comments in gitweb source code. This is harder to find, use and
browse that manpages ("man gitweb" or "git help gitweb") and HTML
documentation ("git help --web gitweb").
The goal is to move documentation out of gitweb/README to gitweb.txt and
gitweb.conf.txt manpages, reducing its size 10x from around 500 to
around 50 lines (two pages), and move information not related drectly to
building and installing gitweb out of gitweb/INSTALL there.
The idea is to have gitweb manpage sources reside in AsciiDoc format
in Documentation/ directory, like for gitk and git-gui. Alternate
solution would be to have gitweb documentation in gitweb/ directory,
perhaps in POD format (see perlpod(1)).
This patch adds infrastructure for easy generating gitweb-related
manpages. It adds currently empty 'gitweb-doc' target to
Documentation/Makefile, and 'doc' proxy target to gitweb's Makefile.
This way to build gitweb documentation one can use
make -C gitweb doc
or
cd gitweb; make doc
The gitweb.conf(5) and gitweb(1) manpages will be added in subsequent
commits.
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
This changes were part of patch adding first gitweb manpage in
previous version of this series.
Compared to v3 series it lacks the following hunk (at the very end of
Documentation/Makefile):
@@ -334,4 +337,4 @@ quick-install-man:
quick-install-html:
'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)
-.PHONY: FORCE
+.PHONY: FORCE gitweb-doc
This is because it would introduce inconsistency, as 'gitweb-doc'
would be only one of many phony targets in Documentation/Makefile
that is explicitly marked .PHONY
So this is something left for other commit.
Documentation/Makefile | 3 +++
gitweb/Makefile | 7 ++++++-
2 files changed, 9 insertions(+), 1 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6346a75..44be67b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -170,6 +170,9 @@ info: git.info gitman.info
pdf: user-manual.pdf
+GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))
+gitweb-doc: $(GITWEB_DOC)
+
install: install-man
install-man: man
diff --git a/gitweb/Makefile b/gitweb/Makefile
index 1c85b5f..3014d80 100644
--- a/gitweb/Makefile
+++ b/gitweb/Makefile
@@ -174,6 +174,11 @@ test-installed:
GITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \
$(MAKE) -C ../t gitweb-test
+### Documentation
+
+doc:
+ $(MAKE) -C ../Documentation gitweb-doc
+
### Installation rules
install: all
@@ -187,5 +192,5 @@ install: all
clean:
$(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS
-.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE
+.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE
--
1.7.6
^ permalink raw reply related
* [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages
From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw)
To: git, Drew Northup
Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin,
Jakub Narebski
The original patch adding manpage for /etc/gitweb.conf was sent by
Drew Northup; I have added manpage for gitweb itself, inspired by his
patch. Unfortunately Drew doesn't currently have time to work on this
patch (patch series), so that is why it is me resending this series.
It is closer to final version, but still is a bit work in progres.
The main improvement is that documentation now renders correctly as
HTML.
Note that we should probably add gitweb(1) and gitweb.conf(5) manpages
to the list in git(1) manpage.
Table of contents:
~~~~~~~~~~~~~~~~~~
1. The changes to Documentation/Makefile adding gitweb-doc target and
to gitweb/Makefile adding doc target are now upfront as a separate
patch, compared to previous version of this series:
"[RFC/PATCHv3 0/5] Improving gitweb documentation, creating manpages"
http://thread.gmane.org/gmane.comp.version-control.git/175140
This is mainly so that description of ideas, which is common for both
gitweb.conf.txt and gitweb.txt, is in a separate upfront commit
message.
2. The man page for /etc/gitweb.conf is modified, extended and
improved version of original patch by Drew Northup from
"[PATCH/WIP] Starting work on a man page for /etc/gitweb.conf"
http://thread.gmane.org/gmane.comp.version-control.git/173422
Drew version was mostly pulled directly from the README and INSTALL
files of gitweb. I have tried to incorporate comments in mentioned
thread, and to group config variables by category. This version
is also checked that it renders correctly as HTML and as manpage,
compared to version send earlier in
"[RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)"
http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175145
This version now moves, rather than copies, contents from
gitweb/README file. It now has up-to-date commit message.
It was also updated to include new gitweb-comon.conf config file
(common system-wide config file, used *in addition to* per-instance
gitweb_config.perl config file).
3. The man page for gitweb is improved version of patch I have sent to
git mailing list as
"[RFC/PATCHv3 5/5] gitweb: Starting work on a man page for gitweb (WIP)"
http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175146
This version was fixed to render correctly as HTML and as manpage, and
has update commit message.
4. The addition of gitweb manpages to 'gitweb' subpackage in
gitweb.spec (via gitweb.spec.in) is new in this series.
Shortlog:
~~~~~~~~~
Drew Northup (1):
gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)
Jakub Narebski (3):
Documentation: Preparation for gitweb manpages
gitweb: Add manpage for gitweb
gitweb: Add gitweb manpages to 'gitweb' package in git.spec
Diffstat:
~~~~~~~~~
Documentation/Makefile | 7 +-
Documentation/gitweb.conf.txt | 789 +++++++++++++++++++++++++++++++++++++++++
Documentation/gitweb.txt | 703 ++++++++++++++++++++++++++++++++++++
git.spec.in | 7 +
gitweb/INSTALL | 96 +-----
gitweb/Makefile | 7 +-
gitweb/README | 411 ++--------------------
7 files changed, 1540 insertions(+), 480 deletions(-)
create mode 100644 Documentation/gitweb.conf.txt
create mode 100644 Documentation/gitweb.txt
--
1.7.6
^ permalink raw reply
* Re: Most elegant way to reference to SVN from GIT?
From: Manuel Reimer @ 2011-09-18 11:20 UTC (permalink / raw)
To: git
In-Reply-To: <20110918034318.GC17977@sigill.intra.peff.net>
Jeff King wrote:
> You can pull their commits into git using git-svn, and then merge them.
Tried that, but maybe I did something wrong.
If I have a git-svn repo inside my git repo, then for some reason my own repo
doesn't known the git-svn repo. Means that I cannot push changes, that occured
in the SVN repo, to my GIT server.
So I'm still searching for an elegant way to get SVN into my GIT repo. As
submodules make it more difficult to clone the project, I think it would be nice
to be just able to fetch the stuff from SVN "commit by commit" and then have
them as git commits in my own tree. So far I wasn't able to get this done...
Yours
Manuel
^ permalink raw reply
* [PATCH] git-web--browse: invoke kfmclient directly
From: Chris Packham @ 2011-09-18 10:20 UTC (permalink / raw)
To: git; +Cc: Chris Packham, peff, chriscool, jepler
In-Reply-To: <20110918032933.GA17977@sigill.intra.peff.net>
Instead of using eval which causes problems when a URL contains an
appropriately escaped ampersand (\&).
Cc: peff@peff.net
Cc: chriscool@tuxfamily.org
Cc: jepler@unpythonic.net
Signed-off-by: Chris Packham <judge.packham@gmail.com>
---
> Which implies that "$browser_path" must be the actual
> executable. In which case, I would think that:
>
> "$browser_path" "$@" &
>
> would be the right thing. And indeed, that is what the firefox arm of
> the case statement does. But chrome, konqueror, and others use eval.
So here is my attempt at a fix for kfmclient.
For what it's worth I've included a testcase that detects my problem. I'm not
sure if the testcase is really worth it because the test library suppresses X
applications and even if it didn't the testcase is fairly trivial and might
just annoy people by opening web-browsers (and it snaps up the last t99xx
prefix).
git-web--browse.sh | 4 ++--
t/t9901-git-web--browse.sh | 43 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 45 insertions(+), 2 deletions(-)
create mode 100755 t/t9901-git-web--browse.sh
diff --git a/git-web--browse.sh b/git-web--browse.sh
index e9de241..1164a22 100755
--- a/git-web--browse.sh
+++ b/git-web--browse.sh
@@ -164,10 +164,10 @@ konqueror)
# It's simpler to use kfmclient to open a new tab in konqueror.
browser_path="$(echo "$browser_path" | sed -e 's/konqueror$/kfmclient/')"
type "$browser_path" > /dev/null 2>&1 || die "No '$browser_path' found."
- eval "$browser_path" newTab "$@"
+ "$browser_path" newTab "$@" &
;;
kfmclient)
- eval "$browser_path" newTab "$@"
+ "$browser_path" newTab "$@" &
;;
*)
"$browser_path" "$@" &
diff --git a/t/t9901-git-web--browse.sh b/t/t9901-git-web--browse.sh
new file mode 100755
index 0000000..7ed38a0
--- /dev/null
+++ b/t/t9901-git-web--browse.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+#
+# Copyright (c) 2011 Chris Packham
+#
+
+test_description='git web--browse basic tests
+
+This test checks that git web--browse can handle various valid URLs with
+the supported browsers that are installed on the host system.'
+
+. ./test-lib.sh
+
+test -x /usr/bin/firefox && test_set_prereq FIREFOX
+test -x /usr/bin/konqueror && test_set_prereq KONQUEROR
+test -x /usr/bin/google-chrome && test_set_prereq CHROME
+test -x /usr/bin/opera && test_set_prereq OPERA
+
+test_expect_success \
+ 'accepts a URL with an ampersand in it (default)' '
+ git web--browse http://example.com/foo\&bar/
+'
+
+test_expect_success FIREFOX \
+ 'accepts a URL with an ampersand in it (firefox)' '
+ git web--browse --browser=firefox http://example.com/foo\&bar/
+'
+
+test_expect_success KONQUEROR \
+ 'accepts a URL with an ampersand in it (konqueror)' '
+ git web--browse --browser=konqueror http://example.com/foo\&bar/
+'
+
+test_expect_success OPERA \
+ 'accepts a URL with an ampersand in it (opera)' '
+ git web--browse --browser=opera http://example.com/foo\&bar/
+'
+
+test_expect_success CHROME \
+ 'accepts a URL with an ampersand in it (chrome)' '
+ git web--browse --browser=google-chrome http://example.com/foo\&bar/
+'
+
+test_done
--
1.7.7.rc1.3.g5593.dirty
^ permalink raw reply related
* Re: Most elegant way to reference to SVN from GIT?
From: Jeff King @ 2011-09-18 3:43 UTC (permalink / raw)
To: Manuel Reimer; +Cc: git
In-Reply-To: <j53c2h$gff$2@dough.gmane.org>
On Sun, Sep 18, 2011 at 01:51:44AM +0200, Manuel Reimer wrote:
> Now someone offered to contribute a translation. This translation is
> hosted on a SVN server.
>
> How can I get his work into my GIT tree and how can I keep things updated?
You can pull their commits into git using git-svn, and then merge them.
Try:
# make a new repo side by side with your project that contains
# their translation
cd /path/to/your-project/..
git svn clone https://host/their-subversion-repo their-translation
# inspect with "git log", "ls", etc to make sure it looks sane
# if so, then merge it in
cd ../your-project
git pull ../their-translation git-svn
# months later, get an update
cd their-translation
git svn fetch
cd ../your-project
git pull ../their-translation git-svn
I think you could also do it all in one repo by using "git svn init" and
"git svn fetch", but you'd have to check "git help svn" for the exact
syntax.
-Peff
^ permalink raw reply
* Re: Merging back from master but keeping a subtree
From: Jeff King @ 2011-09-18 3:37 UTC (permalink / raw)
To: git
In-Reply-To: <87y5xn8v6z.fsf@dod.no>
On Sat, Sep 17, 2011 at 09:49:40AM +0200, Steinar Bang wrote:
> I have a long lived branch that changes a directory and its
> subdirectory, ie.
> top/middle/mydirectory
>
> Now I want to merge in an updated remoterepo/master and keep everything
> from that master, except for mydirectory and its subdirectory, where I
> would like to keep everything from my branch.
Git should generally do that automatically, unless both sides are
changing mydirectory. In which case it will produce conflicts.
Are you sure you really want to just throw out what the other side did
in mydirectory?
> I tried a regular merge, and used
> git checkout --ours
> git add
> and
> git checkout --theirs
> git add
> as appropriate on all conflicts.
>
> But the result didn't build, and the build errors don't make much sense,
> so I think they are caused by "successful" merges giving bad results.
If git was able to auto-merge some files, then they will not be marked
as conflicts in the index. And "git checkout --ours" is about looking in
the index for conflicted entries, and then selecting one side.
I think what you want instead is to do is (assuming you really want to
throw out their side):
1. Start a merge between them and us:
git merge --no-commit remoterepo/master
2. Throw out whatever the merge came up with and make it look like
their tree:
git checkout remoterepo/master -- top
3. Now overwrite their version of mydirectory with what was in your
branch:
git checkout HEAD -- top/middle/mydirectory
4. Commit the resulting tree:
git commit
-Peff
^ permalink raw reply
* Re: git web--browse error handling URL with & in it (Was Re: [RFC/PATCH] Configurable hyperlinking in gitk)
From: Jeff King @ 2011-09-18 3:29 UTC (permalink / raw)
To: Chris Packham; +Cc: Christian Couder, Jeff Epler, git
In-Reply-To: <4E753C04.1070202@gmail.com>
On Sun, Sep 18, 2011 at 12:32:04PM +1200, Chris Packham wrote:
> Update: it's the call to eval that causes the problem
>
> eval kfmclient newTab https://internalhost/code\&stuff/bugs.php?id=foo
> [1] 14728
> bash: stuff/bugs.php?id=foo: No such file or directory
Hmm. The offending lines look like:
eval "$browser_path" "$@" &
Normally in git we treat user-configured commands as shell snippets,
meaning the user is responsible for any quoting. But in this script, we
seem to run:
type "$browser_path"
several times. Which implies that "$browser_path" must be the actual
executable. In which case, I would think that:
"$browser_path" "$@" &
would be the right thing. And indeed, that is what the firefox arm of
the case statement does. But chrome, konqueror, and others use eval.
Unrelated, but it also looks like $browser_path is used unquoted in the
firefox case (see inside the vers=$(...)).
-Peff
^ permalink raw reply
* [PATCH 5/5] git-p4: keyword flattening fixes
From: Pete Wyckoff @ 2011-09-18 1:33 UTC (permalink / raw)
To: git; +Cc: Vitor Antunes, Luke Diamand, Chris Li, Junio C Hamano
In-Reply-To: <20110918012634.GA4578@arf.padd.com>
Join the text before looking for keywords. There is nothing to
prevent the p4 output marshaller from splitting in the middle of a
keyword, although it has never been known to happen.
Also remove the (?i) regexp modifier; perforce keywords are
documented as case-sensitive.
Remove the "\n" end-character match. I don't know why that is
in there, and every keyword in a fairly large production p4 repository
always ends with a $.
Signed-off-by: Pete Wyckoff <pw@padd.com>
---
contrib/fast-import/git-p4 | 8 ++++++--
1 files changed, 6 insertions(+), 2 deletions(-)
diff --git a/contrib/fast-import/git-p4 b/contrib/fast-import/git-p4
index eee288d..782b891 100755
--- a/contrib/fast-import/git-p4
+++ b/contrib/fast-import/git-p4
@@ -1285,9 +1285,13 @@ class P4Sync(Command, P4UserMap):
# even though in theory somebody may want that.
if type_base in ("text", "unicode", "binary"):
if "ko" in type_mods:
- contents = map(lambda text: re.sub(r'(?i)\$(Id|Header):[^$]*\$', r'$\1$', text), contents)
+ text = ''.join(contents)
+ text = re.sub(r'\$(Id|Header):[^$]*\$', r'$\1$', text)
+ contents = [ text ]
elif "k" in type_mods:
- contents = map(lambda text: re.sub(r'\$(Id|Header|Author|Date|DateTime|Change|File|Revision):[^$\n]*\$', r'$\1$', text), contents)
+ text = ''.join(contents)
+ text = re.sub(r'\$(Id|Header|Author|Date|DateTime|Change|File|Revision):[^$]*\$', r'$\1$', text)
+ contents = [ text ]
self.gitStream.write("M %s inline %s\n" % (git_mode, relPath))
--
1.7.6.3
^ permalink raw reply related
* [PATCH 4/5] git-p4: stop ignoring apple filetype
From: Pete Wyckoff @ 2011-09-18 1:32 UTC (permalink / raw)
To: git; +Cc: Vitor Antunes, Luke Diamand, Chris Li, Junio C Hamano
In-Reply-To: <20110918012634.GA4578@arf.padd.com>
Currently "apple" filetype is ignored explicitly, and the file is
not even included in the git repository. This seems wrong.
Remove this, letting it be treated like a "binary" filetype.
Signed-off-by: Pete Wyckoff <pw@padd.com>
---
contrib/fast-import/git-p4 | 5 -----
1 files changed, 0 insertions(+), 5 deletions(-)
diff --git a/contrib/fast-import/git-p4 b/contrib/fast-import/git-p4
index 931cf5f..eee288d 100755
--- a/contrib/fast-import/git-p4
+++ b/contrib/fast-import/git-p4
@@ -1247,11 +1247,6 @@ class P4Sync(Command, P4UserMap):
# - helper for streamP4Files
def streamOneP4File(self, file, contents):
- if file["type"] == "apple":
- print "\nfile %s is a strange apple file that forks. Ignoring" % \
- file['depotFile']
- return
-
relPath = self.stripRepoPath(file['depotFile'], self.branchPrefixes)
relPath = self.wildcard_decode(relPath)
if verbose:
--
1.7.6.3
^ permalink raw reply related
* [PATCH 3/5] git-p4: recognize all p4 filetypes
From: Pete Wyckoff @ 2011-09-18 1:31 UTC (permalink / raw)
To: git; +Cc: Vitor Antunes, Luke Diamand, Chris Li, Junio C Hamano
In-Reply-To: <20110918012634.GA4578@arf.padd.com>
The previous code was approximate in the filetypes it recognized.
Put in the canonical list and be more careful about matching
elements of the file type.
This might change behavior in some cases, hopefully for the
better. Windows newline mangling will now happen on all
text files. Previously some like "text+ko" were oddly exempt.
Files with multiple combinations of modifiers, like "text+klx",
are now recognized for keyword expansion. I expect these to be
seen only rarely.
Signed-off-by: Pete Wyckoff <pw@padd.com>
---
contrib/fast-import/git-p4 | 71 ++++++++++++++++++++++++++++++++------------
1 files changed, 52 insertions(+), 19 deletions(-)
diff --git a/contrib/fast-import/git-p4 b/contrib/fast-import/git-p4
index e69caf3..931cf5f 100755
--- a/contrib/fast-import/git-p4
+++ b/contrib/fast-import/git-p4
@@ -118,13 +118,41 @@ def p4_system(cmd):
real_cmd = p4_build_cmd(cmd)
return system(real_cmd)
-def isP4Exec(kind):
- """Determine if a Perforce 'kind' should have execute permission
+#
+# Canonicalize the p4 type and return a tuple of the
+# base type, plus any modifiers. See "p4 help filetypes"
+# for a list and explanation.
+#
+def split_p4_type(p4type):
+
+ p4_filetypes_historical = {
+ "ctempobj": "binary+Sw",
+ "ctext": "text+C",
+ "cxtext": "text+Cx",
+ "ktext": "text+k",
+ "kxtext": "text+kx",
+ "ltext": "text+F",
+ "tempobj": "binary+FSw",
+ "ubinary": "binary+F",
+ "uresource": "resource+F",
+ "uxbinary": "binary+Fx",
+ "xbinary": "binary+x",
+ "xltext": "text+Fx",
+ "xtempobj": "binary+Swx",
+ "xtext": "text+x",
+ "xunicode": "unicode+x",
+ "xutf16": "utf16+x",
+ }
+ if p4type in p4_filetypes_historical:
+ p4type = p4_filetypes_historical[p4type]
+ mods = ""
+ s = p4type.split("+")
+ base = s[0]
+ mods = ""
+ if len(s) > 1:
+ mods = s[1]
+ return (base, mods)
- 'p4 help filetypes' gives a list of the types. If it starts with 'x',
- or x follows one of a few letters. Otherwise, if there is an 'x' after
- a plus sign, it is also executable"""
- return (re.search(r"(^[cku]?x)|\+.*x", kind) != None)
def setP4ExecBit(file, mode):
# Reopens an already open file and changes the execute bit to match
@@ -1229,16 +1257,18 @@ class P4Sync(Command, P4UserMap):
if verbose:
sys.stderr.write("%s\n" % relPath)
- mode = "644"
- if isP4Exec(file["type"]):
- mode = "755"
- elif file["type"] == "symlink":
- mode = "120000"
- # p4 print on a symlink contains "target\n", so strip it off
+ (type_base, type_mods) = split_p4_type(file["type"])
+
+ git_mode = "100644"
+ if "x" in type_mods:
+ git_mode = "100755"
+ if type_base == "symlink":
+ git_mode = "120000"
+ # p4 print on a symlink contains "target\n"; remove the newline
data = ''.join(contents)
contents = [data[:-1]]
- if file['type'].startswith("utf16"):
+ if type_base == "utf16":
# p4 delivers different text in the python output to -G
# than it does when using "print -o", or normal p4 client
# operations. utf16 is converted to ascii or utf8, perhaps.
@@ -1247,7 +1277,9 @@ class P4Sync(Command, P4UserMap):
text = p4_read_pipe('print -q -o - "%s"' % file['depotFile'])
contents = [ text ]
- if self.isWindows and file["type"].endswith("text"):
+ # Perhaps windows wants unicode, utf16 newlines translated too;
+ # but this is not doing it.
+ if self.isWindows and type_base == "text":
mangled = []
for data in contents:
data = data.replace("\r\n", "\n")
@@ -1256,12 +1288,13 @@ class P4Sync(Command, P4UserMap):
# Note that we do not try to de-mangle keywords on utf16 files,
# even though in theory somebody may want that.
- if file['type'] in ('text+ko', 'unicode+ko', 'binary+ko'):
- contents = map(lambda text: re.sub(r'(?i)\$(Id|Header):[^$]*\$',r'$\1$', text), contents)
- elif file['type'] in ('text+k', 'ktext', 'kxtext', 'unicode+k', 'binary+k'):
- contents = map(lambda text: re.sub(r'\$(Id|Header|Author|Date|DateTime|Change|File|Revision):[^$\n]*\$',r'$\1$', text), contents)
+ if type_base in ("text", "unicode", "binary"):
+ if "ko" in type_mods:
+ contents = map(lambda text: re.sub(r'(?i)\$(Id|Header):[^$]*\$', r'$\1$', text), contents)
+ elif "k" in type_mods:
+ contents = map(lambda text: re.sub(r'\$(Id|Header|Author|Date|DateTime|Change|File|Revision):[^$\n]*\$', r'$\1$', text), contents)
- self.gitStream.write("M %s inline %s\n" % (mode, relPath))
+ self.gitStream.write("M %s inline %s\n" % (git_mode, relPath))
# total length...
length = 0
--
1.7.6.3
^ permalink raw reply related
* [PATCH 2/5] git-p4: handle utf16 filetype properly
From: Pete Wyckoff @ 2011-09-18 1:29 UTC (permalink / raw)
To: git; +Cc: Vitor Antunes, Luke Diamand, Chris Li, Junio C Hamano
In-Reply-To: <20110918012634.GA4578@arf.padd.com>
One of the filetypes that p4 supports is utf16. Its behavior is
odd in this case. The data delivered through "p4 -G print" is
not encoded in utf16, although "p4 print -o" will produce the
proper utf16-encoded file.
When dealing with this filetype, discard the data from -G, and
intstead read the contents directly.
An alternate approach would be to try to encode the data in
python. That worked for true utf16 files, but for other files
marked as utf16, p4 delivers mangled text in no recognizable encoding.
Add a test case to check utf16 handling, and +k and +ko handling.
Reported-by: Chris Li <git@chrisli.org>
Signed-off-by: Pete Wyckoff <pw@padd.com>
---
contrib/fast-import/git-p4 | 11 +++++
t/t9802-git-p4-filetype.sh | 107 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 118 insertions(+), 0 deletions(-)
create mode 100755 t/t9802-git-p4-filetype.sh
diff --git a/contrib/fast-import/git-p4 b/contrib/fast-import/git-p4
index 2f7b270..e69caf3 100755
--- a/contrib/fast-import/git-p4
+++ b/contrib/fast-import/git-p4
@@ -1238,6 +1238,15 @@ class P4Sync(Command, P4UserMap):
data = ''.join(contents)
contents = [data[:-1]]
+ if file['type'].startswith("utf16"):
+ # p4 delivers different text in the python output to -G
+ # than it does when using "print -o", or normal p4 client
+ # operations. utf16 is converted to ascii or utf8, perhaps.
+ # But ascii text saved as -t utf16 is completely mangled.
+ # Invoke print -o to get the real contents.
+ text = p4_read_pipe('print -q -o - "%s"' % file['depotFile'])
+ contents = [ text ]
+
if self.isWindows and file["type"].endswith("text"):
mangled = []
for data in contents:
@@ -1245,6 +1254,8 @@ class P4Sync(Command, P4UserMap):
mangled.append(data)
contents = mangled
+ # Note that we do not try to de-mangle keywords on utf16 files,
+ # even though in theory somebody may want that.
if file['type'] in ('text+ko', 'unicode+ko', 'binary+ko'):
contents = map(lambda text: re.sub(r'(?i)\$(Id|Header):[^$]*\$',r'$\1$', text), contents)
elif file['type'] in ('text+k', 'ktext', 'kxtext', 'unicode+k', 'binary+k'):
diff --git a/t/t9802-git-p4-filetype.sh b/t/t9802-git-p4-filetype.sh
new file mode 100755
index 0000000..f112eaa
--- /dev/null
+++ b/t/t9802-git-p4-filetype.sh
@@ -0,0 +1,107 @@
+#!/bin/sh
+
+test_description='git-p4 p4 filetype tests'
+
+. ./lib-git-p4.sh
+
+test_expect_success 'start p4d' '
+ kill_p4d || : &&
+ start_p4d &&
+ cd "$TRASH_DIRECTORY"
+'
+
+test_expect_success 'utf-16 file create' '
+ cd "$cli" &&
+
+ # p4 saves this verbatim
+ echo -e "three\nline\ntext" > f-ascii &&
+ p4 add -t text f-ascii &&
+
+ # p4 adds \377\376 header
+ cp f-ascii f-ascii-as-utf16 &&
+ p4 add -t utf16 f-ascii-as-utf16 &&
+
+ # p4 saves this exactly as iconv produced it
+ echo -e "three\nline\ntext" | iconv -f ascii -t utf-16 > f-utf16 &&
+ p4 add -t utf16 f-utf16 &&
+
+ # this also is unchanged
+ cp f-utf16 f-utf16-as-text &&
+ p4 add -t text f-utf16-as-text &&
+
+ p4 submit -d "f files" &&
+
+ # force update of client files
+ p4 sync -f &&
+ cd "$TRASH_DIRECTORY"
+'
+
+test_expect_success 'utf-16 file test' '
+ test_when_finished cleanup_git &&
+ "$GITP4" clone --dest="$git" //depot@all &&
+ cd "$git" &&
+
+ cmp "$cli/f-ascii" f-ascii &&
+ cmp "$cli/f-ascii-as-utf16" f-ascii-as-utf16 &&
+ cmp "$cli/f-utf16" f-utf16 &&
+ cmp "$cli/f-utf16-as-text" f-utf16-as-text
+'
+
+test_expect_success 'keyword file create' '
+ cd "$cli" &&
+
+ echo -e "id\n\$Id\$\n\$Author\$\ntext" > k-text-k &&
+ p4 add -t text+k k-text-k &&
+
+ cp k-text-k k-text-ko &&
+ p4 add -t text+ko k-text-ko &&
+
+ cat k-text-k | iconv -f ascii -t utf-16 > k-utf16-k &&
+ p4 add -t utf16+k k-utf16-k &&
+
+ cp k-utf16-k k-utf16-ko &&
+ p4 add -t utf16+ko k-utf16-ko &&
+
+ p4 submit -d "k files" &&
+ p4 sync -f &&
+ cd "$TRASH_DIRECTORY"
+'
+
+ko_smush() {
+ cat >smush.py <<-EOF &&
+ import re, sys
+ sys.stdout.write(re.sub(r'(?i)\\\$(Id|Header):[^$]*\\\$', r'$\1$', sys.stdin.read()))
+ EOF
+ python smush.py < "$1"
+}
+
+k_smush() {
+ cat >smush.py <<-EOF &&
+ import re, sys
+ sys.stdout.write(re.sub(r'(?i)\\\$(Id|Header|Author|Date|DateTime|Change|File|Revision):[^$]*\\\$', r'$\1$', sys.stdin.read()))
+ EOF
+ python smush.py < "$1"
+}
+
+test_expect_success 'keyword file test' '
+ test_when_finished cleanup_git &&
+ "$GITP4" clone --dest="$git" //depot@all &&
+ cd "$git" &&
+
+ # text, ensure unexpanded
+ k_smush "$cli/k-text-k" > cli-k-text-k-smush &&
+ cmp cli-k-text-k-smush k-text-k &&
+ ko_smush "$cli/k-text-ko" > cli-k-text-ko-smush &&
+ cmp cli-k-text-ko-smush k-text-ko &&
+
+ # utf16, even though p4 expands keywords, git-p4 does not
+ # try to undo that
+ cmp "$cli/k-utf16-k" k-utf16-k &&
+ cmp "$cli/k-utf16-ko" k-utf16-ko
+'
+
+test_expect_success 'kill p4d' '
+ kill_p4d
+'
+
+test_done
--
1.7.6.3
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox