[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="http://www.dreamsongs.com/MobSoftware.html">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 @@ifcustom@@
112 <li>The @@nickname@@ root certificate
113 <p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">here</a>
114 and will be assumed to be saved to <tt>/tmp/@@nickname@@_root_cert.pem</tt> in the push example.
115 See also the <a href="@@path(htmlurl)@@/rootcert.html">Root Certificate Information</a>.</p>
116 <pre>
117 cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_root_cert.pem
118 </pre></li>
119 @@end@@
121 <li>The mob user certificate
122 <p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_user.pem">here</a>
123 and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_user.pem</tt> in the push example.</p>
124 <pre>
125 cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_user.pem
126 </pre></li>
128 <li>The mob user private key
129 <p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_key.pem">here</a>
130 and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_key.pem</tt> in the push example.
131 Normally, of course, private keys are never shared, but as described above, since everyone
132 is allowed to push to the mob branch the private key for the mob user must be shared with everyone.</p>
133 <pre>
134 cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_key.pem
135 </pre></li>
136 </ol>
138 <p>With the prerequisites out of the way, here&#x2019;s the mob ssh example
139 redone to use the smart http protocol:</p>
141 <blockquote><pre>
142 cd /tmp
143 git clone -b mob @@httppullurl@@/mobexample.git
144 cd mobexample@@ifcustom@@
145 git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem@@end@@
146 git config http.sslCert /tmp/@@nickname@@_mob_user.pem
147 git config http.sslKey /tmp/@@nickname@@_mob_key.pem
148 git remote set-url --push origin @@httpspushurl@@/mobexample.git
149 echo 'It worked!' >> example.txt
150 git add example.txt
151 git commit -m 'example commit'
152 git push origin mob
153 </pre>
155 <p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">If using git version
156 1.8.5 or later, the @@ifcustom@@<tt>http.sslCAInfo</tt>, @@end@@<tt>http.sslCert</tt> and <tt>http.sslKey</tt>
157 values can be set just once in the Git global configuration file so they apply only to
158 a specific URL (such as <tt>@@base(httpspushurl)@@</tt>)@@ifcustom@@ as shown in the example
159 <a href="@@path(htmlurl)@@/rootcert.html#git185">here</a>@@end@@.</p></blockquote>
161 <p>Note that it&#x2019;s not strictly necessary to fetch with the http protocol,
162 the https protocol can also be used for fetching. However, if using a version of Git
163 older than version 1.8.5, it can be a bother to get the two certificates and the key set
164 properly without a project-specific place to configure them yet (this is not a problem
165 with Git version 1.8.5 or later). See the output of <tt>git config help</tt> for
166 more information about configuring certificates and keys.</p>
167 @@end@@
169 <h3 id="personalmob">Pushing to the personal mob area</h3>
171 <p>Pushing should be configured as though your user had push permission to the project.</p>
173 <p>Any supported push URL may be used.</p>
175 <p>Here&#x2019;s a <tt>mob.$user</tt> example using the ssh protocol:</p>
177 <blockquote><pre>
178 # assume that $HOME/.ssh/config has been set up to automatically provide
179 # the ssh key for user alice when pushing to example.com
181 git clone ssh://example.com/someproject.git
182 cd someproject
184 # this is the single personal mob ref technique
185 git checkout -b mob.alice
186 git push -u origin mob.alice
187 </pre></blockquote>
189 <p>It&#x2019;s just that simple.</p>
191 <p>Here&#x2019;s a <tt>mob_$user/...</tt> ref example using the https protocol:</p>
193 <blockquote><pre>
194 # assume that git config http.sslCert and http.sslKey have been properly
195 # set up to provide the user authentication certificate for user bob
196 # when pushing to example.com
198 git clone https://example.com/someproject.git
199 cd someproject
201 # this is the multiple personal mob ref technique
202 git checkout -b mob_bob/master
203 git push -u origin mob_bob/master
205 # additional refs may be pushed to mob_bob/...
206 </pre></blockquote>
208 <p>Of course the ssh protocol can be used with the multiple ref technique and
209 the https protocol can be used with the single ref technique.</p>
211 <h3 id="personalmobclone">Cloning the personal mob area</h3>
213 <p>Since the personal mob area is intentionally sequestered under <tt>refs/mob/</tt>
214 a little extra work is needed to clone from a personal mob ref to start with.</p>
216 <p>This example will clone both user alice and user bob&#x2019;s personal mob
217 areas, merge them and then push them to user eve&#x2019;s personal mob area.</p>
219 <blockquote><pre>
220 # assume that $HOME/.ssh/config has been set up to automatically provide
221 # the ssh key for user eve when pushing to example.com
222 git clone -n ssh://example.com/someproject.git
223 cd someproject
225 # optionally we may first check which personal mob refs are available
226 git ls-remote origin | grep 'refs/mob/'
227 # we can see from the output that alice has a mob.alice branch and
228 # and bob has a mob_bob/master branch.
230 # since nothing under refs/mob is normally fetched we must add instructions
231 # to fetch the personal mob area of both alice and bob being careful to
232 # match the refs we need
233 git config --add remote.origin.fetch '+refs/mob/mob.alice:refs/remotes/origin/mob.alice'
234 git config --add remote.origin.fetch '+refs/mob/mob_bob/*:refs/remotes/origin/mob_bob/*'
236 # alternatively, this mapping will just get every personal mob ref
237 # but this is not really recommended
238 #git config --add remote.origin.fetch '+refs/mob/*:refs/remotes/origin/*'
240 # now fetch the new refs
241 git fetch
243 # merge mob.alice and mob_bob/master and push to mob.eve
244 git checkout mob.alice
245 git checkout mob_bob/master
246 git checkout -b mob.eve
247 git merge mob.alice
248 git push -u origin mob.eve
249 </pre></blockquote>
251 <p>Not so difficult, but a little bit of extra work to clone from a personal
252 mob area.</p>
254 <p>Of course a mirror clone would get everything under <tt>refs/mob/</tt> but that
255 would not be helpful since it would also be bare.</p>