From: Junio C Hamano Date: Fri, 21 Oct 2011 23:04:36 +0000 (-0700) Subject: Merge branch 'mh/ref-api' X-Git-Tag: v1.7.8-rc0~20 X-Git-Url: https://www.git.lorimer.id.au/gitweb.git/diff_plain/2f18b4642d6ea052cb6ad85f3a013a33b6afbe92?hp=c5f29abd8098275382ff56d8cbb00d660a64b43e Merge branch 'mh/ref-api' * mh/ref-api: clear_ref_cache(): inline function write_ref_sha1(): only invalidate the loose ref cache clear_ref_cache(): extract two new functions clear_ref_cache(): rename parameter invalidate_ref_cache(): expose this function in the refs API invalidate_ref_cache(): take the submodule as parameter invalidate_ref_cache(): rename function from invalidate_cached_refs() --- diff --git a/Documentation/Makefile b/Documentation/Makefile index 6346a75dda..551325604e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,9 +1,9 @@ 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 + 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/RelNotes/1.7.7.1.txt b/Documentation/RelNotes/1.7.7.1.txt new file mode 100644 index 0000000000..fecfac8a16 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.1.txt @@ -0,0 +1,59 @@ +Git v1.7.7.1 Release Notes +========================== + +Fixes since v1.7.7 +------------------ + + * On some BSD systems, adding +s bit on directories is detrimental + (it is not necessary on BSD to begin with). The installation + procedure has been updated to take this into account. + + * After incorrectly written third-party tools store a tag object in + HEAD, git diagnosed it as a repository corruption and refused to + proceed in order to avoid spreading the damage. We now gracefully + recover from such a situation by pretending as if the commit that + is pointed at by the tag were in HEAD. + + * "git apply --whitespace=error" did not bother to report the exact + line number in the patch that introduced new blank lines at the end + of the file. + + * "git apply --index" did not check corrupted patch. + + * "git checkout $tree $directory/" resurrected paths locally removed or + modified only in the working tree in $directory/ that did not appear + in $directory of the given $tree. They should have been kept intact. + + * "git diff $tree $path" used to apply the pathspec at the output stage, + reading the whole tree, wasting resources. + + * The code to check for updated submodules during a "git fetch" of the + superproject had an unnecessary quadratic loop. + + * "git fetch" from a large bundle did not enable the progress output. + + * When "git fsck --lost-and-found" found that an empty blob object in the + object store is unreachable, it incorrectly reported an error after + writing the lost blob out successfully. + + * "git filter-branch" did not refresh the index before checking that the + working tree was clean. + + * "git grep $tree" when run with multiple threads had an unsafe access to + the object database that should have been protected with mutex. + + * The "--ancestry-path" option to "git log" and friends misbehaved in a + history with complex criss-cross merges and showed an uninteresting + side history as well. + + * Test t1304 assumed LOGNAME is always set, which may not be true on + some systems. + + * Tests with --valgrind failed to find "mergetool" scriptlets. + + * "git patch-id" miscomputed the patch-id in a patch that has a line longer + than 1kB. + + * When an "exec" insn failed after modifying the index and/or the working + tree during "rebase -i", we now check and warn that the changes need to + be cleaned up. diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.txt index 108e6cd0ea..886dfbfaa5 100644 --- a/Documentation/RelNotes/1.7.8.txt +++ b/Documentation/RelNotes/1.7.8.txt @@ -4,14 +4,24 @@ Git v1.7.8 Release Notes (draft) Updates since v1.7.7 -------------------- + * Some git-svn, git-gui and msysgit updates. + + * Updates to bash completion scripts. + * The build procedure has been taught to take advantage of computed dependency automatically when the complier supports it. * The date parser now accepts timezone designators that lack minutes part and also has a colon between "hh:mm". + * The contents of the /etc/mailname file, if exists, is used as the + default value of the hostname part of the committer/author e-mail. + * "git am" learned how to read from patches generated by Hg. + * "git archive" talking with a remote repository can report errors + from the remote side in a more informative way. + * "git branch" learned an explicit --list option to ask for branches listed, optionally with a glob matching pattern to limit its output. @@ -21,6 +31,14 @@ Updates since v1.7.7 * Variants of "git cherry-pick" and "git revert" that take multiple commits learned to "--continue". + * Errors at the network layer is logged by "git daemon". + + * "git diff" learned "--minimal" option to spend extra cycles to come + up with a minimal patch output. + + * "git diff" learned "--function-context" option to show the whole + function as context that was affected by a change. + * "git fetch" learned to honor transfer.fsckobjects configuration to validate the objects that were received from the other end, just like "git receive-pack" (the receiving end of "git push") does. @@ -33,10 +51,35 @@ Updates since v1.7.7 * "git for-each-ref" learned "%(contents:subject)", "%(contents:body)" and "%(contents:signature)". The last one is useful for signed tags. + * "git grep" used to incorrectly pay attention to .gitignore files + scattered in the directory it was working in even when "--no-index" + option was used. It no longer does this. The "--exclude-standard" + option needs to be given to explicitly activate the ignore + mechanism. + + * "git grep" learned "--untracked" option, where given patterns are + searched in untracked (but not ignored) files as well as tracked + files in the working tree, so that matches in new but not yet + added files do not get missed. + + * The recursive merge backend no longer looks for meaningless + existing merges in submodules unless in the outermost merge. + + * "git log" and friends learned "--children" option. + * "git ls-remote" learned to respond to "-h"(elp) requests. + * "git merge" learned the "--edit" option to allow users to edit the + merge commit log message. + * "git send-email" learned to respond to "-h"(elp) requests. + * "git send-email" allows the value given to sendemail.aliasfile to begin + with "~/" to refer to the $HOME directory. + + * "git send-email" forces use of Authen::SASL::Perl to work around + issues between Authen::SASL::Cyrus and AUTH PLAIN/LOGIN. + * "git stash" learned "--include-untracked" option to stash away untracked/ignored cruft from the working tree. @@ -57,6 +100,8 @@ Updates since v1.7.7 * "gitweb" leaked unescaped control characters from syntax hiliter outputs. + * "gitweb" now has its own manual pages. + Also contains other documentation updates and minor code cleanups. @@ -71,66 +116,64 @@ included in this release. errors. (merge be22d92eac8 jn/maint-http-error-message later to maint). + * Error report from smart HTTP transport, when the connection was + broken in the middle of a transfer, showed a useless message on + a corrupt packet. + (merge 6cdf022 sp/smart-http-failure later to maint). + + * HTTP transport did not use pushurl correctly, and also did not tell + what host it is trying to authenticate with when asking for + credentials. + (merge deba493 jk/http-auth later to maint). + * Adding many refs to the local repository in one go (e.g. "git fetch" that fetches many tags) and looking up a ref by name in a repository with too many refs were unnecessarily slow. (merge 17d68a54d jp/get-ref-dir-unsorted later to maint). + * Report from "git commit" on untracked files was confused under + core.ignorecase option. + (merge 2548183b jk/name-hash-dirent later to maint). + + * The attribute mechanism did not use case insensitive match when + core.ignorecase was set. + (merge 6eba621 bc/attr-ignore-case later to maint). + + * "git bisect" did not notice when it failed to update the working tree + to the next commit to be tested. + (merge 1acf11717 js/bisect-no-checkout later to maint). + + * "git config --bool --get-regexp" failed to separate the variable name + and its value "true" when the variable is defined without "= true". + (merge 880e3cc mm/maint-config-explicit-bool-display later to maint). + * "git remote rename $a $b" were not careful to match the remote name against $a (i.e. source side of the remote nickname). (merge b52d00aed mz/remote-rename later to maint). - * "git diff $tree $path" used to apply the pathspec at the output stage, - reading the whole tree, wasting resources. - (merge 2f88c1970 jc/diff-index-unpack later to maint). - * "git diff --[num]stat" used to use the number of lines of context different from the default, potentially giving different results from "git diff | diffstat" and confusing the users. (merge f01cae918 jc/maint-diffstat-numstat-context later to maint). - * The code to check for updated submodules during a "git fetch" of the - superproject had an unnecessary quadratic loop. - (merge 6859de45 jk/maint-fetch-submodule-check-fix later to maint). - - * "git fetch" from a large bundle did not enable the progress output. - (merge be042aff jc/maint-bundle-too-quiet later to maint). - - * When "git fsck --lost-and-found" found that an empty blob object in the - object store is unreachable, it incorrectly reported an error after - writing the lost blob out successfully. - (merge eb726f2d jc/maint-fsck-fwrite-size-check later to maint). - - * "git filter-branch" did not refresh the index before checking that the - working tree was clean. - (merge 5347a50f jk/filter-branch-require-clean-work-tree later to maint). - - * "git grep $tree" when run with multiple threads had an unsafe access to - the object database that should have been protected with mutex. - (merge 8cb5775b2 nm/grep-object-sha1-lock later to maint). - - * The "--ancestry-path" option to "git log" and friends misbehaved in a - history with complex criss-cross merges and showed an uninteresting - side history as well. - (merge c05b988a6 bk/ancestry-path later to maint). - * "git merge" did not understand ":/" as a way to name a commit. * "git mergetool" learned to use its arguments as pathspec, not a path to the file that may not even have any conflict. (merge 6d9990a jm/mergetool-pathspec later to maint). - * Tests with --valgrind failed to find "mergetool" scriptlets. - (merge ee0d7bf92 tr/mergetool-valgrind later to maint). + * "git pull" and "git rebase" did not work well even when GIT_WORK_TREE is + set correctly with GIT_DIR if the current directory is outside the working + tree. + (merge 035b5bf jk/pull-rebase-with-work-tree later to maint). - * "git patch-id" miscomputed the patch-id in a patch that has a line longer - than 1kB. - (merge b9ab810b ms/patch-id-with-overlong-line later to maint). + " "git push" on the receiving end used to call post-receive and post-update + hooks for attempted removal of non-existing refs. + (merge 160b81ed ph/push-to-delete-nothing later to maint). - * When an "exec" insn failed after modifying the index and/or the working - tree during "rebase -i", we now check and warn that the changes need to - be cleaned up. - (merge 1686519a mm/rebase-i-exec-edit later to maint). + * "git send-email" did not honor the configured hostname when restarting + the HELO/EHLO exchange after switching TLS on. + (merge 155b940 md/smtp-tls-hello-again later to maint). * "gitweb" used to produce a non-working link while showing the contents of a blob, when JavaScript actions are enabled. @@ -138,7 +181,7 @@ included in this release. --- exec >/var/tmp/1 -O=v1.7.7-212-g4909bbe +O=v1.7.7-418-g40d6987 echo O=$(git describe --always master) git log --first-parent --oneline --reverse ^$O master echo diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index e76195ac97..d4a51da464 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -117,5 +117,4 @@ commit. And the default value is 40. If there are more than one take effect. -h:: ---help:: Show help message. diff --git a/Documentation/config.txt b/Documentation/config.txt index 03296b7eb8..9c81fffc61 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -45,9 +45,10 @@ lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to. -There is also a case insensitive alternative `[section.subsection]` syntax. -In this syntax, subsection names follow the same restrictions as for section -names. +There is also a deprecated `[section.subsection]` syntax. With this +syntax, the subsection name is converted to lower-case and is also +compared case sensitively. These subsection names follow the same +restrictions as section names. All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form @@ -1071,6 +1072,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. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b620b3afec..08b581f040 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -45,6 +45,10 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +--minimal:: + Spend extra time to make sure the smallest possible + diff is produced. + --patience:: Generate a diff using the "patience diff" algorithm. @@ -404,6 +408,10 @@ endif::git-format-patch[] Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other. +-W:: +--function-context:: + Show whole surrounding functions of changes. + ifndef::git-format-patch[] --exit-code:: Make the program exit with codes similar to diff(1). diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 0fdb82ee86..02133d5fc9 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -68,7 +68,9 @@ if set: In case (some of) these environment variables are not set, the information is taken from the configuration items user.name and user.email, or, if not -present, system user name and fully qualified hostname. +present, system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, 'git commit-tree' will just wait @@ -90,6 +92,10 @@ Discussion include::i18n.txt[] +FILES +----- +/etc/mailname + SEE ALSO -------- linkgit:git-write-tree[1] diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 69a1e4af9e..31b28fc29f 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -161,6 +161,16 @@ the facility of inet daemon to achieve the same before spawning repository configuration. By default, all the services are overridable. +--informative-errors:: +--no-informative-errors:: + When informative errors are turned on, git-daemon will report + more verbose errors to the client, differentiating conditions + like "no such repository" from "repository not exported". This + is more convenient for clients, but may leak information about + the existence of unexported repositories. When informative + errors are not enabled, all errors report "access denied" to the + client. The default is --no-informative-errors. + :: A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index e44a4988b7..15d6711d46 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -23,7 +23,7 @@ SYNOPSIS [-A ] [-B ] [-C ] [-f ] [-e] [--and|--or|--not|(|)|-e ...] - [--cached | --no-index | ...] + [ [--exclude-standard] [--cached | --no-index | --untracked] | ...] [--] [...] DESCRIPTION @@ -49,7 +49,20 @@ OPTIONS blobs registered in the index file. --no-index:: - Search files in the current directory, not just those tracked by git. + Search files in the current directory that is not managed by git. + +--untracked:: + In addition to searching in the tracked files in the working + tree, search also in untracked files. + +--no-exclude-standard:: + Also search in ignored files by not honoring the `.gitignore` + mechanism. Only useful with `--untracked`. + +--exclude-standard:: + Do not pay attention to ignored files specified via the `.gitignore` + mechanism. Only useful when searching files in the current directory + with `--no-index`. -a:: --text:: diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index ea95c90460..f3eef510f2 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/Documentation/git-svn.txt b/Documentation/git-svn.txt index f977e8780b..34ee785064 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -234,6 +234,14 @@ svn:mergeinfo property in the SVN repository when possible. Currently, this can only be done when dcommitting non-fast-forward merges where all parents but the first have already been pushed into SVN. +--interactive;; + Ask the user to confirm that a patch set should actually be sent to SVN. + For each patch, one may answer "yes" (accept this patch), "no" (discard this + patch), "all" (accept all patches), or "quit". + + + 'git svn dcommit' returns immediately if answer if "no" or "quit", without + commiting anything to SVN. + 'branch':: Create a branch in the SVN repository. diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt new file mode 100644 index 0000000000..4ca3e27dc9 --- /dev/null +++ b/Documentation/gitweb.conf.txt @@ -0,0 +1,884 @@ +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. + +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 +---------- +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 = ;`") 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. + +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 + `$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 ++ +----------------------------------------------------------------------------- + SP +----------------------------------------------------------------------------- ++ +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`. By default this variable is + not set, which means that 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. ++ +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. + 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`. By default this variable is not set, which + means that you can directly access those repositories that are hidden + from projects list page (e.g. the are not listed in the $projects_list + file). + + +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). + By default set to 'highlight'; set it to full path to highlight + executable if it is not installed on your web server's PATH. + Note that 'highlight' feature must be set for gitweb to actually + use syntax hightlighting. ++ +*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 ` 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 + By default set to '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. + By default set to '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": + ` / / `. Can be set at build time using + the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects", + as this link leads to the list of projects. Other popular choice it to + set it to the name of site. + +$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, http://git-scm.com[]; 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. Unset by 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 + value. + +$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 + value. + +$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. + By default set to '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. +By default it is set to (), i.e. an empty list. This means that gitweb +would not try to create project URL (to fetch) from project name. + +$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 (set to 0). + +$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. By default set to "" (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. + False by default (set to 0). + +$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. +The default value is 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. True by default (set to 1). ++ +*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 '' 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: +---------------------------------------------------------------------- +"" => { + "sub" => , + "override" => , + "default" => [ ... ] +}, +---------------------------------------------------------------------- +Some features cannot be overridden per project. For those +features the structure of appropriate `%feature` hash element has a simpler +form: +---------------------------------------------------------------------- +"" => { + "override" => 0, + "default" => [ ... ] +}, +---------------------------------------------------------------------- +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 "" is configurable via the `gitweb.` +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` 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 +`("