[girocco.git] / html / mob.html
1 @section=site guide
2 @heading=About the Mob Account
3 @header
5 <!-- This file is preprocessed by cgi/html.cgi -->
8 <p>The <tt>mob</tt> account (the name a tribute to the paper
9 <a href="">Mob Software: The Erotic Life of Code</a>)
10 is.a way to enable <em>anonymous push access</em> for your project.
11 This is largely an experiment and may be scrapped in the future if
12 it will not get widespread use, but we think it's an interesting try.
13 The idea is to provide unmoderated <em>side</em> channel for random
14 contributors to work on a project, with similar rationale as
15 e.g. Wikipedia - that given enough interested people, the quality
16 will grow rapidly and occassional "vandalism" will get fixed quickly.
17 Of course this may not work nearly as well for software, but here
18 we are, to give it a try.</p>
20 <h2>For Repository Admins</h2>
22 <p>How it works? First, you need to add the <tt>mob</tt> user to the
23 list of users allowed to push in your project. <tt>mob</tt> is a
24 keyless, passwordless user that anyone can use to push, without
25 any special setup. <strong>But</strong> this does not mean that
26 your project is now in the hands of raging mindless mob! The <tt>mob</tt>
27 user 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
29 is to create a <tt>mob</tt> branch in the repository (e.g.
30 <code>git checkout -b mob
31 &amp;&amp; git push origin mob</code>). Then the <tt>mob</tt> user
32 will be able to push to this and only this branch, and it won't be
33 able to push whatsoever until you take the second step.</p>
35 <p>To sum it up: Anonymous pushes are allowed <em>only</em> to the <tt>mob</tt>
36 branch and <em>only</em> if you add a <tt>mob</tt> user and do an initial
37 pushout of the <tt>mob</tt> branch.</p>
39 <h2>For Users</h2>
41 <p>After cloning the repository, do <code>git checkout mob</code> to move to the
42 <tt>mob</tt> branch.</p>
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>
48 <h2>For Developers</h2>
50 <p>Just commit on the <tt>mob</tt> branch you've checked out and
51 <code>git push</code> when the time is ripe.
52 Have fun and enjoy, you are making the history!</p>
54 <h2>Personal Mob Branches</h2>
56 <p>If the mob user has push permission to a project, but your user does not,
57 then 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>
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
62 global mob branch. The refs in the personal mob area need not be created first
63 to be used and may also be freely deleted by the user.</p>
65 <p>Also note that changes to any refs in the personal mob area will not generate
66 any email notifications.</p>
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>
71 <li>Multiple refs located under <tt>mob_username/</tt></li>
72 </ol>
74 <p>As a convenience to personal mob ref users who do not also have general push
75 permission 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
78 branches to the personal mob area.</p>
80 <p>More details and examples may be found below <a href="#personalmob">here</a>
81 and <a href="#personalmobclone">here</a>.</p>
83 <h2>In Detail Examples</h2>
85 @@ifssh@@
86 <h3>Pushing to the global mob branch with ssh</h3>
88 <p>Nothing special is needed except to remember to set the mob user name in the push url:</p>
90 <blockquote><pre>
91 cd /tmp
92 git clone -b mob @@gitpullurl@@/mobexample.git
93 cd mobexample
94 git remote set-url --push origin @@mobpushurl@@/mobexample.git
95 echo 'It worked!' >> example.txt
96 git add example.txt
97 git commit -m 'example commit'
98 git push origin mob
99 </pre></blockquote>
101 <p>Note that it&#x2019;s not strictly necessary to fetch with the git protocol,
102 the ssh protocol can also be used for fetching.</p>
103 @@end@@
105 @@ifhttps@@
106 <h3 id="httpsmobpush">Pushing to the global mob branch with https</h3>
108 <p>In order to push with https, several things will be needed first:</p>
110 <ol>
111 <li>The @@nickname@@ root certificate
112 <p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">here</a>
113 and will be assumed to be saved to <tt>/tmp/@@nickname@@_root_cert.pem</tt> in the push example.
114 See also the <a href="@@path(htmlurl)@@/rootcert.html">Root Certificate Information</a>.</p>
115 <pre>
116 cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_root_cert.pem
117 </pre></li>
119 <li>The mob user certificate
120 <p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_user.pem">here</a>
121 and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_user.pem</tt> in the push example.</p>
122 <pre>
123 cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_user.pem
124 </pre></li>
126 <li>The mob user private key
127 <p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_key.pem">here</a>
128 and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_key.pem</tt> in the push example.
129 Normally, of course, private keys are never shared, but as described above, since everyone
130 is allowed to push to the mob branch the private key for the mob user must be shared with everyone.</p>
131 <pre>
132 cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_key.pem
133 </pre></li>
134 </ol>
136 <p>With the prerequisites out of the way, here&#x2019;s the mob ssh example
137 redone to use the smart http protocol:</p>
139 <blockquote><pre>
140 cd /tmp
141 git clone -b mob @@httppullurl@@/mobexample.git
142 cd mobexample
143 git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem
144 git config http.sslCert /tmp/@@nickname@@_mob_user.pem
145 git config http.sslKey /tmp/@@nickname@@_mob_key.pem
146 git remote set-url --push origin @@httpspushurl@@/mobexample.git
147 echo 'It worked!' >> example.txt
148 git add example.txt
149 git commit -m 'example commit'
150 git push origin mob
151 </pre>
153 <p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">If using git version
154 1.8.5 or later, the <tt>http.sslCAInfo</tt>, <tt>http.sslCert</tt> and <tt>http.sslKey</tt>
155 values can be set just once in the Git global configuration file so they apply only to
156 a 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>
159 <p>Note that it&#x2019;s not strictly necessary to fetch with the http protocol,
160 the https protocol can also be used for fetching. However, if using a version of Git
161 older than version 1.8.5, it can be a bother to get the two certificates and the key set
162 properly without a project-specific place to configure them yet (this is not a problem
163 with Git version 1.8.5 or later). See the output of <tt>git config help</tt> for
164 more information about configuring certificates and keys.</p>
165 @@end@@
167 <h3 id="personalmob">Pushing to the personal mob area</h3>
169 <p>Pushing should be configured as though your user had push permission to the project.</p>
171 <p>Any supported push URL may be used.</p>
173 <p>Here&#x2019;s a <tt>mob.$user</tt> example using the ssh protocol:</p>
175 <blockquote><pre>
176 # assume that $HOME/.ssh/config has been set up to automatically provide
177 # the ssh key for user alice when pushing to
179 git clone ssh://
180 cd someproject
182 # this is the single personal mob ref technique
183 git checkout -b mob.alice
184 git push -u origin mob.alice
185 </pre></blockquote>
187 <p>It&#x2019;s just that simple.</p>
189 <p>Here&#x2019;s a <tt>mob_$user/...</tt> ref example using the https protocol:</p>
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
196 git clone
197 cd someproject
199 # this is the multiple personal mob ref technique
200 git checkout -b mob_bob/master
201 git push -u origin mob_bob/master
203 # additional refs may be pushed to mob_bob/...
204 </pre></blockquote>
206 <p>Of course the ssh protocol can be used with the multiple ref technique and
207 the https protocol can be used with the single ref technique.</p>
209 <h3 id="personalmobclone">Cloning the personal mob area</h3>
211 <p>Since the personal mob area is intentionally sequestered under <tt>refs/mob/</tt>
212 a little extra work is needed to clone from a personal mob ref to start with.</p>
214 <p>This example will clone both user alice and user bob&#x2019;s personal mob
215 areas, merge them and then push them to user eve&#x2019;s personal mob area.</p>
217 <blockquote><pre>
218 # assume that $HOME/.ssh/config has been set up to automatically provide
219 # the ssh key for user eve when pushing to
220 git clone -n ssh://
221 cd someproject
223 # optionally we may first check which personal mob refs are available
224 git 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.
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
231 git config --add remote.origin.fetch '+refs/mob/mob.alice:refs/remotes/origin/mob.alice'
232 git config --add remote.origin.fetch '+refs/mob/mob_bob/*:refs/remotes/origin/mob_bob/*'
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/*'
238 # now fetch the new refs
239 git fetch
241 # merge mob.alice and mob_bob/master and push to mob.eve
242 git checkout mob.alice
243 git checkout mob_bob/master
244 git checkout -b mob.eve
245 git merge mob.alice
246 git push -u origin mob.eve
247 </pre></blockquote>
249 <p>Not so difficult, but a little bit of extra work to clone from a personal
250 mob area.</p>
252 <p>Of course a mirror clone would get everything under <tt>refs/mob/</tt> but that
253 would not be helpful since it would also be bare.</p>