Merge branch 'master' into rorcz
[girocco.git] / html / mob.html
Commit [+]AuthorDateLineData
ff3ee4c0
PB
Petr Baudis2008-07-24 13:04:11 +02001@section=site guide
2@heading=About the Mob Account
3@header
ea1b028e Petr Baudis2006-10-11 01:50:45 +02004
ff3ee4c0 Petr Baudis2008-07-24 13:04:11 +02005<!-- This file is preprocessed by cgi/html.cgi -->
ea1b028e
PB
Petr Baudis2006-10-11 01:50:45 +02006
7
b9150dc7
PB
Petr Baudis2006-10-10 03:58:14 +02008<p>The <tt>mob</tt> account (the name a tribute to the paper
9<a href="http://www.dreamsongs.com/MobSoftware.html">Mob Software: The Erotic Life of Code</a>)
10is.a way to enable <em>anonymous push access</em> for your project.
11This is largely an experiment and may be scrapped in the future if
bae5c8dd Petr Baudis2008-07-24 12:33:08 +020012it will not get widespread use, but we think it's an interesting try.
b9150dc7 Petr Baudis2006-10-10 03:58:14 +020013The idea is to provide unmoderated <em>side</em> channel for random
bae5c8dd Petr Baudis2008-07-24 12:33:08 +020014contributors to work on a project, with similar rationale as
b9150dc7
PB
Petr Baudis2006-10-10 03:58:14 +020015e.g. Wikipedia - that given enough interested people, the quality
16will grow rapidly and occassional "vandalism" will get fixed quickly.
bae5c8dd Petr Baudis2008-07-24 12:33:08 +020017Of course this may not work nearly as well for software, but here
b9150dc7
PB
Petr Baudis2006-10-10 03:58:14 +020018we are, to give it a try.</p>
19
20<h2>For Repository Admins</h2>
21
22<p>How it works? First, you need to add the <tt>mob</tt> user to the
23list of users allowed to push in your project. <tt>mob</tt> is a
24keyless, passwordless user that anyone can use to push, without
25any special setup. <strong>But</strong> this does not mean that
32ce18db Petr Baudis2007-08-21 10:42:48 +020026your project is now in the hands of raging mindless mob! The <tt>mob</tt>
b9150dc7
PB
Petr Baudis2006-10-10 03:58:14 +020027user has a special restriction: it can push only to an existing
28<tt>mob</tt> branch. This means that the second step you need to take
29is to create a <tt>mob</tt> branch in the repository (e.g.
32ce18db
PB
Petr Baudis2007-08-21 10:42:48 +020030<code>git checkout -b mob
31 &amp;&amp; git push origin mob</code>). Then the <tt>mob</tt> user
bae5c8dd Petr Baudis2008-07-24 12:33:08 +020032will be able to push to this and only this branch, and it won't be
b9150dc7
PB
Petr Baudis2006-10-10 03:58:14 +020033able to push whatsoever until you take the second step.</p>
34
35<p>To sum it up: Anonymous pushes are allowed <em>only</em> to the <tt>mob</tt>
36branch and <em>only</em> if you add a <tt>mob</tt> user and do an initial
37pushout of the <tt>mob</tt> branch.</p>
38
39<h2>For Users</h2>
40
32ce18db
PB
Petr Baudis2007-08-21 10:42:48 +020041<p>After cloning the repository, do <code>git checkout mob</code> to move to the
42<tt>mob</tt> branch.</p>
b9150dc7
PB
Petr Baudis2006-10-10 03:58:14 +020043
44<p><strong>Note that you are taking a huge security risk on yourself
45 if you just blindly grab the mob branch and run it on your
46 system.</strong></p>
47
48<h2>For Developers</h2>
49
bae5c8dd
PB
Petr Baudis2008-07-24 12:33:08 +020050<p>Just commit on the <tt>mob</tt> branch you've checked out and
51<code>git push</code> when the time is ripe.
52Have fun and enjoy, you are making the history!</p>
4c9aedc8 Kyle J. McKay2013-06-19 10:27:48 -070053
a81bec60
KM
Kyle J. McKay2013-07-02 06:36:36 -070054<h2>Personal Mob Branches</h2>
55
56<p>If the mob user has push permission to a project, but your user does not,
57then you may push to a personal mob area. You must <a href="/reguser.cgi"
58>Register user</a> in order to use the personal mob area.</p>
59
60<p>This personal mob area is kept under <tt>refs/mob/mob.username</tt> and
61<tt>refs/mob/mob_username/</tt> and coexists independently with the single
62global mob branch. The refs in the personal mob area need not be created first
63to be used and may also be freely deleted by the user.</p>
64
65<p>Also note that changes to any refs in the personal mob area will not generate
66any email notifications (but JSON/CIA notifications will still happen).</p>
67
68<p>There are two possible ways to use the personal mob area:</p>
69<ol>
70<li>A single ref like <tt>mob.username</tt> or</li>
d8a9c9b3 Kyle J. McKay2013-11-30 17:58:15 -080071<li>Multiple refs located under <tt>mob_username/</tt></li>
a81bec60
KM
Kyle J. McKay2013-07-02 06:36:36 -070072</ol>
73
74<p>As a convenience to personal mob ref users who do not also have general push
75permission for a project, pushes to <tt>refs/heads/mob.username</tt> and
76<tt>refs/heads/mob_username/*</tt> are automatically mapped to the corresponding
77<tt>refs/mob/mob...</tt> location which makes it somewhat easier to push
78branches to the personal mob area.</p>
79
80<p>More details and examples may be found below <a href="#personalmob">here</a>
81and <a href="#personalmobclone">here</a>.</p>
82
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -070083<h2>In Detail Examples</h2>
84
85@@ifssh@@
a81bec60 Kyle J. McKay2013-07-02 06:36:36 -070086<h3>Pushing to the global mob branch with ssh</h3>
4c9aedc8 Kyle J. McKay2013-06-19 10:27:48 -070087
825d078e Kyle J. McKay2013-07-10 21:28:35 -070088<p>Nothing special is needed except to remember to set the mob user name in the push url:</p>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -070089
90<blockquote><pre>
91cd /tmp
92git clone -b mob @@gitpullurl@@/mobexample.git
93cd mobexample
94git remote set-url --push origin @@mobpushurl@@/mobexample.git
95echo 'It worked!' >> example.txt
96git add example.txt
97git commit -m 'example commit'
98git push origin mob
99</pre></blockquote>
100
e9149022
KM
Kyle J. McKay2013-07-05 21:50:10 -0700101<p>Note that it&#x2019;s not strictly necessary to fetch with the git protocol,
102the ssh protocol can also be used for fetching.</p>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -0700103@@end@@
104
105@@ifhttps@@
a81bec60 Kyle J. McKay2013-07-02 06:36:36 -0700106<h3 id="httpsmobpush">Pushing to the global mob branch with https</h3>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -0700107
108<p>In order to push with https, several things will be needed first:</p>
109
110<ol>
111<li>The @@nickname@@ root certificate
e9149022
KM
Kyle J. McKay2013-07-05 21:50:10 -0700112<p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">here</a>
113and will be assumed to be saved to <tt>/tmp/@@nickname@@_root_cert.pem</tt> in the push example.
114See also the <a href="@@path(htmlurl)@@/rootcert.html">Root Certificate Information</a>.</p>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -0700115<pre>
116cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_root_cert.pem
117</pre></li>
118
119<li>The mob user certificate
e9149022
KM
Kyle J. McKay2013-07-05 21:50:10 -0700120<p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_user.pem">here</a>
121and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_user.pem</tt> in the push example.</p>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -0700122<pre>
123cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_user.pem
124</pre></li>
125
126<li>The mob user private key
e9149022
KM
Kyle J. McKay2013-07-05 21:50:10 -0700127<p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_key.pem">here</a>
128and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_key.pem</tt> in the push example.
129Normally, of course, private keys are never shared, but as described above, since everyone
130is allowed to push to the mob branch the private key for the mob user must be shared with everyone.</p>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -0700131<pre>
132cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_key.pem
133</pre></li>
134</ol>
135
e9149022
KM
Kyle J. McKay2013-07-05 21:50:10 -0700136<p>With the prerequisites out of the way, here&#x2019;s the mob ssh example
137redone to use the smart http protocol:</p>
4c9aedc8
KM
Kyle J. McKay2013-06-19 10:27:48 -0700138
139<blockquote><pre>
140cd /tmp
141git clone -b mob @@httppullurl@@/mobexample.git
142cd mobexample
143git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem
144git config http.sslCert /tmp/@@nickname@@_mob_user.pem
145git config http.sslKey /tmp/@@nickname@@_mob_key.pem
146git remote set-url --push origin @@httpspushurl@@/mobexample.git
147echo 'It worked!' >> example.txt
148git add example.txt
149git commit -m 'example commit'
150git push origin mob
d8a9c9b3
KM
Kyle J. McKay2013-11-30 17:58:15 -0800151</pre>
152
153<p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">If using git version
1541.8.5 or later, the <tt>http.sslCAInfo</tt>, <tt>http.sslCert</tt> and <tt>http.sslKey</tt>
155values can be set just once in the Git global configuration file so they apply only to
156a specific URL (such as <tt>@@base(httpspushurl)@@</tt>) as shown in the example
157<a href="@@path(htmlurl)@@/rootcert.html#git185">here</a>.</p></blockquote>
4c9aedc8 Kyle J. McKay2013-06-19 10:27:48 -0700158
e9149022 Kyle J. McKay2013-07-05 21:50:10 -0700159<p>Note that it&#x2019;s not strictly necessary to fetch with the http protocol,
d8a9c9b3
KM
Kyle J. McKay2013-11-30 17:58:15 -0800160the https protocol can also be used for fetching. However, if using a version of Git
161older than version 1.8.5, it can be a bother to get the two certificates and the key set
162properly without a project-specific place to configure them yet (this is not a problem
163with Git version 1.8.5 or later). See the output of <tt>git config help</tt> for
e9149022 Kyle J. McKay2013-07-05 21:50:10 -0700164more information about configuring certificates and keys.</p>
4c9aedc8 Kyle J. McKay2013-06-19 10:27:48 -0700165@@end@@
a81bec60
KM
Kyle J. McKay2013-07-02 06:36:36 -0700166
167<h3 id="personalmob">Pushing to the personal mob area</h3>
168
169<p>Pushing should be configured as though your user had push permission to the project.</p>
170
171<p>Any supported push URL may be used.</p>
172
173<p>Here&#x2019;s a <tt>mob.$user</tt> example using the ssh protocol:</p>
174
175<blockquote><pre>
d8a9c9b3 Kyle J. McKay2013-11-30 17:58:15 -0800176# assume that $HOME/.ssh/config has been set up to automatically provide
a81bec60
KM
Kyle J. McKay2013-07-02 06:36:36 -0700177# the ssh key for user alice when pushing to example.com
178
179git clone ssh://example.com/someproject.git
180cd someproject
181
182# this is the single personal mob ref technique
183git checkout -b mob.alice
184git push -u origin mob.alice
185</pre></blockquote>
186
187<p>It&#x2019;s just that simple.</p>
188
189<p>Here&#x2019;s a <tt>mob_$user/...</tt> ref example using the https protocol:</p>
190
191<blockquote><pre>
192# assume that git config http.sslCert and http.sslKey have been properly
193# set up to provide the user authentication certificate for user bob
194# when pushing to example.com
195
196git clone https://example.com/someproject.git
197cd someproject
198
199# this is the multiple personal mob ref technique
200git checkout -b mob_bob/master
201git push -u origin mob_bob/master
202
203# additional refs may be pushed to mob_bob/...
204</pre></blockquote>
205
206<p>Of course the ssh protocol can be used with the multiple ref technique and
207the https protocol can be used with the single ref technique.</p>
208
209<h3 id="personalmobclone">Cloning the personal mob area</h3>
210
211<p>Since the personal mob area is intentionally sequestered under <tt>refs/mob/</tt>
212a little extra work is needed to clone from a personal mob ref to start with.</p>
213
214<p>This example will clone both user alice and user bob&#x2019;s personal mob
215areas, merge them and then push them to user eve&#x2019;s personal mob area.</p>
216
217<blockquote><pre>
d8a9c9b3 Kyle J. McKay2013-11-30 17:58:15 -0800218# assume that $HOME/.ssh/config has been set up to automatically provide
a81bec60
KM
Kyle J. McKay2013-07-02 06:36:36 -0700219# the ssh key for user eve when pushing to example.com
220git clone -n ssh://example.com/someproject.git
221cd someproject
222
223# optionally we may first check which personal mob refs are available
224git ls-remote origin | grep 'refs/mob/'
225# we can see from the output that alice has a mob.alice branch and
226# and bob has a mob_bob/master branch.
227
228# since nothing under refs/mob is normally fetched we must add instructions
229# to fetch the personal mob area of both alice and bob being careful to
230# match the refs we need
231git config --add remote.origin.fetch '+refs/mob/mob.alice:refs/remotes/origin/mob.alice'
232git config --add remote.origin.fetch '+refs/mob/mob_bob/*:refs/remotes/origin/mob_bob/*'
233
234# alternatively, this mapping will just get every personal mob ref
235# but this is not really recommended
236#git config --add remote.origin.fetch '+refs/mob/*:refs/remotes/origin/*'
237
238# now fetch the new refs
239git fetch
240
241# merge mob.alice and mob_bob/master and push to mob.eve
242git checkout mob.alice
243git checkout mob_bob/master
244git checkout -b mob.eve
245git merge mob.alice
246git push -u origin mob.eve
247</pre></blockquote>
248
249<p>Not so difficult, but a little bit of extra work to clone from a personal
250mob area.</p>
251
252<p>Of course a mirror clone would get everything under <tt>refs/mob/</tt> but that
253would not be helpful since it would also be bare.</p>