* [PATCH da/difftool-mergtool-refactor] Makefile: fix permissions of mergetools/ checked out with permissive umask
From: Jonathan Nieder @ 2011-10-09 9:17 UTC (permalink / raw)
To: David Aguilar
Cc: Junio C Hamano, git, Tanguy Ortolo, Charles Bailey,
Sebastian Schuberth
In-Reply-To: <1313652227-48545-4-git-send-email-davvid@gmail.com>
Ever since mergetool--lib was split into multiple files in
v1.7.7-rc0~3^2~1 (2011-08-18), the Makefile takes care to reset umask
and use tar --no-owner when installing merge tool definitions to
$(gitexecdir)/mergetools/. Unfortunately it does not take into
account the possibility that the permission bits of the files being
copied might already be wrong.
Rather than fixing the "tar" incantation and making it even more
complicated, let's just use the "install" utility. This only means
losing the ability to install executables and subdirectories of
mergetools/, which wasn't used.
Noticed by installing from a copy of git checked out with umask 002.
Compare v1.6.0.3~81^2 (Fix permission bits on sources checked out with
an overtight umask, 2008-08-21).
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
David Aguilar wrote:
> +++ b/Makefile
[...]
> @@ -2266,6 +2274,9 @@ install: all
> $(INSTALL) -m 644 $(SCRIPT_LIB) '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'
> $(INSTALL) $(install_bindir_programs) '$(DESTDIR_SQ)$(bindir_SQ)'
> $(MAKE) -C templates DESTDIR='$(DESTDIR_SQ)' install
> + $(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(mergetools_instdir_SQ)'
> + (cd mergetools && $(TAR) cf - .) | \
> + (cd '$(DESTDIR_SQ)$(mergetools_instdir_SQ)' && umask 022 && $(TAR) xof -)
Last month I tried this out and found that, strangely, my files under
/usr/lib/git-core/mergetools/ had the g+w bit set. Leading me to
wonder: does the "umask" here have any effect at all?
Since debian/rules install is run as root, the default is for tar to
act as thought --preserve-permissions were passed, so the umask when
running "tar" is not relevant. Luckily I think "tar" is overkill
here, anyway.
Thoughts? Sorry to have taken so long to send this out.
Makefile | 3 +--
1 files changed, 1 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
index 1e91b19c..e27755e7 100644
--- a/Makefile
+++ b/Makefile
@@ -2275,8 +2275,7 @@ install: all
$(INSTALL) $(install_bindir_programs) '$(DESTDIR_SQ)$(bindir_SQ)'
$(MAKE) -C templates DESTDIR='$(DESTDIR_SQ)' install
$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(mergetools_instdir_SQ)'
- (cd mergetools && $(TAR) cf - .) | \
- (cd '$(DESTDIR_SQ)$(mergetools_instdir_SQ)' && umask 022 && $(TAR) xof -)
+ $(INSTALL) -m 644 mergetools/* '$(DESTDIR_SQ)$(mergetools_instdir_SQ)'
ifndef NO_PERL
$(MAKE) -C perl prefix='$(prefix_SQ)' DESTDIR='$(DESTDIR_SQ)' install
$(MAKE) -C gitweb install
--
1.7.7.rc1
^ permalink raw reply related
* Re: [PATCH 6/6] revert: Simplify passing command-line arguments around
From: Jonathan Nieder @ 2011-10-09 8:53 UTC (permalink / raw)
To: Ramkumar Ramachandra
Cc: Tay Ray Chuan, Git List, Junio C Hamano, Jeff King,
Daniel Barkalow, Christian Couder
In-Reply-To: <CALkWK0kA=zhpsmYhjMwv11xyHNhA0Ps=BjUDao0+HFLMKnADUg@mail.gmail.com>
Ramkumar Ramachandra wrote:
> Actually, I intended to put it in the commit message. Seems to be
> idiomatic: grep the log for "\[jc:" etc.
More important than the idiom is the intent. Presumably that intent
was something like "I wrote the commit message, so if it makes you
scratch your head, blame me, not Jonathan; and I made some other
(minor) improvements, so consider blaming me even if it's the
functional part that makes you scratch your head."
Sorry I haven't had a chance to look over the patch yet. Is it
supposed to introduce a behavior change, does it prepare for some
future change, or is it just a cleanup?
^ permalink raw reply
* Re: [PATCH 6/6] revert: Simplify passing command-line arguments around
From: Ramkumar Ramachandra @ 2011-10-09 8:28 UTC (permalink / raw)
To: Tay Ray Chuan
Cc: Git List, Jonathan Nieder, Junio C Hamano, Jeff King,
Daniel Barkalow, Christian Couder
In-Reply-To: <CALUzUxo=xN735+=Yz9eS_VSW3fpiTeng9s-66qM0Jno40-DPXQ@mail.gmail.com>
Hi Tay,
Tay Ray Chuan writes:
> On Sun, Oct 9, 2011 at 1:36 AM, Ramkumar Ramachandra <artagnon@gmail.com> wrote:
>> [rr: minor improvements, commit message]
>
> This "[]" could go below, under the 3-dash (but before the stat):
Actually, I intended to put it in the commit message. Seems to be
idiomatic: grep the log for "\[jc:" etc.
Thanks.
-- Ram
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: Matthieu Moy @ 2011-10-09 8:12 UTC (permalink / raw)
To: Martin Fick; +Cc: SZEDER Gábor, Daly Gutierrez, git
In-Reply-To: <ab706826-75df-4410-941e-6b40ec92713c@email.android.com>
Martin Fick <mfick@codeaurora.org> writes:
>>git reflog to the rescue. For your example above it will output
>>something like this:
>>
>>deadbeef HEAD@{0}: checkout: moving from
>>92aa5381b9f7229523dba42aa94735c30f173451 to New_Branch
>> 92aa5381 HEAD@{1}: commit: Committing this in the Detached Head
>>3a5bb38a HEAD@{2}: checkout: moving from master to
>>3a5bb38a83c00f7acab573f0ec836577143200aa
>> deafbabe HEAD@{3}: ...
>> ...
>>
>>There you see the first line of the commit message from your "lost"
>>commit, and you can do
>>
>> git checkout -b lost_detached_head 92aa5381
>>
>>and you get a branch pointing to that commit you made while on
>>detached head, and you can work with it as usual.
>
> While rflog is cool, I can't help but think that git could be even more helpful for these scenarios.
Git has been showing a big scary warning when entering detached HEAD,
and now has another helpful one when leaving a commit orphan:
$ git checkout HEAD^
Note: checking out 'HEAD^'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b new_branch_name
HEAD is now at adcbd2f... foo
$ date > foo.txt; git add foo.txt; git commit -am "commited on detached HEAD"
[detached HEAD 9e9c4ef] commited on detached HEAD
1 files changed, 1 insertions(+), 1 deletions(-)
$ git checkout master
Warning: you are leaving 1 commit behind, not connected to
any of your branches:
9e9c4ef commited on detached HEAD
If you want to keep them by creating a new branch, this may be a good time
to do so with:
git branch new_branch_name 9e9c4efeca049ca559541595c9ca4a3380dee523
Switched to branch 'master'
(since 8e2dc6ac06ae90, Junio C Hamano, Fri Feb 18 16:04:47 2011, commit:
give final warning when reattaching HEAD to leave commits behind)
I think these warnings are (scary and big) enough.
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: Ronan Keryell @ 2011-10-09 7:46 UTC (permalink / raw)
To: Nguyen Thai Ngoc Duy; +Cc: git
In-Reply-To: <CACsJy8CsMCju7joj2B2xbBSTF1vHjyuFeSZyPhTJisO2sU-Fqg@mail.gmail.com>
>>>>> On Sun, 9 Oct 2011 16:52:11 +1100, Nguyen Thai Ngoc Duy <pclouds@gmail.com> said:
Nguyen> On Sun, Oct 9, 2011 at 9:00 AM, Martin Fick <mfick@codeaurora.org> wrote:
>> While rflog is cool, I can't help but think that git could be
>> even more helpful for these scenarios.
>> First, maybe git could create refs for these automatically,
>> perhaps with a name like orphans/1? Maybe these refs would only
>> be visible via git branch --orphans.
Nguyen> If I remember correctly, we don't have private ref
Nguyen> namespace, any refs created automatically this way could be
Nguyen> pushed out by accident.
A way to avoid this could be to deal with this like git-stash works,
instead of relying on the branch machinery.
But anyway, I think there is a trade-off between keeping some references
to some hypothetical future use and preventing the garbage collector to
reclaim useless objects...
--
Ronan KERYELL |\/ Phone: +1 408 844 HPC0
HPC Project, Inc. |/) Cell: +33 613 143 766
5201 Great America Parkway #3241 K Ronan.Keryell@hpc-project.com
Santa Clara, CA 95054 |\ skype:keryell
USA | \ http://hpc-project.com
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: Nguyen Thai Ngoc Duy @ 2011-10-09 5:52 UTC (permalink / raw)
To: Martin Fick; +Cc: SZEDER Gábor, Daly Gutierrez, git
In-Reply-To: <ab706826-75df-4410-941e-6b40ec92713c@email.android.com>
On Sun, Oct 9, 2011 at 9:00 AM, Martin Fick <mfick@codeaurora.org> wrote:
>>git reflog to the rescue. For your example above it will output
>>something like this:
>>
>>deadbeef HEAD@{0}: checkout: moving from
>>92aa5381b9f7229523dba42aa94735c30f173451 to New_Branch
>> 92aa5381 HEAD@{1}: commit: Committing this in the Detached Head
>>3a5bb38a HEAD@{2}: checkout: moving from master to
>>3a5bb38a83c00f7acab573f0ec836577143200aa
>> deafbabe HEAD@{3}: ...
>> ...
>>
>>There you see the first line of the commit message from your "lost"
>>commit, and you can do
>>
>> git checkout -b lost_detached_head 92aa5381
>>
>>and you get a branch pointing to that commit you made while on
>>detached head, and you can work with it as usual.
>
> While rflog is cool, I can't help but think that git could be even more helpful for these scenarios.
>
> First, maybe git could create refs for these automatically, perhaps with a name like orphans/1? Maybe these refs would only be visible via git branch --orphans.
If I remember correctly, we don't have private ref namespace, any refs
created automatically this way could be pushed out by accident.
--
Duy
^ permalink raw reply
* Re: Git is not scalable with too many refs/*
From: Michael Haggerty @ 2011-10-09 5:43 UTC (permalink / raw)
To: Martin Fick
Cc: git, Christian Couder, Thomas Rast, René Scharfe,
Julian Phillips
In-Reply-To: <201110081459.52174.mfick@codeaurora.org>
[-- Attachment #1: Type: text/plain, Size: 2441 bytes --]
On 10/08/2011 10:59 PM, Martin Fick wrote:
> [...]
> So, with this in mind, I have discovered, that the fetch
> performance degradation by invalidating the caches in
> write_ref_sha1() is actually due to the packed-refs being
> reloaded and resorted again on each ref insertion (not the
> loose refs)!!!
Good point.
> I think that all of this might explain why no matter how
> good Michael's intentions are with his patch series, his
> series isn't likely to fix this problem
I never claimed that my patch fixes all use cases, or cures cancer
either :-) One step at a time.
> unless he does not
> invalidate the packed-refs after each insertion. I tried
> preventing this invalidation in his series to prove this,
> but unfortunately, it appears that in his series it is no
> longer possible to only invalidate just the packed-refs? :(
> Michael, I hope I am completely wrong about that...
Yes, you are completely wrong. I just implemented more selective cache
invalidation on top of the patch series.
I think your suggestion is safe because only non-symbolic references can
be stored in the packed refs; therefore the modification of a loose ref
can never affect the value of a packed ref. Of course a loose ref can
*hide* the value of a packed ref, but in such cases the packed ref is
never read anyway. And the *deletion* of a loose ref can expose a
previously-hidden packed ref, but this case is handled by delete_ref(),
which explicitly invalidates the packed-ref cache.
While I was at it, I also:
* In delete_ref(), only invalidate the packed reference cache if the
reference that is being deleted actually *is* among the packed references.
* Changed the code to stop invalidating the ref caches for submodules.
In the code paths where the cache invalidation was being done, only
main-module references were being changed. However, I'm not familiar
enough with submodules to know if/when submodule references *can* be
changed. It could be that the submodule reference caches have to be
invalidated under some circumstances; the current code might be buggy in
this area.
The changes are pushed to github. They don't make any significant
difference to my "refperf" results (attached), so perhaps a new
benchmark should be added. But I'm curious to see how they affect your
timings.
Michael
--
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/
[-- Attachment #2: refperf-summary.out --]
[-- Type: text/plain, Size: 5251 bytes --]
=================================== ======= ======= ======= ======= ======= ======= ======= ======= ======= =======
Test name [0] [1] [2] [3] [4] [5] [6] [7] [8] [9]
=================================== ======= ======= ======= ======= ======= ======= ======= ======= ======= =======
branch-loose-cold 3.19 3.15 3.10 3.19 3.25 0.70 0.61 0.74 0.66 0.56
branch-loose-warm 0.19 0.19 0.20 0.19 0.19 0.00 0.00 0.00 0.00 0.00
for-each-ref-loose-cold 3.73 3.45 3.55 3.39 3.44 3.40 3.50 3.52 3.70 3.51
for-each-ref-loose-warm 0.44 0.44 0.44 0.43 0.43 0.43 0.43 0.43 0.43 0.43
checkout-loose-cold 3.35 3.23 3.23 3.15 3.29 0.65 0.71 0.76 0.66 0.69
checkout-loose-warm 0.19 0.19 0.20 0.18 0.19 0.01 0.01 0.01 0.01 0.00
checkout-orphan-loose 0.19 0.19 0.19 0.18 0.19 0.00 0.00 0.00 0.00 0.00
checkout-from-detached-loose-cold 7.80 4.17 4.17 4.05 4.09 4.07 4.26 4.23 4.18 4.08
checkout-from-detached-loose-warm 1.01 1.01 1.02 1.02 1.04 1.03 1.04 1.04 1.02 1.04
branch-contains-loose-cold 35.76 35.80 36.15 36.67 35.13 36.29 36.37 36.03 36.70 36.01
branch-contains-loose-warm 33.01 33.62 33.52 33.51 32.41 33.51 33.71 32.10 33.70 31.99
pack-refs-loose 4.19 4.20 4.25 4.21 4.20 4.21 4.20 4.19 4.24 4.21
branch-packed-cold 0.79 0.62 0.60 0.66 0.65 0.58 0.68 0.72 0.60 0.61
branch-packed-warm 0.02 0.02 0.02 0.02 0.02 0.02 0.02 0.02 0.02 0.02
for-each-ref-packed-cold 0.96 0.97 0.97 0.93 0.89 0.92 0.98 0.96 0.92 0.96
for-each-ref-packed-warm 0.26 0.26 0.26 0.26 0.26 0.26 0.26 0.27 0.27 0.27
checkout-packed-cold 16.14 16.16 16.74 2.04 2.03 2.09 2.06 2.13 2.03 2.00
checkout-packed-warm 0.17 0.17 0.18 0.19 0.18 0.17 0.27 0.18 0.19 0.18
checkout-orphan-packed 0.02 0.01 0.02 0.02 0.02 0.02 0.02 0.02 0.02 0.02
checkout-from-detached-packed-cold 16.24 15.96 16.80 1.99 2.06 2.01 2.08 2.10 1.97 1.96
checkout-from-detached-packed-warm 15.04 14.96 15.76 0.77 0.81 0.79 0.83 0.80 0.79 0.80
branch-contains-packed-cold 36.18 36.98 36.92 35.19 34.97 35.09 33.34 33.87 34.27 34.51
branch-contains-packed-warm 35.27 35.12 36.20 33.52 32.76 33.49 33.65 32.96 33.68 32.34
clone-loose-cold 9.09 9.22 9.15 9.10 9.19 9.03 9.09 9.25 8.96 9.03
clone-loose-warm 5.57 5.85 5.65 5.55 5.61 5.64 5.65 5.61 5.74 5.59
fetch-nothing-loose 1.43 1.43 1.44 1.44 1.45 1.45 1.46 1.44 1.44 1.44
pack-refs 0.08 0.08 0.08 0.08 0.09 0.08 0.09 0.08 0.08 0.08
fetch-nothing-packed 1.44 1.43 1.44 1.44 1.44 1.44 1.44 1.44 1.44 1.44
clone-packed-cold 1.35 1.26 1.30 1.32 1.28 1.35 1.38 1.35 1.29 1.21
clone-packed-warm 0.36 0.35 0.35 0.36 0.36 0.36 0.35 0.36 0.37 0.35
fetch-everything-cold 30.29 30.01 29.79 29.04 29.84 29.25 29.30 29.26 29.76 29.30
fetch-everything-warm 26.20 26.04 26.40 25.60 26.22 25.83 25.82 25.85 26.68 25.73
=================================== ======= ======= ======= ======= ======= ======= ======= ======= ======= =======
[0] f696543 (tag: v1.7.6) Git 1.7.6
[1] 703f05a (tag: v1.7.7) Git 1.7.7
[2] 27897d2 (origin/master) Merge remote-tracking branch 'gitster/mh/iterate-refs'
[3] 558b49c is_refname_available(): reimplement using do_for_each_ref_in_list()
[4] 1658397 Store references hierarchically
[5] 5f5a126 get_ref_dir(): add a recursive option
[6] a306af1 get_ref_dir(): read one whole directory before descending into subdirs
[7] fd53cf7 add_ref(): change to take a (struct ref_entry *) as second argument
[8] 9944c7f (origin/testing) read_packed_refs(): keep track of the directory being worked in
[9] cb75c57 (origin/ok, origin/hierarchical-refs, origin/HEAD) refs.c: call clear_cached_ref_cache() from repack_without_ref()
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: Martin Fick @ 2011-10-09 5:39 UTC (permalink / raw)
To: Joel C. Salomon, git; +Cc: szeder, daly.gutierrez
In-Reply-To: <4E9115B0.3030701@gmail.com>
"Joel C. Salomon" <joelcsalomon@gmail.com> wrote:
>On 10/08/2011 06:00 PM, Martin Fick wrote:
>>> git reflog to the rescue.
><snip>
>>> There you see the first line of the commit message from your "lost"
>>> commit, and you can do
>>>
>>> git checkout -b lost_detached_head 92aa5381
>>>
>>> and you get a branch pointing to that commit you made while on
>>> detached head, and you can work with it as usual.
>>
>> While rflog is cool, I can't help but think that git could be even
>more helpful for these scenarios.
>>
>> First, maybe git could create refs for these automatically, perhaps
>with a name like orphans/1? Maybe these refs would only be visible via
>git branch --orphans.
>
>Creating these "orphan" refs would require the equivalent of (part of)
>git-fsck; I can't imagine that could be imposed without significant
>overhead on too many operations. I think you'd be better off wrapping
>git-fsck in a script that can create these branches.
Is there another way to create orphan refs than by doing a checkout and leaving the orphan behind? I guess a rebase or other branch rewinding operations, but shouldn't it already know on those that that if it alters anything, it will create an orphan? Git already checks for to see if it is leaving orphan refs behind on a checkout, why not just give the orphan a branch name at those points (not sure what to do if the check is bypassed with -q, just punt I guess)?
-Martin
Employee of Qualcomm Innovation Center,Inc. which is a member of Code Aurora Forum
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: Joel C. Salomon @ 2011-10-09 3:32 UTC (permalink / raw)
To: git; +Cc: mfick, szeder, daly.gutierrez
In-Reply-To: <ab706826-75df-4410-941e-6b40ec92713c@email.android.com>
On 10/08/2011 06:00 PM, Martin Fick wrote:
>> git reflog to the rescue.
<snip>
>> There you see the first line of the commit message from your "lost"
>> commit, and you can do
>>
>> git checkout -b lost_detached_head 92aa5381
>>
>> and you get a branch pointing to that commit you made while on
>> detached head, and you can work with it as usual.
>
> While rflog is cool, I can't help but think that git could be even more helpful for these scenarios.
>
> First, maybe git could create refs for these automatically, perhaps with a name like orphans/1? Maybe these refs would only be visible via git branch --orphans.
Creating these "orphan" refs would require the equivalent of (part of)
git-fsck; I can't imagine that could be imposed without significant
overhead on too many operations. I think you'd be better off wrapping
git-fsck in a script that can create these branches.
--Joel
^ permalink raw reply
* Re: A Basic Git Question About File Tracking [ANSWERED]
From: Jon Forrest @ 2011-10-09 2:42 UTC (permalink / raw)
To: Jakub Narebski; +Cc: git
In-Reply-To: <m3ipnz0xri.fsf@localhost.localdomain>
On 10/8/2011 6:17 PM, Jakub Narebski wrote:
> You seem to be under [false] impression that git commit is about
> _changes_ / _changeset_.
This is correct. The Pro Git book says:
"You stage these modified files and then commit
all your staged changes"
Plus, even "git status" tells me
$ git status
# On branch master
# Changes to be committed:
But I see my error. Below is what I hope is a clear
explanation of what I didn't understand. It presumes
that the reader understands the git objects model.
Please let me know if anything is incorrect.
----------
When you "git add" a file two things happen:
1) The file is copied to the git objects tree.
This location where the file is copied depends
on the hash of the file's content.
2) An entry for the file is added to the git index.
This entry includes the same hash that was mentioned
in #1.
A tracked file has an entry in the git index file.
A copy of the file also exists in the objects tree.
When you run 'git status', git computes the hash of
every file in your working directory and looks
up each file in the index. If the file isn't found
then the file is shown as untracked.
When you do a commit, the hash values of everything
in the index are copied into a tree object. The hash
value of the tree object is then placed in a commit object.
No copies of tracked files in the working directory are
made at commit time. This is because the files were already
copied into the objects tree when 'git add' was run.
This is one reason why git commits are so fast.
-----
How's that?
Thanks to everyone for sticking with me on this.
Jon
^ permalink raw reply
* Re: [PATCH 6/6] revert: Simplify passing command-line arguments around
From: Tay Ray Chuan @ 2011-10-09 2:14 UTC (permalink / raw)
To: Ramkumar Ramachandra
Cc: Git List, Jonathan Nieder, Junio C Hamano, Jeff King,
Daniel Barkalow, Christian Couder
In-Reply-To: <1318095407-26429-7-git-send-email-artagnon@gmail.com>
On Sun, Oct 9, 2011 at 1:36 AM, Ramkumar Ramachandra <artagnon@gmail.com> wrote:
> [snip]
> [rr: minor improvements, commit message]
This "[]" could go below, under the 3-dash (but before the stat):
> [snip]
> ---
> builtin/revert.c | 53 +++++++++++++++++++++++++++++------------------------
> 1 files changed, 29 insertions(+), 24 deletions(-)
--
Cheers,
Ray Chuan
^ permalink raw reply
* Re: A Basic Git Question About File Tracking
From: Jakub Narebski @ 2011-10-09 1:17 UTC (permalink / raw)
To: Jon Forrest; +Cc: git, Jonathan Nieder
In-Reply-To: <4E90E60C.7060105@gmail.com>
Jon Forrest <nobozo@gmail.com> writes:
> On 10/3/2011 6:22 PM, Jonathan Nieder wrote:
>
> [I'm just getting back to this question. I had accidentally
> sent this follow up directly to Jonathan but I want to
> continue this on the email list.]
>
> > Yes, "x" is tracked. Moreover, "x" is in the index. You can
> > list files in the index with the "git ls-files -s" command.
>
> This spoils my understanding of what the index
> is. I had been thinking that after you add files
> to the index, and then commit, the index is then
> empty. In other words, whatever's in the index
> gets committed, and then the index is cleaned.
>
> On the other hand, if the definition of a tracked
> file is a file that's in the index, then this definitely
> clears up my understanding of tracked files.
>
> If every file that's 'git add'ed stays in the
> index, how does git know which files to commit?
>
> I can't prove it but I suspect that many git beginners
> also are confused by this.
You seem to be under [false] impression that git commit is about
_changes_ / _changeset_.
It is not true. What is stored in git commit object is (pointer to)
_snapshot_ of a state of a project at given time. This means that
"git commit" creates a tree object out of state of the index, and
creates commit object that points to said newly created tree, and has
version you started work from as its parent. It is commit remember
the previous version that allows to turn commit into changeset.
Hopefully that would clear up your confusion.
--
Jakub Narębski
^ permalink raw reply
* Re: A Basic Git Question About File Tracking
From: Jon Forrest @ 2011-10-09 0:08 UTC (permalink / raw)
To: git
In-Reply-To: <20111004012244.GB13836@elie>
On 10/3/2011 6:22 PM, Jonathan Nieder wrote:
[I'm just getting back to this question. I had accidentally
sent this follow up directly to Jonathan but I want to
continue this on the email list.]
> Yes, "x" is tracked. Moreover, "x" is in the index. You can
> list files in the index with the "git ls-files -s" command.
This spoils my understanding of what the index
is. I had been thinking that after you add files
to the index, and then commit, the index is then
empty. In other words, whatever's in the index
gets committed, and then the index is cleaned.
On the other hand, if the definition of a tracked
file is a file that's in the index, then this definitely
clears up my understanding of tracked files.
If every file that's 'git add'ed stays in the
index, how does git know which files to commit?
I can't prove it but I suspect that many git beginners
also are confused by this.
Thanks for your replies.
Jon Forrest
^ permalink raw reply
* Re: [RFC/PATCH] Add multiple workdir support to branch/checkout
From: Julián Landerreche @ 2011-10-08 22:55 UTC (permalink / raw)
To: git
In-Reply-To: <1317786204-57335-1-git-send-email-jaysoffian@gmail.com>
Jay wrote:
> I guess it depends what you mostly use your workdirs for. For me, it's
> to have different branches checked out, not to have the same branch
> checked out in multiple locations.
I find those both use cases for workdirs to fit perfectly in my usual workflow
(web development).
- Different branches checked out
I've a cloned repo of a CMS and I use git-new-workdir to checkout different
branches and tags, so to have available a few workdirs of recent versions, which
I "attach" by symlinks to my web development projects.
- Same branch checked out in multiple locations
This use case just came up recently, when I find out that I prefer to have two
websites "attached" (via symlink) to two different workdirs of the same branch.
I could have "attached" both websites to the same workdir, but my idea of having
the websites "attached" to different workdirs was to be able to do some
development (i.e: to commit stuff) on one workdir, while keeping the other one
"fixed" at some particular commit.
Juno wrote:
> Careful. Git has survived without your patch series till now, as people
> learned to be careful when they use separate workdirs and avoid certain
> things, to the point that they are not necessarily aware that they are
> avoiding them (one good practice is to keep the HEADs of non-primary
> workdirs detached).
Jay wrote:
> Also, while I might recommend new-workdir to my coworkers with the
> advice "don't checkout the same branch in multiple workdirs", never in
> a million years would I say "use new-workdir, but make sure to only
> use a detached HEAD in the workdirs." The latter would make their
> actual HEADs explode.
After reading this, I noticed that using git-new-workdir with detached HEAD in
each workdir could fit my workflow very well. In some cases (the ones mentioned
above), I find that I may not need to have a workdir for a branch (where I won't
do work, so won't be committing there), but rather to have that workdir "fixed"
at a particular commit.
That being said, I also see that I would find useful to be able to
update/advance this workdir (in a detached HEAD state, that is, "fixed" at an
specific commit) to a newer commit or to a particular branch.
Bottom line: making git-new-workdir a more reliable & friendly tool that could
fit in the workflows of both advanced and non-advanced users.
-----
Quick note about me: I am an "advanced n00b" on git usage (using it since one
year ago), and a general non-advanced user (of git and git-new-workdir). In
other words, a git user that could easily shoot itself in the foot.
Arrived here while looking for some info about git-new-workdir, and if it was a
Bad Idea to have different workdirs of the same branch (ie. checkout the same
branch on different folders), as the idea of recklessly committing on different
workdirs for the same branch sounded like a recipe for disasters to me.
I find it git-new-workdir a really useful tool in my workflow, and prefer it
over having many clones of the same repo, which will imply having to do
configuration for remotes and push/pull operations, which are also mind-boggling
tasks for non-advanced users.
-----
Thanks for reading.
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: Martin Fick @ 2011-10-08 22:00 UTC (permalink / raw)
To: SZEDER Gábor, Daly Gutierrez; +Cc: git
In-Reply-To: <20111008213741.GA24409@goldbirke>
>git reflog to the rescue. For your example above it will output
>something like this:
>
>deadbeef HEAD@{0}: checkout: moving from
>92aa5381b9f7229523dba42aa94735c30f173451 to New_Branch
> 92aa5381 HEAD@{1}: commit: Committing this in the Detached Head
>3a5bb38a HEAD@{2}: checkout: moving from master to
>3a5bb38a83c00f7acab573f0ec836577143200aa
> deafbabe HEAD@{3}: ...
> ...
>
>There you see the first line of the commit message from your "lost"
>commit, and you can do
>
> git checkout -b lost_detached_head 92aa5381
>
>and you get a branch pointing to that commit you made while on
>detached head, and you can work with it as usual.
While rflog is cool, I can't help but think that git could be even more helpful for these scenarios.
First, maybe git could create refs for these automatically, perhaps with a name like orphans/1? Maybe these refs would only be visible via git branch --orphans.
-Martin
Employee of Qualcomm Innovation Center,Inc. which is a member of Code Aurora Forum
^ permalink raw reply
* Re: Recovering Committed Changes in a Detached Head?
From: SZEDER Gábor @ 2011-10-08 21:37 UTC (permalink / raw)
To: Daly Gutierrez; +Cc: git
In-Reply-To: <1318107488.5865.46.camel@R0b0ty>
Hi,
On Sat, Oct 08, 2011 at 04:58:07PM -0400, Daly Gutierrez wrote:
> Is this possible after changing from the Detached Head branch to an
> existing branch? How about if I don't remember the commit SHA1 ID?
>
> What I did, to the best of my knowledge:
> 1) Checked out a previous version:
> > git checkout 3a5bb38a83c00f7acab573f0ec836577143200aa
>
> 2) Modified file and committed the changes in the detached branch.
> > git log
> commit 92aa5381b9f7229523dba42aa94735c30f173451
> Author: Daly Gutierrez <Daly.Gutierrez@gmail.com>
> Date: Sat Oct 8 16:20:11 2011 -0400
>
> Committing this in the Detached Head
>
> 3) For curiosity,
> > git branch
> * (no branch)
> New_Branch
> Second_New_Branch
> master
>
> 4) Changed to 'New_Branch' branch... I no longer see the detached
> branch...
> > git branch
> * New_Branch
> Second_New_Branch
> master
>
> 5) Want to access the file with the changes I made in the Detached
> branch, but don't know how... PLEASE HELP?
git reflog to the rescue. For your example above it will output
something like this:
deadbeef HEAD@{0}: checkout: moving from 92aa5381b9f7229523dba42aa94735c30f173451 to New_Branch
92aa5381 HEAD@{1}: commit: Committing this in the Detached Head
3a5bb38a HEAD@{2}: checkout: moving from master to 3a5bb38a83c00f7acab573f0ec836577143200aa
deafbabe HEAD@{3}: ...
...
There you see the first line of the commit message from your "lost"
commit, and you can do
git checkout -b lost_detached_head 92aa5381
and you get a branch pointing to that commit you made while on
detached head, and you can work with it as usual.
Best,
Gábor
^ permalink raw reply
* Re: Git is not scalable with too many refs/*
From: Martin Fick @ 2011-10-08 20:59 UTC (permalink / raw)
To: git
Cc: Christian Couder, Thomas Rast, René Scharfe, Julian Phillips,
Michael Haggerty
In-Reply-To: <201109301606.31748.mfick@codeaurora.org>
On Friday, September 30, 2011 04:06:31 pm Martin Fick wrote:
> On Friday, September 30, 2011 03:02:30 pm Martin Fick
wrote:
> > On Friday, September 30, 2011 10:41:13 am Martin Fick
>
> wrote:
> > Since a full sync is now done to about 5mins, I broke
> > down the output a bit. It appears that the longest
> > part (2:45m) is now the time spent scrolling though
> > each
> >
> > change still. Each one of these takes about 2ms:
> > * [new branch] refs/changes/99/71199/1 ->
> >
> > refs/changes/99/71199/1
> >
> > Seems fast, but at about 80K... So, are there any
> > obvious N loops over the refs happening inside each of
> > of the [new branch] iterations?
>
> OK, I narrowed it down I believe. If I comment out the
> invalidate_cached_refs() line in write_ref_sha1(), it
> speeds through this section.
>
> I guess this makes sense, we invalidate the cache and
> have to rebuild it after every new ref is added?
> Perhaps a simple fix would be to move the invalidation
> right after all the refs are updated? Maybe
> write_ref_sha1 could take in a flag to tell it to not
> invalidate the cache so that during iterative updates it
> could be disabled and then run manually after the
> update?
OK, this thing has been bugging me...
I found some more surprising results, I hope you can follow
because there are corner cases here which have surprising
impacts.
** Important fact:
** ---------------
** When I clone my repo, it has about 4K tags which
** come in packed to the clone.
**
This fact has a heavy impact on how I test things. If I
choose to delete these packed-refs from the cloned repo and
then do a fetch of the changes, all of the tags are also
fetched along with these changes. This means that if I want
to test the impact of having packed-refs vs no packed refs,
on my change fetches, I need to first delete the packed-refs
file, and second fetch all the tags again, so that when I
fetch the changes, the repo only actually fetches changes,
not all the tags!
So, with this in mind, I have discovered, that the fetch
performance degradation by invalidating the caches in
write_ref_sha1() is actually due to the packed-refs being
reloaded and resorted again on each ref insertion (not the
loose refs)!!!
Remember the important fact above? Yeah, those silly 4K
refs (not a huge number, not 61K!) take a while to reread
from the file and sort. When this is done for 61K changes,
it adds a lot of time to a fetch. The sad part is that, of
course, the packed-refs don't really need to be invalidated
since we never add new refs as packed refs during a fetch
(but apparently we do during a clone)! Also noteworthy is
that invalidating the loose refs, does not cause a big
delay.
Some data:
1) A fetch of the changes in my series with all good
external patches applied takes about 7:30min.
2) A fetch of the changes with #1 invalidate_cache_refs()
commented out in write_ref_sha1() takes about 1:50min.
3) A fetch of the changes with #1 with
invalidate_cache_refs() in write_ref_sha1() replaced with a
call to my custom invalidate_loose_cache_refs() takes about
1:50min.
4) A fetch with #1 on a repo with packed-refs deleted after
the clone, takes about ~5min.
** This is a strange regression which threw me off. In this
case, all the tags are refetched in addition to the changes,
this seems to cause some weird interaction that makes things
take longer than they should (#5 + #6 = 2:10m << #4 5min).
5) A fetch with #1 on a repo with packed-refs deleted after
the clone, and then a fetch done to get all the tags (see
#6), takes only 1:30m!!!!
6) A fetch to get all the **TAGS** with packed-refs deleted
after the clone, takes about 40s.
---Additional side data/tests:
7) A fetch of the changes with #1 and a special flag causing
the packed-refs to be read from the file, but not parsed or
sorted, takes 2:34min. So just the repeated reads add at
least 40s.
8) A fetch of the changes with #1 and a special flag causing
the packed-refs to be read from the file, parsed, but NOT
sorted, takes 3:40min. So the parsing appears to take an
additional minute at least.
I think that all of this might explain why no matter how
good Michael's intentions are with his patch series, his
series isn't likely to fix this problem unless he does not
invalidate the packed-refs after each insertion. I tried
preventing this invalidation in his series to prove this,
but unfortunately, it appears that in his series it is no
longer possible to only invalidate just the packed-refs? :(
Michael, I hope I am completely wrong about that...
Are there any good consistency reasons to invalidate the
packed refs in write_ref_sha1()? If not, would you accept a
patch to simply skip this invalidation (to only invalidate
the loose refs)?
Thanks,
-Martin
--
Employee of Qualcomm Innovation Center, Inc. which is a
member of Code Aurora Forum
^ permalink raw reply
* Recovering Committed Changes in a Detached Head?
From: Daly Gutierrez @ 2011-10-08 20:58 UTC (permalink / raw)
To: git
Is this possible after changing from the Detached Head branch to an
existing branch? How about if I don't remember the commit SHA1 ID?
What I did, to the best of my knowledge:
1) Checked out a previous version:
> git checkout 3a5bb38a83c00f7acab573f0ec836577143200aa
2) Modified file and committed the changes in the detached branch.
> git log
commit 92aa5381b9f7229523dba42aa94735c30f173451
Author: Daly Gutierrez <Daly.Gutierrez@gmail.com>
Date: Sat Oct 8 16:20:11 2011 -0400
Committing this in the Detached Head
3) For curiosity,
> git branch
* (no branch)
New_Branch
Second_New_Branch
master
4) Changed to 'New_Branch' branch... I no longer see the detached
branch...
> git branch
* New_Branch
Second_New_Branch
master
5) Want to access the file with the changes I made in the Detached
branch, but don't know how... PLEASE HELP?
^ permalink raw reply
* [PATCH v3] Teach merge the '[-e|--edit]' option
From: Jay Soffian @ 2011-10-08 18:39 UTC (permalink / raw)
To: git; +Cc: Jay Soffian, Junio C Hamano, Todd A. Jacobs
Implemented internally instead of as "git merge --no-commit && git commit"
so that "merge --edit" is otherwise consistent (hooks, etc) with "merge".
Note: the edit message does not include the status information that one
gets with "commit --status" and it is cleaned up after editing like one
gets with "commit --cleanup=default". A later patch could add the status
information if desired.
Note: previously we were not calling stripspace() after running the
prepare-commit-msg hook. Now we are, stripping comments and
leading/trailing whitespace lines if --edit is given, otherwise only
stripping leading/trailing whitespace lines if not given --edit.
Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
---
I probably can't spend more time on this patch any time soon. Hopefully
this iteration is close enough. If not, maybe Todd can help.
Documentation/merge-options.txt | 6 ++
builtin/merge.c | 109 +++++++++++++++++++++++++--------------
t/t7600-merge.sh | 15 +++++
3 files changed, 91 insertions(+), 39 deletions(-)
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index b613d4ed08..6bd0b041c3 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -7,6 +7,12 @@ With --no-commit perform the merge but pretend the merge
failed and do not autocommit, to give the user a chance to
inspect and further tweak the merge result before committing.
+--edit::
+-e::
++
+ Invoke editor before committing successful merge to further
+ edit the default merge message.
+
--ff::
--no-ff::
Do not generate a merge commit if the merge resolved as
diff --git a/builtin/merge.c b/builtin/merge.c
index ee56974371..fcb7a60bfa 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -46,7 +46,7 @@ static const char * const builtin_merge_usage[] = {
static int show_diffstat = 1, shortlog_len, squash;
static int option_commit = 1, allow_fast_forward = 1;
-static int fast_forward_only;
+static int fast_forward_only, option_edit;
static int allow_trivial = 1, have_message;
static struct strbuf merge_msg;
static struct commit_list *remoteheads;
@@ -190,6 +190,8 @@ static struct option builtin_merge_options[] = {
"create a single commit instead of doing a merge"),
OPT_BOOLEAN(0, "commit", &option_commit,
"perform a commit if the merge succeeds (default)"),
+ OPT_BOOLEAN('e', "edit", &option_edit,
+ "edit message before committing"),
OPT_BOOLEAN(0, "ff", &allow_fast_forward,
"allow fast-forward (default)"),
OPT_BOOLEAN(0, "ff-only", &fast_forward_only,
@@ -842,30 +844,54 @@ static void add_strategies(const char *string, unsigned attr)
}
-static void write_merge_msg(void)
+static void write_merge_msg(struct strbuf *msg)
{
int fd = open(git_path("MERGE_MSG"), O_WRONLY | O_CREAT, 0666);
if (fd < 0)
die_errno(_("Could not open '%s' for writing"),
git_path("MERGE_MSG"));
- if (write_in_full(fd, merge_msg.buf, merge_msg.len) != merge_msg.len)
+ if (write_in_full(fd, msg->buf, msg->len) != msg->len)
die_errno(_("Could not write to '%s'"), git_path("MERGE_MSG"));
close(fd);
}
-static void read_merge_msg(void)
+static void read_merge_msg(struct strbuf *msg)
{
- strbuf_reset(&merge_msg);
- if (strbuf_read_file(&merge_msg, git_path("MERGE_MSG"), 0) < 0)
+ strbuf_reset(msg);
+ if (strbuf_read_file(msg, git_path("MERGE_MSG"), 0) < 0)
die_errno(_("Could not read from '%s'"), git_path("MERGE_MSG"));
}
-static void run_prepare_commit_msg(void)
+static void write_merge_state(void);
+static void abort_commit(const char *err_msg)
{
- write_merge_msg();
+ if (err_msg)
+ error("%s", err_msg);
+ fprintf(stderr,
+ _("Not committing merge; use 'git commit' to complete the merge.\n"));
+ write_merge_state();
+ exit(1);
+}
+
+static void prepare_to_commit(void)
+{
+ struct strbuf msg = STRBUF_INIT;
+ strbuf_addbuf(&msg, &merge_msg);
+ strbuf_addch(&msg, '\n');
+ write_merge_msg(&msg);
run_hook(get_index_file(), "prepare-commit-msg",
git_path("MERGE_MSG"), "merge", NULL, NULL);
- read_merge_msg();
+ if (option_edit) {
+ if (launch_editor(git_path("MERGE_MSG"), NULL, NULL))
+ abort_commit(NULL);
+ }
+ read_merge_msg(&msg);
+ stripspace(&msg, option_edit);
+ if (!msg.len)
+ abort_commit(_("Empty commit message."));
+ strbuf_release(&merge_msg);
+ strbuf_addbuf(&merge_msg, &msg);
+ strbuf_release(&msg);
}
static int merge_trivial(void)
@@ -879,7 +905,7 @@ static int merge_trivial(void)
parent->next = xmalloc(sizeof(*parent->next));
parent->next->item = remoteheads->item;
parent->next->next = NULL;
- run_prepare_commit_msg();
+ prepare_to_commit();
commit_tree(merge_msg.buf, result_tree, parent, result_commit, NULL);
finish(result_commit, "In-index merge");
drop_save();
@@ -907,9 +933,9 @@ static int finish_automerge(struct commit_list *common,
for (j = remoteheads; j; j = j->next)
pptr = &commit_list_insert(j->item, pptr)->next;
}
- free_commit_list(remoteheads);
strbuf_addch(&merge_msg, '\n');
- run_prepare_commit_msg();
+ prepare_to_commit();
+ free_commit_list(remoteheads);
commit_tree(merge_msg.buf, result_tree, parents, result_commit, NULL);
strbuf_addf(&buf, "Merge made by the '%s' strategy.", wt_strategy);
finish(result_commit, buf.buf);
@@ -1015,6 +1041,36 @@ static int setup_with_upstream(const char ***argv)
return i;
}
+static void write_merge_state(void)
+{
+ int fd;
+ struct commit_list *j;
+ struct strbuf buf = STRBUF_INIT;
+
+ for (j = remoteheads; j; j = j->next)
+ strbuf_addf(&buf, "%s\n",
+ sha1_to_hex(j->item->object.sha1));
+ fd = open(git_path("MERGE_HEAD"), O_WRONLY | O_CREAT, 0666);
+ if (fd < 0)
+ die_errno(_("Could not open '%s' for writing"),
+ git_path("MERGE_HEAD"));
+ if (write_in_full(fd, buf.buf, buf.len) != buf.len)
+ die_errno(_("Could not write to '%s'"), git_path("MERGE_HEAD"));
+ close(fd);
+ strbuf_addch(&merge_msg, '\n');
+ write_merge_msg(&merge_msg);
+ fd = open(git_path("MERGE_MODE"), O_WRONLY | O_CREAT | O_TRUNC, 0666);
+ if (fd < 0)
+ die_errno(_("Could not open '%s' for writing"),
+ git_path("MERGE_MODE"));
+ strbuf_reset(&buf);
+ if (!allow_fast_forward)
+ strbuf_addf(&buf, "no-ff");
+ if (write_in_full(fd, buf.buf, buf.len) != buf.len)
+ die_errno(_("Could not write to '%s'"), git_path("MERGE_MODE"));
+ close(fd);
+}
+
int cmd_merge(int argc, const char **argv, const char *prefix)
{
unsigned char result_tree[20];
@@ -1418,33 +1474,8 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
if (squash)
finish(NULL, NULL);
- else {
- int fd;
- struct commit_list *j;
-
- for (j = remoteheads; j; j = j->next)
- strbuf_addf(&buf, "%s\n",
- sha1_to_hex(j->item->object.sha1));
- fd = open(git_path("MERGE_HEAD"), O_WRONLY | O_CREAT, 0666);
- if (fd < 0)
- die_errno(_("Could not open '%s' for writing"),
- git_path("MERGE_HEAD"));
- if (write_in_full(fd, buf.buf, buf.len) != buf.len)
- die_errno(_("Could not write to '%s'"), git_path("MERGE_HEAD"));
- close(fd);
- strbuf_addch(&merge_msg, '\n');
- write_merge_msg();
- fd = open(git_path("MERGE_MODE"), O_WRONLY | O_CREAT | O_TRUNC, 0666);
- if (fd < 0)
- die_errno(_("Could not open '%s' for writing"),
- git_path("MERGE_MODE"));
- strbuf_reset(&buf);
- if (!allow_fast_forward)
- strbuf_addf(&buf, "no-ff");
- if (write_in_full(fd, buf.buf, buf.len) != buf.len)
- die_errno(_("Could not write to '%s'"), git_path("MERGE_MODE"));
- close(fd);
- }
+ else
+ write_merge_state();
if (merge_was_ok) {
fprintf(stderr, _("Automatic merge went well; "
diff --git a/t/t7600-merge.sh b/t/t7600-merge.sh
index 87aac835a1..8c6b811718 100755
--- a/t/t7600-merge.sh
+++ b/t/t7600-merge.sh
@@ -643,4 +643,19 @@ test_expect_success 'amending no-ff merge commit' '
test_debug 'git log --graph --decorate --oneline --all'
+cat >editor <<\EOF
+#!/bin/sh
+# strip comments and blank lines from end of message
+sed -e '/^#/d' < "$1" | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}' > expected
+EOF
+chmod 755 editor
+
+test_expect_success 'merge --no-ff --edit' '
+ git reset --hard c0 &&
+ EDITOR=./editor git merge --no-ff --edit c1 &&
+ verify_parents $c0 $c1 &&
+ git cat-file commit HEAD | sed "1,/^$/d" > actual &&
+ test_cmp actual expected
+'
+
test_done
--
1.7.7.147.g4f6dc9
^ permalink raw reply related
* [PATCHv5 6/6] gitweb: Add gitweb manpages to 'gitweb' package in git.spec
From: Jakub Narebski @ 2011-10-08 18:32 UTC (permalink / raw)
To: git, Drew Northup; +Cc: Jonathan Nieder, Jakub Narebski
In-Reply-To: <1318098723-12813-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>
---
This version adds gitweb's README and INSTALL to 'gitweb' subpackage.
git.spec.in | 7 +++++++
1 files changed, 7 insertions(+), 0 deletions(-)
diff --git a/git.spec.in b/git.spec.in
index 91c8462..c562c62 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 gitweb/README gitweb/INSTALL 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
* [PATCHv5 5/6] Documentation: Add gitweb config variables to git-config(1)
From: Jakub Narebski @ 2011-10-08 18:32 UTC (permalink / raw)
To: git, Drew Northup; +Cc: Jonathan Nieder, Jakub Narebski
In-Reply-To: <1318098723-12813-1-git-send-email-jnareb@gmail.com>
Add a list of gitweb config variables to git-config(1) manpage, just
linking to gitweb(1) or gitweb.conf(5).
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
This patch is new in this series.
BTW. there was a patch from Thomas Rast, which you can see e.g. in
't/doc-config-extraction' branch in my repositories:
http://repo.or.cz/w/git/jnareb-git.git
https://github.com/jnareb/git
which made git generate such thing automatically.
Documentation/config.txt | 17 +++++++++++++++++
1 files changed, 17 insertions(+), 0 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 03296b7..b30c7e6 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1071,6 +1071,23 @@ All gitcvs variables except for 'gitcvs.usecrlfattr' and
is one of "ext" and "pserver") to make them apply only for the given
access method.
+gitweb.category::
+gitweb.description::
+gitweb.owner::
+gitweb.url::
+ See linkgit:gitweb[1] for description.
+
+gitweb.avatar::
+gitweb.blame::
+gitweb.grep::
+gitweb.highlight::
+gitweb.patches::
+gitweb.pickaxe::
+gitweb.remote_heads::
+gitweb.showsizes::
+gitweb.snapshot::
+ See linkgit:gitweb.conf[5] for description.
+
grep.lineNumber::
If set to true, enable '-n' option by default.
--
1.7.6
^ permalink raw reply related
* [PATCHv5 4/6] Documentation: Link to gitweb(1) and gitweb.conf(5) in other manpages
From: Jakub Narebski @ 2011-10-08 18:32 UTC (permalink / raw)
To: git, Drew Northup; +Cc: Jonathan Nieder, Jakub Narebski
In-Reply-To: <1318098723-12813-1-git-send-email-jnareb@gmail.com>
Add link to gitweb(1) in "SEE ALSO" section of git-instaweb(1) manpage,
and "Ancillary Commands" section of git(1) manpage (the latter by the
way of command-list.txt file).
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
This is new in this series.
BTW. why command-list.txt uses not only spaces to separate and align,
but also tabs, and mixtures of tabs and spaces???
Documentation/git-instaweb.txt | 4 ++++
command-list.txt | 1 +
2 files changed, 5 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt
index ea95c90..f3eef51 100644
--- a/Documentation/git-instaweb.txt
+++ b/Documentation/git-instaweb.txt
@@ -84,6 +84,10 @@ If the configuration variable 'instaweb.browser' is not set,
'web.browser' will be used instead if it is defined. See
linkgit:git-web{litdd}browse[1] for more information about this.
+SEE ALSO
+--------
+linkgit:gitweb[1]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/command-list.txt b/command-list.txt
index 95bf18c..a36ee9b 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -130,5 +130,6 @@ git-upload-pack synchelpers
git-var plumbinginterrogators
git-verify-pack plumbinginterrogators
git-verify-tag ancillaryinterrogators
+gitweb ancillaryinterrogators
git-whatchanged ancillaryinterrogators
git-write-tree plumbingmanipulators
--
1.7.6
^ permalink raw reply related
* [PATCHv5/RFC 3/6] gitweb: Add manpage for gitweb
From: Jakub Narebski @ 2011-10-08 18:32 UTC (permalink / raw)
To: git, Drew Northup; +Cc: Jonathan Nieder, Jakub Narebski
In-Reply-To: <1318098723-12813-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>
---
Does anyone know a well structured _manpage_ for a web application
(other than SVN::Web) to borrow ideas from for this one?
Jonathan, could you please review also this patch, if you have some
free time? Thanks in advance.
Documentation/Makefile | 2 +-
Documentation/gitweb.conf.txt | 9 +
Documentation/gitweb.txt | 703 +++++++++++++++++++++++++++++++++++++++++
gitweb/INSTALL | 94 +-----
gitweb/README | 278 ++---------------
5 files changed, 741 insertions(+), 345 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 31eb527..eaff477 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
----------
@@ -109,6 +113,8 @@ Location of repositories
The configuration variables described below control how gitweb finds
git repositories, and how repositories are displayed and accessed.
+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
@@ -193,6 +199,9 @@ our $export_ok = "git-daemon-export-ok";
----------------------------------------------------------------------------
+
If not set (default), it means that this feature is disabled.
++
+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..2acdb3b
--- /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 explicitly
+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 accessible
+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).
+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).
- 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
+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
* [PATCHv5 2/6] gitweb: Add manpage for gitweb configuration files
From: Jakub Narebski @ 2011-10-08 18:31 UTC (permalink / raw)
To: git, Drew Northup; +Cc: Jonathan Nieder, Jakub Narebski
In-Reply-To: <1318098723-12813-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>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
---
I refer to my reply to Jonathan Nieder in
Re: [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)
http://thread.gmane.org/gmane.comp.version-control.git/181605/focus=181896
for description of changes (and to parent post).
Thanks a lot to Jonathan Nieder.
Documentation/Makefile | 2 +-
Documentation/gitweb.conf.txt | 866 +++++++++++++++++++++++++++++++++++++++++
gitweb/README | 133 +-------
3 files changed, 868 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..31eb527
--- /dev/null
+++ b/Documentation/gitweb.conf.txt
@@ -0,0 +1,866 @@
+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 the '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 reads 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 fallback system-wide configuration file (defaults to '/etc/gitweb.conf').
+
+Values obtained in later configuration files override values obtained earlier
+in the above sequence.
+
+Locations of the common system-wide configuration file, the fallback
+system-wide configuration file and the per-instance configuration file
+are defined at compile time using build-time Makefile configuration
+variables, respectively `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM`
+and `GITWEB_CONFIG`.
+
+You can also override locations of gitweb configuration files during
+runtime by setting the following environment variables:
+`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`
+to a non-empty value.
+
+
+The syntax of the configuration files is that of Perl, since these files are
+handled by sourcing them as fragments of Perl code (the language that
+gitweb itself is written in). Variables are typically set using the
+`our` qualifier (as in "`our $variable = <value>;`") to avoid syntax
+errors if a new version of gitweb no longer uses a variable and therefore
+stops declaring it.
+
+You can include other configuration file using read_config_file()
+subroutine. For example, one might want to put gitweb configuration
+related to access control for viewing repositories via Gitolite (one
+of git repository management tools) in a separate file, e.g. in
+'/etc/gitweb-gitolite.conf'. To include it, put
+
+--------------------------------------------------
+read_config_file("/etc/gitweb-gitolite.conf");
+--------------------------------------------------
+
+somewhere in gitweb configuration file used, e.g. in per-installation
+gitweb configuration file. Note that read_config_file() checks itself
+that the file it reads exists, and does nothing if it is not found.
+It also handles errors in included file.
+
+
+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 configuration variables have their default values (embedded in the CGI
+script) set during building gitweb -- if that is the case, this fact is put
+in their description. See gitweb's 'INSTALL' file for instructions on building
+and installing gitweb.
+
+
+Location of repositories
+~~~~~~~~~~~~~~~~~~~~~~~~
+The configuration variables described below control how gitweb finds
+git repositories, and how repositories are displayed and accessed.
+
+$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
+------------------------------------------------
++
+and its path_info based equivalent
++
+------------------------------------------------
+http://git.example.com/gitweb.cgi/foo/bar.git
+------------------------------------------------
++
+will map to the path '/srv/git/foo/bar.git' on the filesystem.
+
+$projects_list::
+ Name of a plain text file listing projects, or a 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.
+
+$project_maxdepth::
+ If `$projects_list` variable is unset, gitweb will recursively
+ scan filesystem for git repositories. The `$project_maxdepth`
+ is used to limit traversing depth, relative to `$projectroot`
+ (starting point); it means that directories which are further
+ from `$projectroot` than `$project_maxdepth` will be skipped.
++
+It is purely performance optimization, originally intended for MacOS X,
+where recursive directory traversal is slow. Gitweb follows symbolic
+links, but it detects cycles, ignoring any duplicate files and directories.
++
+The default value of this variable is determined by the build-time
+configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to
+2007.
+
+$export_ok::
+ Show repository only if this file exists (in repository). Only
+ effective if this variable evaluates to true. Can be set when
+ building gitweb by setting `GITWEB_EXPORT_OK`. This path is
+ relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok',
+ unless started with `--export-all`. [No default / Not set
+ (this feature is turned off)]
+
+$export_auth_hook::
+ Function used to determine which repositories should be shown.
+ This subroutine should take one parameter, the full path to
+ a project, and if it returns true, that project will be included
+ in the projects list and can be accessed through gitweb as long
+ as it fulfills the other requirements described by $export_ok,
+ $projects_list, and $projects_maxdepth. 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";
+----------------------------------------------------------------------------
++
+If not set (default), it means that this feature is disabled.
+
+$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 (you can access
+ repositories hidden from projects list page)]
+
+
+Finding files
+~~~~~~~~~~~~~
+The following configuration variables tell gitweb where to find files.
+The values of these variables are paths on the filesystem.
+
+$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 installed
+ from a binary package, you should usually set this to "/usr/bin/git".
+ This can just be "git" if your web server has a sensible PATH; from
+ security point of view it is better to use absolute path to git binary.
+ If you have multiple git versions installed it can be used to choose
+ which one to use. Must be (correctly) set for gitweb to be able to
+ work.
+
+$mimetypes_file::
+ File to use for (filename extension based) guessing of MIME types before
+ trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken
+ as relative to the current git repository, not to CGI script. If unset,
+ only '/etc/mime.types' is used (if present on filesystem). If no mimetypes
+ file is found, mimetype guessing based on extension of file is disabled.
+ [Unset by default]
+
+$highlight_bin::
+ Path to the highlight executable to use (it 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 web server's PATH.
+ [Default: 'highlight']
++
+*NOTE*: if you want to add support for new file type (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"). The keys of these hashes are extension and basename,
+respectively, and value for given key is name of syntax to be passed via
+`--syntax <syntax>` to highlighter.
++
+For example if repositories you are hosting use "phtml" extension for
+PHP files, and you want to have correct syntax-highlighting for those
+files, you can add the following to gitweb configuration:
++
+---------------------------------------------------------
+our %highlight_ext;
+$highlight_ext{'phtml'} = 'php';
+---------------------------------------------------------
+
+
+Links and their targets
+~~~~~~~~~~~~~~~~~~~~~~~
+The 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 the base URI of a page). You
+ might specify more than one stylesheet, for example to use "gitweb.css"
+ as base with site specific modifications in a separate stylesheet
+ to make it easier to upgrade gitweb. For example, you can add
+ a `site` stylesheet 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 the URI of gitweb's standard stylesheet. The default
+URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS`
+makefile variable. Its 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 a legacy `$stylesheet` configuration variable, which was
+used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet
+given by this variable is used by gitweb.
+
+$logo::
+ Points to the location where you put 'git-logo.png' on your web
+ server, or to be more the generic URI of logo, 72x27 size). This image
+ is displayed in the top right corner of each gitweb page and used as
+ a logo for the Atom feed. Relative to the base URI of gitweb (as a path).
+ Can be adjusted when 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 the generic URI of favicon, which will be served
+ as "image/png" type. Web browsers that support favicons (website icons)
+ may display them in the browser's URL bar and next to the site name in
+ bookmarks. Relative to the base URI of gitweb. Can be adjusted at
+ 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 the URI of JavaScript code used by gitweb.
+ Relative to the base URI of gitweb. Can be set at build time using
+ the `GITWEB_JS` build-time configuration variable.
++
+The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if
+the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used
+at build time. *Note* that this single file is generated from multiple
+individual JavaScript "modules".
+
+$home_link::
+ Target of the home link on the top of all pages (the first part of view
+ "breadcrumbs"). By default it is set to the absolute URI of a current page
+ (to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined
+ or is an empty string).
+
+$home_link_str::
+ Label for the "home link" at the top of all pages, leading to `$home_link`
+ (usually the main gitweb page, which contains the projects list). It is
+ used as the first component of gitweb's "breadcrumb trail":
+ `<home link> / <project> / <action>`. Can be set at build time using
+ the `GITWEB_HOME_LINK_STR` variable. [Default: "projects"]
+
+$logo_url::
+$logo_label::
+ URI and label (title) for the Git logo link (or your site logo,
+ if you chose to use different logo image). By default, these both
+ refer to git homepage; in the past, they pointed to git documentation
+ at http://www.kernel.org[].
+
+
+Changing gitweb's look
+~~~~~~~~~~~~~~~~~~~~~~
+You can adjust how pages generated by gitweb look using the variables described
+below. You can change the site name, add common headers and footers for all
+pages, and add a description of this gitweb installation on its main page
+(which is the 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 this variable
+ is not set or is, then gitweb uses the value of the `SERVER_NAME`
+ CGI environment variable, setting site name 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 the `GITWEB_SITENAME` at build time. [No default]
+
+$site_header::
+ Name of a file with HTML to be included at the top of each page.
+ Relative to the directory containing the 'gitweb.cgi' script.
+ Can be set using `GITWEB_SITE_HEADER` at build time. [No default]
+
+$site_footer::
+ Name of a file with HTML to be included at the bottom of each page.
+ Relative to the directory containing the 'gitweb.cgi' script.
+ Can be set using `GITWEB_SITE_FOOTER` at build time. [No default]
+
+$home_text::
+ Name of a HTML file which, if it exists, is included on the
+ gitweb projects overview page ("projects_list" view). Relative to
+ the directory containing the gitweb.cgi script. Default value
+ can be adjusted during build time using `GITWEB_HOMETEXT` variable.
+ [Default: 'indextext.html']
+
+$projects_list_description_width::
+ The width (in characters) of the "Description" column of the projects list.
+ Longer descriptions will be truncated (trying to cut at word boundary);
+ the full description is available in the 'title' attribute (usually shown on
+ mouseover). The default is 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, which
+ means the ordering used if you don't explicitly sort projects list
+ (if there is no "o" CGI query parameter in the URL). Valid values
+ are "none" (unsorted), "project" (projects are 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's behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+These configuration variables control _internal_ gitweb behavior.
+
+$default_blob_plain_mimetype::
+ Default mimetype for the blob_plain (raw) view, if mimetype checking
+ doesn't result in some other type; by default "text/plain".
+ Gitweb guesses mimetype of a file to display based on extension
+ of its filename, using `$mimetypes_file` (if set and file exists)
+ and '/etc/mime.types' files (see *mime.types*(5) manpage; only
+ filename extension rules are supported by gitweb).
+
+$default_text_plain_charset::
+ Default charset for text files. If this is not set, the web server
+ configuration will be used. Unset by default.
+
+$fallback_encoding::
+ Gitweb assumes this charset when a line contains non-UTF-8 characters.
+ The fallback decoding is used without error checking, so it can be even
+ "utf-8". The value must be a valid encoding; see the *Encoding::Supported*(3pm)
+ man page for a list. The default is "latin1", aka. "iso-8859-1".
+
+@diff_opts::
+ Rename detection options for git-diff and git-diff-tree. The default is
+ (\'-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.
++
+*Note* that rename and especially copy detection can be quite
+CPU-intensive. Note also that non git tools can have problems with
+patches generated with options mentioned above, especially when they
+involve file copies (\'-C') or criss-cross renames (\'-B').
+
+
+Some optional features and policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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. These URLs are used to generate URLs
+ describing from where to fetch a project, which are shown on
+ project summary page. The full fetch URL is "`$git_base_url/$project`",
+ for each element of this list. You can set up multiple base URLs
+ (for example one for `git://` protocol, and one for `http://`
+ protocol).
++
+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. Per-repository configuration takes precedence over value
+composed from `@git_base_url_list` elements and project name.
++
+You can setup one single value (single entry/item in this list) at build
+time by setting the `GITWEB_BASE_URL` built-time configuration variable.
+[Default: (), i.e. empty list]
+
+$projects_list_group_categories::
+ Whether to 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 each
+ repository's configuration. [Disabled by default].
+
+$project_list_default_category::
+ Default category for projects for which none is specified. If this is
+ set to the empty string, such projects will remain uncategorized and
+ listed at the top, above categorized projects. Used only if project
+ categories 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 the server load exceeds this value then gitweb will return
+ "503 Service Unavailable" error. The server load is taken to be 0
+ if gitweb cannot determine its value. Currently it works only on Linux,
+ where it uses '/proc/loadavg'; the load there is the number of active
+ tasks on the system -- processes that are actually running -- averaged
+ over the last minute.
++
+Set `$maxload` to undefined value (`undef`) to turn this feature off.
+[Default: 300]
+
+$per_request_config::
+ If this is set to code reference, it will be run once for each request.
+ You can set parts of configuration that change per session this way.
+ For example, one might use the following code in a gitweb configuration
+ file
++
+--------------------------------------------------------------------------------
+our $per_request_config = sub {
+ $ENV{GL_USER} = $cgi->remote_user || "gitweb";
+};
+--------------------------------------------------------------------------------
++
+If `$per_request_config` is not a code reference, it is interpreted as boolean
+value. If it is true gitweb will process config files once per request,
+and if it is false gitweb will process config files only once, each time it
+is executed. [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.
++
+This variable matters only when using persistent web environments that
+serve multiple requests using single gitweb instance, like mod_perl,
+FastCGI or Plackup.
+
+
+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";
+---------------------------------------------------
++
+if you run modified version of gitweb with caching support. This variable
+is purely informational, used e.g. in the "generator" meta header in HTML
+header.
+
+$my_url::
+$my_uri::
+ Full URL and absolute URL of the gitweb script;
+ in earlier versions of gitweb you might have need to set those
+ variables, but 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 '<base href="$base_url">' only for URLs with nonempty
+ PATH_INFO. 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 override 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 features cannot be overridden per project. 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 the \'sub' element.
+
+The meaning of each part of feature configuration is 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 the passage about the "blame" feature in the "Examples"
+section.
++
+To disable features that accept parameters (are configurable), you
+need to set this element to empty list i.e. `[]`.
+
+override::
+ If this field has a true value then the given feature is
+ overriddable, which means that it can be configured
+ (or enabled/disabled) on a per-repository basis.
++
+Usually given "<feature>" is configurable via the `gitweb.<feature>`
+config variable in the per-repository git configuration file.
++
+*Note* that no feature is overriddable by default.
+
+sub::
+ Internal detail of implementation. What is important is that
+ if this field is 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`
+~~~~~~~~~~~~~~~~~~~~~~
+The gitweb features that are configurable via `%feature` hash are listed
+below. This should be a complete list, but ultimately the authoritative
+and complete list is in gitweb.cgi source code, with features described
+in the comments.
+
+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 the "snapshot" action, which allows user to
+ download a compressed archive of any tree or commit, as produced
+ by linkgit:git-archive[1] and possibly additionally compressed.
+ This can potentially 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.
+Supported formats include "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 are ignored.
+
+grep::
+ Enable grep search, which lists 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 introduced or removed a given string in a file. This can be
+ practical and quite faster alternative to "blame" action, but it is
+ 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 by setting
+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 costs 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::
+ Enable and 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 the 'default' field to a list containing single
+ item of or to an empty list to disable patch view, or to a list
+ containing a single 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 each committer and author.
++
+Currently available providers are *"gravatar"* and *"picon"*.
+Only one provider at a time can be selected ('default' is one element list).
+If an unknown provider is specified, the feature is disabled.
+*Note* that some providers 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 highlight support in "blob" view. It requires
+ `$highlight_bin` program to be available (see the description of
+ this variable in the "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 the list of remote-tracking branches is an
+ unnecessary internal private detail, and this feature 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 remaining features cannot be overridden on a per project basis.
+
+search::
+ Enable text search, which will list the commits which match author,
+ committer or commit text to a given string; see the description of
+ `--author`, `--committer` and `--grep` options in linkgit:git-log[1]
+ manpage. Enabled by default.
++
+Project specific override is not supported.
+
+forks::
+ If this feature is enabled, gitweb considers projects in
+ subdirectories of project root (basename) to be forks of existing
+ projects. For each project `$projname.git`, projects in the
+ `$projname/` directory and its subdirectories will not be
+ shown in the main projects list. Instead, a \'+' mark is shown
+ next to `$projname`, which links to a "forks" view that lists all
+ the forks (all projects in `$projname/` subdirectory). Additionally
+ a "forks" view for a project is linked from project summary page.
++
+If the project list is taken from a file (`$projects_list` points to a
+file), forks are only recognized if they are listed after the main project
+in that file.
++
+Project specific override is not supported.
+
+actions::
+ Insert custom links to the action bar of all project pages. This
+ allows 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 (i.e. "$projectroot/$project"), `%h` to the current hash
+(\'h' gitweb parameter) and `%b` to the current hash base
+(\'hb' gitweb parameter); `%%` expands to \'%'.
++
+For example, at the time this page was written, the http://repo.or.cz[]
+git hosting site set it to the following to enable graphical log
+(using the third party tool *git-browser*):
++
+----------------------------------------------------------------------
+$feature{'actions'}{'default'} =
+ [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
+----------------------------------------------------------------------
++
+This adds a link titled "graphiclog" after the "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 each page in the page footer (at the bottom of
+ page). For example the footer might contain: "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 the ability to change a common timezone for dates
+ in gitweb output via JavaScript. Dates in gitweb output include
+ authordate and committerdate in "commit", "commitdiff" and "log"
+ views, and taggerdate in "tag" view. Enabled by default.
++
+The value is a list of three values: a default timezone (for if the client
+hasn't selected some other timezone and saved it in a cookie), a name of cookie
+where to store selected timezone, and a CSS class used to mark up
+dates for manipulation. If you want to turn this feature off, set "default"
+to empty list: `[]`.
++
+Typical gitweb config files will only change starting (default) timezone,
+and leave other elements at their default values:
++
+---------------------------------------------------------------------------
+$feature{'javascript-timezone'}{'default'}[0] = "utc";
+---------------------------------------------------------------------------
++
+The example configuration presented here is guaranteed to be backwards
+and forward compatible.
++
+Timezone values can be "local" (for local timezone that browser uses), "utc"
+(what gitweb uses when JavaScript or this feature is disabled), or numerical
+timezones in the form of "+/-HHMM", such as "+0200".
++
+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
+overridden 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 name of per-instance configuration file. The
+ format of this file is described above.
+/etc/gitweb.conf::
+ This is default name of 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 name of 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,140 +41,9 @@ 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.
+See also gitweb.conf(5) manpage.
-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.
-
Projects list file format
~~~~~~~~~~~~~~~~~~~~~~~~~
--
1.7.6
^ permalink raw reply related
* [PATCHv5/RFC 1/6] Documentation: Preparation for gitweb manpages
From: Jakub Narebski @ 2011-10-08 18:31 UTC (permalink / raw)
To: git, Drew Northup; +Cc: Jonathan Nieder, Jakub Narebski
In-Reply-To: <1318098723-12813-1-git-send-email-jnareb@gmail.com>
Gitweb documentation currently consists of gitweb/README, gitweb/INSTALL
and comments in gitweb source code. This is harder to find, use and
browse than manpages ("man gitweb" or "git help gitweb") and HTML
documentation ("git help --web gitweb").
The goal of the next two commits 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 to move
information not related directly to building and installing gitweb out
of gitweb/INSTALL.
The idea is to have the gitweb manpage sources reside in AsciiDoc
format in the Documentation/ directory, like for gitk and git-gui.
This means that building git documentation (with "make doc") would
also build gitweb manpages.
An alternate solution would be to have gitweb documentation in the
gitweb/ directory, perhaps in POD format (see perlpod(1)).
This patch adds infrastructure for easy generation of only
gitweb-related manpages. It adds a currently empty 'gitweb-doc'
target to Documentation/Makefile, and a 'doc' proxy target to
gitweb/Makefile.
This way to build only gitweb documentation in both 'man' and 'html'
formats one can use
make -C gitweb doc
or
cd gitweb; make doc
This somewhat follows the idea of 'full-svn-test' and 'gitweb-test' in
t/Makefile. Note also that with alternate solution, where source of
gitweb manpages would reside in the gitweb/ directory, "make doc"
would invoke "make -C gitweb doc" to generate formatted docs.
The gitweb.conf(5) and gitweb(1) manpages will be added in subsequent
commits.
[Commit message improved with help of Jonathan Nieder]
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
This commit is not strictly necessary: it only adds "doc" target to
gitweb/Makefile, and "gitweb-doc" target to Documentation/Makefile;
neither is run when e.g. generating RPM.
They are here because they would be here if documentation source was
kept along with gitweb script in the 'gitweb/' subdirectory, and to
make it easier and faster to test the changes.
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
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