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">
13 <i>Game of Trees</i></a>
20 These examples are supplemental documentation to the man pages, which are
21 available both in the installed system and <a href="manual.html">online</a>.
22 A quick-start guide to <tt>got(1)</tt> is provided by the
23 <a href="got.1.html#EXAMPLES">examples listed in the manual page</a>.
29 <a href="#selective-commit" >Comitting changes selectively</a><br>
30 <a href="#amend" >Amending the latest commit</a><br>
31 <a href="#ports" >Using got(1) with the ports tree</a>
38 <h2 id="selective-commit"><a class="permalink" href="#selective-commit">Committing changes selectively</a></h2>
41 Working on a bug fix will often leave behind unrelated local changes,
42 such as temporary debug messages. This section explains how isolated parts
43 of local changes in a work tree can be committed in such situations.
46 Consider the following diff, which contains a workaround (disable MIMO)
47 for a fictional bug in the <tt>iwm(4)</tt> driver.
48 This workaround sits between two temporary debug messages:
52 diff a737ddea9a6b93fdcfad0176dad8d184b2e2138a /usr/src
53 blob - 335033d21091a23511403804f09d1548b109b104
54 file + sys/dev/pci/if_iwm.c
55 --- sys/dev/pci/if_iwm.c
56 +++ sys/dev/pci/if_iwm.c
57 @@ -4620,6 +4620,8 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
59 struct ieee80211com *ic = &sc->sc_ic;
61 + printf("%s: adding node for STA %s\n", __func__, ether_sprintf(in->in_ni.ni_macaddr));
63 if (!update && (sc->sc_flags & IWM_FLAG_STA_ACTIVE))
64 panic("STA already added");
66 @@ -4638,7 +4640,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
68 add_sta_cmd.add_modify = update ? 1 : 0;
69 add_sta_cmd.station_flags_msk
70 - |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
71 + |= htole32(IWM_STA_FLG_FAT_EN_MSK);
72 +#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
73 + add_sta_cmd.station_flags_msk
74 + |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
76 add_sta_cmd.tid_disable_tx = htole16(0xffff);
78 add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
79 @@ -4675,8 +4681,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
80 status = IWM_ADD_STA_SUCCESS;
81 err = iwm_send_cmd_pdu_status(sc, IWM_ADD_STA, sizeof(add_sta_cmd),
82 &add_sta_cmd, &status);
83 - if (err == 0 && status != IWM_ADD_STA_SUCCESS)
84 + if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
86 + printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
87 + add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
95 Got offers several ways of committing this workaround in isolation.
98 One possibility is to stage the desired change with <tt>got stage</tt>:
101 $ <b>got stage -p</b>
102 -----------------------------------------------
103 @@ -4620,6 +4620,8 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
105 struct ieee80211com *ic = &sc->sc_ic;
107 + printf("%s: adding node for STA %s\n", __func__, ether_sprintf(in->in_ni.ni_macaddr));
109 if (!update && (sc->sc_flags & IWM_FLAG_STA_ACTIVE))
110 panic("STA already added");
112 -----------------------------------------------
113 M sys/dev/pci/if_iwm.c (change 1 of 4)
114 stage this change? [y/n/q] <b>n</b>
115 -----------------------------------------------
116 @@ -4638,7 +4640,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
118 add_sta_cmd.add_modify = update ? 1 : 0;
119 add_sta_cmd.station_flags_msk
120 - |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
121 + |= htole32(IWM_STA_FLG_FAT_EN_MSK);
122 +#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
123 + add_sta_cmd.station_flags_msk
124 + |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
126 add_sta_cmd.tid_disable_tx = htole16(0xffff);
128 add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
129 -----------------------------------------------
130 M sys/dev/pci/if_iwm.c (change 2 of 4)
131 stage this change? [y/n/q] <b>y</b>
132 -----------------------------------------------
133 @@ -4675,7 +4681,7 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
134 status = IWM_ADD_STA_SUCCESS;
135 err = iwm_send_cmd_pdu_status(sc, IWM_ADD_STA, sizeof(add_sta_cmd),
136 &add_sta_cmd, &status);
137 - if (err == 0 && status != IWM_ADD_STA_SUCCESS)
138 + if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
140 printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
141 add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
142 -----------------------------------------------
143 M sys/dev/pci/if_iwm.c (change 3 of 4)
144 stage this change? [y/n/q] <b>q</b>
148 The staged change can be seen with <tt>got status</tt> and <tt>got diff</tt>:
152 MM sys/dev/pci/if_iwm.c
154 diff a737ddea9a6b93fdcfad0176dad8d184b2e2138a /usr/src (staged changes)
155 blob - 335033d21091a23511403804f09d1548b109b104
156 blob + 7ad0ed87af5ef451beba1224ca5186906881aba5
157 --- sys/dev/pci/if_iwm.c
158 +++ sys/dev/pci/if_iwm.c
159 @@ -4638,7 +4638,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
161 add_sta_cmd.add_modify = update ? 1 : 0;
162 add_sta_cmd.station_flags_msk
163 - |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
164 + |= htole32(IWM_STA_FLG_FAT_EN_MSK);
165 +#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
166 + add_sta_cmd.station_flags_msk
167 + |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
169 add_sta_cmd.tid_disable_tx = htole16(0xffff);
171 add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
176 The debug message changes are no longer necessary and can reverted:
178 $ <b>got revert sys/dev/pci/if_iwm.c</b>
179 R sys/dev/pci/if_iwm.c
181 M sys/dev/pci/if_iwm.c
184 To commit the staged change, run <tt>got commit</tt> as usual:
187 $ <b>got commit -m "disable MIMO for now to work around a crash reported on bugs@"</b>
191 A second possibility is to revert all debug message changes with
195 $ <b>got revert -p sys/dev/pci/if_iwm.c</b>
196 -----------------------------------------------
197 @@ -4620,6 +4620,8 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
199 struct ieee80211com *ic = &sc->sc_ic;
201 + printf("%s: adding node for STA %s\n", __func__, ether_sprintf(in->in_ni.ni_macaddr));
203 if (!update && (sc->sc_flags & IWM_FLAG_STA_ACTIVE))
204 panic("STA already added");
206 -----------------------------------------------
207 M sys/dev/pci/if_iwm.c (change 1 of 4)
208 revert this change? [y/n/q] <b>y</b>
209 -----------------------------------------------
210 @@ -4638,7 +4640,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
212 add_sta_cmd.add_modify = update ? 1 : 0;
213 add_sta_cmd.station_flags_msk
214 - |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
215 + |= htole32(IWM_STA_FLG_FAT_EN_MSK);
216 +#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
217 + add_sta_cmd.station_flags_msk
218 + |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
220 add_sta_cmd.tid_disable_tx = htole16(0xffff);
222 add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
223 -----------------------------------------------
224 M sys/dev/pci/if_iwm.c (change 2 of 4)
225 revert this change? [y/n/q] <b>n</b>
226 -----------------------------------------------
227 @@ -4675,7 +4681,7 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
228 status = IWM_ADD_STA_SUCCESS;
229 err = iwm_send_cmd_pdu_status(sc, IWM_ADD_STA, sizeof(add_sta_cmd),
230 &add_sta_cmd, &status);
231 - if (err == 0 && status != IWM_ADD_STA_SUCCESS)
232 + if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
234 printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
235 add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
236 -----------------------------------------------
237 M sys/dev/pci/if_iwm.c (change 3 of 4)
238 revert this change? [y/n/q] <b>y</b>
239 -----------------------------------------------
240 @@ -4677,6 +4683,9 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
241 &add_sta_cmd, &status);
242 if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
244 + printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
245 + add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
250 -----------------------------------------------
251 M sys/dev/pci/if_iwm.c (change 4 of 4)
252 revert this change? [y/n/q] <b>y</b>
256 This leaves us with the workaround as our only local change we can commit:
260 diff a737ddea9a6b93fdcfad0176dad8d184b2e2138a /usr/src
261 blob - 335033d21091a23511403804f09d1548b109b104
262 file + sys/dev/pci/if_iwm.c
263 --- sys/dev/pci/if_iwm.c
264 +++ sys/dev/pci/if_iwm.c
265 @@ -4638,7 +4638,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
267 add_sta_cmd.add_modify = update ? 1 : 0;
268 add_sta_cmd.station_flags_msk
269 - |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
270 + |= htole32(IWM_STA_FLG_FAT_EN_MSK);
271 +#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
272 + add_sta_cmd.station_flags_msk
273 + |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
275 add_sta_cmd.tid_disable_tx = htole16(0xffff);
277 add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
280 <h2 id="amend"><a class="permalink" href="#rollback">Amending the latest commit</a></h2>
283 Sometimes a mistake is found in the latest commit on a branch.
284 This section explains how such a mistake can be corrected with Got.
287 As a first step, Got can create another commit which undoes the changes
288 made by the latest commit. Assuming a branch called <tt>main</tt>,
289 the latest commit on this branch can be identified by the same
290 name (<tt>main</tt>).
291 In a clean work tree according to <tt>got status</tt>, run:
293 $ <b>got backout main</b>
294 $ <b>got commit -m 'oops, roll back previous change'</b>
297 Using <tt>got backout</tt> a second time will now fetch the rolled-back
298 change into the work tree as a local change which can be amended:</p>
301 $ <b>got backout main</b>
303 $ <b>got commit -m 'fixed version of previous change'</b>
306 The history of the three latest commits on the branch would
307 now look something like this:
310 $ <b>got log -l 3</b>
311 -----------------------------------------------
312 commit bcb49d15e041ddffb59397d2fe851fdb1729b005 (main)
313 from: Flan Hacker <flan_hacker@openbsd.org>
314 date: Wed Aug 14 22:07:22 2038 UTC
316 fixed version of previous change
318 -----------------------------------------------
319 commit 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda
320 from: Flan Hacker <flan_hacker@openbsd.org>
321 date: Wed Aug 14 21:37:07 2038 UTC
323 oops, roll back previous change
325 -----------------------------------------------
326 commit 7ef28ff8dd61cbf38f88784ea8c11e373757985f
327 from: Flan Hacker <flan_hacker@openbsd.org>
328 date: Wed Aug 14 21:10:00 2038 UTC
330 this is surely a great idea!
335 If commit <tt>7ef28ff8dd61cbf38f88784ea8c11e373757985f</tt> has already
336 been copied to another repository, our story ends here because the history
337 must now be considered immutable.
340 Otherwise, the local branch history can be edited to cover up our little
341 mistake. First, find the ID of the parent commit of the bad commit:
344 $ <b>got log -l 4 | grep ^commit| tail -n 1</b>
345 commit e27a7222faaa171dcb086ea0b566dc7bebb74a0b (origin/main)
349 Back-date the work tree to this commit and ask Got to edit the history
350 leading up to the latest commit on the branch:
353 $ <b>got update -c e27a7222fa</b>
354 $ <b>got histedit</b>
358 The <tt>histedit</tt> command will open a histedit script in an editor:
361 # Available histedit commands:
362 # pick (p): use commit
363 # edit (e): use commit but stop for amending
364 # fold (f): combine with commit below
365 # drop (d): remove commit from history
366 # mesg (m): single-line log message for commit above (open editor if empty)
367 # Commits will be processed in order from top to bottom of this file.
368 pick 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
369 pick 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous change
370 pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
374 To make the mistaken commits disappear from history, the corresponding
375 lines can changed to execute <tt>drop</tt> commands, and the log message
376 of the latest commit can be changed to that of the original commit:
379 <b>drop</b> 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
380 <b>drop</b> 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous change
381 pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
382 <b>mesg this is surely a great idea!</b>
386 After saving the file and exiting the editor, Got will create a new
387 version of history which does not contain the mistake:
390 $ <b>got log -l 1</b>
391 -----------------------------------------------
392 commit 60b83404dd25547f19d9b468b931809541a3325c (main)
393 from: Flan Hacker <flan_hacker@openbsd.org>
394 date: Wed Aug 14 22:17:12 2038 UTC
396 this is surely a great idea!
400 <p id="callout">CAVEAT:
401 <p>The <tt>mesg</tt> command of the histedit script only accepts a
402 single-line log message argument. Omit the argument to write a new
403 multi-line log message in an editor:
407 pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
411 <h2 id="ports"><a class="permalink" href="#ports">Using got(1) with the ports tree</a></h2>
413 Clone the ports repository from github. This step currently requires git(1):
416 $ <b>mkdir /var/git</b>
418 $ <b>git clone --bare https://github.com/openbsd/ports.git</b>
420 <p>We jump into ports.git directory and we create our new branch to work with (let's say
424 $ <b>cd ports.git</b>
425 $ <b>got branch mystuff</b>
427 We check that the <tt>master</tt> and the new branch are in sync:
430 $ <b>got branch -l</b>
431 master: 05a7abcec81fc1865d1983314b6783680ab31f689
432 mystuff: 05a7abcec81fc1865d1983314b6783680ab31f689
434 <p>Now we need to checkout the content inside our new branch <tt>mystuff</tt>
438 $ <b>got checkout -b mystuff ports.git</b>
440 A /var/git/ports/x11/yeahconsole/distinfo
441 A /var/git/ports/x11/yeahconsole/patches/patch-Makefile
442 A /var/git/ports/x11/yeahconsole/pkg/DESCR
443 A /var/git/ports/x11/yeahconsole/pkg/PLIST
444 A /var/git/ports/x11/yeahlaunch/Makefile
445 A /var/git/ports/x11/yeahlaunch/distinfo
446 A /var/git/ports/x11/yeahlaunch/patches/patch-yeahlaunch_c
447 A /var/git/ports/x11/yeahlaunch/pkg/DESCR
448 A /var/git/ports/x11/yeahlaunch/pkg/PLIST
451 <p>As <code>got</code> says, now shut up and hack:
454 $ <b>cd /var/git/ports</b>
455 $ <b>cd www/nextcloud</b>
456 $ <b>vim pkg/README</b>
458 <p>So we changed the README file inside the Nextcloud port and we need to cook the diff:
462 diff 05a7abcec81fc1865d1983314b6783680ab31f689 /var/git/ports
463 blob - 47bfbdd7fa7aaf027971ac5c62db25dde75595d7
464 file + www/nextcloud/pkg/README
465 --- www/nextcloud/pkg/README
466 +++ www/nextcloud/pkg/README
467 @@ -96,12 +96,20 @@ server "domain.tld" {
468 block return 301 "$DOCUMENT_URI/index.php"
471 - location "/nextcloud/ocm-provider/" {
472 - block return 301 "$DOCUMENT_URI/index.php"
473 + location "/.well-known/carddav" {
474 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
477 - location "/nextcloud/ocs-provider/" {
478 - block return 301 "$DOCUMENT_URI/index.php"
479 + location "/.well-known/caldav" {
480 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
483 + location "/.well-known/webfinger" {
484 + block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
487 + location match "/nextcloud/oc[ms]%-provider/*" {
488 + directory index index.php
491 ---8<---------------------------------------------------------------------------
493 <p>Time to commit those changes in our branch <tt>mystuff</tt>, so we can keep
497 $ <b>got commit -m "Add new examples for httpd(8) to shut up warnings"</b>
498 M www/nextcloud/pkg/README
499 Created commit 7848652ef6243db09841d449f346f21fc6386633
501 <p>Paranoid? Probably yes, let's check again our diff against <tt>master</tt>:
503 $ <b>got diff master mystuff</b>
504 diff refs/heads/master refs/heads/mystuff
505 blob - 47bfbdd7fa7aaf027971ac5c62db25dde75595d7
506 blob + 71d2df1463ae11c9b66403d401c16fff63382b2c
507 --- www/nextcloud/pkg/README
508 +++ www/nextcloud/pkg/README
509 @@ -96,12 +96,20 @@ server "domain.tld" {
510 block return 301 "$DOCUMENT_URI/index.php"
513 - location "/nextcloud/ocm-provider/" {
514 - block return 301 "$DOCUMENT_URI/index.php"
515 + location "/.well-known/carddav" {
516 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
519 - location "/nextcloud/ocs-provider/" {
520 - block return 301 "$DOCUMENT_URI/index.php"
521 + location "/.well-known/caldav" {
522 + block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
525 + location "/.well-known/webfinger" {
526 + block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
529 + location match "/nextcloud/oc[ms]%-provider/*" {
530 + directory index index.php
533 ---8<---------------------------------------------------------------------------
535 <p>Now, let's send that diff to ports@ for some OKs.
538 <p>Once the diff has been committed to CVS the same change will eventually show
539 up on github as well. Fetch incoming changes to the <tt>master</tt> branch
543 $ <b>cd /var/git/ports.git</b>
544 $ <b>git fetch origin master:master</b>
547 <p>Next, rebase the <tt>mystuff</tt> branch onto the latest <tt>master</tt>:</p>
550 $ <b>cd /var/git/ports</b>
552 (status should be clean; revert or commit local changes if needed)
553 $ <b>got update -b master</b>
554 $ <b>got rebase mystuff</b>
558 Now we can shut up and hack again!