From d020116c3a9e5a26ece6ea09f19ccccbaa1cf0f5 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Wed, 26 Feb 2014 23:22:37 -0500
Subject: [PATCH] Documentation

---
 src/main/distrib/data/gitblit.properties |  212 ++++++++++++++++++++++++++++------------------------
 1 files changed, 114 insertions(+), 98 deletions(-)

diff --git a/src/main/distrib/data/gitblit.properties b/src/main/distrib/data/gitblit.properties
index 2823c4d..5a08326 100644
--- a/src/main/distrib/data/gitblit.properties
+++ b/src/main/distrib/data/gitblit.properties
@@ -381,6 +381,33 @@
 # Common unit suffixes of k, m, or g are supported.
 # Documentation courtesy of the Gerrit project.
 #
+#
+# NOTE: The importance of JGit's streamFileTreshold AND Git's bigFileThreshold
+# ISSUE: https://bugs.eclipse.org/bugs/show_bug.cgi?id=394078
+#
+# "core.bigFileThreshold  
+#
+#    Files larger than this size are stored deflated, without
+#    attempting delta compression.  Storing large files without
+#    delta compression avoids excessive memory usage, at the
+#    slight expense of increased disk usage.
+#
+#  Default is 512 MiB on all platforms.
+#  This should be reasonable for most projects as source code and other 
+#  text files can still be delta compressed, 
+#  but larger binary media files won't be."
+#  -- Git documentation
+#
+# If streamFileTreshold < bigFileTreshold you _may_ spend alot of time waiting
+# for push and/or fetch to complete.  It may even look hung.
+#
+# Until the issue is resolved gracefully, a workaround is to configure
+# bigFileThreshold < streamFileTreshold AND then repack the repository.
+#
+# e.g. from the repository folder with Gitblit NOT running:
+#     git config core.bigFileTreshold 40m
+#     git gc --aggressive
+#
 # SINCE 1.0.0
 # RESTART REQUIRED
 git.streamFileThreshold = 50m
@@ -562,16 +589,7 @@
 web.projectsFile = ${baseFolder}/projects.conf
 
 # Either the full path to a user config file (users.conf)
-# OR the full path to a simple user properties file (users.properties)
 # OR a fully qualified class name that implements the IUserService interface.
-#
-# Alternative user services:
-#    com.gitblit.LdapUserService
-#    com.gitblit.RedmineUserService
-#    com.gitblit.SalesforceUserService
-#    com.gitblit.WindowsUserService
-#    com.gitblit.PAMUserService
-#    com.gitblit.HtpasswdUserService
 #
 # Any custom user service implementation must have a public default constructor.
 #
@@ -579,6 +597,25 @@
 # RESTART REQUIRED
 # BASEFOLDER
 realm.userService = ${baseFolder}/users.conf
+
+# Ordered list of external authentication providers which will be used if
+# authentication against the local user service fails.
+#
+# Valid providers are:
+#
+#    htpasswd
+#    ldap
+#    pam
+#    redmine
+#    salesforce
+#    windows
+
+# e.g. realm.authenticationProviders = htpasswd windows
+#
+# SINCE 1.4.0
+# RESTART REQUIRED
+# SPACE-DELIMITED
+realm.authenticationProviders =
 
 # How to store passwords.
 # Valid values are plain, md5, or combined-md5.  md5 is the hash of password.
@@ -601,6 +638,12 @@
 #
 # SINCE 0.5.0
 web.siteName =
+
+# The canonical url of your Gitblit server to bs used in email notifications.
+# e.g. web.canonicalUrl = https://demo-gitblit.rhcloud.com
+#
+# SINCE 1.4.0
+web.canonicalUrl = 
 
 # You may specify a different logo image for the header but it must be 120x45px.
 # If the specified file does not exist, the default Gitblit logo will be used.
@@ -1007,6 +1050,11 @@
 # SINCE 0.5.0
 web.summaryRefsCount = 5
 
+# Show a README file, if available, on the summary page.
+#
+# SINCE 1.4.0
+web.summaryShowReadme = false
+
 # The number of items to show on a page before showing the first, prev, next
 # pagination links.  A default of 50 is used for any invalid value.
 #
@@ -1024,6 +1072,16 @@
 #
 # SINCE 1.3.0
 web.reflogChangesPerPage = 10
+
+# Specify the names of documents in the root of your repository to be displayed
+# in tabs on your repository docs page.  If the name is not found in the root
+# then no tab is added.  The order specified is the order displayed.  Do not
+# specify a file extension as the aggregation of markup extensions + txt are used
+# in the search algorithm.
+#
+# SPACE-DELIMITED
+# SINCE 1.4.0
+web.documents = readme home index changelog contributing submitting_patches copying license notice authors
 
 # Registered file extensions to ignore during Lucene indexing
 #
@@ -1116,6 +1174,7 @@
 # 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
@@ -1316,19 +1375,16 @@
 # SINCE 1.3.0
 realm.container.autoCreateAccounts = false
 
-# The WindowsUserService must be backed by another user service for standard user
-# and team management.
-# default: users.conf
-#
-# RESTART REQUIRED
-# BASEFOLDER
-# SINCE 1.3.0
-realm.windows.backingUserService = ${baseFolder}/users.conf
-
 # Allow or prohibit Windows guest account logins
 #
 # SINCE 1.3.0
 realm.windows.allowGuests = false
+
+# Allow user accounts belonging to the BUILTIN\Administrators group to be
+# Gitblit administrators.
+#
+# SINCE 1.4.0
+realm.windows.permitBuiltInAdministrators = true
 
 # The default domain for authentication.
 #
@@ -1342,29 +1398,11 @@
 # SINCE 1.3.0
 realm.windows.defaultDomain =
 
-# The PAMUserService must be backed by another user service for standard user
-# and team management.
-# default: users.conf
-#
-# RESTART REQUIRED
-# BASEFOLDER
-# SINCE 1.3.1
-realm.pam.backingUserService = ${baseFolder}/users.conf
-
 # The PAM service name for authentication.
 # default: system-auth
 #
 # SINCE 1.3.1
 realm.pam.serviceName = system-auth
-
-# The HtpasswdUserService must be backed by another user service for standard user
-# and team management and attributes. This can be one of the local Gitblit user services.
-# default: users.conf
-#
-# RESTART REQUIRED
-# BASEFOLDER
-# SINCE 1.3.2
-realm.htpasswd.backingUserService = ${baseFolder}/users.conf
 
 # The Apache htpasswd file that contains the users and passwords.
 # default: ${baseFolder}/htpasswd
@@ -1373,30 +1411,6 @@
 # BASEFOLDER
 # SINCE 1.3.2
 realm.htpasswd.userfile = ${baseFolder}/htpasswd
-
-#  Determines how accounts are looked up upon login.
-#
-# If set to false, then authentication for local accounts is done against
-# the backing user service.
-# If set to true, then authentication will first be checked against the
-# htpasswd store, even if the account appears as a local account in the
-# backing user service. If the user is found in the htpasswd store, then
-# an already existing local account will be turned into an external account.
-# In this case an initial local password is never used and gets overwritten
-# by the externally stored password upon login.
-# default: false
-#
-# SINCE 1.3.2
-realm.htpasswd.overrideLocalAuthentication = false
-
-# The SalesforceUserService must be backed by another user service for standard user
-# and team management.
-# default: users.conf
-#
-# RESTART REQUIRED
-# BASEFOLDER
-# SINCE 1.3.0
-realm.salesforce.backingUserService = ${baseFolder}/users.conf
 
 # Restrict the Salesforce user to members of this org.
 # default: 0 (i.e. do not check the Org ID)
@@ -1423,15 +1437,6 @@
 #
 # SINCE 1.0.0
 realm.ldap.password = password
-
-# The LdapUserService must be backed by another user service for standard user
-# and team management.
-# default: users.conf
-#
-# SINCE 1.0.0
-# RESTART REQUIRED
-# BASEFOLDER
-realm.ldap.backingUserService = ${baseFolder}/users.conf
 
 # Delegate team membership control to LDAP.
 #
@@ -1489,10 +1494,20 @@
 # SINCE 1.0.0
 realm.ldap.groupMemberPattern = (&(objectClass=group)(member=${dn}))
 
+# Filter criteria for empty LDAP groups
+#
+# Query pattern to use when searching for an empty team. This may be any valid 
+# LDAP query expression, including the standard (&) and (|) operators.
+#
+# default: (&(objectClass=group)(!(member=*)))
+# SINCE 1.4.0
+realm.ldap.groupEmptyMemberPattern = (&(objectClass=group)(!(member=*)))
+
 # LDAP users or groups that should be given administrator privileges.
 #
 # Teams are specified with a leading '@' character.  Groups with spaces in the
-# name can be entered as "@team name".
+# name can be entered as "@team name".  This setting only applies when using
+# LDAP to maintain team memberships.
 #
 # e.g. realm.ldap.admins = john @git_admins "@git admins"
 #
@@ -1522,43 +1537,44 @@
 # SINCE 1.0.0
 realm.ldap.email = email
 
-# Defines the cache period to be used when caching LDAP queries. This is currently
-# only used for LDAP user synchronization.
-#
-# Must be of the form '<long> <TimeUnit>' where <TimeUnit> is one of 'MILLISECONDS', 'SECONDS', 'MINUTES', 'HOURS', 'DAYS' 
-# default: 2 MINUTES
-#
-# RESTART REQUIRED
-realm.ldap.ldapCachePeriod = 2 MINUTES
-
-# Defines whether to synchronize all LDAP users into the backing user service
-#
-# Valid values: true, false
-# If left blank, false is assumed
-realm.ldap.synchronizeUsers.enable = false
-
-# Defines whether to delete non-existent LDAP users from the backing user service
-# during synchronization. depends on  realm.ldap.synchronizeUsers.enable = true
-#
-# Valid values: true, false
-# If left blank, true is assumed
-realm.ldap.synchronizeUsers.removeDeleted = true
-
 # Attribute on the USER record that indicate their username to be used in gitblit
 # when synchronizing users from LDAP
 # if blank, Gitblit will use uid
 # For MS Active Directory this may be sAMAccountName
+#
+# SINCE 1.0.0
 realm.ldap.uid = uid
 
-# The RedmineUserService must be backed by another user service for standard user
-# and team management.
-# default: users.conf
+# Defines whether to synchronize all LDAP users and teams into the user service
+#
+# Valid values: true, false
+# If left blank, false is assumed
+#
+# SINCE 1.4.0
+realm.ldap.synchronize = false
+
+# Defines the period to be used when synchronizing users and teams from ldap.
+#
+# Must be of the form '<long> <TimeUnit>' where <TimeUnit> is one of 'MILLISECONDS', 'SECONDS', 'MINUTES', 'HOURS', 'DAYS' 
+
+# default: 5 MINUTES
 #
 # RESTART REQUIRED
-# BASEFOLDER
-realm.redmine.backingUserService = ${baseFolder}/users.conf
+# SINCE 1.4.0
+realm.ldap.syncPeriod = 5 MINUTES
+
+# Defines whether to delete non-existent LDAP users from the user service
+# during synchronization. depends on  realm.ldap.synchronize = true
+#
+# Valid values: true, false
+# If left blank, true is assumed
+#
+# SINCE 1.4.0
+realm.ldap.removeDeletedUsers = true
 
 # URL of the Redmine.
+#
+# SINCE 1.2.0
 realm.redmine.url = http://example.com/redmine
 
 #
@@ -1623,7 +1639,7 @@
 #
 # SINCE 1.4.0
 # RESTART REQUIRED
-server.redirectToHttpsPort = true
+server.redirectToHttpsPort = false
 
 # Specify the interface for Jetty to bind the standard connector.
 # You may specify an ip or an empty value to bind to all interfaces.

--
Gitblit v1.9.1