clone.sh/update.sh: abort early if baseurl is bad
[girocco.git] / html / mob.html
1 @section=site guide
2 @heading=About the Mob Account
3 @header
4
5 <!-- This file is preprocessed by cgi/html.cgi -->
6
7
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>
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
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>
34
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>
38
39 <h2>For Users</h2>
40
41 <p>After cloning the repository, do <code>git checkout mob</code> to move to the
42 <tt>mob</tt> branch.</p>
43
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
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>
53
54 <h2>Personal Mob Branches</h2>
55
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>
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
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>
64
65 <p>Also note that changes to any refs in the personal mob area will not generate
66 any 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>
71 <li>Multiple refs located under <tt>mob_username/</tt></li>
72 </ol>
73
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>
79
80 <p>More details and examples may be found below <a href="#personalmob">here</a>
81 and <a href="#personalmobclone">here</a>.</p>
82
83 <h2>In Detail Examples</h2>
84
85 @@ifssh@@
86 <h3>Pushing to the global mob branch with ssh</h3>
87
88 <p>Nothing special is needed except to remember to set the mob user name in the push url:</p>
89
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>
100
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@@
104
105 @@ifhttps@@
106 <h3 id="httpsmobpush">Pushing to the global mob branch with https</h3>
107
108 <p>In order to push with https, several things will be needed first:</p>
109
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>
118
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>
125
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>
135
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>
138
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>
152
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>
158
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@@
166
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>
176 # assume that $HOME/.ssh/config has been set up to automatically provide
177 # the ssh key for user alice when pushing to example.com
178
179 git clone ssh://example.com/someproject.git
180 cd someproject
181
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>
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
196 git clone https://example.com/someproject.git
197 cd someproject
198
199 # this is the multiple personal mob ref technique
200 git checkout -b mob_bob/master
201 git 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
207 the 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>
212 a 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
215 areas, merge them and then push them to user eve&#x2019;s personal mob area.</p>
216
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 example.com
220 git clone -n ssh://example.com/someproject.git
221 cd someproject
222
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.
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
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/*'
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
239 git fetch
240
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>
248
249 <p>Not so difficult, but a little bit of extra work to clone from a personal
250 mob area.</p>
251
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>