From 8daefa09d99774639a355c0dfa2b989fa1007f5f Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Thu, 11 Oct 2012 17:11:18 -0400
Subject: [PATCH] Created static repository close functions for unit testing and fixed Windows sharing violations
---
docs/01_setup.mkd | 99 +++++++++++++++++++++++++++++++++++++++++++++----
1 files changed, 90 insertions(+), 9 deletions(-)
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd
index 07f4b00..3123aa1 100644
--- a/docs/01_setup.mkd
+++ b/docs/01_setup.mkd
@@ -8,7 +8,11 @@
Open `web.xml` in your favorite text editor and make sure to review and set:
- <context-parameter> *git.repositoryFolder* (set the full path to your repositories folder)
- <context-parameter> *groovy.scriptsFolder* (set the full path to your Groovy hook scripts folder)
+ - <context-parameter> *groovy.grapeFolder* (set the full path to your Groovy Grape artifact cache)
+ - <context-parameter> *web.projectsFile* (set the full path to your projects metadata file)
- <context-parameter> *realm.userService* (set the full path to `users.conf`)
+ - <context-parameter> *git.packedGitLimit* (set larger than the size of your largest repository)
+ - <context-parameter> *git.streamFileThreshold* (set larger than the size of your largest committed file)
5. You may have to restart your servlet container.
6. Open your browser to <http://localhost/gitblit> or whatever the url should be.
7. Enter the default administrator credentials: **admin / admin** and click the *Login* button
@@ -22,10 +26,13 @@
Open `gitblit.properties` in your favorite text editor and make sure to review and set:
- *git.repositoryFolder* (path may be relative or absolute)
- *groovy.scriptsFolder* (path may be relative or absolute)
+ - *groovy.grapeFolder* (path may be relative or absolute)
- *server.tempFolder* (path may be relative or absolute)
- *server.httpPort* and *server.httpsPort*
- *server.httpBindInterface* and *server.httpsBindInterface*
**https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!
+ - *git.packedGitLimit* (set larger than the size of your largest repository)
+ - *git.streamFileThreshold* (set larger than the size of your largest committed file)
3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line
4. Wait a minute or two while all dependencies are downloaded and your self-signed *localhost* certificate is generated.
Please see the section titled **Creating your own Self-Signed Certificate** to generate a certificate for *your hostname*.
@@ -150,6 +157,15 @@
# If your httpd frontend is https but you are proxying http Gitblit WAR or GO
#Header edit Location ^http://([^⁄]+)/gitblit/ https://$1/gitblit/
+# Additionally you will want to tell Gitblit the original scheme and port
+#RequestHeader set X-Forwarded-Proto https
+#RequestHeader set X-Forwarded-Port 443
+
+# If you are using subdomain proxying then you will want to tell Gitblit the appropriate
+# context path for your repository url.
+# If you are not using subdomain proxying, then ignore this setting.
+#RequestHeader set X-Forwarded-Context /
+
#ProxyPass /gitblit ajp://localhost:8009/gitblit
%ENDCODE%
**Please** make sure to:
@@ -218,7 +234,7 @@
federationSets =
#### Repository Names
-Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - .`<br/>
+Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - . ~`<br/>
Whitespace is illegal.
Repositories can be grouped within subfolders. e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*
@@ -227,6 +243,35 @@
#### Repository Owner
The *Repository Owner* has the special permission of being able to edit a repository through the web UI. The Repository Owner is not permitted to rename the repository, delete the repository, or reassign ownership to another user.
+
+### Access Restrictions and Access Permissions
+
+
+#### Discrete Permissions (Gitblit v1.2.0+)
+
+Since v1.2.0, Gitblit supports more discrete permissions. While Gitblit does not offer a built-in solution for branch-based permissions like Gitolite, it does allow for the following repository access permissions:
+
+- **V** (view in web ui, RSS feeds, download zip)
+- **R** (clone)
+- **RW** (clone and push)
+- **RWC** (clone and push with ref creation)
+- **RWD** (clone and push with ref creation, deletion)
+- **RW+** (clone and push with ref creation, deletion, rewind)
+
+These permission codes are combined with the repository path to create a user permission:
+
+ RW:mygroup/myrepo.git
+
+#### Discrete Permissions with Regex Matching (Gitblit v1.2.0+)
+
+Gitblit also supports regex matching for repository permissions. The following permission grants push privileges to all repositories in the *mygroup* folder.
+
+ RW:mygroup/[A-Za-z0-9-~_\\./]+
+
+#### No-So-Discrete Permissions (Gitblit <= v1.1.0)
+
+Prior to v1.2.0, Gitblit had two main access permission groupings:
+What you were permitted to do as an anonymous user and then **RW+** for any permitted user.
### Teams
@@ -241,11 +286,13 @@
password = admin
role = "#admin"
role = "#notfederated"
- repository = repo1.git
- repository = repo2.git
+ repository = RW+:repo1.git
+ repository = RW+:repo2.git
[user "hannibal"]
password = bossman
+ repository = RWD:topsecret.git
+ repository = RW+:ateam/[A-Za-z0-9-~_\\./]+
[user "faceman"]
password = vanity
@@ -261,7 +308,7 @@
user = faceman
user = murdock
user = babaracus
- repository = topsecret.git
+ repository = RW:topsecret.git
mailingList = list@ateam.org
postReceiveScript = sendmail
@@ -275,15 +322,49 @@
username=password,role1,role2,role3...
@teamname=&mailinglist,!username1,!username2,!username3,repository1,repository2,repository3...
-#### Usernames
+### Usernames
Usernames must be unique and are case-insensitive.
Whitespace is illegal.
-#### Passwords
+### Passwords
User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).
-#### User Roles
-There are two actual *roles* in Gitblit: *#admin*, which grants administrative powers to that user, and *#notfederated*, which prevents an account from being pulled by another Gitblit instance. Administrators automatically have access to all repositories. All other *roles* are repository names. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository.
+### User Roles
+There are four actual *roles* in Gitblit:
+
+- *#admin*, which grants administrative powers to that user
+- *#notfederated*, which prevents an account from being pulled by another Gitblit instance
+- *#create*, which allows the user the power to create personal repositories
+- *#fork*, which allows the user to create a personal fork of an existing Gitblit-hosted repository
+
+Administrators automatically have access to all repositories. All other *roles* are repository permissions. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository.
+
+**NOTE:**
+The following roles are equivalent:
+
+- myrepo.git
+- RW+:myrepo.git
+
+This is to preserve backwards-compatibility with Gitblit <= 1.1.0 which granted rewind power to all access-permitted users.
+
+### Personal Repositories & Forks
+
+Personal Repositories and Forks are related but are controlled individually.
+
+#### Creating a Personal Repository
+A user may be granted the power to create personal repositories by specifying the *#create* role through the web ui or through the RPC mechanism via the Gitblit Manager. Personal repositories are exactly like common/shared repositories except that the owner has a few additional administrative powers for that repository, like rename and delete.
+
+#### Creating a Fork
+A user may also be granted the power to fork an existing repository hosted on your Gitblit server to their own personal clone by specifying the *#fork* role through the web ui or via the Gitblit Manager.
+
+Forks are mostly likely personal repositories or common/shared repositories except for two important differences:
+
+1. Forks inherit a view/clone access list from the origin repository.
+i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork. This is to facilitate collaboration.
+2. Forks are always listed in the fork network, regardless of any access restriction set on the fork.
+In other words, if you fork *RepoA.git* to *~me/RepoA.git* and then set the access restriction of *~me/RepoA.git* to *Authenticated View, Clone, & Push* your fork will still be listed in the fork network for *RepoA.git*.
+
+If you really must have an invisible fork, the clone it locally, create a new personal repository for your invisible fork, and push it back to that personal repository.
## Alternative Authentication and Authorization
@@ -404,7 +485,7 @@
[Grape](http://groovy.codehaus.org/Grape) lets you quickly add maven repository dependencies to your Groovy hook script.
-<blockquote>Grape (The Groovy Adaptable Packaging Engine or Groovy Advanced Packaging Engine) is the infrastructure enabling the grab() calls in Groovy, a set of classes leveraging [Ivy](http://ant.apache.org/ivy) to allow for a repository driven module system for Groovy. This allows a developer to write a script with an essentially arbitrary library requirement, and ship just the script. Grape will, at runtime, download as needed and link the named libraries and all dependencies forming a transitive closure when the script is run from existing repositories such as Ibiblio, Codehaus, and java.net.</blockquote>
+<blockquote>Grape (The Groovy Adaptable Packaging Engine or Groovy Advanced Packaging Engine) is the infrastructure enabling the grab() calls in Groovy, a set of classes leveraging <a href="http://ant.apache.org/ivy">Ivy</a> to allow for a repository driven module system for Groovy. This allows a developer to write a script with an essentially arbitrary library requirement, and ship just the script. Grape will, at runtime, download as needed and link the named libraries and all dependencies forming a transitive closure when the script is run from existing repositories such as Ibiblio, Codehaus, and java.net.</blockquote>
%BEGINCODE%
// create and use a primitive array
--
Gitblit v1.9.1