Blob


1 <!doctype html>
2 <html lang=en>
3 <meta charset=utf-8>
5 <title>Game of Trees (Got): Examples</title>
6 <meta name="description" content="Game of Trees (Got) Examples">
7 <meta name="viewport" content="width=device-width, initial-scale=1">
8 <link rel="stylesheet" type="text/css" href="openbsd.css">
9 <link rel="canonical" href="https://gameoftrees.org/examples.html">
11 <h2>
12 <a href="index.html">
13 <i>Game of Trees</i></a>
14 Examples
15 </h2>
16 <hr>
18 <p id="callout">
19 <br>
20 These examples are supplemental documentation to the man pages, which are
21 available both in the installed system and
22 <a href="https://gameoftrees.org/manual.html">online</a>.
24 <h3>Quick Links:</h3>
26 <table>
27 <tr>
28 <a href="#amend" >Amending the latest commit</a><br>
29 <a href="#ports" >Using got(1) with ports tree</a>
30 </tr>
31 </table>
33 <p>
34 <hr>
36 <h2 id="amend"><a class="permalink" href="#rollback">Amending the latest commit</a></h2>
38 <p>
39 Sometimes a mistake is found in the latest commit on a branch.
40 This section explains how such a mistake can be corrected with Got.
42 <p>
43 As a first step, Got can create another commit which undoes the changes
44 made by the latest commit. Assuming a branch called <tt>master</tt>,
45 the latest commit on this branch can be identified by the same
46 name (<tt>master</tt>).
47 In a clean work tree according to <tt>got status</tt>, run:
48 <pre class="cmdbox">
49 $ <b>got backout master</b>
50 $ <b>got commit -m 'oops, roll back previous'</b>
51 </pre>
53 Using <tt>got backout</tt> a second time will now fetch the rolled-back
54 change into the work tree as a local change which can be amended:</p>
56 <pre class="cmdbox">
57 $ <b>got backout master</b>
58 (edit files)
59 $ <b>got commit -m 'fixed version of previous change'</b>
60 </pre>
62 The history of the tree latest commits on the branch would
63 now look something like this:
65 <pre class="cmdbox">
66 $ <b>got log -l 3</b>
67 -----------------------------------------------
68 commit bcb49d15e041ddffb59397d2fe851fdb1729b005 (master)
69 from: Flan Hacker &lt;flan_hacker@openbsd.org&gt;
70 date: Wed Aug 14 22:07:22 2038 UTC
72 fixed version of previous change
74 -----------------------------------------------
75 commit 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda
76 from: Flan Hacker &lt;flan_hacker@openbsd.org&gt;
77 date: Wed Aug 14 21:37:07 2038 UTC
79 oops, roll back previous
81 -----------------------------------------------
82 commit 7ef28ff8dd61cbf38f88784ea8c11e373757985f
83 from: Flan Hacker &lt;flan_hacker@openbsd.org&gt;
84 date: Wed Aug 14 21:10:00 2038 UTC
86 this is surely a great idea!
88 </pre>
90 <p>
91 If commit <tt>7ef28ff8dd61cbf38f88784ea8c11e373757985f</tt> has already
92 been copied to another repository, our story ends here because the history
93 must now be considered immutable.
95 <p>
96 Otherwise, the local branch history can be edited to cover up our little
97 mistake. First, find the ID of the parent commit of the bad commit:
99 <pre class="cmdbox">
100 $ <b>got log -l 4 | grep ^commit| tail -n 1</b>
101 commit e27a7222faaa171dcb086ea0b566dc7bebb74a0b (origin/master)
102 </pre>
104 <p>
105 Back-date the work tree to this commit and ask Got to edit the history
106 leading up to the latest commit on the branch:
108 <pre class="cmdbox">
109 $ <b>got update -c e27a7222fa</b>
110 $ <b>got histedit</b>
111 </pre>
113 <p>
114 The <tt>histedit</tt> command will open a histedit script in an editor:
116 <pre class="cmdbox">
117 # Available histedit commands:
118 # pick (p): use commit
119 # edit (e): use commit but stop for amending
120 # fold (f): combine with commit below
121 # drop (d): remove commit from history
122 # mesg (m): single-line log message for commit above (open editor if empty)
123 # Commits will be processed in order from top to bottom of this file.
124 pick 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
125 pick 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous
126 pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
127 </pre>
129 <p>
130 To make the mistaken commits disappear from history, the corresponding
131 lines can changed to execute <tt>drop</tt> commands, and the log message
132 of the latest commit can be changed to that of the original commit:
134 <pre class="cmdbox">
135 <b>drop</b> 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
136 <b>drop</b> 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous
137 pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
138 <b>mesg this is surely a great idea!</b>
139 </pre>
141 <p>
142 After saving the file and exiting the editor, Got will create a new
143 version of history which does not contain the mistake:
145 <pre class="cmdbox">
146 $ <b>got log -l 1</b>
147 -----------------------------------------------
148 commit 60b83404dd25547f19d9b468b931809541a3325c (master)
149 from: Flan Hacker &lt;flan_hacker@openbsd.org&gt;
150 date: Wed Aug 14 22:17:12 2038 UTC
152 this is surely a great idea!
154 </pre>
156 <p id="callout">CAVEAT:
157 <p>The <tt>mesg</tt> command of the histedit script only accepts a
158 single-line log message argument. Omit the argument to write a new
159 multi-line log message in an editor:
161 <pre class="cmdbox">
162 [...]
163 pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
164 <b>mesg</b>
165 </pre>
167 <h2 id="ports"><a class="permalink" href="#ports">Using got(1) with ports tree</a></h2>
169 Clone the ports repository from github. This step currently requires git(1):
170 <p></p>
171 <pre class="cmdbox">
172 $ <b>mkdir /var/git</b>
173 $ <b>cd /var/git</b>
174 $ <b>git clone --bare https://github.com/openbsd/ports.git</b>
175 </pre>
176 <p>We jump into ports.git directory and we create our new branch to work with (let's say
177 <tt>mystuff</tt>):
178 <p></p>
179 <pre class="cmdbox">
180 $ <b>cd ports.git</b>
181 $ <b>got branch mystuff</b>
182 </pre>
183 We check that the <tt>master</tt> and the new branch are in sync:
184 <p></p>
185 <pre class="cmdbox">
186 $ <b>got branch -l</b>
187 master: 05a7abcec81fc1865d1983314b6783680ab31f689
188 mystuff: 05a7abcec81fc1865d1983314b6783680ab31f689
189 </pre>
190 <p>Now we need to checkout the content inside our new branch <tt>mystuff</tt>
191 <p></p>
192 <pre class="cmdbox">
193 $ <b>cd /var/git</b>
194 $ <b>got checkout -b mystuff ports.git</b>
195 ...
196 A /var/git/ports/x11/yeahconsole/distinfo
197 A /var/git/ports/x11/yeahconsole/patches/patch-Makefile
198 A /var/git/ports/x11/yeahconsole/pkg/DESCR
199 A /var/git/ports/x11/yeahconsole/pkg/PLIST
200 A /var/git/ports/x11/yeahlaunch/Makefile
201 A /var/git/ports/x11/yeahlaunch/distinfo
202 A /var/git/ports/x11/yeahlaunch/patches/patch-yeahlaunch_c
203 A /var/git/ports/x11/yeahlaunch/pkg/DESCR
204 A /var/git/ports/x11/yeahlaunch/pkg/PLIST
205 Now shut up and hack
206 </pre>
207 <p>As <code>got</code> says, now shut up and hack:
208 <p></p>
209 <pre class="cmdbox">
210 $ <b>cd /var/git/ports</b>
211 $ <b>cd www/nextcloud</b>
212 $ <b>vim pkg/README</b>
213 </pre>
214 <p>So we changed the README file inside the Nextcloud port and we need to cook the diff:
215 <p></p>
216 <pre class="cmdbox">
217 $ <b>got diff</b>
218 diff 05a7abcec81fc1865d1983314b6783680ab31f689 /var/git/ports
219 blob - 47bfbdd7fa7aaf027971ac5c62db25dde75595d7
220 blob + 71d2df1463ae11c9b66403d401c16fff63382b2c
221 --- www/nextcloud/pkg/README
222 +++ www/nextcloud/pkg/README
223 @@ -96,12 +96,20 @@ server "domain.tld" {
224 block return 301 "$DOCUMENT_URI/index.php"
227 - location "/nextcloud/ocm-provider/" {
228 - block return 301 "$DOCUMENT_URI/index.php"
229 + location "/.well-known/carddav" {
230 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
233 - location "/nextcloud/ocs-provider/" {
234 - block return 301 "$DOCUMENT_URI/index.php"
235 + location "/.well-known/caldav" {
236 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
237 + }
239 + location "/.well-known/webfinger" {
240 + block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
241 + }
243 + location match "/nextcloud/oc[ms]%-provider/*" {
244 + directory index index.php
247 ---8<---------------------------------------------------------------------------
248 </pre>
249 <p>Time to commit those changes in our branch <tt>mystuff</tt>, so we can keep
250 track of our work:
251 <p></p>
252 <pre class="cmdbox">
253 $ <b>got commit -m "Add new examples for httpd(8) to shut up warnings"</b>
254 M www/nextcloud/pkg/README
255 Created commit 7848652ef6243db09841d449f346f21fc6386633
256 </pre>
257 <p>Paranoid? Probably yes, let's check again our diff against <tt>master</tt>:
258 <pre class="cmdbox">
259 $ <b>got diff master mystuff</b>
260 diff refs/heads/master refs/heads/mystuff
261 blob - 47bfbdd7fa7aaf027971ac5c62db25dde75595d7
262 file + www/nextcloud/pkg/README
263 --- www/nextcloud/pkg/README
264 +++ www/nextcloud/pkg/README
265 @@ -96,12 +96,20 @@ server "domain.tld" {
266 block return 301 "$DOCUMENT_URI/index.php"
269 - location "/nextcloud/ocm-provider/" {
270 - block return 301 "$DOCUMENT_URI/index.php"
271 + location "/.well-known/carddav" {
272 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
275 - location "/nextcloud/ocs-provider/" {
276 - block return 301 "$DOCUMENT_URI/index.php"
277 + location "/.well-known/caldav" {
278 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
279 + }
281 + location "/.well-known/webfinger" {
282 + block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
283 + }
285 + location match "/nextcloud/oc[ms]%-provider/*" {
286 + directory index index.php
289 ---8<---------------------------------------------------------------------------
290 </pre>
291 <p>Now, let's send that diff to ports@ for some OKs.
292 </p>
294 <p>Once the diff has been committed to CVS the same change will eventually show
295 up on github as well. Fetch incoming changes to the <tt>master</tt> branch
296 with:</p>
298 <pre class="cmdbox">
299 $ <b>cd /var/git/ports.git</b>
300 $ <b>git fetch origin master:master</b>
301 </pre>
303 <p>Next, rebase the <tt>mystuff</tt> branch onto the latest <tt>master</tt>:</p>
305 <pre class="cmdbox">
306 $ <b>cd /var/git/ports</b>
307 $ <b>got status</b>
308 (status should be clean; revert or commit local changes if needed)
309 $ <b>got update -b master</b>
310 $ <b>got rebase mystuff</b>
311 </pre>
313 <p>
314 Now we can shut up and hack again!
316 </body>
317 </html>