Moxie
2015-11-23 67834872ddd5630b9c30c53c2972f5dcbf3dd5aa
commit | author | age
48fe87 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
M 2 <html>
3 <head>
4 <!-- Begin Header -->
5 <title>Gitblit</title>
6 <meta charset="utf-8">
7 <meta name="ROBOTS" content="INDEX">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 <meta name="viewport" content="width=device-width, initial-scale=1.0">
10         
11 <link rel="stylesheet" href="./bootstrap/css/bootstrap.css">
12 <link rel='shortcut icon' type='image/png' href='./gitblt-favicon.png' />
13 <link rel="stylesheet" href="./prettify/prettify.css" />
14 <!-- Google Plus Profile Page -->
15 <link rel="publisher" href="https://plus.google.com/114464678392593421684" />
16 <style type="text/css"> a.gpluspage { margin-top:3px;text-decoration: none; } </style>
17
18 <!-- Google Plus One -->
19 <link rel="canonical" href="http://gitblit.com" />
20 <script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
21 <style type="text/css"> div.gplusone { margin-top:12px; } </style>
22
23 <script src="./prettify/prettify.js"></script>
24 <script src="./bootstrap/js/jquery.js"></script>
25 <script src="./bootstrap/js/bootstrap.min.js"></script>
26 </head>
27 <body onload='prettyPrint()'>        <!-- Navigation Bar -->
28         <div class="navbar navbar-fixed-top">
29             <div class="navbar-inner">
30                 <div class="container">
31                       <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
32                         <span class="icon-bar"></span>
33                         <span class="icon-bar"></span>
34                         <span class="icon-bar"></span>
35                       </a>
36                       <a class="brand" href="./"><img src="./gitblt_25_white.png" alt="Gitblit"></img></a>
37                     <div class="nav-collapse">
38                         <ul class="nav">
39                             <li class='dropdown'> <!-- Menu -->
40 <a class='dropdown-toggle' href='#' data-toggle='dropdown'>about<b class='caret'></b></a>
41 <ul class='dropdown-menu'>
42 <li><a href='index.html'>overview</a></li>
43 <li><a href='features.html'>features</a></li>
44 <li><a href='screenshots.html'>screenshots</a></li>
45 </ul></li> <!-- End Menu -->
46 <li class='dropdown'> <!-- Menu -->
47 <a class='dropdown-toggle' href='#' data-toggle='dropdown'>documentation<b class='caret'></b></a>
48 <ul class='dropdown-menu'>
49 <li class='dropdown-submenu'> <!-- Submenu -->
50 <a tabindex='-1' href='#'>Gitblit GO</a>
51 <ul class='dropdown-menu'>
52 <li><a href='setup_go.html'>setup GO</a></li>
53 <li><a href='upgrade_go.html'>upgrade GO</a></li>
54 </ul></li> <!-- End Submenu -->
55 <li class='divider'></li>
56 <li class='dropdown-submenu'> <!-- Submenu -->
57 <a tabindex='-1' href='#'>Gitblit WAR</a>
58 <ul class='dropdown-menu'>
59 <li><a href='setup_war.html'>setup WAR</a></li>
60 <li><a href='upgrade_war.html'>upgrade WAR</a></li>
61 </ul></li> <!-- End Submenu -->
62 <li class='divider'></li>
63 <li class='dropdown-submenu'> <!-- Submenu -->
64 <a tabindex='-1' href='#'>Server Configuration</a>
65 <ul class='dropdown-menu'>
66 <li><a href='administration.html'>administration</a></li>
67 <li><a href='setup_authentication.html'>authentication</a></li>
68 <li><a href='setup_hooks.html'>push hooks</a></li>
69 <li><a href='setup_lucene.html'>lucene indexing</a></li>
70 <li><a href='setup_proxy.html'>reverse proxies</a></li>
71 <li><a href='setup_clientmenus.html'>client app menus</a></li>
72 <li><a href='setup_bugtraq.html'>bugtraq</a></li>
73 <li><a href='setup_mirrors.html'>mirrors</a></li>
74 <li><a href='setup_scaling.html'>scaling</a></li>
5287d2 75 <li><a href='setup_fail2ban.html'>fail2ban</a></li>
48fe87 76 <li class='divider'></li>
M 77 <li><a href='setup_viewer.html'>Gitblit as a viewer</a></li>
78 </ul></li> <!-- End Submenu -->
79 <li class='divider'></li>
80 <li class='dropdown-submenu'> <!-- Submenu -->
81 <a tabindex='-1' href='#'>Client Usage</a>
82 <ul class='dropdown-menu'>
83 <li><a href='setup_transport_http.html'>using HTTP/HTTPS</a></li>
84 <li><a href='setup_transport_ssh.html'>using SSH</a></li>
85 <li><a href='eclipse_plugin.html'>using the Eclipse plugin</a></li>
86 </ul></li> <!-- End Submenu -->
87 <li class='divider'></li>
88 <li class='dropdown-submenu'> <!-- Submenu -->
89 <a tabindex='-1' href='#'>Tickets</a>
90 <ul class='dropdown-menu'>
91 <li><a href='tickets_overview.html'>overview</a></li>
92 <li><a href='tickets_using.html'>using</a></li>
93 <li><a href='tickets_barnum.html'>barnum</a></li>
94 <li><a href='tickets_setup.html'>setup</a></li>
95 <li><a href='tickets_replication.html'>replication & advanced administration</a></li>
96 </ul></li> <!-- End Submenu -->
97 <li class='divider'></li>
98 <li class='dropdown-submenu'> <!-- Submenu -->
99 <a tabindex='-1' href='#'>Plugins</a>
100 <ul class='dropdown-menu'>
101 <li><a href='plugins_overview.html'>overview</a></li>
102 <li><a href='plugins_extensions.html'>extension points</a></li>
103 </ul></li> <!-- End Submenu -->
104 <li class='divider'></li>
105 <li><a href='federation.html'>federation</a></li>
106 <li class='divider'></li>
107 <li><a href='properties.html'>settings</a></li>
108 <li><a href='faq.html'>faq</a></li>
109 <li class='divider'></li>
110 <li><a href='design.html'>design</a></li>
111 <li><a href='rpc.html'>rpc</a></li>
112 </ul></li> <!-- End Menu -->
113 <li class='dropdown'> <!-- Menu -->
114 <a class='dropdown-toggle' href='#' data-toggle='dropdown'>releases<b class='caret'></b></a>
115 <ul class='dropdown-menu'>
116 <li><a href='releasenotes.html'>release notes</a></li>
117 <li><a href='releases.html'>release history</a></li>
118 </ul></li> <!-- End Menu -->
119 <li class='dropdown'> <!-- Menu -->
120 <a class='dropdown-toggle' href='#' data-toggle='dropdown'>downloads<b class='caret'></b></a>
121 <ul class='dropdown-menu'>
678348 122 <li><a href='http://dl.bintray.com/gitblit/releases/gitblit-1.7.1.zip'>Gitblit GO (Windows)</a></li>
M 123 <li><a href='http://dl.bintray.com/gitblit/releases/gitblit-1.7.1.tar.gz'>Gitblit GO (Linux/OSX)</a></li>
124 <li><a href='http://dl.bintray.com/gitblit/releases/gitblit-1.7.1.war'>Gitblit WAR</a></li>
48fe87 125 <li class='divider'></li>
M 126 <li><a href='https://registry.hub.docker.com/u/jmoger/gitblit/'>Gitblit GO (Docker)</a></li>
127 <li class='divider'></li>
128 <li><a href='http://plugins.gitblit.com'>Plugins Registry</a></li>
129 <li class='divider'></li>
678348 130 <li><a href='http://dl.bintray.com/gitblit/releases/manager-1.7.1.zip'>Gitblit Manager</a></li>
M 131 <li><a href='http://dl.bintray.com/gitblit/releases/fedclient-1.7.1.zip'>Federation Client</a></li>
48fe87 132 <li class='divider'></li>
678348 133 <li><a href='http://dl.bintray.com/gitblit/releases/gbapi-1.7.1.zip'>API Library</a></li>
48fe87 134 <li class='divider'></li>
M 135 <li><a href='https://bintray.com/gitblit/releases/gitblit'>Bintray (1.4.0+)</a></li>
136 <li><a href='https://code.google.com/p/gitblit/downloads/list?can=1'>GoogleCode (pre-1.4.0)</a></li>
137 <li class='divider'></li>
138 <li><a href='http://gitblit.github.io/gitblit-maven'>Maven Repository</a></li>
139 </ul></li> <!-- End Menu -->
140 <li class='dropdown'> <!-- Menu -->
141 <a class='dropdown-toggle' href='#' data-toggle='dropdown'>links<b class='caret'></b></a>
142 <ul class='dropdown-menu'>
143 <li><a href='https://dev.gitblit.com'>dev.gitblit.com (self-hosted)</a></li>
144 <li class='divider'></li>
145 <li><a href='http://plugins.gitblit.com'>Plugins Registry</a></li>
146 <li class='divider'></li>
147 <li><a href='https://github.com/gitblit/gitblit'>Github</a></li>
5287d2 148 <li><a href='https://github.com/gitblit/gitblit'>Issues</a></li>
48fe87 149 <li><a href='http://groups.google.com/group/gitblit'>Discussion</a></li>
M 150 <li><a href='https://twitter.com/gitblit'>Twitter</a></li>
151 <li><a href='http://www.ohloh.net/p/gitblit'>Ohloh</a></li>
584328 152 <li class='divider'></li>
M 153 <li><a href='https://vimeo.com/86164723'>Gitblit Tickets screencast</a></li>
154 <li><a href='https://asciinema.org/a/9342'>Gitblit SSH and Plugin Management asciicast</a></li>
155 <li><a href='http://episodes.gitminutes.com/2014/05/gitminutes-29-james-moger-on-gitblit.html'>GitMinutes #29: James Moger on Gitblit</a></li>
48fe87 156 <li class='divider'></li>
M 157 <li><a href='https://twitter.com/JamesMoger'>@JamesMoger</a></li>
158 </ul></li> <!-- End Menu -->
159 <li class='divider-vertical'></li>
160 <li><a href='https://plus.google.com/114464678392593421684?prsrc=3' class='gpluspage'><img src='https://ssl.gstatic.com/images/icons/gplus-16.png' width='16' height='16 style='order: 0;'/></a></li><li><div class='gplusone'><g:plusone size='small' href='http://gitblit.com'></g:plusone></div></li>
161                         </ul>
162                     </div><!--/.nav-collapse -->
163                 </div>
164             </div>
165         </div><!-- end Navigation Bar -->
166 <div class='container'>
167 <!-- Begin Markdown -->
168 <h2 class="section" id='H1'><a href="#H1" class="sectionlink"><i class="icon-share-alt"> </i></a>Gitblit Configuration</h2>
169 <h3 class="section" id='H2'><a href="#H2" class="sectionlink"><i class="icon-share-alt"> </i></a>Administering Repositories</h3><p>Repositories can be created, edited, renamed, and deleted through the web UI. They may also be created, edited, and deleted from the command-line using real <a href="http://git-scm.com">Git</a> or your favorite file manager and text editor.</p><p>All repository settings are stored within the repository <code>.git/config</code> file under the <em>gitblit</em> section.</p>
170 <pre><code>[gitblit]
171     description = master repository
172     owner = james
173     useTickets = false
174     useDocs = true
175     showRemoteBranches = false
176     accessRestriction = clone
177     isFrozen = false
178     showReadme = false
179     federationStrategy = FEDERATE_THIS
180     isFederated = false
181     skipSizeCalculation = false
182     federationSets = 
183 </code></pre>
184 <h4 class="section" id='H3'><a href="#H3" class="sectionlink"><i class="icon-share-alt"> </i></a>Repository Names</h4><p>Repository names must be case-insensitive-unique but are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or <code>/ _ - . ~ +</code><br/><br/>Whitespace is illegal.</p><p>Repositories can be grouped within subfolders. e.g. <em>libraries/mycoollib.git</em> and <em>libraries/myotherlib.git</em></p><p>All repositories created with Gitblit are <em>bare</em> and will automatically have <em>.git</em> appended to the name at creation time, if not already specified. </p>
185 <h4 class="section" id='H4'><a href="#H4" class="sectionlink"><i class="icon-share-alt"> </i></a>Repository Owner</h4><p>The <em>Repository Owner</em> 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.</p>
186 <h3 class="section" id='H5'><a href="#H5" class="sectionlink"><i class="icon-share-alt"> </i></a>Access Restrictions and Access Permissions</h3><p><img src="permissions_matrix.png"  alt="permissions matrix"/></p>
187 <h4 class="section" id='H6'><a href="#H6" class="sectionlink"><i class="icon-share-alt"> </i></a>Discrete Permissions (Gitblit v1.2.0+)</h4><p>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:</p>
188 <ul>
189   <li><strong>V</strong> (view in web ui, RSS feeds, download zip)</li>
190   <li><strong>R</strong> (clone)</li>
191   <li><strong>RW</strong> (clone and push)</li>
192   <li><strong>RWC</strong> (clone and push with ref creation)</li>
193   <li><strong>RWD</strong> (clone and push with ref creation, deletion)</li>
194   <li><strong>RW+</strong> (clone and push with ref creation, deletion, rewind)</li>
195 </ul><p>These permission codes are combined with the repository path to create a user permission:</p>
196 <pre><code>RW:mygroup/myrepo.git
197 </code></pre><p><strong>NOTE:</strong><br/>The following repository permissions are equivalent:</p>
198 <ul>
199   <li>myrepo.git</li>
200   <li>RW+:myrepo.git</li>
201 </ul><p>This is to preserve backwards-compatibility with Gitblit &lt;= 1.1.0 which granted rewind power to all access-permitted users.</p>
202 <h4 class="section" id='H7'><a href="#H7" class="sectionlink"><i class="icon-share-alt"> </i></a>Discrete Permissions with Regex Matching (Gitblit v1.2.0+)</h4><p>Gitblit also supports <em>case-insensitive</em> regex matching for repository permissions. The following permission grants push privileges to all repositories in the <em>mygroup</em> folder.</p>
203 <pre><code>RW:mygroup/.*
204 </code></pre>
205 <h5 class="section" id='H8'><a href="#H8" class="sectionlink"><i class="icon-share-alt"> </i></a>Exclusions</h5><p>When using regex matching it may also be useful to exclude specific repositories or to exclude regex repository matches. You may specify the <strong>X</strong> permission for exclusion. The following example grants clone permission to all repositories except the repositories in mygroup. The user/team will have no access whatsoever to these repositories.</p>
206 <pre><code>X:mygroup/.*
207 R:.*
208 </code></pre>
209 <h5 class="section" id='H9'><a href="#H9" class="sectionlink"><i class="icon-share-alt"> </i></a>Order is Important</h5><p>The preceding example should suggest that order of permissions is important with regex matching. Here are the rules for determining the permission that is applied to a repository request:</p>
210 <ol>
211   <li>If the user is an admin or repository owner, then RW+</li>
212   <li>Else if user has an explicit permission, use that</li>
213   <li>Else check for the first regex match in user permissions</li>
214   <li>Else check for the HIGHEST permission from team memberships
215   <ol>
216     <li>If the team is an admin team, then RW+</li>
217     <li>Else if a team has an explicit permission, use that</li>
218     <li>Else check for the first regex match in team permissions</li>
219   </ol></li>
220 </ol>
221 <h4 class="section" id='H10'><a href="#H10" class="sectionlink"><i class="icon-share-alt"> </i></a>No-So-Discrete Permissions (Gitblit &lt;= v1.1.0)</h4><p>Prior to v1.2.0, Gitblit has two main access permission groupings: </p>
222 <ol>
223   <li>what you are permitted to do as an anonymous user</li>
224   <li><strong>RW+</strong> for any permitted user</li>
225 </ol>
226 <h4 class="section" id='H11'><a href="#H11" class="sectionlink"><i class="icon-share-alt"> </i></a>Committer Verification</h4><p>You may optionally enable committer verification which requires that each commit be committed by the authenticated user pushing the commits. i.e. If Bob is pushing the commits, Bob <strong>must</strong> be the committer of those commits.</p><p><strong>How is this enforced?</strong></p><p>Bob must properly set his <em>user.name</em> and <em>user.email</em> values for the repository to match his Gitblit user account <strong>BEFORE</strong> committing to his repository.</p><p><pre>[user &quot;bob&quot;]
227     displayName = Bob Jones
228     emailAddress = bob@somewhere.com
229 </pre></p>
230 <pre><code>git config user.name &quot;Bob Jones&quot;
231 git config user.email bob@somewhere.com 
232 </code></pre><p>or</p>
233 <pre><code>git config user.name bob
234 git config user.email bob@somewhere.com 
235 </code></pre><p>The committer email address is required to be identical. Display name or username can be used as the committer name.</p><p>All checks are case-insensitive.</p><p><strong>What about merges?</strong></p><p>You can not use fast-forward merges on your client when using committer verification. You must specify <em>--no-ff</em> to ensure that a merge commit is created with your identity as the committer. Only the first/left parent chain is traversed when verifying commits.</p>
236 <h4 class="section" id='H12'><a href="#H12" class="sectionlink"><i class="icon-share-alt"> </i></a>Reflog</h4><p>Gitblit v1.2.1 introduced an incomplete reflog mechanism which was completed in 1.3.0. All pushes to Gitblit are automatically logged on an orphan branch, <code>refs/meta/gitblit/reflog</code>. If this ref exists, the reflog page link will be displayed on the repository pages.</p><p>This reflog is similar to, but not the same as, the normal Git reflog. The Gitblit reflog links Gitblit accounts to ref changes and because it is stored on an orphan branch, the reflog is portable by the federation mechanism or by a normal <code>git clone --mirror</code> command.</p>
237 <h3 class="section" id='H13'><a href="#H13" class="sectionlink"><i class="icon-share-alt"> </i></a>Teams</h3><p>Teams have assigned users and assigned repositories. A user can be a member of multiple teams and a repository may belong to multiple teams. This allows the administrator to quickly add a user to a team without having to keep track of all the appropriate repositories. </p>
238 <h3 class="section" id='H14'><a href="#H14" class="sectionlink"><i class="icon-share-alt"> </i></a>Administering Users</h3><p>All users and permissions are stored in the <code>users.conf</code> file. Your file extension must be <em>.conf</em> in order to use this user service.</p><p>The <code>users.conf</code> file uses a Git-style configuration format:</p>
239 <pre><code>[user &quot;admin&quot;]
240     password = admin
241     role = &quot;#admin&quot;
242     role = &quot;#notfederated&quot;
243     repository = RW+:repo1.git
244     repository = RW+:repo2.git
245
246 [user &quot;hannibal&quot;]
247     password = bossman
248     repository = RWD:topsecret.git
249     repository = RW+:ateam/[A-Za-z0-9-~_\\./]+
250
251 [user &quot;faceman&quot;]
252     password = vanity
253
254 [user &quot;murdock&quot;]
255     password = crazy     
256
257 [user &quot;babaracus&quot;]
258     password = grrrr
259
260 [team &quot;ateam&quot;]
261     user = hannibal
262     user = faceman
263     user = murdock
264     user = babaracus
265     repository = RW:topsecret.git
266     mailingList = list@ateam.org
267     postReceiveScript = sendmail
268 </code></pre><p>The <code>users.conf</code> file allows flexibility for adding new fields to a UserModel object without imposing the complexity of relying on an embedded SQL database. </p>
269 <h3 class="section" id='H15'><a href="#H15" class="sectionlink"><i class="icon-share-alt"> </i></a>Usernames</h3><p>Usernames must be unique and are case-insensitive.<br/>Whitespace is illegal.</p>
270 <h3 class="section" id='H16'><a href="#H16" class="sectionlink"><i class="icon-share-alt"> </i></a>Passwords</h3><p>User passwords are CASE-SENSITIVE and may be <em>plain</em>, <em>md5</em>, or <em>combined-md5</em> formatted (see <code>gitblit.properties</code> -&gt; <em>realm.passwordStorage</em>).</p>
271 <h3 class="section" id='H17'><a href="#H17" class="sectionlink"><i class="icon-share-alt"> </i></a>User Roles</h3><p>There are four actual <em>roles</em> in Gitblit:</p>
272 <ul>
273   <li><em>#admin</em>, which grants administrative powers to that user for all repositories, users, and teams</li>
274   <li><em>#notfederated</em>, which prevents an account from being pulled by another Gitblit instance</li>
275   <li><em>#create</em>, which allows the user the power to create personal repositories</li>
276   <li><em>#fork</em>, which allows the user to create a personal fork of an existing Gitblit-hosted repository</li>
277 </ul>
278 <h3 class="section" id='H18'><a href="#H18" class="sectionlink"><i class="icon-share-alt"> </i></a>Personal Repositories & Forks</h3><p>Personal Repositories and Forks are related but are controlled individually.</p>
279 <h4 class="section" id='H19'><a href="#H19" class="sectionlink"><i class="icon-share-alt"> </i></a>Creating a Personal Repository</h4><p>A user may be granted the power to create personal repositories by specifying the <em>#create</em> 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.</p>
280 <h4 class="section" id='H20'><a href="#H20" class="sectionlink"><i class="icon-share-alt"> </i></a>Creating a Fork</h4><p>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 <em>#fork</em> role through the web ui or via the Gitblit Manager.</p><p>Forks are mostly likely personal repositories or common/shared repositories except for two important differences:</p>
281 <ol>
282   <li>Forks inherit a view/clone access list from the origin repository.<br/>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.</li>
283   <li>Forks are always listed in the fork network, regardless of any access restriction set on the fork.<br/>In other words, if you fork <em>RepoA.git</em> to <em>~me/RepoA.git</em> and then set the access restriction of <em>~me/RepoA.git</em> to <em>Authenticated View, Clone, &amp; Push</em> your fork will still be listed in the fork network for <em>RepoA.git</em>.</li>
284 </ol><p>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.
285 <!-- End Markdown -->
678348 286 <div ><ul class="pager"> <li class="next"><a href="setup_authentication.html">authentication &rarr;</a></li></ul></div><footer class="footer"><p class="pull-right">generated 2015-11-23</p>
48fe87 287 <p>The content of this page is licensed under the <a href="http://creativecommons.org/licenses/by/3.0">Creative Commons Attribution 3.0 License</a>.</p>
M 288 </footer>
289 </div>
290 <!-- Google Analytics -->
291 <script type="text/javascript">
292     var _gaq = _gaq || [];
293     _gaq.push(['_setAccount', 'UA-24377072-1']);
294     _gaq.push(['_trackPageview']);
295
296     (function() {
297         var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
298         ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
299         var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
300     })();
301 </script>
302
303 </body>
304 </html>