commit - c26475dbc3548ae6d9932d3d6cf5c9fc7e6480ca
commit + 0181e0ca12de0e13856ace068d7ab4f10ad2c4c8
blob - c832387be77dc875bb919aa110ca9dd20c176dcf
blob + 6fbf7a55ac547c18fd703767d90d821e0ba06ad2
--- examples.html
+++ examples.html
<p>
A quick-start guide to <tt>got(1)</tt> can be found in the
<a href="got.1.html#EXAMPLES">EXAMPLES section of the manual page</a>.
-
-<h3>Supplementary Examples:</h3>
-
-<p id="callout">
-<br>
-These examples are supplemental documentation to the manual pages, which are
-available both in the installed system and <a href="manual.html">online</a>.
-
-<table>
- <tr>
- <a href="#selective-commit" >Comitting changes selectively</a><br>
- <a href="#amend" >Amending the latest commit</a><br>
- <a href="#ports" >Using got(1) with the ports tree</a>
- </tr>
-</table>
-
-<p>
-<hr>
-
-<h2 id="selective-commit"><a class="permalink" href="#selective-commit">Committing changes selectively</a></h2>
-
-<p>
-Working on a bug fix will often leave behind unrelated local changes,
-such as temporary debug messages. This section explains how isolated parts
-of local changes in a work tree can be committed in such situations.
-
-<p>
-Consider the following diff, which contains a workaround (disable MIMO)
-for a fictional bug in the <tt>iwm(4)</tt> driver.
-This workaround sits between two temporary debug messages:
-
-<pre class="cmdbox">
-$ <b>got diff</b>
-diff a737ddea9a6b93fdcfad0176dad8d184b2e2138a /usr/src
-blob - 335033d21091a23511403804f09d1548b109b104
-file + sys/dev/pci/if_iwm.c
---- sys/dev/pci/if_iwm.c
-+++ sys/dev/pci/if_iwm.c
-@@ -4620,6 +4620,8 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- uint32_t status;
- struct ieee80211com *ic = &sc->sc_ic;
-
-+ printf("%s: adding node for STA %s\n", __func__, ether_sprintf(in->in_ni.ni_macaddr));
-+
- if (!update && (sc->sc_flags & IWM_FLAG_STA_ACTIVE))
- panic("STA already added");
-
-@@ -4638,7 +4640,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- }
- add_sta_cmd.add_modify = update ? 1 : 0;
- add_sta_cmd.station_flags_msk
-- |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
-+ |= htole32(IWM_STA_FLG_FAT_EN_MSK);
-+#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
-+ add_sta_cmd.station_flags_msk
-+ |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
-+#endif
- add_sta_cmd.tid_disable_tx = htole16(0xffff);
- if (update)
- add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
-@@ -4675,8 +4681,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- status = IWM_ADD_STA_SUCCESS;
- err = iwm_send_cmd_pdu_status(sc, IWM_ADD_STA, sizeof(add_sta_cmd),
- &add_sta_cmd, &status);
-- if (err == 0 && status != IWM_ADD_STA_SUCCESS)
-+ if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
- err = EIO;
-+ printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
-+ add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
-+ }
-
- return err;
- }
-</pre>
-
-<p>
-Got offers several ways of committing this workaround in isolation.
-
-<p>
-One possibility is to stage the desired change with <tt>got stage</tt>:
-
-<pre class="cmdbox">
-$ <b>got stage -p</b>
------------------------------------------------
-@@ -4620,6 +4620,8 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- uint32_t status;
- struct ieee80211com *ic = &sc->sc_ic;
-
-+ printf("%s: adding node for STA %s\n", __func__, ether_sprintf(in->in_ni.ni_macaddr));
-+
- if (!update && (sc->sc_flags & IWM_FLAG_STA_ACTIVE))
- panic("STA already added");
-
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 1 of 4)
-stage this change? [y/n/q] <b>n</b>
------------------------------------------------
-@@ -4638,7 +4640,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- }
- add_sta_cmd.add_modify = update ? 1 : 0;
- add_sta_cmd.station_flags_msk
-- |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
-+ |= htole32(IWM_STA_FLG_FAT_EN_MSK);
-+#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
-+ add_sta_cmd.station_flags_msk
-+ |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
-+#endif
- add_sta_cmd.tid_disable_tx = htole16(0xffff);
- if (update)
- add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 2 of 4)
-stage this change? [y/n/q] <b>y</b>
------------------------------------------------
-@@ -4675,7 +4681,7 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- status = IWM_ADD_STA_SUCCESS;
- err = iwm_send_cmd_pdu_status(sc, IWM_ADD_STA, sizeof(add_sta_cmd),
- &add_sta_cmd, &status);
-- if (err == 0 && status != IWM_ADD_STA_SUCCESS)
-+ if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
- err = EIO;
- printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
- add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 3 of 4)
-stage this change? [y/n/q] <b>q</b>
-$
-</pre>
-
-The staged change can be seen with <tt>got status</tt> and <tt>got diff</tt>:
-
-<pre class="cmdbox">
-$ <b>got status</b>
-MM sys/dev/pci/if_iwm.c
-$ <b>got diff -s</b>
-diff a737ddea9a6b93fdcfad0176dad8d184b2e2138a /usr/src (staged changes)
-blob - 335033d21091a23511403804f09d1548b109b104
-blob + 7ad0ed87af5ef451beba1224ca5186906881aba5
---- sys/dev/pci/if_iwm.c
-+++ sys/dev/pci/if_iwm.c
-@@ -4638,7 +4638,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- }
- add_sta_cmd.add_modify = update ? 1 : 0;
- add_sta_cmd.station_flags_msk
-- |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
-+ |= htole32(IWM_STA_FLG_FAT_EN_MSK);
-+#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
-+ add_sta_cmd.station_flags_msk
-+ |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
-+#endif
- add_sta_cmd.tid_disable_tx = htole16(0xffff);
- if (update)
- add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
-$
-</pre>
-
-
-The debug message changes are no longer necessary and can reverted:
-<pre class="cmdbox">
-$ <b>got revert sys/dev/pci/if_iwm.c</b>
-R sys/dev/pci/if_iwm.c
-$ <b>got status</b>
- M sys/dev/pci/if_iwm.c
-</pre>
-
-To commit the staged change, run <tt>got commit</tt> as usual:
-
-<pre class="cmdbox">
-$ <b>got commit -m "disable MIMO for now to work around a crash reported on bugs@"</b>
-</pre>
-
-<p>
-A second possibility is to revert all debug message changes with
-<tt>got revert</tt>:
-
-<pre class="cmdbox">
-$ <b>got revert -p sys/dev/pci/if_iwm.c</b>
------------------------------------------------
-@@ -4620,6 +4620,8 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- uint32_t status;
- struct ieee80211com *ic = &sc->sc_ic;
-
-+ printf("%s: adding node for STA %s\n", __func__, ether_sprintf(in->in_ni.ni_macaddr));
-+
- if (!update && (sc->sc_flags & IWM_FLAG_STA_ACTIVE))
- panic("STA already added");
-
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 1 of 4)
-revert this change? [y/n/q] <b>y</b>
------------------------------------------------
-@@ -4638,7 +4640,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- }
- add_sta_cmd.add_modify = update ? 1 : 0;
- add_sta_cmd.station_flags_msk
-- |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
-+ |= htole32(IWM_STA_FLG_FAT_EN_MSK);
-+#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
-+ add_sta_cmd.station_flags_msk
-+ |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
-+#endif
- add_sta_cmd.tid_disable_tx = htole16(0xffff);
- if (update)
- add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 2 of 4)
-revert this change? [y/n/q] <b>n</b>
------------------------------------------------
-@@ -4675,7 +4681,7 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- status = IWM_ADD_STA_SUCCESS;
- err = iwm_send_cmd_pdu_status(sc, IWM_ADD_STA, sizeof(add_sta_cmd),
- &add_sta_cmd, &status);
-- if (err == 0 && status != IWM_ADD_STA_SUCCESS)
-+ if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
- err = EIO;
- printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
- add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 3 of 4)
-revert this change? [y/n/q] <b>y</b>
------------------------------------------------
-@@ -4677,6 +4683,9 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- &add_sta_cmd, &status);
- if (err == 0 && status != IWM_ADD_STA_SUCCESS) {
- err = EIO;
-+ printf("ADD_STA_CMD failed: add_modify=%d flags=0x%x\n",
-+ add_sta_cmd.add_modify, add_sta_cmd.station_flags_msk);
-+ }
-
- return err;
- }
------------------------------------------------
-M sys/dev/pci/if_iwm.c (change 4 of 4)
-revert this change? [y/n/q] <b>y</b>
-$
-</pre>
-
-This leaves us with the workaround as our only local change we can commit:
-
-<pre class="cmdbox">
-$ <b>got diff</b>
-diff a737ddea9a6b93fdcfad0176dad8d184b2e2138a /usr/src
-blob - 335033d21091a23511403804f09d1548b109b104
-file + sys/dev/pci/if_iwm.c
---- sys/dev/pci/if_iwm.c
-+++ sys/dev/pci/if_iwm.c
-@@ -4638,7 +4638,11 @@ iwm_add_sta_cmd(struct iwm_softc *sc, struct iwm_node
- }
- add_sta_cmd.add_modify = update ? 1 : 0;
- add_sta_cmd.station_flags_msk
-- |= htole32(IWM_STA_FLG_FAT_EN_MSK | IWM_STA_FLG_MIMO_EN_MSK);
-+ |= htole32(IWM_STA_FLG_FAT_EN_MSK);
-+#ifdef notyet /* FIXME: we are not yet ready for MIMO! */
-+ add_sta_cmd.station_flags_msk
-+ |= htole32(IWM_STA_FLG_MIMO_EN_MSK);
-+#endif
- add_sta_cmd.tid_disable_tx = htole16(0xffff);
- if (update)
- add_sta_cmd.modify_mask |= (IWM_STA_MODIFY_TID_DISABLE_TX);
-$
-</pre>
-<h2 id="amend"><a class="permalink" href="#rollback">Amending the latest commit</a></h2>
-
-<p>
-Sometimes a mistake is found in the latest commit on a branch.
-This section explains how such a mistake can be corrected with Got.
-
-<p>
-As a first step, Got can create another commit which undoes the changes
-made by the latest commit. Assuming a branch called <tt>main</tt>,
-the latest commit on this branch can be identified by the same
-name (<tt>main</tt>).
-In a clean work tree according to <tt>got status</tt>, run:
-<pre class="cmdbox">
-$ <b>got backout main</b>
-$ <b>got commit -m 'oops, roll back previous change'</b>
-</pre>
-Using <tt>got backout</tt> a second time will now fetch the rolled-back
-change into the work tree as a local change which can be amended:</p>
-
-<pre class="cmdbox">
-$ <b>got backout main</b>
-(edit files)
-$ <b>got commit -m 'fixed version of previous change'</b>
-</pre>
-
-The history of the three latest commits on the branch would
-now look something like this:
-
-<pre class="cmdbox">
-$ <b>got log -l 3</b>
------------------------------------------------
-commit bcb49d15e041ddffb59397d2fe851fdb1729b005 (main)
-from: Flan Hacker <flan_hacker@openbsd.org>
-date: Wed Aug 14 22:07:22 2038 UTC
-
- fixed version of previous change
-
------------------------------------------------
-commit 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda
-from: Flan Hacker <flan_hacker@openbsd.org>
-date: Wed Aug 14 21:37:07 2038 UTC
-
- oops, roll back previous change
-
------------------------------------------------
-commit 7ef28ff8dd61cbf38f88784ea8c11e373757985f
-from: Flan Hacker <flan_hacker@openbsd.org>
-date: Wed Aug 14 21:10:00 2038 UTC
-
- this is surely a great idea!
-
-</pre>
-
-<p>
-If commit <tt>7ef28ff8dd61cbf38f88784ea8c11e373757985f</tt> has already
-been copied to another repository, our story ends here because the history
-must now be considered immutable.
-
-<p>
-Otherwise, the local branch history can be edited to cover up our little
-mistake. First, find the ID of the parent commit of the bad commit:
-
-<pre class="cmdbox">
-$ <b>got log -l 4 | grep ^commit| tail -n 1</b>
-commit e27a7222faaa171dcb086ea0b566dc7bebb74a0b (origin/main)
-</pre>
-
-<p>
-Back-date the work tree to this commit and ask Got to edit the history
-leading up to the latest commit on the branch:
-
-<pre class="cmdbox">
-$ <b>got update -c origin/main</b>
-$ <b>got histedit</b>
-</pre>
-
-<p>
-The <tt>histedit</tt> command will open a histedit script in an editor:
-
-<pre class="cmdbox">
-# Available histedit commands:
-# pick (p): use commit
-# edit (e): use commit but stop for amending
-# fold (f): combine with commit below
-# drop (d): remove commit from history
-# mesg (m): single-line log message for commit above (open editor if empty)
-# Commits will be processed in order from top to bottom of this file.
-pick 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
-pick 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous change
-pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
-</pre>
-
-<p>
-To make the mistaken commits disappear from history, the corresponding
-lines can changed to execute <tt>drop</tt> commands, and the log message
-of the latest commit can be changed to that of the original commit:
-
-<pre class="cmdbox">
-<b>drop</b> 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
-<b>drop</b> 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous change
-pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
-<b>mesg this is surely a great idea!</b>
-</pre>
-
-<p>
-After saving the file and exiting the editor, Got will create a new
-version of history which does not contain the mistake:
-
-<pre class="cmdbox">
-$ <b>got log -l 1</b>
------------------------------------------------
-commit 60b83404dd25547f19d9b468b931809541a3325c (main)
-from: Flan Hacker <flan_hacker@openbsd.org>
-date: Wed Aug 14 22:17:12 2038 UTC
-
- this is surely a great idea!
-
-</pre>
-
-<p id="callout">CAVEAT:
-<p>The <tt>mesg</tt> command of the histedit script only accepts a
-single-line log message argument. Omit the argument to write a new
-multi-line log message in an editor:
-
-<pre class="cmdbox">
-[...]
-pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
-<b>mesg</b>
-</pre>
-
-<h2 id="ports"><a class="permalink" href="#ports">Using got(1) with the ports tree</a></h2>
-
-Clone the ports repository from github. This step currently requires git(1):
-<p></p>
-<pre class="cmdbox">
-$ <b>mkdir /var/git</b>
-$ <b>cd /var/git</b>
-$ <b>git clone --bare https://github.com/openbsd/ports.git</b>
-</pre>
-<p>We jump into ports.git directory and we create our new branch to work with (let's say
-<tt>mystuff</tt>):
-<p></p>
-<pre class="cmdbox">
-$ <b>cd ports.git</b>
-$ <b>got branch mystuff</b>
-</pre>
-We check that the <tt>master</tt> and the new branch are in sync:
-<p></p>
-<pre class="cmdbox">
-$ <b>got branch -l</b>
-master: 05a7abcec81fc1865d1983314b6783680ab31f689
-mystuff: 05a7abcec81fc1865d1983314b6783680ab31f689
-</pre>
-<p>Now we need to checkout the content inside our new branch <tt>mystuff</tt>
-<p></p>
-<pre class="cmdbox">
-$ <b>cd /var/git</b>
-$ <b>got checkout -b mystuff ports.git</b>
-...
-A /var/git/ports/x11/yeahconsole/distinfo
-A /var/git/ports/x11/yeahconsole/patches/patch-Makefile
-A /var/git/ports/x11/yeahconsole/pkg/DESCR
-A /var/git/ports/x11/yeahconsole/pkg/PLIST
-A /var/git/ports/x11/yeahlaunch/Makefile
-A /var/git/ports/x11/yeahlaunch/distinfo
-A /var/git/ports/x11/yeahlaunch/patches/patch-yeahlaunch_c
-A /var/git/ports/x11/yeahlaunch/pkg/DESCR
-A /var/git/ports/x11/yeahlaunch/pkg/PLIST
-Now shut up and hack
-</pre>
-<p>As <code>got</code> says, now shut up and hack:
-<p></p>
-<pre class="cmdbox">
-$ <b>cd /var/git/ports</b>
-$ <b>cd www/nextcloud</b>
-$ <b>vim pkg/README</b>
-</pre>
-<p>So we changed the README file inside the Nextcloud port and we need to cook the diff:
-<p></p>
-<pre class="cmdbox">
-$ <b>got diff</b>
-diff 05a7abcec81fc1865d1983314b6783680ab31f689 /var/git/ports
-blob - 47bfbdd7fa7aaf027971ac5c62db25dde75595d7
-file + www/nextcloud/pkg/README
---- www/nextcloud/pkg/README
-+++ www/nextcloud/pkg/README
-@@ -96,12 +96,20 @@ server "domain.tld" {
- block return 301 "$DOCUMENT_URI/index.php"
- }
-
-- location "/nextcloud/ocm-provider/" {
-- block return 301 "$DOCUMENT_URI/index.php"
-+ location "/.well-known/carddav" {
-+ block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
- }
-
-- location "/nextcloud/ocs-provider/" {
-- block return 301 "$DOCUMENT_URI/index.php"
-+ location "/.well-known/caldav" {
-+ block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
-+ }
-+
-+ location "/.well-known/webfinger" {
-+ block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
-+ }
-+
-+ location match "/nextcloud/oc[ms]%-provider/*" {
-+ directory index index.php
- }
- }
- ---8<---------------------------------------------------------------------------
-</pre>
-<p>Time to commit those changes in our branch <tt>mystuff</tt>, so we can keep
-track of our work:
-<p></p>
-<pre class="cmdbox">
-$ <b>got commit -m "Add new examples for httpd(8) to shut up warnings"</b>
-M www/nextcloud/pkg/README
-Created commit 7848652ef6243db09841d449f346f21fc6386633
-</pre>
-<p>Paranoid? Probably yes, let's check again our diff against <tt>master</tt>:
-<pre class="cmdbox">
-$ <b>got diff master mystuff</b>
-diff refs/heads/master refs/heads/mystuff
-blob - 47bfbdd7fa7aaf027971ac5c62db25dde75595d7
-blob + 71d2df1463ae11c9b66403d401c16fff63382b2c
---- www/nextcloud/pkg/README
-+++ www/nextcloud/pkg/README
-@@ -96,12 +96,20 @@ server "domain.tld" {
- block return 301 "$DOCUMENT_URI/index.php"
- }
-
-- location "/nextcloud/ocm-provider/" {
-- block return 301 "$DOCUMENT_URI/index.php"
-+ location "/.well-known/carddav" {
-+ block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
- }
-
-- location "/nextcloud/ocs-provider/" {
-- block return 301 "$DOCUMENT_URI/index.php"
-+ location "/.well-known/caldav" {
-+ block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
-+ }
-+
-+ location "/.well-known/webfinger" {
-+ block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
-+ }
-+
-+ location match "/nextcloud/oc[ms]%-provider/*" {
-+ directory index index.php
- }
- }
- ---8<---------------------------------------------------------------------------
-</pre>
-<p>Now, let's send that diff to ports@ for some OKs.
-</p>
-
-<p>Once the diff has been committed to CVS the same change will eventually show
-up on github as well. Fetch incoming changes to the <tt>master</tt> branch
-with:</p>
-
-<pre class="cmdbox">
-$ <b>cd /var/git/ports.git</b>
-$ <b>git fetch origin master:master</b>
-</pre>
-
-<p>Next, rebase the <tt>mystuff</tt> branch onto the latest <tt>master</tt>:</p>
-
-<pre class="cmdbox">
-$ <b>cd /var/git/ports</b>
-$ <b>got status</b>
-(status should be clean; revert or commit local changes if needed)
-$ <b>got update -b master</b>
-$ <b>got rebase mystuff</b>
-</pre>
-
-<p>
-Now we can shut up and hack again!
-
</body>
</html>
