Documentation

10 files changed, 173 insertions, 50 deletions

diff --git a/HOME.md b/HOME.md
index a644bd95..98c45ebf 100644
--- a/HOME.md
+++ b/HOME.md
@@ -28,11 +28,15 @@ This documentation is the source content from which the [Gitblit website](http:/
 [[src/site/setup_authentication.mkd]]

 [[src/site/setup_client.mkd]]

 [[src/site/setup_clientmenus.mkd]]

+[[src/site/eclipse_plugin.mkd]]

+[[src/site/setup_mirrors.mkd]]

+[[src/site/setup_bugtraq.mkd]]

 [[src/site/setup_hooks.mkd]]

 [[src/site/setup_lucene.mkd]]

 [[src/site/setup_proxy.mkd]]

 [[src/site/setup_viewer.mkd]]

 [[src/site/administration.mkd]]

+[[src/site/setup_scaling.mkd]]

 

 ### Other Pages

 

diff --git a/build.xml b/build.xml
index ac4e5411..5385e267 100644
--- a/build.xml
+++ b/build.xml
@@ -547,16 +547,24 @@
 						<page name="upgrade Express" src="upgrade_express.mkd" />

 					</menu>

 					<divider />

-					<page name="administration" src="administration.mkd" />

-					<page name="authentication" src="setup_authentication.mkd" />

-					<page name="push hooks" src="setup_hooks.mkd" />

-					<page name="lucene indexing" src="setup_lucene.mkd" />

-					<page name="reverse proxies" src="setup_proxy.mkd" />

-					<page name="client app menus" src="setup_clientmenus.mkd" />

-					<divider />

-					<page name="Gitblit as a viewer" src="setup_viewer.mkd" />

+					<menu name="Server Configuration" pager="true" pagerPlacement="bottom" pagerLayout="justified">

+						<page name="administration" src="administration.mkd" />

+						<page name="authentication" src="setup_authentication.mkd" />

+						<page name="push hooks" src="setup_hooks.mkd" />

+						<page name="lucene indexing" src="setup_lucene.mkd" />

+						<page name="reverse proxies" src="setup_proxy.mkd" />

+						<page name="client app menus" src="setup_clientmenus.mkd" />

+						<page name="bugtraq" src="setup_bugtraq.mkd" />

+						<page name="mirrors" src="setup_mirrors.mkd" />

+						<page name="scaling" src="setup_scaling.mkd" />

+						<divider />

+						<page name="Gitblit as a viewer" src="setup_viewer.mkd" />

+					</menu>

 					<divider />

-					<page name="git client setup" src="setup_client.mkd" />

+					<menu name="Client Configuration" pager="true" pagerPlacement="bottom" pagerLayout="justified">

+						<page name="git client setup" src="setup_client.mkd" />

+						<page name="eclipse plugin" src="eclipse_plugin.mkd" />

+					</menu>

 					<divider />

 					<page name="federation" src="federation.mkd" />

 					<divider />

@@ -863,16 +871,24 @@
 							<page name="upgrade Express" src="upgrade_express.mkd" />

 						</menu>

 						<divider />

-						<page name="administration" src="administration.mkd" />

-						<page name="authentication" src="setup_authentication.mkd" />

-						<page name="push hooks" src="setup_hooks.mkd" />

-						<page name="lucene indexing" src="setup_lucene.mkd" />

-						<page name="reverse proxies" src="setup_proxy.mkd" />

-						<page name="client app menus" src="setup_clientmenus.mkd" />

-						<divider />

-						<page name="Gitblit as a viewer" src="setup_viewer.mkd" />

+						<menu name="Server Configuration" pager="true" pagerPlacement="bottom" pagerLayout="justified">

+							<page name="administration" src="administration.mkd" />

+							<page name="authentication" src="setup_authentication.mkd" />

+							<page name="push hooks" src="setup_hooks.mkd" />

+							<page name="lucene indexing" src="setup_lucene.mkd" />

+							<page name="reverse proxies" src="setup_proxy.mkd" />

+							<page name="client app menus" src="setup_clientmenus.mkd" />

+							<page name="bugtraq" src="setup_bugtraq.mkd" />

+							<page name="mirrors" src="setup_mirrors.mkd" />

+							<page name="scaling" src="setup_scaling.mkd" />

+							<divider />

+							<page name="Gitblit as a viewer" src="setup_viewer.mkd" />

+						</menu>

 						<divider />

-						<page name="git client setup" src="setup_client.mkd" />

+						<menu name="Client Configuration" pager="true" pagerPlacement="bottom" pagerLayout="justified">

+							<page name="git client setup" src="setup_client.mkd" />

+							<page name="eclipse plugin" src="eclipse_plugin.mkd" />

+						</menu>

 						<divider />

 						<page name="federation" src="federation.mkd" />

 						<divider />

diff --git a/releases.moxie b/releases.moxie
index da847641..e498f6ec 100644
--- a/releases.moxie
+++ b/releases.moxie
@@ -5,15 +5,14 @@ r20: {
     title: ${project.name} ${project.version} released
     id: ${project.version}
     date: ${project.buildDate}
-    note: "The default access restriction has been elevated from NONE to PUSH and anonymous push access has been disabled."
+    note: "The default access restriction has been elevated from NONE to PUSH and anonymous push access has been disabled by default."
     html: ~
-    text: ~
+    text: ''
+          This is a major release.
+          
+          The entire core has been refactored to be more modular.  Authentication providers have all been refactored to be simpler.  Both of these were precursor requirements for future planned improvements.  Markup rendering has been improved and expanded to several additional formats.  A repository mirroring service  has been added.  Commit pages now indicate diffstat information. And many bug fixes and smaller features have been introduced.''
     security:
-	- ''issue-361: Cookies were not reset on administrative password change of a user account.
-        This allowed accounts with changed passwords to continue authenticating.
-        Cookies are now reset on password changes, they are validated on each page request,
-        AND they will now expire 7 days after generation.
-        ''
+	- issue-361: Cookies were not reset on administrative password change of a user account. This allowed accounts with changed passwords to continue authenticating. Cookies are now reset on password changes, they are validated on each page request, AND they will now expire 7 days after generation.
     fixes:
 	- Fixed incorrect tagger attribution in the dashboard (issue-276)
 	- Fixed support for implied SSH urls in web.otherUrls (issue-311)
@@ -29,7 +28,7 @@ r20: {
 	- Fix error on generating activity page when there is no activity
 	- Fix raw page content type of binaries when running behind a reverse proxy
     changes:
-	- Gitblit now rejects pushes to mirror repositories (issue-5)
+	- Gitblit now rejects pushes to identified mirror repositories (issue-5)
 	- Personal repository prefix (~) is now configurable (issue-265)
 	- Refactored user services and separated authentication into providers (issue-281)
 	- Reversed line links in blob view (issue-309)
@@ -41,7 +40,7 @@ r20: {
 	- Change the WAR baseFolder context parameter to a JNDI env-entry to improve enterprise deployments
 	- Removed internal Gitblit ref exclusions in the upload pack
 	- Removed "show readme" setting in favor of automatic detection
-	- README files are not shown on the summary page by default, this can be changed with web.summaryShowReadme
+	- README files are not shown on the summary page by default, this can be restored with web.summaryShowReadme
 	- Support plain text, markdown, confluence, mediawiki, textile, tracwiki, or twiki "readme" files
 	- Determine best commit id (e.g. "master") for the tree and docs pages and use that in links
 	- By default GO will now bind to all interfaces for both http and https connectors.  This simplifies setup for first-time users.	
@@ -52,7 +51,7 @@ r20: {
 	- Serve repositories on both /r and /git, displaying /r because it is shorter
     additions:
 	- Added color modes for the blame page (issue-2)
-	- Added an optional MirrorExecutor which will periodically fetch ref updates from source repositories for mirrors (issue-5).  Repositories must be manually cloned using native git and "--mirror".
+	- Added an optional MirrorService which will periodically fetch ref updates from source repositories for mirrors (issue-5).  Repositories must be manually cloned using native git and "--mirror".
 	- Added branch graph image servlet based on EGit's branch graph renderer (issue-194)
 	- Added option to render Markdown commit messages (issue-203)
 	- Added setting to control creating a repository as --shared on Unix servers (issue-263)
@@ -63,12 +62,13 @@ r20: {
 	- Added filesystem write permission check (issue-345)
 	- Added GO launch parameter for redirecting logging to a rolling, daily log file (issue-348)
 	- Added settings to Windows authentication provider to permit/prohibit BUILTIN\Administrators from being Gitblit Admins (issue-354)
+	- Added canonical url setting for email notifications and web display
 	- Support rendering confluence, mediawiki, textile, tracwiki, and twiki markup documents
 	- Added setting to globally disable anonymous pushes in the receive pack
 	- Added a normalized diffstat display to the commit, commitdiff, and compare pages
 	- Added GO setting to automatically redirect all http requests to the secure https connector
 	- Automatically display common repository root documents as tabs on the docs page
-	- Support bugtraq configuration in collaboration with syntevo
+	- Support bugtraq configuration in collaboration with Syntevo,  the regex.* config keys are now DEPRECATED
 	- Added FishEye hook script (pr-137)
 	- Added Redmine Fetch hook script (issue-359)
     dependencyChanges:
@@ -83,15 +83,17 @@ r20: {
     settings:
     - { name: 'git.createRepositoriesShared', defaultValue: 'false' }
     - { name: 'git.allowAnonymousPushes', defaultValue: 'false' }
-	- { name: 'git.enableMirroring', defaultValue: 'false' }
 	- { name: 'git.defaultAccessRestriction', defaultValue: 'PUSH' }
+	- { name: 'git.enableMirroring', defaultValue: 'false' }
 	- { name: 'git.mirrorPeriod', defaultValue: '30 mins' }
+	- { name: 'git.userRepositoryPrefix', defaultValue: '~' }
 	- { name: 'realm.authenticationProviders', defaultValue: ' ' }
 	- { name: 'realm.ldap.groupEmptyMemberPattern', defaultValue: '(&(objectClass=group)(!(member=*)))' }
 	- { name: 'realm.ldap.synchronize', defaultValue: 'false' }
 	- { name: 'realm.ldap.syncPeriod', defaultValue: '5 MINUTES' }
 	- { name: 'realm.ldap.removeDeletedUsers', defaultValue: 'true' }
 	- { name: 'realm.windows.permitBuiltInAdministrators', defaultValue: 'true' }
+	- { name: 'web.canonicalUrl', defaultValue: ' ' }
 	- { name: 'web.commitMessageRenderer', defaultValue: 'plain' }
 	- { name: 'web.documents', defaultValue: 'readme home index changelog contributing submitting_patches copying license notice authors' }
 	- { name: 'web.showBranchGraph', defaultValue: 'true' }
diff --git a/src/main/distrib/data/gitblit.properties b/src/main/distrib/data/gitblit.properties
index b9e6e06a..5a083264 100644
--- a/src/main/distrib/data/gitblit.properties
+++ b/src/main/distrib/data/gitblit.properties
@@ -1174,6 +1174,7 @@ web.forceDefaultLocale =
 # Enable/disable global regex substitutions (i.e. shared across repositories)

 #

 # SINCE 0.5.0

+# DEPRECATED 1.4.0 (migrate to bugtraq instead)

 regex.global = true

 

 # Example global regex substitutions

diff --git a/src/site/eclipse_plugin.mkd b/src/site/eclipse_plugin.mkd
new file mode 100644
index 00000000..bfa394a2
--- /dev/null
+++ b/src/site/eclipse_plugin.mkd
@@ -0,0 +1,22 @@
+

+## Egitblit

+

+There is an Eclipse plugin, *Egitblit*, provided by the [Baloise Group](http://baloise.github.io).

+

+Features include:

+

+- Filtering repositories

+- Support for multiple Gitblit servers

+- Copying git repo urls to the clipboard

+- or via drag&drop to any drag&drop enabled target as text (or as type URL)

+- Integration with the EGit Clone Wizard

+- Opening the Gitblit summary page of the selected repository

+

+

+### Installation

+

+You can install it from the Eclipse Marketplace.

+

+### Source Code & Issue Tracker

+

+The source and issue tracker for *Egitblit* are hosted on [Github](https://github.com/baloise/egitblit).

diff --git a/src/site/roadmap.mkd b/src/site/roadmap.mkd
index 8b3e31f0..485885ea 100644
--- a/src/site/roadmap.mkd
+++ b/src/site/roadmap.mkd
@@ -3,15 +3,7 @@
 This is not exactly a formal roadmap but it is a priority list of what might be implemented in future releases.  

 This list is volatile and may not reflect what will be in the next release.

 

-* Integrate an SSH daemon to complete the transport trifecta: http/https, git, and ssh

-* GitHub-style Pull Requests or Gerrit-style Patchsets (issue 215)

-* Clone/Mirror Repository feature (issue 5)

-    * optional scheduled pulls

-    * optional automatic push to origin/remotes?

-    * optional manual push to origin/remotes?

-* Re-use the EGit branch visualization table cell renderer as some sort of servlet (issue 194)

+* **In-Progress**: Integrate an SSH daemon to complete the transport trifecta: http/https, git, and ssh (issue-369)

 * Diff should highlight inserted/removed fragment compared to original line

 * Respect Gerrit branch permissions, if found (issue 36)

-* Repository regex substitutions should be stored in .git/.config, not gitblit.properties

-* Editable settings page in GO/WAR

-* Create Eclipse plugin to enumerate repositories and delegate cloning to EGit

+

diff --git a/src/site/rpc.mkd b/src/site/rpc.mkd
index 6fa9ba5a..58b2966c 100644
--- a/src/site/rpc.mkd
+++ b/src/site/rpc.mkd
@@ -21,15 +21,6 @@ This application uses a combination of RSS feeds and the JSON RPC interface, bot
 **NOTE:**  

 Gitblit Manager stores your login credentials **INSECURELY** in homedir/.gitblit/config.

 

-### Eclipse/EGit "Import from Gitblit" Feature (Planning)

-

-One obvious goal of a Gitblit RPC mechanism would be to have an Eclipse/EGit Feature that allows authentication and enumeration of Gitblit repositories from the Eclipse *Import...* menu.  Batch cloning would be supported and delegated to EGit.

-

-This particular project should not be difficult as the only external dependency for `com.gitblit.utils.RpcUtils` is [google-gson](http://google-gson.googlecode.com) which is already a dependency of the EGit/GitHub Mylyn feature.

-

-One proposal from the EGit team is to define a common JSON RPC method for enumeration of repositories which can be implemented by Git hosts.  The EGit team would then implement the UI and the client-side enumeration code.  This idea was raised as part of this [feature request for EGit](https://bugs.eclipse.org/bugs/show_bug.cgi?id=361251).

-

-Currently this project is in the planning stage.

 

 ## RSS Query Interface

 

@@ -302,4 +293,4 @@ The original repository name is specified in the *name* url parameter.  The new
   "heapSize": 1899560960,

   "servletContainer": "jetty/7.4.3.v20110701"

 }

-```
\ No newline at end of file
+```

diff --git a/src/site/setup_bugtraq.mkd b/src/site/setup_bugtraq.mkd
new file mode 100644
index 00000000..ad4a75dd
--- /dev/null
+++ b/src/site/setup_bugtraq.mkd
@@ -0,0 +1,35 @@
+

+## Setting up Bugtraq

+

+*SINCE 1.4.0*

+

+[Bugtraq](https://github.com/mstrap/bugtraq) is a specification started by Syntevo & supported by Gitblit to establish a standard to define and parse commit messages for linkable text.

+

+### Why do I care?

+

+It's a portable way for your repository to have linkable issue, pull request, change-id, etc text fragments.  SmartGit/Hg and Gitblit both use the reference implementation available in the aforementioned Github project so if you configure Bugtraq for one you automatically get linked text in the other.

+

+### How do I define the configuration?

+

+You add a *.gitbugtraq* file to the root of your repository on the default branch.

+

+This file is formatted like a standard Git config file.  Here are some quick examples:

+

+    [bugtraq "googlecode"]

+        url = http://code.google.com/p/yourproject/issues/detail?id=%BUGID%

+        logregex = "[Ii]ssues?:?(\\s*(,|and)?\\s*#?\\d+)+\n(\\d+)"

+    

+    [bugtraq "gerrit"]

+        url = "https://git.eclipse.org/r/#q,%BUGID%,n,z"

+        logregex = "Change-Id:\\s*(I[A-Fa-f0-9]{40})"

+    

+    [bugtraq "jira"]

+        https://jira.atlassian.com/browse/%BUGID%

+        logregex = (JRA-\\d+)

+

+    [bugtraq "github"]

+        url = "https://github.com/gitblit/gitblit/pull/%BUGID%"

+        loglinkregex = "(?:pull request|pull|pr)\\s*[-#]?[0-9]+"

+        logregex = "\\d+"

+        loglinktext = "pull request #%BUGID%"

+

diff --git a/src/site/setup_mirrors.mkd b/src/site/setup_mirrors.mkd
new file mode 100644
index 00000000..9e2b91e0
--- /dev/null
+++ b/src/site/setup_mirrors.mkd
@@ -0,0 +1,28 @@
+

+## Setting up Mirrors

+

+*SINCE 1.4.0*

+

+Gitblit supports mirroring external public repositories.  The service that updates mirrors will be enabled *after a restart* with the following setting:

+

+    git.enableMirroring = true

+

+Gitblit does not yet provide a web interface to setup a repository mirror so you will need to use native git for initial setup of your repository mirror.

+

+1. Open a command prompt in your *git.repositoriesFolder*

+2. Optionally create a subfolder for the mirror repositories and cd into that directory, for example you might put all mirrors together in a *mirrors* folder.

+3. Clone the external public repository as a mirror<pre>git clone --mirror &lt;repository_url&gt;</pre>

+4. If Gitblit is currently running, login as the administrator and clear the repository cache

+

+That's it.  Gitblit will identify the newly cloned repository as a mirror, will enforce the necessary rules regarding mirrors, and will automatically fetch ref updates based on your configured *git.mirrorPeriod* setting.

+

+    git.mirrorPeriod = 30 mins

+

+### Rules, Requirements, & Gotchas

+

+1. The *origin* remote must be the mirror source

+2. The *origin* repository must be publicly accessible, or at least accessible without explicit authentication unless you embed the credentials in the origin url (not recommended).

+3. *origin* SSH urls are untested and are very unlikely to work since Gitblit and JGit are not configured to look for your personal SSH keys.  Stick to the http, https, or git transports.

+4. Gitblit will automatically repair and ref specs that it finds with a // sequence.

+5. Mirrors are *read-only*.  You may not directly push to a mirror.

+6. Mirrors can not have work trees.  They must be a bare repository cloned using the --mirror flag.

diff --git a/src/site/setup_scaling.mkd b/src/site/setup_scaling.mkd
new file mode 100644
index 00000000..5e0551e1
--- /dev/null
+++ b/src/site/setup_scaling.mkd
@@ -0,0 +1,32 @@
+

+## Scaling Gitblit

+

+My experience with scaling Gitblit to be very large is from interacting with those who do run very large Gitblit or Gerrit installs.

+

+### Configuring Big JGit Servers

+

+-Xmx8g # gobs of JVM heap

+

+    # for `jgit daemon` or gerrit.config

+    [core]

+        packedGitLimit = 4g # around 50% of JVM heap

+        packedGitOpenFiles = 8192 # don't forget to configure ulimit

+        streamFileThreshold = 2047m # avoids pathological inflate

+        deltaBaseCacheLimit = 50m

+

+    # applies to `jgit gc`

+    [pack]

+        bigFileThreshold = 20m # don't delta compress big binaries

+        indexVersion = 2 # use index v2

+

+-- Shawn Pearce, co-team lead on JGit @ Google ([slides](http://www.eclipsecon.org/2013/sites/eclipsecon.org.2013/files/Scaling%20Up%20JGit%20-%20EclipseCon%202013.pdf))

+

+### How does these Gerrit settings apply to Gitblit?

+

+Gerrit & Gitblit are both JGit-based servers.  They have similar configuration options.  Here are the relevant Gitblit settings:

+

+    git.packedGitLimit = 4g

+    git.packedGitOpenFiles = 8192

+    git.streamFileTreshold = 2047m

+    git.deltaBaseCacheLimit = 50m

+