Documentation

6 files changed, 120 insertions, 20 deletions

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

+